STARWARCLOUD STARWAR.AI
返回市场
黑曜石语义MCP服务器

黑曜石语义MCP服务器

作者：aaronsb26 星标更新：2025-07-12
安装使用来源：spider==github.com

项目介绍

Obsidian 语义化 MCP 服务器

🎉 激动人心的消息！ 我们从这个项目中学到了很多，并创造了一个更好的东西！请查看新的 Obsidian MCP 插件 — 这是一个原生的 Obsidian 插件，它直接在你的保险库中运行，具有改进的性能、简化的设置和增强的功能。我们鼓励您试用！

npm 版本

一个语义化的、AI优化的 MCP 服务器，用于 Obsidian，将 20 个工具整合成 5 个智能操作，并提供上下文工作流提示。

🚀 尝试我们的新原生插件！

这个 MCP 服务器教会了我们关于 AI 与 Obsidian 集成的重要课程。我们应用这些见解创建了 Obsidian MCP 插件，它提供了：

  • 原生集成：直接在 Obsidian 内部运行（无需外部依赖项！）
  • 更好的性能：直接访问保险库，没有 REST API 的开销
  • 更简单的设置：像安装任何 Obsidian 插件一样安装——无需 API 密钥或外部服务器
  • 增强的功能：完全访问 Obsidian 的内部 API 和搜索能力
  • 更高的可靠性：不再有连接问题或超时

👉 获取 Obsidian MCP 插件

<a href="https://glama.ai/mcp/servers/@aaronsb/obsidian-semantic-mcp"> <img width="380" height="200" src="https://gips0.baidu.com/it/u=813769049,1331248914&fm=3081&app=3081&f=PNG?w=760&h=400" alt="Obsidian 语义化服务器 MCP 服务器" /> </a>

先决条件

安装

npm install -g obsidian-semantic-mcp

或者直接使用 npx（推荐）：

npx obsidian-semantic-mcp

在 npm 上查看：https://www.npmjs.com/package/obsidian-semantic-mcp

快速开始

  1. 安装 Obsidian 插件：

    • 打开 Obsidian 设置 → 社区插件
    • 浏览并搜索“Local REST API”
    • 安装 Adam Coddington 的 Local REST API 插件
    • 启用插件
    • 在插件设置中复制您的 API 密钥（配置时需要此密钥）

  2. 配置 Claude Desktop：

    npx 命令会自动用于 Claude Desktop 配置。将以下内容添加到您的 Claude Desktop 配置文件中（通常位于 macOS 的 ~/Library/Application Support/Claude/claude_desktop_config.json）：

    {
  "mcpServers": {
    "obsidian": {
      "command": "npx",
      "args": ["-y", "obsidian-semantic-mcp"],
      "env": {
        "OBSIDIAN_API_KEY": "your-api-key-here",
        "OBSIDIAN_API_URL": "https://127.0.0.1:27124",
        "OBSIDIAN_VAULT_NAME": "your-vault-name"
      }
    }
  }
}

功能

该服务器将传统的 MCP 工具整合到一个 AI 优化的语义界面中，使 AI 代理更容易理解和使用 Obsidian 操作。

主要优势

  • 简化接口：5 个语义操作代替 21+ 个单独工具
  • 上下文工作流：智能提示引导 AI 代理进行下一步逻辑操作
  • 状态跟踪：基于令牌的系统防止无效操作
  • 错误恢复：操作失败时提供智能恢复提示
  • 模糊匹配：对文本编辑具有弹性，处理小的变化
  • 片段检索：自动返回大文件的相关部分以节省令牌

为什么采用语义操作？

传统的 MCP 服务器暴露了许多细粒度的工具（20+），这可能会让 AI 代理感到不知所措，并导致低效的工具选择。我们的语义方法：

  • 根据意图将 20 个工具整合成 5 个语义操作
  • 提供上下文工作流提示以指导下一步操作
  • 通过令牌跟踪状态（灵感来自 Petri 网络）以防止不合逻辑的建议
  • 当操作失败时提供恢复提示

