MCP Documentation Server：让 AI 编程助手真正读懂你的文档

想象一个场景：你维护着一套内部 API 文档，Claude Code 或 Cursor 每次写代码时却对你的接口一无所知，只能靠猜测。传统的 MCP 服务器能解决一部分问题，但大多数只是暴露几个 CLI 工具，AI 依然无法真正理解文档的语义关联。MCP Documentation Server 正是为了填补这个空白而诞生的——它将文档转化为可检索的语义向量，让 AI 编码助手在写代码时实时查阅、精准搜索你的整个知识库。

这个项目由独立开发者 Andrea Bravaccino 创建，最初是为了解决自己在使用 Claude Code 时遇到的信息缺失问题。经过多个版本迭代，项目已形成完整的产品形态：文档管理、语义搜索、Web 界面、REST API，四位一体。截至目前，该项目在 GitHub 获得 333 颗星，被标记为 MCP Registry 官方收录项目。

图1：MCP Documentation Server 已纳入 Model Context Protocol 官方注册表

一、技术架构：本地优先的向量检索引擎

项目采用 TypeScript 开发，运行在 Node.js 之上，无需任何外部数据库或云服务。整体架构围绕 FastMCP 框架构建，核心组件分为三层：

表现层包含两个入口：FastMCP 服务（通过 stdio 与 MCP 客户端通信）和 Express Web 服务器（监听 3080 端口提供 REST API 和 Dashboard）。每个 MCP 工具都有对应的 REST 端点，AI 代理可以通过 REST API 直接查询，避免将工具 Schema 注入对话上下文的开销。

业务层以 DocumentManager 为核心，负责文档的全生命周期管理。添加文档时，先由 IntelligentChunker 执行 Parent-Child 分块策略：文档首先被拆分为大块 parent chunks 以保持完整语义上下文，再将每个 parent 进一步拆分为小块 child chunks 用于精确向量匹配。查询时系统自动去重，确保 AI 收到的既是匹配片段又有完整上下文。

数据层使用 Orama 向量数据库存储文档和分块数据，所有数据持久化为二进制文件（orama-docs.msp、orama-chunks.msp、orama-parents.msp），存储在 ~/.mcp-documentation-server/data/ 目录下，无需额外部署 PostgreSQL 或 Elasticsearch 等外部服务。

图2：Orama — 项目使用的本地向量数据库引擎

二、核心功能：从文档到答案的完整管道

2.1 文档上传与管理

支持三种文件格式：.txt、.md 和 .pdf。用户可以通过 Web 界面拖拽上传，也可以将文件放入 uploads/ 文件夹后调用 process_uploads 批量处理。对于 PDF 文件，系统调用 unpdf 库提取文本内容，再交给分块器处理。

上传后的文档被自动分块、计算向量嵌入，然后存入 Orama 数据库。每篇文档都有独立的元数据字段（可自定义键值对），方便按类别、版本或部门进行组织和过滤。

2.2 语义搜索与上下文窗口

搜索功能提供三个层级：

跨文档混合搜索（search_all_documents）结合全文检索和向量相似度，返回全局最相关的分块结果。单文档内搜索（search_documents）用于在特定文档中定位内容。上下文窗口（get_context_window）是项目的一个亮点功能：给定任意分块 ID，系统返回该分块周围的内容块，让 AI 获得比精确匹配更丰富的背景信息。

2.3 本地向量嵌入与可选 AI 增强

向量嵌入默认使用 Transformers.js 在本地推理（模型：Xenova/all-MiniLM-L6-v2，384 维），无需 GPU 也可运行，首次启动时自动下载模型文件（80-420MB）。如对搜索质量有更高要求，可切换到 Xenova/paraphrase-multilingual-mpnet-base-v2（768 维）以提升多语义理解能力。

对于更复杂的文档理解需求，项目集成了 Google Gemini 作为可选的 AI 搜索后端。设置 GEMINI_API_KEY 环境变量后，调用 search_documents_with_ai 工具即可获得 Gemini 对文档内容的深度分析。需要注意的是，切换嵌入模型会导致已有索引失效，需要重新添加所有文档。

图3：FastMCP — 项目使用的 MCP 框架

三、Web UI：零配置的文档管理界面

项目内置完整的 Web 界面，随 MCP Server 启动自动在 http://localhost:3080 开放。Dashboard 提供文档统计概览，Documents 页面支持查看、搜索和删除操作，Upload 页面支持拖拽上传。AI Search 页面则用于配置 Gemini API 并进行 AI 增强搜索。

Web UI 完全由前端实现（src/public/index.html），通过 REST API 与后端通信，无需额外的 Web 服务器进程。这种 All-in-One 的设计使得部署极为简单：一行 npx -y @andrea9293/mcp-documentation-server 即可同时启动 MCP 服务和 Web 界面。

四、MCP 工具生态：AI 代理的标准化接口

项目的核心价值在于为 AI 编码代理提供了标准化的文档访问接口。通过 Model Context Protocol，Claude Code、Cursor、OpenCode 等工具可以将项目文档库作为外部知识源，在写代码时实时查询。这解决了大型代码库、新框架文档、内部 API 手册等场景下 AI 助手"信息不对称"的根本问题。

项目还提供了 skills/documentation-server/SKILL.md，可通过 npx skills add 命令安装到 AI 代理中，使其直接了解所有 REST API 端点的用法和示例，实现开箱即用。

作者头像

图4：项目作者 Andrea Bravaccino

五、部署方式与系统要求

推荐部署方式：通过 npm 注册表直接运行，无需克隆仓库：

