MCP 文档服务器

一个基于TypeScript的模型上下文协议（MCP）服务器，提供本地优先的文档管理和使用嵌入式的语义搜索。该服务器公开了一系列MCP工具，并针对性能进行了优化，包括磁盘持久化、内存索引和缓存。

🚀 AI驱动的文档智能

新！ 增强了Google Gemini AI，用于高级文档分析和上下文理解。提出复杂问题并从文档中获取智能摘要、解释和见解。要获取API密钥，请访问Google AI Studio

关键AI特性：

• 智能文档分析：Gemini AI理解上下文、关系和概念
• 自然语言查询：提问，而不仅仅是关键词
• 智能总结：获得全面概述和解释
• 上下文洞察：了解文档不同部分之间的关联
• 文件映射缓存：避免重新上传相同的文件给Gemini以提高效率

核心能力

🔍 搜索与智能

• AI驱动的搜索 🤖：使用Gemini AI进行高级文档分析，实现上下文理解和智能洞察
• 传统语义搜索：基于嵌入式分块搜索加上内存关键词索引
• 上下文窗口检索：收集周围分块以丰富LLM答案

⚡ 性能与优化

• O(1) 文档查找 和通过DocumentIndex的关键词索引，实现即时检索
• LRU EmbeddingCache 避免重新计算嵌入式并加速重复查询
• 并行分块 和批量处理以加速大型文档的摄入
• 流式文件读取器 处理大型文件而不占用高内存

📁 文件管理

• 智能文件处理：基于复制的存储，自动备份保存
• 完全删除：移除JSON文件及其相关原始文件
• 仅本地存储：无需外部数据库。所有数据都位于~/.mcp-documentation-server/

快速开始

配置MCP客户端

MCP客户端示例配置（例如，Claude Desktop）：

{
  "mcpServers": {
    "documentation": {
      "command": "npx",
      "args": [
        "-y",
        "@andrea9293/mcp-documentation-server"
      ],
      "env": {
            "GEMINI_API_KEY": "your-api-key-here",  // 可选，启用AI驱动的搜索
            "MCP_EMBEDDING_MODEL": "Xenova/all-MiniLM-L6-v2",
      }
    }
  }
}

基本工作流程

• 使用add_document工具添加文档或通过放置.txt、.md或.pdf文件到上传文件夹并调用process_uploads。
• 使用search_documents搜索文档以获取排名靠前的分块命中。
• 使用get_context_window获取相邻分块并为LLMs提供更丰富的上下文。

公开的MCP工具

服务器公开了几种工具（通过Zod模式验证），用于文档生命周期和搜索：

📄 文档管理

• add_document — 添加文档（标题、内容、元数据）
• list_documents — 列出存储的文档和元数据
• get_document — 通过ID检索完整文档
• delete_document — 删除文档及其分块和相关原始文件

📁 文件处理

• process_uploads — 将上传文件夹中的文件转换为文档（分块+嵌入式+备份保存）
• get_uploads_path — 返回绝对上传文件夹路径
• list_uploads_files — 列出上传文件夹中的文件

🔍 搜索与智能

• search_documents_with_ai — 🤖 使用Gemini的AI驱动搜索 进行高级文档分析（需要GEMINI_API_KEY）
• search_documents — 在文档内进行语义搜索（返回分块命中和LLM提示）
• get_context_window — 返回围绕目标分块索引的分块窗口

配置与环境变量

通过环境变量配置行为。重要选项：

• MCP_EMBEDDING_MODEL — 嵌入式模型名称（默认：Xenova/all-MiniLM-L6-v2）。更改模型需要重新添加文档。
• GEMINI_API_KEY — Google Gemini API密钥 用于AI驱动的搜索功能（可选，启用search_documents_with_ai）。
• MCP_INDEXING_ENABLED — 启用/禁用DocumentIndex（真/假）。默认：true。
• MCP_CACHE_SIZE — LRU嵌入式缓存大小（整数）。默认：11000。
• MCP_PARALLEL_ENABLED — 启用并行分块（真/假）。默认：true。
• MCP_MAX_WORKERS — 分块/索引的并行工作者数量。默认：4。
• MCP_STREAMING_ENABLED — 启用大型文件的流式读取。默认：true。
• MCP_STREAM_CHUNK_SIZE — 流式缓冲区大小（字节）。默认：65536（64KB）。
• MCP_STREAM_FILE_SIZE_LIMIT — 切换到流式路径的阈值（字节）。默认：10485760（10MB）。

