Mcp Documentation Server

MCP Documentation Server

为 AI 编码 Agent 提供本地优先的文档管理和语义搜索。 无需外部数据库、云 API，也不会受制于供应商。

与其他仅支持命令行的 MCP 服务不同，本服务自带完整的 Web 控制面板——可在浏览器中浏览、搜索、上传和管理知识库。每个 MCP 工具也都提供 REST API，为 AI Agent 提供轻量、无需架构定义的接口。

• 🏠 完全离线运行 — Orama 向量数据库搭配本地 AI 嵌入（Transformers.js）
• 🌐 内置 Web UI — 与 MCP 服务一同自动在端口 3080 上启动
• 🔍 混合搜索 — 全文搜索 + 向量相似度，并采用父子分块
• 🤖 可选 AI 搜索 — 使用 Google Gemini 进行高级文档分析（自备密钥）
• 📁 拖放上传 — 支持 .txt、.md、.pdf
• 📦 已发布到 MCP Registry — 可通过 npx 安装，无需克隆

快速开始

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

在浏览器中打开 http://localhost:3080——Web UI 会自动启动。

🤖 Agent 技能（REST API）— 推荐用于 AI Agent

每个 MCP 工具都可通过 http://127.0.0.1:3080/api/ 上的 REST API 访问。建议从 AI Agent（Claude Code、OpenCode、Gemini CLI、Cursor）通过此方式交互，因为这样无需将 MCP 工具架构加载到对话上下文中——上下文中只会包含响应 JSON。

curl -s http://127.0.0.1:3080/api/config
curl -s http://127.0.0.1:3080/api/documents
curl -s -X POST http://127.0.0.1:3080/api/search-all \
  -H "Content-Type: application/json" \
  -d '{"query": "your search", "limit": 5}'

项目在 skills/documentation-server/SKILL.md 中附带了一个可直接使用的技能文件，其中通过示例向 Agent 介绍了每个端点。安装方法：

npx skills add https://github.com/andrea9293/mcp-documentation-server --skill documentation-server

基本工作流

1. 使用 add_document 添加文档，或将 .txt / .md / .pdf 文件放入 uploads 文件夹，然后调用 process_uploads。
2. 使用 search_all_documents 搜索所有文档，或使用 search_documents 在单个文档中搜索。
3. 使用 get_context_window 获取相邻分块，为大模型提供更广泛的上下文。

Web UI

MCP 服务启动时，Web 界面会自动在端口 3080 上启动。你可以通过 Web UI：

• 📊 控制面板 — 查看所有文档和统计数据概览
• 📄 文档 — 浏览、查看和删除文档
• ➕ 添加文档 — 创建包含标题、内容和元数据的文档
• 🔍 搜索全部 — 对所有文档进行语义搜索
• 🎯 在文档中搜索 — 在指定文档中搜索
• 🤖 AI 搜索 — 由 Gemini 提供支持的分析（需设置 GEMINI_API_KEY）
• 📁 上传文件 — 拖放文件并将其处理到知识库中
• 🪟 上下文窗口 — 查看特定索引附近的分块

配置 MCP 客户端

最简配置

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

使用环境变量（均为可选）

{
  "mcpServers": {
    "documentation": {
      "command": "npx",
      "args": ["-y", "@andrea9293/mcp-documentation-server"],
      "env": {
        "MCP_BASE_DIR": "/path/to/workspace",
        "GEMINI_API_KEY": "your-api-key-here",
        "MCP_EMBEDDING_MODEL": "Xenova/all-MiniLM-L6-v2",
        "START_WEB_UI": "true",
        "WEB_HOST": "127.0.0.1",
        "WEB_PORT": "3080"
      }
    }
  }
}

所有环境变量均为可选。未设置 GEMINI_API_KEY 时，只能使用基于本地嵌入的搜索工具。

MCP 工具

服务会注册以下工具（全部通过 Zod 架构验证）：

📄 文档管理

工具	描述
add_document	添加文档（标题、内容、可选元数据）
list_documents	列出所有文档及其元数据和内容预览
get_document	根据 ID 获取文档的完整内容
delete_document	删除文档、其分块、数据库条目及相关文件

📁 文件处理

工具	描述
process_uploads	处理 uploads 文件夹中的所有文件（分块 + 嵌入）
get_uploads_path	返回 uploads 文件夹的绝对路径
list_uploads_files	列出 uploads 文件夹中的文件及其大小和格式信息
get_ui_url	返回 Web UI URL（例如 http://localhost:3080）——可用于打开仪表板，或在浏览器中定位 uploads 文件夹

🔍 搜索

