🚀 MCP Server for Document Processing

🚀 文档处理 MCP 服务

🔗 关于模型上下文协议（MCP）

模型上下文协议（MCP） 是 Anthropic 创建的一项新标准，旨在让 AI 助手能够访问外部工具和数据源。通过连接到此类 MCP 服务等专用服务，该协议可以让 AI 模型扩展训练数据之外的能力。

通过实现 MCP 标准，此服务可让 AI 助手查询和检索自定义文档集合中的信息，从而利用你的特定内容扩展其知识库。

🧠 使用最新信息扩展大模型的知识

此模型上下文协议（MCP）服务可帮助你克服大模型最显著的局限之一：知识截止时间。通过创建自己的 MCP 服务，你可以为 AI 助手提供以下方面的最新信息：

• 最新框架文档：使用未包含在大模型训练数据中的内容（React 19、Angular 17、Vue 3.4+ 等）
• 私有代码库：帮助 AI 助手理解专有代码模式和结构
• 技术规范：导入新 API、协议或工具的文档

推荐的数据来源：

• FireCrawl.dev：用于抓取文档网站的强大工具
• 官方 GitHub 仓库：下载 README 和文档
• 技术博客和教程：将重要文章保存为 Markdown 文件

🏗️ 架构

系统由两个主要组件构成：

1. 📝 处理管道：读取 Markdown 和文本文件，对其进行分块、生成嵌入，并将其存储在向量数据库中。
2. 🔌 MCP 服务：通过 MCP 工具提供处理后的内容，让 AI 助手能够搜索和检索相关信息。

💡 使用示例

使用最新框架文档更新 AI 的知识

# Scrape latest React 19 docs using FireCrawl.dev
# Place the saved markdown files in the data/ directory
# Run the pipeline to process the documentation
# Now ask your AI assistant about React 19 features!

使用私有代码库文档

# Export your API documentation as markdown
# Place the markdown files in the data/ directory
# Run the pipeline to process
# Now your AI assistant can help debug issues with your specific APIs!

✅ 先决条件

• Docker：适用于 Windows 或 Mac 的 Docker Desktop，或适用于 Linux 的 Docker Engine
• OpenAI API 密钥（可选）：也可以改用免费的本地嵌入模型
• 支持 MCP 的 AI 助手：例如 Roo 或其他兼容的助手

🛠️ 设置

1. 克隆此仓库：

   git clone https://github.com/donphi/mcp-server.git
   cd mcp-server
   

2. 创建 .env 文件并填写配置：

   # Copy the example file
   cp .env.example .env
   
   # Edit the file with your settings
   nano .env
   

   在 Windows 上，你可以使用记事本编辑 .env 文件。

3. 将 Markdown（.md）和文本（.txt）文件放入 data/ 目录。

⚙️ 配置

你可以在 .env 文件中使用环境变量配置 MCP 服务：

# API Keys
OPENAI_API_KEY=your_openai_api_key_here  # Optional - can use free local embeddings instead
ANTHROPIC_API_KEY=your_anthropic_api_key_here  # Optional

# Pipeline Configuration
CHUNK_SIZE=800                 # Size of text chunks
CHUNK_OVERLAP=120              # Overlap between chunks (in tokens)
BATCH_SIZE=10                  # Batch size for embedding generation
EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2  # Model to use (see options below)
SUPPORTED_EXTENSIONS=.md,.txt,.pdf,.docx,.doc  # Comma-separated list of supported file extensions

# Server Configuration
CLAUDE_MODEL=claude-3-7-sonnet-20240307  # Claude model to use
MAX_RESULTS=10                 # Maximum number of results to return
USE_ANTHROPIC=true             # Whether to use Anthropic API for responses

# Paths
DATA_DIR=/data                 # Directory containing input files
OUTPUT_DIR=/output             # Directory for output files
DB_PATH=/db                    # Directory for vector database
CONFIG_PATH=/config/server_config.json  # Path to server configuration file

📊 嵌入模型

系统支持多种嵌入模型，可将文本转换为向量表示：

免费模型（无需 API 密钥）

这些模型在 Docker 容器内本地运行，无需任何 API 密钥：

• sentence-transformers/all-MiniLM-L6-v2：专为句子和短段落编码设计的紧凑型模型，可高效生成嵌入，适用于快速检索任务。

• BAAI/bge-m3：多用途模型，支持多种检索功能、100 多种语言以及最长 8192 个词元的输入，非常适合全面的检索任务。

• Snowflake/snowflake-arctic-embed-m：针对高质量检索性能进行了优化，能够有效平衡准确性和推理速度。

付费模型（需要 OpenAI API 密钥）

