Docs MCP

🚀 docs-mcp

這是一個MCP服務器，可讓用戶高效地搜索和參考自定義文檔。它能幫助用戶快速定位所需信息，提升文檔使用效率。

🚀 快速開始

最基礎的使用方法

如果你已有現成的文檔項目，可按以下步驟操作：

# 創建文檔管理文件夾
mkdir -p my-docs/docs
# 將文檔文件放置在docs/目錄下

在Claude Desktop的配置文件（claude_desktop_config.json）中添加如下內容：

{
  "mcpServers": {
    "docs": {
      "command": "uvx",
      "args": ["docs-mcp"],
      "env": {
        "DOCS_BASE_DIR": "/path/to/my-docs"
      }
    }
  }
}

重要提示：docs-mcp始終會引用項目文件夾內的docs/目錄。

✨ 主要特性

• 📄 文檔列表展示 - 展示所有文檔及其說明。
• 🔍 grep搜索 - 利用正則表達式進行快速全文搜索。
• 🧠 語義搜索 - 使用OpenAI Embeddings進行語義相似搜索（需配置）。
• 📝 文檔獲取 - 獲取指定文檔的全部內容。
• 📖 分頁支持 - 可高效分頁瀏覽大型文檔。

📦 安裝指南

前提條件

使用docs-mcp需要安裝uv，它是一個用於Python包和項目管理的快速工具。

uv的安裝

curl -LsSf https://astral.sh/uv/install.sh | sh

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

brew install uv

pip install uv

配置方法

方法1：使用現有文檔

如果你手頭有Markdown或文本文件，可按以下步驟讓其可被搜索：

1. 創建項目文件夾。
2. 將文檔放置在docs/目錄下。
3. 更新Claude Desktop的配置。

✅ 優點：無需命令行操作，可立即使用。
❌ 缺點：無法使用導入工具。

方法2：使用導入工具

如果你想從GitHub或網站導入文檔，可按以下步驟操作：

# 初始化文檔管理項目
uv init my-docs
cd my-docs
uv add docs-mcp

# 從GitHub導入文檔
uv run docs-mcp-import-github https://github.com/owner/repo

# 僅導入特定目錄
uv run docs-mcp-import-github https://github.com/owner/repo/tree/main/docs -o project-docs

✅ 優點：可輕鬆導入外部文檔。
❌ 缺點：需要進行uv的設置。

💻 使用示例

基礎用法

以下是在Claude內使用MCP工具的示例：

# 顯示文檔列表
list_docs

# 獲取文檔內容（支持分頁）
get_doc("path/to/document.md")

# 正則表達式搜索
grep_docs

# 語義相似搜索（需要OpenAI API密鑰）
semantic_search

高級用法

開啟語義搜索

你可以使用OpenAI Embeddings添加語義搜索功能：

# 1. 設置OpenAI API密鑰
export OPENAI_API_KEY="sk-..."

# 2. 生成元數據（在項目目錄中執行）
uv run docs-mcp-generate-metadata

在Claude Desktop的配置中添加API密鑰：

{
  "mcpServers": {
    "docs": {
      "command": "uvx",
      "args": ["docs-mcp"],
      "env": {
        "DOCS_BASE_DIR": "/path/to/my-docs",
        "OPENAI_API_KEY": "sk-..."  // 開啟語義搜索
      }
    }
  }
}

分頁功能的使用

對於大型文檔（超過15,000個字符），系統會自動顯示第一頁，建議使用分頁功能：

# 基本用法（與以往相同）
get_doc("path/to/document.md")  # 小文件會顯示全文，大文件會自動顯示第一頁

# 使用分頁
get_doc("path/to/document.md", page=1)  # 第一頁（默認最多10,000個字符）
get_doc("path/to/document.md", page=2)  # 第二頁
get_doc("path/to/document.md", page=3)  # 第三頁

分頁輸出示例：

📄 文檔: pytest/reference/plugin_list.rst
📖 第2頁/共5頁 (字符10,001 - 20,000/共45,123個字符)
📏 行數285 - 570/共1,324行 | 每頁最大字符數: 10,000
⚠️  大型文檔已自動分頁。若要查看其他頁面，請使用以下命令：
💡 get_doc('pytest/reference/plugin_list.rst', page=3)  # 下一頁
💡 get_doc('pytest/reference/plugin_list.rst', page=5)  # 最後一頁
────────────────────────────────────────────────────────────

[文檔內容]

📚 詳細文檔

可用工具

MCP工具（在Claude內使用）

• list_docs - 顯示文檔列表
• get_doc - 獲取文檔內容（支持分頁）
• grep_docs - 正則表達式搜索
• semantic_search - 語義相似搜索（需要OpenAI API密鑰）

命令行工具（用於文檔管理）

• docs-mcp-import-url - 從網站導入文檔
• docs-mcp-import-github - 從GitHub倉庫導入文檔
• docs-mcp-generate-metadata - 生成語義搜索的元數據

詳細配置選項

{
  "mcpServers": {
    "docs": {
      "command": "uvx",
      "args": ["docs-mcp"],
      "env": {
        "DOCS_BASE_DIR": "/path/to/my-docs",
        "OPENAI_API_KEY": "sk-...",
        "DOCS_FOLDERS": "api,guides,examples",  // 僅加載特定文件夾
        "DOCS_FILE_EXTENSIONS": ".md,.mdx,.txt,.py",  // 限制目標文件擴展名
        "DOCS_MAX_CHARS_PER_PAGE": "5000",  // 每頁最大字符數
        "DOCS_LARGE_FILE_THRESHOLD": "10000"  // 自動分頁閾值（字符數）
      }
    }
  }
}

環境變量

支持的文件格式

目錄結構示例

my-docs/
└── docs/
    ├── api/
    │   └── reference.md
    ├── guides/
    │   └── quickstart.md
    └── examples/
        └── sample.py

🔧 技術細節

從源代碼開發

git clone https://github.com/herring101/docs-mcp.git
cd docs-mcp
uv sync

# 測試
uv run pytest tests/

# 構建
uv build

命令行工具詳情

docs-mcp-import-url https://example.com/docs --output-dir imported

# 導入整個倉庫
docs-mcp-import-github https://github.com/owner/repo

# 僅導入特定路徑（保存在docs/imported下）
docs-mcp-import-github https://github.com/owner/repo/tree/main/docs --output-dir imported

# 也會自動檢測master分支的倉庫
docs-mcp-import-github https://github.com/Cysharp/UniTask

export OPENAI_API_KEY="your-key"
docs-mcp-generate-metadata

安全措施

• 通過環境變量管理API密鑰。
• 使用DOCS_FOLDERS和DOCS_FILE_EXTENSIONS限制訪問。
• 僅允許外部網絡訪問OpenAI API。

故障排除

📄 許可證

本項目採用MIT License。

貢獻說明

請參考CONTRIBUTING.md瞭解如何為項目做出貢獻。