mcp-qdrant-docs MCP 服务器

一个模型上下文协议服务器

这是一个基于 TypeScript 的 MCP 服务器，它抓取网站内容，将其索引到 Qdrant 向量数据库中，并提供一个工具来回答有关索引内容的问题。

使用例

ask_hono_docs: Hono.dev 的文档内容について質問できます
ask_reactrouter_docs: ReactRouter.com 的文档内容について質問できます
ask_gradio_docs: Gradio.app 的 LLMs 文档について質問できます

功能

工具: ask_<文档名称>_docs

• 名称: 基于 DOCS_URL 或 --start-url 动态生成 (例如, ask_reactrouter_docs)。
• 功能: 允许用户使用自然语言提问关于从指定网站抓取的内容。
• 流程:
  1. 在启动时 (或者如果指定了 force-reindex)，服务器会抓取目标网站。
  2. 抓取的内容会被处理、分块，并使用句子转换器模型进行嵌入。
  3. 这些嵌入和内容块存储在特定于该网站的 Qdrant 集合中。
  4. 当使用查询调用该工具时，服务器会嵌入该查询，在 Qdrant 中搜索相关块，并将找到的内容作为答案返回。
• 输入: 自然语言查询 (字符串)。
• 输出: 包含在 Qdrant 索引中找到的相关内容块的文本。

安装

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

在 MacOS 上: ~/Library/Application Support/Claude/claude_desktop_config.json 在 Windows 上: %APPDATA%/Claude/claude_desktop_config.json

npm i -g @kazuph/mcp-qdrant-docs

使用 npx

推荐使用 npx 在您的 MCP 客户端配置 (例如，Claude Desktop 的 claude_desktop_config.json) 中运行此服务器。 这避免了全局安装的需要。

使用 npx 的 claude_desktop_config.json 示例:

{
  "mcpServers": {
    "react-router-docs": { // 此服务器实例的唯一名称
      "command": "npx",
      "args": [
        "@kazuph/mcp-qdrant-docs", // 在 package.json bin 中注册的命令
        // 可选: 如果需要，在此处添加命令行参数
        // "--start-url", "https://some-default-url.com/",
        // "--debug"
      ],
      // 可选: 设置环境变量进行配置
      "env": {
        "DOCS_URL": "https://reactrouter.com/",
        "QDRANT_URL": "http://your-qdrant-instance:6333",
        "COLLECTION_NAME": "react-router-docs", // 集合的基本名称
        "EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2"
        // "DEBUG": "true" // 启用调试日志的另一种方法
      }
    }
    // 您可以在此处为不同的文档站点添加更多服务器实例
  }
}

命令行选项

当直接运行服务器时 (例如，使用 npx mcp-qdrant-docs 或 npm run dev --)，您可以使用以下命令行选项。 如果同时设置了命令行选项和环境变量，则这些选项将覆盖相应的环境变量。

• --start-url <url> 或 -s <url>:
  • 必需 (如果未设置 DOCS_URL 环境变量)。
  • 要抓取的网站的起始 URL。
  • 覆盖 DOCS_URL 环境变量。
• --limit <number> 或 -l <number>:
  • 要抓取的最大页面数。
  • 默认值: 300。
• --match <pattern> 或 -m <pattern>:
  • URL 路径模式 (前缀匹配) 以限制抓取。 可以多次指定。
  • 示例: --match /docs/ --match /api/
  • 默认值: 抓取 start-url 域下的所有页面。
• --force-reindex:
  • 强制重新抓取和重新索引，即使 Qdrant 集合已存在。
  • 默认值: false。
• --collection-name <name> 或 -c <name>:
  • Qdrant 集合的基本名称。 最终集合名称将为 <base_name>-<sanitized_hostname>。
  • 覆盖 COLLECTION_NAME 环境变量。
  • 默认值: docs-collection。
• --qdrant-url <url>:
  • Qdrant 实例的 URL。
  • 覆盖 QDRANT_URL 环境变量。
  • 默认值: http://localhost:6333。
• --embedding-model <model_name>:
  • 用于嵌入的句子转换器模型的名称 (来自 Hugging Face 或本地)。
  • 覆盖 EMBEDDING_MODEL 环境变量。
  • 默认值: Xenova/all-MiniLM-L6-v2。
• --debug:
  • 启用详细的调试日志记录。
  • 覆盖 DEBUG 环境变量 (如果设置为 true)。
  • 默认值: false。
• --help 或 -h:
  • 显示列出所有选项的帮助消息。

使用命令行选项的示例:

npx @kazuph/mcp-qdrant-docs --start-url https://example-docs.com/ --collection-name my-docs --limit 50 --debug

配置优先级:

服务器使用以下设置优先级：

1. 命令行参数: (例如, --start-url, --collection-name) - 最高优先级。
2. 环境变量: (例如, DOCS_URL, COLLECTION_NAME) - 如果未提供命令行参数，则使用。
3. 默认值: (在代码中定义) - 最低优先级。

示例: 添加 React Router 文档

要添加专门用于查询 React Router 文档的服务器实例，请将以下条目添加到您的 mcpServers 配置 (例如，在 claude_desktop_config.json 中)：

{
  "mcpServers": {
    // ... 其他服务器 ...
    "react-router-docs": {
      "command": "npx", // 或者如果未全局安装，则使用直接路径
      "args": [
        "@kazuph/mcp-qdrant-docs"
        // 如果使用环境变量，则无需指定 --start-url 等。
      ],
      "env": {
        "DOCS_URL": "https://reactrouter.com/",
        "QDRANT_URL": "http://your-qdrant-instance:6333", // 替换为您的 Qdrant URL
        "COLLECTION_NAME": "react-router-docs", // 基本名称，将变为 'react-router-docs-reactrouter_com'
        "EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2" // 或者您喜欢的模型
        // "DEBUG": "true" // 如果需要，启用调试日志
      }
    }
    // ... 其他服务器 ...
  }
}

生成的工具:

一旦此服务器实例正在运行并连接到您的 MCP 客户端，它将提供一个类似于 ask_reactrouter_docs (而不是 ask_reactrouter_com_docs) 的工具。

• 工具名称: ask_<文档名称>_docs (例如, ask_reactrouter_docs)
• 描述: 询问有关 DOCS_URL (或 --start-url) 指定的站点的内容的问题。
• 输入: 关于文档的自然语言查询。

服务器将自动抓取站点 (如果集合不存在或使用了 --force-reindex)，将内容索引到指定的 Qdrant 集合 (在此示例中为 react-router-docs-reactrouter_com)，然后使用该索引通过提供的工具 (ask_reactrouter_docs) 回答您的查询。