MCP RAG 服务器

<!-- Badges -->

<!-- --> <!-- TODO: 设置完成后添加覆盖率徽章 -->

mcp-rag-server 是一个 模型上下文协议 (MCP) 服务器，它为连接的 LLM 启用检索增强生成 (RAG) 功能。它索引您项目中的文档，并提供相关的上下文来增强 LLM 的响应。

使用 Google Genkit、ChromaDB 和 Ollama 构建。

快速开始

（在此处提供一个最小的可运行示例，假设 Docker 设置已完成）

# 示例：通过 MCP 客户端查询（概念性的）
# （实际用法取决于客户端的实现）

为什么选择这个项目？

• 无缝 MCP 集成： 专为模型上下文协议生态系统设计。
• 本地控制： 利用本地模型 (Ollama) 和向量存储 (ChromaDB) 来实现隐私和定制。
• 自动上下文： 自动索引您的项目文件，为 LLM 提供相关的上下文。
• 可扩展： 使用 Genkit 构建，允许潜在的未来扩展和集成。

特性

• 自动索引： 在启动时扫描项目目录（可配置）并索引支持的文件。
• 支持的文件类型： .txt、.md、代码文件（通过通用拆分）、.json、.jsonl、.csv。（代码文件分块是基本的）。
• 分层分块： 智能地对 Markdown 文件进行分块，分离文本和代码块。
• 向量存储： 使用 ChromaDB 进行持久向量存储。
• 本地嵌入： 利用 Ollama 进行本地嵌入生成（默认：nomic-embed-text）。
• MCP 工具： 将 RAG 函数公开为标准 MCP 工具：
  • indexDocuments：手动索引文件或目录。
  • queryDocuments：检索查询的相关文档块。
  • removeDocument：按源路径删除特定文档的块。
  • removeAllDocuments：清除当前项目的整个索引。
  • listDocuments：列出已索引的文档源路径。
• Docker 化： 包含一个 docker-compose.yml，方便设置服务器、ChromaDB 和 Ollama。

设计理念

• 简单性： 旨在提供直接的设置和使用体验，尤其是在使用 Docker Compose 时。
• 模块化： 利用 Genkit 流来组织 RAG 逻辑。
• 本地优先： 优先使用 Ollama 和 ChromaDB 等本地工具来实现核心功能。

安装和使用（Docker Compose - 推荐）

此方法在隔离的容器中运行服务器及其依赖项（ChromaDB、Ollama）。

1. 先决条件：

   • 安装 Docker Desktop 或 Docker Engine。
   • 确保主机上的端口 8000 (ChromaDB) 和 11434 (Ollama) 空闲，或者在 docker-compose.yml 中调整端口。

2. 克隆存储库：

   git clone https://github.com/sylphlab/rag-server-mcp.git
   cd mcp-rag-server
   

3. 启动服务：

   docker-compose up -d --build
   

   • 这会构建服务器镜像，下载 ChromaDB 和 Ollama 镜像，并启动服务。
   • 首次运行可能需要一些时间来下载镜像和构建。

4. 拉取嵌入模型（首次运行）： 默认的嵌入模型 (nomic-embed-text) 需要在 Ollama 容器启动_后_拉取到其中。

   docker exec ollama ollama pull nomic-embed-text
   

   • 在运行此命令之前，请在 docker-compose up 之后等待片刻。您只需要执行一次此操作，因为该模型将持久保存在 Docker 卷中。

5. 与 MCP 客户端集成： 配置您的 MCP 客户端（例如，在 VS Code 设置或其他 MCP 服务器中）以连接到此服务器。由于它通过 Docker Compose 运行，因此通常不会直接在客户端配置中使用 npx 运行它。相反，客户端需要知道如何与正在运行的服务器通信（在这种设置中，默认情况下不会直接公开服务器，通常通过其他方式进行通信，例如，如果服务器公开了 HTTP 接口，则通过直接 API 调用，或者如果适用，则通过共享卷/数据库）。

   注意： 当前设置主要通过 Genkit 流促进 此项目内 或可能同一 Docker 网络内的其他服务的 RAG。从外部主机直接进行 MCP 客户端集成需要从 Docker 容器公开服务器的 MCP 端口。

配置（环境变量）

通过环境变量配置服务器，通常在 docker-compose.yml 文件中为 rag-server 服务设置：

• CHROMA_URL: ChromaDB 服务的 URL。（Compose 中的默认值：http://chromadb:8000）
• OLLAMA_HOST: Ollama 服务的 URL。（Compose 中的默认值：http://ollama:11434）
• INDEX_PROJECT_ON_STARTUP: 设置为 true（默认）或 false 以启用/禁用服务器启动时的自动索引。
• INDEXING_EXCLUDE_PATTERNS: 以逗号分隔的 glob 模式列表，用于从索引中排除（例如，**/node_modules/**,**/.git/**）。默认值在 autoIndexer.ts 中定义。
• GENKIT_ENV: 设置为 production 或 development（影响日志记录等）。
• LOG_LEVEL: 设置日志级别（例如，debug、info、warn、error）。

(有关更多详细信息，请参见 docker-compose.yml 和 src/config/genkit.ts)

性能

（性能基准测试尚未提供。）

与其他解决方案的比较

（与其他 RAG 解决方案的比较将在稍后添加。）

未来计划

• 改进代码文件分块策略。
• 增加对更多文件类型（例如，PDF）的支持。
• 增强查询的过滤功能。
• 调查并解决 E2E 测试失败。
• 添加更强大的错误处理。

开发

1. 先决条件： Node.js (LTS), npm。
2. 安装依赖项： npm install
3. 构建： npm run build
4. 运行 Linters/Formatters：
   • npm run lint
   • npm run format
   • npm run validate（运行格式检查、lint、类型检查、测试）
5. 运行测试：
   • npm test（运行单元测试）
   • npm run test:cov（运行带有覆盖率的单元测试）
   • E2E 测试： 需要运行 Docker Compose 环境 (docker-compose up -d)。通过 Vitest 命令运行特定的 E2E 测试，或者可能集成到 npm test 中。 (注意：由于外部服务交互问题，E2E 测试当前失败)。
6. 在本地运行服务器（不使用 Docker）：
   • 确保 ChromaDB 和 Ollama 正在运行且可访问（例如，本地安装或单独的 Docker 容器）。
   • 设置环境变量 (CHROMA_URL, OLLAMA_HOST)。
   • npm start

文档

完整文档可在 [TODO: 添加到已部署的 VitePress 站点的链接] 中找到。

贡献

欢迎贡献！请在提交拉取请求之前打开一个 issue 来讨论更改。遵循编码标准和提交约定。

许可证

此项目已获得 MIT 许可证 的许可。