Torna al Blog

Codifica di documenti tecnici con AI e MCP

By Sergio Vieira Greve
Codifica di documenti tecnici con AI e MCP

Come Claude Code e il Sutram MCP Server hanno trasformato uno standard di 30 pagine in un sistema funzionante in pochi minuti

La sfida

Lo standard Petrobras N-1710 Rev. N (Codifica dei Documenti Tecnici di Ingegneria) definisce un sistema rigoroso per l'identificazione dei documenti tecnici. Ogni documento riceve un codice composto da fino a 7 gruppi separati da trattini:

[A-]BB-CDDD.EE-FGGGG-HHH-III-JJJ

Dove ogni gruppo rappresenta, rispettivamente: lingua, categoria del documento, impianto, area di attività, classe di servizio, origine e un numero sequenziale. Gli allegati dello standard dettagliano centinaia di codici validi per ogni campo — l'Allegato C (Area di Attività) da solo ha oltre 900 codici, e l'Allegato D (Classe di Servizio) circa 690.

Implementare questo sistema manualmente — definire i campi, registrare centinaia di valori, configurare le regole di generazione automatica del codice — è un lavoro che normalmente richiederebbe ore, se non giorni.

Il prompt iniziale

Tutto è partito da una semplice istruzione a Claude Code:

"Leggi lo standard N-1710 e i suoi allegati (A, C e D) in PDF. Poi, configura una Categoria di Record in Sutram che implementi la codifica definita dallo standard."

Da questa singola richiesta, l'agente doveva:

  1. Leggere e interpretare lo standard principale e 3 allegati in PDF (48 pagine in totale)
  2. Estrarre tutti i codici e le descrizioni dagli allegati
  3. Modellare la struttura dei metadati in Sutram
  4. Registrare più di 1.600 valori enumerati
  5. Configurare la generazione automatica dello slug nel formato dello standard
  6. Testare e validare il risultato

Gli strumenti del Sutram MCP Server

Sutram fornisce un MCP Server (Model Context Protocol) che permette agli agenti AI di interagire direttamente con la piattaforma. Questo è stato l'elemento differenziante che ha reso possibile l'implementazione in un'unica sessione.

Gli strumenti utilizzati, nell'ordine del flusso di lavoro:

1. sutram_project_info — Ricognizione

Prima chiamata: verificare lo stato del progetto. Risultato: zero definizioni di metadati, zero categorie di record. Tabula rasa.

2. sutram_upsert_metadata — Modellazione dei campi

Con lo standard già interpretato, l'agente ha creato 7 definizioni di metadati in chiamate parallele:

Campo Tipo Valori
idioma (lingua) enum 6 (Inglese, Tedesco, Francese, ecc.)
categoria_documento (categoria documento) enum 21 (Disegno, Relazione, Scheda Dati, ecc.)
instalacao (impianto) text formato libero (formato CDDD.EE)
area_atividade (area di attività) enum 903 codici dall'Allegato C
classe_servico (classe di servizio) enum 690 codici dall'Allegato D
origem (origine) text formato libero (codice NORTEC)
sequencial (sequenziale) computed auto-generato, 3 cifre

La parallelizzazione era essenziale — i campi indipendenti sono stati creati simultaneamente, risparmiando tempo.

3. sutram_add_enum_values — Caricamento massivo dei dati

Ecco la parte più impressionante. Gli Allegati C e D dello standard contengono, insieme, quasi 1.600 codici. L'agente ha:

  • Letto i PDF pagina per pagina (il solo Allegato C ha 27 pagine)
  • Estratto ogni codice e la sua descrizione
  • Caricato i valori in batch paralleli usando sutram_add_enum_values

Esempio di un batch dall'Allegato C:

{
  "key": "area_atividade",
  "values": [
    {"code": "2111", "label": "Unità di Distillazione Atmosferica"},
    {"code": "2112", "label": "Unità di Distillazione sotto Vuoto"},
    {"code": "2113", "label": "Unità Pre-Flash"},
    ...
  ]
}

