{ "document": [ { "type": "base64", "data": "", "mimeType": "image/jpeg" }, { "type": "base64", "data": "", "mimeType": "image/jpeg" } ] } ``` Ogni parte viene inviata al provider Vision separatamente (come se fosse una pagina PDF) e i risultati vengono unificati da `MergeService` con la stessa identica strategia campo-per-campo già usata per il PDF multipagina — vedi [Strategia di merge multipagina](#strategia-di-merge-multipagina). Non esiste una nozione di "questa è la faccia anteriore": il merge semplicemente prende, per ogni campo, il valore con confidence più alta tra tutte le parti fornite. Vincoli: - Ammesso **solo** per parti tutte di tipo immagine (`jpg`/`jpeg`/`png`/`webp`). Un array contenente un PDF o un documento XML/`.p7m` viene rifiutato esplicitamente (`mixed_or_unsupported_document_parts`): un PDF ha già il proprio meccanismo multipagina, un documento strutturato è per natura un'unica unità. - Un array che supera `MAX_DOCUMENT_PARTS` viene rifiutato esplicitamente (`too_many_document_parts`), prima di caricare o elaborare qualunque parte. - Un singolo oggetto (senza array) continua a funzionare esattamente come prima — nessuna modifica per i client esistenti. Questa capacità vive interamente in `ExtractionService`/`documentInputOrPartsSchema`, non nei singoli tool: sia `extract_demographics` che `extract_invoice` la ereditano senza alcuna modifica al proprio file, e un futuro `extract_identity_card` la avrebbe fin dal primo giorno. ## Responsabilità dei layer | Layer | Percorso | Responsabilità | | ------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | Config | `src/config/env.ts` | Unica fonte delle variabili d'ambiente, validate con Zod all'avvio (fail-fast) | | MCP transport | `src/mcp/transport/http.transport.ts` | Endpoint `POST /mcp`, Streamable HTTP stateless | | MCP auth | `src/mcp/auth/bearer.middleware.ts` | Verifica del bearer token in tempo costante, interfaccia `AuthStrategy` | | MCP tools | `src/mcp/tools/*.tool.ts` | Dichiarazione `inputSchema`/`outputSchema`, delega totale la logica a `ExtractionService`. Nessuna logica di business qui | | MCP tools (glue) | `src/mcp/tools/anagrafica.postprocess.ts` | Normalizzazione + validator di dominio per un record anagrafico, condivisa da `extract_demographics` e da cedente/cessionario di `extract_invoice` | | Providers | `src/providers/*.provider.ts` | Interfaccia `VisionProvider` e implementazione `AnthropicVisionProvider`. Il resto del sistema conosce solo l'interfaccia | | Services | `src/services/extraction.service.ts`, `merge.service.ts` | Orchestrazione della pipeline di estrazione (inclusa la scelta della strategy) e strategia di merge multipagina | | Services (strategy) | `src/services/extraction-strategy.ts`, `vision.strategy.ts`, `parser.strategy.ts` | Interfaccia `ExtractionStrategy` e le sue due implementazioni (Vision, Parser deterministico) | | Document | `src/document/loader.ts`, `base64.loader.ts`, `url.loader.ts`, `pdf.renderer.ts` | Caricamento documento (base64/URL con protezioni SSRF) e rendering PDF via `pdftoppm` | | Document (XML/P7M) | `src/document/xml.parser.ts`, `p7m.unwrapper.ts` | Parsing FatturaPA deterministico (no DTD/entità esterne, allegati scartati) ed estrazione del contenuto da una busta `.p7m` (nessuna verifica firma) | | Prompts | `src/prompts/*.system.md` | Prompt di sistema versionati come file, mai hardcodati nel codice | | Schemas | `src/schemas/*.schema.ts` | Contratti Zod di input/output | | Normalizers | `src/normalizers/*` | Normalizzazione dei campi estratti (ragione sociale, P.IVA, indirizzo, telefono, email) | | Validators | `src/validators/*` | Validatori di dominio (P.IVA, Codice Fiscale, SDI, EAN, Natura IVA, ...): non scartano il valore, segnalano in `warnings` | | Utils | `src/utils/*` | Sanitizzazione, retry con backoff, rilevamento MIME/magic bytes (incluso XML/`.p7m`), hash SHA-256, logger | ## Flusso completo di una richiesta ```mermaid sequenceDiagram participant C as Client MCP participant T as HTTP Transport (/mcp) participant A as Auth (Bearer) participant X as ExtractionService participant L as Document Loader participant R as PDF Renderer participant V as VisionProvider participant M as MergeService C->>T: POST /mcp (tools/call extract_demographics) T->>A: verifica Authorization: Bearer alt token assente/non valido A-->>C: 401 (nessun dettaglio) else token valido A->>X: invoca extractStructuredData(document, prompt, schema) X->>L: carica ogni parte (una o più, es. fronte/retro) Note over L: SSRF guard se URL,
verifica magic bytes vs MIME dichiarato,
per ciascuna parte L-->>X: buffer per ogni parte opt una parte è un PDF X->>R: pdftoppm (rendering per pagina, limite MAX_PDF_PAGES) R-->>X: immagini per pagina end loop per ogni pagina X->>V: chiamata Vision (con retry/backoff su timeout, 429, 503) V-->>X: output grezzo X->>X: sanitizzazione + validazione Zod end X->>M: merge multipagina (campo per campo, confidence) M-->>X: risultato unificato + warnings X-->>T: structuredContent T-->>C: 200 JSON (structuredContent) end ``` Questo è il flusso quando il documento è un'immagine o un PDF (entrambi i tool). Se `document` è un array (fronte/retro), ogni parte viene caricata e poi trattata esattamente come una pagina: il "loop per ogni pagina" scorre sull'unione di tutte le pagine di tutte le parti (vedi [Documenti multi-parte (fronte/retro)](#documenti-multi-parte-fronteretro)). Per `extract_invoice` con un documento XML o `.p7m`, la pipeline è diversa a valle del Document Loader: nessun rendering PDF, nessuna chiamata al provider Vision, nessun retry. ```mermaid sequenceDiagram participant X as ExtractionService participant L as Document Loader participant P as ParserExtractionStrategy participant U as p7m.unwrapper.ts participant XP as xml.parser.ts (parseInvoiceXml) X->>L: carica documento (base64 o URL) Note over L: verifica magic bytes:
dichiarazione XML oppure struttura ASN.1/OID PKCS#7 L-->>X: buffer + mimeType (application/xml | application/pkcs7-mime) X->>P: selectStrategy() ha scelto ParserExtractionStrategy opt mimeType è application/pkcs7-mime P->>U: estrae il contenuto dalla busta CMS SignedData Note over U: nessuna verifica di firma/certificato:
fuori scope, fuori dal perimetro OCR U-->>P: XML originale end P->>XP: parseInvoiceXml(xml) Note over XP: DOCTYPE rifiutato, blocco <Allegati> scartato
prima di ogni elaborazione, mai loggato/restituito XP-->>P: dati mappati (confidence 1 per ogni campo) P->>P: validazione Zod (stesso schema del ramo Vision) P-->>X: risultato (un solo "page", MergeService lo restituisce invariato) ``` ## Protocollo MCP - SDK ufficiale `@modelcontextprotocol/sdk`, nessuna implementazione manuale del protocollo. - Trasporto: **solo** Streamable HTTP (`StreamableHTTPServerTransport`), endpoint unico `POST /mcp`. - Modalità **stateless**: nessuna gestione di sessione lato server, `enableJsonResponse: true` per ottenere risposte JSON dirette invece dello streaming SSE opzionale. - **Non** implementati: trasporto `stdio`, trasporto legacy HTTP+SSE. - Entrambi i tool (`extract_demographics`, `extract_invoice`) dichiarano `inputSchema` e `outputSchema` (derivati da Zod) e restituiscono il risultato tramite `structuredContent`, così il client riceve JSON tipizzato nativamente senza dover ri-parsare testo libero. ## Configurazione Tutte le variabili sono validate con Zod all'avvio (`src/config/env.ts`): configurazione invalida ⇒ il processo termina immediatamente con un errore chiaro (fail-fast). Nessun `process.env.X` è utilizzato fuori da questo modulo. Copiare `.env.example` in `.env` e valorizzare: | Variabile | Descrizione | Default | | ------------------------- | ------------------------------------------------------------- | ---------------- | | `ANTHROPIC_API_KEY` | API key del provider Anthropic | — (obbligatoria) | | `VISION_MODEL` | Modello Vision Anthropic da utilizzare | — (obbligatoria) | | `MCP_AUTH_TOKEN` | Bearer token richiesto su `/mcp` | — (obbligatoria) | | `HTTP_PORT` | Porta di ascolto HTTP interna | `3000` | | `TRUST_PROXY` | Rispetta `X-Forwarded-For` (dietro reverse proxy) | `true` | | `RATE_LIMIT_WINDOW_MS` | Finestra del rate limit | `60000` | | `RATE_LIMIT_MAX_REQUESTS` | Richieste massime per finestra (per IP e per token) | `30` | | `MAX_FILE_SIZE_MB` | Dimensione massima **per parte** di documento | `10` | | `MAX_PDF_PAGES` | Numero massimo di pagine PDF elaborabili | `10` | | `PDF_RENDER_DPI` | Risoluzione di rendering PDF (`pdftoppm`) | `150` | | `MAX_DOCUMENT_PARTS` | Numero massimo di parti immagine per richiesta (fronte/retro) | `4` | | `REQUEST_TIMEOUT_MS` | Timeout richiesta HTTP/provider | `60000` | | `MAX_RETRIES` | Tentativi massimi di retry (backoff esponenziale + jitter) | `3` | | `LOG_LEVEL` | Livello di log Pino (`debug`/`info`/`warn`/`error`) | `info` | ## Sicurezza dell'endpoint remoto Il server è esposto su internet e processa dati personali: la sicurezza del confine HTTP è un requisito primario. - **Autenticazione**: header `Authorization: Bearer ` obbligatorio su `/mcp`, confrontato in tempo costante (`crypto.timingSafeEqual`). Richieste senza token o con token errato ⇒ `401`, senza dettagli interni. L'architettura predispone un'interfaccia `AuthStrategy` per una futura migrazione a OAuth 2.1 (non implementata in questa versione). - **Rate limiting**: per IP e per token, configurabile via env. - **Limite dimensione body**: applicato _prima_ del parsing JSON, coerente con `MAX_FILE_SIZE_MB × MAX_DOCUMENT_PARTS` più l'overhead base64 (una richiesta può contenere fino a `MAX_DOCUMENT_PARTS` parti immagine, es. fronte/retro, ciascuna fino a `MAX_FILE_SIZE_MB`). - **Timeout** di richiesta a livello HTTP. - **Header di sicurezza** standard (helmet). - **Nessuna informazione interna** (stack trace, path, versioni) negli errori restituiti al client. - **TLS**: il container espone solo HTTP in chiaro sulla rete interna; la terminazione TLS è demandata a un reverse proxy esterno (vedi sezione nginx). Il server rispetta `X-Forwarded-For` per il rate limiting dietro proxy (`TRUST_PROXY`). - **SSRF** (caricamento documento da URL): solo schema `https`, risoluzione DNS con blocco di IP privati/loopback/link-local e metadata endpoint (`169.254.0.0/16`, `10/8`, `172.16/12`, `192.168/16`, `::1`), blocco dei redirect verso IP privati, timeout e limite dimensione sul download. - **XML (`extract_invoice`)**: qualunque documento con dichiarazione `DOCTYPE` viene rifiutato esplicitamente, prima di qualunque parsing (protezione XXE/entity-expansion in profondità — il parser XML usato [`fast-xml-parser`] non risolve comunque entità esterne per progettazione, ma il rifiuto esplicito non dipende da questa garanzia implicita). Il blocco `` di una FatturaPA viene scartato dalla stringa XML **prima** di qualunque elaborazione: il suo contenuto (spesso un allegato base64 di dimensioni significative) non diventa mai un valore in memoria, non compare nell'output, non viene mai loggato. - **`.p7m` (busta CMS/PKCS#7)**: viene solo **estratto** il contenuto originale firmato. **Non viene eseguita alcuna verifica della firma** (certificato, catena di fiducia, scadenza, revoca): è una scelta di design, non una lacuna — la validità legale di una firma digitale è una valutazione che spetta al gestionale/operatore a valle, non a un servizio di estrazione OCR. Solo le buste CMS SignedData con contenuto incorporato sono supportate; le firme distaccate (detached) sono rifiutate esplicitamente. ## Docker Build multi-stage: stage di build (dipendenze complete, compilazione TypeScript) e stage runtime minimale (`node:20-bookworm-slim` + `poppler-utils` per `pdftoppm`), eseguito come utente non-root, con `HEALTHCHECK` su `GET /health` (non autenticato, senza informazioni interne). ```bash docker compose up -d --build ``` Il container: - è **stateless** e condivisibile tra più client MCP contemporanei; - **non pubblica alcuna porta** sulla rete pubblica: `docker-compose.yml` lega la porta esterna (`3501`, porta interna sempre `3000`) esclusivamente all'indirizzo dell'interfaccia WireGuard locale (`10.10.0.4`, `wg0`), non a `0.0.0.0`; - è raggiungibile solo dal reverse proxy (nginx) che sta dall'altro capo del tunnel WireGuard, su una VPS separata — vedi [Reverse proxy nginx con TLS (certbot)](#reverse-proxy-nginx-con-tls-certbot); - monta `/tmp` come **tmpfs** (`docker-compose.yml`). Motivo: `pdftoppm` non è in grado di scrivere l'immagine renderizzata su stdout (l'argomento `-` come prefisso di output viene trattato come nome di file letterale, non come richiesta di stream), quindi ogni pagina viene scritta in un file temporaneo e riletta in memoria. Montando `/tmp` come tmpfs quei byte restano esclusivamente in RAM e non toccano mai uno storage persistente, in coerenza con il vincolo "documenti mai persistiti su disco". **Questo mount è obbligatorio in produzione**: senza tmpfs, `/tmp` sarebbe disco reale del filesystem del container. ## Reverse proxy nginx con TLS (certbot) > **Nota sul deployment reale di questa istanza**: nginx e la gestione del > certificato (certbot) **non fanno parte di questo progetto** e non vengono > installati/gestiti da esso. Nel deployment attuale il reverse proxy e il > TLS sono già gestiti su una VPS separata, indipendente da questo > repository. Il container qui pubblica solo la porta `3501` sull'interfaccia > WireGuard locale (`wg0`, IP `10.10.0.4`; porta interna sempre `3000`, > numero esterno diverso perché su questo host convivono più server MCP) — > irraggiungibile da chiunque non sia dall'altro capo del tunnel. La > configurazione che segue è mantenuta come **esempio di riferimento > generico** (richiesto da docs/SPEC.md) per chi clona questo progetto e non > dispone già di un proprio reverse proxy con TLS. Più server MCP possono condividere lo stesso dominio, instradati per prefisso di path (`/ocr`, `/rag`, ...) verso upstream diversi, ciascuno sulla propria porta `wg0`. Il backend espone sempre e solo l'endpoint fisso `POST /mcp` (vincolo di docs/SPEC.md, non configurabile), quindi nginx deve riscrivere il path esterno su `/mcp` in fase di `proxy_pass`, non limitarsi a un passthrough: ```nginx upstream mcp_ocr_anagrafica { server 10.10.0.4:3501; } # Esempio: un futuro secondo server MCP (es. RAG) sulla stessa VPS, sulla # propria porta wg0 dedicata, seguirebbe lo stesso schema: # upstream mcp_rag { # server 10.10.0.4:3502; # } server { listen 80; server_name mcp.baldoweb.it; # Redirect verso HTTPS, eccetto la sfida ACME di certbot location /.well-known/acme-challenge/ { root /var/www/certbot; } location / { return 301 https://$host$request_uri; } } server { listen 443 ssl http2; server_name mcp.baldoweb.it; ssl_certificate /etc/letsencrypt/live/mcp.baldoweb.it/fullchain.pem; ssl_certificate_key /etc/letsencrypt/live/mcp.baldoweb.it/privkey.pem; ssl_protocols TLSv1.2 TLSv1.3; # Coerente con MAX_FILE_SIZE_MB × MAX_DOCUMENT_PARTS (10MB × 4) + # overhead base64 (~1.37x) - una richiesta può contenere più parti # immagine (fronte/retro) client_max_body_size 60m; # /ocr esterno -> /mcp interno (endpoint fisso del server OCR anagrafica) location = /ocr { proxy_pass http://mcp_ocr_anagrafica/mcp; proxy_http_version 1.1; proxy_set_header Host $host; proxy_set_header X-Real-IP $remote_addr; proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; proxy_set_header X-Forwarded-Proto $scheme; # Allineati a REQUEST_TIMEOUT_MS (60s di default) proxy_connect_timeout 10s; proxy_send_timeout 70s; proxy_read_timeout 70s; } location = /ocr/health { proxy_pass http://mcp_ocr_anagrafica/health; proxy_set_header Host $host; } # Esempio: un futuro MCP "rag" seguirebbe lo stesso schema, sul proprio # upstream/porta: # location = /rag { # proxy_pass http://mcp_rag/mcp; # ... (stessi header/timeout di cui sopra) # } } ``` Rinnovo certificati con certbot (esempio, container dedicato o cron host): ```bash certbot certonly --webroot -w /var/www/certbot -d mcp.baldoweb.it ``` ## Configurazione client MCP remoti Il server espone internamente un unico endpoint fisso `POST /mcp` (vincolo di docs/SPEC.md). In questo deployment, il reverse proxy lo pubblica all'esterno come `POST https://mcp.baldoweb.it/ocr` (vedi [Reverse proxy nginx con TLS (certbot)](#reverse-proxy-nginx-con-tls-certbot) per lo schema di path-routing multi-MCP); richiede comunque l'header `Authorization: Bearer `. **Claude Desktop** (`claude_desktop_config.json`): ```json { "mcpServers": { "ocr-anagrafica": { "url": "https://mcp.baldoweb.it/ocr", "headers": { "Authorization": "Bearer " } } } } ```

mcp-ocr-anagrafica

Installation