mcp-server-ragdocs

你是否曾经希望 AI 助手能够直接“阅读”你公司的内部文档库，然后基于最新的、准确的信息回答你的问题？将文档直接放入提示词中，往往会因为内容过长而超出上下文限制，或者无法找到最相关的那一段。

这就是 mcp-server-ragdocs 要解决的问题。它是一个基于模型上下文协议的服务器，通过向量搜索技术，让你的 AI 助手能够从海量的文档中检索最相关的片段，从而增强其回答的质量和准确性。你可以将其理解为“为 AI 构建的即时文档问答系统”。

项目基本信息

一、项目介绍

mcp-server-ragdocs 是一个功能完善的 RAG 检索增强生成 MCP 服务器。它使用向量数据库来存储文档的嵌入向量，并提供了一系列工具来管理文档源、执行语义搜索以及处理网页内容。

该项目基于一个重要的核心理念：AI 的回答应该基于可检索的证据。它将 RAG 的完整流程——文档获取、切片、向量化、存储、检索——封装成 MCP 工具，并通过标准协议暴露给 AI。

该服务器提供的核心工具包括：

• search_documentation：根据自然语言查询，从向量数据库中找到最相关的文档片段。
• extract_urls：从一个网页中提取所有链接，并选择性地添加到处理队列。
• run_queue：处理队列中的所有 URL，对它们进行抓取、切片、生成嵌入向量并存储。
• list_sources：列出所有已索引的文档源。
• remove_documentation：从数据库中移除特定的文档源。
• list_queue 和 clear_queue：管理待处理的 URL 队列。

二、核心优势

完整的 RAG 生命周期管理
不仅仅是搜索，而是涵盖了从文档发现、抓取、处理到检索的全过程。你只需要提供起始 URL，其他的交给队列系统。

支持本地和云端两种模式
你可以完全在本地运行整个栈：使用 Ollama 生成嵌入向量，使用 Qdrant 作为向量数据库。也可以使用 OpenAI 的嵌入模型和 Qdrant 云服务，以获得更高性能。

灵活的内容提取
服务器集成了 Playwright，可以处理现代 JavaScript 渲染的网页。它既能抓取单个页面，也能递归地处理一个站点。Playwright 可以作为本地进程运行，也可以通过 Docker 容器运行，解决了依赖问题。

丰富的队列管理
run_queue 和 list_queue 让你能够控制处理节奏。你可以先批量添加 URL，然后在需要的时候再触发处理，非常适合对大型文档库进行后台索引。

开源且可扩展
该项目采用 MIT 许可证，代码结构清晰（模块化架构）。基于它，你可以轻松添加对更多文档格式（如 PDF、Word）的支持，或者接入不同的向量数据库。

三、适用场景

企业内部知识库问答
将公司内部的 Confluence、Notion 或技术文档网站的 URL 加入队列，让服务器抓取并索引。然后，你可以问 AI：“我们公司关于远程办公的政策是什么？” AI 会搜索这些内部文档并给出答案。

技术文档助手
为你的开源项目构建一个文档助手。将项目文档网站的所有页面索引后，用户可以直接问：“这个库的安装步骤是什么？” AI 会从你的官方文档中提取正确步骤。

竞品分析
将竞品的帮助文档或博客文章索引后，你可以问：“竞品 X 在 Y 功能上提供了哪些配置选项？” AI 会从多个相关页面中提取信息，帮你快速了解。

自动化内容摘要
你可以定期运行 run_queue 来处理一批新的博客文章，然后让 AI 根据检索到的内容生成摘要，而不需要手动复制粘贴。

法律或合规文档检索
将大量 PDF 格式的法规文件转换为 HTML 或文本，然后索引。律师或合规人员可以快速问：“关于数据跨境传输的最新规定有哪些？”

四、安装教程

安装 mcp-server-ragdocs 需要你先准备好向量数据库和嵌入模型。以下是使用 Docker Compose 进行本地全栈部署的推荐方式。

准备工作

确保你的系统已安装 Docker 和 Docker Compose，以及 Node.js 18+。

第一步：克隆并启动基础设施

git clone https://github.com/sanderkooger/mcp-server-ragdocs.git
cd mcp-server-ragdocs
docker compose up -d

这将启动：

• Qdrant 向量数据库，监听端口 6333
• Ollama 服务，监听端口 11434（用于本地嵌入）
• Playwright 浏览器服务（可选），用于抓取动态网页

第二步：拉取嵌入模型（Ollama）

# 在本地安装 Ollama（如果尚未安装）
curl -fsSL https://ollama.com/install.sh | sh
# 拉取推荐的嵌入模型
ollama pull nomic-embed-text

第三步：安装 MCP 服务器（全局）

npm install -g @sanderkooger/mcp-server-ragdocs

