모든 저장소는 누군가 결국 문서로 필요로 하는 구조화된 데이터를 축적합니다: 릴리스의 변경 사항, 연간 기여자, API 인벤토리, 열려 있는 위험 목록. 데이터는 이미 JSON 형태이며, 누락된 단계는 고객, 감사인 또는 관리자가 실제로 열어볼 수 있는 형식이 지정된 PDF 또는 Word 파일입니다. Claude Code 옆에 로컬로 실행되는 GroupDocs.Assembly.Mcp(claude mcp add와 dnx GroupDocs.Assembly.Mcp --yes 사용)와 함께, 에이전트는 저장소에 보관된 JSON 파일을 사용해 저장소에 보관된 Word 템플릿을 채우고 PDF를 작성합니다. 테이블을 직접 포맷할 필요가 없습니다:
data/release-4.2.0.json과 templates/release-notes.docx를 사용하여 4.2.0 릴리스 노트 PDF를 생성하고, data/contributors-2026.json에 있는 모든 기여자를 위한 기여 증명서를 생성합니다.
구성 및 문제 해결이 포함된 단계별 버전은 문서에 있습니다: Claude Code를 사용하여 저장소의 JSON 데이터에서 PDF 또는 Word 보고서를 생성하는 방법.
문서 작성을 코딩 에이전트에게 맡기지 않는 이유
Coding agents는 데이터를 생성하는 데는 매우 뛰어나지만 문서를 만드는 데는 꽤 서툽니다. “PDF 형식의 릴리스 노트"를 요청하면 마크다운 파일을 작성하고, 이를 변환하는 스크립트를 만든 뒤, 스크립트의 글꼴을 디버깅합니다. 다음 릴리스에서는 약간 다르게 다시 수행합니다. 출력은 변환 라이브러리의 기본값에 따라 나오며, 회사에서 보내는 문서와는 다릅니다.
템플릿은 외관을 고정하고 버전 관리 하에 둡니다. templates/release-notes.docx는 로고, 헤딩 스타일 및 표가 포함된 일반 Word 파일이며, 몇 개의 <<…>> 태그가 추가되어 있습니다. 레이아웃을 담당하는 사람은 Word에서 편집하고, 에이전트는 절대 건드리지 않습니다. JSON은 릴리스 도구에 의해 생성되거나 git log에서 에이전트가 생성하며, 이는 코딩 에이전트가 잘 수행하는 부분입니다.
또한 작업을 검토 가능하게 합니다. data/release-4.2.0.json을 변경하는 풀 리퀘스트는 릴리스 노트에 나타날 변경 사항을 정확히 라인별로 diff 형태로 보여주어 검토자가 1분 안에 읽을 수 있습니다. 생성된 PDF를 변경하는 풀 리퀘스트는 아무것도 보여주지 않습니다. 데이터를 레이아웃과 별개의 버전 관리 파일로 유지하고, 문서를 그들로부터 렌더링하는 것으로 취급하는 것은 소스 코드와 빌드 결과물을 분리하는 것과 같은 아이디어이며, 문서에도 동일하게 적용됩니다.
저장소 구조
./ (the repository, registered as the storage folder)
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":
"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":
"templates/release-notes.docx"},
"data":{"filePath":"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()를 사용해 변경 수와 고유한 작성자 수를 셉니다. 이러한 숫자는 렌더링 시점의 데이터에서 가져온 것이며, 에이전트에서 나온 것이 아닙니다.
증명서는 팬아웃 방식입니다: contributors 배열의 각 요소마다 하나의 PDF가 생성되며, 기여자의 핸들을 파일명으로 사용합니다:
-> assemble_per_record {"template":{"filePath":
"templates/certificate.docx"},
"data":{"filePath":"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를 저장소의 out/ 폴더로 설정하고 해당 폴더를 .gitignore에 추가하세요. JSON과 템플릿이 소스이며, PDF는 몇 초 안에 재생성되는 빌드 산출물입니다. 이를 커밋하면 검토할 수 없는 diff만 생성됩니다.
솔직한 제한 사항
- 평가 모드: 모든 PDF는 “Evaluation Only. Created with GroupDocs.Assembly 26.7…” 로 시작합니다. 테스트용으로는 괜찮지만, 팀을 떠나기 전에 서버에 라이선스를 적용하세요.
- 템플릿은 신뢰할 수 있는 입력입니다. 이미지 및 문서 태그는 표현식이 반환하는 경로와 URL을 로드하므로, 풀 리퀘스트에서 온 템플릿을 코드처럼 취급하고 서버에 하나의 스토리지 폴더만 제공하세요.
- 날짜:
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 또는 any agent runner. Docker 이미지(ghcr.io/groupdocs-assembly/assembly-net-mcp)는 파이프라인에 편리한 형태이며, Linux 러너에서는 --user "$(id -u):$(id -g)" 옵션을 추가해야 합니다. 이미지가 비루트 사용자로 실행되며 체크아웃 디렉터리에 쓸 수 있어야 하기 때문입니다.
Word 또는 PDF?
둘 다 가능합니다. format을 생략하면 출력은 템플릿과 같은 DOCX가 되고, "format":"pdf"는 PDF를 생성합니다. get_supported_formats는 템플릿별 모든 대상 형식을 나열합니다.
더 깊이 파고들기
- 문서, 정식 사용법: Claude Code를 사용하여 저장소의 JSON 데이터에서 PDF 또는 Word 보고서를 생성하는 방법
- 문서 허브: GroupDocs.Assembly MCP Server
- GroupDocs.Assembly MCP 제품 페이지 — VS Code와 Cursor에 원클릭 설치, 다른 모든 클라이언트에 대한 구성
- 시작하기: 모델이 데이터를 채우게 하고, 문서는 작성하지 않게 하기
- 관련: 한 프롬프트로 백 개의 맞춤형 PDF 만들기: AI 에이전트와 메일 머지
- 관련: 이 템플릿에 무엇이 필요한가? 물어보세요.
- 관련: 차트는 템플릿에서, 숫자는 데이터에서
- 온프레미스 및 보안 모델: AI 문서 처리용 3가지 아키텍처와 파일을 네트워크 내부에 보관하는 방법
- 질문: GroupDocs Assembly 포럼
- 소스: GroupDocs.Assembly.Mcp on GitHub