文档-MCP服务器

Name: 文档-MCP服务器
Author: arabold

作者：arabold784 星标更新：2025-11-24

安装使用来源：spider==github.com

项目介绍

Grounded Docs: 您的AI文档专家，时刻更新

AI编码助手经常因过时的文档和幻觉而遇到问题。Docs MCP服务器通过提供一个个人、始终最新的知识库来解决这个问题。它从各种来源（网站、GitHub、npm、PyPI、本地文件）索引第三方文档，并通过模型上下文协议（MCP）提供强大的、版本感知的搜索工具。

这使得您的AI代理能够访问最新官方文档，从而极大地提高生成代码和集成细节的质量和可靠性。它是免费的、开源的，在本地运行以保护隐私，并无缝地集成到您的开发工作流程中。

为什么使用Docs MCP服务器？

LLM辅助编码承诺速度和效率，但往往因为以下原因表现不佳：

🌀 陈旧的知识：LLMs基于互联网快照进行训练，很快就会落后于新库发布和API变更。
👻 代码幻觉：AI可以发明看起来合理的代码，这些代码在语法上是正确的，但在功能上是错误的或使用了不存在的API。
❓ 版本模糊性：通用答案很少考虑项目中的具体版本依赖关系，导致细微的错误。
⏳ 验证开销：开发者花费宝贵的时间来核对AI建议与官方文档的一致性。

Docs MCP服务器通过以下方式解决了这些问题：

✅ 提供最新的上下文：根据需求直接从官方来源（网站、GitHub、npm、PyPI、本地文件）获取并索引文档。
🎯 提供特定版本的答案：搜索查询可以针对确切的库版本，确保信息与项目的依赖项匹配。
💡 减少幻觉：将LLM扎根于真实的文档中，以获得准确的例子和集成细节。
⚡ 提升生产力：更快地获得值得信赖的答案，直接集成到您的AI助手工作流程中。

✨ 关键特性

精确且版本感知的AI响应：提供最新的、特定版本的文档，以减少AI幻觉并提高代码准确性。
广泛的源兼容性：从网站、GitHub仓库、包管理器站点（npm、PyPI）和本地文件目录抓取文档。
高级搜索和处理：智能地按语义分块文档，生成嵌入，并结合向量相似性和全文搜索。
灵活的嵌入模型：支持包括OpenAI（及其兼容API）、Google Gemini/Vertex AI、Azure OpenAI和AWS Bedrock在内的各种提供商。向量搜索是可选的。
企业认证：可选的OAuth2/OIDC认证，具有动态客户端注册，用于安全部署。
Web界面：易于使用的Web界面，用于搜索和管理文档。
本地及私有：完全在您的机器上运行，确保数据和查询保持私密。
免费及开源：社区驱动且免费可用。
简单的部署：通过Docker或npx轻松设置。
无缝集成：与MCP兼容的客户端（如Claude、Cline、Roo）无缝工作。

什么是语义分块？

语义分块基于结构（如标题、代码块和表格）将文档分割成有意义的部分，而不是任意的文本大小。Docs MCP服务器保留逻辑边界，保持代码和表格的完整性，并从HTML文档中移除导航杂乱。这确保LLMs接收到连贯、富含上下文的信息，以产生更准确和相关的答案。

如何运行Docs MCP服务器

选择您的部署方法：

独立服务器（推荐）
嵌入式服务器
高级：Docker Compose（扩展）

独立服务器（推荐）

运行一个包含MCP端点和Web界面的独立服务器。这是开始的最简单方式。

选项1：Docker

安装Docker。

启动服务器：

docker run --rm \
  -v docs-mcp-data:/data \
  -p 6280:6280 \
  ghcr.io/arabold/docs-mcp-server:latest \
  --protocol http --host  0.0.0.0 --port 6280

可选： 添加 -e OPENAI_API_KEY="your-openai-api-key" 以启用向量搜索，提高结果质量。

选项2：npx

安装Node.js 20.x或更高版本。
启动服务器：
```
npx @arabold/docs-mcp-server@latest
```
默认情况下，服务器运行在6280端口。

可选： 前缀 OPENAI_API_KEY="your-openai-api-key" 以启用向量搜索，提高结果质量。

配置您的MCP客户端

将此添加到您的MCP设置（VS Code、Claude Desktop等）：

{
  "mcpServers": {
    "docs-mcp-server": {
      "type": "sse",
      "url": "http://localhost:6280/sse",
      "disabled": false,
      "autoApprove": []
    }
  }
}

替代连接类型：

// SSE（服务器发送事件）
"type": "sse", "url": "http://localhost:6280/sse"

// HTTP（流式传输）
"type": "http", "url": "http://localhost:6280/mcp"

更新配置后重启您的AI助手。

访问Web界面

在浏览器中打开http://localhost:6280以管理文档和监控任务。

使用独立服务器的CLI命令

您还可以使用CLI命令与本地数据库交互：

# 列出已索引的库
OPENAI_API_KEY="your-key" npx @arabold/docs-mcp-server@latest list

