Todo repositório acumula dados estruturados que alguém eventualmente precisa como documento: as alterações em uma versão, os contribuidores do ano, um inventário de API, uma lista de riscos abertos. Os dados já estão em JSON; o passo que falta é um PDF ou arquivo Word formatado que um cliente, auditor ou gerente realmente abrirá. Com o GroupDocs.Assembly.Mcp rodando localmente ao lado do Claude Code (claude mcp add com dnx GroupDocs.Assembly.Mcp --yes), o agente preenche um modelo Word mantido no repositório a partir de um arquivo JSON no repositório, e grava o PDF, sem que ninguém formate uma tabela:

Gerar o PDF de notas de lançamento para 4.2.0 a partir de data/release-4.2.0.json com templates/release-notes.docx, e um certificado de contribuição para cada contribuinte em data/contributors-2026.json.

A versão passo a passo com configuração e solução de problemas está na documentação: Como gerar um relatório PDF ou Word a partir de dados JSON em um repositório com Claude Code.

Por que não deixar o agente de codificação escrever o documento?

Agentes de codificação são muito bons em produzir dados e bastante ruins em produzir documentos. Peça a um deles “notas de lançamento como PDF” e ele escreverá um arquivo Markdown, depois um script que o converte, depois depura as fontes do script. Na próxima versão, ele faz isso novamente de forma ligeiramente diferente. A saída parece o que quer que a biblioteca de conversão use como padrão, não como os documentos que sua empresa envia.

Um modelo corrige a aparência e o coloca sob controle de versão. templates/release-notes.docx é um arquivo Word normal com o logotipo, os estilos de título e uma tabela, além de algumas tags <<…>>. Quem for responsável pelo layout o edita no Word; o agente nunca o toca. O JSON é produzido pela sua ferramenta de lançamento, ou pelo agente a partir de git log, e essa é a parte que um agente de codificação faz bem.

Também torna o trabalho revisável. Um pull request que altera data/release-4.2.0.json mostra exatamente quais mudanças aparecerão nas notas de lançamento, linha por linha, em um diff que um revisor pode ler em um minuto. Um pull request que altera um PDF gerado não mostra nada. Manter os dados e o layout como arquivos separados e versionados, e tratar o documento como algo que você renderiza a partir deles, é a mesma ideia de manter o código-fonte e a saída de compilação separados, e isso vale para documentos pelos mesmos motivos.

Como o repositório se parece

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]>> linha da tabela, contagens
    certificate.docx         <<[contributor.Name]>> ...
  out/                       GROUPDOCS_MCP_OUTPUT_PATH, in .gitignore
        |
        |  Claude Code -> servidor GroupDocs.Assembly MCP (local, stdio)
        v
  release-notes-4.2.0.pdf    pnair.pdf  tvarga.pdf  mrossi.pdf

As chamadas

Primeiro o agente verifica o que o modelo espera, para que possa dizer se o JSON está faltando algo:

-> 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" ] }

Então uma chamada o renderiza:

-> 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

A linha da tabela do modelo se repete uma vez por alteração, e sua última linha conta as alterações e os autores distintos com changes.Count() e changes.Select(c => c.Author).Distinct().Count(). Esses números vêm dos dados no momento da renderização, não do agente.

Os certificados são distribuídos: um PDF por elemento do array contributors, nomeado pelo identificador do contribuinte:

-> 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 informa ao servidor onde está o array quando o arquivo JSON é um objeto, que é a forma usual dos arquivos de dados reais.

Transforme isso em um hábito, não em um prompt

Os agentes seguem as instruções do projeto sobre quando usar uma ferramenta. Algumas linhas em CLAUDE.md ou AGENTS.md transformam isso em uma convenção:

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.

Mantenha as saídas fora do git. Por padrão o servidor grava ao lado da sua pasta de armazenamento; defina GROUPDOCS_MCP_OUTPUT_PATH no registro do servidor para a pasta out/ do repositório e adicione essa pasta ao .gitignore. O JSON e o modelo são a fonte; o PDF é um artefato de compilação, regenerado em segundos, e comitar ele só produz diffs que ninguém pode revisar.

Limites honestos

  • Modo de avaliação: cada PDF começa com “Evaluation Only. Created with GroupDocs.Assembly 26.7…”. Ok para testar; licencie o servidor antes que algo saia da equipe.
  • Modelos são entrada confiável. Tags de imagem e documento carregam os caminhos e URLs que suas expressões retornam, portanto trate um modelo de um pull request como código, e forneça ao servidor uma única pasta de armazenamento.
  • Datas: escreva-as como 2026-11-03T00:00:00 e formate-as no modelo (<<[release.Date]:"d MMMM yyyy">>). Uma string contendo apenas a data foi deslocada em um dia em uma máquina UTC+2 no nosso teste; a imagem Docker roda em UTC.
  • A geração por registro lê apenas JSON, e maxDocuments (padrão 100) interrompe um array inesperadamente grande antes que algo seja escrito.
  • get_template_fields é estático: valores calculados dentro de projeções Select ou GroupBy não são seguidos.

Perguntas Frequentes

Claude Code pode gerar um PDF a partir de JSON no meu repositório sem um serviço de nuvem?
Sim. O servidor MCP roda localmente como um processo filho do Claude Code e lê o modelo e o JSON da pasta que você indicar.

Isso pode ser executado em CI?
O servidor é um servidor MCP, portanto precisa de um cliente MCP: Claude Code em modo headless, ou qualquer executor de agente. A imagem Docker (ghcr.io/groupdocs-assembly/assembly-net-mcp) é a forma conveniente para um pipeline.

Word ou PDF?
Ambos. Omitir format e a saída será um DOCX como o modelo; "format":"pdf" gera um PDF. get_supported_formats lista todos os destinos por modelo.

Aprofunde-se