mcp-docs-rag MCP 服务器

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

这是一个基于TypeScript的MCP服务器，实现了针对存储在本地目录中的文档的RAG系统。它允许用户通过LLMs使用本地存储库和文本文件中的上下文查询文档。

功能

资源

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

工具

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

   您可以访问哪些文档？
   

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