docs-mcp服务器mcp服务器
用于获取和搜索第三方软件包文档的MCP服务器。
✨ 主要特点
- 🌐 多功能刮擦: 从网站、GitHub、npm、PyPI或本地文件等不同来源获取文档。
- 🧠 智能处理: 使用您选择的模型(OpenAI、Google Gemini、Azure OpenAI、AWS Bedrock、Ollama等)自动语义拆分内容并生成嵌入。
- 💾 优化存储: 利用SQLite
sqlite-vecFTS5用于强大的全文搜索。 - 🔍 强大的混合搜索: 将向量相似性和跨不同库版本的全文搜索相结合,以获得高度相关的结果。
- ⚙️ 异步作业处理: 使用后台作业队列和MCP/CLI工具高效管理抓取和索引任务。
- 🐳 简单部署: 使用Docker或npx快速启动并运行。
概述
该项目提供了一个模型上下文协议(MCP)服务器,旨在抓取、处理、索引和搜索各种软件库和包的文档。它从指定的URL获取内容,使用语义分割技术将其分割成有意义的块,使用OpenAI生成向量嵌入,并将数据存储在SQLite数据库中。服务器利用 sqlite-vec 用于高效的向量相似性搜索,FTS5用于全文搜索功能,将它们结合起来用于混合搜索结果。它支持版本控制,允许不同库版本(包括未版本化的内容)的文档被清晰地存储和查询。
服务器公开了MCP工具,用于:
- 开始刮擦作业(
scrape_docs):返回ajobId立即。 - 检查作业状态(
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/v1MODEL_ID:默认模型(如openai/gpt-4.1),可选
示例代码```typescript
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)
#### 更多 API 参数
如需支持流式输出、函数调用、system prompt、stop、temperature、max_tokens 等 OpenRouter API 参数,只需通过 `extraBody` 字段传递即可,无需修改底层代码。
## ⚠️ 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。
1. **确保Docker已安装并正在运行。**
1. **配置您的MCP设置:**
**Claude/Cline/Roo配置示例:**
将以下配置块添加到MCP设置文件中(根据需要调整路径):```json
{
"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 旗帜。例如:```bash
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。**
1. **配置您的MCP设置:**
**Claude/Cline/Roo配置示例:**
将以下配置块添加到MCP设置文件中:```json
{
"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:```bash
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:```bash
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 ...).
一般帮助:```bash
docs-cli --help
or
npx -y --package=@arabold/docs-mcp-server docs-cli --help
**命令特定帮助:** (替换 `docs-cli` 随着 `npx...` 命令(如果未全局安装)```bash
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,此命令不会抓取链接或存储内容。```bash
docs-cli fetch-url [options]
**选项:**
- `--no-follow-redirects`:禁用以下HTTP重定向(默认:follow redirects)。
- `--scrape-mode `:HTML处理策略:“fetch”(快速,少JS),“descriptor”(慢速,全JS),”auto”(默认)。
**示例:**```bash
# Fetch a URL and convert to Markdown
docs-cli fetch-url https://example.com/page.html
报废文件(scrape)
从特定库的给定URL中抓取文档并建立索引。```bash
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)。
**示例:**```bash
# Scrape React 18.2.0 docs
docs-cli scrape react --version 18.2.0 https://react.dev/
搜索文档(search)
在索引文档中搜索库,可以选择按版本进行筛选。```bash
docs-cli search [options]
**选项:**
- `-v, --version `:要搜索的目标版本或范围。
- 支持精确版本(`18.0.0`),部分版本(`18`),或范围(`18.x`).
- 如果省略,则搜索 **最新的** 可用的索引版本。
- 如果特定版本/范围不匹配,它将回退到最新的索引版本 _更老的_ 比目标。
- 搜索 **只有未版本** documents,显式传递一个空字符串: `--version ""`(注:省略 `--version` 搜索最新,其中 _可能_ 如果不存在其他版本,则取消版本)。
- `-l, --limit `:最大结果数(默认值:5)。
- `-e, --exact-match`:仅匹配指定的确切版本(禁用回退和范围匹配)(默认值:false)。
**示例:**```bash
# Search latest React docs for 'hooks'
docs-cli search react 'hooks'
查找可用版本(find-version)
检查索引中基于目标的库的最佳匹配版本,并指示是否存在未版本化的文档。```bash
docs-cli find-version [options]
**选项:**
- `-v, --version `:目标版本或范围。如果省略,则查找最新可用版本。
**示例:**```bash
# Find the latest indexed version for react
docs-cli find-version react
列出库(list)
列出存储中当前索引的所有库。```bash
docs-cli list
### 删除文档(`remove`)
删除特定库和版本的索引文档。```bash
docs-cli remove [options]
选项:
-v, --version:要删除的特定版本。如果省略,则删除 未版本 图书馆的文件。
示例:```bash
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 目录下重新运行:```bash
npm run dev:server
- 等待出现 `Build success`、`Watching for changes` 字样。
______________________________________________________________________
如遇到任何问题,把报错内容发给开发者或技术支持即可。
## 开发和高级设置
本节介绍了出于开发目的直接从源代码运行服务器/CLI。现在主要的使用方法是通过公共Docker镜像,如“方法2”所述。
### 源代码运行(开发)
这提供了一个隔离的环境,并通过HTTP端点公开服务器。
1. **克隆存储库:**```bash
git clone https://github.com/arabold/docs-mcp-server.git # Replace with actual URL if different
cd docs-mcp-server
- 创建
.env文件:
复制示例并添加您的OpenAI密钥(请参阅下面的“环境设置”)。```bash
cp .env.example .env
Edit .env and add your OPENAI_API_KEY
1. **构建Docker镜像:**```bash
docker build -t docs-mcp-server .
- 运行Docker容器:```bash
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运行,并通过以下方式进行通信 **标准输入输出**.
此方法对于为项目做出贡献或运行未发布的版本非常有用。
1. **克隆存储库:**```bash
git clone https://github.com/arabold/docs-mcp-server.git # Replace with actual URL if different
cd docs-mcp-server
- 安装依赖项:```bash
npm install
1. **构建项目:**
这将TypeScript编译为JavaScript `dist/` 目录。```bash
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:```bash
cp .env.example .env
1. 在中更新您的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检查员,构建后可作为包脚本使用:bash
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服务器的功能。
