AI导哈

文档处理MCP服务器

一个基于Model Context Protocol (MCP)标准的服务器，用于处理和扩展AI助手的外部文档知识库，支持多种文件格式和嵌入模型。

  • by donphi
  • Python
  • 本地部署
  • 9 星标
  • 更新于
在 GitHub 查看 donphi/MCP-Server

使用说明

🚀 文档处理MCP服务器

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

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

通过实施MCP标准，该服务器使AI助手能够从您的自定义文档集合中查询和检索信息，从而有效地用您的特定内容扩展他们的知识库。

🧠 用最新信息扩展法学硕士知识

此模型上下文协议（MCP）服务器允许您克服大型语言模型的最大限制之一：知识截断。通过创建自己的MCP服务器，您可以向AI助手提供有关以下内容的最新信息：

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

推荐数据来源：

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

🏗️ 建筑

该系统由两个主要部分组成：

  1. 📝 处理管线：读取Markdown和文本文件，将其分块，生成嵌入，并将其存储在向量数据库中。
  2. 🔌 MCP服务器：通过MCP工具公开处理后的内容，允许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桌面 视窗 或 苹果电脑，或 Docker引擎 适用于Linux
  • 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/ 目录。

⚙️ 配置

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

# 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密钥：

  • 句子转换器/全MiniLM-L6-v2：为句子和短段落编码设计的紧凑模型，提供适用于快速检索任务的高效嵌入。

  • BAAI/bge-m3：一个支持多种检索功能、100多种语言和多达8192个令牌输入的多功能模型，使其成为全面检索任务的理想选择。

  • 雪花/雪花实际嵌入-m：该模型针对高质量检索性能进行了优化，有效地平衡了准确性和推理速度。

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

  • text-embedding-3-small：针对速度和成本效益进行了优化，质量良好
  • 文本嵌入-3大：最高质量的嵌入物（更贵）

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

🚀 用法

🔄 处理文件

要处理文件并生成嵌入：

docker-compose build pipeline
docker-compose run pipeline

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

这将：

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

⚠️ 重要的下一步： 处理完文件后，您必须在运行服务器之前构建它。请参阅下一节。

🔧 构建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用户很重要：The run-mcp-server.bat 该文件已更新为一致使用Docker Compose，解决了一些Windows用户遇到的“无效引用格式”错误。如果您仍然遇到此问题，请确保您使用的是此存储库中批处理文件的最新版本。

示例：使用Roo进行配置

如果你使用Roo作为你的人工智能助手：

  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_文件：处理和检索文件。参数： file_path （特定文件或目录的可选路径）
  • 🔍 搜索内容：在已处理的内容中搜索。参数： query （必填搜索查询）
  • 📋 get_text：检索上下文信息。参数： query （所需的上下文查询）， window_size （要检索的上下文项的可选数量）
  • 🏗️ 工程结构：提供项目结构信息。没有参数。
  • 💡 建议实施：提出实施建议。参数： description （需要说明要实施什么）

📄 支持的文件类型

默认情况下，支持以下文件类型：

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

您可以通过设置来配置其他文件扩展名 SUPPORTED_EXTENSIONS 您的环境变量 .env 文件。

🔄 操作模式

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       # 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.
  • “引用格式无效”错误：出现这种常见错误的原因有两个：
    1. 缺少构建步骤：您试图在不首先构建服务器映像的情况下运行MCP服务器。始终运行 docker-compose build server 在尝试运行服务器之前。
    2. Docker与Docker Compose的融合：Windows批处理文件已更新为一致使用Docker Compose。如果您仍然遇到此错误，请确保您使用的是此存储库中批处理文件的最新版本。
  • API关键问题：别担心！您可以在没有任何API密钥的情况下使用免费的本地嵌入模型。
  • 缺少句子转换包：如果您选择免费型号，系统将自动安装所需的软件包。
  • 找不到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被用作所有文档类型的首选分块方法。

📄 许可证

麻省理工学院

创建于❤️ 靠近 唐菲

相关 MCP