# 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.