Obsidian Semantic MCP

🚀 Obsidian语义MCP服务器

Obsidian语义MCP服务器是一个针对Obsidian进行语义优化和AI优化的MCP服务器，它将20种工具整合为5种智能操作，并提供上下文工作流提示，能有效提升AI代理对Obsidian操作的理解和使用效率。

🚀 快速开始

尝试我们的新原生插件！

这个MCP服务器让我们在将AI与Obsidian集成方面积累了宝贵经验。我们运用这些见解创建了 Obsidian MCP插件，它具有以下优势：

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

👉 获取Obsidian MCP插件

前提条件

• 计算机上已安装 Obsidian
• Obsidian保险库中已安装 本地REST API 插件
• 已安装 Claude桌面版 应用程序

安装

npm install -g obsidian-semantic-mcp

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

npx obsidian-semantic-mcp

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

快速上手

1. 安装Obsidian插件：

   • 打开Obsidian设置 → 社区插件
   • 浏览并搜索 "本地REST API"
   • 安装Adam Coddington开发的 本地REST API 插件
   • 启用该插件
   • 在插件设置中，复制你的API密钥（配置时需要用到）

2. 配置Claude桌面版： 在Claude桌面版配置中会自动使用npx命令。将以下内容添加到Claude桌面版配置中（在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"
         }
       }
     }
   }
   

✨ 主要特性

关键优势

• 简化界面：用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": "- [ ] New task"
  }
}

大文档的片段检索

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

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

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

{
  "result": {
    "content": [
      {
        "id": "file:large-document.md:frag0",
        "content": "Most relevant section...",
        "score": 0.95,
        "lineStart": 145,
        "lineEnd": 167
      }
    ],
    "fragmentMetadata": {
      "totalFragments": 5,
      "strategy": "adaptive",
      "originalContentLength": 135662
    }
  }
}

片段搜索策略：

• adaptive - TF-IDF关键字匹配（短查询的默认策略）
• proximity - 查找查询词相邻出现的片段
• semantic - 将文档分割成有意义的部分

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

{
  "operation": "vault",
  "action": "fragments",
  "params": {
    "query": "project roadmap timeline",
    "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 参数获取完整内容
• 策略选择：系统会根据查询长度自动选择，也可以手动指定：
  • adaptive 用于关键字匹配（1 - 2个单词的查询）
  • proximity 用于查找相关术语相邻出现的情况（3 - 5个单词的查询）
  • semantic 用于概念性分块（较长的查询）

错误恢复

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

{
  "error": {
    "code": "FILE_NOT_FOUND",
    "message": "File not found: 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 - 来自本地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 - 针对前置元数据字段

• 操作：

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

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

{
  "operation": "append",
  "targetType": "heading",
  "target": "Daily Notes::Today",
  "content": "- New task added"
}

架构

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

• 语义路由器 (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     # 测试集成

📄 许可证

本项目采用MIT许可证。

已知问题

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

贡献

欢迎贡献代码！感兴趣的领域包括：

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