Coffee MCP Server

Coffee MCP Server

一个功能强大的文档提取和处理 API 服务，基于 FastAPI 构建，旨在从文档中提取文本、表格并生成嵌入向量。

📋 概述

Coffee MCP Server 提供了一个可靠的 API，用于处理文档（PDF、图像等），并借助先进的 OCR 和文本处理功能提取其内容。服务会异步处理文档，因此适合处理大型文件，而不会阻塞客户端。

主要功能包括：

• 异步文档处理，长时间运行的任务期间 API 仍能响应
• 按页处理 PDF，实时更新状态
• 使用 OCR（光学字符识别）提取文本
• 检测和提取表格
• 生成文本嵌入向量（使用 OpenAI 或其他提供方）
• 使用 MongoDB 持久化跟踪任务和存储结果
• 提供全面端点的 RESTful API
• 通过后台线程处理，保持 API 响应能力

🚀 设置指南

前置条件

• Python 3.8+
• 已安装并运行 MongoDB
• OCR 依赖项：
  • Tesseract OCR 引擎
  • Poppler（用于 PDF 处理）
• 嵌入向量提供方的 API 密钥（OpenAI、Anthropic）

安装

1. 克隆仓库

   git clone <repository-url>
   cd coffee_mcp_server
   

2. 安装依赖项

   项目需要若干 Python 软件包和系统依赖项：

   # Install system dependencies (macOS example)
   brew install tesseract poppler
   
   # Install Python dependencies
   pip install -r requirements.txt
   

   主要依赖项包括：

   • 用于 API 服务的 FastAPI 和 Uvicorn
   • 用于与 MongoDB 交互的 PyMongo
   • 用于生成嵌入向量的 OpenAI 和 Anthropic
   • 用于文档处理的 PyTesseract 和 PDF2Image
   • 用于图像处理的 OpenCV
   • 用于处理各种文件格式的实用工具

3. 环境配置

   在项目根目录中创建一个 .env 文件，并填写以下变量：

   # MongoDB Connection
   MONGODB_URI=mongodb://localhost:27017
   MONGODB_DATABASE=coffee_mcp
   
   # API Keys
   OPENAI_API_KEY=your_openai_api_key
   
   # Optional: Other embedding providers
   # ANTHROPIC_API_KEY=your_anthropic_api_key
   
   # Server Configuration
   PORT=8000
   HOST=localhost
   

   重要：切勿将 .env 文件提交到仓库。请确保将其加入 .gitignore。 使用 .env.example 作为模板，但不要在其中填写实际密钥。

4. 启动 MongoDB

   确保 MongoDB 实例正在运行：

   mongod --dbpath /path/to/data/directory
   

5. 运行服务

   uvicorn app:app --host localhost --port 8000 --reload
   

🔌 API 端点

文档提取 API

POST /v1/extract_data

提交文档以进行提取。

请求：

• Content-Type：multipart/form-data
• 请求体：
  • file：要处理的文档文件（必需）
  • embedding_provider：用于生成嵌入向量的提供方（默认值："openai"）

响应：

{
  "job_id": "65a1f2d3b4c5d6e7f8g9h0i1",
  "status": "pending",
  "message": "Job created and queued for processing."
}

处理流程：

1. 上传文档并创建任务
2. 在后台异步处理文档
3. 客户端会收到一个任务 ID，可用来查询状态
4. 依次进行文本提取、表格检测和嵌入向量生成
5. 将结果存储在 MongoDB 中，以便后续检索

GET /v1/extract_data_job

获取文档提取任务的状态。

请求：

• 查询参数：
  • job_id：要查询的任务 ID（必需）

响应：

{
  "job_id": "65a1f2d3b4c5d6e7f8g9h0i1",
  "status": "processing",
  "progress": 65.0,
  "message": "Processing page 13 of 20...",
  "estimated_completion_time": "2025-05-09T12:45:21.000Z",
  "next_poll_time": 5
}

可能的状态值：

• pending：任务已排队，但尚未开始
• processing：正在处理任务
• completed：任务已成功完成
• failed：任务失败（包含错误消息）

GET /v1/extract_data_result

获取已完成文档提取任务的结果。

请求：

• 查询参数：
  • job_id：要获取结果的任务 ID（必需）
  • page：分页的页码（可选）
  • page_size：每次请求返回的页数（可选，默认值：10）

响应：

{
  "job_id": "65a1f2d3b4c5d6e7f8g9h0i1",
  "status": "completed",
  "filename": "example.pdf",
  "fileFormat": "application/pdf",
  "totalPages": 20,
  "created_at": "2025-05-09T10:15:30.000Z",
  "completed_at": "2025-05-09T10:17:45.000Z",
  "processing_time_seconds": 135,
  "pages": [
    {
      "pageNumber": 1,
      "text": "Full extracted text content...",
      "textChunks": [
        {
          "text": "Text chunk content...",
          "bbox": [100, 200, 300, 400],
          "embeddings": [0.12, 0.34, 0.56, ...],
          "embedding_model": "text-embedding-ada-002"
        }
      ],
      "hasTable": true,
      "tables": [
        {
          "table_id": "table_1",
          "title": "Table Title",
          "rows": 5,
          "columns": 3,
          "data": [["Header1", "Header2", "Header3"], ["Row1Col1", "Row1Col2", "Row1Col3"], ...]
        }
      ]
    }
  ],
  "metadata": {
    "title": "Document Title",
    "author": "Document Author",
    "creation_date": "2025-01-01"
  }
}

使用分页时，只会返回所请求的页面，并附带分页元数据：

