Come usare un server MCP per la documentazione dell'architettura
Gli assistenti AI di coding sono diventati indispensabili. Claude Code aiuta a rifattorizzare sistemi complessi. Cursor accelera lo sviluppo delle funzionalita'. GitHub Copilot suggerisce implementazioni. Ma tutti questi strumenti condividono un punto cieco comune: non conoscono l'architettura.
Quando si chiede a un assistente AI di "aggiungere un nuovo endpoint allo User Service", non sa che lo User Service comunica con un Auth Service tramite gRPC, memorizza i dati in PostgreSQL, pubblica eventi su Kafka e ha requisiti di sicurezza specifici documentati negli ADR. L'AI tira a indovinare, si corregge, e meta' del guadagno di produttivita' evapora.
I server MCP risolvono questo problema. Danno agli assistenti AI accesso strutturato alla documentazione dell'architettura, trasformando il design del sistema in una sorgente dati interrogabile e azionabile. Questa guida copre tutto cio' che serve sapere sull'uso di un server MCP per la documentazione dell'architettura -- cos'e' MCP, perche' conta e come configurarlo con Archyl.
Cos'e' MCP (Model Context Protocol)?
MCP -- il Model Context Protocol -- e' uno standard aperto creato da Anthropic per connettere gli assistenti AI a strumenti e sorgenti dati esterne. Definisce un modo strutturato per i modelli AI di scoprire, invocare e ricevere risultati da capacita' esterne.
Si puo' pensare a MCP come a un adattatore universale. Prima di MCP, ogni assistente AI aveva il proprio modo proprietario di integrarsi con strumenti esterni. MCP standardizza questo, creando un singolo protocollo che funziona su diversi assistenti AI.
Un server MCP e' un servizio che espone un insieme di strumenti attraverso il protocollo MCP. Ogni strumento ha un nome, una descrizione, parametri di input e un formato di output. Quando un assistente AI si connette a un server MCP, scopre gli strumenti disponibili e puo' invocarli secondo necessita' durante una conversazione.
Per la documentazione dell'architettura, questo significa che il modello architetturale diventa un insieme di strumenti interrogabili e modificabili che qualsiasi assistente AI compatibile con MCP puo' usare. L'AI non deve analizzare file o tirare a indovinare la struttura del sistema -- puo' interrogare direttamente la fonte di verita' autorevole.
Perche' l'architettura ha bisogno di MCP
La documentazione dell'architettura si trova all'intersezione di diverse esigenze che MCP affronta perfettamente.
Il contesto e' tutto per lo sviluppo assistito dall'AI
La qualita' del codice generato dall'AI e' direttamente proporzionale alla qualita' del contesto di cui l'AI dispone. Quando un assistente AI comprende l'architettura -- quali servizi esistono, come comunicano, quali tecnologie usano, quali vincoli si applicano -- genera codice che si integra naturalmente nel sistema.
Senza contesto architetturale, gli assistenti AI fanno ipotesi. Potrebbero suggerire un'API REST quando il servizio usa gRPC. Potrebbero creare una connessione diretta al database quando l'architettura richiede di passare attraverso un livello di servizio. Potrebbero proporre una chiamata sincrona quando il sistema usa comunicazione event-driven.
MCP da' agli assistenti AI accesso all'architettura reale, eliminando questi disallineamenti.
La documentazione dell'architettura e' dati strutturati
A differenza della documentazione libera (wiki, pagine Confluence, file README), la documentazione dell'architettura modellata nel framework C4 e' intrinsecamente strutturata. I sistemi contengono container. I container contengono componenti. Gli elementi hanno tecnologie, descrizioni e relazioni. Gli ADR hanno stati ed elementi interessati.
Questa struttura si mappa naturalmente sugli strumenti MCP. Ogni tipo di elemento architetturale diventa un'entita' interrogabile. Ogni operazione (elencare, ottenere, creare, aggiornare) diventa uno strumento. L'assistente AI puo' navigare il modello architetturale nello stesso modo in cui uno sviluppatore naviga un file system.
La documentazione deve essere bidirezionale
La maggior parte degli strumenti di documentazione e' di sola lettura dal punto di vista API. Si possono visualizzare i documenti, ma modificarli richiede l'apertura di un'applicazione specifica. MCP abilita l'interazione bidirezionale: l'assistente AI puo' sia leggere dalla che scrivere nel modello architetturale.
Questo significa che un assistente AI non puo' solo interrogare l'architettura ma anche proporre modifiche -- aggiungendo un nuovo componente, creando una relazione, redigendo un ADR. Lo sviluppatore revisiona e approva queste modifiche, ma l'AI fa il lavoro meccanico di aggiornamento della documentazione.
Il server MCP di Archyl: 56 strumenti per l'architettura
Archyl fornisce una delle implementazioni di server MCP piu' complete per la documentazione dell'architettura. Con 56 strumenti organizzati nell'intero ambito della modellazione dell'architettura, copre tutto dall'interrogazione del modello C4 alla gestione delle release e al tracciamento della deriva.
Ecco una panoramica delle categorie di strumenti.
Interrogazione del modello C4
Gli strumenti di interrogazione principali permettono all'assistente AI di esplorare l'architettura a ogni livello:
- list_systems / get_project_c4_model -- Scoprire tutti i software system in un progetto
- list_containers / list_components -- Navigare la gerarchia C4
- list_relationships -- Capire come gli elementi si connettono
- get_element_technologies -- Vedere lo stack tecnologico di qualsiasi elemento
- get_element_owners -- Sapere chi possiede cosa
Questi strumenti abilitano interrogazioni in linguaggio naturale sull'architettura. Quando si chiede "Da quali database dipende l'Order Service?", l'AI puo' elencare le relazioni dell'Order Service, filtrare per container di tipo database e restituire una risposta precisa.
Gestione degli elementi architetturali
Gli strumenti di scrittura permettono all'assistente AI di modificare il modello architetturale:
- create_system / update_system / delete_system -- Gestire i software system
- create_container / update_container / delete_container -- Gestire i container
- create_component / update_component / delete_component -- Gestire i componenti
- create_relationship / update_relationship / delete_relationship -- Gestire le connessioni
Questi strumenti sono particolarmente potenti per mantenere la documentazione aggiornata durante lo sviluppo. Quando si aggiunge un nuovo servizio alla codebase, si puo' chiedere all'assistente AI di aggiungere il container corrispondente al modello architetturale, impostare le sue tecnologie e creare le relazioni appropriate -- tutto senza lasciare l'IDE.
Architecture Decision Records
Gli strumenti ADR portano la documentazione delle decisioni nel workflow AI:
- list_adrs / get_adr -- Interrogare le decisioni esistenti
- create_adr / update_adr -- Creare nuovi ADR o aggiornare quelli esistenti
- link_adr_to_element -- Collegare le decisioni agli elementi interessati
Quando si discute una scelta tecnologica con il proprio assistente AI, questo puo' verificare gli ADR esistenti per decisioni correlate, redigere un nuovo ADR per la decisione attuale e collegarlo agli elementi architetturali rilevanti.
Contratti API e Event Channel
Gli strumenti di documentazione delle integrazioni coprono i confini dei servizi:
- list_api_contracts / create_api_contract -- Gestire le specifiche API
- list_event_channels / create_event_channel -- Modellare la comunicazione asincrona
- link_api_contract / link_event_channel -- Collegare le specifiche agli elementi
Questi strumenti aiutano a mantenere la connessione tra architettura e implementazione. Quando si crea un nuovo endpoint API, l'AI puo' verificare se esiste un contratto API per quel servizio e suggerire di aggiornarlo.
Documentazione e collaborazione
Gli strumenti di documentazione piu' ampi supportano i workflow del team:
- create_documentation / update_documentation -- Gestire la documentazione del progetto
- create_comment / list_comments -- Annotare gli elementi architetturali
- list_flows / create_flow -- Documentare i flussi utente e di sistema
- get_drift_score / compute_drift_score -- Verificare l'accuratezza della documentazione
Release e metriche
Gli strumenti operativi collegano l'architettura alla delivery:
- create_release / list_releases -- Tracciare i deployment
- get_dora_metrics / get_dora_trend -- Misurare le performance ingegneristiche
- list_environments -- Comprendere i target di deployment
Esempi reali: MCP in azione
Ecco esempi concreti di come gli sviluppatori usano il server MCP di Archyl nel loro workflow quotidiano.
Esempio 1: Interrogare i sistemi da Claude Code
Si sta lavorando in Claude Code e si deve comprendere l'architettura prima di apportare modifiche:
Tu: Quali sistemi e container ha il nostro progetto?
Claude: Verifico l'architettura.
[Chiama list_systems, poi list_containers per ogni sistema]
Il progetto "E-Commerce Platform" ha 3 sistemi:
1. E-Commerce Platform (software_system)
- API Gateway (Go, Kong)
- User Service (Go, PostgreSQL)
- Order Service (Java, PostgreSQL)
- Product Service (Node.js, MongoDB)
- Notification Service (Python, Redis)
- Event Bus (Kafka)
2. Stripe (external_system)
- Gateway di elaborazione pagamenti
3. SendGrid (external_system)
- Servizio email transazionali
L'AI restituisce dati reali dall'architettura documentata, non un'allucinazione.
Esempio 2: Creare componenti da Cursor
Si sta aggiungendo un nuovo modulo a un servizio e si vuole documentarlo:
Tu: Ho appena aggiunto un componente RateLimiter all'API Gateway.
Usa Redis e la libreria golang.org/x/time/rate.
Puoi aggiungerlo alla nostra architettura?
Cursor: Lo aggiungo al modello C4.
[Chiama create_component con name="RateLimiter",
container="API Gateway", technologies=["Redis", "Go"]]
[Chiama create_relationship da RateLimiter
al container Redis]
Fatto. Ho aggiunto il componente RateLimiter all'API Gateway
e creato una relazione con il container Redis.
La documentazione viene aggiornata in pochi secondi, senza lasciare l'IDE.
Esempio 3: Verificare la deriva prima di un refactoring
Prima di un importante lavoro di refactoring, si vuole sapere quanto sia accurata la documentazione:
Tu: Qual e' il nostro punteggio di deriva attuale? Ci sono servizi
non documentati?
Claude: Verifico.
[Chiama get_drift_score]
[Chiama get_drift_details]
Il punteggio di deriva e' 78/100 (Buono).
Problemi rilevati:
- Il Search Service e' in esecuzione in produzione ma non
documentato nel modello C4
- L'Analytics Service ha 2 relazioni non documentate
con il Data Warehouse
- La lista delle tecnologie dell'API Gateway manca di "Redis"
(aggiunto recentemente per il rate limiting)
Vuoi che corregga questi problemi?
L'AI identifica esattamente cosa non e' aggiornato e puo' correggerlo automaticamente.
Esempio 4: Redigere un ADR
Durante una discussione di design sul passaggio da REST a gRPC per la comunicazione interna tra servizi:
Tu: Stiamo considerando di passare la comunicazione interna
tra servizi da REST a gRPC. Puoi redigere un ADR e
verificare se abbiamo decisioni esistenti al riguardo?
Claude: Verifico prima gli ADR esistenti.
[Chiama list_adrs]
Ho trovato un ADR correlato:
- ADR-007: "Use REST for all internal APIs" (Stato: Accepted)
Deciso 18 mesi fa.
Redigo un nuovo ADR per sostituirlo.
[Chiama create_adr con title="Migrate Internal
Communication from REST to gRPC"]
Creato ADR-015 con:
- Contesto: L'attuale comunicazione basata su REST aggiunge
overhead di serializzazione...
- Decisione: Adottare gRPC con Protocol Buffers per tutta
la nuova comunicazione interna tra servizi...
- Stato: Proposed
- Sostituisce: ADR-007
Vuoi che lo colleghi ai servizi interessati?
L'AI verifica le decisioni correlate, redige un nuovo ADR e offre di collegarlo agli elementi architetturali rilevanti.
Esempio 5: Comprendere l'impatto prima delle modifiche
Prima di modificare un servizio, si vuole capire il raggio d'azione:
Tu: Devo modificare lo schema del database dell'Order Service.
Cos'altro dipende dall'Order Service?
Claude: Traccio le dipendenze.
[Chiama list_relationships filtrate per Order Service]
[Chiama get_element_owners per gli elementi dipendenti]
L'Order Service ha questi dipendenti:
- API Gateway -> Order Service (REST, gestione ordini)
- Order Service -> Payment Service (gRPC, elaborazione pagamenti)
- Order Service -> Event Bus (pubblica eventi OrderCreated,
OrderUpdated, OrderCancelled)
- Notification Service consuma eventi Order dall'Event Bus
- Analytics Service consuma eventi Order dall'Event Bus
Proprieta':
- Order Service: Platform Team
- Payment Service: Payments Team
- Notification Service: Platform Team
- Analytics Service: Data Team
Le modifiche allo schema potrebbero impattare il Payment Service
(dipendenza diretta) e qualsiasi consumatore di eventi Order.
Consiglio di coordinarsi con il Payments Team e il Data Team.
Configurare il server MCP di Archyl
Iniziare con il server MCP di Archyl richiede solo pochi minuti. Ecco come configurarlo per gli assistenti AI piu' comuni.
Configurazione per Claude Code
Aggiungere il server MCP di Archyl alla configurazione di Claude Code:
{
"mcpServers": {
"archyl": {
"url": "https://mcp.archyl.com/sse",
"headers": {
"Authorization": "Bearer YOUR_ARCHYL_API_KEY"
}
}
}
}
Una volta configurato, Claude Code scopre automaticamente tutti i 56 strumenti e puo' usarli in qualsiasi conversazione.
Configurazione per Cursor
Cursor supporta i server MCP attraverso le sue impostazioni. Aggiungere Archyl nella sezione MCP:
{
"mcpServers": {
"archyl": {
"url": "https://mcp.archyl.com/sse",
"headers": {
"Authorization": "Bearer YOUR_ARCHYL_API_KEY"
}
}
}
}
Dopo aver aggiunto la configurazione, riavviare Cursor. Gli strumenti Archyl appaiono nell'elenco degli strumenti MCP, e Cursor puo' usarli durante la generazione del codice e il refactoring.
Configurazione per altri strumenti compatibili MCP
Qualsiasi strumento che supporta il protocollo MCP puo' connettersi al server MCP di Archyl. Il server espone un endpoint MCP standard con discovery degli strumenti, cosi' i client compatibili rilevano e elencano automaticamente gli strumenti disponibili.
Generazione della chiave API
Generare la chiave API MCP dalla dashboard di Archyl:
- Navigare nelle impostazioni dell'organizzazione
- Andare nella sezione API
- Creare una nuova chiave API con i permessi appropriati
- Copiare la chiave nella configurazione del server MCP
Si consiglia di creare chiavi API separate per diversi casi d'uso (ad esempio, una per Claude Code, una per CI/CD) cosi' da poterle ruotare indipendentemente.
Best practice per la documentazione dell'architettura guidata da MCP
Iniziare con la sola lettura
Quando si configura il server MCP per la prima volta, iniziare con interrogazioni di sola lettura. Familiarizzarsi con la capacita' dell'assistente AI di esplorare l'architettura prima di abilitare le operazioni di scrittura. Questo costruisce fiducia nell'accuratezza e affidabilita' dello strumento.
Revisionare le modifiche generate dall'AI
Quando l'assistente AI crea o modifica elementi architetturali, revisionare le modifiche prima di considerarle definitive. Le funzionalita' di cronologia e versioning di Archyl permettono di vedere cosa e' cambiato e di fare rollback se necessario. L'AI e' un assistente potente, ma le decisioni architetturali dovrebbero sempre avere la supervisione umana.
Combinare MCP con Architecture as Code
MCP e architecture as code sono complementari. Usare MCP per interrogazioni interattive e aggiornamenti rapidi durante lo sviluppo. Usare architecture as code (il file archyl.yaml) per definizioni autorevoli e versionate che passano attraverso la code review. I due approcci si rafforzano a vicenda.
Usare MCP nelle code review
Durante le code review, chiedere all'assistente AI di verificare se le modifiche al codice sono allineate con l'architettura documentata. "Questo nuovo endpoint API corrisponde al contratto API documentato per questo servizio?" o "Queste query al database passano attraverso il livello di servizio come documentato?" L'AI puo' validare il codice rispetto al modello architetturale in tempo reale.
Insegnare al team gli strumenti disponibili
La barriera piu' grande all'adozione di MCP e' la consapevolezza. La maggior parte degli sviluppatori non si rende conto di quali domande l'AI puo' rispondere sulla loro architettura. Condividere esempi, creare una guida rapida delle interrogazioni utili e dimostrare i workflow MCP nelle riunioni del team.
Il futuro della documentazione dell'architettura guidata dall'AI
I server MCP rappresentano un cambiamento fondamentale nel modo in cui i team interagiscono con la documentazione dell'architettura. Invece di essere un artefatto passivo che gli sviluppatori leggono (o piu' spesso, non leggono), diventa un partecipante attivo nel workflow di sviluppo.
Quando il proprio assistente AI puo' interrogare l'architettura prima di generare codice, verificare la conformita' dopo le modifiche e aggiornare la documentazione man mano che il sistema evolve, la barriera tra "lavorare sul sistema" e "documentare il sistema" scompare.
La documentazione dell'architettura smette di essere qualcosa che si mantiene separatamente e diventa qualcosa che e' intessuto in ogni interazione di sviluppo. Ogni domanda posta all'AI, ogni modifica al codice, ogni discussione di design -- tutte possono essere informate dal e riflesse nel modello architetturale.
Questo e' il futuro che Archyl sta costruendo. Il server MCP e' il ponte tra lo sviluppo basato sull'AI e la documentazione strutturata dell'architettura. E con 56 strumenti che coprono l'intero ambito della modellazione dell'architettura, e' abbastanza completo per supportare qualsiasi workflow di cui il team abbia bisogno.
Inizia con il server MCP di Archyl e dai al tuo assistente AI il contesto architetturale che gli mancava.