{
  "markdown": "# docx4j-mcp\n\nA [Model Context Protocol](https://modelcontextprotocol.io/) server that exposes\n[docx4j](https://www.docx4java.org/)'s engine to AI agents: read, convert and fill\nWord (.docx) documents from Claude Desktop, Claude Code, or any MCP client.\n\n**Engine: docx4j 17.0.4** (the server versions independently; the bundled docx4j\nversion is in the pom, the server's startup log, and its MCP instructions).\n\n**Status: phase 3** — all tools work over stdio against released docx4j 17.0.4;\npackaged as a runnable jar, an `.mcpb` bundle, an OCI image and a Claude Code\nplugin.  The plan, tool surface and phasing are in [CR-mcp-server.md](CR-mcp-server.md).\n\n## Build\n\nRequires JDK 17+.  All docx4j dependencies (17.0.4) come from Maven Central.\n\n```bash\nmvn package            # -> target/docx4j-mcp.jar (shaded, runnable)\nmvn test               # JUnit 5 tests against the tool handlers directly\n```\n\n## Run\n\n```bash\njava -jar target/docx4j-mcp.jar --root /path/to/documents [--root ...] [--max-inline-chars N]\n```\n\nBare directory arguments are also accepted as roots (this is what the `.mcpb`\nbundle's folder picker passes).\n\n### Claude Desktop, one click\n\nInstall `docx4j-mcp.mcpb` from the GitHub release (Settings → Extensions), pick\nthe folders the server may touch, done.  Built locally with\n`packaging/build-mcpb.sh`.  Requires Java 17+ on your PATH.\n\n### Docker\n\n```bash\ndocker run -i --rm -v /path/to/documents:/data ghcr.io/plutext/docx4j-mcp\n```\n\n(paths in tool calls are then container paths under `/data`;\n`packaging/docker/Dockerfile` to build locally).\n\n### Claude Code plugin\n\n`packaging/claude-plugin/` bundles the server config and a skill for the\ntemplate/authoring workflows.  Set `DOCX4J_MCP_JAR` (path to the jar) and\noptionally `DOCX4J_MCP_ROOTS`.\n\n## Releasing\n\nTag `vX.Y.Z`: `.github/workflows/release.yml` builds jar + mcpb, attaches them\nto the GitHub release, pushes `ghcr.io/plutext/docx4j-mcp`, and publishes\n`server.json` (sha filled in) to the official MCP registry via GitHub OIDC.\n\nEvery file path an agent passes must resolve inside one of the `--root`\ndirectories (symlinks are resolved first).  There is no default root; the server\nrefuses to start without one.  Logging goes to stderr; stdout is the protocol.\nTools that return text inline cap it at `--max-inline-chars` (default 200000) and\notherwise write to `output_path` or truncate with a marker.\n\n### Claude Code (`.mcp.json` in your project)\n\n```json\n{\n  \"mcpServers\": {\n    \"docx4j\": {\n      \"command\": \"java\",\n      \"args\": [\"-jar\", \"/path/to/docx4j-mcp.jar\", \"--root\", \"/path/to/documents\"]\n    }\n  }\n}\n```\n\n### Claude Desktop (`claude_desktop_config.json`)\n\n```json\n{\n  \"mcpServers\": {\n    \"docx4j\": {\n      \"command\": \"java\",\n      \"args\": [\"-jar\", \"/path/to/docx4j-mcp.jar\", \"--root\", \"/Users/you/Documents\"]\n    }\n  }\n}\n```\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `describe_template` | What data a template wants: skeleton XML + xpaths/conditions (OpenDoPE, bound content controls) or MERGEFIELD names and format switches (mail merge). Call before `fill_template`. |\n| `fill_template` | Fill a template, preserving its formatting. `data` is an XML string (OpenDoPE / bound controls; repeats and conditions processed) or a JSON object (mail merge). |\n| `convert_to_pdf` | docx → PDF via XSL-FO / Apache FOP; reports font substitutions. Bundles metric-compatible fonts (Carlito, Caladea, Liberation, Tinos…). |\n| `markdown_to_docx` | Markdown → properly styled docx (headings, numbering, GFM tables, footnotes, task lists, TeX math). Optional `styles_template_path`. |\n| `docx_to_markdown` | docx → Markdown (structure preserved). Options: `tracked_changes` accept/markup, `image_dir_path`. |\n| `html_to_docx` | HTML → docx via docx4j-ImportXHTML. Loose HTML accepted (normalised with jsoup); `h1`–`h6` map to heading styles; optional `styles_template_path`; `mode: altchunk` embeds the HTML for Word to convert on open. Remote images/stylesheets are never fetched. |\n| `convert_to_html` | docx → standalone HTML (visitor exporter; `image_dir_path` for images). |\n| `extract_text` | Plain text, one line per paragraph/table. |\n\n**Mathematics** is supported end to end (docx4j 17.0.4): TeX math in Markdown\n(`$..$`) and MathML in HTML become real, editable Word equations (OMML), and\nequations render in PDF (via jeuclid/FOP, no LaTeX toolchain) and HTML (native\nMathML, no JavaScript) output.  Known limitation: a very long single display\nequation is one atomic graphic in PDF and does not line-wrap.\n\nWriters take `output_path` and refuse to overwrite unless `overwrite: true`.\n\n## Example (Claude Code)\n\n> Use describe_template on contracts/nda-template.docx, then fill it for Acme Pty Ltd and\n> write contracts/nda-acme.docx, then convert that to PDF.\n\nThe agent gets the skeleton XML (or MERGEFIELD names), fills it, and calls\n`fill_template` and `convert_to_pdf`; the results tell it what was written and which\nfonts were substituted.\n\n## Licence\n\nApache License 2.0.\n",
  "bytes": 4984,
  "sha": "ab95dc5c78ef2361460405128ed77a778dd932dec4fb6739973d68471fd726d7",
  "repo_slug": "plutext/docx4j-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_plutext_docx4j_mcp_95b5755e/readme"
}