docs-mcp-server MCP 服务器

一个用于获取和搜索第三方软件包文档的 MCP 服务器。

本项目提供了一个模型上下文协议 (MCP) 服务器，旨在抓取、处理、索引和搜索各种软件库和软件包的文档。它从指定的 URL 获取内容，使用语义分割技术将其分割成有意义的块，使用 OpenAI 生成向量嵌入，并将数据存储在 SQLite 数据库中。该服务器利用 sqlite-vec 实现高效的向量相似度搜索，并利用 FTS5 实现全文搜索功能，将它们结合起来以获得混合搜索结果。它支持版本控制，允许存储和查询不同库版本的文档（包括未版本控制的内容）。

抓取过程由异步作业队列 (PipelineManager) 管理，允许多个抓取作业并发运行。

该服务器公开了以下 MCP 工具：

• 启动抓取作业 (scrape_docs)：立即返回一个 jobId。
• 检查作业状态 (get_job_status)：检索特定作业的当前状态和进度。
• 列出活动/已完成的作业 (list_jobs)：显示最近和正在进行的作业。
• 取消作业 (cancel_job)：尝试停止正在运行或已排队的作业。
• 搜索文档 (search_docs)。
• 列出已索引的库 (list_libraries)。
• 查找合适的版本 (find_version)。
• 删除已索引的文档 (remove_docs)。

还包含一个配套的 CLI (docs-mcp)，用于本地管理和交互（注意：CLI scrape 命令会等待完成）。

构建项目

在使用服务器之前（例如，通过将其与 Claude Desktop 集成，如“安装”部分所述），您需要克隆存储库并从源代码构建项目。

1. 克隆存储库： 如果您尚未克隆，请将项目克隆到您的本地计算机：

   git clone <repository-url> # 将 <repository-url> 替换为实际 URL
   cd docs-mcp-server
   

2. 安装依赖项： 导航到项目目录并安装所需的 Node.js 包：

   npm install
   

3. 构建服务器： 将 TypeScript 源代码编译为 JavaScript。输出将放置在 dist/ 目录中。此步骤是生成安装说明中引用的 dist/server.js 文件所必需的。

   npm run build
   

完成这些步骤并设置您的 .env 文件（请参阅“开发”下的“环境设置”）后，您可以继续执行“安装”或“使用 Docker 运行”说明。

安装

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

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

{
  "mcpServers": {
    "docs-mcp-server": {
      "command": "node",
      "args": ["/path/to/docs-mcp-server/dist/server.js"],
      "env": {
        "OPENAI_API_KEY": "sk-proj-..."
      },
      "disabled": false,
      "autoApprove": []
    }
  }
}

使用 Docker 运行

或者，您可以使用 Docker 构建和运行服务器。这提供了一个隔离的环境，并通过 HTTP 端点公开服务器。

1. 构建 Docker 镜像：

   docker build -t docs-mcp-server .
   

2. 运行 Docker 容器：

   确保您的 .env 文件存在于项目根目录中，因为它包含必要的 OPENAI_API_KEY。容器将在运行时使用 --env-file 标志从此文件读取变量。（有关 .env 文件的详细信息，请参阅“开发”下的“环境设置”）。

   docker run -p 8000:8000 --env-file .env --name docs-mcp-server-container docs-mcp-server
   

   • -p 8000:8000：将主机上的端口 8000 映射到容器中的端口 8000。
   • --env-file .env：在运行时从本地 .env 文件加载环境变量。这是处理密钥的推荐方法。
   • --name docs-mcp-server-container：为容器分配一个名称，以便于管理。

3. 可用端点：

   容器运行后，可以通过以下方式访问 MCP 服务器：

   • SSE 端点： http://localhost:8000/sse（用于服务器发送事件通信）
   • POST 消息： http://localhost:8000/message（用于发送单个消息）

