Coffee MCP Server

Coffee MCP Server

FastAPI で構築された強力なドキュメント抽出・処理 API サーバーです。ドキュメントからテキストや表を抽出し、埋め込みを生成するよう設計されています。

📋 概要

Coffee MCP Server は、ドキュメント（PDF、画像など）を処理し、高度な OCR とテキスト処理機能を使ってコンテンツを抽出する堅牢な API を提供します。サーバーはドキュメントを非同期で処理するため、クライアントをブロックすることなく大容量ファイルを処理できます。

主な機能は次のとおりです。

• 長時間実行されるタスクの間も応答性を保つ API による非同期ドキュメント処理
• リアルタイムのステータス更新に対応した、ページ単位の PDF 処理
• OCR（光学文字認識）によるテキスト抽出
• 表の検出と抽出
• テキスト埋め込みの生成（OpenAI またはその他のプロバイダーを使用）
• ジョブ追跡と結果の永続化のための MongoDB ストレージ
• 包括的なエンドポイントを備えた RESTful API
• API の応答性を維持するためのバックグラウンドスレッド処理

🚀 セットアップガイド

前提条件

• Python 3.8+
• MongoDB がインストールされ、実行中であること
• OCR の依存関係：
  • Tesseract OCR エンジン
  • Poppler（PDF 処理用）
• 埋め込みプロバイダー（OpenAI、Anthropic）の API キー

インストール

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
• Body：
  • 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：1 回のリクエストで返すページ数（任意、デフォルト：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）：次の 3 つの主要なエンドポイントを実装します。
   • 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 は一度に 1 ページずつ処理されます
   • すべてのページの変換が完了するのを待たず、変換後すぐに各ページを処理します
   • 各ページの処理完了後に 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