Każde repozytorium gromadzi ustrukturyzowane dane, które ktoś ostatecznie potrzebuje jako dokument: zmiany w wydaniu, autorzy roku, inwentaryzacja API, lista otwartych ryzyk. Dane są już w formacie JSON; brakującym krokiem jest sformatowany plik PDF lub Word, który klient, audytor lub menedżer faktycznie otworzy. Z uruchomionym lokalnie GroupDocs.Assembly.Mcp obok Claude Code (claude mcp add z dnx GroupDocs.Assembly.Mcp --yes), agent wypełnia szablon Word przechowywany w repozytorium z pliku JSON w repozytorium i zapisuje PDF, bez konieczności formatowania tabeli przez kogokolwiek:

Wygeneruj PDF z notatkami wydania dla wersji 4.2.0 z pliku data/release-4.2.0.json przy użyciu templates/release-notes.docx oraz certyfikat wkładu dla każdego współtwórcy w data/contributors-2026.json.

Wersja krok po kroku z konfiguracją i rozwiązywaniem problemów znajduje się w dokumentacji: Jak wygenerować raport PDF lub Word z danych JSON w repozytorium przy użyciu Claude Code.

Dlaczego nie pozwolić agentowi kodującemu napisać dokumentu?

Agenci kodujący są bardzo dobrzy w generowaniu danych, a raczej słabi w tworzeniu dokumentów. Poproś ich o „notatki wydania jako PDF”, a napiszą plik Markdown, potem skrypt konwertujący go, a następnie będą debugować czcionki w skrypcie. Przy następnym wydaniu zrobią to ponownie, nieco inaczej. Wynik wygląda tak, jak domyślnie ustawia biblioteka konwersji, a nie jak dokumenty, które wysyła twoja firma.

Szablon ustala wygląd i umieszcza go pod kontrolą wersji. templates/release-notes.docx to zwykły plik Word z logo, stylami nagłówków i tabelą, plus kilka znaczników <<…>>. Kto zarządza układem, edytuje go w Wordzie; agent nigdy go nie modyfikuje. JSON jest generowany przez twoje narzędzia wydania lub przez agenta z git log, i to jest część, w której agent kodujący radzi sobie dobrze.

Umożliwia to także przeglądanie pracy. Pull request zmieniający data/release-4.2.0.json pokazuje dokładnie, które zmiany pojawią się w notatkach wydania, linia po linii, w diffie, który recenzent może przeczytać w minutę. Pull request zmieniający wygenerowany PDF nie pokazuje niczego. Trzymanie danych i układu jako oddzielnych, wersjonowanych plików oraz traktowanie dokumentu jako czegoś, co renderujesz z nich, to ta sama idea co oddzielanie kodu źródłowego od wyników kompilacji i ma zastosowanie do dokumentów z tych samych powodów.

Jak wygląda repozytorium

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

Wywołania

Najpierw agent sprawdza, czego oczekuje szablon, aby móc poinformować cię, czy w JSON brakuje czegoś:

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

Następnie jedno wywołanie renderuje go:

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

Wiersz tabeli w szablonie powtarza się raz na każdą zmianę, a jego ostatnia linia liczy zmiany oraz unikalnych autorów przy użyciu changes.Count() i changes.Select(c => c.Author).Distinct().Count(). Te liczby pochodzą z danych w momencie renderowania, a nie od agenta.

Certyfikaty są rozdzielane: jeden PDF na każdy element tablicy contributors, nazwany według identyfikatora współtwórcy:

-> 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 informuje serwer, gdzie znajduje się tablica, gdy plik JSON jest obiektem, co jest typowym kształtem rzeczywistych plików danych.

Uczyń to nawykiem, nie jednorazowym poleceniem

Agenci podążają za instrukcjami projektu dotyczącymi użycia narzędzia. Kilka linijek w CLAUDE.md lub AGENTS.md przekształca to w konwencję:

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.

Trzymaj wyniki poza git. Domyślnie serwer zapisuje obok swojego folderu przechowywania; ustaw GROUPDOCS_MCP_OUTPUT_PATH w rejestracji serwera na folder out/ repozytorium i dodaj ten folder do .gitignore. JSON i szablon są źródłem; PDF jest artefaktem budowania, odtwarzanym w kilka sekund, a jego zatwierdzanie generuje jedynie diffy, których nikt nie może przejrzeć.

Szczere ograniczenia

  • Tryb ewaluacji: każdy PDF zaczyna się od “Evaluation Only. Created with GroupDocs.Assembly 26.7…”. W porządku do testów; przed udostępnieniem czegokolwiek zespołowi należy licencjonować serwer.
  • Szablony są zaufanym wejściem. Znaczniki obrazu i dokumentu ładują ścieżki i URL‑e zwracane przez ich wyrażenia, więc traktuj szablon z pull requestu jak kod i zapewnij serwerowi jeden folder przechowywania.
  • Daty: zapisz je jako 2026-11-03T00:00:00 i formatuj w szablonie (<<[release.Date]:"d MMMM yyyy">>). Ciąg zawierający tylko datę został przesunięty o dzień na maszynie UTC+2 w naszym teście; obraz Docker działa w UTC.
  • Generowanie per-record odczytuje tylko JSON, a maxDocuments (domyślnie 100) zatrzymuje nieoczekiwanie dużą tablicę przed zapisaniem czegokolwiek.
  • get_template_fields jest statyczny: wartości obliczane wewnątrz projekcji Select lub GroupBy nie są uwzględniane.

FAQ

Czy Claude Code może wygenerować PDF z JSON w moim repozytorium bez usługi w chmurze?
Tak. Serwer MCP działa lokalnie jako proces potomny Claude Code i odczytuje szablon oraz JSON z folderu, który wskażesz.

Czy to może działać w CI?
Serwer jest serwerem MCP, więc potrzebuje klienta MCP: Claude Code w trybie bezgłowym lub dowolnego uruchamiacza agenta. Obraz Docker (ghcr.io/groupdocs-assembly/assembly-net-mcp) jest wygodną formą dla pipeline’u.

Word czy PDF?
Oba. Pomiń format, a wyjściem będzie DOCX podobny do szablonu; "format":"pdf" daje PDF. get_supported_formats wymienia każdy dostępny format dla szablonu.

Zagłęb się