第四步：配置 MCP 客户端

对于 Claude Desktop，编辑配置文件（macOS: ~/Library/Application Support/Claude/claude_desktop_config.json；Windows: %AppData%\Claude\claude_desktop_config.json），添加：

{
  "mcpServers": {
    "ragdocs": {
      "command": "npx",
      "args": ["-y", "@sanderkooger/mcp-server-ragdocs"],
      "env": {
        "EMBEDDINGS_PROVIDER": "ollama",
        "OLLAMA_BASE_URL": "http://localhost:11434",
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

第五步：重启客户端

保存配置，完全退出并重启 Claude Desktop。

五、使用示例

以下是在配置好服务器后，与 Claude 的自然语言对话示例。假设你已经通过 extract_urls 和 run_queue 索引了一些文档。

示例1：搜索文档

用户输入：在我们的技术文档库中搜索关于“身份验证”的内容。

Claude 会调用 search_documentation，参数为 query: "身份验证", limit: 5。然后返回最匹配的 5 个文档片段，并附上来源 URL。Claude 会基于这些片段总结答案。

示例2：添加新的文档源

用户输入：请将 https://example.com/docs 这个页面以及它链接的所有同域页面都加入处理队列。

AI 会先调用 extract_urls，参数为 url: "https://example.com/docs", add_to_queue: true。该工具会解析页面，将发现的 URL 添加到队列。然后你可以输入：现在处理队列中的所有 URL。 AI 会调用 run_queue 开始索引。

示例3：列出已有源

用户输入：目前已经索引了哪些文档源？

Claude 会调用 list_sources，返回一个已索引 URL 的列表，包括标题和最后更新时间。

示例4：移除过时文档

用户输入：从数据库中移除 https://old-docs.example.com/old-page 。

AI 会调用 remove_documentation，参数为 urls: ["https://old-docs.example.com/old-page"]。

六、常见问题

问题1：运行 docker compose up -d 后，Qdrant 或 Ollama 无法启动。

解决方案：请检查端口是否被占用。Qdrant 默认使用 6333，Ollama 使用 11434。你可以通过 docker compose logs 查看错误日志。如果是第一次运行，拉取镜像可能需要几分钟。

问题2：search_documentation 返回空结果，但我确信已经索引了文档。

解决方案：

1. 确认 Qdrant 容器正在运行，并且 QDRANT_URL 环境变量配置正确。
2. 确认你已经运行过 run_queue，并且队列已经处理完成。可以调用 list_sources 查看是否有已索引的源。
3. 检查你的查询词是否与文档中的语言匹配。向量搜索对语义相近的查询有效，但精准关键词匹配可能不佳。

问题3：处理队列时，某些 URL 失败了（如超时或 404）。

解决方案：run_queue 工具具有重试和错误处理机制。失败的 URL 通常会保留在队列中？错误信息会输出到 Claude 的响应中。你可以查看具体错误。如果是网络问题，可以稍后再次运行 run_queue。如果某个 URL 永久失效，可以用 remove_documentation 移除。

问题4：我想使用 OpenAI 的嵌入模型而不是本地的 Ollama。

解决方案：在配置文件中，将 EMBEDDINGS_PROVIDER 改为 "openai"，并添加 OPENAI_API_KEY 环境变量。同时，你需要移除 OLLAMA_BASE_URL。注意，使用 OpenAI 会产生 API 费用。

问题5：Playwright 容器无法启动或连接。

解决方案：在 docker-compose.yml 中，Playwright 服务命名为 playwright。你需要单独启动它：docker compose up playwright。然后在服务器配置中添加 PLAYWRIGHT_WS_ENDPOINT: "ws://localhost:3000"。如果不需要抓取复杂的 JavaScript 页面，你可以不启动它，服务器会自动回退到本地 HTTP 抓取（适用于静态站点）。

七、总结

mcp-server-ragdocs 是一个完整的、生产级的 RAG 解决方案，以 MCP 服务器的形式呈现。它解决了“让 AI 访问特定文档库”这一核心问题，并且提供了从文档发现、清理、索引到检索的全套工具。

该项目的亮点包括：

• 完整性：涵盖了 RAG 的整个生命周期，而不只是检索。
• 灵活性：支持本地免费部署（Ollama + Qdrant）和云端生产部署。
• 可观测性：提供了队列管理、源列表等工具，让你清楚系统状态。
• 活跃维护：项目有 1.3.0 版本，且发布了 npm 包，持续更新。

28 颗星或许还不算多，但考虑到其功能的深度和广度，这个项目的价值远超其星数所体现的。对于任何一个希望将 AI 助手与内部知识库深度结合的组织或个人开发者来说，mcp-server-ragdocs 都是一个值得深入研究和部署的基石工具。