星战科技xingzhan.cloud
返回市场
MCP服务器文档工具

MCP服务器文档工具

作者：oborchers17 星标更新：2025-04-29
安装使用来源：spider==github.com

项目介绍

Docy Logo

Docy: 您的AI指尖上的文档

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

Docy让您的AI可以直接访问它需要的技术文档，就在它需要的时候。不再有过时的信息、断开的链接或速率限制——只需准确、实时的文档访问，以提供更精确的编码帮助。

为什么选择Docy？

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

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

Docy MCP服务器

一个提供文档访问能力的模型上下文协议服务器。该服务器使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 - 根据URL获取文档页面的内容作为markdown

    • url (字符串，必需)：要获取内容的URL

  • fetch_document_links - 获取文档页面中的所有链接

    • url (字符串，必需)：要获取链接的URL

提示

  • documentation_sources

    • 列出所有可用的文档源及其URL和类型
    • 不需要参数

  • documentation_page

    • 根据特定URL获取文档页面的完整内容作为markdown
    • 参数：
      • url (字符串，必需)：特定文档页面的URL

  • documentation_links

    • 获取文档页面中的所有链接以发现相关内容
    • 参数：
      • url (字符串，必需)：要获取链接的文档页面的URL

安装

使用uv（推荐）

当使用uv时，不需要特定的安装。我们将使用uvx直接运行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> 
"mcpServers": {
  "docy": {
    "command": "uvx",
    "args": ["mcp-server-docy"],
    "env": {
      "DOCY_DOCUMENTATION_URLS": "https://docs.crawl4ai.com/,https://react.dev/"
    }
  }
}
</details> <details> <summary>使用docker</summary> 
"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> 
"mcpServers": {
  "docy": {
    "command": "python",
    "args": ["-m", "mcp_server_docy"],
    "env": {
      "DOCY_DOCUMENTATION_URLS": "https://docs.crawl4ai.com/,https://react.dev/"
    }
  }
}
</details>

针对VS Code的配置

对于手动安装，将以下JSON块添加到VS Code的用户设置（JSON）文件中。您可以通过按Ctrl + Shift + P并键入Preferences: 打开用户设置（JSON）来执行此操作。

可选地，您可以将其添加到工作区中的名为.vscode/mcp.json的文件中。这将允许您与其他人员共享配置。

注意，当使用mcp.json文件时，需要mcp键。

<details> <summary>使用uvx</summary> 
{
  "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> 
{
  "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，如果没有找到，则会查找.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 inspector运行：uv run --with fastmcp --with-editable /Users/oliverborchers/Desktop/Code.nosync/mcp-server-docy --with crawl4ai --with loguru --with diskcache --with pydantic-settings fastm mcp run src/mcp_server_docy/__main__.py

调试

您可以使用MCP inspector来调试服务器。对于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

故障排除："Tool not found"错误在Claude Code CLI中

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

  1. 在当前目录中创建一个.docy.urls文件，并添加您的文档URL：
https://docs.crawl4ai.com/
https://react.dev/
  1. 使用Docker运行服务器，使用SSE传输协议并挂载URL文件：
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
  1. 配置您的Claude Code .mcp.json以使用SSE端点：
{
  "mcp": {
    "servers": {
      "docy": {
        "type": "sse",
        "url": "http://localhost:8000/sse"
      }
    }
  }
}

此配置：

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

当作为需要通过HTTP访问的独立服务运行时，推荐使用SSE传输，特别是在Docker部署中特别有用。

发布过程

该项目使用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

欢迎提交拉取请求！请自由贡献新想法、bug修复或增强功能，使mcp-server-docy更加强大和实用。

许可

mcp-server-docy根据MIT许可证授权。这意味着您可以在遵守MIT许可证条款和条件的情况下自由使用、修改和分发软件。更多详情，请参阅项目存储库中的LICENSE文件。