Mcp Server Ragdocs

MCP-server-ragdocs

一个 MCP 服务实现，提供通过向量搜索检索和处理文档的工具，使 AI 助手能够利用相关文档上下文增强回复。

目录

• 用法
• 功能
• 配置
• 部署
  • 本地开发
  • 云部署
• Playwright 集成
• 工具
• 项目结构
• 使用 Ollama 嵌入
• 许可证
• 开发工作流
• 贡献
• Forkception 致谢

用法

RAG Documentation 工具适用于：

• 使用相关文档增强 AI 回复
• 构建能够理解文档的 AI 助手
• 为开发者创建上下文感知工具
• 实现语义文档搜索
• 增强现有知识库

功能

• 基于向量的文档搜索和检索
• 支持多个文档来源
• 支持本地（Ollama）生成嵌入或使用 OPENAI
• 语义搜索功能
• 自动处理文档
• 为 LLM 提供实时上下文增强

配置

{
  "mcpServers": {
    "rag-docs": {
      "command": "npx",
      "args": ["-y", "@sanderkooger/mcp-server-ragdocs"],
      "env": {
        "EMBEDDINGS_PROVIDER": "ollama",
        "QDRANT_URL": "your-qdrant-url",
        "QDRANT_API_KEY": "your-qdrant-key" # if applicable
      }
    }
  }
}

在 Claude Desktop 中使用

将以下内容添加到 claude_desktop_config.json：

OpenAI 配置

{
  "mcpServers": {
    "rag-docs-openai": {
      "command": "npx",
      "args": ["-y", "@sanderkooger/mcp-server-ragdocs"],
      "env": {
        "EMBEDDINGS_PROVIDER": "openai",
        "OPENAI_API_KEY": "your-openai-key-here",
        "QDRANT_URL": "your-qdrant-url",
        "QDRANT_API_KEY": "your-qdrant-key"
      }
    }
  }
}

Ollama 配置

{
  "mcpServers": {
    "rag-docs-ollama": {
      "command": "npx",
      "args": ["-y", "@sanderkooger/mcp-server-ragdocs"],
      "env": {
        "EMBEDDINGS_PROVIDER": "ollama",
        "OLLAMA_BASE_URL": "http://localhost:11434",
        "QDRANT_URL": "your-qdrant-url",
        "QDRANT_API_KEY": "your-qdrant-key"
      }
    }
  }
}

从此代码库运行 Ollama

"ragdocs-mcp": {
      "command": "node",
      "args": [
        "/home/sander/code/mcp-server-ragdocs/build/index.js"
      ],
      "env": {
        "QDRANT_URL": "http://127.0.0.1:6333",
        "EMBEDDINGS_PROVIDER": "ollama",
        "OLLAMA_URL": "http://localhost:11434"
      },
      "alwaysAllow": [
        "run_queue",
        "list_queue",
        "list_sources",
        "search_documentation",
        "clear_queue",
        "remove_documentation",
        "extract_urls"
      ],
      "timeout": 3600
    }

环境变量参考

变量	适用范围	默认值	备注
EMBEDDINGS_PROVIDER	全部	ollama	"openai" 或 "ollama"
OPENAI_API_KEY	OpenAI	-	从 OpenAI 控制台获取
OLLAMA_BASE_URL	Ollama	http://localhost:11434	本地 Ollama 服务 URL
QDRANT_URL	全部	http://localhost:6333	Qdrant 端点 URL
QDRANT_API_KEY	云端 Qdrant	-	从 Qdrant Cloud 控制台获取
PLAYWRIGHT_WS_ENDPOINT	远程 Playwright	-	远程 Playwright 服务的 WebSocket 端点（例如，ws://localhost:3000/）

本地部署

仓库包含用于本地开发的 Docker Compose 配置：

下载 Docker Compose

docker compose up -d

这将启动：

• 运行在端口 6333 上的 Qdrant 向量数据库
• 运行在端口 11434 上的 Ollama 大模型服务

访问端点：

• Qdrant：http://localhost:6333
• Ollama：http://localhost:11434

云部署

用于生产环境部署：

1. 使用托管的 Qdrant Cloud 服务
2. 设置以下环境变量：

QDRANT_URL=your-cloud-cluster-url
QDRANT_API_KEY=your-cloud-api-key

Playwright 集成

此项目支持在本地或通过 Docker 容器运行 Playwright。这为 Playwright 依赖项难以直接安装的环境提供了灵活性。

