voitta-rag MCP 服务端

使用说明（Markdown 格式）

• 项目简介

  • voitta-rag 附带的 MCP 服务端实现，融合了资源管理、工具集、以及对话模板等能力，旨在为大语言模型客户端提供可扩展的上下文与外部功能调用能力。

• 主要功能点

  • MCP 服务端核心能力：提供工具集供 LLM 调用（如搜索、获取文件、获取块区间、文件下载 URI、文件/文件夹元数据与设置等）。
  • 资源与数据访问：通过向量存储、嵌入服务、以及文件系统服务，向 LLM 客户端暴露索引后的内容与元数据。
  • 安全上下文与会话：通过 X-User-Name 头部实现会话作用域内的权限和上下文分离，支持多用户场景。
  • 多种传输与集成：在同一 FastAPI 应用中暴露 MCP 接口并挂载在 /mcp 路径，支持与 Claude Code 等 MCP 客户端对接；内部实现了向量检索、BM25 複合检索、以及文件/目录的元数据和同步状态。

• 安装步骤

  • 直接在本地/服务器部署应用（Python 3.11+），并按照仓库提供的 Quick Start 进行搭建（Docker-Compose 方案为首选，可一并启动 VOITTA 组件及 Qdrant）。也可在本地开发环境中直接运行 FastAPI 应用。
  • 环境与依赖配置通常通过 .env 和 settings 模块完成，确保数据库、Qdrant、以及嵌入模型等服务可用。

• 服务器配置（MCP 客户端所需的连接信息，JSON 格式；不包含客户端代码） { "server_name": "voitta-rag", "command": "uvicorn", "args": [ "voitta.main:app", "--host", "0.0.0.0", "--port", "8000" ], "notes": "该命令启动整合在同一 FastAPI 应用中的 MCP 服务端，MCP 的端点在 /mcp 路径下，通过 /mcp/mcp 提供 JSON-RPC 服务。若在 Docker 场景，端口按实际映射调整。" }

• 基本使用方法

  • 运行后，MCP 客户端应指向服务器暴露的 MCP 入口；客户端配置需指向 http(s)://<host>:<port>/mcp/mcp。
  • 客户端通过 JSON-RPC 请求调用 voitta-rag 提供的工具，如搜索、获取文件、获取区间文本、以及文件下载 URI 等，以获取上下文信息与外部功能。
  • 如需多用户场景，请在请求中传递 X-User-Name 头以标识当前用户，服务器据此过滤和管理用户级的可见性与设置。

• 备注

  • MCP 服务端在同一应用内暴露，结合了资源管理、向量检索、以及嵌入模型等能力，确保向 LLM 客户端提供可扩展的上下文服务框架。