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