# 搜索文档
OPENAI_API_KEY="your-key" npx @arabold/docs-mcp-server@latest search react "useState hook"

# 抓取新的文档（连接到正在运行的服务器的工作程序）
npx @arabold/docs-mcp-server@latest scrape react https://react.dev/reference/react --server-url http://localhost:8080/api

添加库文档

在http://localhost:6280处打开Web界面。
使用“排队新的抓取任务”表单。
输入文档URL、库名称以及（可选）版本。
点击“排队任务”。在任务队列中监控进度。
对每个要索引的库重复上述步骤。

一旦任务完成，文档即可通过您的AI助手或Web UI进行搜索。

Docs MCP服务器Web界面

优点：

单个命令设置，同时包含Web UI和MCP服务器
持久的数据存储（Docker卷或本地目录）
不需要克隆仓库
完整的功能访问，包括Web界面

要停止服务器，请按Ctrl+C。

嵌入式服务器

直接在您的AI助手内嵌入MCP服务器，无需单独进程或Web界面。此方法仅提供MCP集成。

配置您的MCP客户端

将此添加到您的MCP设置（VS Code、Claude Desktop等）：

{
  "mcpServers": {
    "docs-mcp-server": {
      "command": "npx",
      "args": ["@arabold/docs-mcp-server@latest"],
      "disabled": false,
      "autoApprove": []
    }
  }
}

可选： 要启用向量搜索以提高结果质量，添加一个带有API密钥的env部分：

