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 返回。

配置

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

嵌入模型配置

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_API_BASE的openai提供程序。

无论您如何运行服务器（Docker、npx 或从源代码），都可以设置这些变量。

运行 MCP 服务器

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

选项 1：使用 Docker（推荐）

对于大多数用户来说，这是推荐的方法。它简单、直接，并且不需要安装 Node.js。

确保 Docker 已安装并正在运行。
配置您的 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": [] } } }
请记住用您的实际 OpenAI API 密钥替换"sk-proj-..."并重新启动应用程序。
**就这样！**现在你的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。

确保已安装 Node.js。
配置您的 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": [] } } }
请记住用您的实际 OpenAI API 密钥替换"sk-proj-..."并重新启动应用程序。
**就这样！**现在你的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

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

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 重定向（默认：跟随重定向）

例子：

# 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）。
--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

版本处理摘要

**抓取：**需要指定有效版本（ XYZ 、 XYZ-pre 、 XY 、 X ）或无版本（适用于无版本控制的文档）。范围（ Xx ）对于抓取无效。
**搜索/查找：**接受特定版本、部分版本或范围（ XYZ 、 XY 、 X 、 Xx ）。如果目标版本不匹配，则回退到最新的旧版本。省略版本号将定位到最新版本。使用--version ""明确搜索将定位到未版本控制的文档。
**未版本控制的文档：**库中可以存储未指定版本的文档（通过在抓取过程中省略--version ）。可以使用--version ""显式搜索这些文档。 find-version命令还会报告是否存在未版本控制的文档以及任何符合语义版本号的文档。

开发和高级设置

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

从源代码运行（开发）

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

克隆存储库：
git clone https://github.com/arabold/docs-mcp-server.git # Replace with actual URL if different cd docs-mcp-server
**创建.env文件：**复制示例并添加您的 OpenAI 密钥（请参阅下面的“环境设置”）。
cp .env.example .env # Edit .env and add your OPENAI_API_KEY
构建 Docker 镜像：
docker build -t docs-mcp-server .
运行 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``/data 。/data 目录是服务器存储其documents.db文件的位置（由 Dockerfile 中的DOCS_MCP_STORE_PATH配置）。这可确保即使容器停止或移除，索引文档也能持久化。
- --name docs-mcp-server ：为容器分配一个方便的名称。
容器内的服务器现在直接使用 Node.js 运行并通过stdio进行通信。

此方法对于为项目做出贡献或运行未发布的版本很有用。

克隆存储库：
git clone https://github.com/arabold/docs-mcp-server.git # Replace with actual URL if different cd docs-mcp-server
安装依赖项：
npm install
**构建项目：**这会将dist/目录中的 TypeScript 编译为 JavaScript。
npm run build
**设置环境：**按照下文“环境设置”中的说明创建并配置.env文件。这对于提供OPENAI_API_KEY至关重要。
跑步：
- 服务器（开发模式）： npm run dev:server （构建、监视和重启）
- 服务器（生产模式）： npm run start （运行预构建代码）
- CLI： npm run cli -- <command> [options]或node dist/cli.js <command> [options]

环境设置（针对 Source/Docker）

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

根据.env.example创建.env文件：
cp .env.example .env
在.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

检查器将提供一个 URL 来访问浏览器中的调试工具。

释放

该项目使用语义发布和常规提交来自动化发布过程。

工作原理：

提交消息：合并到main分支的所有提交都必须遵循常规提交规范。
**手动触发：**当您准备创建新版本时，可以从“操作”选项卡手动触发“发布”GitHub Actions 工作流程。
**semantic-release操作：**确定版本、更新CHANGELOG.md和package.json 、提交、标记、发布到 npm 并创建 GitHub 版本。

您需要做什么：

使用常规提交。
将更改合并到main 。
准备就绪后，从 GitHub 中的“操作”选项卡手动触发发布。

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

建筑学

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

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

Integrations

docs-mcp-server MCP 服务器

✨ 主要特点

概述

配置

嵌入模型配置

向量维度

运行 MCP 服务器

选项 1：使用 Docker（推荐）

选项 2：使用 npx

使用 CLI

使用 Docker CLI

使用 npx CLI

CLI 命令参考

获取单个 URL（ fetch-url ）

抓取文档（ scrape ）

搜索文档（ search ）

查找可用版本（ find-version ）

列出库（ list ）

删除文档（ remove ）

版本处理摘要

开发和高级设置

从源代码运行（开发）

环境设置（针对 Source/Docker）

调试（从源代码）

释放

建筑学

获取单个 URL（ `fetch-url` ）

抓取文档（ `scrape` ）

搜索文档（ `search` ）

查找可用版本（ `find-version` ）

列出库（ `list` ）

删除文档（ `remove` ）