groupdocs-assembly-mcp

GroupDocs.Assembly MCP 服务

让 Claude、Cursor、GitHub Copilot 和任何其他 MCP Agent 根据模板和数据生成 Word、Excel、PowerPoint、PDF 和电子邮件文档——包括合同、发票、信件、报告和证书——通过 JSON、XML、CSV 或电子表格数据填充模板中的 <<[field]>>、<<foreach>>、<<if>>、表格、图表、图像 和条形码标签。生成一份文档，或为每条记录生成一份。 本地运行：模板和数据绝不会离开你的计算机。

60 秒内完成安装

一键安装会预填所有受支持的设置：安装后编辑占位文档文件夹（输出默认使用同一文件夹）；GROUPDOCS_LICENSE_PATH 为空时将以评估模式运行——将其指向你的许可证即可解除限制。

更多客户端——Claude Code、Codex CLI、Visual Studio 2022、Cursor、Windsurf、Cline 和 JetBrains Rider 的现成配置位于 install/generated/。

原生运行需要 .NET 10 SDK——也可以直接使用 Docker。

直接使用 dnx 运行（推荐——无需安装）：

dnx GroupDocs.Assembly.Mcp --yes

每次调用都会拉取最新的稳定版本。要固定版本（共享配置和 CI 推荐），请追加 @<version>：

dnx [email protected] --yes

服务从 GROUPDOCS_MCP_STORAGE_PATH 读取模板和数据（默认值：当前目录），并将生成的文档也写入该目录。它绝不会覆盖已有文件：若文件名已被占用，会添加 (1) 后缀。

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "groupdocs-assembly": {
      "type": "stdio",
      "command": "dnx",
      "args": ["GroupDocs.Assembly.Mcp", "--yes"],
      "env": {
        "GROUPDOCS_MCP_STORAGE_PATH": "/path/to/documents"
      }
    }
  }
}

若要使用许可证，请将 "GROUPDOCS_LICENSE_PATH": "/path/to/GroupDocs.Assembly.lic" 添加到 env 中—— 若要以评估模式运行，则省略此项。

Claude Code

claude mcp add groupdocs-assembly -- dnx GroupDocs.Assembly.Mcp --yes

VS Code / GitHub Copilot

使用上方的 Install in VS Code 按钮，或将NuGet 包页面中的现成代码片段复制到 .vscode/mcp.json， 也可以从此仓库获取 install/generated/vscode-mcp.json。

Visual Studio 2022 (17.14+)

在解决方案根目录中创建 .mcp.json，内容取自 install/generated/vs2022-mcp.json。

Cursor · Windsurf · Cline · Rider · Codex

• Cursor — 使用上方的 Add to Cursor 按钮，或将 install/generated/claude-desktop.json 粘贴到 ~/.cursor/mcp.json。
• Windsurf — 按照 install/generated/windsurf.md 操作。
• Cline — 将 install/generated/cline.json 粘贴到 Cline 的 MCP 设置中。
• JetBrains Rider — 按照 install/generated/rider.md 操作。
• Codex CLI — codex mcp add groupdocs-assembly -- dnx GroupDocs.Assembly.Mcp --yes，详情见 install/generated/codex.md。

Docker

docker run --rm -i \
  -v "$(pwd)/documents:/data" \
  ghcr.io/groupdocs-assembly/assembly-net-mcp:latest

镜像发布在 GHCR（ghcr.io/groupdocs-assembly/assembly-net-mcp）和 Docker Hub （groupdocs/assembly-net-mcp），支持 linux/amd64 和 linux/arm64，标签包括 latest 以及与每个 NuGet 版本对应的不可变版本标签（例如 :26.11.0）。镜像包含引擎所需的所有本机库和字体。

Linux 上的 Docker：以当前用户身份运行容器

镜像以非 root 用户（uid 1654）运行，绑定挂载会保留主机上的所有者，因此在 Linux 主机上，除非容器以当前用户身份运行，否则服务写入 /data 的所有文档都会因 Permission denied 而失败：

docker run --rm -i --user "$(id -u):$(id -g)" \
  -v "$(pwd)/documents:/data" \
  ghcr.io/groupdocs-assembly/assembly-net-mcp:latest

JSON 客户端配置不会运行 shell，因此请将这些数字写入 "args": ["run", "--rm", "-i", "--user", "1000:1000", …]。Windows 和 macOS 上的 Docker Desktop 无需此设置。

