STARWARCLOUD STARWAR.AI
返回市场
麦普-知识文档

麦普-知识文档

作者：rahulretnan49 星标更新：2025-06-26
安装使用来源：spider==github.com

项目介绍

RAG 文档 MCP 服务器

smithery 徽章

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

目录

功能

工具

  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

    • 通过提供 URL 直接将新文档添加到系统中
    • 自动获取、处理并索引内容
    • 支持各种网页格式并提取相关内容
    • 智能分块内容以优化检索
    • 必需参数：url（必须包括协议，例如 https://）

  9. add_repository

    • 对本地代码仓库进行索引以生成文档
    • 配置文件和目录的包含/排除模式
    • 根据文件类型支持不同的分块策略
    • 使用异步处理避免大型仓库导致的 MCP 超时
    • 在索引期间提供详细的进度日志（心跳）到 stderr
    • 必需参数：path（仓库的绝对路径）

  10. list_repositories

    • 列出所有已索引的仓库及其配置
    • 显示包含/排除模式和监控状态

  11. update_repository

    • 使用更新后的配置重新索引仓库
    • 可修改包含/排除模式和其他设置
    • 在重新索引期间提供详细的进度日志（心跳）到 stderr
    • 必需参数：name（仓库名称）

  12. remove_repository

    • 从索引中移除仓库
    • 删除与该仓库关联的所有文档
  • 必需参数：name（仓库名称）

  1. watch_repository

    • 开始或停止监控仓库的变化
    • 文件更改时自动更新索引
    • 必需参数：name（仓库名称）和 action（"start" 或 "stop"）

  2. get_indexing_status

    • 获取仓库索引操作的当前状态
    • 提供正在进行或已完成的索引过程的详细信息
    • 显示进度百分比、文件计数和时间信息
    • 可选参数：name（仓库名称）- 如果未提供，则返回所有仓库的状态

快速开始

RAG 文档工具旨在：

  • 增强 AI 响应的相关文档
  • 构建具有文档意识的 AI 助手
  • 创建面向开发者的上下文感知工具
  • 实现语义文档搜索
  • 扩展现有的知识库

Docker Compose 配置

该项目包含一个 docker-compose.yml 文件，用于轻松的容器化部署。启动服务：

docker-compose up -d

停止服务：

docker-compose down

Web 界面

系统包含一个 Web 界面，在启动 Docker Compose 服务后可以访问：

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

配置

嵌入式配置

系统使用 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", // 默认值
        "EMBEDDING_MODEL": "nomic-embed-text", // 可选
        "OPENAI_API_KEY": "your-api-key-here", // 必需用于备用
        "FALLBACK_PROVIDER": "openai", // 推荐用于可靠性
        "FALLBACK_MODEL": "nomic-embed-text", // 可选
        "QDRANT_URL": "http://localhost:6333"
      },
      "disabled": false,
      "autoApprove": [
        "search_documentation",
        "list_sources",
        "extract_urls",
        "remove_documentation",
        "list_queue",
        "run_queue",
        "clear_queue",
        "add_documentation",
        "add_repository",
        "list_repositories",
        "update_repository",
        "remove_repository",
        "watch_repository",
        "get_indexing_status"
      ]
    }
  }
}

Claude Desktop 配置

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

{
  "mcpServers": {
    "rag-docs": {
      "command": "node",
      "args": ["/path/to/your/mcp-ragdocs/build/index.js"],
      "env": {
        "EMBEDDING_PROVIDER": "ollama", // 默认值
        "EMBEDDING_MODEL": "nomic-embed-text", // 可选
        "OPENAI_API_KEY": "your-api-key-here", // 必需用于备用
        "FALLBACK_PROVIDER": "openai", // 推荐用于可靠性
        "FALLBACK_MODEL": "nomic-embed-text", // 可选
        "QDRANT_URL": "http://localhost:6333"
      },
      "autoApprove": [
        "search_documentation",
        "list_sources",
        "extract_urls",
        "remove_documentation",
        "list_queue",
        "run_queue",
        "clear_queue",
        "add_documentation",
        "add_repository",
        "list_repositories",
        "update_repository",
        "remove_repository",
        "watch_repository",
        "get_indexing_status"
      ]
    }
  }
}

默认配置

系统默认使用 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 维度

文档管理

直接添加 vs. 队列式文档添加

系统提供了两种互补的方法来添加文档：

  1. 直接添加（add_documentation 工具）

    • 立即处理并索引来自 URL 的文档
    • 最适合添加单个文档来源
    • 提供处理成功/失败的即时反馈
    • 示例用法：add_documentation 与 url: "https://example.com/docs"

  2. 队列式处理

    • 将 URL 添加到处理队列（extract_urls 与 add_to_queue: true）
    • 后续批量处理多个 URL（run_queue）
    • 更适合大规模文档摄入
    • 允许安排许多文档来源的处理
    • 通过队列系统提供弹性

