🚀 文档处理的MCP服务器

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

模型上下文协议（MCP）是由Anthropic创建的新标准，旨在使AI助手能够访问外部工具和数据源。该协议允许AI模型通过连接到像这个MCP服务器这样的专用服务来扩展其训练数据之外的能力。

通过实现MCP标准，此服务器使AI助手能够查询并检索来自您自定义文档集合的信息，从而有效地扩展其知识库以包含您的特定内容。

🧠 使用最新信息扩展LLM的知识

此模型上下文协议（MCP）服务器让您克服大型语言模型的一个最大限制：知识截止日期。通过创建自己的MCP服务器，您可以向AI助手提供最新的信息，包括：

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

推荐的数据来源：

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

🏗️ 架构

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

1. 📝 处理管道：读取Markdown和文本文件，将其分块，生成嵌入，并存储在向量数据库中。
2. 🔌 MCP服务器：通过MCP工具公开处理过的内容，允许AI助手搜索和检索相关信息。

💡 示例用例

使用最新框架文档升级AI知识

# 使用FireCrawl.dev抓取最新的React 19文档
# 将保存的Markdown文件放置在data/目录下
# 运行管道处理文档
# 现在可以询问您的AI助手关于React 19的功能了！

使用私有代码库文档

# 将您的API文档导出为Markdown
# 将Markdown文件放置在data/目录下
# 运行管道进行处理
# 现在您的AI助手可以帮助调试与您的特定API相关的问题！

✅ 先决条件

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

🛠️ 设置

1. 克隆此仓库：

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

2. 创建一个.env文件并添加您的配置：

   # 复制示例文件
   cp .env.example .env
   
   # 编辑文件以设置您的选项
   nano .env
   

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

3. 将您的Markdown（.md）和文本（.txt）文件放置在data/目录下。

⚙️ 配置

您可以通过.env文件中的环境变量来配置MCP服务器：

# API密钥
OPENAI_API_KEY=your_openai_api_key_here  # 可选 - 可以使用免费的本地嵌入代替
ANTHROPIC_API_KEY=your_anthropic_api_key_here  # 可选

# 管道配置
CHUNK_SIZE=800                 # 文本块大小
CHUNK_OVERLAP=120              # 块之间的重叠（以token计）
BATCH_SIZE=10                  # 嵌入生成的批处理大小
EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2  # 要使用的模型（参见下方选项）
SUPPORTED_EXTENSIONS=.md,.txt,.pdf,.docx,.doc  # 支持的文件扩展名列表，逗号分隔

# 服务器配置
CLAUDE_MODEL=claude-3-7-sonnet-20240307  # 要使用的Claude模型
MAX_RESULTS=1
USE_ANTHROPIC=true             # 是否使用Anthropic API响应

# 路径
DATA_DIR=/data                 # 包含输入文件的目录
OUTPUT_DIR=/output             # 输出文件的目录
DB_PATH=/db                    # 向量数据库的目录
CONFIG_PATH=/config/server_config.json  # 服务器配置文件路径

📊 嵌入模型

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

免费模型（无需API密钥）

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

• sentence-transformers/all-MiniLM-L6-v2：一种紧凑型模型，设计用于句子和短段落编码，提供高效的嵌入，适合快速检索任务。
• BAAI/bge-m3：一种多功能模型，支持多种检索功能，超过100种语言，输入可达8192个token，非常适合全面检索任务。
• 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服务器之前是至关重要的。如果没有构建服务器镜像，尝试运行服务器时会出现“无效引用格式”错误。

更新后的Linux/macOS运行脚本如果缺少服务器镜像，会自动构建，但建议手动构建以获得更好的性能并避免首次运行服务器时出现意外延迟。

🔌 连接到兼容MCP的AI助手

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

1. 构建管道（docker-compose build pipeline）
2. 运行管道（docker-compose run pipeline）
3. 构建服务器（docker-compose build server） - 这一步至关重要且经常被忽略！

MCP服务器需要与您的AI助手进行配置。我们提供了生成配置的脚本：

对于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用户遇到的“无效引用格式”错误。如果您仍然遇到此问题，请确保您使用的是来自此仓库的最新版本的批处理文件。

示例：配置Roo

如果您使用Roo作为您的AI助手：

1. 根据您的平台运行适当的设置脚本来生成配置文件
2. 在Roo中，点击侧边栏中的“MCP服务器”按钮/标签
3. 启用“启用MCP服务器”切换
4. 点击“编辑MCP设置”
5. 复制并粘贴整个mcp-config.json文件的内容
6. 保存设置

🧩 使用MCP服务器

一旦配置完成，您可以使用支持MCP的AI助手来使用MCP服务器。与兼容助手如Roo一起，您可以使用两种方式：

1. 自动模式（autoQuery: true）：正常提问，AI将自动检查您的向量数据库以获取相关信息。

   示例：“React 19的关键特性是什么？”

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

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

🧰 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助手）使用其自身的LLM进行处理。

📁 项目结构

mcp-server/
├── Dockerfile.pipeline
├── Dockerfile.server
├── docker-compose.yml
├── requirements.pipeline.txt
├── requirements.server.txt
├── README.md
├── .env.example
├── run-mcp-server.sh       # 适用于macOS/Linux
├── run-mcp-server.bat      # 适用于Windows
├── setup-mcpServer-json.sh # macOS/Linux的设置脚本
├── setup-mcpServer-json.bat # Windows的设置脚本
├── enhanced_chunking.py
├── inspect_chunks.py
├── run_chunk_analysis.sh
├── setup_enhanced_chunking.sh
├── visualize_chunks.py
├── restart_server.sh
├── chunk_analysis/         # 分析分块方法的工具
│   ├── 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检查。
• “无效引用格式”错误：此常见错误可能由以下原因引起：
  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中的测试工具比较标准和增强的分块方法：

  # 首先构建Docker容器
  cd chunk_analysis
  docker-compose build
  
  # 然后运行测试
  ./run_tests.sh
  

分块策略

管道使用这些文档特定的分块策略：

• 科学论文：按部分拆分，保留参考文献
• 财务文档：保留表格和数字部分
• 技术文档：保留代码块和示例
• 叙述性文本：使用spaCy NLP的语义边界
• 通用：使用章节标题和语义断点的平衡方法

当可用时，spaCy被用作所有文档类型的首选分块方法。

📄 许可

MIT

---

由donphi用心制作