docs-mcp-server MCP 服务器

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

✨ 主要功能

• 🌐 多用途抓取： 从网站、GitHub、npm、PyPI或本地文件等多样化来源获取文档。
• 🧠 智能处理： 使用您选择的模型（OpenAI、Google Gemini、Azure OpenAI、AWS Bedrock、Ollama等）自动进行语义分割并生成嵌入向量。
• 💾 优化存储： 利用带有sqlite-vec的SQLite进行高效的向量存储，并使用FTS5进行强大的全文搜索。
• 🔍 强大的混合搜索： 结合不同库版本之间的向量相似性和全文搜索，以获得高度相关的结果。
• ⚙️ 异步任务处理： 通过后台作业队列和MCP/CLI工具高效管理抓取和索引任务。
• 🐳 简单的部署： 使用Docker或npx快速启动并运行。

概述

此项目提供了一个Model Context Protocol (MCP)服务器，设计用于抓取、处理、索引和搜索各种软件库和包的文档。它从指定的URL获取内容，使用语义分割技术将其拆分为有意义的块，使用OpenAI生成向量嵌入，并将数据存储在SQLite数据库中。该服务器利用sqlite-vec实现高效的向量相似性搜索，并结合FTS5实现全文搜索能力，从而提供混合搜索结果。它支持版本控制，允许存储和查询不同库版本（包括未版本化的内容）的文档。

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

• 启动抓取任务 (scrape_docs)：立即返回一个jobId。
• 检查任务状态 (get_job_status)：检索特定任务的当前状态和进度。
• 列出活动/已完成的任务 (list_jobs)：显示最近和正在进行的任务。
• 取消任务 (cancel_job)：尝试停止正在运行或排队的任务。
• 搜索文档 (search_docs)。
• 列出已索引的库 (list_libraries)。
• 查找适当的版本 (find_version)。
• 移除已索引的文档 (remove_docs)。
• 获取单个URL (fetch_url)：获取URL并以Markdown格式返回其内容。

配置

支持以下环境变量来配置嵌入模型的行为：

嵌入模型配置

• DOCS_MCP_EMBEDDING_MODEL: 可选。 格式：provider:model_name 或仅 model_name（默认为 text-embedding-3-small）。支持的提供商及其所需的环境变量：

  • openai（默认）：使用 OpenAI 的嵌入模型

    • OPENAI_API_KEY：必需。 您的 OpenAI API 密钥
    • OPENAI_ORG_ID：可选。 您的 OpenAI 组织 ID
    • OPENAI_API_BASE：可选。 用于 OpenAI 兼容 API 的自定义基础 URL（例如，Ollama、Azure OpenAI）

  • vertex：使用 Google Cloud Vertex AI 嵌入

    • GOOGLE_APPLICATION_CREDENTIALS：必需。 服务账户 JSON 密钥文件的路径

  • gemini：使用 Google 生成式 AI（Gemini）嵌入

    • GOOGLE_API_KEY：必需。 您的 Google API 密钥

  • aws：使用 AWS Bedrock 嵌入

    • AWS_ACCESS_KEY_ID：必需。 AWS 访问密钥
    • AWS_SECRET_ACCESS_KEY：必需。 AWS 秘密密钥
    • AWS_REGION 或 BEDROCK_AWS_REGION：必需。 AWS 区域（针对 Bedrock）

  • microsoft：使用 Azure OpenAI 嵌入

    • AZURE_OPENAI_API_KEY：必需。 Azure OpenAI API 密钥
    • AZURE_OPENAI_API_INSTANCE_NAME：必需。 Azure 实例名称
    • AZURE_OPENAI_API_DEPLOYMENT_NAME：必需。 Azure 部署名称
    • AZURE_OPENAI_API_VERSION：必需。 Azure API 版本

向量维度

数据库模式使用固定维度 1536 的嵌入向量。只支持生成维度 ≤ 1536 的向量的模型，除了某些提供商（如 Gemini）支持维度缩减。

对于与 OpenAI 兼容的 API（如 Ollama），请使用 openai 提供商，并将 OPENAI_API_BASE 指向您的端点。

这些变量可以在您运行服务器时设置（无论您是通过 Docker、npx 还是从源代码运行）。

运行 MCP 服务器

有两种方法可以运行 docs-mcp-server：

选项 1：使用 Docker（推荐）

这是大多数用户的推荐方法。它简单直接，不需要安装 Node.js。

1. 确保已安装并运行 Docker。

