Obsidian Semantic MCP

🚀 Obsidian語義MCP服務器

Obsidian語義MCP服務器是一個專為Obsidian設計的語義化、AI優化的MCP服務器，它將20種工具整合為5種智能操作，並提供上下文工作流提示。

---

🚀 快速開始

試用我們的新原生插件！

這個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設置 → 社區插件
   • 瀏覽並搜索“Local REST API”
   • 安裝Adam Coddington開發的本地REST API插件
   • 啟用該插件
   • 在插件設置中，複製您的API密鑰（配置時需要用到）
2. 配置Claude桌面： npx命令會自動用於Claude桌面配置。將以下內容添加到您的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": "- [ ] 新任務"
  }
}

大文檔片段檢索

系統在讀取文件時會自動使用智能片段檢索，在保持相關性的同時顯著減少令牌消耗：

{
  "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
    }
  }
}

片段搜索策略：

• adaptive - TF-IDF關鍵字匹配（短查詢的默認策略）
• proximity - 查找查詢詞相鄰出現的片段
• semantic - 將文檔分割成有意義的部分

您可以明確在保險庫中搜索片段：

{
  "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參數可獲取完整內容
• 策略選擇：系統會根據查詢長度自動選擇，您也可以手動指定：
  • adaptive用於關鍵字匹配（1 - 2個單詞的查詢）
  • proximity用於查找相關術語相鄰出現的情況（3 - 5個單詞的查詢）
  • semantic用於概念性分塊（較長的查詢）

錯誤恢復

操作失敗時，語義界面會提供智能恢復提示：

{
  "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')"
      }
    ]
  }
}

---

📦 安裝指南

npm install -g obsidian-semantic-mcp

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

npx obsidian-semantic-mcp

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

---

💻 使用示例

基礎用法

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

高級用法

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

---

📚 詳細文檔

環境變量

服務器會自動從.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": "每日筆記::今日",
  "content": "- 新增任務"
}

---

🔧 技術細節

架構

語義系統由以下部分組成：

• 語義路由器 (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插件集成