devdocs-mcp

DevDocs-MCP：AI Agent 的权威文档来源

借助本地、版本感知且权威的文档，消除 AI 的幻觉。

DevDocs-MCP 是一个 Model Context Protocol（MCP）服务，为 AI 助手（Claude、RooCode、Cline、Copilot 等）提供来自 DevDocs.io 的固定版本、确定性文档。它充当本地文档智能层，确保你的 Agent 始终获得正确的 API 上下文，不受网络延迟或训练数据偏差的影响。

此服务遵循 MCP 提出的 MCP 服务标准。整个生态系统中的 AI 工具和 Agent（包括 Anthropic、OpenAI 和 Google 等提供商的产品）都在采用该标准。

⚠️ 项目状态说明 ⚠️ 此项目正处于活跃且快速的开发阶段。目前仍需测试现有功能，并实现更多新功能，例如优化缓存、自动更新最新文档并支持按需更新、优化查询等。设计决策、API 和项目结构预计会根据开发者社区的意见、评审和反馈不断演进。我热忱欢迎大家参与讨论、提出批评和贡献代码，共同推动项目朝正确的方向发展。

📑 目录

1. 概述
2. 核心功能
3. 快速开始
4. 安装与设置
5. AI Agent 配置
6. 延伸阅读

🎯 概述

graph TD
    Agent["AI Agents"] -->|MCP Search/Explain| Server["DevDocs-MCP Server"]
    Server -->|Metadata| DB[(SQLite - sql.js)]
    Server -->|Content| FS[Local Disk - JSON Cache]
    Server -.->|Lazy Fetch| Web[DevDocs.io API]

🚀 核心功能

• 离线优先：文档缓存在本地；摄取完成后无需联网。
• 排序模糊搜索：即时查找相关条目（例如“intersection observer”）。
• 版本感知：自动映射到项目中指定的库版本。
• 纯 Node 架构：使用 sql.js，无需原生依赖（不需要 Python/C++ 构建步骤）。
• 结构化输出：返回简洁、针对 LLM 优化的内容。

⚡ 快速开始

1. 克隆并安装

git clone https://github.com/madhan-g-p/DevDocs-MCP.git
cd DevDocs-MCP
pnpm install

2. 配置环境

cp .env.example .env
# Edit .env: Set DEVDOCS_DATA_PATH to where you want to store docs.

3. 构建并运行

pnpm build
pnpm start:prod

**注意：**开发和贡献时必须使用 pnpm。

🛠️ 安装与设置

DevDocs-MCP 通过 pnpm 实现轻松设置。它是一个仅限 Node.js 的项目。

前置条件

• Node.js 18+（已在 18.x 和 20.x 上测试）。

🐳 Docker 用法

DevDocs-MCP 专为轻量化和持久化而设计。由于它会下载并缓存大型文档数据集，因此正确管理数据卷至关重要。

方法 A：Docker Compose（动态且持久）

这是推荐的方法。通过 .env 文件中的 DEVDOCS_VOLUME_SOURCE 变量，它支持 3 种存储模式。

1. 在 .env 中配置首选存储方式：

   # 模式 1：命名卷（默认 — 由 Docker 管理）
   DEVDOCS_VOLUME_SOURCE=devdocs_data
   
   # 模式 2：主机路径（Docker 外部 — 本地文件夹）
   # DEVDOCS_VOLUME_SOURCE=./my-docs-storage
   

2. 启动服务：

   docker compose up -d
   

灵活性：每次启动容器时，只需更改 .env 文件中的 DEVDOCS_VOLUME_SOURCE，即可指定新卷（从头开始）或现有卷（保留数据）。mcp.db（数据库库）和 data/（文档下载文件）都会存储在此卷中。

方法 B：Docker Run（手动）

如果你只想直接从 Docker Hub 运行公开镜像：

docker run -d -p 3000:3000 \
  -v "devdocs_data:/app/data" \
  --name devdocs-mcp \
  madhandock1/devdocs-mcp:latest

💾 数据策略

项目使用 /app/data 这一个挂载点，其中包含：

• /app/data/mcp.db：SQLite 注册表。
• /app/data/docs/：缓存的文档文件。 这种统一结构让你只需移动一个文件夹或卷，就能轻松备份或迁移整个文档库。

配置（.env）

导入文档

服务器连接到你的 Agent 后，使用 ingest 工具下载与你的技术栈对应的文档： 服务器启动并运行后，Agent 会负责处理；它应该会列出可用工具，并据此作出决定。

{
  "dependencies": {
    "react": "18.2.0",
    "typescript": "5.0.0"
  }
}

注意：用于导入的 Devdocs 获取 URL 定义在 src/config/constants.ts 中。此 URL 当前指向正确且官方支持的路径。如果 devdocs 社区未来更改此路径，可能需要相应更新配置。
此方法不涉及网页抓取，而是采用 DevDocs 使用的相同支持机制来提供离线使用的文档，类似于用户在 DevDocs 中下载文档的方式。

🤖 AI Agent 配置

RooCode / Cline / Claude Desktop（推荐：STDIO）

将以下内容添加到 mcp_settings.json。设置 cwd（当前工作目录）后，服务会自动从 .env 文件加载配置，让你可以使用相对路径存储数据。

{
  "mcpServers": {
    "devdocs": {
      "command": "node",
      "args": ["dist/main.js"],
      "cwd": "file://path/to/your/DevDocs-MCP"
    }
  }
}

专业提示：在 cwd 中使用项目的绝对路径。这样服务就能找到 .env，并使用你在其中定义的 DEVDOCS_DATA_PATH 和 MCP_DB_PATH（例如 ./data 或 mcp.db），让设置更易于移植！

远程 / Web 客户端（HTTP SSE）

如果需要通过端口公开服务（用于生产环境 / 远程设置）：

1. 使用端口标志启动服务：

   node dist/main.js --port 3000
   

2. 配置客户端：
   • SSE URL：http://your-server:3000/mcp/sse
   • 类型：SSE（大多数 MCP 客户端都支持，至少我猜是这样）

📖 延伸阅读

• 系统架构：深入了解数据流、架构和 sql.js 内部机制。
• 贡献者指南：工作流、编码规范和 PR 要求。
• 许可证：MIT 许可证。

灵感来自 @Nathaniel Whiteinge 的项目 devdocs-local、 devdocs-local-demo