Surat selamat datang untuk empat puluh pelanggan baru, sertifikat untuk setiap peserta, faktur per pesanan: dokumen yang sama, catatan yang berbeda setiap kali. Dengan GroupDocs.Assembly.Mcp berjalan secara lokal (dnx GroupDocs.Assembly.Mcp --yes), Claude Desktop, Cursor atau Copilot melakukannya dengan satu panggilan alat, assemble_per_record, yang mengisi templat Word Anda sekali per elemen array JSON, menyimpan setiap hasil sebagai PDF terpisah yang dinamai berdasarkan bidang yang Anda pilih, dan melaporkan catatan yang gagal alih‑alih berhenti pada yang pertama:
Buat PDF surat selamat datang untuk setiap pelanggan di customers.json menggunakan welcome-letter.docx, dan beri nama setiap file sesuai dengan pelanggan.
Versi langkah‑demi‑langkah dengan konfigurasi dan pemecahan masalah ada di dokumentasi: Cara menghasilkan satu dokumen per catatan (mail merge) dengan agen AI.
Mengapa tidak membiarkan agen melakukan perulangan?
Agen bisa, dan untuk lima catatan itu cukup baik. Tetapi satu perulangan dengan empat puluh panggilan alat berarti empat puluh peluang bagi agen untuk kehilangan hitungan, melewatkan catatan ketika konteks menjadi panjang, atau “dengan baik” mengubah kembali satu surat. Alat per‑catatan memindahkan perulangan ke server: satu panggilan, satu templat, satu kali iterasi atas array, dan laporan yang menyebutkan tepat berapa file yang ditulis serta catatan mana yang tidak berhasil. Tugas agen adalah memilih templat, file data, dan bidang penamaan, lalu membaca laporan kembali kepada Anda.
Apa yang agen periksa pertama?
Dua hal: seperti apa data, dan apa yang dibaca templat. Dalam percobaan kami, lima pelanggan di customers.json dan satu surat selamat datang satu halaman:
-> get_document_info {"file":{"filePath":"customers.json"}}
<- { "dataKind": "json",
"data": { "root": "array", "length": 5, "keys": null } }
-> get_template_fields {"template":{"filePath":"welcome-letter.docx"}}
<- { "dataSourceNames": [ "customer" ],
"fields": [ "customer.Contact", "customer.Plan", "customer.Name",
"customer.Manager", "customer.FirstInvoice" ] }
Templat memanggil satu catatan customer; server menentukannya sendiri, jadi agen tidak perlu mengirim dataSourceName.
Satu panggilan, lima catatan, satu kegagalan
-> assemble_per_record {"template":{"filePath":"welcome-letter.docx"},
"data":{"filePath":"customers.json"},"fileNameField":"Name",
"format":"pdf"}
<- Assembled 4 of 5 document(s) from 'welcome-letter.docx' with
'customers.json', one per record (each record as 'customer'), as PDF.
Saved to:
.../Contoso Pharma.pdf
.../Fabrikam Logistics.pdf
.../Tailspin Toys.pdf
.../Litware Labs.pdf
1 record(s) failed:
record 4: InvalidOperationException: ... Can not get the value of
member 'FirstInvoice' on type 'System.Data.DataRow'. The template
reads 'FirstInvoice', which the data does not have. ...
Catatan 4, Wingtip Travel, tidak memiliki tanggal faktur pertama dalam data. Empat surat lainnya berhasil ditulis, masing‑masing dinamai sesuai pelanggan, dan kegagalan dilaporkan dengan nomor catatan serta bidang yang hilang. Agen melaporkan hal ini sebagai “empat surat selesai; Wingtip Travel tidak memiliki tanggal faktur pertama, apakah Anda ingin saya membiarkan baris kosong atau menunggu tanggalnya?”. Itulah percakapan yang Anda inginkan, bukan empat puluh file tanpa tahu mana yang salah.
Cara kerja fan-out
customers.json [ {Name:"Contoso Pharma",...}, {Name:"Fabrikam ..."},
... 5 records ]
|
assemble_per_record {"template":{"filePath":"welcome-letter.docx"},
"data":{"filePath":"customers.json"},
"fileNameField":"Name","format":"pdf"}
|
+--> Contoso Pharma.pdf
+--> Fabrikam Logistics.pdf ... 2 lagi
'--> "4 of 5 ... 1 record(s) failed: record 4 ..."
Tiga parameter yang melakukan pekerjaan. fileNameField menamai setiap output berdasarkan bidang pada catatan itu sendiri: Name di sini, atau jalur bertitik seperti order.Number ketika setiap catatan memiliki objek bersarang. Pada catatan datar ini, customer.Name gagal untuk semuanya (“catatan tidak memiliki bidang ‘customer.Name’ untuk menamai filenya”). Tanpa parameter ini, file mendapat nomor urut, dan nama yang sudah ada tidak pernah ditimpa: file baru mendapat (1). recordsPath menunjuk ke array ketika JSON adalah objek yang memuat satu, seperti "customers" atau "batch.items". Dan maxDocuments adalah remnya.
Apa yang menghentikan batch yang tidak terkendali?
maxDocuments, yang secara bawaan 100 dan dapat naik hingga 1000. Sebelum menulis apa pun, server menghitung catatan; jika lebih dari batas, server menolak. Kami mengaturnya menjadi 3 untuk lima pelanggan kami:
-> assemble_per_record {..., "maxDocuments":3}
<- Per-record assembly failed for 'welcome-letter.docx': there are 5
records, more than maxDocuments=3. Raise 'maxDocuments' (up to 1000)
or pass fewer records.
Tidak ada yang ditulis. Untuk pengiriman surat ke orang nyata, itulah bawaan yang tepat: sebuah prompt yang secara tidak sengaja menunjuk ke seluruh ekspor CRM akan menghasilkan pertanyaan kembali, bukan sepuluh ribu PDF.
Data saya berupa spreadsheet, bukan JSON
Generasi per‑catatan hanya membaca JSON: array objek, atau objek yang memuat satu. Ketika daftar berada dalam CSV atau lembar kerja, agen mengonversi baris‑baris ke JSON terlebih dahulu, yang dilakukan agen dengan baik, dan menulis file ke folder penyimpanan. Jika yang Anda inginkan adalah satu dokumen yang mencantumkan setiap baris, daftar harga, atau register, gunakan assemble_document dengan <<foreach>> di templat, dan ia membaca CSV serta spreadsheet secara langsung.
Batasan jujur
- Per-record assembly hanya membaca JSON; data CSV dan spreadsheet harus dikonversi terlebih dahulu.
- Mode evaluasi: setiap file yang dihasilkan dimulai dengan “Evaluation Only. Created with GroupDocs.Assembly 26.7…”, dan templat email hanya menyimpan isi teks polosnya. Lisensikan server sebelum pengiriman massal yang sesungguhnya.
- Field yang hilang menyebabkan catatan tersebut gagal.
allowMissingMembers: truemenulisnya dengan baris kosong; pilih mana yang Anda inginkan. - Tanggal: tulis dalam format
2026-12-01T00:00:00dan format di dalam templat, seperti surat kami menggunakan<<[customer.FirstInvoice]:"d MMMM yyyy">>. Sebuah string tanggal saja yang bergeser satu hari pada mesin UTC+2 dalam pengujian kami. - Server menulis file; tidak mengirimkannya. Pengiriman adalah langkah terpisah.
FAQ
Apakah saya dapat melakukan mail merge dengan Claude tanpa mengunggah daftar pelanggan?
Ya. Server berjalan secara lokal dan membaca customers.json dari folder penyimpanan Anda; PDF yang dihasilkan juga ditulis di sana.
Bagaimana nama file output?
Dengan bidang catatan yang Anda berikan sebagai fileNameField, di sini nama pelanggan, sehingga Contoso Pharma.pdf. Tanpa itu, nomor urut.
Bisakah setiap dokumen menjadi email alih‑alih PDF?
Ya, jika templatnya berupa email: templat EML atau MSG disimpan sebagai eml, emlx atau msg, satu pesan per catatan. Templat Word seperti surat ini tidak dapat disimpan sebagai email; server menjawab “a WordProcessing template cannot be saved as ’eml’”. Dalam mode evaluasi, badan HTML email diganti dengan baris evaluasi, jadi uji output email dengan lisensi.
Selami lebih dalam
- Dokumentasi, cara kanonik: Cara menghasilkan satu dokumen per catatan (mail merge) dengan agen AI
- Pusat dokumentasi: GroupDocs.Assembly MCP Server
- halaman produk GroupDocs.Assembly MCP — instalasi satu klik untuk VS Code dan Cursor, konfigurasi untuk setiap klien lain
- Mulai di sini: Biarkan model mengisi data, bukan menulis dokumen
- Terkait: Apa yang dibutuhkan templat ini? Tanyalah.
- Terkait: Diagram berasal dari templat, angka berasal dari data
- Terkait: Repositori Anda sudah memiliki data; biarkan agen membuat PDF
- Model on‑premise dan keamanan: 3 arsitektur untuk pemrosesan dokumen AI, dan yang menjaga file di dalam jaringan Anda
- Pertanyaan: GroupDocs Assembly forum
- Sumber: GroupDocs.Assembly.Mcp on GitHub