mcp-qdrant-docs MCP Server

mcp-qdrant-docs MCP 服务

模型上下文协议服务

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

使用例

ask_hono_docs: Hono.devのドキュメント内容について質問できます
ask_reactrouter_docs: ReactRouter.comのドキュメント内容について質問できます
ask_gradio_docs: Gradio.appのLLMsドキュメントについて質問できます

功能

工具：ask_<doc name>_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

推荐的运行方式是在 MCP 客户端配置中使用 npx（例如 Claude Desktop 的 claude_desktop_config.json）。这样无需全局安装。

使用 npx 的 claude_desktop_config.json 示例：

{
  "mcpServers": {
    "react-router-docs": { // A unique name for this server instance
      "command": "npx",
      "args": [
        "@kazuph/mcp-qdrant-docs", // The command registered in package.json bin
        // Optional: Add command-line arguments here if needed
        // "--start-url", "https://some-default-url.com/",
        // "--debug"
      ],
      // Optional: Set environment variables for configuration
      "env": {
        "DOCS_URL": "https://reactrouter.com/",
        "QDRANT_URL": "http://your-qdrant-instance:6333",
        "COLLECTION_NAME": "react-router-docs", // Base name for the collection
        "EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2"
        // "DEBUG": "true" // Alternative way to enable debug logging
      }
    }
    // You can add more server instances for different documentation sites here
  }
}

命令行选项

直接运行服务时（例如，使用 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": {
    // ... other servers ...
    "react-router-docs": {
      "command": "npx", // Or the direct path if not installed globally
      "args": [
        "@kazuph/mcp-qdrant-docs"
        // No need to specify --start-url etc. if using env vars
      ],
      "env": {
        "DOCS_URL": "https://reactrouter.com/",
        "QDRANT_URL": "http://your-qdrant-instance:6333", // Replace with your Qdrant URL
        "COLLECTION_NAME": "react-router-docs", // Base name, will become 'react-router-docs-reactrouter_com'
        "EMBEDDING_MODEL": "sentence-transformers/all-MiniLM-L6-v2" // Or your preferred model
        // "DEBUG": "true" // Enable debug logs if needed
      }
    }
    // ... other servers ...
  }
}

生成的工具：

此服务实例运行并连接到 MCP 客户端后，将提供一个类似 ask_reactrouter_docs 的工具（而不是 ask_reactrouter_com_docs）。

• 工具名称： ask_<doc name>_docs（例如，ask_reactrouter_docs）
• 描述： 针对 DOCS_URL（或 --start-url）指定的网站内容提问。
• 输入： 有关文档的自然语言查询。

服务会自动抓取网站（如果集合不存在或使用了 --force-reindex），将内容编入指定的 Qdrant 集合索引（本例中为 react-router-docs-reactrouter_com），然后通过提供的工具（ask_reactrouter_docs）使用该索引回答你的查询。