docx4j Word documents

docx4j-mcp

一个 Model Context Protocol 服务，可将 docx4j 引擎提供给 AI Agent 使用：通过 Claude Desktop、Claude Code 或任何 MCP 客户端读取、转换和填充 Word（.docx）文档。

引擎：docx4j 17.1.0（服务版本独立发布；捆绑的 docx4j 版本见 pom、服务启动日志和 MCP 说明）。

MCP 协议：2025-11-25（Java SDK 2.0.1，目前可用的最新版本）。使用 2026-07-28 规范的客户端，只要实现双时期回退机制即可正常工作：server/discover 探测会收到干净的 JSON-RPC -32601 响应，随后客户端回退到 initialize（已通过 stdio 验证）。仅支持新版且没有回退机制的客户端，在 SDK 支持 2026-07-28（里程碑 2.2）发布之前无法连接；届时本服务将迁移。

状态：第 3 阶段 — 所有工具均可通过 stdio 连接已发布的 docx4j 17.0.4 正常工作；已打包为可运行的 jar、.mcpb 捆绑包、OCI 镜像和 Claude Code 插件。计划、工具范围和分阶段安排见 CR-mcp-server.md。

构建

需要 JDK 17+。所有 docx4j 依赖（docx4j 17.1.0、ImportXHTML 17.0.4）均来自 Maven Central。

mvn package            # -> target/docx4j-mcp.jar (shaded, runnable)
mvn test               # JUnit 5 tests against the tool handlers directly

运行

java -jar target/docx4j-mcp.jar --root /path/to/documents [--root ...] [--max-inline-chars N]

也接受裸目录参数作为根目录（.mcpb 捆绑包的文件夹选择器会传入此类参数）。

Claude Desktop，一键安装

从 GitHub release 安装 docx4j-mcp.mcpb（Settings → Extensions），选择服务可访问的文件夹即可。本地构建命令为 packaging/build-mcpb.sh。PATH 中需要有 Java 17+。

Docker

docker run -i --rm -v /path/to/documents:/data ghcr.io/plutext/docx4j-mcp

（工具调用中的路径此时为 /data 下的容器路径； 可使用 packaging/docker/Dockerfile 在本地构建）。

Claude Code 插件

packaging/claude-plugin/ 捆绑了服务配置和用于模板/编写工作流的技能。设置 DOCX4J_MCP_JAR（jar 的路径），并可选设置 DOCX4J_MCP_ROOTS。

发布

打上 vX.Y.Z 标签后：.github/workflows/release.yml 会构建 jar + mcpb，将它们附加到 GitHub release，推送 ghcr.io/plutext/docx4j-mcp，并通过 GitHub OIDC 将 server.json（填入 sha）发布到官方 MCP 注册表。

Agent 传入的每个文件路径都必须解析到某个 --root 目录中（先解析符号链接）。没有默认根目录；未指定根目录时，服务会拒绝启动。日志写入 stderr；stdout 用于协议通信。内联返回文本的工具会将文本限制在 --max-inline-chars 指定的长度内（默认 200000）；超出时会写入 output_path，或截断并附上标记。

Claude Code（项目中的 .mcp.json）

{
  "mcpServers": {
    "docx4j": {
      "command": "java",
      "args": ["-jar", "/path/to/docx4j-mcp.jar", "--root", "/path/to/documents"]
    }
  }
}

Claude Desktop（claude_desktop_config.json）

{
  "mcpServers": {
    "docx4j": {
      "command": "java",
      "args": ["-jar", "/path/to/docx4j-mcp.jar", "--root", "/Users/you/Documents"]
    }
  }
}

工具

工具	功能
describe_template	说明模板需要哪些数据：骨架 XML + xpaths/条件（OpenDoPE、绑定内容控件），或 MERGEFIELD 名称和格式开关（邮件合并）。请在调用 fill_template 前调用此工具。
fill_template	填充模板并保留其格式。data 可以是 XML 字符串（OpenDoPE / 绑定控件；会处理重复项和条件）或 JSON 对象（邮件合并）。
convert_to_pdf	通过 XSL-FO / Apache FOP 将 docx 转为 PDF；将公式和 WMF/EMF 绘图渲染为矢量图；可选 update_toc；报告字体替换情况。内置度量兼容字体（Carlito、Caladea、Liberation、Tinos 等）。
markdown_to_docx	将 Markdown 转为格式规范的 docx（标题、编号、GFM 表格、脚注、任务列表、TeX 数学公式）。可选 styles_template_path。
docx_to_markdown	将 docx 转为 Markdown（保留结构）。选项：tracked_changes accept/markup、image_dir_path。
html_to_docx	通过 docx4j-ImportXHTML 将 HTML 转为 docx。接受不规范的 HTML（使用 jsoup 规范化）；h1–h6 映射到标题样式；可选 styles_template_path；mode: altchunk 会嵌入 HTML，供 Word 打开时转换。绝不会获取远程图片或样式表。
convert_to_html	将 docx 转为独立 HTML（visitor 导出器；使用 image_dir_path 指定图片路径；可选 update_toc）。
extract_text	提取纯文本，每个段落或表格占一行。

数学公式支持完整端到端处理：Markdown 中的 TeX 数学公式 （$..$）和 HTML 中的 MathML 会转换为可真实编辑的 Word 公式（OMML）；公式也会渲染到 PDF（通过 jeuclid/FOP，无需 LaTeX 工具链）和 HTML（原生 MathML，无需 JavaScript）输出中。已知限制：在 PDF 中，超长的单个行间公式会作为一个不可拆分的图形，且不会自动换行。

写入工具会接受 output_path，并且除非设置 overwrite: true，否则不会覆盖现有文件。

示例（Claude Code）

在 contracts/nda-template.docx 上调用 describe_template，然后为 Acme Pty Ltd 填写模板，并 写入 contracts/nda-acme.docx，随后将其转换为 PDF。

Agent 会获取骨架 XML（或 MERGEFIELD 名称），填写内容，然后调用 fill_template 和 convert_to_pdf；返回结果会说明写入的内容以及替换了哪些 字体。

许可证

Apache License 2.0。