2. 配置您的 MCP 设置：

   Claude/Cline/Roo 配置示例：
   将以下配置块添加到您的 MCP 设置文件中（根据需要调整路径）：

   {
     "mcpServers": {
       "docs-mcp-server": {
         "command": "docker",
         "args": [
           "run",
           "-i",
           "--rm",
           "-e",
           "OPENAI_API_KEY",
           "-v",
           "docs-mcp-data:/data",
           "ghcr.io/arabold/docs-mcp-server:latest"
         ],
         "env": {
           "OPENAI_API_KEY": "sk-proj-..." // 必需：替换为您的密钥
         },
         "disabled": false,
         "autoApprove": []
       }
     }
   }
   

   请记得将 "sk-proj-..." 替换为您的实际 OpenAI API 密钥，并重新启动应用程序。

3. 就这样！ 服务器现在可供您的 AI 助手使用了。

Docker 容器设置：

• -i: 保持 STDIN 打开，这对于通过 stdio 进行 MCP 通信至关重要。
• --rm: 容器退出时自动删除。
• -e OPENAI_API_KEY: 必需。 设置你的 OpenAI API 密钥。
• -v docs-mcp-data:/data: 对于持久化是必需的。 挂载一个名为 docs-mcp-data 的 Docker 卷来存储数据库。如果你愿意，也可以用特定的主机路径替换（例如，-v /path/on/host:/data）。

任何配置环境变量（见上文配置）都可以使用 -e 标志传递给容器。例如：

# Example 1: Using OpenAI embeddings (default)
docker run -i --rm \
  -e OPENAI_API_KEY="your-key-here" \
  -e DOCS_MCP_EMBEDDING_MODEL="text-embedding-3-small" \
  -v docs-mcp-data:/data \
  ghcr.io/arabold/docs-mcp-server:latest

# Example 2: Using OpenAI-compatible API (like Ollama)
docker run -i --rm \
  -e OPENAI_API_KEY="your-key-here" \
  -e OPENAI_API_BASE="http://localhost:11434/v1" \
  -e DOCS_MCP_EMBEDDING_MODEL="embeddings" \
  -v docs-mcp-data:/data \
  ghcr.io/arabold/docs-mcp-server:latest

# Example 3a: Using Google Cloud Vertex AI embeddings
docker run -i --rm \
  -e OPENAI_API_KEY="your-openai-key" \  # Keep for fallback to OpenAI
  -e DOCS_MCP_EMBEDDING_MODEL="vertex:text-embedding-004" \
  -e GOOGLE_APPLICATION_CREDENTIALS="/app/gcp-key.json" \
  -v docs-mcp-data:/data \
  -v /path/to/gcp-key.json:/app/gcp-key.json:ro \
  ghcr.io/arabold/docs-mcp-server:latest

# Example 3b: Using Google Generative AI (Gemini) embeddings
docker run -i --rm \
  -e OPENAI_API_KEY="your-openai-key" \  # Keep for fallback to OpenAI
  -e DOCS_MCP_EMBEDDING_MODEL="gemini:embedding-001" \
  -e GOOGLE_API_KEY="your-google-api-key" \
  -v docs-mcp-data:/data \
  ghcr.io/arabold/docs-mcp-server:latest

# Example 4: Using AWS Bedrock embeddings
docker run -i --rm \
  -e AWS_ACCESS_KEY_ID="your-aws-key" \
  -e AWS_SECRET_ACCESS_KEY="your-aws-secret" \
  -e AWS_REGION="us-east-1" \
  -e DOCS_MCP_EMBEDDING_MODEL="aws:amazon.titan-embed-text-v1" \
  -v docs-mcp-data:/data \
  ghcr.io/arabold/docs-mcp-server:latest

# Example 5: Using Azure OpenAI embeddings
docker run -i --rm \
  -e AZURE_OPENAI_API_KEY="your-azure-key" \
  -e AZURE_OPENAI_API_INSTANCE_NAME="your-instance" \
  -e AZURE_OPENAI_API_DEPLOYMENT_NAME="your-deployment" \
  -e AZURE_OPENAI_API_VERSION="2024-02-01" \
  -e DOCS_MCP_EMBEDDING_MODEL="microsoft:text-embedding-ada-002" \
  -v docs-mcp-data:/data \
  ghcr.io/arabold/docs-mcp-server:latest

选项 2：使用 npx

当你需要本地文件访问（例如，从本地文件系统索引文档）时，推荐此方法。虽然这也可以通过将路径挂载到 Docker 容器中实现，但使用 npx 更简单，不过需要安装 Node.js。

1. 确保已安装 Node.js。

2. 配置你的 MCP 设置：

   Claude/Cline/Roo 配置示例：
   在你的 MCP 设置文件中添加以下配置块：

   {
     "mcpServers": {
       "docs-mcp-server": {
         "command": "npx",
         "args": ["-y", "--package=@arabold/docs-mcp-server", "docs-server"],
         "env": {
           "OPENAI_API_KEY": "sk-proj-..." // 必需：替换为你的密钥
         },
         "disabled": false,
         "autoApprove": []
       }
     }
   }
   

   记得将 "sk-proj-..." 替换为你的实际 OpenAI API 密钥，并重启应用程序。

