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 存储库克隆到 docs 目录，并可选择稀疏检出
  • 接受 repository_url 作为参数
  • 可选的 document_name 参数，用于自定义文档的名称（使用简单的描述性名称，不带 '-docs' 后缀）
  • 可选的 subdirectory 参数，用于稀疏检出特定目录
  • 如果存储库已存在，则自动拉取最新更改
• add_text_file - 将文本文件下载到 docs 目录
  • 接受 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. 列出可用文档：

   您有权访问哪些文档？
   

服务器将自动处理文档的索引，以实现高效检索。