• text-embedding-3-small：针对速度和成本效益进行了优化，同时保持良好的质量
• text-embedding-3-large：质量最高的嵌入（价格较高）

运行管道时，系统会提示你选择要使用的模型。如果你没有 OpenAI API 密钥，系统会自动使用一种免费的本地模型。

🚀 使用

🔄 处理文件

要处理文件并生成嵌入：

docker-compose build pipeline
docker-compose run pipeline

在 Windows 上安装 Docker Desktop 后，可以在命令提示符或 PowerShell 中运行这些命令。

此操作将：

• 提示你选择一个嵌入模型
• 在需要时安装必要的软件包
• 读取 data/ 目录中的所有受支持文件
• 处理内容并将其分块
• 生成嵌入
• 将嵌入存储在向量数据库中（在 db/ 目录中创建 chroma.sqlite3 文件）

**⚠️ 重要后续步骤：**处理完文件后，运行服务前必须先构建服务。请参阅下一节。

🔧 构建 MCP 服务

**必需步骤：**处理完文档后，运行服务前需要先构建服务组件：

docker-compose build server

Windows 用户须知：在运行 MCP 服务前，此步骤至关重要。如果不构建服务镜像，运行服务时会遇到“invalid reference format”错误。

适用于 Linux/macOS 的更新版运行脚本会在服务镜像不存在时自动构建，但仍建议手动构建，以获得更好的性能，并避免首次运行服务时出现意外延迟。

🔌 连接到兼容 MCP 的 AI 助手

⚠️ 提醒：配置 MCP 服务连接前，请确保已完成以下步骤：

1. 构建流水线（docker-compose build pipeline）
2. 运行流水线（docker-compose run pipeline）
3. 构建服务（docker-compose build server）——此步骤至关重要，且经常被遗漏！

需要为 AI 助手配置 MCP 服务。我们提供了用于生成配置的脚本：

适用于 macOS/Linux：

1. 使设置脚本可执行并运行：

   chmod +x setup-mcpServer-json.sh
   ./setup-mcpServer-json.sh
   

2. 此操作将创建配置正确的 mcp-config.json 文件。

3. 将配置添加到 AI 助手中。

适用于 Windows：

1. 双击 setup-mcpServer-json.bat 文件，或在命令提示符中运行：

   setup-mcpServer-json.bat
   

2. 此操作将创建配置正确的 mcp-config.json 文件。

3. 将配置添加到 AI 助手中。

给 Windows 用户的重要提示：run-mcp-server.bat 文件已更新为统一使用 Docker Compose，从而解决部分 Windows 用户遇到的“invalid reference format”错误。如果仍遇到此问题，请确保使用此仓库中的最新批处理文件。

示例：使用 Roo 配置

如果你将 Roo 用作 AI 助手：

1. 运行适用于你平台的设置脚本，生成配置文件
2. 在 Roo 中，点击侧边栏中的“MCP Server”按钮/选项卡
3. 启用“Enable MCP Servers”开关
4. 点击“Edit MCP Settings”
5. 复制并粘贴 mcp-config.json 文件的全部内容
6. 保存设置

🧩 使用 MCP 服务

配置完成后，你可以将 MCP 服务与支持 MCP 的 AI 助手搭配使用。使用 Roo 等兼容助手时，可以通过两种方式使用：

1. 自动模式（设置 autoQuery: true）：像平常一样提问，AI 会自动检查向量数据库，查找相关信息。

   示例：“React 19 的主要功能有哪些？”

2. 显式使用工具：直接要求 AI 使用特定工具。

   示例：“使用 search_content 工具查找有关 React 19 Compiler 的信息。”

🧰 MCP 工具

MCP 服务提供以下工具：

• 📚 read_md_files：处理并检索文件。参数：file_path（可选，指定文件或目录的路径）
• 🔍 search_content：搜索已处理的内容。参数：query（必填，搜索查询）
• 📋 get_context：检索上下文信息。参数：query（必填，上下文查询）、window_size（可选，要检索的上下文项数量）
• 🏗️ project_structure：提供项目信息结构。无参数。
• 💡 suggest_implementation：生成实现建议。参数：description（必填，要实现内容的描述）

📄 支持的文件类型

默认支持以下文件类型：

• Markdown 文件（.md）
• 文本文件（.txt）
• PDF 文件（.pdf）
• Word 文档（.docx、.doc）

你可以在 .env 文件中设置 SUPPORTED_EXTENSIONS 环境变量，以配置其他文件扩展名。

🔄 运行模式

MCP 服务可在以下两种模式下运行：

1. 🤖 完整处理模式：提供 Anthropic API 密钥并将 USE_ANTHROPIC 设置为 true 时，服务将使用 Claude 根据检索到的上下文生成回复。

