docs-mcp服务器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)：返回a jobId 立即。
检查作业状态(get_job_status)：检索特定作业的当前状态和进度。
列出活动/已完成的作业(list_jobs)：显示最近和正在进行的作业。
取消作业(cancel_job)：尝试停止正在运行或排队的作业。
搜索文档(search_docs).
列出索引库(list_libraries).
寻找合适的版本(find_version).
删除索引文档(remove_docs).
获取单个URL(fetch_url)：获取URL并将其内容作为Markdown返回。

🆕 OpenRouter API 集成与多模型支持

Chat/Completions 功能

本服务已全面适配 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密钥
OPENAI_API_BASE：OpenRouter API基础推荐 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
人/claude-3.7连接器
谷歌/双子座-2.5-pro评论-03-25
x-ai/grok-3-beta
qwen/qwen2.5-vl-32b指令：免费
deepseek/deepseek-chat-v3-0324：免费
thudm/glm-z1-32b：免费
openrouter/auto
...（详见源码 OPENROUTER_MODELS）

⚠️ Embedding 功能说明

Embedding 功能已禁用！ 本项目当前版本已彻底移除所有 embedding 相关实现和依赖，不再支持向量生成与检索。所有 embedding 相关 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：使用谷歌云顶点AI嵌入

- GOOGLE_APPLICATION_CREDENTIALS: 必修的。 服务帐户JSON密钥文件的路径

- gemini：使用谷歌生成人工智能（Gemini）嵌入

- GOOGLE_API_KEY: 必修的。 您的Google API密钥

- aws：使用AWS基岩嵌入

- AWS_ACCESS_KEY_ID: 必修的。 AWS访问密钥 - AWS_SECRET_ACCESS_KEY: 必修的。 AWS密钥 - AWS_REGION 或 BEDROCK_AWS_REGION: 必修的。 基岩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服务器：

选项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": []
       }
     }
   }

记得更换 "sk-proj-..." 使用实际的OpenAI API密钥，然后重新启动应用程序。

就是这样！ 服务器现在将可供您的AI助手使用。

Docker容器设置：

-i：保持STDIN打开，这对MCP通过stdio进行通信至关重要。
--rm：容器退出时自动移除。
-e OPENAI_API_KEY: 必修的。 设置您的OpenAI API密钥。
-v docs-mcp-data:/data: 坚持所必需的。 挂载一个名为Docker的卷 docs-mcp-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。

确保已安装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": []
       }
     }
   }

记得更换 "sk-proj-..." 使用实际的OpenAI API密钥，然后重新启动应用程序。

就是这样！ 服务器现在将可供您的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  [options]

