Local Docs MCP

🚀 Local Docs MCP Server

Local Docs MCP Server是一個實現了模型上下文協議（MCP）的服務器，用於本地文檔訪問。它能讓Claude無縫訪問來自多個來源的Markdown文檔，為用戶提供便捷的文檔查詢體驗。

✨ 主要特性

• 多源文檔支持：可從命令、項目文檔和項目根目錄訪問文檔。
• 智能搜索：採用模糊匹配，優先精確匹配和子串匹配。
• YAML前置元數據支持：可添加可選元數據（描述、標籤），增強搜索效果。
• 持續緩存：對文件列表進行緩存，文件更改時自動失效，速度提升約3000倍。
• 文件監控：文檔文件更改時自動使緩存失效。
• 安全路徑處理：防止目錄遍歷，驗證路徑有效性。
• 源前綴：可明確指定文檔來源（例如 commands:file.md）。
• 大小限制：避免讀取超過5MB的文件。

📚 詳細文檔

文檔來源

1. 共享文檔 (~/.claude/commands/**/*.md)：用戶命令和知識庫（可配置）。
2. 項目文檔 ($CWD/docs/**/*.md)：特定項目的文檔，可配置排除項。
3. 項目根目錄 ($CWD/*.md)：根級文檔，如README.md（可選啟用）。

YAML前置元數據支持

文檔文件可選擇包含YAML前置元數據，以提高搜索性能：

---
description: Enforce Test-Driven Development approach for Go code with test-first workflow
tags: [testing, development, go]
---

# Your Documentation Content

支持的字段：

• description：用於提高搜索相關性的文本描述。
• tags：用於分類的標籤數組或逗號分隔列表。

搜索行為：

• 描述匹配使搜索得分增加0.5。
• 精確標籤匹配使搜索得分增加0.3。
• 部分標籤匹配使搜索得分增加0.15。
• read_doc 輸出會自動去除前置元數據。
• list_all_docs 在文件元數據中包含描述和標籤。

注意：前置元數據是可選的，純Markdown文件無需它也能正常工作。

📦 安裝指南

下載二進制文件

從發佈頁面下載最新版本。

使用Go安裝

go install github.com/umputun/local-docs-mcp/app@latest

使用Homebrew（macOS）

brew tap umputun/apps
brew install umputun/apps/local-docs-mcp

從源代碼構建

git clone https://github.com/umputun/local-docs-mcp.git
cd local-docs-mcp
make build
make install

配置Claude

添加到 ~/.claude.json：

{
  "mcpServers": {
    "local-docs": {
      "command": "local-docs-mcp"
    }
  }
}

或者使用絕對路徑：

{
  "mcpServers": {
    "local-docs": {
      "command": "/path/to/local-docs-mcp"
    }
  }
}

重啟Claude Code以加載服務器。

🔧 技術細節

命令行選項

# 自定義文檔目錄
local-docs-mcp --shared-docs-dir=~/.my-docs --docs-dir=documentation

# 啟用根級Markdown掃描
local-docs-mcp --enable-root-docs

# 從項目文檔掃描中排除目錄
local-docs-mcp --exclude-dir=plans --exclude-dir=drafts

# 通過環境變量進行多個排除
EXCLUDE_DIRS=plans,drafts,archive local-docs-mcp

可用選項：

• --shared-docs-dir - 共享文檔目錄（默認：~/.claude/commands）
• --docs-dir - 項目文檔目錄（默認：docs）
• --enable-root-docs - 掃描根級 *.md 文件（默認：禁用）
• --exclude-dir - 從項目文檔掃描中排除的目錄（默認：plans）
• --cache-ttl - 緩存生存時間（默認：1h）
• --max-file-size - 要索引的最大文件大小（默認：5242880 - 5MB）
• --dbg - 啟用調試日誌

緩存

文件列表緩存始終啟用，以顯著加快重複查詢速度。緩存的生存時間（TTL）可以配置：

# 使用默認的1小時TTL
local-docs-mcp

# 自定義TTL
local-docs-mcp --cache-ttl=30m

# 通過環境變量設置
CACHE_TTL=2h local-docs-mcp

性能：緩存命中比文件系統掃描快約3000倍（66納秒 vs 201微秒）。當文檔文件更改時，緩存會自動失效，確保數據新鮮。

工作原理：

• 首次查詢掃描文件系統並填充緩存。
• 後續查詢直接從內存返回。
• 文件監控器檢測到更改後，會在500毫秒內使緩存失效。
• TTL提供安全回退機制（默認：1小時）。

💻 使用示例

配置完成後，Claude可以自然地查詢文檔：

• "Show me docs for routegroup"
• "Find documentation about testing"
• "List all available commands"
• "What's in the go-architect command?"

可用工具

search_docs

通過模糊匹配按名稱搜索文檔文件。 輸入：{"query": "search-term"} 輸出：前10個匹配文件及其得分

read_doc

讀取特定的文檔文件。 輸入：{"path": "file.md"} 或 {"path": "commands:action/commit.md"} 輸出：包含元數據的文件內容

list_all_docs

列出所有來源的可用文檔文件。 輸出：包含文件大小和來源信息的完整文件列表

🔒 安全保障

• 防止目錄遍歷
• 文件大小限制（5MB）
• UTF-8驗證
• 不跟隨基礎目錄外的符號鏈接
• 拒絕絕對路徑

📄 許可證

本項目採用MIT許可證 - 詳情請參閱 LICENSE 文件。