Mỗi kho lưu trữ tích lũy dữ liệu có cấu trúc mà ai đó cuối cùng cần dưới dạng tài liệu: các thay đổi trong một bản phát hành, những người đóng góp trong năm, một danh mục API, danh sách các rủi ro đang mở. Dữ liệu đã ở dạng JSON; bước còn thiếu là một tệp PDF hoặc Word được định dạng mà khách hàng, kiểm toán viên hoặc quản lý thực sự sẽ mở. Với GroupDocs.Assembly.Mcp chạy cục bộ bên cạnh Claude Code (claude mcp add với dnx GroupDocs.Assembly.Mcp --yes), tác nhân điền một mẫu Word được lưu trong repo từ một tệp JSON trong repo, và ghi ra PDF, mà không ai phải định dạng bảng:

Tạo PDF ghi chú phát hành cho phiên bản 4.2.0 từ data/release-4.2.0.json với templates/release-notes.docx, và một chứng nhận đóng góp cho mỗi người đóng góp trong data/contributors-2026.json.

Phiên bản từng bước với cấu hình và khắc phục sự cố có trong tài liệu: How to generate a PDF or Word report from JSON data in a repository with Claude Code.

Tại sao không để tác nhân lập trình viết tài liệu?

Các tác nhân lập trình rất giỏi trong việc tạo dữ liệu nhưng khá kém trong việc tạo tài liệu. Yêu cầu một tác nhân tạo “ghi chú phát hành dưới dạng PDF” và nó sẽ viết một tệp Markdown, sau đó một script chuyển đổi nó, rồi gỡ lỗi phông chữ của script. Phiên bản tiếp theo, nó lại làm lại một cách hơi khác. Kết quả trông giống như mặc định của thư viện chuyển đổi, không giống như các tài liệu công ty bạn gửi.

Một mẫu (template) cố định giao diện và đưa nó vào kiểm soát phiên bản. templates/release-notes.docx là một tệp Word bình thường có logo, các kiểu tiêu đề và một bảng, cộng với một vài thẻ <<…>>. Người sở hữu bố cục chỉnh sửa nó trong Word; tác nhân không bao giờ chạm vào. JSON được tạo bởi công cụ phát hành của bạn, hoặc bởi tác nhân từ git log, và đó là phần mà tác nhân lập trình làm tốt.

Nó cũng giúp công việc có thể được xem xét. Một pull request thay đổi data/release-4.2.0.json cho thấy chính xác những thay đổi sẽ xuất hiện trong ghi chú phát hành, dòng theo dòng, trong một diff mà người xem có thể đọc trong một phút. Một pull request thay đổi một PDF đã tạo ra không hiển thị gì cả. Giữ dữ liệu và bố cục dưới dạng các tệp riêng biệt, có phiên bản, và coi tài liệu như một thứ bạn render từ chúng, là cùng một ý tưởng như việc giữ mã nguồn và kết quả biên dịch tách biệt, và nó áp dụng cho tài liệu vì những lý do tương tự.

Cấu trúc kho lưu trữ

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

Các lời gọi

Đầu tiên tác nhân kiểm tra những gì mẫu yêu cầu, để có thể cho bạn biết nếu JSON thiếu gì đó:

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

Sau đó một lời gọi sẽ render nó:

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

Hàng bảng của mẫu được lặp lại một lần cho mỗi thay đổi, và dòng cuối cùng đếm số thay đổi và các tác giả riêng biệt bằng changes.Count() và changes.Select(c => c.Author).Distinct().Count(). Những con số này đến từ dữ liệu tại thời điểm render, không phải từ tác nhân.

Các chứng nhận là dạng fan-out: một PDF cho mỗi phần tử của mảng contributors, đặt tên theo handle của người đóng góp:

-> 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 cho server biết vị trí của mảng khi tệp JSON là một đối tượng, đây là dạng thường gặp của các tệp dữ liệu thực.

Biến nó thành thói quen, không phải một lời nhắc

Các tác nhân tuân theo hướng dẫn dự án về thời điểm sử dụng công cụ. Một vài dòng trong CLAUDE.md hoặc AGENTS.md biến điều này thành một quy ước:

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.

Giữ các đầu ra ra ngoài git. Mặc định server ghi bên cạnh thư mục lưu trữ của nó; đặt GROUPDOCS_MCP_OUTPUT_PATH trong đăng ký server tới thư mục out/ của repo và thêm thư mục đó vào .gitignore. JSON và mẫu là nguồn; PDF là một artefact của quá trình build, được tạo lại trong vài giây, và việc commit nó chỉ tạo ra các diff mà không ai có thể xem xét.

Giới hạn thực tế

  • Chế độ đánh giá: mỗi PDF bắt đầu bằng “Evaluation Only. Created with GroupDocs.Assembly 26.7…”. Thích hợp để thử nghiệm; cần cấp phép cho server trước khi bất kỳ tài liệu nào ra khỏi nhóm.
  • Mẫu là đầu vào đáng tin cậy. Các thẻ hình ảnh và tài liệu tải các đường dẫn và URL mà biểu thức của chúng trả về, vì vậy hãy xử lý một mẫu từ pull request như mã, và cung cấp cho server một thư mục lưu trữ duy nhất.
  • Ngày tháng: viết chúng dưới dạng 2026-11-03T00:00:00 và định dạng trong mẫu (<<[release.Date]:"d MMMM yyyy">>). Một chuỗi chỉ ngày đã bị dịch một ngày trên máy UTC+2 trong thử nghiệm của chúng tôi; hình ảnh Docker chạy ở UTC.
  • Việc tạo theo từng bản ghi chỉ đọc JSON, và maxDocuments (mặc định 100) ngăn một mảng quá lớn không mong muốn trước khi bất kỳ tài liệu nào được ghi.
  • get_template_fields là tĩnh: các giá trị được tính bên trong các phép chiếu Select hoặc GroupBy sẽ không được theo dõi.

Câu hỏi thường gặp

Claude Code có thể tạo PDF từ JSON trong kho lưu trữ của tôi mà không cần dịch vụ đám mây không?
Có. Máy chủ MCP chạy cục bộ như một tiến trình con của Claude Code và đọc mẫu và JSON từ thư mục bạn chỉ định.

Có thể chạy trong CI không?
Máy chủ là một MCP server, vì vậy nó cần một MCP client: Claude Code ở chế độ không giao diện, hoặc bất kỳ trình chạy tác nhân nào. Hình ảnh Docker (ghcr.io/groupdocs-assembly/assembly-net-mcp) là dạng tiện lợi cho một pipeline.

Word hay PDF?
Cả hai. Bỏ qua format và đầu ra sẽ là DOCX giống như mẫu; "format":"pdf" sẽ cho ra PDF. get_supported_formats liệt kê mọi định dạng mục tiêu cho mỗi mẫu.

Đi sâu hơn