MCP文档服务器开放路由

Name: MCP文档服务器开放路由
Author: xinlei413

作者：xinlei4132 星标更新：2025-04-28

安装使用来源：spider==github.com

项目介绍

docs-mcp-server MCP 服务器

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

✨ 主要特性

🌐 多功能抓取： 从各种来源抓取文档，如网站、GitHub、npm、PyPI 或本地文件。
🧠 智能处理： 自动按语义分割内容，并使用您选择的模型（如 OpenAI、Google Gemini、Azure OpenAI、AWS Bedrock、Ollama 等）生成嵌入。
💾 优化存储： 使用 SQLite 和 sqlite-vec 实现高效的向量存储，并使用 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。

🆕 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 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: '这张图片里有什么？' },
      { 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: '您的站点名称'           // 可选
  // 还可加 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）

⚠️ 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: 使用 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: 必需。 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。

确保 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-..." // 必须：替换为您自己的密钥
      },
      "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 标志传递给容器。例如：

# 示例 1：使用 OpenAI 嵌入（默认）
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

# 示例 2：使用兼容 OpenAI 的 API（如 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

# 示例 3a：使用 Google Cloud Vertex AI 嵌入
docker run -i --rm \
  -e OPENAI_API_KEY="your-openai-key" \  # 保持为回退到 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

# 示例 3b：使用 Google 生成式 AI（Gemini）嵌入
docker run -i --rm \
  -e OPENAI_API_KEY="your-openai-key" \  # 保持为回退到 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

# 示例 4：使用 AWS Bedrock 嵌入
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

# 示例 5：使用 Azure OpenAI 嵌入
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-..." // 必须：替换为您自己的密钥
      },
      "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 <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
# 或
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'（默认）。

示例：

# 抓取 URL 并转换为 Markdown
docs-cli fetch-url https://example.com/page.html

抓取文档 (`scrape`)

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

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