5 个语义操作

  1. vault - 文件和文件夹操作

    • 动作：list，read，create，update，delete，search，fragments

  2. edit - 智能内容编辑

    • 动作：window（模糊匹配），append，patch，at_line，from_buffer

  3. view - 内容查看和导航

    • 动作：window（带上下文），open_in_obsidian

  4. workflow - 获取引导建议

    • 动作：suggest

  5. system - 系统操作

    • 动作：info，commands，fetch_web
    • 注意：fetch_web 获取并转换网页内容为 Markdown（仅使用 url 参数）

示例用法

不再需要在 get_vault_file，get_active_file，read_file_content 等之间选择，只需使用：

{
  "operation": "vault",
  "action": "read",
  "params": {
    "path": "daily-notes/2024-01-15.md"
  }
}

响应包括智能工作流提示：

{
  "result": { /* 文件内容 */ },
  "workflow": {
    "message": "读取文件：daily-notes/2024-01-15.md",
    "suggested_next": [
      {
        "description": "编辑此文件",
        "command": "edit(action='window', path='daily-notes/2024-01-15.md', ...)",
        "reason": "修改内容"
      },
      {
        "description": "跟随链接笔记",
        "command": "vault(action='read', path='{linked_file}')",
        "reason": "探索相关知识"
      }
    ]
  }
}

状态感知建议

系统跟踪上下文令牌以提供相关建议：

  • 读取带有 [[链接]] 的文件后，它会建议跟随它们
  • 编辑失败后，它会提供缓冲区恢复选项
  • 搜索后，它会建议细化或阅读结果

高级功能

内容缓冲

window 编辑动作会自动缓冲您的新内容，然后再尝试编辑。如果编辑失败或您想要细化它，可以从缓冲区检索：

{
  "operation": "edit",
  "action": "from_buffer",
  "params": {
    "path": "notes/meeting.md"
  }
}

模糊窗口编辑

语义编辑器使用模糊匹配来查找和替换内容：

{
  "operation": "edit",
  "action": "window",
  "params": {
    "path": "daily/2024-01-15.md",
    "oldText": "meting notes",  // 拼写错误会被模糊匹配
    "newText": "meeting notes",
    "fuzzyThreshold": 0.8
  }
}

智能 PATCH 操作

针对特定文档结构：

{
  "operation": "edit",
  "action": "patch",
  "params": {
    "path": "projects/todo.md",
    "operation": "append",
    "targetType": "heading",
    "target": "## In Progress",
    "content": "- [ ] 新任务"
  }
}

大文档片段检索

系统在读取文件时自动使用智能片段检索，显著减少令牌消耗同时保持相关性：

{
  "operation": "vault",
  "action": "read",
  "params": {
    "path": "large-document.md"
  }
}

返回相关片段而不是整个文件：

{
  "result": {
    "content": [
      {
        "id": "file:large-document.md:frag0",
        "content": "最相关的部分...",
        "score": 0.95,
        "lineStart": 145,
        "lineEnd": 167
      }
    ],
    "fragmentMetadata": {
      "totalFragments": 5,
      "strategy": "adaptive",
      "originalContentLength": 135662
    }
  }
}

片段搜索策略：

  • 自适应 - TF-IDF 关键词匹配（默认用于短查询）
  • 接近度 - 查找查询词出现在一起的片段
  • 语义 - 将文档切分为有意义的部分

您可以显式地在整个保险库中搜索片段：

{
  "operation": "vault",
  "action": "fragments",
  "params": {
    "query": "项目路线图时间线",
    "maxFragments": 10,
    "strategy": "proximity"
  }
}

要检索完整文件（当需要时），使用：

{
  "operation": "vault",
  "action": "read",
  "params": {
    "path": "document.md",
    "returnFullFile": true
  }
}

工作流示例

日常笔记工作流

  1. 创建今天的笔记 → 2. 添加模板 → 3. 链接昨天的笔记

研究工作流

  1. 搜索主题 → 2. 阅读结果 → 3. 创建综合笔记 → 4. 链接来源