3. 就这样！ 服务器现在可以供你的 AI 助手使用了。

使用 CLI

你可以使用 CLI 直接管理文档，无论是通过 Docker 还是 npx。重要提示：为了确保能够访问相同的索引文档，请对服务器和 CLI 使用相同的方法（Docker 或 npx）。

使用 Docker CLI

如果你正在使用 Docker 运行服务器，那么也请使用 Docker 来运行 CLI：

docker run --rm \
  -e OPENAI_API_KEY="your-openai-api-key-here" \
  -v docs-mcp-data:/data \
  ghcr.io/arabold/docs-mcp-server:latest \
  docs-cli <command> [options]

确保使用与服务器相同的卷名称（本例中为 docs-mcp-data）。任何配置环境变量（见上文配置）都可以像在服务器中那样使用 -e 标志传递。

使用 npx CLI

如果你正在使用 npx 运行服务器，那么也请使用 npx 来运行 CLI：

npx -y --package=@arabold/docs-mcp-server docs-cli <command> [options]

npx 方法将使用系统中的默认数据目录（通常位于主目录下），以确保服务器和 CLI 之间的一致性。

（参见下面的“CLI 命令参考”以获取可用命令和选项。）

CLI 命令参考

docs-cli 提供了用于管理文档索引的命令。可以通过 Docker (docker run -v docs-mcp-data:/data ghcr.io/arabold/docs-mcp-server:latest docs-cli ...) 或 npx (npx -y --package=@arabold/docs-mcp-server docs-cli ...) 来访问它。

通用帮助：

docs-cli --help
# or
npx -y --package=@arabold/docs-mcp-server docs-cli --help

特定命令帮助：（如果未全局安装，请将 docs-cli 替换为 npx... 命令）

docs-cli scrape --help
docs-cli search --help
docs-cli fetch-url --help
docs-cli find-version --help
docs-cli remove --help
docs-cli list --help

获取单个 URL (fetch-url)

获取单个 URL 并将其内容转换为 Markdown。与 scrape 不同，此命令不会爬取链接或存储内容。

docs-cli fetch-url <url> [options]

选项:

• --no-follow-redirects: 禁用 HTTP 重定向跟随（默认：跟随重定向）。
• --scrape-mode <mode>: HTML 处理策略：'fetch'（快速，较少的 JS），'playwright'（慢速，完整的 JS），'auto'（默认）。

示例:

# Fetch a URL and convert to Markdown
docs-cli fetch-url https://example.com/page.html

抓取文档 (scrape)

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

docs-cli 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>: 最大抓取页面数（默认：1000）。
• -d, --max-depth <number>: 最大导航深度（默认：3）。
• -c, --max-concurrency <number>: 最大并发请求数（默认：3）。
• --scope <scope>: 定义爬取边界：'subpages'（默认）、'hostname' 或 'domain'。
• --no-follow-redirects: 禁用 HTTP 重定向跟随（默认：跟随重定向）。
• --scrape-mode <mode>: HTML 处理策略：'fetch'（快速，较少的 JS），'playwright'（慢速，完整的 JS），'auto'（默认）。
• --ignore-errors: 忽略抓取过程中的错误（默认：true）。

示例:

# Scrape React 18.2.0 docs
docs-cli scrape react --version 18.2.0 https://react.dev/

搜索文档 (search)

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

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

选项:

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

示例:

# Search latest React docs for 'hooks'
docs-cli search react 'hooks'

查找可用版本 (find-version)

根据目标检查索引中库的最佳匹配版本，并指示是否存在未版本化的文档。

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

选项:

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

示例:

# Find the latest indexed version for react
docs-cli find-version react

列出库 (list)

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

docs-cli list

删除文档 (remove)

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

docs-cli remove <library> [options]

选项:

• -v, --version <string>: 要移除的具体版本。如果省略，则移除该库的未版本化文档。

示例：

# Remove React 18.2.0 docs
docs-cli remove react --version 18.2.0

版本处理摘要

• 抓取: 需要一个特定的有效版本（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 命令还会报告是否存在未版本化的文档以及任何语义化版本匹配。

开发与高级设置

本节介绍如何从源代码直接运行服务器/CLI以进行开发。主要使用方法现在是通过公共 Docker 镜像，如“方法 2”中所述。

从源代码运行（开发）

这提供了一个隔离的环境，并通过 HTTP 端点暴露服务器。

1. 克隆仓库：

   git clone https://github.com/arabold/docs-mcp-server.git # 如果不同，请替换为实际URL
   cd docs-mcp-server
   