{
  "mcpServers": {
    "documentation": {
      "command": "npx",
      "args": ["-y", "@andrea9293/mcp-documentation-server"]
    }
  }
}

环境变量全部为可选项，默认值即可运行：

| 变量 | 默认值 | 说明 | |---|---| | MCP_BASE_DIR | ~/.mcp-documentation-server | 数据存储根目录 | | MCP_EMBEDDING_MODEL | Xenova/all-MiniLM-L6-v2 | 向量嵌入模型 | | START_WEB_UI | true | 是否启动 Web 界面 | | WEB_PORT | 3080 | Web 服务端口 |

硬件需求极低：无需 GPU，2GB RAM + 1GB 磁盘即可运行。首次启动需联网下载嵌入模型（80-420MB），之后完全离线可用。

项目未提供 Dockerfile 或 docker-compose.yml，无法通过容器化部署，这是目前最大的部署局限性。对于需要在服务器环境统一管理的团队，需要自行编写 Dockerfile。

六、技术亮点与局限性

值得肯定的亮点：

真正本地优先：Orama 向量数据库 + Transformers.js 本地推理，零外部依赖，隐私数据不出本地
Parent-Child 分块策略：解决了传统向量检索"精确但不连贯"的问题，保证 AI 获得既有匹配又有上下文的答案
MCP + REST API 双接口：兼顾 MCP 生态兼容性和 AI 代理的轻量级调用需求
多文件格式支持：.txt/.md/.pdf 全面覆盖，内置 PDF 文本提取

需要正视的局限：

无容器化支持：缺少 Dockerfile，服务器部署需要自行处理 Node.js 环境
单节点本地存储：数据存储在本地文件系统，多机共享需要额外方案（如 NFS）
模型切换成本高：切换嵌入模型需重建全部索引，缺乏增量更新机制
中文语义支持有限：默认模型对中文长句的语义理解能力不如英文，多语言场景建议使用 paraphrase-multilingual-mpnet-base-v2

七、行业意义与增长趋势

MCP Documentation Server 诞生于 Model Context Protocol 生态快速发展的时期。随着 Claude Code、Cursor 等 AI 编程工具的普及，如何让 AI 高效利用项目文档成为新的痛点。相比传统的全文搜索引擎，该项目通过向量语义检索大幅提升了搜索质量；相比云端 RAG 服务，它又保持了本地部署的隐私性和零订阅成本优势。

项目的增长轨迹（GitHub 333 Stars，纳入 MCP 官方 Registry）反映出开发者社区对"本地化 RAG + MCP 集成"这一组合模式的认可。随着 MCP 协议成为 AI 代理工具调用的主流标准，预计这类文档增强工具的需求将持续增长。

Transformers.js

图5：Transformers.js — 项目本地 AI 推理的核心依赖

技术标签：Model Context Protocol · FastMCP · Orama Vector DB · Transformers.js · Express · TypeScript · 本地 RAG · 语义搜索

许可证：MIT · 主语言：TypeScript

MCP Documentation Server：让 AI 编程助手真正读懂你的文档

图1：MCP Documentation Server 已纳入 Model Context Protocol 官方注册表

一、技术架构：本地优先的向量检索引擎

项目采用 TypeScript 开发，运行在 Node.js 之上，无需任何外部数据库或云服务。整体架构围绕 FastMCP 框架构建，核心组件分为三层：

图2：Orama — 项目使用的本地向量数据库引擎

二、核心功能：从文档到答案的完整管道

2.1 文档上传与管理

2.2 语义搜索与上下文窗口

搜索功能提供三个层级：

2.3 本地向量嵌入与可选 AI 增强

图3：FastMCP — 项目使用的 MCP 框架

三、Web UI：零配置的文档管理界面

四、MCP 工具生态：AI 代理的标准化接口

作者头像

图4：项目作者 Andrea Bravaccino

五、部署方式与系统要求

推荐部署方式：通过 npm 注册表直接运行，无需克隆仓库：

{
  "mcpServers": {
    "documentation": {
      "command": "npx",
      "args": ["-y", "@andrea9293/mcp-documentation-server"]
    }
  }
}

环境变量全部为可选项，默认值即可运行：

硬件需求极低：无需 GPU，2GB RAM + 1GB 磁盘即可运行。首次启动需联网下载嵌入模型（80-420MB），之后完全离线可用。

六、技术亮点与局限性

值得肯定的亮点：

真正本地优先：Orama 向量数据库 + Transformers.js 本地推理，零外部依赖，隐私数据不出本地
Parent-Child 分块策略：解决了传统向量检索"精确但不连贯"的问题，保证 AI 获得既有匹配又有上下文的答案
MCP + REST API 双接口：兼顾 MCP 生态兼容性和 AI 代理的轻量级调用需求
多文件格式支持：.txt/.md/.pdf 全面覆盖，内置 PDF 文本提取

需要正视的局限：

无容器化支持：缺少 Dockerfile，服务器部署需要自行处理 Node.js 环境
单节点本地存储：数据存储在本地文件系统，多机共享需要额外方案（如 NFS）
模型切换成本高：切换嵌入模型需重建全部索引，缺乏增量更新机制
中文语义支持有限：默认模型对中文长句的语义理解能力不如英文，多语言场景建议使用 paraphrase-multilingual-mpnet-base-v2

七、行业意义与增长趋势

Transformers.js

图5：Transformers.js — 项目本地 AI 推理的核心依赖

技术标签：Model Context Protocol · FastMCP · Orama Vector DB · Transformers.js · Express · TypeScript · 本地 RAG · 语义搜索

许可证：MIT · 主语言：TypeScript