RAG 文档 MCP 服务器

这是一个 MCP 服务器实现，提供了通过向量搜索检索和处理文档的工具，使 AI 助手能够在其响应中添加相关的文档上下文。

目录

• 功能
• 快速开始
• Docker Compose 设置
• Web 界面
• 配置
  • Cline 配置
  • Claude 桌面配置
• 致谢
• 故障排除

功能

工具

1. search_documentation

   • 使用向量搜索浏览文档
   • 返回带有来源信息的相关文档片段

2. list_sources

   • 列出所有可用的文档来源
   • 提供每个来源的元数据

3. extract_urls

   • 从文本中提取 URL 并检查它们是否已经在文档中
   • 有助于防止重复文档

4. remove_documentation

   • 从特定来源移除文档
   • 清理过时或不相关的文档

5. list_queue

   • 列出处理队列中的所有项目
   • 显示待处理文档的状态

6. run_queue

   • 处理队列中的所有项目
   • 自动将新文档添加到向量存储中

7. clear_queue

   • 清空处理队列中的所有项目
   • 有助于重置系统

8. add_documentation

   • 将新文档添加到处理队列
   • 支持多种格式和来源

快速开始

RAG 文档工具设计用于：

• 通过相关文档增强 AI 响应
• 构建了解文档的 AI 助手
• 为开发人员创建上下文感知的工具
• 实现语义文档搜索
• 扩展现有知识库

Docker Compose 设置

该项目包含一个 docker-compose.yml 文件，以便于容器化部署。要启动服务：

docker-compose up -d

要停止服务：

docker-compose down

Web 界面

该系统包括一个在启动 Docker Compose 服务后可访问的 Web 界面：

1. 打开浏览器并导航至：http://localhost:3030
2. 该界面提供：
   • 实时队列监控
   • 文档来源管理
   • 用于测试查询的搜索界面
   • 系统状态和健康检查

配置

Embeddings 配置

系统默认使用 Ollama 作为本地嵌入生成的嵌入提供商，OpenAI 作为备用选项。这种设置优先考虑本地处理，同时通过基于云的备用选项保持可靠性。

环境变量

• EMBEDDING_PROVIDER: 选择主要的嵌入提供者（'ollama' 或 'openai'，默认：'ollama'）
• EMBEDDING_MODEL: 指定要使用的模型（可选）
  • 对于 OpenAI：默认为 'text-embedding-3-small'
  • 对于 Ollama：默认为 'nomic-embed-text'
• OPENAI_API_KEY: 当使用 OpenAI 作为提供者时必需
• FALLBACK_PROVIDER: 备用提供者（可选）（'ollama' 或 'openai'）
• FALLBACK_MODEL: 备用提供者的模型（可选）

Cline 配置

将以下内容添加到您的 cline_mcp_settings.json 中：

{
  "mcpServers": {
    "rag-docs": {
      "command": "node",
      "args": ["/path/to/your/mcp-ragdocs/build/index.js"],
      "env": {
        "EMBEDDING_PROVIDER": "ollama", // default
        "EMBEDDING_MODEL": "nomic-embed-text", // optional
        "OPENAI_API_KEY": "your-api-key-here", // required for fallback
        "FALLBACK_PROVIDER": "openai", // recommended for reliability
        "FALLBACK_MODEL": "nomic-embed-text", // optional
        "QDRANT_URL": "http://localhost:6333"
      },
      "disabled": false,
      "autoApprove": [
        "search_documentation",
        "list_sources",
        "extract_urls",
        "remove_documentation",
        "list_queue",
        "run_queue",
        "clear_queue",
        "add_documentation"
      ]
    }
  }
}

Claude 桌面配置

将以下内容添加到您的 claude_desktop_config.json 中：

{
  "mcpServers": {
    "rag-docs": {
      "command": "node",
      "args": ["/path/to/your/mcp-ragdocs/build/index.js"],
      "env": {
        "EMBEDDING_PROVIDER": "ollama", // default
        "EMBEDDING_MODEL": "nomic-embed-text", // optional
        "OPENAI_API_KEY": "your-api-key-here", // required for fallback
        "FALLBACK_PROVIDER": "openai", // recommended for reliability
        "FALLBACK_MODEL": "nomic-embed-text", // optional
        "QDRANT_URL": "http://localhost:6333"
      }
    }
  }
}

默认配置

系统默认使用 Ollama 进行高效的本地嵌入生成。为了获得最佳可靠性：

1. 安装并运行 Ollama 本地版本
2. 将 OpenAI 配置为备用（推荐）：

   {
     // 默认使用 Ollama，无需指定 EMBEDDING_PROVIDER
     "EMBEDDING_MODEL": "nomic-embed-text", // 可选
     "FALLBACK_PROVIDER": "openai",
     "FALLBACK_MODEL": "text-embedding-3-small",
     "OPENAI_API_KEY": "your-api-key-here"
   }
   

此配置确保：

• 使用 Ollama 快速生成本地嵌入
• 如果 Ollama 失败，则自动回退到 OpenAI
• 除非必要，否则不会调用外部 API

注意：系统将根据提供者自动使用适当的向量维度：

• Ollama (nomic-embed-text)：768 维度
• OpenAI (text-embedding-3-small)：1536 维度

致谢

此项目是 qpd-v/mcp-ragdocs 的一个分支，最初由 qpd-v 开发。原始项目为此实现提供了基础。

特别感谢原始创建者 qpd-v 在此 MCP 服务器初始版本上的创新工作。此分支由 Rahul Retnan 增强了额外的功能和改进。

故障排除

服务器无法启动（端口冲突）

如果由于端口冲突导致 MCP 服务器无法启动，请按照以下步骤操作：

1. 找到并终止占用 3030 端口的进程：

npx kill-port 3030

1. 重启 MCP 服务器

2. 如果问题仍然存在，请检查是否有其他进程正在使用该端口：

lsof -i :3030

1. 如有需要，您也可以在配置中更改默认端口