Correggere la documentazione con AI e il Sutram MCP Server

Come abbiamo usato l'MCP Server per trovare, commentare, correggere e versionare la sua stessa guida utente — senza uscire dal terminale

Il problema

Stavamo configurando il Sutram MCP Server in Claude Code quando la connessione è fallita. Il colpevole? Un URL errato nella guida utente. La documentazione indicava agli utenti di connettersi a https://sutram.io/mcp, ma l'endpoint corretto è https://app.sutram.io/mcp — mancava il sottodominio app..

Un piccolo errore di battitura, ma uno che avrebbe fatto inciampare ogni nuovo utente che seguiva la guida. Il tipo di bug che erode la fiducia nella documentazione.

Invece di aprire l'interfaccia di Sutram, scaricare il file, cercare e sostituire, ricaricare e gestire le versioni manualmente, abbiamo deciso di correggerlo nello stesso modo in cui l'abbiamo trovato: attraverso AI e MCP, direttamente dal terminale.

Il flusso di lavoro

L'intera correzione è stata eseguita da Claude Code usando gli strumenti del Sutram MCP Server — gli stessi strumenti documentati nella guida che stavamo correggendo. Ecco cosa è successo, passo dopo passo.

1. Trovare il documento

Il progetto organizza la sua documentazione come record — cartelle con metadati strutturati (titolo, categoria, estratto, data di pubblicazione). Invece di navigare l'albero delle cartelle livello per livello, l'agente ha cercato per metadati usando sutram_search_folders:

{
  "conditions": [{"key": "title", "value": "MCP Server"}],
  "type": "file"
}

Una chiamata, un risultato: la Guida Utente del MCP Server — un file markdown di 69,5 KB, versione 1, pubblicato, situato in /en/Docs/User guides/sutram-mcp-server-user-guide.

2. Scaricare e valutare il danno

Usando sutram_get_item per ottenere un URL di download, e poi scaricando il file, l'agente ha cercato tutte le occorrenze dell'URL errato:

10 occorrenze di https://sutram.io/mcp
 0 occorrenze di https://app.sutram.io/mcp

L'errore compariva ovunque: nel diagramma dell'architettura, negli esempi di configurazione per Claude Code, Cursor e Claude Desktop, nella sezione di riferimento API e persino in un esempio di codice Node.js. Ogni singolo frammento di configurazione che un utente avrebbe copiato e incollato era errato.

3. Creare un commento che documenta il bug

Prima di apportare qualsiasi modifica, l'agente ha creato un commento ancorato al markdown sul file usando sutram_create_comment:

"Bug: l'URL del MCP server è errato in tutto il documento. Tutte le 9 occorrenze mostrano https://sutram.io/mcp ma l'URL corretto è https://app.sutram.io/mcp (manca il sottodominio app.). Questo causa fallimenti di connessione quando gli utenti seguono la guida."

Il commento era ancorato direttamente alla prima occorrenza dell'URL nel testo — non una nota generica a livello di file, ma un puntatore preciso al problema.

4. Creare una nuova versione ed effettuare il check-out per la modifica

Il file era pubblicato (v1), quindi la modifica diretta non era possibile. Il flusso di versionamento richiedeva due passaggi:

sutram_create_new_version — creata la versione 2 in stato bozza
sutram_checkout_file — bloccato il file per la modifica esclusiva

Questo è lo stesso flusso di lavoro che i team di ingegneria usano per le revisioni controllate dei documenti: nessun altro può modificare il file mentre è in check-out.

5. Correggere e caricare il file corretto

L'agente ha eseguito un cerca e sostituisci globale:

https://sutram.io/mcp → https://app.sutram.io/mcp

Tutte le 10 occorrenze sostituite. Poi, il caricamento ha seguito il flusso standard in tre passaggi:

sutram_request_upload — ottenuto un URL S3 pre-firmato
HTTP PUT — caricato il file corretto direttamente su S3
sutram_upload_modified_file — registrato il nuovo contenuto con Sutram

6. Check-in e pubblicazione

Con il file caricato:

sutram_checkin_file — rilasciato il blocco, rendendo il file nuovamente disponibile
sutram_publish_version — promossa la versione 2 da bozza a pubblicata

La cronologia delle versioni ora mostra entrambe le versioni: v1 (l'originale con gli URL errati) e v2 (la versione corretta), entrambe conservate per l'audit.

7. Risolvere il commento

Infine, sutram_resolve_comment ha contrassegnato il commento del bug come risolto. Il commento rimane visibile nella cronologia del file — chiunque riveda il documento può vedere cosa era sbagliato e quando è stato corretto.

Gli strumenti utilizzati

Strumento	Scopo
`sutram_search_folders`	Trovare il documento per metadati
`sutram_get_item`	Ottenere metadati e URL di download del file
`sutram_create_comment`	Documentare il bug con un commento ancorato al markdown
`sutram_create_new_version`	Creare la bozza v2 dalla v1 pubblicata
`sutram_checkout_file`	Bloccare il file per la modifica esclusiva
`sutram_request_upload`	Ottenere l'URL pre-firmato per il caricamento su S3
`sutram_upload_modified_file`	Registrare il file corretto
`sutram_checkin_file`	Rilasciare il blocco di modifica
`sutram_publish_version`	Pubblicare la v2
`sutram_resolve_comment`	Chiudere il commento del bug

Dieci diversi strumenti MCP, orchestrati in sequenza dall'agente AI, ciascuno con un passaggio specifico in un flusso professionale di gestione documentale.

Perché è importante

Questa non era una demo o un proof of concept. Era un bug reale, trovato nella documentazione di produzione, che causava reali errori di connessione per gli utenti che cercavano di configurare l'MCP Server.

Ciò che lo rende interessante è il ciclo chiuso: gli stessi strumenti dell'MCP Server sono stati usati per correggere la documentazione dell'MCP Server. L'agente ha utilizzato le stesse funzionalità di versionamento, commento e gestione file che la guida descrive — dimostrando che funzionano esattamente come documentato (una volta che hai l'URL giusto, ovviamente).

L'intera correzione — dalla scoperta alla pubblicazione — ha richiesto circa 2 minuti e non ha mai lasciato il terminale. Nessuna scheda del browser, nessun download manuale di file, nessun copia-incolla tra editor. Solo un agente AI, strumenti MCP e una conversazione.

Il quadro più ampio

I bug nella documentazione sono particolarmente insidiosi. Si annidano in file che raramente ricevono lo stesso rigore di revisione del codice. Interrompono l'onboarding. Generano ticket di supporto. E tendono a persistere perché correggerli sembra un'incombenza a bassa priorità.

MCP cambia l'economia della manutenzione della documentazione. Quando un agente AI può navigare un repository di contenuti, identificare problemi, applicare correzioni attraverso un corretto controllo di versione e documentare le modifiche — tutto nella stessa conversazione in cui il bug è stato scoperto — la barriera per correggere la documentazione si riduce quasi a zero.