{
  "job_id": "65a1f2d3b4c5d6e7f8g9h0i1",
  "status": "completed",
  "filename": "example.pdf",
  "fileFormat": "application/pdf",
  "totalPages": 20,
  "pageCount": 10,
  "currentPage": 1,
  "pageSize": 10,
  "pages": [
    // Only includes the first 10 pages
  ]
}

🛠️ 架构

组件概览

该服务围绕几个关键组件构建：

1. FastAPI 应用（app.py）：主入口和 API 定义
2. API 路由（routes/ragnor_routes.py）：API 端点实现，包含三个主要端点：
   • POST /v1/extract_data：提交文档进行处理
   • GET /v1/extract_data_job：检查任务状态
   • GET /v1/extract_data_result：获取处理结果
3. 文档处理器（utils/ragnor_processor.py）：文档提取的核心处理逻辑
4. 文本提取器（utils/ragnor_text_extractor.py）：使用 Tesseract 进行 OCR 和文本提取
5. 格式处理器（utils/ragnor_format_handlers.py）：针对不同文件类型（PDF、图像）的专用处理器
6. 嵌入生成器（utils/ragnor_embedding_generator.py）：使用多个提供方（OpenAI、Anthropic）生成文本嵌入
7. 数据库模型（db/ragnor_db_models.py）：用于 MongoDB 存储的数据模型
8. 数据库连接（db/db.py）：MongoDB 连接管理

文档处理流程

┌─────────────┐     ┌───────────────┐     ┌────────────────────┐
│ Client      │     │ FastAPI Router │     │ Document Processor │
│ Application │────▶│ (ragnor_routes)│────▶│  (Background Task) │
└─────────────┘     └───────────────┘     └────────────────────┘
                                                      │
                                                      ▼
┌─────────────┐     ┌───────────────┐     ┌────────────────────┐
│ Result      │     │ MongoDB       │     │ Text Extraction    │
│ Retrieval   │◀────│ Storage       │◀────│ & Embedding        │
└─────────────┘     └───────────────┘     └────────────────────┘

1. 文档上传：

   • 客户端将文档上传到 /v1/extract_data
   • 服务端在 MongoDB 中创建任务条目
   • 触发后台任务进行处理

2. 优化的后台处理：

   • 分析文档并检测格式
   • 对于大型 PDF（>10 页），实时逐页处理
   • 将每页转换为图像，并立即使用 OCR 进行处理
   • 每处理完一页，就更新 MongoDB，从而支持实时进度跟踪
   • 后台线程处理可确保在执行密集型 OCR 任务期间 API 仍能保持响应
   • 持续在 MongoDB 中更新进度百分比
   • 对于较小的文档，使用批处理以提高效率

3. 结果获取：

   • 客户端轮询 /v1/extract_data_job 查询状态
   • 处理完成后，客户端从 /v1/extract_data_result 获取结果
   • 大型文档的结果支持分页

🔐 安全注意事项

• API 密钥管理：
  • 将所有 API 密钥（OpenAI、Anthropic）存储在 .env 文件中
  • 重要：切勿将 .env 文件提交到 Git 仓库
  • 使用 .env.example 作为不含实际机密信息的模板
  • 将 .env 添加到 .gitignore 文件中，以防意外提交
  • 如果意外提交了机密信息，请按以下步骤处理：
    1. 使用 git filter-branch 从 Git 历史记录中移除敏感数据
    2. 立即更新所有已泄露的 API 密钥
    3. 确保正确配置了 .gitignore 文件
• 输入验证：验证所有输入，以防止注入攻击
• 错误处理：完善的错误处理可防止敏感详情泄露
• CORS 配置：为 API 配置适当的 CORS 设置
• 安全开发工作流：
  • 使用功能分支进行开发
  • 合并前检查代码中的安全问题
  • 定期更新依赖项，以修补安全漏洞

🔧 性能优化

响应式 PDF 处理

该服务实现了多项优化，确保处理大型 PDF 文档时仍能保持响应能力：

1. 逐页处理：

   • 大型 PDF 会逐页处理
   • 每一页转换完成后会立即处理，而不是等所有页面都转换完成
   • 每页处理完成后都会更新 MongoDB，实时提供状态更新

2. 后台线程处理：

   • 文档处理在后台线程中运行
   • 主 API 线程仍可响应状态查询和其他请求
   • 非阻塞架构支持并发处理多个文档

3. 优化的 MongoDB 交互：

   • 查询支持字符串 ID 和 ObjectId
   • 高效的更新操作最大限度减少数据库开销
   • 以原子方式更新页面数据，避免竞态条件
   • 强健的错误处理机制，并支持自动恢复

4. 灵活的调试图像处理：

   • 可使用 RAGNOR_DEBUG_IMAGES_PATH 环境变量将调试图像保存到可配置的路径
   • 如果未设置该变量，则不会创建调试图像，从而提升性能

内存和性能注意事项

• 处理大型文档（500 页以上）时，OCR 操作需要充足的内存
• 对于超大型文档，可考虑增加服务的内存分配
• 即使在执行高强度处理任务期间，API 仍能保持响应
• 进度更新可帮助客户端准确跟踪长时间运行任务的状态

🧩 开发与扩展

添加新功能

如需为 Coffee MCP Server 添加新功能：

1. 在 utils/ 目录中实现核心功能
2. 在 db/ragnor_db_models.py 中添加任何新模型
3. 在 routes/ 中创建相应路由
4. 更新本文档以反映新功能

测试

运行测试：

pytest

Coffee MCP Server 的建议文件夹结构和命名规范

文件夹结构和命名规范文档链接： docs/folder_structure_and_naming_conventions.md

!NOTE: 文件夹结构和命名规范文档仍在编写中，内容可能会有变更。

📄 许可证

[在此处填写许可证信息]

👥 贡献者

[贡献者名单]

作者

Vijay