Quelqu’un vous remet un modèle Word et une échéance. Quelles données veut‑il ? La réponse habituelle est d’ouvrir le fichier, de faire défiler, de deviner, de l’exécuter, de lire l’erreur, puis de réessayer. Avec GroupDocs.Assembly.Mcp exécuté localement (dnx GroupDocs.Assembly.Mcp --yes), Claude Desktop, Cursor ou Copilot interrogent directement le modèle : get_template_fields renvoie chaque balise, les noms de données qu’il utilise et un squelette JSON à remplir, sans lancer le moteur, et lorsqu’une exécution échoue, l’erreur indique ce qu’il faut modifier :
Quelles données
order-lines.docxnécessite ? Si cela ne génère pas, dites‑moi pourquoi et comment corriger le modèle.
La version pas à pas avec configuration et dépannage se trouve dans la documentation : How to find out what a template needs and why it failed.
Pourquoi inspecter avant de remplir ?
Parce que l’essai‑erreur est la façon coûteuse d’apprendre un schéma. Un agent qui devine les noms de champs à partir du texte visible d’un document devinera CustomerName alors que le modèle lit customer.Name, et chaque mauvaise supposition coûte un aller‑retour et une erreur déroutante. Un modèle n’est pas de la prose ; c’est un programme avec un contrat de données, et le contrat peut être lu.
C’est tout ce que fait get_template_fields. Il analyse les balises <<…>>, détermine les noms et construit le squelette :
-> 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." ] }
La note est honnête sur la méthode : il s’agit d’une inspection statique. Un champ produit à l’intérieur d’une projection Select n’est pas suivi. Pour un contrat normal, une lettre ou un modèle de facture, le squelette est exactement ce qu’il faut remplir.
Le squelette change également la conversation avec vous. Au lieu de « J’ai essayé de générer la commande et ça a échoué », l’agent peut dire « ce modèle a besoin d’une liste de lignes, chacune avec un titre et une quantité ; j’en ai trouvé trois dans votre e‑mail, les voici », puis ne générer qu’après. L’inspection est peu coûteuse, ne nécessite aucune donnée et ne touche rien, c’est donc le premier appel approprié pour tout modèle que l’agent n’a jamais vu, et le bon appel à nouveau chaque fois que quelqu’un a modifié le modèle depuis.
Trois échecs, trois réponses
problème de modèle ce que le serveur indique la solution
------------------------ ---------------------------- -------------------
{{name}} placeholders "2 '{{...}}' espace(s) réservé(s). write <<[name]>>
... does not process that
syntax"
<<foreach>> never closed "Unexpected end of template. add <</foreach>>
A block tag is not closed"
les données manquent d’un champ "The template reads 'Email', add it, or
which the data does not have" allowMissingMembers
La mauvaise syntaxe. De nombreux modèles trouvés « dans la nature » ont été écrits pour d’autres moteurs et utilisent {{name}}. GroupDocs.Assembly laisse ces balises telles quelles, et l’inspection le signale avant que quiconque ne gaspille une exécution :
-> 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." ] }
Le bloc non fermé. Notre order-lines.docx ouvre un <<foreach>> et ne le ferme jamais. L’inspection liste les balises sans problème ; la génération, non :
-> 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>>.
Le champ manquant. Lorsque les données ne contiennent pas ce que le modèle lit, l’erreur indique le champ, précise que les noms sont sensibles à la casse et propose l’option : allowMissingMembers: true ne produit rien pour les membres manquants et renvoie des listes vides au lieu d’échouer. Cette indication dépasse le moteur, comme le montre la section suivante : une liste vide échoue toujours lorsque le modèle effectue des opérations arithmétiques sur ses membres.
Quand le modèle est truffé d’erreurs
Certains modèles comportent plusieurs erreurs, et les corriger une exécution ratée à la fois est lent. inlineErrors: true transforme le modèle en son propre rapport d’erreurs : le document est généré et chaque balise défectueuse reçoit son message écrit à côté. Sur le modèle d’exemple des exemples 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!'
La sortie contient << var [name] Error! An assignment operator is expected. >>, à l’endroit du document où se trouve la balise. Ouvrez le fichier, corrigez chaque balise marquée, relancez sans le drapeau.
Ce que l’inspection ne peut pas voir
Les modèles binaires Outlook sont l’exception. Les balises d’un fichier .msg ne peuvent pas être lues sans le générer, et le serveur l’indique plutôt que de renvoyer une liste vide qui ressemblerait à « aucun champ » :
-> 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." ] }
Un autre piège que nous avons rencontré : une liste vide dans les données n’a aucun type de membre. Notre modèle de contrat multiplie item.Quantity * item.UnitPrice ; avec "items": [] et allowMissingMembers: true, la génération échoue quand même avec “Can not apply operator ‘’ to operands of type ‘System.Object’ and ‘System.Object’”*. La garde évidente, <<if [items.Any()]>> autour du tableau, n’a pas aidé : le moteur vérifie chaque expression avant d’exécuter quoi que ce soit. Ce qui a fonctionné, c’est d’éviter l’arithmétique dans la ligne. En plaçant le montant déjà dans les données (<<[item.Amount]>>), la même liste vide et allowMissingMembers: true ont produit le document, et <<if [items.Count() == 0]>>No services ordered.<</if>> a affiché sa ligne. Sinon, faites vérifier à l’agent qu’une liste n’est pas vide avant de générer, et demandez‑lui à quoi doit ressembler un contrat vide.
Limites honnêtes
- L’inspection est statique : les projections
SelectetGroupByne sont pas suivies, et les modèles.msgne peuvent pas être lus. - Les modèles sont des entrées de confiance ; les balises image et document chargent les chemins et URL que leurs expressions renvoient.
- Mode évaluation : chaque sortie commence par “Evaluation Only. Created with GroupDocs.Assembly 26.7…”.
- Dates : passez
2026-11-12T00:00:00et formatez dans le modèle avec:"d MMMM yyyy"; une chaîne contenant uniquement la date a été décalée d’un jour sur une machine UTC+2, et"12.11.2026"a été interprétée comme le 11 décembre.
FAQ
Comment voir quels champs un modèle Word nécessite ?
Demandez à l’agent d’appeler get_template_fields dessus. Vous obtenez les balises, les noms de données et un squelette JSON, localement, sans rien générer.
Pourquoi mon modèle affiche-t-il {{name}} au lieu de la valeur ?
Parce que les balises GroupDocs.Assembly sont <<[name]>>. L’inspection du serveur signale les espaces réservés {{…}} et indique ce qu’il faut écrire à la place.
Le Markdown peut‑il être un modèle ?
Oui. Notre product-readme.md contenant les balises <<[product]>> et <<[description]>> a été inspecté comme un fichier Word et généré directement en DOCX.
Approfondir
- Documentation, guide canonique : How to find out what a template needs and why it failed
- Hub de documentation : GroupDocs.Assembly MCP Server
- GroupDocs.Assembly MCP product page — installation en un clic pour VS Code et Cursor, configurations pour tous les autres clients
- Commencez ici : Let the model fill in the data, not write the document
- Connexe : A hundred personalised PDFs from one prompt: mail merge with an AI agent
- Connexe : The chart comes from the template, the numbers come from the data
- Connexe : Your repo already has the data; let the agent make the PDF
- Sur site et modèle de sécurité : 3 architectures for AI document processing, and the one that keeps files inside your network
- Questions : GroupDocs Assembly forum
- Source : GroupDocs.Assembly.Mcp on GitHub