Files

Tony 23a00c365e feat: async OCR workflow - split submit + poll tools to avoid timeout issues

- Add submit_pdf_for_ocr() - submits immediately, returns task_id
- Add get_ocr_result() - polls for completion, saves Markdown
- Keep batch_ocr_pdf() as deprecated fallback
- Update README with new async usage pattern
- Update pyproject.toml description

2026-05-09 20:53:19 +08:00

3.3 KiB

Raw Blame History

procleaning-mcp

Python MCP Server for PDF OCR batch processing.

Features

Non-blocking OCR - Submit PDF tasks and poll for results later (no blocking)
Batch Processing - Process multiple PDF files in one call
Async Workflow - Decoupled submission and result retrieval to avoid timeouts

Tools

⚠️ NEW: Async Workflow (Recommended)

`submit_pdf_for_ocr`

Submits PDF file(s) for OCR processing. Returns task_id immediately. Does NOT wait for completion.

Parameters:

input_file: Path to a single PDF file
input_dir: Directory containing PDF files
output_dir: Output directory (auto-created)
api_key: OCR API key (optional, reads from OCR_API_KEY env var)
base_url: OCR API base URL (default: https://agent.imqimacau.com)

`get_ocr_result`

Polls for OCR result by task_id. Saves result as Markdown when completed.

Parameters:

task_id: Task ID from submit_pdf_for_ocr
wait_until_completed: Keep polling until done (default: True)
poll_interval: Seconds between polls (default: 3)
max_polls: Maximum polls (default: 120 → max 360s wait)

⏱️ TIMEOUT RULE: 50s (page 1) + 30s × (pages - 1). For an N-page PDF, set max_polls such that max_polls * poll_interval ≥ 50 + 30*(N-1). Example: 10-page PDF → 320s needed → max_polls=120, poll_interval=3 (360s) works.

Usage Example:

1. submit_pdf_for_ocr(input_file="/path/to/doc.pdf")
   → Returns: {"task_id": "abc123", ...}

2. get_ocr_result(task_id="abc123", wait_until_completed=True)
   → Returns: {"status": "completed", "output_file": "/path/to/doc.md", ...}

3. Check the Markdown file at output_file

🗑️ DEPRECATED: `batch_ocr_pdf`

Original synchronous tool. Kept for backward compatibility but NOT recommended. Blocks and may time out with Hermes (default 120s). Use the async tools above instead.

Deployment (For Other Hermes Agents)

This MCP server can be deployed on any machine running Hermes. Follow the steps below.

Prerequisites

Python 3.10+
uv installed (curl -LsSf https://astral.sh/uv/install.sh | sh)
Access to Gitea (or download the source code)
OCR API Key

Step 1: Clone & Install

git clone https://gitea.imqimacau.com/tony-claw/procleaning-mcp.git
cd procleaning-mcp
uv sync

Step 2: Configure API Key

Set your OCR API key as an environment variable:

# Add to shell profile
echo 'export OCR_API_KEY="***"' >> ~/.bashrc
source ~/.bashrc

Or set it in ~/.hermes/config.yaml directly.

Step 3: Add to Hermes Config

Edit ~/.hermes/config.yaml and add the mcp_servers section:

mcp_servers:
  procleaning:
    command: "uv"
    args: ["run", "--project", "/home/USER/procleaning-mcp", "python", "-m", "procleaning_mcp.server"]
    timeout: 300

Important: Replace /home/USER/procleaning-mcp with the actual path on your machine.

Step 4: Restart Hermes

Restart your Hermes agent to load the new MCP server. Two new tools will be available:

mcp_procleaning_submit_pdf_for_ocr
mcp_procleaning_get_ocr_result

Step 5: Test

Run a test in Hermes:

1. submit_pdf_for_ocr(input_file="/path/to/test.pdf")
   → Note the task_id

2. get_ocr_result(task_id="...")
   → Check the output Markdown file

Local Testing

cd procleaning-mcp
uv run python -m procleaning_mcp.server

3.3 KiB Raw Blame History Unescape Escape