docs-mcp-server MCP Server

docs-mcp-server MCP 服务

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

✨ 主要功能

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

概述

本项目提供了一个模型上下文协议（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 格式返回其内容。

🆕 OpenRouter API 集成与多模型支持

聊天/补全功能

本服务已全面适配 OpenRouter API，支持主流大模型（GPT-4.1、Claude 3.7、Gemini 2.5、Grok、Qwen 等），并支持多模态输入（文本+图片）。

主要特性

• ✅ 支持 OpenRouter 官方所有主流模型，模型列表见 src/utils/openrouter.ts 的 OPENROUTER_MODELS
• ✅ 支持多模态消息格式（如 text、image_url）
• ✅ 支持自定义 HTTP-Referer、X-Title 等 header，便于 openrouter.ai 统计和排名
• ✅ 支持 OpenRouter API 的所有扩展参数（如 stream、tools、temperature、max_tokens 等）

环境变量配置

• OPENAI_API_KEY：OpenRouter API Key（必填）
• OPENAI_API_BASE：OpenRouter API Base，推荐 https://openrouter.ai/api/v1
• MODEL_ID：默认模型（如 openai/gpt-4.1），可选

示例代码

import { openrouterChat } from './src/utils/openrouter';

const messages = [
  {
    role: 'user',
    content: [
      { type: 'text', text: 'What is in this image?' },
      { type: 'image_url', image_url: { url: 'https://upload.wikimedia.org/wikipedia/commons/thumb/d/dd/Gfp-wisconsin-madison-the-nature-boardwalk.jpg/2560px-Gfp-wisconsin-madison-the-nature-boardwalk.jpg' } }
    ]
  }
];

const result = await openrouterChat({
  model: 'openai/gpt-4.1',
  messages,
  referer: 'https://your-site.com', // 可选
  xTitle: 'Your Site Name'           // 可选
  // 还可加 extraBody, headers 等参数
});
console.log(result);

支持的主流模型（部分示例）

• openai/gpt-4.1
• openai/gpt-4.1-mini
• anthropic/claude-3.7-sonnet
• google/gemini-2.5-pro-preview-03-25
• x-ai/grok-3-beta
• qwen/qwen2.5-vl-32b-instruct:free
• deepseek/deepseek-chat-v3-0324:free
• thudm/glm-z1-32b:free
• openrouter/auto
• ...（详见源码 OPENROUTER_MODELS）

更多 API 参数

如需支持流式输出、函数调用、system 提示词、stop、temperature、max_tokens 等 OpenRouter API 参数，只需通过 extraBody 字段传递即可，无需修改底层代码。

⚠️ 嵌入功能说明

嵌入功能已禁用！

本项目当前版本已彻底移除所有与嵌入相关的实现和依赖，不再支持生成和检索向量。所有与嵌入相关的 API 均会直接抛出异常提示。

仅保留全文检索与大模型 chat/completions 能力。

配置

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

嵌入模型配置

• 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 Generative 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：必需。 Bedrock 的 AWS 区域

  • 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-..." // Required: Replace with your key
         },
         "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：持久化所必需。 将 Docker 命名卷 docs-mcp-data 挂载到 /data 以存储数据库。你也可以替换为特定的主机路径（例如 -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-..." // Required: Replace with your key
         },
         "disabled": false,
         "autoApprove": []
       }
     }
   }
   

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

3. 完成！ 现在，AI 助手即可使用该服务。

使用 CLI

你可以通过 Docker 或 npx 使用 CLI 直接管理文档。重要提示：服务和 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 命令也会报告是否存在无版本文档，以及是否存在任何 semver 匹配项。

本地配置 OpenRouter 详细步骤（零基础操作指引）

1. 打开 .env 文件

• 路径：~/MCP/MCP DOC Server/docs-mcp-server-main/.env
• 使用文本编辑器（如 TextEdit、记事本、VSCode）打开。

2. 填写你的 OpenRouter 信息

