星战科技xingzhan.cloud
返回市场
mcp服务器-检索增强文档服务

mcp服务器-检索增强文档服务

作者：sanderkooger24 星标更新：2025-10-22
安装使用来源：spider==github.com

项目介绍

MCP-server-ragdocs

Node.js 包 NPM 下载量 版本 代码覆盖率 MIT 许可证

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

目录

使用

RAG 文档工具旨在：

  • 通过相关文档增强AI响应
  • 构建具有文档意识的AI助手
  • 创建面向开发者的上下文感知工具
  • 实现语义文档搜索
  • 增强现有的知识库

特性

  • 基于向量的文档搜索和检索
  • 支持多个文档来源
  • 支持本地（Ollama）嵌入生成或OPENAI
  • 语义搜索能力
  • 自动化文档处理
  • 对LLMs实时上下文增强

配置

{
  "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" # 如适用
      }
    }
  }
}

与 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_KEYOpenAI-从 OpenAI 控制台获取
OLLAMA_BASE_URLOllamahttp://localhost:11434本地 Ollama 服务 URL
QDRANT_URL所有http://localhost:6333Qdrant 终端 URL
QDRANT_API_KEY云 Qdrant-从 Qdrant Cloud 控制台获取
PLAYWRIGHT_WS_ENDPOINTPlaywright 远程-远程 Playwright 服务器的 WebSocket 终点（例如，ws://localhost:3000/）

本地部署

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

Docker Compose 下载

docker compose up -d

这将启动：

  • 在 6333 端口上的 Qdrant 向量数据库
  • 在 11434 端口上的 Ollama LLM 服务

访问终端：

云部署

对于生产部署：

  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：应用程序将尝试连接到指定 WebSocket 终点的远程 Playwright 服务器，使用 chromium.connect()。这对于使用容器化的 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 镜像，并在主机机器的 3000 端口上启动一个 Playwright 服务器。

要配置您的应用程序使用此容器化的 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 (布尔值，可选)：如果为真，则自动将提取的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 中的结构文档和设计决策。

使用 Ollama 嵌入而无需 Docker

  1. 安装 Ollama：
curl -fsSL https://ollama.com/install.sh | sh
  1. 下载 nomic-embed-text 模型：
ollama pull nomic-embed-text
  1. 验证安装：
ollama list

许可证

此MCP服务器在MIT许可证下发布。这意味着您可以自由地使用、修改和分发软件，但需遵守MIT许可证的条款和条件。更多详细信息，请参见项目存储库中的LICENSE文件。

贡献

我们欢迎贡献！请参阅我们的 CONTRIBUTING.md 获取详细的指南，但这里是一些基本步骤：

  1. 分叉仓库
  2. 安装依赖项：npm install
  3. 创建一个功能分支：git checkout -b feat/your-feature
  4. 使用 npm run commit 提交更改，确保符合 常规提交
  5. 推送到您的分叉并打开PR

分叉致谢

该项目基于 hannesrudolph/mcp-ragdocs 的分叉，而后者又基于 qpd-v/mcp-ragdocs 的原始工作。原始项目为此实现提供了基础。