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