Trasforma codice, Terraform e diagrammi in un modello C4 con MCP

La parte più difficile della documentazione di architettura non è disegnare i box. È che, quando apri lo strumento, la tua architettura esiste già — sparsa in cinque posti che non si parlano tra loro.

Un file Structurizr DSL che qualcuno ha mantenuto per otto mesi. Diagrammi Mermaid in una dozzina di README. Moduli Terraform che descrivono la tua infrastruttura reale meglio di quanto qualsiasi diagramma abbia mai fatto. Un export PlantUML dello strumento che usavi prima. E la codebase stessa, l'unica fonte che non mente mai.

Sabato ho mostrato come migrare uno space Confluence in Archyl con due server MCP e un prompt. Oggi, lo stesso trucco con un premio più grande: importare l'architettura stessa.

Due strade, scegli in base alla sorgente

Prima, le strade integrate: se il tuo repository è collegato ad Archyl, AI Discovery analizza il codice e propone un modello C4 completo — sistemi, container, componenti, relazioni — che tu rivedi e approvi. E se arrivi da un altro strumento C4, gli export Structurizr DSL, LikeC4 e IcePanel hanno già un importer con un clic. Quando una delle due va bene, parti da lì.

La strada MCP è per tutto il resto: le sorgenti che Discovery non può vedere. File di diagrams-as-code, definizioni di infrastruttura, quella pagina di architettura nel wiki di qualcuno, o un repo su un server privato. Il server MCP di Archyl espone l'intera superficie di scrittura del modello C4 — create_system, create_container, create_component, create_relationship, set_element_technologies, create_adr — così qualsiasi agent in grado di leggere la tua sorgente può scrivere il tuo modello.

Il setup è lo stesso one-liner di sabato:

claude mcp add --transport http archyl https://api.archyl.com/mcp \
  --header "X-API-Key: your_api_key"

Ricetta 1 — Structurizr, Mermaid, PlantUML

I diagrams-as-code sono la vittoria più facile, perché la semantica è già esplicita. Per un workspace.dsl standard, l'importer con un clic qui sopra è più veloce — l'agent si guadagna il suo posto con Mermaid e PlantUML (non esiste un importer), con le varianti del DSL che l'importer non riesce a parsare, o quando vuoi fare un merge selettivo in un progetto che ha già un modello. Apri il repo in Claude Code e:

Leggi workspace.dsl alla radice di questo repo. Ricrea il modello
nel mio progetto Archyl "Aurora Commerce":

- softwareSystem → create_system (marca quelli esterni come
  external_system)
- container → create_container sotto il sistema giusto, mantieni
  il campo technology
- ogni relazione → create_relationship con la sua descrizione
- non inventare nulla che non sia nel DSL; elenca tutto ciò che
  non sei riuscito a mappare

Poi rileggi il modello con list_systems e list_containers e
mostrami un riepilogo, così posso verificare che non si sia
perso nulla.

Il passaggio di rilettura alla fine è l'abitudine che vale la pena tenersi: l'agent verifica la propria importazione contro il modello live invece di dare per scontato che abbia funzionato.

Ricetta 2 — Terraform

Il tuo codice di infrastruttura sa cose che i tuoi diagrammi hanno dimenticato. Punta l'agent sul tuo Terraform e lascialo lavorare alla giusta altitudine:

Leggi infra/ in questo repo. Modella in Archyl l'architettura a
livello di deployment: i servizi gestiti (RDS, SQS, S3,
CloudFront...) diventano container o sistemi esterni, uno per
servizio reale — non uno per risorsa. Ricava le relazioni dalle
policy IAM, dai security group e dalle variabili d'ambiente.
Tagga tutto ciò che crei con "terraform" così potrò filtrare in
seguito il layer importato.

La riga "non uno per risorsa" fa un lavoro vero. Un importer ingenuo trasforma 400 risorse Terraform in 400 box. Un agent capisce che un'istanza di database, il suo subnet group e il suo parameter group sono un unico container chiamato Orders Database.

Ricetta 3 — la codebase stessa

Niente DSL, niente diagrammi, repo non collegato ad Archyl? L'agent è già seduto dentro il tuo codice. Chiedigli di proporre il modello dal basso verso l'alto — i servizi dai manifest di deploy, i componenti dalla struttura dei package, le relazioni dai client HTTP e dai producer di code che trova. È il lavoro di AI Discovery fatto a mano, ed è il fallback giusto quando Discovery non può raggiungere la sorgente.

Ricetta 4 — diagrammi intrappolati nel tuo wiki

Combina i due server MCP del post di sabato: l'agent legge le pagine di architettura attraverso il server MCP di Atlassian, estrae i sistemi e i flussi descritti e li scrive in Archyl. La pagina wiki che descrive la tua pipeline di eventi diventa un modello reale e navigabile di quella pipeline — e la pagina stessa arriva insieme, come documentazione collegata.

L'importazione è la parte noiosa — ecco il punto

Il giorno dopo l'importazione è il motivo per cui l'hai fatta. Poiché il modello è entrato via MCP, resta raggiungibile via MCP:

• I tuoi agent lo interrogano mentre scrivono codice — "quali container parlano con il database dei pagamenti?" è a una sola chiamata di strumento di distanza.
• I nuovi servizi vengono aggiunti dagli stessi agent che li costruiscono, così il modello segue la realtà invece di decadere.
• Il drift scoring e le regole di conformità girano contro un modello che corrisponde davvero ai tuoi sistemi.

Una regola onesta per chiudere: l'agent propone, tu rivedi. Importa un sistema alla volta, leggi i riepiloghi e pota ciò che non c'entra — la stessa disciplina di qualsiasi code review. Il modello con cui ti ritrovi è buono solo quanto le sorgenti che gli hai dato in pasto, e sei tu a sapere quale delle cinque fonti stava dicendo la verità.

La tua architettura esiste già. Smetti di ridisegnarla — importala. La lista completa degli strumenti è nella documentazione del server MCP.