示例.env（当变量未设置时应用默认值）：

MCP_INDEXING_ENABLED=true          # 启用O(1)索引（默认：true）
GEMINI_API_KEY=your-api-key-here   # Google Gemini API密钥（可选）
MCP_CACHE_SIZE=1000                # LRU缓存大小（默认：1000）
MCP_PARALLEL_ENABLED=true          # 启用并行处理（默认：true）
MCP_MAX_WORKERS=4                  # 并行工作者数量（默认：4）
MCP_STREAMING_ENABLED=true         # 启用流式传输（默认：true）
MCP_STREAM_CHUNK_SIZE=65536        # 流式传输块大小（默认：64KB）
MCP_STREAM_FILE_SIZE_LIMIT=10485760 # 流式传输阈值（默认：10MB）

默认存储布局（数据目录）：

~/.mcp-documentation-server/
├── data/      # 文档JSON文件
└── uploads/   # 放置文件（.txt, .md, .pdf）以导入

使用示例

基本文档操作

通过MCP工具添加文档：

{
  "tool": "add_document",
  "arguments": {
    "title": "Python基础",
    "content": "Python是一种高级编程语言...",
    "metadata": {
      "category": "编程",
      "tags": ["python", "教程"]
    }
  }
}

搜索文档：

{
  "tool": "search_documents",
  "arguments": {
    "document_id": "doc-123",
    "query": "变量赋值",
    "limit": 5
  }
}

🤖 AI驱动的搜索示例

高级分析（需要GEMINI_API_KEY）：

{
  "tool": "search_documents_with_ai",
  "arguments": {
    "document_id": "doc-123",
    "query": "解释主要概念及其关系"
  }
}

复杂问题：

{
  "tool": "search_documents_with_ai",
  "arguments": {
    "document_id": "doc-123",
    "query": "关键架构模式是什么，它们是如何协同工作的？"
  }
}

总结请求：

{
  "tool": "search_documents_with_ai",
  "arguments": {
    "document_id": "doc-123",
    "query": "总结核心原则并提供示例"
  }
}

上下文增强

获取上下文窗口：

{
  "tool": "get_context_window",
  "arguments": {
    "document_id": "doc-123",
    "chunk_index": 5,
    "before": 2,
    "after": 2
  }
}

何时使用AI驱动的搜索：

• 复杂问题："这些概念是如何相互关联的？"
• 总结："给我一个主要原则的概述"
• 分析："关键模式及其权衡是什么？"
• 解释："如果我是新手，如何解释这个主题？"
• 比较："比较这些不同的方法"

性能优势：

• 智能缓存：文件映射防止重新上传相同内容

• 高效处理：只有相关部分由Gemini分析

• 上下文结果：更准确和全面的答案

• 自然交互：用普通英语提问

• 嵌入式模型在首次使用时下载；某些模型可能需要几百MB的下载量。

• DocumentIndex持久化索引文件并在必要时可以重建。

• EmbeddingCache可以通过调用process_uploads、发出精心策划的查询或在可用时使用预加载API来预热。

嵌入式模型

通过MCP_EMBEDDING_MODEL环境变量设置：

• Xenova/all-MiniLM-L6-v2（默认） - 快速，质量好（384维）
• Xenova/paraphrase-multilingual-mpnet-base-v2（推荐） - 最佳质量，多语言（768维）

系统自动管理每个模型的正确嵌入维度。嵌入式提供商通过getDimensions()暴露其维度。

⚠️ 重要：更改模型需要重新添加所有文档，因为嵌入式不兼容。

开发

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

cd mcp-documentation-server

npm run dev

npm run build

npm run inspect

贡献

1. 分叉仓库
2. 创建功能分支：git checkout -b feature/name
3. 遵循常规提交的消息格式
4. 打开拉取请求

许可证

MIT - 查看LICENSE文件

支持

• 📖 文档
• 🐛 报告问题
• 💬 MCP社区

---

星星历史

使用FastMCP和TypeScript构建 🚀