选择最适合您文档管理需求的方法。对于少量重要文档，直接添加提供即时结果。对于大量文档集或递归爬取，队列式方法提供更好的可扩展性。

本地仓库索引

系统支持对本地代码仓库进行索引，使其内容可以与网络文档一起搜索：

  1. 仓库配置

    • 使用通配符模式定义要包含/排除哪些文件
    • 针对每种文件类型配置分块策略
    • 设置自动变更检测的监控模式

  2. 文件处理

    • 根据文件类型和语言处理文件
    • 智能分块代码以保留上下文
    • 保留如文件路径和语言等元数据

  3. 异步处理

    • 大型仓库异步处理以避免 MCP 超时
    • 初始响应后继续后台索引
    • 使用 get_indexing_status 工具监控进度
    • 较小的批次大小（每批 50 个块）提高响应速度

  4. 变更检测

    • 监控仓库变化
    • 自动重新索引修改的文件
    • 从索引中删除已删除的文件

示例用法：

add_repository with {
  "path": "/path/to/your/repo",
  "name": "my-project",
  "include": ["**/*.js", "**/*.ts", "**/*.md"],
  "exclude": ["**/node_modules/**", "**/dist/**"],
  "watchMode": true
}

启动索引过程后，您可以检查其状态：

get_indexing_status with {
  "name": "my-project"
}

这将返回关于索引进度的详细信息：

仓库：my-project
状态：🔄 正在处理
进度：45%
开始时间：2025年5月11日 下午2:45:30
持续时间：3分钟15秒
文件：已处理120个，跳过15个（共250个）
块：已索引1500个（共3300个）
批次：第15批（共33批）

仓库配置文件

系统支持一个 repositories.json 配置文件，允许您定义在启动时自动索引的仓库：

{
  "repositories": [
    {
      "path": "/path/to/your/repo",
      "name": "my-project",
      "include": ["**/*.js", "**/*.ts", "**/*.md"],
      "exclude": ["**/node_modules/**", "**/.git/**"],
      "watchMode": true,
      "watchInterval": 60000,
      "chunkSize": 1000,
      "fileTypeConfig": {
        ".js": { "include": true, "chunkStrategy": "semantic" },
        ".ts": { "include": true, "chunkStrategy": "semantic" },
        ".md": { "include": true, "chunkStrategy": "semantic" }
      }
    }
  ],
  "autoWatch": true
}

配置文件会在使用仓库管理工具添加、更新或移除仓库时自动更新。您也可以手动编辑文件以在启动服务器前配置仓库。配置文件中的路径，如每个仓库的 path 和隐含的 repositories.json 位置，都是相对于执行服务器的项目根目录解析的。

配置选项：

  • repositories：仓库配置数组

    • path：仓库目录的绝对路径
    • name：仓库的唯一名称
    • include：包含的通配符模式数组
    • exclude：排除的通配符模式数组
    • watchMode：是否监控变更
    • watchInterval：轮询间隔（毫秒）
    • chunkSize：文件的默认分块大小
    • fileTypeConfig：特定文件类型的配置
      • include：是否包含此文件类型
      • chunkStrategy：分块策略（"semantic"、"line" 或 "character"）
      • chunkSize：分块大小的可选覆盖

  • autoWatch：是否在启动时自动开始监控 watchMode: true 的仓库

致谢

本项目是 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. 如有需要，可以在配置中更改默认端口

Claude Desktop 缺少工具

如果某些工具（如 add_documentation）在 Claude Desktop 中没有出现：

  1. 验证工具是否已在服务器的 handler-registry.ts 文件中正确注册
  2. 确保工具包含在 ListToolsRequestSchema 处理程序响应的 tools 数组中
  3. 检查您的 Claude Desktop 配置是否在 autoApprove 数组中包含该工具
  4. 重启 Claude Desktop 应用程序和 MCP 服务器
  5. 检查服务器日志是否有与工具注册相关的错误

缺少工具最常见的原因是它们被注册为处理程序但未包含在 ListToolsRequestSchema 处理程序返回的 tools 数组中。

大型仓库超时问题

如果您在索引大型仓库时遇到超时错误：

  1. 系统现在使用异步处理以避免 MCP 超时
  2. 当使用 add_repository 添加仓库时，索引将在后台继续
  3. 使用 get_indexing_status 工具监控进度
  4. 如果您仍然遇到问题，请尝试以下解决方案：
    • 使用更具体的包含/排除模式减少索引范围
    • 将非常大的仓库拆分为较小的逻辑单元
    • 如果系统有更多的资源可用，增加代码中的批次大小
    • 在索引期间检查系统资源（内存、CPU），以识别瓶颈