🚀 用于文档处理的 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：适用于 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 文件：

   # 复制示例文件
   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=10                 # 要返回的最大结果数
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 服务器与支持 MCP 的 AI 助手一起使用。 对于像 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 创建