如果您不想直接通过 Node.js 运行服务器，或者不想使用标准安装方法将其与 Claude Desktop 集成，则此方法非常有用。

CLI 用法

docs-mcp CLI 提供了用于管理文档的命令。要查看可用命令和选项：

# 显示所有命令
docs-mcp --help

# 显示特定命令的帮助
docs-mcp scrape --help
docs-mcp search --help
docs-mcp find-version --help
docs-mcp remove --help

抓取文档 (scrape)

从给定 URL 抓取和索引特定库的文档。

docs-mcp scrape <library> <url> [options]

选项：

• -v, --version <string>：与抓取的文档关联的特定版本。
  • 接受完整版本 (1.2.3)、预发布版本 (1.2.3-beta.1) 或部分版本 (1、1.2，它们扩展为 1.0.0、1.2.0)。
  • 如果省略，则文档将索引为未版本控制。
• -p, --max-pages <number>：要抓取的最大页数（默认值：100）。
• -d, --max-depth <number>：最大导航深度（默认值：3）。
• -c, --max-concurrency <number>：最大并发请求数（默认值：3）。
• --ignore-errors：在抓取期间忽略错误（默认值：true）。

示例：

# 抓取 React 18.2.0 文档
docs-mcp scrape react --version 18.2.0 https://react.dev/

# 抓取没有特定版本的 React 文档（索引为未版本控制）
docs-mcp scrape react https://react.dev/

# 抓取部分版本（将存储为 7.0.0）
docs-mcp scrape semver --version 7 https://github.com/npm/node-semver

# 抓取预发布版本
docs-mcp scrape mylib --version 2.0.0-rc.1 https://mylib.com/docs

搜索文档 (search)

搜索已索引的库文档，可以选择按版本过滤。

docs-mcp search <library> <query> [options]

选项：

• -v, --version <string>：要在其中搜索的目标版本或范围。
  • 支持确切版本 (18.0.0)、部分版本 (18) 或范围 (18.x)。
  • 如果省略，则搜索最新可用的已索引版本。
  • 如果特定版本/范围不匹配，它会回退到比目标版本_更旧_的最新索引版本。
  • 要仅搜索未版本控制的文档，请显式传递一个空字符串：--version ""。（注意：省略 --version 会搜索最新版本，如果不存在其他版本，则_可能_是未版本控制的）。
• -l, --limit <number>：最大结果数（默认值：5）。
• -e, --exact-match：仅匹配指定的精确版本（禁用回退和范围匹配）（默认值：false）。

示例：

# 搜索最新的 React 文档中的 'hooks'
docs-mcp search react 'hooks'

# 搜索 React 18.x 文档中的 'hooks'
docs-mcp search react --version 18.x 'hooks'

# 搜索 React 17 文档（如果未找到 17.x.x，将匹配 17.x.x 或更旧版本）
docs-mcp search react --version 17 'hooks'

# 仅搜索 React 18.0.0 文档
docs-mcp search react --version 18.0.0 --exact-match 'hooks'

# 仅搜索未版本控制的 React 文档
docs-mcp search react --version "" 'hooks'

查找可用版本 (find-version)

检查索引中库的最佳匹配版本（基于目标），并指示是否存在未版本控制的文档。

docs-mcp find-version <library> [options]

选项：

• -v, --version <string>：目标版本或范围。如果省略，则查找最新可用版本。

示例：

# 查找 react 的最新索引版本
docs-mcp find-version react

# 查找 react 版本 17.x 的最佳匹配
docs-mcp find-version react --version 17.x

# 查找 react 版本 17.0.0 的最佳匹配（可能会回退到更旧的版本）
docs-mcp find-version react --version 17.0.0

列出库 (list-libraries)

列出当前存储中索引的所有库。

docs-mcp list-libraries

删除文档 (remove)

删除特定库和版本的已索引文档。

docs-mcp remove <library> [options]

选项：

• -v, --version <string>：要删除的特定版本。如果省略，则删除库的未版本控制文档。