工作原理

src/api-client.ts 文件会自动检测是否存在 PLAYWRIGHT_WS_ENDPOINT 环境变量：

• 如果已设置 PLAYWRIGHT_WS_ENDPOINT：应用将使用 chromium.connect() 尝试连接到指定 WebSocket 端点上的远程 Playwright 服务。这非常适合使用容器化的 Playwright 实例。
• 如果未设置 PLAYWRIGHT_WS_ENDPOINT：应用将使用 chromium.launch() 启动本地 Playwright 浏览器实例。

在 Docker 中运行 Playwright

docker-compose.yml 文件中已添加 playwright 服务，以便在 Docker 容器中运行 Playwright。

要在 Docker 中启动 Playwright 服务：

docker-compose up playwright

此命令将拉取 mcr.microsoft.com/playwright:v1.53.0-noble 镜像，并启动一个 Playwright 服务，可通过主机的 3000 端口访问。

要将应用配置为使用此容器化的 Playwright 实例，请设置以下环境变量：

PLAYWRIGHT_WS_ENDPOINT=ws://localhost:3000/

工具

search_documentation

使用自然语言查询搜索已存储的文档。返回带上下文的匹配摘录，并按相关性排序。

输入：

• query（字符串）：要在文档中搜索的文本。可以是自然语言查询、特定术语或代码片段。
• limit（数字，可选）：返回结果的最大数量（1-20，默认值：5）。较高的上限会提供更全面的结果，但可能需要更长的处理时间。

list_sources

列出系统中当前存储的所有文档来源。返回所有已编入索引的文档的完整列表，包括来源 URL、标题和最后更新时间。可用于了解有哪些文档可供搜索，或确认特定来源是否已编入索引。

extract_urls

从给定网页中提取并分析所有 URL。此工具会抓取指定网页，识别其中的所有超链接，并可选择将其添加到处理队列。

输入：

• url（字符串）：要分析的网页完整 URL（必须包含协议，例如 https://）。该网页必须可公开访问。
• add_to_queue（布尔值，可选）：如果为 true，则自动将提取出的 URL 添加到处理队列，以便稍后编入索引。在大型网站上使用时请谨慎，以免队列中加入过多内容。

remove_documentation

通过 URL 从系统中移除特定文档来源。此操作不可撤销，并会影响后续搜索结果。

输入：

• urls（字符串数组）：要从数据库中移除的 URL 数组。每个 URL 必须与添加文档时使用的 URL 完全一致。

list_queue

列出当前在文档处理队列中等待的所有 URL。显示待处理的文档来源，这些来源将在调用 run_queue 时处理。可用于监控队列状态、确认 URL 是否已正确添加，或查看处理积压情况。

run_queue

处理并索引文档队列中的所有 URL。每个 URL 都会按顺序处理，并具备适当的错误处理和重试逻辑。处理期间会提供进度更新。长时间运行的操作会持续处理，直到队列清空或发生无法恢复的错误。

clear_queue

从文档处理队列中移除所有待处理的 URL。可用于重置队列、移除不需要的 URL，或取消待处理的任务。此操作立即生效且不可撤销；如果之后还要处理这些 URL，则需要重新添加。

项目结构

此软件包采用模块化架构，清晰分离核心组件和 MCP 协议处理程序。有关结构和设计决策的详细说明，请参阅 ARCHITECTURE.md。

不使用 docker 的情况下使用 Ollama Embeddings

1. 安装 Ollama：

curl -fsSL https://ollama.com/install.sh | sh

2. 下载 nomic-embed-text 模型：

ollama pull nomic-embed-text

3. 验证安装：

ollama list

许可证

此 MCP 服务采用 MIT 许可证授权。这意味着您可以自由使用、修改和分发该软件，但须遵守 MIT 许可证的条款和条件。更多详情请参阅项目仓库中的 LICENSE 文件。

贡献

欢迎贡献！详细指南请参阅 CONTRIBUTING.md，以下是基本步骤：

1. Fork 此仓库
2. 安装依赖：npm install
3. 创建功能分支：git checkout -b feat/your-feature
4. 使用 npm run commit 提交更改，以确保符合 Conventional Commits 规范
5. 推送到您的 fork 并创建 PR

Forkception 致谢

此项目基于 hannesrudolph/mcp-ragdocs 的 fork，而该项目本身是从 qpd-v/mcp-ragdocs 的原始作品 fork 而来。原始项目为此实现提供了基础。