mcp-server-docy

Docy：AI 触手可及的文档

通过即时访问技术文档，增强您的 AI 助手的功能。

Docy 让您的 AI 能够在需要时直接访问所需的技术文档。告别过时信息、失效链接或速率限制，只需访问准确、实时的文档，即可获得更精准的编码辅助。

为什么选择 Docy？

• 即时文档访问：直接访问 React、Python、crawl4ai 和您使用的任何其他技术栈的文档
• 热重载支持：无需重新启动即可动态添加新的文档源 - 只需编辑.docy.urls 文件！
• 智能缓存：减少延迟和外部请求，同时保持新鲜内容
• 自托管控制：将您的文档访问保持在安全范围内
• 无缝 MCP 集成：轻松与 Claude、VS Code 和其他支持 MCP 的 AI 工具配合使用

注意：Claude 可能默认使用其内置的 WebFetchTool 而不是 Docy。要明确请求 Docy 的功能，请使用类似这样的标注：“请使用 Docy 查找...”

Docy MCP 服务器

提供文档访问功能的模型上下文协议 (MCP) 服务器。该服务器支持 LLM 使用 crawl4ai 抓取文档网站内容，从而搜索和检索内容。基于 FastMCP v2 构建。

使用 Docy

以下是 Docy 如何帮助完成常见文档任务的示例：

借助 Docy，Claude Code 可以直接访问和分析来自配置源的文档，从而更有效地提供准确的基于文档的指导。

为确保 Claude Code 优先使用 Docy 执行与文档相关的任务，请将以下准则添加到项目的CLAUDE.md文件中：

将这些说明添加到您的CLAUDE.md文件中有助于 Claude Code 在处理文档时始终使用 Docy 而不是其内置的 Web 获取功能。

可用工具

• list_documentation_sources_tool - 列出所有可用的文档来源
  • 无需参数
• fetch_documentation_page - 通过 URL 获取文档页面内容作为 markdown
  • url (字符串，必需)：获取内容的 URL
• fetch_document_links - 从文档页面获取所有链接
  • url (字符串，必需)：获取链接的 URL

提示

• 文档来源
  • 列出所有可用的文档源及其 URL 和类型
  • 无需任何参数
• 文档页面
  • 获取指定 URL 上的文档页面的全部内容作为 markdown
  • 参数：
    • url （字符串，必需）：要获取的特定文档页面的 URL
• 文档链接
  • 从文档页面获取所有链接以发现相关内容
  • 参数：
    • url （字符串，必需）：获取链接的文档页面的 URL

安装

使用 uv（推荐）

使用uv时无需特殊安装。我们将使用uvx直接运行mcp-server-docy 。

使用 PIP

或者，您可以通过 pip 安装mcp-server-docy ：

安装后，您可以使用以下命令将其作为脚本运行：

使用 Docker

您还可以使用 Docker 镜像：

全局服务器设置

对于团队或多项目开发，请查看server/README.md以获取有关运行可在多个项目之间共享的持久 SSE 服务器的说明。此设置允许您维护一个包含共享文档 URL 和缓存的 Docy 实例。

配置

为 Claude.app 配置

添加到您的 Claude 设置：

配置 VS Code

如需手动安装，请将以下 JSON 块添加到 VS Code 中的“用户设置 (JSON)”文件中。您可以按下Ctrl + Shift + P并输入Preferences: Open User Settings (JSON)来执行此操作。

或者，您可以将其添加到工作区中名为.vscode/mcp.json的文件中。这样您就可以与其他人共享该配置。

请注意，使用mcp.json文件时需要mcp密钥。

配置选项

可以使用环境变量来配置应用程序：

• DOCY_DOCUMENTATION_URLS （字符串）：要包含的文档站点 URL 的逗号分隔列表（例如，“ https://docs.crawl4ai.com/,https://react.dev/ ”）
• DOCY_DOCUMENTATION_URLS_FILE （字符串）：包含文档 URL 的文件路径，每行一个（默认值：“.docy.urls”）
• DOCY_CACHE_TTL （整数）：缓存生存时间（秒）（默认值：432000）
• DOCY_CACHE_DIRECTORY （字符串）：缓存目录的路径（默认值：“.docy.cache”）
• DOCY_USER_AGENT （字符串）：HTTP 请求的自定义 User-Agent 字符串
• DOCY_DEBUG （布尔值）：启用调试日志记录（“true”、“1”、“yes”或“y”）
• DOCY_SKIP_CRAWL4AI_SETUP （布尔值）：启动时跳过运行 crawl4ai-setup 命令（“true”、“1”、“yes”或“y”）
• DOCY_TRANSPORT （字符串）：要使用的传输协议（选项：“sse”或“stdio”，默认值：“stdio”）
• DOCY_HOST （字符串）：绑定服务器的主机地址（默认值：“127.0.0.1”）
• DOCY_PORT （整数）：运行服务器的端口（默认值：8000）

环境变量可以直接设置，也可以通过.env文件设置。

URL配置文件

作为设置DOCY_DOCUMENTATION_URLS环境变量的替代方法，您可以在项目目录中创建一个.docy.urls文件，每行一个 URL：

此方法尤其适用于：

• 您希望与团队共享文档源的项目
• 在版本控制中存储 URL 是有益的存储库
• 想要避免使用长环境变量值的情况

