누군가가 워드 템플릿과 마감일을 건네줍니다. 어떤 데이터를 원할까요? 일반적인 답은 템플릿을 열고, 스크롤하고, 추측하고, 실행하고, 오류를 읽고, 다시 실행하는 것입니다. GroupDocs.Assembly.Mcp를 로컬에서 실행(dnx GroupDocs.Assembly.Mcp --yes)하면, Claude Desktop, Cursor 또는 Copilot이 템플릿에 직접 물어봅니다: get_template_fields는 모든 태그와 사용되는 데이터 이름, 그리고 채워야 할 JSON 스켈레톤을 반환하며, 엔진을 실행하지 않아도 되고, 실행이 실패하면 오류가 무엇을 바꿔야 하는지 알려줍니다:

order‑lines.docx에 어떤 데이터가 필요합니까? 생성되지 않으면, 왜 그런지와 템플릿을 어떻게 수정해야 하는지 알려 주세요.

The step‑by‑step version with config and troubleshooting is in the documentation: 템플릿에 어떤 것이 필요한지 그리고 왜 실패했는지 알아보는 방법.

채우기 전에 검토하는 이유

시도와 오류는 스키마를 배우는 비용이 많이 드는 방법이기 때문입니다. 문서의 보이는 텍스트에서 필드 이름을 추측하는 에이전트는 템플릿이 customer.Name이라고 적혀 있을 때 CustomerName을 추측하게 되며, 잘못된 추측마다 왕복 호출과 혼란스러운 오류가 발생합니다. 템플릿은 산문이 아니라 데이터 계약을 가진 프로그램이며, 그 계약은 읽을 수 있습니다.

get_template_fields가 하는 일은 바로 그것입니다. <<…>> 태그를 파싱하고 이름을 파악한 뒤 스켈레톤을 구축합니다:

-> get_template_fields {"template":{"filePath":"order-lines.docx"}}
<- { "tagCount": 3,
     "dataSourceNames": [ "lines" ],
     "fields": [ "lines[].Title", "lines[].Quantity" ],
     "dataSkeleton": { "lines": [ { "Title": "", "Quantity": "" } ] },
     "notes": [ "fields and dataSkeleton are inferred from the tags,
       not from the engine; values computed by Select/GroupBy
       projections are not followed." ] }

노트는 이 방법에 대해 솔직히 설명합니다: 이것은 정적 검토입니다. Select 프로젝션 내부에서 생성된 필드는 추적되지 않습니다. 일반 계약서, 편지 또는 청구서 템플릿의 경우, 스켈레톤이 바로 채워야 할 내용입니다.

스켈레톤은 당신과의 대화 방식도 바꿉니다. “주문을 생성하려고 했지만 실패했습니다” 대신, 에이전트는 “이 템플릿은 각 라인에 제목과 수량이 있는 라인 목록이 필요합니다; 이메일에서 세 개를 찾았으니 여기 있습니다” 라고 말하고 나서야 생성합니다. 검토는 비용이 적고 데이터가 필요 없으며 아무 것도 건드리지 않으므로, 에이전트가 아직 보지 못한 모든 템플릿에 대한 첫 번째 호출에 적합하고, 누군가 템플릿을 수정했을 때도 다시 호출하기에 적합합니다.

세 가지 실패, 세 가지 해결책

템플릿 문제               서버가 말하는 내용                     해결 방법
------------------------  ----------------------------  -------------------
{{name}} 자리표시자       "2 '{{...}}' 자리표시자. <<[name]>>를      <<[name]>>를 작성하십시오 ...
                          작성하십시오 ... 해당 구문을 처리하지
                          않습니다"
<<foreach>> 닫히지 않음   "템플릿이 예상치 못하게 종료되었습니다.   <</foreach>>를 추가하십시오
                          <</foreach>>를 추가하십시오 블록 태그가   블록 태그가 닫히지 않았습니다"
                          닫히지 않았습니다"
데이터에 필드가 없음       "템플릿이 'Email'을 읽고 있습니다,      allowMissingMembers
                          추가하거나 데이터에 존재하지 않는 경우"

잘못된 구문. 실제로 많이 사용되는 템플릿 중 상당수가 다른 엔진용으로 작성되어 {{name}}를 사용합니다. GroupDocs.Assembly는 이를 텍스트로 남기며, 검토는 실행을 낭비하기 전에 이를 알려줍니다:

-> get_template_fields {"template":{"filePath":"shipping-notice.docx"}}
<- { "tagCount": 0, "notes": [ "No <<…>> tags were found: ...",
     "The template contains 2 '{{…}}' placeholder(s). GroupDocs.Assembly
      does not process that syntax and leaves it as text; write
      <<[name]>> instead." ] }

닫히지 않은 블록. 우리의 order-lines.docx는 <<foreach>>를 열고 닫지 않습니다. 검토는 태그를 기쁘게 나열하지만, 생성은 그렇지 않습니다:

-> assemble_document {"template":{"filePath":"order-lines.docx"},
     "dataJson":"{\"lines\":[{\"Title\":\"Cable\",\"Quantity\":2}]}"}
<- Document assembly failed for 'order-lines.docx': ...
   Unexpected end of template. A block tag is not closed: every
   <<foreach>> needs <</foreach>> and every <<if>> needs <</if>>.

필드 누락. 데이터에 템플릿이 읽는 항목이 없을 때, 오류는 해당 필드명을 표시하고 이름이 대소문자를 구분한다는 점을 알리며 스위치를 제안합니다: allowMissingMembers: true는 누락된 멤버와 빈 리스트에 대해 아무 것도 출력하지 않아 실패를 방지합니다. 이 힌트는 엔진보다 더 넓은 범위에 적용되며, 다음 섹션에서 보듯이 템플릿이 멤버에 대해 산술 연산을 수행할 경우 빈 리스트도 여전히 실패합니다.

템플릿에 실수가 많을 때

일부 템플릿은 여러 오류를 가지고 있으며, 한 번에 하나씩 실패하면서 수정하는 것은 느립니다. inlineErrors: true는 템플릿을 자체 오류 보고서로 변환합니다: 문서가 생성되고 각 잘못된 태그 옆에 메시지가 작성됩니다. GroupDocs.Assembly 예제의 샘플 템플릿에서:

-> assemble_document {"template":{"filePath":"inline-error.docx"},
     "dataJson":"{\"name\":\"x\"}","inlineErrors":true}
<- Assembled 'inline-error.docx' ... The template has errors: each one
   is written into the output next to its tag, starting with 'Error!'

출력에는 << var [name] Error! An assignment operator is expected. >>가 포함되어 있으며, 이는 태그가 위치한 문서의 해당 위치에 나타납니다. 파일을 열어 모든 표시된 태그를 수정하고 플래그 없이 다시 실행하십시오.

검토로 볼 수 없는 것

바이너리 Outlook 템플릿은 예외입니다. .msg 파일의 태그는 생성하지 않으면 읽을 수 없으며, 서버는 “필드 없음"처럼 보이는 빈 리스트를 반환하는 대신 이를 알려줍니다:

-> get_template_fields {"template":{"filePath":"contracts-table.msg"}}
<- { "readable": false, "notes": [ "Tags cannot be read from a .msg
     template without generating it. Save the template as DOCX, XLSX,
     PPTX or EML to inspect it, or generate it with assemble_document
     and inlineErrors=true to see which fields fail." ] }

우리가 또 마주한 함정: 데이터에 빈 리스트가 있으면 멤버 타입이 없습니다. 우리 계약 템플릿은 item.Quantity * item.UnitPrice를 곱합니다; "items": []와 allowMissingMembers: true를 사용해도 생성은 ‘System.Object’와 ‘System.Object’ 타입의 피연산자에 ‘’ 연산자를 적용할 수 없습니다* 라는 오류로 실패했습니다. 테이블 주변에 <<if [items.Any()]>>와 같은 명백한 방어문도 도움이 되지 않았습니다: 엔진은 어떤 실행도 하기 전에 모든 표현식을 검사합니다. 효과가 있었던 것은 행에서 산술 연산을 제외하는 것이었습니다. 데이터에 이미 금액이 포함되어 있으면 (<<[item.Amount]>>), 동일한 빈 리스트와 allowMissingMembers: true가 문서를 생성했고, <<if [items.Count() == 0]>>No services ordered.<</if>>가 해당 라인을 출력했습니다. 그렇지 않다면, 에이전트가 리스트가 비어 있지 않은지 확인하도록 하고, 빈 계약이 어떻게 보여야 하는지 물어보세요.

솔직한 한계

  • 검토는 정적입니다: Select 및 GroupBy 프로젝션은 추적되지 않으며, .msg 템플릿은 읽을 수 없습니다.
  • 템플릿은 신뢰된 입력이며, 이미지 및 문서 태그는 표현식이 반환하는 경로와 URL을 로드합니다.
  • 평가 모드: 모든 출력은 “Evaluation Only. Created with GroupDocs.Assembly 26.7…” 로 시작합니다.
  • 날짜: 2026-11-12T00:00:00을 전달하고 템플릿에서 :"d MMMM yyyy"로 포맷하십시오; 날짜 전용 문자열은 UTC+2 머신에서 하루가 이동했으며, "12.11.2026"은 12월 11일로 읽혔습니다.

FAQ

Word 템플릿에 어떤 필드가 필요한지 어떻게 확인하나요?
에이전트에게 get_template_fields를 호출하도록 요청하십시오. 태그, 데이터 이름 및 JSON 스켈레톤을 로컬에서, 아무 것도 생성하지 않고 얻을 수 있습니다.

템플릿이 값을 대신해 {{name}}을 출력하는 이유는 무엇인가요?
GroupDocs.Assembly 태그는 <<[name]>>이기 때문입니다. 서버의 검토는 {{…}} 자리표시자를 표시하고 대신 무엇을 작성해야 하는지 알려줍니다.

Markdown을 템플릿으로 사용할 수 있나요?
네. <<[product]>>와 <<[description]>> 태그가 포함된 우리의 product-readme.md는 Word 파일처럼 검토되었으며 바로 DOCX로 생성되었습니다.

더 깊이 들어가기