示例：

# 删除 React 18.2.0 文档
docs-mcp remove react --version 18.2.0

# 删除未版本控制的 React 文档
docs-mcp remove react

版本处理摘要

• 抓取： 需要特定的有效版本 (X.Y.Z、X.Y.Z-pre、X.Y、X) 或没有版本（对于未版本控制的文档）。范围 (X.x) 对于抓取无效。
• 搜索/查找： 接受特定版本、部分版本或范围 (X.Y.Z、X.Y、X、X.x)。如果目标不匹配，则回退到最新的旧版本。省略版本以定位最新可用版本。显式搜索 --version "" 以定位未版本控制的文档。
• 未版本控制的文档： 库可以存储没有特定版本的文档（通过在抓取期间省略 --version）。可以使用 --version "" 显式搜索这些文档。find-version 命令还将报告是否存在未版本控制的文档以及任何 semver 匹配项。

开发

有关项目架构和设计原则的详细信息，请参阅 ARCHITECTURE.md。

值得注意的是，该项目的大部分代码是由 AI 助手 Cline 生成的，它利用了该 MCP 服务器的功能。

发布

本项目使用 semantic-release 和 Conventional Commits 来自动化发布过程。

工作原理：

1. 提交消息： 合并到 main 分支的所有提交必须遵循 Conventional Commits 规范。这允许 semantic-release 自动确定更改类型（功能、修复、重大更改等）。
   • feat: 提交触发 minor 版本发布。
   • fix: 提交触发 patch 版本发布。
   • 脚注中包含 BREAKING CHANGE: 或类型/范围后包含 ! 的提交（例如，feat!:）触发 major 版本发布。
   • 其他类型（chore:、docs:、style:、refactor:、test: 等）本身不会触发版本发布。
2. 自动化： 当具有触发版本发布的类型（feat、fix、BREAKING CHANGE）的提交被推送或合并到 main 分支时，“Release” GitHub Actions 工作流程会自动运行 semantic-release。
3. semantic-release 操作： 该工具会自动执行以下步骤：
   • 根据提交确定下一个语义版本号。
   • 使用相关提交更新 CHANGELOG.md 文件。
   • 更新 package.json 中的 version。
   • 提交更新后的 CHANGELOG.md 和 package.json。
   • 为新版本创建 Git 标签（例如，v1.2.3）。
   • 将软件包发布到 npm。
   • 创建相应的 GitHub Release，其中包含生成的发布说明。

您需要做什么：

• 使用 Conventional Commits： 严格遵守所有提交消息的 Conventional Commits 格式。提交钩子 (commitlint) 将有助于强制执行此操作。
• 合并到 main： 在功能分支准备就绪时将其合并到 main。

您_不需要_手动执行以下操作：

• 更新 CHANGELOG.md。
• 增加 package.json 中的版本号。
• 创建 Git 标签。
• 发布到 npm。
• 创建 GitHub 版本。

自动化会根据 main 分支上的提交历史记录处理所有这些步骤。

环境设置

注意： 此 .env 文件设置主要在手动运行服务器（例如，node dist/server.js）或在使用 CLI 进行本地开发/测试期间（docs-mcp）需要。在为 Claude Desktop 配置服务器时（请参阅“安装”），OPENAI_API_KEY 通常直接在 claude_desktop_config.json 文件中设置，并且 Claude 集成不使用此 .env 文件。

1. 基于 .env.example 创建一个 .env 文件：

cp .env.example .env

2. 在 .env 中更新您的 OpenAI API 密钥：

OPENAI_API_KEY=your-api-key-here

调试

由于 MCP 服务器通过 stdio 进行通信，因此调试可能具有挑战性。我们建议使用 MCP Inspector，它作为包脚本提供：

npx @modelcontextprotocol/inspector node dist/server.js

Inspector 将提供一个 URL，用于访问浏览器中的调试工具。