{
  "mcpServers": {
    "docs-mcp-server": {
      "command": "npx",
      "args": ["@arabold/docs-mcp-server@latest"],
      "env": {
        "OPENAI_API_KEY": "sk-proj-..." // 您的OpenAI API密钥
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

更新配置后重启应用程序。

添加库文档

选项1：使用MCP工具

您的AI助手可以使用内置的scrape_docs工具索引新的文档：

请从https://react.dev/reference/react抓取React文档，库名为"react"，版本为"18.x"

选项2：启动Web界面

启动一个临时的Web界面，共享相同的数据库：

OPENAI_API_KEY="your-key" npx @arabold/docs-mcp-server@latest web --port 6281

然后打开http://localhost:6281以管理文档。完成后停止Web界面（Ctrl+C）。

选项3：CLI命令

直接使用CLI命令（避免与嵌入式服务器并发运行抓取任务）：

# 列出库
OPENAI_API_KEY="your-key" npx @arabold/docs-mcp-server@latest list

# 搜索文档
OPENAI_API_KEY="your-key" npx @arabold/docs-mcp-server@latest search react "useState hook"

优点：

直接与AI助手集成
不需要单独的服务器进程
数据持久存储在用户的主目录中
与独立服务器和CLI共享数据库

限制：

没有Web界面（除非单独启动）
文档索引需要MCP工具或单独的命令

抓取本地文件和文件夹

您可以使用file://URL作为源来索引来自本地文件系统的文档。这在Web UI和CLI中都适用。

示例：

Web：https://react.dev/reference/react
本地文件：file:///Users/me/docs/index.html
本地文件夹：file:///Users/me/docs/my-library

要求：

所有MIME类型为text/*的文件都会被处理。这包括HTML、Markdown、纯文本以及.js、.ts、.tsx、.css等源代码文件。二进制文件、PDF、图像和其他非文本格式将被忽略。
必须使用file://前缀表示本地文件/文件夹。
路径必须对服务器进程可访问。
如果在Docker中运行：
- 您必须将本地文件夹挂载到容器中，并在file://URL中使用容器路径。
- 示例Docker运行：
```
docker run --rm \
  -e OPENAI_API_KEY="your-key" \
  -v /绝对路径/to/docs:/docs:ro \
  -v docs-mcp-data:/data \
  -p 6280:6280 \
  ghcr.io/arabold/docs-mcp-server:latest \
  scrape mylib file:///docs/my-library
```
- 在Web UI中，输入路径为file:///docs/my-library（与容器路径匹配）。

有关更多详细信息，请参阅Web UI和CLI帮助中的工具提示。

高级：Docker Compose（扩展）

对于生产部署或需要扩展处理的情况，使用Docker Compose运行单独的服务。系统根据配置选择本地进程内工作者或远程工作者客户端，确保跨模式行为一致。

启动服务：

# 克隆仓库（以获取docker-compose.yml）
git clone https://github.com/arabold/docs-mcp-server.git
cd docs-mcp-server

# 设置环境变量
export OPENAI_API_KEY="your-key-here"

# 启动所有服务
docker compose up -d

服务架构：

工作者（端口8080）：处理文档处理作业
MCP服务器（端口6280）：提供AI工具的/sse端点
Web界面（端口6281）：基于浏览器的管理界面

配置您的MCP客户端：

{
  "mcpServers": {
    "docs-mcp-server": {
      "type": "sse",
      "url": "http://localhost:6280/sse",
      "disabled": false,
      "autoApprove": []
    }
  }
}

替代连接类型：

// SSE（服务器发送事件）
"type": "sse", "url": "http://localhost:6280/sse"

// HTTP（流式传输）
"type": "http", "url": "http://localhost:6280/mcp"

访问接口：

Web界面：http://localhost:6281
MCP端点（HTTP）：http://localhost:6280/mcp
MCP端点（SSE）：http://localhost:6280/sse

这种架构允许独立扩展处理（工作者）和用户界面。

配置

Docs MCP服务器可以在没有任何配置的情况下运行，并仅使用全文搜索。要启用向量搜索以提高结果质量，请通过环境变量配置嵌入提供者。

命令行参数覆盖

许多CLI参数可以通过环境变量覆盖。这对于Docker部署、CI/CD管道或设置默认值非常有用。

环境变量	CLI参数	描述	用于命令
`DOCS_MCP_STORE_PATH`	`--store-path`	自定义数据存储目录路径	所有
`DOCS_MCP_TELEMETRY`	`--no-telemetry`	禁用遥测（设为`false`禁用）	所有
`DOCS_MCP_PROTOCOL`	`--protocol`	MCP服务器协议（自动、标准I/O、HTTP）	默认、MCP
`DOCS_MCP_PORT`	`--port`	服务器端口	默认、MCP、Web、Worker
`DOCS_MCP_WEB_PORT`	`--port`（Web命令）	Web界面端口（仅限Web命令）	Web
`PORT`	`--port`	服务器端口（如果未设置`DOCS_MCP_PORT`则使用）	默认、MCP、Web、Worker
`DOCS_MCP_HOST`	`--host`	服务器主机/绑定地址	默认、MCP、Web、Worker
`HOST`	`--host`	服务器主机（如果未设置`DOCS_MCP_HOST`则使用）	默认、MCP、Web、Worker
`DOCS_MCP_EMBEDDING_MODEL`	`--embedding-model`	嵌入模型配置	默认、MCP、Web、Worker
`DOCS_MCP_AUTH_ENABLED`	`--auth-enabled`	启用OAuth2/OIDC认证	默认、MCP
`DOCS_MCP_AUTH_ISSUER_URL`	`--auth-issuer-url`	OAuth2提供者发行人/发现URL	默认、MCP
`DOCS_MCP_AUTH_AUDIENCE`	`--auth-audience`	JWT受众声明（资源标识符）	默认、MCP

使用示例：

# 通过环境变量设置
export DOCS_MCP_PORT=8080
export DOCS_MCP_HOST=0.0.0.0
export DOCS_MCP_EMBEDDING_MODEL=text-embedding-3-small
npx @arabold/docs-mcp-server@latest

# 通过CLI参数覆盖（优先级更高）
DOCS_MCP_PORT=8080 npx @arabold/docs-mcp-server@latest --port 9090

嵌入提供者配置

Docs MCP服务器通过环境变量进行配置。在您的shell、Docker或MCP客户端配置中设置这些变量。

变量	描述
`DOCS_MCP_EMBEDDING_MODEL`	使用的嵌入模型（见下文选项）。
`OPENAI_API_KEY`	OpenAI API密钥用于嵌入。
`OPENAI_API_BASE`	自定义OpenAI兼容API端点（例如，Ollama）。
`GOOGLE_API_KEY`	Google API密钥用于Gemini嵌入。
`GOOGLE_APPLICATION_CREDENTIALS`	Google服务账户JSON的路径用于Vertex AI。
`AWS_ACCESS_KEY_ID`	AWS密钥用于Bedrock嵌入。
`AWS_SECRET_ACCESS_KEY`	AWS密钥用于Bedrock嵌入。
`AWS_REGION`	AWS区域用于Bedrock。
`AZURE_OPENAI_API_KEY`	Azure OpenAI API密钥。
`AZURE_OPENAI_API_INSTANCE_NAME`	Azure OpenAI实例名称。
`AZURE_OPENAI_API_DEPLOYMENT_NAME`	Azure OpenAI部署名称。
`AZURE_OPENAI_API_VERSION`	Azure OpenAI API版本。

参见上面的示例以了解使用方法。

嵌入模型选项

设置DOCS_MCP_EMBEDDING_MODEL为以下之一：

text-embedding-3-small（默认，OpenAI）
openai:snowflake-arctic-embed2（OpenAI兼容，Ollama）
vertex:text-embedding-004（Google Vertex AI）
gemini:embedding-001（Google Gemini）
aws:amazon.titan-embed-text-v1（AWS Bedrock）
microsoft:text-embedding-ada-002（Azure OpenAI）
或任何OpenAI兼容模型名称

提供商特定配置示例

以下是不同嵌入提供商的完整配置示例：

OpenAI（默认）：

OPENAI_API_KEY="sk-proj-your-openai-api-key" \
DOCS_MCP_EMBEDDING_MODEL="text-embedding-3-small" \
npx @arabold/docs-mcp-server@latest

Ollama（本地）：

OPENAI_API_KEY="ollama" \
OPENAI_API_BASE="http