Docs MCP Server

Grounded Docs MCP Server

Grounded Docs 为你的 AI 编码助手提供文档索引，并与您使用的库版本相匹配。它会从网站、GitHub 仓库、npm、PyPI 和本地文件夹获取文档，并通过 Model Context Protocol（MCP）、命令行和 Web 界面提供搜索功能。你的助手会基于这些文档回答，而不是依赖记忆中的内容。

它是 Context7、Nia 和 Ref.Tools 的开源替代方案。

功能

• 为网站、GitHub 仓库、npm 和 PyPI 软件包、本地文件夹及归档文件（ZIP、TAR）建立索引。
• 读取 HTML、Markdown、PDF、Office 和 OpenDocument 文件、EPUB、Jupyter 笔记本、源代码等。请参阅支持的格式。
• 分别存储每个库版本，因此搜索会针对项目所用的版本。
• 将全文搜索与可选的向量搜索相结合，向量搜索可通过 OpenAI、Ollama、Gemini、Vertex AI、AWS Bedrock、Azure OpenAI 或任何兼容 OpenAI 的服务端实现。
• 在你的设备上运行，并将索引保存在本地 SQLite 数据库中。文档文本只会发送给你配置的嵌入服务；如果使用 Ollama 等本地服务，文本会留在你的设备上。使用情况遥测默认开启；遥测列出了发送的内容以及关闭方法。
• 可通过 stdio 或 Streamable HTTP 与任何 MCP 客户端配合使用。

快速开始

你需要 Node.js 22 或更高版本，或者 Docker。安装详细介绍了这两种方式，以及 Docker Compose 和如何在 AI 客户端内部运行服务。

1. 启动服务

npx @arabold/docs-mcp-server@latest

或者使用 Docker：

docker run --rm \
  -v docs-mcp-data:/data \
  -v docs-mcp-config:/config \
  -p 6280:6280 \
  ghcr.io/arabold/docs-mcp-server:latest

2. 启用向量搜索（可选）

如果没有嵌入模型，搜索将使用全文匹配。向量搜索还可以按含义查找段落。若要使用 OpenAI，请设置 OPENAI_API_KEY 后启动服务：

OPENAI_API_KEY="sk-proj-..." npx @arabold/docs-mcp-server@latest

使用 Docker 时，添加 -e OPENAI_API_KEY="sk-proj-..."。嵌入模型介绍了 Ollama、Gemini、Azure OpenAI 和其他服务提供商。

请在添加文档前完成此操作。嵌入向量会在页面建立索引时计算，因此未使用模型建立索引的文档不会生成向量，除非你使用 --replace 再次抓取。

3. 添加文档

打开 Web 界面 http://localhost:6280，然后选择 添加库。

4. 连接 AI 客户端

将服务的 MCP 端点 http://localhost:6280/mcp 添加到客户端。大多数客户端接受如下配置项：

{
  "mcpServers": {
    "docs-mcp-server": {
      "url": "http://localhost:6280/mcp"
    }
  }
}

MCP 客户端连接指南提供了 Claude Code、Claude Desktop、Zed 和其他客户端的具体设置，介绍了客户端如何通过 stdio 自行启动服务，并列出了 MCP 工具。

命令行

CLI 无需运行中的服务即可建立索引并搜索，适用于脚本和编码 Agent。它与同一设备上的服务共用数据库。

# Index documentation
npx @arabold/docs-mcp-server@latest scrape react https://react.dev/reference/react

# Search it
npx @arabold/docs-mcp-server@latest search react "useEffect cleanup" --output yaml

# Fetch one page as Markdown without indexing it
npx @arabold/docs-mcp-server@latest fetch-url https://react.dev/reference/react/useEffect

如果库版本已存在，scrape 会拒绝操作。传入 --replace 可重新构建该版本，也可以运行 refresh 原地更新。skills/ 目录包含可教会编码 Agent 使用这些命令的 Agent Skills。基本用法介绍了所有命令、输出格式和本地文件。

网页抓取

• 抓取或刷新网站前，会在起始 URL 所在目录和网站根目录中查找 llms.txt 文件。其中列出的链接会成为额外的起始点；对于这些页面，抓取器会先尝试 URL 对应的 Markdown 版本，例如 /guide/index.html.md 或 /page.html.md。
• 请求会优先获取 HTML，就像浏览器一样。服务器在收到请求后转换生成的 Markdown 不包含网站导航，因此抓取会遗漏大多数页面。网站发布 Markdown 的地方，抓取器会使用 Markdown：llms.txt 中列出的页面以及指向 .md 文件的链接。自定义 Accept 标头会替换默认标头。
• 对于使用哈希 URL 路由的文档网站，例如 https://docs.example.com/#/guide，请为抓取启用哈希路由。请参阅哈希路由行为。

文档

设置：

• 安装：npx、Docker、Docker Compose 和嵌入式服务。
• 配置：配置文件、环境变量和所有设置。
• 嵌入模型：提供商、模型以及如何更换模型。

使用：

• 基本用法：Web 界面、命令行和本地文件。
• 连接 MCP 客户端：客户端设置和 MCP 工具。
• 支持的格式：文件格式及其处理方式。
• 搜索质量基准测试：衡量检索质量。

部署：

• 部署模式：单进程，或使用独立 MCP 和 Web 服务的工作进程。
• 反向代理部署：通过类似 https://example.com/docs 的路径提供服务。
• 身份验证：使用 OAuth2/OIDC 保护 MCP 端点。
• 安全：信任边界以及抓取器可访问范围的限制。
• 遥测：服务发送的使用情况事件，以及如何关闭遥测。

内部：

• 架构：面向贡献者的系统设计说明。

贡献

开发环境设置和指南请参阅 CONTRIBUTING.md。

许可证

本项目基于 MIT License 授权。详情请参阅 LICENSE。