# OCR MCP

MCP server che converte **screenshot di pagine web in Markdown strutturato** usando **GLM-OCR (Zhipu)**. Si registra nel `mcp-gateway`: i tool compaiono in Claude come `mcp__mcp-gateway__ocr__*`.

## Tool

| Tool | Cosa fa |
|---|---|
| `ocr_image(image, instructions="")` | OCR di un'immagine già catturata. `image` = base64, data URI, o URL http(s) a un'immagine. |
| `ocr_webpage(url, full_page=True, viewport_width=0, wait_until="networkidle", instructions="")` | Cattura uno screenshot full-page dell'URL con Chromium headless, poi OCR. |
| `ocr_health()` | Stato e configurazione (host GLM-OCR, API style, modello, key, Chromium, tiling). Nessuna chiamata a pagamento. |

I tool **restituiscono il Markdown come testo**. Il server NON scrive file `.md`: gira su un LXC remoto senza accesso al disco locale. È la sessione Claude a salvare il `.md` dove serve (es. _"salva il risultato in ./pagina.md"_).

## Motore OCR — `.env`

Il server è agnostico all'endpoint: si passa da cloud a self-hosted cambiando solo il `.env`.

| Variabile | Cloud Zhipu | vLLM self-hosted |
|---|---|---|
| `GLM_OCR_BASE_URL` | `https://api.z.ai/api/paas/v4` | `http://<host-vllm>:8000` |
| `GLM_OCR_API_STYLE` | `layout_parsing` | `chat` |
| `GLM_OCR_MODEL` | `glm-ocr` | `zai-org/GLM-OCR` |
| `GLM_OCR_API_KEY` | chiave API Zhipu | token del server vLLM |

- `chat` → `POST {BASE}/v1/chat/completions` (OpenAI-compatibile).
- `layout_parsing` → `POST {BASE}/layout_parsing` (endpoint dedicato Zhipu).

Screenshot molto alti: tagliati in tile sovrapposte (`MAX_TILE_HEIGHT` / `TILE_OVERLAP` / `MAX_TILES`) e il Markdown viene ricucito automaticamente.

## Deploy (CT102)

```bash
./deploy/install.sh root@192.168.1.107
```

rsync → `/opt/ocr-mcp`, crea venv, `playwright install --with-deps chromium`, installa e avvia il servizio systemd `ocr-mcp`. Poi su CT102 compila `/opt/ocr-mcp/.env` e `systemctl restart ocr-mcp`.

## Registrazione nel gateway

Su CT102, aggiungere alla lista `upstreams:` in `/etc/mcp-gateway/upstreams.yaml`:

```yaml
- name: ocr
  url: http://127.0.0.1:8011/sse
  tags:
  - core
  - ocr
```

poi `systemctl restart mcp-gateway`.

> Porta **8011**: la 8009 è occupata da `gmail` e la 8008 da un altro servizio. Se va cambiata, aggiornare `config.py`, `.env`, `deploy/ocr-mcp.service` e la voce `upstreams.yaml`. Il tag `core` rende i tool visibili nelle sessioni che caricano il set core del gateway.

## Verifica

- `curl http://127.0.0.1:8011/` → 200 con stato.
- In Claude Code `/mcp` → `mcp__mcp-gateway__ocr__ocr_image | ocr_webpage | ocr_health`.
- Chiamare `ocr_health`, poi `ocr_webpage` su una pagina lunga reale.

## Stack

Python 3.12 · FastMCP (`mcp==1.27.0`) · Uvicorn · httpx · Playwright/Chromium · Pillow. Transport SSE su `/sse`, servizio systemd, log di audit dei job in SQLite (`/var/lib/ocr-mcp/ocr_mcp.db`).