MCP-server-ragdocs

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

目录

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

用法

RAG 文档工具专为以下目的而设计：

• 使用相关文档增强 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 控制台

本地部署

该存储库包含用于本地开发的 Docker Compose 配置：

Docker Compose 下载

docker compose up -d

这将启动：

• Qdrant 向量数据库，端口 6333
• Ollama LLM 服务，端口 11434

访问端点：

• 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

工具

search_documentation

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

输入：

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

list_sources

列出当前存储在系统中的所有文档源。返回所有索引文档的完整列表，包括源 URL、标题和上次更新时间。使用此选项可以了解哪些文档可用于搜索，或验证是否已索引特定源。

extract_urls

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

输入：

• url (string)：要分析的网页的完整 URL（必须包括协议，例如 https://）。该页面必须可公开访问。
• add_to_queue (boolean, optional)：如果为 true，则自动将提取的 URL 添加到处理队列以供以后索引。在大型站点上使用时要小心，以避免过度排队。

remove_documentation

按 URL 从系统中删除特定的文档源。删除是永久性的，会影响未来的搜索结果。

输入：

• urls (string[])：要从数据库中删除的 URL 数组。每个 URL 必须与添加文档时使用的 URL 完全匹配。

list_queue

列出当前在文档处理队列中等待的所有 URL。显示在调用 run_queue 时将处理的待处理文档源。使用此选项可以监视队列状态、验证 URL 是否已正确添加或检查处理积压。

run_queue

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

clear_queue

从文档处理队列中删除所有待处理的 URL。当您想要重新开始、删除不需要的 URL 或取消待处理的处理时，可以使用此选项来重置队列。此操作是立即且永久的 - 如果您想稍后处理 URL，则需要重新添加它们。

项目结构

该软件包遵循模块化架构，核心组件和 MCP 协议处理程序之间有明确的分隔。有关详细的结构文档和设计决策，请参见 ARCHITECTURE.md。

使用没有 docker 的 Ollama 嵌入

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 而来的。原始项目为该实现提供了基础。