mcp-docs-rag MCP 服务器

用于本地目录中文档的 RAG（检索增强生成）

这是一个基于 TypeScript 的 MCP 服务器，实现了针对存储在本地目录中的文档的 RAG 系统。它允许用户使用 LLM 并结合本地存储的仓库和文本文件的内容来查询文档。

功能

资源

• 通过 docs:// URI 列出和访问文档
• 文档可以是 Git 仓库或文本文件
• 内容访问的纯文本 MIME 类型

工具

• list_documents - 列出 DOCS_PATH 目录中所有可用的文档
  • 返回所有文档的格式化列表
  • 显示可用文档的总数
• rag_query - 使用 RAG 查询文档
  • 接受 document_id 和 query 作为参数
  • 返回带有文档上下文的 AI 生成的响应
• add_git_repository - 将 Git 仓库克隆到文档目录，并可选择稀疏检出
  • 接受 repository_url 作为参数
  • 可选的 document_name 参数来自定义文档名称（使用简单的描述性名称，不要有 '-docs' 后缀）
  • 可选的 subdirectory 参数用于特定目录的稀疏检出
  • 如果仓库已经存在，则自动拉取最新更改
• add_text_file - 将文本文件下载到文档目录
  • 接受 file_url 作为参数
  • 使用 wget 下载文件

提示

• guide_documents_usage - 关于如何使用文档和 RAG 功能的指南
  • 包括可用文档列表
  • 提供 RAG 功能的使用提示

开发

安装依赖项：

npm install

构建服务器：

npm run build

开发时启用自动重建：

npm run watch

设置

该服务器需要一个本地目录来存储文档。默认情况下，它使用 ~/docs，但你可以通过 DOCS_PATH 环境变量配置不同的位置。

文档结构

文档目录可以包含：

• Git 仓库（克隆的目录）
• 纯文本文件（扩展名为 .txt）

每个文档都使用 llama-index.ts 和 Google 的 Gemini 嵌入单独索引。

API 密钥

该服务器使用 Google 的 Gemini API 进行文档索引和查询。你需要将你的 Gemini API 密钥设置为环境变量：

export GEMINI_API_KEY=your-api-key-here

你可以从 Google AI Studio 网站获取 Gemini API 密钥。将其添加到你的 shell 配置文件中，或在 Claude Desktop 的环境配置中包含它。

安装

要与 Claude Desktop 一起使用，请添加服务器配置：

在 MacOS 上：~/Library/Application Support/Claude/claude_desktop_config.json
在 Windows 上：%APPDATA%/Claude/claude_desktop_config.json
在 Linux 上：~/.config/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "docs-rag": {
      "command": "npx",
      "args": ["-y", "@kazuph/mcp-docs-rag"],
      "env": {
        "DOCS_PATH": "/Users/username/docs",
        "GEMINI_API_KEY": "your-api-key-here"
      }
    }
  }
}

请确保将 /Users/username/docs 替换为你实际的文档目录路径。

调试

由于 MCP 服务器通过 stdio 通信，调试可能会比较困难。我们建议使用 MCP Inspector，它作为一个包脚本提供：

npm run inspector

Inspector 将提供一个 URL 以在您的浏览器中访问调试工具。

使用方法

配置完成后，您可以使用带有 Claude 的服务器来执行以下操作：

1. 添加文档：

   从 GitHub 添加一个新的文档：https://github.com/username/repository
   

   或者使用自定义的文档名称：

   添加 GitHub 仓库 https://github.com/username/repository-name 并将其命名为 'framework'
   

   或者仅签出特定目录：

   仅从 https://github.com/username/repository 中添加 'src/components' 目录
   

   或者结合自定义名称和稀疏签出：

   从 https://github.com/username/large-repo 中添加 'examples/demo' 目录并将其命名为 'demo-app'
   

   或者添加一个文本文件：

   添加此文本文件：https://example.com/document.txt
   

2. 查询文档：

   Y 仓库中的文档关于 X 说了什么？
   

3. 列出可用文档：

   您可以访问哪些文档？
   

服务器将自动处理文档索引以便高效检索。