2. 📋 上下文检索模式：未提供 Anthropic API 密钥或将 USE_ANTHROPIC 设置为 false 时，服务只会检索并返回相关上下文，以便客户端（例如，AI 助手）使用自己的大模型进行处理。

📁 项目结构

mcp-server/
├── Dockerfile.pipeline
├── Dockerfile.server
├── docker-compose.yml
├── requirements.pipeline.txt
├── requirements.server.txt
├── README.md
├── .env.example
├── run-mcp-server.sh       # For macOS/Linux
├── run-mcp-server.bat      # For Windows
├── setup-mcpServer-json.sh # Setup script for macOS/Linux
├── setup-mcpServer-json.bat # Setup script for Windows
├── enhanced_chunking.py
├── inspect_chunks.py
├── run_chunk_analysis.sh
├── setup_enhanced_chunking.sh
├── visualize_chunks.py
├── restart_server.sh
├── chunk_analysis/         # Tools for analyzing chunking methods
│   ├── docker_entrypoint.sh
│   ├── docker-compose.yml
│   ├── Dockerfile
│   ├── inspect_chunks.py
│   ├── README.md
│   ├── run_tests.sh
│   ├── semi_interactive_chunking.py
│   └── test_chunking.py
├── src/
│   ├── pipeline.py
│   ├── server.py
│   └── utils/
│       ├── __init__.py
│       ├── chunking.py
│       ├── embedding.py
│       └── vector_db.py
├── config/
│   ├── pipeline_config.json
│   └── server_config.json
├── data/
│   └── README.md
├── output/
│   └── .gitkeep
└── db/
    └── .gitkeep

❓ 故障排除

• 未找到 Docker：确保已安装并运行 Docker。使用 docker --version 检查。
• “Invalid reference format”错误：此常见错误可能由以下两种原因导致：
  1. 缺少构建步骤：你尝试在构建服务镜像之前运行 MCP 服务。运行服务前，务必先执行 docker-compose build server。
  2. 混用 Docker 和 Docker Compose：Windows 批处理文件已更新为统一使用 Docker Compose。如果仍然遇到此错误，请确保使用的是此仓库中的最新版本批处理文件。
• API 密钥问题：别担心！你可以使用免费的本地嵌入模型，无需任何 API 密钥。
• 缺少 sentence-transformers 包：如果你选择免费模型，系统会自动安装所需的包。
• 未找到 Chroma 数据库：确保已先运行处理文档的流水线。
• 连接问题：确认 MCP 配置中的路径指向正确的运行脚本位置。
• Windows 路径问题：如果在 Windows 上遇到路径问题，请确保 JSON 配置中的路径使用双反斜杠（\\）。
• 嵌入模型不匹配：服务会自动检测创建数据库时使用的模型，并使用相同的模型进行检索。

文档分块问题

分块不一致

如果发现文件之间的分块不一致，可能是由以下原因导致的：

• 文档类型检测系统记住了之前的判定
• 缺少 spaCy 依赖项
• 配置文件与环境变量冲突

解决方案：

• 流水线会在每次运行之间自动重置文档类型记忆
• 确保已安装 spaCy：pip install spacy && python -m spacy download en_core_web_md
• 确认 .env 和配置文件保持一致

PDF 处理

出现以下情况时，PDF 可能无法正确分块：

• PDF 包含扫描图像而非文本
• PDF 格式复杂
• 缺少所需依赖项

解决方案：

• 流水线已改进 PDF 处理，并提供更完善的诊断信息
• 对于扫描版 PDF，可考虑先使用 OCR 进行预处理
• 安装 PyPDF：pip install pypdf

🔬 高级配置

对于高级用例，可以自定义管线和服务：

• 自定义嵌入函数：创建自定义嵌入逻辑
• 文档类型分类：修改文档类型检测方式
• 分块行为：根据特定需求调整分块参数
• 分块分析：使用 /chunk_analysis 中的测试工具比较标准分块方法和增强分块方法：

  # First build the Docker container
  cd chunk_analysis
  docker-compose build
  
  # Then run the tests
  ./run_tests.sh
  

分块策略

管线针对不同文档采用以下分块策略：

• 科学论文：按章节拆分，保留参考文献
• 金融文档：保留表格和数字内容章节
• 技术文档：保留代码块和示例
• 叙述文本：通过 spaCy NLP 使用语义边界
• 通用文档：结合章节标题和语义断点，采取均衡方案

如果可用，所有文档类型均优先使用 SpaCy 进行分块。

📄 许可证

MIT

---

由 donphi 倾情打造 ❤️