Every repository accumula dati strutturati che qualcuno alla fine necessita come documento: le modifiche in una release, i contributori dell’anno, un inventario API, un elenco di rischi aperti. I dati sono già in JSON; il passaggio mancante è un PDF o un file Word formattato che un cliente, un revisore o un manager aprirà effettivamente. Con GroupDocs.Assembly.Mcp in esecuzione localmente accanto a Claude Code (claude mcp add con dnx GroupDocs.Assembly.Mcp --yes), l’agente riempie un modello Word conservato nel repository da un file JSON nel repository, e scrive il PDF, senza che nessuno formatti una tabella:

Genera il PDF delle note di rilascio per la versione 4.2.0 da data/release-4.2.0.json con templates/release-notes.docx, e un certificato di contributo per ogni collaboratore in data/contributors-2026.json.

La versione passo‑passo con configurazione e risoluzione dei problemi è nella documentazione: How to generate a PDF or Word report from JSON data in a repository with Claude Code.

Perché non far scrivere il documento all’agente di programmazione?

Gli agenti di programmazione sono molto bravi a produrre dati e piuttosto scarsi a produrre documenti. Chiedine uno di “note di rilascio come PDF” e scriverà un file Markdown, poi uno script che lo converte, poi debuggherà i font dello script. Nella prossima release, lo farà di nuovo in modo leggermente diverso. L’output appare come quello che la libreria di conversione imposta di default, non come i documenti che la tua azienda invia.

Un modello fissa l’aspetto e lo mette sotto controllo di versione. templates/release-notes.docx è un normale file Word con il logo, gli stili di intestazione e una tabella, più alcuni tag <<…>>. Chiunque sia responsabile del layout lo modifica in Word; l’agente non lo tocca mai. Il JSON è prodotto dal tuo strumento di rilascio, o dall’agente da git log, ed è la parte in cui un agente di programmazione è bravo.

Rende anche il lavoro revisionabile. Una pull request che modifica data/release-4.2.0.json mostra esattamente quali modifiche appariranno nelle note di rilascio, riga per riga, in un diff che un revisore può leggere in un minuto. Una pull request che modifica un PDF generato non mostra nulla. Tenere dati e layout come file separati e versionati, e trattare il documento come qualcosa che si genera da essi, è la stessa idea di tenere separati il codice sorgente e l’output di build, e vale per i documenti per le stesse ragioni.

Come appare il repository

repo/
  data/
    release-4.2.0.json       {"release":{...}, "changes":[...4 items]}
    contributors-2026.json   {"contributors":[...3 items]}
  templates/
    release-notes.docx       <<[release.Version]>>, <<foreach [c in
                             changes]>> table row, counts
    certificate.docx         <<[contributor.Name]>> ...
  out/                       GROUPDOCS_MCP_OUTPUT_PATH, in .gitignore
        |
        |  Claude Code -> GroupDocs.Assembly MCP server (local, stdio)
        v
  release-notes-4.2.0.pdf    pnair.pdf  tvarga.pdf  mrossi.pdf

Le chiamate

Prima l’agente verifica cosa si aspetta il modello, così può dirti se al JSON manca qualcosa:

-> get_template_fields {"template":{"filePath":
     "repo/templates/release-notes.docx"}}
<- { "dataSourceNames": [ "release", "changes" ],
     "fields": [ "release.Product", "release.Version", "release.Date",
                 "changes[].Type", "changes[].Title",
                 "changes[].PullRequest", "changes[].Author" ] }

Poi una chiamata lo rende:

-> assemble_document {"template":{"filePath":
     "repo/templates/release-notes.docx"},
     "data":{"filePath":"repo/data/release-4.2.0.json"},
     "format":"pdf","outputName":"release-notes-4.2.0.pdf"}
<- Assembled 'release-notes.docx' with 'release-4.2.0.json' (JSON
   object) as PDF
   Saved to: .../release-notes-4.2.0.pdf

La riga della tabella del modello si ripete una volta per ogni modifica, e la sua ultima riga conta le modifiche e gli autori distinti con changes.Count() e changes.Select(c => c.Author).Distinct().Count(). Quei numeri provengono dai dati al momento del rendering, non dall’agente.

I certificati sono un fan‑out: un PDF per ogni elemento dell’array contributors, denominato con l’handle del collaboratore:

-> assemble_per_record {"template":{"filePath":
     "repo/templates/certificate.docx"},
     "data":{"filePath":"repo/data/contributors-2026.json"},
     "recordsPath":"contributors","fileNameField":"Handle",
     "format":"pdf"}
<- Assembled 3 of 3 document(s) from 'certificate.docx' with
   'contributors-2026.json', one per record (each record as
   'contributor'), as PDF.
   Saved to:
   .../pnair.pdf
   .../tvarga.pdf
   .../mrossi.pdf

recordsPath indica al server dove si trova l’array quando il file JSON è un oggetto, che è la forma usuale dei file di dati reali.

Falla un’abitudine, non un prompt

Gli agenti seguono le istruzioni del progetto su quando usare uno strumento. Alcune righe in CLAUDE.md o AGENTS.md trasformano questo in una convenzione:

Documents for people (release notes, reports, certificates) are generated
with the groupdocs-assembly MCP server from templates/*.docx and data/*.json.
Call get_template_fields first; never edit a template. Generated files land
in out/, which is in .gitignore. Dates in JSON as yyyy-MM-ddTHH:mm:ss.

Tieni gli output fuori da git. Per impostazione predefinita il server scrive accanto alla sua cartella di storage; imposta GROUPDOCS_MCP_OUTPUT_PATH nella registrazione del server sulla cartella out/ del repository e aggiungi quella cartella a .gitignore. Il JSON e il modello sono la sorgente; il PDF è un artefatto di build, rigenerato in pochi secondi, e committarlo produce solo diff che nessuno può revisionare.

Limiti onesti

  • Modalità valutazione: ogni PDF inizia con “Evaluation Only. Created with GroupDocs.Assembly 26.7…”. Va bene per provarlo; licenzia il server prima che qualcosa lasci il team.
  • I modelli sono input fidato. I tag immagine e documento caricano i percorsi e gli URL restituiti dalle loro espressioni, quindi tratta un modello proveniente da una pull request come codice, e fornisci al server una sola cartella di storage.
  • Date: scrivile come 2026-11-03T00:00:00 e formattale nel modello (<<[release.Date]:"d MMMM yyyy">>). Una stringa contenente solo la data è stata spostata di un giorno su una macchina UTC+2 nel nostro test; l’immagine Docker gira in UTC.
  • La generazione per record legge solo JSON, e maxDocuments (default 100) interrompe un array inaspettatamente grande prima che venga scritto qualcosa.
  • get_template_fields è statico: i valori calcolati all’interno delle proiezioni Select o GroupBy non vengono seguiti.

FAQ

Claude Code può generare un PDF da JSON nel mio repository senza un servizio cloud?
Sì. Il server MCP gira localmente come processo figlio di Claude Code e legge il modello e il JSON dalla cartella a cui lo indirizzi.

Può essere eseguito in CI?
Il server è un server MCP, quindi necessita di un client MCP: Claude Code in modalità headless, o qualsiasi runner di agenti. L’immagine Docker (ghcr.io/groupdocs-assembly/assembly-net-mcp) è la forma comoda per una pipeline.

Word o PDF?
Entrambi. Ometti format e l’output è un DOCX come il modello; "format":"pdf" restituisce un PDF. get_supported_formats elenca ogni destinazione per modello.

Approfondisci