Ragdoc MCP 服务器

关键词

Contextualized embeddings语义检索ChromaDBVoyage AICohere

使用说明（Markdown 格式）

一、项目简介

  • Ragdoc MCP 服务器基于 MCP 协议实现，为 LLM 客户端（如 Claude Desktop、VS Code Copilot 等）提供统一的上下文服务。核心功能包括托管和管理知识资源、注册和执行工具、定义与渲染 Prompt 模板，并通过 JSON-RPC 进行远程调用。服务器支持多种传输模式（标准输入输出、HTTP/SSE，及后续扩展），并具备会话管理与能力声明能力。

二、主要功能点

  • MCP 服务端实现

    • 处理来自客户端的资源读取与管理请求，提供对知识库中文档、分块等资源的访问能力
    • 提供工具注册与执行，允许 LLM 调用服务器端功能（如检索、文档读取、上下文获取等）
    • 定义与渲染 Prompt 模板，支持可定制化的对话/交互流程
    • 会话管理、能力声明与权限控制（基于 MCP 标准）
    • 支持多传输协议（stdio、HTTP/SSE 等），便于本地开发、单机会话以及多会话并行使用

  • 与 Ragdoc 生态耦合

    • 集成 Contextualized Embeddings 与 BM25 混合检索、ChromaDB 向量数据库和 Cohere 重新排序
    • 提供对 Voyage AI、Cohere 等外部服务的可选整合
    • 结合现有 Ragdoc 的文档、索引和数据管线，提升 LLM 的上下文能力

三、安装步骤

  • 先决条件

    • Python 3.8+（仓库中示例使用 3.x 版本及虚拟环境）
    • 需要的外部服务或 API Key（Voyage AI Embeddings、Cohere、MinerU 等，按需要开启）
    • 依赖示例：fastmcp、chromadb、voyageai、cohere、BM25 相关包等

  • 安装与部署

    1. 克隆仓库并进入项目目录
    2. 创建并激活虚拟环境
    3. 安装依赖（pip install -r 需要的依赖文件）
    4. 根据需要配置环境变量，包含 VOYAGE_API_KEY、COHERE_API_KEY、VOYAGE_TOKEN 等
    5. 启动 MCP 服务器（标准模式）
      • 命令示例（标准模式，STDIO 传输）：python src/server.py
      • 启动完成后，服务器会在指定端口通过 JSON-RPC 与客户端通信

  • 服务器的两种运行模式

    • STDIO 传输（默认，直接在终端/脚本中以标准输入输出进行 JSON-RPC 通信）
    • HTTP/SSE 传输（通过 Python 调用 server_http.py，提供一个共享 HTTP 服务，便于多会话使用）

  • 常用运维

    • 通过提供的工具接口（如 ragdoc-menu.py、ragdoc-cli.py 等）对数据进行索引、监控、状态查询等
    • 结合 Claude Desktop / Copilot 进行 MCP 客户端的远程调用

四、服务器配置（MCP 客户端所需信息） 以下信息用于 MCP 客户端在配置文件中建立与 Ragdoc MCP 服务器的连接。请将其放入客户端的 MCP 配置中，无需在客户端代码中实现。

{ "server_name": "ragdoc-contextualized", "command": "python", "args": ["src/server.py"], "cwd": "/path/to/Ragdoc", "description": "Ragdoc MCP 服务器，Contextualized 模式，提供资源、工具与 Prompt 的标准化访问", "transport": "stdio（默认）/ http-sse（通过 server_http.py 提供的 HTTP/SSE 服务）" }

可选的 HTTP/SSE 客户端配置（用于 Claude/其他支持 SSE 的客户端） { "server_name": "ragdoc-contextualized-http", "type": "sse", "url": "http://127.0.0.1:8321/mcp" }

五、基本使用方法

  • 启动方式
    • 直接在本地运行：python src/server.py（stdio 模式，适合开发与调试）
    • 作为 HTTP/SSE 服务：python src/server_http.py（适合多会话并发与多客户端接入）
  • 客户端接入
    • 使用 Claude Desktop、VS Code Copilot 等工具时，在 MCP 客户端设置中指定服务器的启动命令与参数（如上文 JSON 配置所示），以及连接方式（stdio 或 SSE/http）。
    • 启动后，客户端即可通过 MCP 的 JSON-RPC 调用来读取资源、执行工具、获取 Prompt 模板等。
  • 常用操作
    • 通过客户端调用 Ragdoc 提供的工具，例如语义检索、文档读取、获取片段上下文等
    • 观察返回的 JSON-RPC 响应，并结合 Ragdoc 的数据管线进行后续处理

六、注意事项与兼容性

  • Ragdoc 的 MCP 服务是面向 LLM 客户端的后端服务，核心在于提供标准化上下文及能力。请确保环境变量和外部服务 API Key 配置正确，否则检索、嵌入与重新排序等功能可能受限。
  • MCP 服务可能需要较大的内存与网络带宽，尤其在进行 Contextualized Embeddings 与大规模向量检索时，请据实际部署容量配置硬件与并发策略。

七、运行和维护参考

  • 参考 Ragdoc 的 README 与示例配置，结合 Claude Desktop / Copilot 的 MCP 集成文档，完成服务器启动与客户端配置。
  • Ragdoc 提供了多种工具和脚本，用于索引、监控、诊断与评测等，方便日常维护与性能调优。

关键词 Contextualized embeddings, 语义检索, ChromaDB, Voyage AI, Cohere

分类ID 6

服务器信息

访问项目