23a00c365e
- 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
128 lines
3.3 KiB
Markdown
128 lines
3.3 KiB
Markdown
# 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
|
||
```
|