idmlkit

# idmlkit **The AI-native toolkit for Adobe InDesign files (IDML) — parse, summarize, and safely write back. No InDesign required.** AI tools have transformed how we write code and build web pages, but print and layout designers have largely been left out: the InDesign ecosystem has no AI-ready open interface. Existing InDesign MCP servers all remote-control a *running* InDesign instance — which means a license, a desktop, and an open app for every operation. `idmlkit` takes the other road: it works directly on `.idml` files (InDesign's open, XML-based interchange format). That means it runs anywhere Node.js runs — servers, CI pipelines, Linux, a designer's laptop — with nothing from Adobe installed. ``` JSON data in ──► idmlkit ──► perfectly laid-out IDML out ──► open in InDesign / print ``` ## Design philosophy: the AI never touches the XML LLMs are great at understanding a document and deciding *what* should change, and terrible at hand-editing 5,000 lines of layout XML without breaking it. So idmlkit splits the work: - **Deterministic code** parses the package and produces a compact, LLM-friendly summary (pages, frames, stories as indexed text runs, image links, styles) — a few hundred tokens instead of megabytes of XML. - **Write-back is surgical**: replacing a text run or relinking an image rewrites only that one element via targeted string surgery. Everything else — geometry, styles, the XML formatting itself — is preserved **byte-for-byte** (enforced by tests). The AI physically cannot corrupt your layout. Validated against real InDesign 2025 exports: on Adobe's official Flex Layout sample (14.5 MB, with a single 20 MB spread), summarize runs in under half a second and a text edit changes exactly one zip entry — every other entry verified byte-identical by CRC. ## Packages | Package | What it is | | --- | --- | | [`idmlkit`](packages/idmlkit) | Core library + CLI: open, summarize, safe text/image write-back | | [`idml-mcp`](packages/idml-mcp) | [MCP](https://modelcontextprotocol.io) server exposing those abilities to Claude and any MCP-capable agent | ## Quick start ```sh npm install npm run build node scripts/make-sample-idml.mjs # generates examples/sample.idml ``` ### CLI ```sh $ node packages/idmlkit/dist/cli.js summary examples/sample.idml Pages: 1 Spreads: 1 Story u123 (11 words, 2 runs): Spring Catalog 2026 Fresh arrivals for the new season… Image link u202: file:/images/hero.jpg Paragraph styles: $ID/NormalParagraphStyle, Headline, Body $ node packages/idmlkit/dist/cli.js set-text examples/sample.idml u123 0 "Summer Sale 2026" -o out.idml $ node packages/idmlkit/dist/cli.js relink out.idml u202 "file:/images/summer.jpg" ``` ### MCP server (Claude Code / Claude Desktop) ```json { "mcpServers": { "idml": { "command": "node", "args": ["<repo>/packages/idml-mcp/dist/server.js"] } } } ``` Then ask Claude things like *"Summarize catalog.idml and replace every 2025 date with 2026"* — it will use these tools: | Tool | Purpose | | --- | --- | | `idml_summarize` | Structured summary of pages, frames, stories, images, styles | | `idml_get_story` | One story's plain text + indexed runs with styles | | `idml_set_text` | Replace one run's text (layout untouched, byte-for-byte) | | `idml_relink_image` | Point an image link at a new file (geometry untouched) | ### Library ```ts import { IdmlDocument, summarizeDocument, setStoryRunText } from "idmlkit"; const doc = await IdmlDocument.open("catalog.idml"); console.log(summarizeDocument(doc)); // LLM-friendly JSON setStoryRunText(doc, "u123", 0, "New headline"); await doc.save("catalog-updated.idml"); ``` ## Use cases - **Database publishing**: fill a designed template with product data — thousands of catalog pages, price lists, or menus without opening InDesign once. - **Localization**: extract every text run with its styles, translate, write back safely. - **Agent workflows**: let Claude read a layout, reason about its content, and apply text/image updates as part of a larger pipeline. ## Roadmap - [x] Read IDML packages, LLM-friendly summaries - [x] Safe text run replacement and image relinking - [x] MCP server (stdio) - [ ] Page → frame mapping with geometry (which frame is where) - [ ] Template fill: apply a JSON data object to a tagged template in one call - [ ] Story-level structured diff (what changed between two IDML files) - [ ] Overflow heuristics (warn when new text likely won't fit its frame) - [ ] Real-world IDML corpus tests (CC 2018–2026 exports) ## Development ```sh npm install npm run build # tsc project references npm test # vitest — includes byte-for-byte preservation tests ``` ## License [MIT](LICENSE). Not affiliated with or endorsed by Adobe. "Adobe" and "InDesign" are trademarks of Adobe Inc., used here only to describe compatibility.