2. 创建.env文件：
   复制示例并添加您的OpenAI密钥（请参阅下面的“环境设置”）。

   cp .env.example .env
   # 编辑.env并添加您的OPENAI_API_KEY
   

3. 构建Docker镜像：

   docker build -t docs-mcp-server .
   

4. 运行Docker容器：

   # 选项1：使用命名卷（推荐）
   # Docker会在首次运行时自动创建名为'docs-mcp-data'的卷，如果它不存在的话。
   docker run -i --env-file .env -v docs-mcp-data:/data --name docs-mcp-server docs-mcp-server
   
   # 选项2：映射到主机目录
   # docker run -i --env-file .env -v /path/on/your/host:/data --name docs-mcp-server docs-mcp-server
   

   • -i: 即使未附加也保持STDIN打开。这对于通过stdio与服务器交互至关重要。
   • --env-file .env: 从本地.env文件加载环境变量（如OPENAI_API_KEY）。
   • -v docs-mcp-data:/data 或 -v /path/on/your/host:/data: 对于持久化存储至关重要。 这会将一个Docker命名卷（如果需要，Docker会自动创建docs-mcp-data）或主机目录挂载到容器内的/data目录。/data目录是服务器存储其documents.db文件的地方（由Dockerfile中的DOCS_MCP_STORE_PATH配置）。这确保了即使容器停止或被删除，已索引的文档也能持久保存。
   • --name docs-mcp-server: 为容器分配一个方便的名字。

   容器内的服务器现在直接使用Node.js运行，并通过stdio通信。

这种方法对于贡献项目或运行未发布的版本非常有用。

1. 克隆仓库：

   git clone https://github.com/arabold/docs-mcp-server.git # 如果不同，请替换为实际URL
   cd docs-mcp-server
   

2. 安装依赖：

   npm install
   

3. 构建项目：
   这将在dist/目录中将TypeScript编译为JavaScript。

   npm run build
   

4. 设置环境：
   按照下面“环境设置”部分描述的方式创建并配置您的.env文件。这对于提供OPENAI_API_KEY至关重要。

5. 运行：

   • 服务器（开发模式）: npm run dev:server （构建、监视并重启）
   • 服务器（生产模式）: npm run start （运行预构建的代码）
   • CLI: npm run cli -- <command> [options] 或 node dist/cli.js <command> [options]

环境设置（适用于源码/Docker）

注意： 当从源码运行服务器或使用Docker方法时，主要需要进行这种.env文件设置。当使用npx集成方法时，OPENAI_API_KEY直接在MCP配置文件中设置。

1. 根据 .env.example 创建一个 .env 文件：

   cp .env.example .env
   

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

   # 必填：用于生成嵌入的 OpenAI API 密钥。
   OPENAI_API_KEY=your-api-key-here
   
   # 可选：您的 OpenAI 组织 ID（如果设置，LangChain 会自动处理）
   OPENAI_ORG_ID=
   
   # 可选：OpenAI API 的自定义基础 URL（例如，对于 Azure OpenAI 或兼容的 API）
   OPENAI_API_BASE=
   
   # 可选：嵌入模型名称（默认为 "text-embedding-3-small"）
   # 示例：text-embedding-3-large, text-embedding-ada-002
   DOCS_MCP_EMBEDDING_MODEL=
   
   # 可选：指定自定义目录以存储 SQLite 数据库文件 (documents.db)。
   # 如果设置了此路径，则优先于默认位置。
   # 默认行为（如果未设置）：
   # 1. 如果存在项目根目录下的 './.store/' 则使用它（遗留）。
   # 2. 回退到特定于操作系统的数据目录（例如，在 macOS 上为 ~/Library/Application Support/docs-mcp-server）。
   # DOCS_MCP_STORE_PATH=/path/to/your/desired/storage/directory
   

调试（从源代码）

由于 MCP 服务器在直接通过 Node.js 运行时通过 stdio 通信，调试可能会很困难。我们建议使用 MCP Inspector，它在构建后作为包脚本提供：

npx @modelcontextprotocol/inspector node dist/server.js

Inspector 将提供一个 URL，以便您在浏览器中访问调试工具。

发布

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

工作原理：

1. 提交信息： 合并到 main 分支的所有提交必须遵循 Conventional Commits 规范。
2. 手动触发： 当您准备好创建新版本时，可以从 Actions 标签页手动触发“Release” GitHub Actions 工作流。
3. semantic-release 操作： 确定版本，更新 CHANGELOG.md 和 package.json，提交、打标签、发布到 npm，并创建 GitHub 版本发布。

你需要做什么：

• 使用 Conventional Commits。
• 将更改合并到 main。
• 准备好时从 GitHub 的 Actions 标签页手动触发发布。

自动化处理： 变更日志、版本提升、标签、npm 发布、GitHub 版本发布。

架构

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

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