全局 dotnet 工具

dotnet tool install -g GroupDocs.Assembly.Mcp
groupdocs-assembly-mcp

可用的 MCP 工具

工具	功能
assemble_document	使用数据填充模板并保存结果——可保存为模板原格式、同一格式系列中的其他格式或 PDF。数据可内嵌（dataJson），也可来自 .json、.xml、.csv/.tsv 文件或文档中的表格（data）
assemble_per_record	邮件合并：为 JSON 数组中的每个元素生成一份文档——例如为每位客户生成一封信、为每笔订单生成一张发票——并以连续编号或记录字段命名
get_template_fields	列出模板的标签、数据使用的名称、模板读取的字段，以及用于填充数据的 JSON 框架——无需运行引擎或提供数据（JSON）
get_document_info	将文件作为模板时的信息（格式系列、标签数量、数据名称、保存目标），以及将文件作为数据时的信息（JSON 键、CSV 表头、电子表格、Word 或演示文稿文档中的表格）（JSON）
get_supported_formats	模板格式、各格式系列可保存的格式以及数据格式（JSON）
get_license_status	许可模式、计量用量和引擎版本（由 GroupDocs.Mcp.Core 提供）

每次失败都会设置 isError，并以工具前缀开头，例如 Document assembly failed for 'invoice.docx': …，因此客户端只需进行一次检查。消息中会指出数据缺少的字段。

数据如何到达模板

• JSON 对象的键就是模板的名称。 {"customer": {…}, "items": […]} 会填充 <<[customer.Name]>> 和 <<foreach [i in items]>> — 即 get_template_fields 以 dataSkeleton 返回的结构。
• 数组、XML、CSV 或表格都视为一个集合；服务会根据模板使用的集合为其命名（<<foreach [c in customers]>> → customers），也可以传入 dataSourceName。
• JSON 值会保留其 JSON 类型："007" 仍是文本（引擎默认会将其转换为 7）。

面向 AI Agent 的示例提示词

Fill invoice-template.docx with this order and save it as a PDF: …
What data does contract-template.docx need? Give me a JSON skeleton.
Generate a welcome letter for every customer in customers.json, named after the customer.
Build the quarterly report from report-template.xlsx and sales.csv.
Turn the rows of attendees.xlsx into one certificate each from certificate.pptx.

评估模式

MCP 服务本身采用 MIT 许可；GroupDocs.Assembly 引擎用于生产环境时需要许可证。 未提供许可证时，所有工具仍可使用，但有以下限制（基于 GroupDocs.Assembly 26.7.0 测量）：

• 生成的文档开头会出现一行 "Evaluation Only. Created with GroupDocs.Assembly …"。
• 保存的工作簿会多出一个工作表。
• 电子邮件只保留纯文本正文：HTML 正文（MSG 模板通常会在其中保留表格）会被评估提示行替换，另存为文档的电子邮件文本也会如此。

未发现行数、页数或文档数量限制（测试包括 200 行的表格和连续生成 25 份文档）。生成工具的响应会以一行 Evaluation mode: 开头。调用 get_license_status 可查看当前启用的模式。

许可

服务有两种许可方式。

许可证文件 — 将 GROUPDOCS_LICENSE_PATH 指向你的 GroupDocs.Assembly（或 GroupDocs.Total）许可证文件。可离线使用。

计量付费（按使用量付费） — 同时设置 GROUPDOCS_METERED_PUBLIC_KEY 和 GROUPDOCS_METERED_PRIVATE_KEY。按处理量付费，适合 Agent 工作负载。如果同时配置了计量密钥对和许可证文件，计量模式优先，许可证文件将被忽略。

计量模式需要出站网络连接。 使用情况会报告给 GroupDocs 服务器，因此隔离网络或受防火墙保护的部署必须允许此类出站流量 — 或改用许可证文件。

避免在配置中暴露私钥

计量私钥属于机密信息。MCP 客户端配置是纯文本文件，而且按照惯例，项目级 .mcp.json 会提交到版本控制，因此建议按以下顺序处理：