工具	描述
search_documents	在指定文档中进行语义向量搜索
search_all_documents	跨文档混合搜索（全文 + 向量）
get_context_window	返回指定分块索引附近的分块窗口
search_documents_with_ai	🤖 使用 Gemini 进行 AI 驱动的搜索（需要 GEMINI_API_KEY）

配置

通过环境变量或项目根目录中的 .env 文件进行配置：

变量	默认值	描述
MCP_BASE_DIR	~/.mcp-documentation-server	数据存储的根目录
MCP_EMBEDDING_MODEL	Xenova/all-MiniLM-L6-v2	嵌入模型名称
GEMINI_API_KEY	—	Google Gemini API 密钥（启用 search_documents_with_ai）
MCP_CACHE_ENABLED	true	启用/禁用 LRU 嵌入缓存
START_WEB_UI	true	设置为 false 可禁用内置 Web 界面
WEB_HOST	127.0.0.1	Web UI 的绑定地址（使用 0.0.0.0 可对所有网络接口开放）
WEB_PORT	3080	Web UI 的端口
MCP_STREAMING_ENABLED	true	为大型文件启用流式读取
MCP_STREAM_CHUNK_SIZE	65536	流式缓冲区大小，单位为字节（64KB）
MCP_STREAM_FILE_SIZE_LIMIT	10485760	切换到流式读取的阈值（10MB）

存储布局

~/.mcp-documentation-server/     # Or custom path via MCP_BASE_DIR
├── data/
│   ├── orama-chunks.msp         # Orama vector DB (child chunks + embeddings)
│   ├── orama-docs.msp           # Orama document DB (full content + metadata)
│   ├── orama-parents.msp        # Orama parent chunks DB (context sections)
│   ├── migration-complete.flag   # Written after legacy JSON migration
│   └── *.md                     # Markdown copies of documents
└── uploads/                     # Drop .txt, .md, .pdf files here

嵌入模型

通过 MCP_EMBEDDING_MODEL 设置：

模型	维度	备注
Xenova/all-MiniLM-L6-v2	384	默认模型——速度快，质量好
Xenova/paraphrase-multilingual-mpnet-base-v2	768	推荐——质量最佳，支持多语言

模型会在首次使用时下载（约 80–420 MB）。向量维度由提供程序自动确定。

⚠️ 重要：更改嵌入模型需要重新添加所有文档——不同模型生成的嵌入彼此不兼容。维度发生变化时，Orama 数据库会自动重新创建。

架构

Server (FastMCP, stdio)
  ├─ Web UI (Express, port 3080)
  │    └─ REST API → DocumentManager
  └─ MCP Tools
       └─ DocumentManager
            ├─ OramaStore          — Orama vector DB (chunks DB + docs DB + parents DB), persistence, migration
            ├─ IntelligentChunker  — Parent-child chunking (code, markdown, text, PDF)
            ├─ EmbeddingProvider   — Local embeddings via @xenova/transformers
            │    └─ EmbeddingCache — LRU in-memory cache
            └─ GeminiSearchService — Optional AI search via Google Gemini

• OramaStore 管理三个 Orama 实例：一个用于文档元数据/内容，一个用于带有向量嵌入的子分块，一个用于父分块（上下文片段）。所有实例都会持久化到磁盘上的二进制文件，并在启动时恢复。
• IntelligentChunker 实现父子分块模式：首先将文档拆分为保留完整上下文（章节、段落）的大型父分块，然后将每个父分块进一步拆分为用于精确向量搜索的小型子分块。查询时，结果会按父分块去重，使大模型同时获得匹配片段和更广泛的上下文。
• EmbeddingProvider 延迟加载 Transformers.js 模型以进行本地推理——无需 API 调用。

开发

git clone https://github.com/andrea9293/mcp-documentation-server.git
cd mcp-documentation-server
npm install

npm run dev       # FastMCP dev mode with hot reload
npm run build     # TypeScript compilation
npm run inspect   # FastMCP web UI for interactive tool testing
npm start         # Direct tsx execution (MCP server + web UI)
npm run web       # Run only the web UI (development)
npm run web:build # Run only the web UI (compiled)

贡献

1. Fork 此仓库
2. 创建功能分支：git checkout -b feature/name
3. 提交信息遵循 Conventional Commits
4. 提交拉取请求

许可证

MIT — 详见 LICENSE

支持

• 📖 文档
• 🐛 报告问题
• 💬 MCP 社区
• 🤖 Google AI Studio — 获取 Gemini API 密钥

---

星标历史

使用 FastMCP、Orama 和 TypeScript 构建