Her depo, birinin sonunda belge olarak ihtiyaç duyacağı yapılandırılmış verileri biriktirir: bir sürümdeki değişiklikler, yılın katkıcıları, bir API envanteri, açık risklerin listesi. Veriler zaten JSON; eksik adım, bir müşterinin, denetçinin ya da yöneticinin gerçekten açacağı biçimlendirilmiş bir PDF veya Word dosyasıdır. GroupDocs.Assembly.Mcp, Claude Code’un yanına yerel olarak çalıştırıldığında (claude mcp add ile dnx GroupDocs.Assembly.Mcp --yes), ajan, depodaki bir JSON dosyasından depodaki bir Word şablonunu doldurur ve PDF’yi yazar, hiç kimse tabloyu biçimlendirmeden:

4.2.0 sürümü için sürüm notları PDF’sini data/release-4.2.0.json dosyasından templates/release-notes.docx ile oluştur ve data/contributors-2026.json içindeki her katkıcı için bir katkı sertifikası oluştur.

Yapılandırma ve sorun giderme adımlarıyla birlikte adım adım sürüm belgelerde bulunabilir: Claude Code ile bir depodaki JSON verilerinden PDF veya Word raporu nasıl oluşturulur.

Kodlama ajanının belgeyi yazmasını neden istemeyelim?

Kodlama ajanları veri üretmede çok iyidir ancak belge üretmede oldukça kötüdür. Birine “sürüm notları PDF olarak” istediğinizde bir Markdown dosyası yazar, ardından onu dönüştüren bir betik oluşturur, ardından betiğin yazı tiplerini hata ayıklar. Bir sonraki sürümde, bunu biraz farklı bir şekilde tekrar eder. Çıktı, dönüşüm kütüphanesinin varsayılanına benzer, şirketinizin gönderdiği belgeler gibi değildir.

Bir şablon görünümü sabitler ve sürüm kontrolüne alır. templates/release-notes.docx logo, başlık stilleri ve bir tablo içeren normal bir Word dosyasıdır, ayrıca birkaç <<…>> etiketi bulunur. Düzeni kim sahipleniyorsa Word’de düzenler; ajan ona dokunmaz. JSON, sürüm araçlarınız tarafından ya da ajan tarafından git log üzerinden üretilir ve bu, bir kodlama ajanın iyi yaptığı bölümdür.

Ayrıca işi gözden geçirilebilir kılar. data/release-4.2.0.json dosyasını değiştiren bir pull request, sürüm notlarında hangi değişikliklerin görüneceğini satır satır, bir dakikada bir inceleyicinin okuyabileceği diff içinde tam olarak gösterir. Oluşturulmuş bir PDF’yi değiştiren bir pull request ise hiçbir şey göstermez. Veriyi ve düzeni ayrı, sürümlü dosyalar olarak tutmak ve belgeyi onlardan oluşturulan bir şey olarak ele almak, kaynak kodu ve derleme çıktısını ayrı tutma fikriyle aynıdır ve belgeler için de aynı nedenlerle geçerlidir.

Depo Nasıl Görünür

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

Çağrılar

İlk olarak ajan, şablonun ne beklediğini kontrol eder, böylece JSON’da bir şey eksikse size bildirebilir:

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

Ardından bir çağrı onu oluşturur:

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

Şablonun tablo satırı her değişiklik için bir kez tekrarlanır ve son satırı, changes.Count() ve changes.Select(c => c.Author).Distinct().Count() ile değişiklikleri ve farklı yazarları sayar. Bu sayılar, ajan tarafından değil, oluşturma zamanındaki veriden gelir.

Sertifikalar bir fan-out’tur: contributors dizisinin her öğesi için bir PDF, katkıcının takma adıyla adlandırılır:

-> 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, JSON dosyası bir nesne olduğunda dizinin nerede olduğunu sunucuya bildirir; bu, gerçek veri dosyalarının genellikle sahip olduğu şekildir.

Alışkanlık haline getirin, bir istem değil

Ajanlar, bir aracı ne zaman kullanacaklarıyla ilgili proje talimatlarını izler. CLAUDE.md veya AGENTS.md içinde birkaç satır bunu bir konvansiyona dönüştürür:

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.

Çıktıları git’ten uzak tutun. Varsayılan olarak sunucu, depolama klasörünün yanına yazar; sunucu kaydında GROUPDOCS_MCP_OUTPUT_PATH‘i deponun out/ klasörüne ayarlayın ve bu klasörü .gitignore‘a ekleyin. JSON ve şablon kaynak; PDF ise saniyeler içinde yeniden oluşturulan bir derleme artefaktıdır ve onu commit etmek sadece kimsenin gözden geçiremeyeceği diff’ler üretir.

Dürüst sınırlamalar

  • Değerlendirme modu: her PDF, “Evaluation Only. Created with GroupDocs.Assembly 26.7…” ile başlar. Denemek için uygundur; ekipten bir şey çıkmadan önce sunucuyu lisanslayın.
  • Şablonlar güvenilir girdi olarak kabul edilir. Görsel ve belge etiketleri, ifadelerinin döndürdüğü yol ve URL’leri yükler, bu yüzden bir pull request’ten gelen şablonu kod gibi ele alın ve sunucuya tek bir depolama klasörü verin.
  • Tarihler: 2026-11-03T00:00:00 şeklinde yazın ve şablonda formatlayın (<<[release.Date]:"d MMMM yyyy">>). Sadece tarih içeren bir dize, testimizde UTC+2 makinede bir gün kaydırıldı; Docker imajı UTC’de çalışır.
  • Kayıt başına üretim yalnızca JSON okur ve maxDocuments (varsayılan 100) herhangi bir şey yazılmadan önce beklenmedik şekilde büyük bir diziyi durdurur.
  • get_template_fields statiktir: Select veya GroupBy projeksiyonları içinde hesaplanan değerler izlenmez.

SSS

Claude Code, depomdaki JSON’dan bir PDF oluşturabilir mi, bulut hizmeti olmadan?
Evet. MCP sunucusu, Claude Code’un bir alt süreci olarak yerel çalışır ve şablonu ve JSON’u belirttiğiniz klasörden okur.

Bu CI’de çalışabilir mi?
Sunucu bir MCP sunucusudur, bu yüzden bir MCP istemcisine ihtiyaç duyar: başsız modda Claude Code veya herhangi bir ajan çalıştırıcı. Docker imajı (ghcr.io/groupdocs-assembly/assembly-net-mcp) bir pipeline için uygun formattır.

Word mu PDF mi?
Her ikisi de. format parametresini bırakmazsanız çıktı, şablon gibi bir DOCX olur; "format":"pdf" bir PDF verir. get_supported_formats her şablon için tüm hedefleri listeler.

Daha Derine İnceleyin