服务器将首先检查DOCY_DOCUMENTATION_URLS环境变量中的 URL，如果没有找到，它将查找.docy.urls文件。

URL 文件热加载

当使用.docy.urls文件作为文档源时，服务器会实现热重载机制，该机制会在每次请求时读取文件，而不是缓存 URL。这意味着您可以：

1. 在服务器运行时添加、删除或修改.docy.urls文件中的文档 URL
2. 在后续调用list_documentation_sources_tool或其他文档工具时，立即查看这些更改
3. 修改文档源时避免重新启动服务器

这在开发过程中或当您需要快速向正在运行的服务器添加新的文档源时特别有用。

文档 URL 最佳实践

您配置的 URL 理想情况下应该指向包含以下内容的文档索引或介绍页面：

• 目录
• 导航结构
• 内部和外部链接的集合

这使得法学硕士能够：

1. 从高级文档页面开始
2. 通过链接发现相关子页面
3. 根据需要导航至特定文档

强烈建议使用具有结构良好的子页面的文档站点，因为它：

• 通过允许法学硕士 (LLM) 专注于相关部分，最大限度地减少上下文使用
• 通过文档提高导航效率
• 提供一种自然的方式来探索和查找信息
• 减少一次性加载整个文档集的需要

例如，LLM 无需加载整个文档站点，而是可以从索引页开始，识别相关部分，然后根据需要导航到特定的子页面。

缓存行为

MCP 服务器自动缓存文档内容以提高性能：

• 启动时，服务器会从DOCY_DOCUMENTATION_URLS预取并缓存所有已配置的文档 URL
• 可以通过DOCY_CACHE_TTL环境变量配置缓存生存时间 (TTL)
• 每个新访问的站点都会自动加载到缓存中，以减少流量并提高响应时间
• 使用diskcache库将缓存内容存储在持久的基于磁盘的缓存中
• 可以通过DOCY_CACHE_DIRECTORY环境变量配置缓存位置（默认值：“.docy.cache”）
• 缓存在服务器重启后仍然存在，为经常访问的文档提供更好的性能

缓存的例外

虽然大多数内容都会被缓存以提高性能，但也有特定的例外：

• 文档 URL 列表：使用.docy.urls文件时，文档源列表不会被缓存 - 相反，该文件会在每次请求时重新读取，以支持 URL 的热加载
• 页面内容：文档页面的实际内容仍根据配置的TTL进行缓存

这种混合方法既为内容访问提供了性能优势，又为文档源管理提供了灵活性。

本地开发

• 以开发模式运行： fastmcp dev src/mcp_server_docy/__main__.py --with-editable .
• 访问 API： http://127.0.0.1:6274
• 使用 MCP 检查器运行： uv run --with fastmcp --with-editable /Users/oliverborchers/Desktop/Code.nosync/mcp-server-docy --with crawl4ai --with loguru --with diskcache --with pydantic-settings fastmcp run src/mcp_server_docy/__main__.py

调试

您可以使用 MCP 检查器来调试服务器。对于 uvx 安装：

或者，如果您已将软件包安装在特定目录中或正在其上进行开发：

故障排除：Claude Code CLI 中的“未找到工具”错误

如果您在 Claude Code CLI 中遇到“ERROR Tool not found for mcp__docy__fetch_documentation_page”之类的错误，请按照以下步骤操作：

1. 在当前目录中创建一个包含文档 URL 的.docy.urls文件：

2. 使用带有 SSE 传输协议的 Docker 运行服务器并挂载 URL 文件：

3. 配置您的 Claude Code .mcp.json以使用 SSE 端点：

此配置：

• 使用已挂载的.docy.urls文件而不是环境变量作为文档源
• 从默认的 stdio 模式切换到 SSE（服务器发送事件）协议
• 使服务器可从容器外部访问
• 将服务器暴露在端口 8000 上以供 HTTP 访问

当将服务器作为需要通过 HTTP 访问的独立服务运行时，建议使用 SSE 传输，这对于 Docker 部署特别有用。

发布流程

该项目使用 GitHub Actions 进行自动发布：

1. 更新pyproject.toml中的版本
2. 使用git tag vX.YZ创建一个新标签（例如， git tag v0.1.0 ）
3. 使用git push --tags推送标签

这将自动：

• 验证pyproject.toml中的版本与标签匹配
• 运行测试和 Lint 检查
• 构建并发布到 PyPI
• 构建并发布到 Docker Hub，例如oborchers/mcp-server-docy:latest和oborchers/mcp-server-docy:XYZ

贡献

我们鼓励您为扩展和改进 mcp-server-docy 做出贡献。无论您是想添加新功能、增强现有功能还是改进文档，您的贡献都弥足珍贵。

有关其他 MCP 服务器和实现模式的示例，请参阅： https://github.com/modelcontextprotocol/servers

欢迎提交 Pull 请求！欢迎贡献新想法、错误修复或改进，让 mcp-server-docy 更加强大实用。

执照

mcp-server-docy 采用 MIT 许可证。这意味着您可以自由使用、修改和分发该软件，但需遵守 MIT 许可证的条款和条件。更多详细信息，请参阅项目仓库中的 LICENSE 文件。