Molteplici round di chiamate parallele sono stati necessari per caricare tutti i valori — circa 15 chiamate in totale per entrambi gli allegati. Lo strumento sutram_add_enum_values esegue un merge intelligente: i codici duplicati vengono ignorati e tutto viene riordinato automaticamente.

4. sutram_upsert_record_category — Configurazione della codifica

Con i metadati pronti, una singola chiamata ha creato la Categoria di Record con tutta la logica di generazione del codice:

  • computed_from: definisce quali campi compongono la "base di unicità" per il sequenziale (categoria + impianto + area + classe + origine)
  • slug_from: definisce come viene assemblato il codice finale, campo per campo, scegliendo tra l'uso del code o della label di ogni enum
  • slug_separator: il trattino che separa i gruppi
{
  "slug_from": [
    {"key": "idioma", "use": "code"},
    {"key": "categoria_documento", "use": "code"},
    {"key": "instalacao", "use": "label"},
    {"key": "area_atividade", "use": "code"},
    {"key": "classe_servico", "use": "code"},
    {"key": "origem", "use": "label"},
    {"key": "sequencial", "use": "label"}
  ],
  "slug_separator": "-"
}

5. sutram_create_record — Validazione

Il test finale: creare record e verificare se il codice generato corrisponde al formato dello standard.

Test 1 — Memoriale Descrittivo in portoghese:

Input:    category=Memoriale Descrittivo, facility=4300.06,
          area=Laboratorio, class=Perforazione, origin=PTD
Risultato: MD-4300.06-8222-114-PTD-001 ✓

Test 2 — Stessa combinazione, secondo documento:

Risultato: MD-4300.06-8222-114-PTD-002 ✓  (sequenziale incrementato)

Test 3 — Documento in inglese:

Input:    language=Inglese, category=Disegno, facility=5285.00,
          area=Laboratorio, class=Torri, origin=PPC
Risultato: I-DE-5285.00-8222-550-PPC-001 ✓  (prefisso "I-" per l'inglese)

Il ruolo di MCP (Model Context Protocol)

MCP è ciò che rende possibile questa integrazione. Permette a Claude Code di interagire con Sutram come se fosse un utente avanzato della piattaforma — ma con la capacità di:

  • Parallelizzare chiamate indipendenti (creare più campi di metadati contemporaneamente)
  • Elaborare in batch grandi volumi di dati (centinaia di codici per chiamata)
  • Concatenare operazioni dipendenti (creare metadati → creare categoria → testare)
  • Validare i risultati in tempo reale e correggere errori nello stesso flusso

Senza MCP, lo stesso compito avrebbe richiesto di navigare l'interfaccia di Sutram, registrare ogni campo manualmente, digitare o importare centinaia di codici uno per uno e configurare le regole dello slug attraverso la UI. Con MCP, l'agente ha fatto tutto in modo programmatico, direttamente dal terminale.

I numeri della sessione

Metrica Valore
Pagine PDF lette 48
Definizioni di metadati create 7
Valori enum registrati 1.614 (903 + 690 + 21)
Categoria di record configurata 1
Record di test creati e validati 3
Correzioni in tempo reale 1 (aggiustamento slug_from da label a code)

Conclusione

La combinazione di un agente AI capace di interpretare documenti tecnici (Claude Code che legge i PDF dello standard) con strumenti MCP che consentono azioni dirette sulla piattaforma (il Sutram MCP Server) crea un flusso di lavoro che semplicemente non era possibile prima.

Quello che in precedenza avrebbe richiesto ore di lavoro manuale — leggere lo standard, interpretare le regole, registrare centinaia di codici, configurare la logica di generazione — è stato risolto in un'unica sessione di conversazione. E il risultato non è un prototipo: è un sistema funzionale, validato, pronto per l'uso in produzione.

Questa è la promessa di MCP: non solo chiedere e rispondere, ma agire.

Torna al Blog