确保使用相同的卷名(docs-mcp-data 在这个例子中），就像您对服务器所做的那样。任何配置环境变量（请参见配置上面）可以使用传递 -e 标志，就像服务器一样。

使用npx CLI

如果您使用npx运行服务器，也可以将npx用于CLI：

npx -y --package=@arabold/docs-mcp-server docs-cli  [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  [options]

选项：

--no-follow-redirects：禁用以下HTTP重定向（默认：follow redirects）。
--scrape-mode ：HTML处理策略：“fetch”（快速，少JS），“descriptor”（慢速，全JS），”auto”（默认）。

示例：

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

报废文件(`scrape`)

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

docs-cli scrape 
  [options]

选项：

-v, --version ：与抓取的文档关联的特定版本。

- 接受完整版本(1.2.3)，预发布版本(1.2.3-beta.1)，或部分版本(1, 1.2 扩展到 1.0.0, 1.2.0). - 如果省略，文档将被索引为 未版本.

-p, --max-pages ：要抓取的最大页面数（默认值：1000）。
-d, --max-depth ：最大导航深度（默认值：3）。
-c, --max-concurrency ：最大并发请求数（默认值：3）。
--scope ：定义爬网边界：“子页面”（默认）、“主机名”或“域”。
--no-follow-redirects：禁用以下HTTP重定向（默认：follow redirects）。
--scrape-mode ：HTML处理策略：“fetch”（快速，少JS），“descriptor”（慢速，全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 
  [options]

选项：

-v, --version ：要搜索的目标版本或范围。

- 支持精确版本(18.0.0)，部分版本(18)，或范围(18.x). - 如果省略，则搜索 最新的 可用的索引版本。 - 如果特定版本/范围不匹配，它将回退到最新的索引版本 _更老的_ 比目标。 - 搜索 只有未版本 documents，显式传递一个空字符串： --version ""（注：省略 --version 搜索最新，其中 _可能_ 如果不存在其他版本，则取消版本）。

-l, --limit ：最大结果数（默认值：5）。
-e, --exact-match：仅匹配指定的确切版本（禁用回退和范围匹配）（默认值：false）。

示例：

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

查找可用版本(`find-version`)

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

docs-cli find-version 
 [options]

选项：

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

示例：

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

列出库(`list`)

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

docs-cli list

删除文档(`remove`)

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

docs-cli remove 
 [options]

选项：

-v, --version ：要删除的特定版本。如果省略，则删除 未版本 图书馆的文件。

示例：

# 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 ""The 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服务器

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

npm run dev:server

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

______________________________________________________________________

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

开发和高级设置

本节介绍了出于开发目的直接从源代码运行服务器/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：加载环境变量（如 OPENAI_API_KEY)来自您当地的 .env 文件。 - -v docs-mcp-data:/data 或 -v /path/on/your/host:/data: 对坚持至关重要。 这将挂载一个名为Docker的卷（Docker创建 docs-mcp-data 如果需要，自动）或主机目录 /data 容器内的目录。这 /data 目录是服务器存储其 documents.db 文件（由配置 DOCS_MCP_STORE_PATH 在Dockerfile中）。这确保了即使容器被停止或删除，您的索引文档也会保留。 - --name docs-mcp-server：为容器分配一个方便的名称。

容器内的服务器现在直接使用Node.js运行，并通过以下方式进行通信 标准输入输出.

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

克隆存储库：

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

安装依赖项：

   npm install

构建项目：

这将TypeScript编译为JavaScript dist/ 目录。

   npm run build

设置环境：

创建和配置您的 .env 文件，如下面“环境设置”中所述。这对于提供 OPENAI_API_KEY.

运行：

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

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

注：这 .env 文件设置主要是在从源代码运行服务器或使用Docker方法时需要的。使用时 npx 整合方法 OPENAI_API_KEY 直接在MCP配置文件中设置。

创建一个 .env 文件基于 .env.example:

   cp .env.example .env

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

   # 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检查员，构建后可作为包脚本使用：

npx @modelcontextprotocol/inspector node dist/server.js

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

释放

它是如何工作的：

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

你需要做什么：

使用常规承诺。
将更改合并到 main.
在GitHub的Actions选项卡中准备就绪时手动触发发布。

自动化手柄： 变更日志、版本颠簸、标签、npm发布、GitHub发布。

建筑

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

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

DOC Server MCP

快速接入

详细介绍

docs-mcp服务器mcp服务器

✨ 主要特点

概述

🆕 OpenRouter API 集成与多模型支持

Chat/Completions 功能

主要特性

环境变量配置

示例代码

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

更多 API 参数

⚠️ Embedding 功能说明

配置

嵌入模型配置

矢量维度

运行MCP服务器

选项1：使用Docker（推荐）

选项2：使用npx

使用CLI

使用Docker CLI

使用npx CLI

CLI命令参考

获取单个URL(fetch-url)

报废文件(scrape)

搜索文档(search)

查找可用版本(find-version)

列出库(list)

删除文档(remove)

版本处理摘要

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

1. 打开 .env 文件

2. 填写你的 OpenRouter 信息

3. 保存 .env 文件

4. 重启 MCP服务器

开发和高级设置

源代码运行（开发）

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

调试（来源）

释放

建筑

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

获取单个URL(`fetch-url`)

报废文件(`scrape`)

搜索文档(`search`)

查找可用版本(`find-version`)

列出库(`list`)

删除文档(`remove`)