每個儲存庫都會累積結構化資料，最終需要以文件形式呈現：發行版的變更、年度貢獻者、API 清單、未解決風險清單。資料已經是 JSON；缺少的步驟是將其格式化為 PDF 或 Word 檔，讓客戶、稽核員或經理實際打開。透過在 Claude Code 旁本機執行的 GroupDocs.Assembly.Mcp（claude mcp add 搭配 dnx GroupDocs.Assembly.Mcp --yes），代理會從儲存庫中的 JSON 檔填入儲存庫內的 Word 範本，並寫出 PDF，無需任何人手動排版表格：

為 4.2.0 產生 release notes PDF，資料來源為 data/release-4.2.0.json，範本為 templates/release-notes.docx，並為 data/contributors-2026.json 中的每位貢獻者產生貢獻證書。

逐步說明（含設定與除錯）請參考文件：如何在儲存庫中使用 Claude Code 從 JSON 資料產生 PDF 或 Word 報告

為什麼不讓程式編寫代理撰寫文件？

程式編寫代理非常擅長產生資料，卻相當不擅長產生文件。若要求它「以 PDF 形式的 release notes」，它會先寫出 Markdown 檔，接著產生轉換腳本，然後除錯腳本的字型。下一個發行版又會稍微不同地重複這個流程。最終輸出看起來像是轉換函式庫的預設樣式，而不是貴公司實際發送的文件。

範本可以固定外觀並放入版本控制。templates/release-notes.docx 是一個普通的 Word 檔，內含商標、標題樣式與表格，還有少量 <<…>> 標記。負責版面的人在 Word 中編輯它；代理永遠不會觸碰它。JSON 由您的發行工具產生，或由代理從 git log 取得，這正是程式編寫代理擅長的部分。

此外，這也讓工作可供審查。變更 data/release-4.2.0.json 的 Pull Request 能夠逐行顯示哪些變更會出現在 release notes 中，審查者只需一分鐘即可閱讀差異。變更已產生的 PDF 的 Pull Request 則什麼都看不見。將資料與版面分別存放為獨立的、具版本的檔案，並把文件視為從它們渲染出的產物，與將原始程式碼與建置輸出分離的概念相同，對文件同樣適用。

儲存庫的結構

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

呼叫方式

首先，代理會檢查範本需要哪些欄位，以便告知您 JSON 是否缺少某些資料：

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

接著執行一次呼叫進行渲染：

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

範本的表格列會依每筆變更重複一次，最後一行會使用 changes.Count() 與 changes.Select(c => c.Author).Distinct().Count() 計算變更數量與不同作者數。這些數字是渲染時從資料取得的，而非由代理產生。

證書則是以 fan‑out 方式產生：對 contributors 陣列的每個元素產生一份 PDF，檔名以貢獻者的 handle 命名：

-> 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 為物件時陣列位於何處，這是實際資料檔的常見結構。

讓它成為習慣，而非一次性提示

代理會遵循專案指示何時使用工具。只要在 CLAUDE.md 或 AGENTS.md 中寫幾行，即可將此規範化：

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.

將產出檔案排除於 git 之外。預設情況下伺服器會寫入其儲存資料夾旁；在伺服器註冊時將 GROUPDOCS_MCP_OUTPUT_PATH 設為 repo 的 out/ 資料夾，並將該資料夾加入 .gitignore。JSON 與範本是來源；PDF 是建置產物，會在數秒內重新產生，將其提交只會產生無法審查的差異。

誠實的限制

  • 評估模式：每個 PDF 都會以 “Evaluation Only. Created with GroupDocs.Assembly 26.7…” 開頭。可用於測試；在任何檔案離開團隊前請先為伺服器取得授權。
  • 範本屬於受信任的輸入。影像與文件標記會載入其表達式回傳的路徑與 URL，因此請將來自 Pull Request 的範本視為程式碼，並僅提供伺服器一個儲存資料夾。
  • 日期：請寫成 2026-11-03T00:00:00，並在範本中格式化（<<[release.Date]:"d MMMM yyyy">>）。在我們的測試中，僅有日期的字串在 UTC+2 的機器上會被推遲一天；Docker 映像則以 UTC 執行。
  • 每筆記錄產生僅讀取 JSON，且 maxDocuments（預設 100）會在陣列過大時阻止寫入任何檔案。
  • get_template_fields 為靜態：在 Select 或 GroupBy 投影內計算的值不會被追蹤。

常見問題

Claude Code 能否在不使用雲端服務的情況下，直接從我的儲存庫 JSON 產生 PDF？
可以。MCP 伺服器會以子行程方式在本機執行於 Claude Code，並從您指定的資料夾讀取範本與 JSON。

這可以在 CI 中執行嗎？
伺服器本身是 MCP 伺服器，因此需要 MCP 用戶端：以無頭模式執行的 Claude Code，或任何代理執行器。Docker 映像（ghcr.io/groupdocs-assembly/assembly-net-mcp）是建置管線中最方便的形式。

Word 還是 PDF？
兩者皆可。若省略 format，輸出會是與範本相同的 DOCX；設定 "format":"pdf" 則會產生 PDF。get_supported_formats 會列出每個範本支援的所有目標格式。

深入了解