重构工作流

  1. 查找所有提及 → 2. 更新链接 → 3. 重命名/合并笔记

配置

语义工作流提示定义在 src/config/workflows.json 中，并可根据您的工作流偏好进行定制。

片段检索配置

片段检索系统在读取文件时自动激活以节省令牌。您可以控制这种行为：

  • 默认行为：读取文件时返回最多 5 个相关片段
  • 完整文件访问：使用 returnFullFile: true 参数获取完整内容
  • 策略选择：系统根据查询长度自动选择，或者您可以指定：
    • 自适应 用于关键词匹配（1-2 词查询）
    • 接近度 用于查找相关词在一起出现（3-5 词查询）
    • 语义 用于概念分块（较长查询）

错误恢复

当操作失败时，语义界面提供智能恢复提示：

{
  "error": {
    "code": "FILE_NOT_FOUND",
    "message": "未找到文件：daily/2024-01-15.md",
    "recovery_hints": [
      {
        "description": "创建此文件",
        "command": "vault(action='create', path='daily/2024-01-15.md')"
      },
      {
        "description": "搜索类似文件",
        "command": "vault(action='search', query='2024-01-15')"
      }
    ]
  }
}

环境变量

服务器会自动从 .env 文件加载环境变量（如果存在）。变量可以按优先级顺序设置：

  1. 现有的环境变量（最高优先级）
  2. 当前工作目录中的 .env 文件
  3. 服务器目录中的 .env 文件

必需变量：

  • OBSIDIAN_API_KEY - 来自 Local REST API 插件的 API 密钥

可选变量：

  • OBSIDIAN_API_URL - API URL（默认：https://localhost:27124）
    • 支持 HTTP（端口 27123）和 HTTPS（端口 27124）
    • HTTPS 使用自签名证书，自动接受
  • OBSIDIAN_VAULT_NAME - 上下文中的保险库名称

示例 .env 文件：

OBSIDIAN_API_KEY=your-api-key-here
OBSIDIAN_API_URL=http://127.0.0.1:27123
OBSIDIAN_VAULT_NAME=MyVault

PATCH 操作

PATCH 操作（patch_active_file 和 patch_vault_file）允许复杂的文本操作：

  • 目标类型：

    • heading：使用路径如 "Heading 1::Subheading" 目标特定标题下的内容
    • block：目标特定块引用
    • frontmatter：目标 frontmatter 字段

  • 操作：

    • append：在目标之后添加内容
    • prepend：在目标之前添加内容
    • replace：替换目标内容

示例：在特定标题下追加内容：

{
  "operation": "append",
  "targetType": "heading",
  "target": "日常笔记::今天",
  "content": "- 新任务已添加"
}

开发

# 克隆并安装
git clone https://github.com/aaronsb/obsidian-semantic-mcp.git
cd obsidian-semantic-mcp
npm install

# 开发模式
npm run dev

# 测试
npm test              # 运行所有测试
npm run test:coverage # 带覆盖率报告

# 构建
npm run build         # 构建服务器
npm run build:full    # 测试 + 构建

# 启动
npm start             # 启动服务器

架构

语义系统由以下部分组成：

  • 语义路由器 (src/semantic/router.ts) - 路由操作到处理器
  • 状态令牌 (src/semantic/state-tokens.ts) - 跟踪上下文状态
  • 工作流配置 (src/config/workflows.json) - 定义提示和建议
  • 核心实用工具 (src/utils/) - 共享功能如文件读取和模糊匹配

测试

该项目包括全面的 Jest 测试以测试语义系统：

npm test                    # 运行所有测试
npm test semantic-router    # 测试路由逻辑
npm test semantic-tools     # 测试集成

已知问题

  • 搜索功能：由于 Obsidian Local REST API 插件中的 API 限制，搜索操作可能偶尔会在大型保险库上超时。

贡献

欢迎贡献！感兴趣的领域：

  • 在 workflows.json 中添加更多工作流模式
  • 新的语义操作
  • 增强的状态跟踪
  • 与 Obsidian 插件的集成

许可证

MIT