# 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

```bash
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:

```bash
# 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:

```yaml
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

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