1. 在操作系统环境中设置变量，完全不将其写入配置 — stdio MCP 服务会继承客户端的环境。在 macOS 上，从 Finder 启动的应用不会继承 Shell 导出变量；请使用 launchctl setenv，或从终端启动客户端。
2. 如果客户端支持，则间接引用变量（Claude Code 会展开 ${VAR}；VS Code 使用 ${env:VAR} 和 ${input:...}）。
3. 在用户级配置中填写字面值（例如 ~/.claude.json），单个开发者使用时可以接受。
4. 切勿在项目级 .mcp.json 中提交字面密钥。

使用 Docker 时，请转发这些值，不要将其写入任何文件：

docker run --rm -i \
  -e GROUPDOCS_METERED_PUBLIC_KEY -e GROUPDOCS_METERED_PRIVATE_KEY \
  -v /path/to/documents:/data \
  ghcr.io/groupdocs-assembly/assembly-net-mcp:latest

• 获取免费的 30 天临时许可证
• 购买许可证 · 产品页面

配置

变量	描述	默认值
GROUPDOCS_MCP_STORAGE_PATH	模板、数据和生成文档的基础文件夹	当前目录
GROUPDOCS_MCP_OUTPUT_PATH	*（可选）*生成文档的独立文件夹	GROUPDOCS_MCP_STORAGE_PATH
GROUPDOCS_LICENSE_PATH	GroupDocs 许可证文件的路径	（评估模式）
GROUPDOCS_METERED_PUBLIC_KEY	计量公钥。也需要私钥；优先于许可证文件	（未设置）
GROUPDOCS_METERED_PRIVATE_KEY	计量私钥。机密信息 — 参见许可	（未设置）

原生依赖

Word、电子表格和电子邮件模板通过 Aspose.Drawing 和 SkiaSharp 绘制，这些原生库包含在程序包中。演示文稿模板（PPTX、PPT、ODP，以及保存为 PDF 的幻灯片）通过 System.Drawing.Common 绘制，在 Linux 和 macOS 上需要 GDI+ 库。PDF 和 XPS 输出需要排版文本，因此 Linux 还需要真实字体：

平台	设置
Windows	无需设置。
Linux	sudo apt-get install -y libgdiplus libfontconfig1 ttf-mscorefonts-installer
macOS	brew install mono-libgdiplus（仅演示文稿模板）
Docker	无需设置，镜像已包含所有依赖。

如果缺少 libgdiplus，演示文稿模板会报错：“The type initializer for 'Gdip' threw an exception”；服务会在消息中说明如何修复。

限制

• 模板属于可信输入。 模板的图像和文档标签会从服务器进程可访问的任意位置加载表达式返回的文件路径或 URL。表达式无法调用数据之外的 .NET API（无法访问文件或环境），但请确保服务进程只能访问应该看到的文件夹——仅挂载一个文件夹的 Docker 镜像正是如此。
• {{name}} 占位符不是 GroupDocs.Assembly 语法，会保留为文本；模板应使用 <<[name]>>。get_template_fields 会将其标记出来。
• 空列表。 数据中的列表为空时不会包含任何字段，因此读取该列表的模板会失败，除非设置 allowMissingMembers=true。
• 二进制模板（DOC、XLS、PPT、MSG）可以使用，但必须生成后才能列出其中的标签，因此当数据是数组、XML、CSV 或表格时，请传入 dataSourceName。
• 逐记录组装会读取 JSON。 请先将 CSV 或电子表格行转换为 JSON 数组，或使用带有 <<foreach>> 的模板调用 assemble_document，生成一份列出所有行的文档。
• macOS CI。 集成测试在 Linux 和 Windows 上运行；整个系列的 macOS 运行器挂起问题另行跟踪。

使用 Docker Compose

cd docker
docker compose up

编辑 docker/docker-compose.yml，将卷指向你的文档文件夹。

文档与指南

分步部署指南和已发布程序包的集成测试套件位于配套仓库 GroupDocs.Assembly.Mcp.Tests：

• 从 NuGet 安装 — dnx、全局工具、固定版本与始终使用最新版本
• 通过 Docker 运行
• 在 MCP 注册表中验证
• 与 Claude Desktop 配合使用
• 与 VS Code / GitHub Copilot 配合使用
• 运行集成测试
• 与 Cursor 配合使用

该仓库会使用已发布的程序包（在 Linux、Windows 和 macOS 上运行 dnx）和 Docker 镜像，测试所有宣传的工具，并读取每个生成的文档。

许可证

MIT — 详见 LICENSE