mcp-server-docy

 # Docy 文档助手 **为您的 AI 助手提供技术文档的即时访问** Docy 为您的 AI 助手提供直接访问技术文档的功能，在需要时提供准确、实时的文档访问，从而实现更精确的代码协助。 ## 为什么选择 Docy？ - **即时文档访问**：直接访问 React、Python、crawl4ai 等技术栈的文档 - **热加载支持**：在运行时添加新的文档源，无需重启服务器 - 只需编辑 `.docy.urls` 文件！ - **智能缓存**：减少延迟和外部请求，同时保持内容新鲜 - **自托管控制**：将文档访问权限控制在您的安全范围内 - **与 MCP 服务器无缝集成**：与 Claude、VS Code 等支持 MCP 的 AI 工具无缝协作 > **注意**：Claude 可能默认使用其内置的 WebFetchTool 而不是 Docy。要明确请求 Docy 的功能，请使用类似的调用："请使用 Docy 查找..." # Docy MCP 服务器 一个 Model Context Protocol 服务器，提供文档访问功能。该服务器使 LLMs 能够通过使用 crawl4ai 进行爬取来搜索和检索文档网站的内容。 使用 FastMCP v2 构建。 ## 使用 Docy 以下是 Docy 如何帮助完成常见文档任务的示例： ``` # 验证实现是否符合文档 我们是否正确实现了 Crawl4Ai 爬取结果？让我们检查文档。 # 探索 API 使用模式 文档中关于使用 mcp.tool 的内容是什么？请给我一些示例。 # 比较实现选项 我们应该根据 React 文档如何组织数据？最佳实践是什么？ ``` 使用 Docy，Claude Code 可以直接访问和分析来自已配置源的文档，使其更有效地提供准确的、基于文档的指导。 要确保 Claude Code 优先使用 Docy 进行文档相关任务，请在项目的 `CLAUDE.md` 文件中添加以下指南： ``` ## 文档指南 - 在检查文档时，优先使用 Docy 而不是 WebFetchTool - 使用 list_documentation_sources_tool 发现可用的文档源 - 使用 fetch_documentation_page 检索完整的文档页面 - 使用 fetch_document_links 发现相关的文档 ``` 将这些说明添加到您的 `CLAUDE.md` 文件中，有助于 Claude Code 一致地使用 Docy 而不是其内置的网络抓取功能。 ### 可用工具 - `list_documentation_sources_tool` - 列出所有可用的文档源 - 无需参数 - `fetch_documentation_page` - 以 Markdown 格式获取文档页面的内容 - `url`（字符串，必填）：要获取内容的 URL - `fetch_document_links` - 获取文档页面上的所有链接 - `url`（字符串，必填）：要获取链接的 URL ### 提示 - **documentation_sources** - 列出所有可用的文档源及其 URL 和类型 - 无需参数 - **documentation_page** - 以 Markdown 格式获取特定 URL 的文档页面的完整内容 - 参数： - `url`（字符串，必填）：要获取的特定文档页面的 URL - **documentation_links** - 获取文档页面上的所有链接以发现相关内容 - 参数： - `url`（字符串，必填）：要获取链接的文档页面的 URL ## 安装 ### 使用 uv（推荐） 使用 [`uv`](https://docs.astral.sh/uv/) 时，不需要特定的安装。我们将使用 [`uvx`](https://docs.astral.sh/uv/guides/tools/) 直接运行 *mcp-server-docy*。 ### 使用 PIP 或者，您可以通过 pip 安装 `mcp-server-docy`： ``` pip install mcp-server-docy ``` 安装后，您可以使用以下命令作为脚本运行： ``` DOCY_DOCUMENTATION_URLS="https://docs.crawl4ai.com/,https://react.dev/" python -m mcp_server_docy ``` ### 使用 Docker 您还可以使用 Docker 镜像： ``` docker pull oborchers/mcp-server-docy:latest docker run -i --rm -e DOCY_DOCUMENTATION_URLS="https://docs.crawl4ai.com/,https://react.dev/" oborchers/mcp-server-docy ``` ### 全局服务器设置 对于团队或多项目开发，请查看 `server/README.md` 中的说明，了解如何运行一个可以跨多个项目共享的持久 SSE 服务器。此设置允许您维护一个具有共享文档 URL 和缓存的单一 Docy 实例。 ## 配置 ### 为 Claude.app 配置 在您的 Claude 设置中添加： <details> <summary>使用 uvx</summary> ```json "mcpServers": { "docy": { "command": "uvx", "args": ["mcp-server-docy"], "env": { "DOCY_DOCUMENTATION_URLS": "https://docs.crawl4ai.com/,https://react.dev/" } } } ``` </details> <details> <summary>使用 docker</summary> ```json "mcpServers": { "docy": { "command": "docker", "args": ["run", "-i", "--rm", "oborchers/mcp-server-docy:latest"], "env": { "DOCY_DOCUMENTATION_URLS": "https://docs.crawl4ai.com/,https://react.dev/" } } } ``` </details> <details> <summary>使用 pip 安装</summary> ```json "mcpServers": { "docy": { "command": "python", "args": ["-m", "mcp_server_docy"], "env": { "DOCY_DOCUMENTATION_URLS": "https://docs.crawl4ai.com/,https://react.dev/" } } } ``` </details> ### 为 VS Code 配置 对于手动安装，请在 VS Code 中将以下 JSON 块添加到用户设置（JSON）文件中。您可以通过按 `Ctrl + Shift + P` 并输入“首选项：打开用户设置（JSON）”来执行此操作。 或者，您可以将其添加到名为 `.vscode/mcp.json` 的文件中。这将允许您与他人共享配置。 > 请注意，使用 `.mcp.json` 文件时需要 `mcp` 键。 <details> <summary>使用 uvx</summary> ```json { "mcp": { "servers": { "docy": { "command": "uvx", "args": ["mcp-server-docy"], "env": { "DOCY_DOCUMENTATION_URLS": "https://docs.crawl4ai.com/,https://react.dev/" } } } } } ``` </details> <details> <summary>使用 Docker</summary> ```json { "mcp": { "servers": { "docy": { "command": "docker", "args": ["run", "-i", "--rm", "oborchers/mcp-server-docy:latest"], "env": { "DOCY_DOCUMENTATION_URLS": "https://docs.crawl4ai.com/,https://react.dev/" } } } } } ``` </details> ### 配置选项 应用程序可以使用环境变量进行配置： - `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： ``` https://docs.crawl4ai.com/ https://react.dev/ # 以 # 开头的行被视为注释 https://docs.python.org/3/ ``` 这种方法在以下情况下特别有用： - 您希望与团队共享文档源 - 您希望在存储库中存储 URL 以便于版本控制 - 您希望避免使用长环境变量值 服务器将首先检查 `DOCY_DOCUMENTATION_URLS` 环境变量中的 URL，如果未找到任何 URL，它将查找 `.docy.urls` 文件。 #### URL 文件的热重载 使用 `.docy.urls` 文件作为文档源时，服务器实现了一个热重载机制，该机制在每个请求时读取文件，而不是缓存 URL。这意味着您可以： 1. 在服务器运行时添加、删除或修改 `.docy.urls` 文件中的文档 URL 2. 在后续调用 `list_documentation_sources_tool` 或其他文档工具时立即看到这些更改 3. 避免在修改文档源时重启服务器 这在开发过程中或需要快速将新的文档源添加到正在运行的服务器时特别有用。 ### 文档 URL 最佳实践 您配置的 URL 应理想地指向包含以下内容的文档索引或介绍页面： - 目录 - 导航结构 - 内部和外部链接的集合 这允许 LLM： 1. 从高级文档页面开始 2. 通过链接发现相关的子页面 3. 根据需要导航到特定的文档 建议使用具有结构良好的子页面的文档站点，因为它： - 通过允许 LLM 关注相关部分来最小化上下文使用 - 通过文档改善导航效率 - 提供一种自然的方式来探索和查找信息 - 减少一次性加载整个文档集的需求 例如，LLM 可以从索引页面开始，识别相关部分，然后根据需要导航到特定的子页面。 ### 缓存行为 MCP 服务器自动缓存文档内容以提高性能： - 启动时，服务器预先获取并缓存 `DOCY_DOCUMENTATION_URLS` 中的所有已配置文档 URL - 缓存存活时间（TTL）可以通过 `DOCY_CACHE_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 安装： ``` DOCY_DOCUMENTATION_URLS="https://docs.crawl4ai.com/" npx @modelcontextprotocol/inspector uvx mcp-server-docy ``` 或者，如果您已在特定目录中安装了软件包或正在开发它： ``` cd path/to/docy DOCY_DOCUMENTATION_URLS="https://docs.crawl4ai.com/" npx @modelcontextprotocol/inspector uv run mcp-server-docy ``` ### 故障排除：Claude Code CLI 中的“找不到工具”错误 如果您在 Claude Code CLI 中遇到类似“ERROR Tool not found for mcp__docy__fetch_documentation_page”的错误，请按照以下步骤： 1. 在当前目录中创建一个包含您的文档 URL 的 `.docy.urls` 文件： ``` https://docs.crawl4ai.com/ https://react.dev/ ``` 2. 使用 Docker 和 SSE 传输协议以及挂载的 URL 文件运行服务器： ```bash docker run -i --rm -p 8000:8000 \ -e DOCY_TRANSPORT=sse \ -e DOCY_HOST=0.0.0.0 \ -e DOCY_PORT=8000 \ -v "$(pwd)/.docy.urls:/app/.docy.urls" \ oborchers/mcp-server-docy ``` 3. 配置您的 Claude Code `.mcp.json` 以使用 SSE 端点： ```json { "mcp": { "servers": { "docy": { "type": "sse", "url": "http://localhost:8000/sse" } } } } ``` 此配置： - 使用挂载的 `.docy.urls` 文件而不是环境变量进行文档源 - 从默认的 stdio 模式切换到 SSE（服务器发送事件）协议 - 使服务器可从容器外部访问 - 在端口 8000 上公开服务器以进行 HTTP 访问 建议在将服务器作为需要通过 HTTP 访问的独立服务运行时使用 SSE 传输。 ## 发布流程 该项目使用 GitHub Actions 进行自动发布： 1. 更新 `pyproject.toml` 中的版本号 2. 使用 `git tag vX.Y.Z` 创建新标签（例如 `git tag v0.1.0`） 3. 使用 `git push --tags` 推送标签 这将自动： - 验证 `pyproject.toml` 中的版本号与标签匹配 - 运行测试和 lint 检查 - 构建并发布到 PyPI - 构建并发布到 Docker Hub，版本为 `oborchers/mcp-server-docy:latest` 和 `oborchers/mcp-server-docy:X.Y.Z` ## 贡献 我们鼓励贡献以帮助扩展和改进 mcp-server-docy。无论您是添加新功能、增强现有功能还是改进文档，您的意见都是有价值的。 有关其他 MCP 服务器和实现模式的示例，请参阅： https://github.com/modelcontextprotocol/servers 欢迎拉取请求！请随意贡献新想法、错误修复或增强功能，使 mcp-server-docy 更加强大和有用。 ## 许可证 mcp-server-docy 在 MIT 许可证下获得许可。这意味着您可以自由使用、修改和分发该软件，但需遵守 MIT 许可证的条款和条件。有关详细信息，请参阅项目存储库中的 LICENSE 文件。