用以下内容替换（或补充）你的 .env 文件：

OPENAI_API_KEY=你的OpenRouter Key
OPENAI_API_BASE=https://openrouter.ai/api/v1
MODEL_ID=qwen/qwen2.5-vl-3b-instruct:free

说明：

• OPENAI_API_KEY 使用你的 OpenRouter Key（如上例）。
• OPENAI_API_BASE 固定为 https://openrouter.ai/api/v1。
• MODEL_ID 填写 qwen/qwen2.5-vl-3b-instruct:free。

3. 保存 .env 文件

4. 重启 MCP Server

• 关闭之前的 MCP Server 终端窗口（如有）。
• 在 MCP 目录下重新运行：

npm run dev:server

• 等待出现 Build success、Watching for changes 字样。

---

如遇到任何问题，请将报错内容发给开发者或技术支持。

开发与高级设置

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

从源代码运行（开发）

这会提供一个隔离环境，并通过 HTTP 端点公开服务。

1. 克隆仓库：

   git clone https://github.com/arabold/docs-mcp-server.git # Replace with actual URL if different
   cd docs-mcp-server
   

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

   cp .env.example .env
   # Edit .env and add your OPENAI_API_KEY
   

3. 构建 Docker 镜像：

   docker build -t docs-mcp-server .
   

4. 运行 Docker 容器：

   # Option 1: Using a named volume (recommended)
   # Docker automatically creates the volume 'docs-mcp-data' if it doesn't exist on first run.
   docker run -i --env-file .env -v docs-mcp-data:/data --name docs-mcp-server docs-mcp-server
   
   # Option 2: Mapping to a host directory
   # 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 目录。服务会将 documents.db 文件存储在 /data 目录中（由 Dockerfile 中的 DOCS_MCP_STORE_PATH 配置）。这样，即使容器停止或移除，已索引的文档也能保留。
   • --name docs-mcp-server：为容器指定一个便于使用的名称。

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

此方法适用于为项目贡献代码或运行尚未发布的版本。

1. 克隆仓库：

   git clone https://github.com/arabold/docs-mcp-server.git # Replace with actual URL if different
   cd docs-mcp-server
   

2. 安装依赖：

   npm install
   

3. 构建项目： 这会将 TypeScript 编译为 JavaScript，并输出到 dist/ 目录。

   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）

注意： 这种 .env 文件设置主要适用于从源代码运行服务或使用 Docker 的情况。使用 npx 集成方式时，OPENAI_API_KEY 会直接在 MCP 配置文件中设置。

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

   cp .env.example .env
   

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

   # Required: Your OpenAI API key for generating embeddings.
   OPENAI_API_KEY=your-api-key-here
   
   # Optional: Your OpenAI Organization ID (handled automatically by LangChain if set)
   OPENAI_ORG_ID=
   
   # Optional: Custom base URL for OpenAI API (e.g., for Azure OpenAI or compatible APIs)
   OPENAI_API_BASE=
   
   # Optional: Embedding model name (defaults to "text-embedding-3-small")
   # Examples: text-embedding-3-large, text-embedding-ada-002
   DOCS_MCP_EMBEDDING_MODEL=
   
   # Optional: Specify a custom directory to store the SQLite database file (documents.db).
   # If set, this path takes precedence over the default locations.
   # Default behavior (if unset):
   # 1. Uses './.store/' in the project root if it exists (legacy).
   # 2. Falls back to OS-specific data directory (e.g., ~/Library/Application Support/docs-mcp-server on macOS).
   # 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 Release。

你需要做的事：

• 使用 Conventional Commits。
• 将更改合并到 main。
• 准备好发布时，在 GitHub 的 Actions 选项卡中手动触发发布。

自动化会处理： 更新变更日志、升级版本、创建标签、发布到 npm、创建 GitHub Release。

架构

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

值得一提的是，本项目绝大多数代码都是由 AI 助手 Cline 利用这个 MCP 服务的能力生成的。