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了解如何为项目做出贡献。