adobe-indesign-mcp

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="media/hero.svg"> <img src="media/hero.svg" width="100%" alt="indesign-nutria-mcp"> </picture> </p> <p align="center"> <b>Say "Create an A4 document with 5 pages, add a red circle on page 3" — and it happens.</b><br> <i>The most comprehensive MCP server for Adobe InDesign. 197 tools. 34 handlers. Full DOM coverage.</i> </p> <p align="center"> <a href="media/demo.mp4"> <img src="media/social-preview.png" width="600" alt="Demo video" style="border-radius: 12px; border: 1px solid #312e81;"> </a> <br> _{⚡ Click for a quick demo · <a href="https://github.com/nutriandrea/adobe-indesign-mcp/releases/tag/v1.1.0">v1.1.0 release</a>} </p> <p align="center"> <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-7c3aed?style=flat" alt="license"></a> <a href="https://www.npmjs.com/package/indesign-nutria-mcp"><img src="https://img.shields.io/npm/v/indesign-nutria-mcp?style=flat" alt="npm"></a> <a href="#"><img src="https://img.shields.io/badge/tools-197-7c3aed?style=flat" alt="tools"></a> <a href="#"><img src="https://img.shields.io/badge/tests-1131-22c55e?style=flat" alt="tests"></a> <a href="https://github.com/nutriandrea/adobe-indesign-mcp/actions/workflows/ci.yml/badge.svg"><img src="https://github.com/nutriandrea/adobe-indesign-mcp/actions/workflows/ci.yml/badge.svg" alt="CI"></a> <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D18-339933?style=flat&logo=node.js" alt="node"></a> <a href="https://www.adobe.com/products/indesign.html"><img src="https://img.shields.io/badge/InDesign-2022%2B-007396?style=flat&logo=adobe" alt="indesign"></a> </p> > **Published to npm** as > [`indesign-nutria-mcp`](https://www.npmjs.com/package/indesign-nutria-mcp). > Your agent starts it with `npx -y indesign-nutria-mcp` — see > [Quick Start](#-quick-start-30-seconds). InDesign still runs on your machine: > the server reaches it over a local bridge, and nothing leaves the box. --- ## 🚀 Why This Exists **InDesign automation has been broken for 20 years.** ExtendScript is ancient. CEP panels are over-engineered. UXP scripting requires a CS degree. You just want AI to do the layout. This MCP server fixes that. Clone it, point your agent at it, and InDesign is yours to drive like a puppeteer. ### 🆚 MCP vs The Old Ways | | **MCP (this)** | **ExtendScript** | **CEP Panels** | **UXP Scripts** | **Manual** | |---|---|---|---|---|---| | **Learn in** | 30 seconds | 3 weeks | 2 months | 1 month | 0 (slow) | | **AI-native** | ✅ Any MCP agent | ❌ | ❌ | ❌ | ❌ | | **Tool count** | **197** | Unlimited (you write them) | 5-20 typical | 5-20 typical | ∞ (manual) | | **Error messages** | Human-readable | Opaque crashes | Varies | Better | N/A | | **Setup time** | 5 minutes | 10 minutes | 2 hours | 30 minutes | Instant | | **Undo support** | ✅ Built-in | ❌ | Varies | ❌ | ✅ | | **Search text** | `text_search("pattern")` | Write 50 lines | Maybe | Maybe | Ctrl+F | | **Debug mode** | ✅ Stack traces | ❌ | Varies | Limited | N/A | | **Remote control** | ✅ Anywhere STDIO works | ❌ InDesign-only | ❌ | ❌ | N/A | | **Maintenance** | Zero (we handle 197 tools) | You write+test everything | Fragile | Fragile | N/A | --- ## ✨ What It Can Do ### 📝 Text & Typography (27 tools) Create frames, set content, apply paragraph/character styles, control formatting, search with GREP, find/replace, apply fonts, set columns, insets, auto-size, vertical justification, drop caps, keep options, hyphenation, tabs, paragraph rules, text wrap, baseline, linking/unlinking. ### 🎨 Shapes & Objects (20 tools) Rectangles, ellipses, polygons, lines, groups, anchored objects — create, modify, delete, list, arrange. ### 🖼️ Images (5 tools) Place from disk, query metadata, fit/proportional, adjust brightness/contrast, relink. ### 🎭 Colors & Swatches (6 tools) CMYK/RGB/LAB/spot swatches, ink list, gradients, apply to fill/stroke. ### 📄 Pages & Documents (15 tools) Create, open, save, close, getInfo, listOpen — plus page add/delete/duplicate/move/getInfo/listAll/applyMaster, sections. ### 📊 Tables (20 tools) Create, set cells, add/delete rows/columns, merge/split, alignment, fills, strokes, insets, header/footer, row/column sizing, table styles, cell styles. ### 🧬 Styles (10 tools) Paragraph, character, object styles — create, list, duplicate, delete, apply. ### 🏗️ Masters & Books (10 tools) Master spreads — create, duplicate, apply, delete, list, getPages. Books — list, open, getDocuments, synchronize. ### 📤 Export (9 tools) PDF, EPUB, HTML, JPG, PNG, package — plus preflight, font/swatch/table lists, and `script_run()` for custom ExtendScript. ### 🔍 Find & Replace (5 tools) GREP find/replace, format-aware find/replace. ### 🔄 Transform (5 tools) Align, distribute, rotate, scale, flip. ### 🔗 Interactive (5 tools) Hyperlinks, buttons, cross-reference anchors. ### 📚 References (10 tools) Footnotes, endnotes, cross-references, index entries/topics/generation. ### 📋 Lists (6 tools) Define, apply to paragraph/selection, remove, restart numbering. ### 🧩 XML & Data Merge (11 tools) XML tags, import/export, data merge with CSV/TSV/XML sources. ### 🔧 Other Layers, effects (drop shadow, feather, transparency), TOC, sections, undo/redo, undo groups. --- ## 🧠 Included AI Skills Ten skills ship with the repo, auto-loaded by trigger keywords when you use any AI agent: | # | Skill | What it does for you | |---|---|---| | 1 | **Aesthetic Preference** | Asks 8 questions before any creative work — font, palette, style, margins. Builds a persistent JSON profile. | | 2 | **Layout Readability** | Validates overlays, contrast, orphans/widows, hierarchy, spacing, overflow before delivery. | | 3 | **Export & Verify** | Mandatory modify → export JPG → analyze pixels → fix → repeat cycle. | | 4 | **Import Word** | Imports `.docx`, maps Word styles to InDesign paragraph styles. | | 5 | **Batch Operations** | Applies the same modification across N pages. | | 6 | **Image Optimize** | Place, resize, DPI check, relink. Profiles for print (300dpi CMYK) vs web (72dpi RGB). | | 7 | **Table Format** | Creates and styles tables — columns, rows, borders, fills, merge cells. | | 8 | **Template Manager** | Save/load reusable page templates. | | 9 | **Export Batch** | Export same document to multiple formats at once with different profiles. | | 10 | **Style Extractor** | Scans `.indd` files, extracts full style profile (fonts, colors, styles, masters, margins) as JSON, replicates on new layout. | --- ## 🏗️ Architecture ``` ┌─────────────────────┐ STDIO ┌──────────────────────┐ WebSocket ┌──────────────────┐ │ Any AI Agent │ ◄────────────────► │ indesign-nutria-mcp │ ◄───────────────► │ Adobe InDesign │ │ (Claude, OpenCode, │ │ (Node.js MCP Server) │ port 8120 │ + UXP Plugin │ │ Cursor, etc.) │ │ 34 handlers │ │ + ExtendScript │ └─────────────────────┘ │ 197 tools │ └──────────────────┘ │ 10 AI skills │ └──────────────────────┘ ``` ### Two ways to reach InDesign The MCP protocol always speaks stdio. Only the last hop differs, and you pick one per platform: | | macOS | Windows | |---|---|---| | **With plugin** | UXP panel in `plugin/` | UXP panel in `plugin/` | | **Without plugin** | `node bridge-proxy.mjs` (JXA/osascript) | `COM_BRIDGE_ENABLED=true` (in-process COM) | Both are supported. The plugin is the richer path (it also emits change events); the proxy exists for setups where you cannot or do not want to load a UXP panel. See [WINDOWS.md](WINDOWS.md) for the Windows bridge and `start-bridge.sh` for the macOS one. > **Full breakdown:** the four macOS processes, the request lifecycle, the error > contract and the trust boundaries are in > [docs/architecture.md](docs/architecture.md). ### Full Handler Catalog | Handler | Tools | Key Features | |---------|-------|-------------| | **AnchoredObject** | 5 | create, getSettings, release, setPosition, setProperties | | **Book** | 4 | list, open, getDocuments, synchronize | | **Changes** | 1 | getStatus — what changed since T?, without touching InDesign | | **Color** | 6 | swatch CRUD, inks, gradients, apply | | **DataMerge** | 5 | selectDataSource, listFields, mergeRecords, export, removeDataSource | | **Document** | 9 | create/open/save/close, getInfo, listOpen, **getState**, **getPageStories, getStoryPages** | | **Effect** | 4 | drop shadow, feather, transparency, gradient feather | | **Export** | **10** | multi-format export, batch folder, preflight, fonts/swatches/tables/masters/XML, **executeScript, script_run** | | **Font** | 5 | list, find, change, missing check, glyph insert | | **Grep** | 4 | find, replace, findFormat, replaceFormat | | **Image** | 5 | place, info, adjust, fit, relink | | **Index** | 4 | addEntry, createTopic, generate, listTopics | | **Interactive** | 5 | hyperlinks, buttons, anchors | | **Layer** | 5 | create, delete, list, reorder, setProperties | | **List** | 6 | define, apply, remove, restart numbering | | **Master** | 6 | create, duplicate, apply, delete, list, getPages | | **Note** | 4 | footnotes, endnotes | | **Object** | 6 | shapes, groups, image links | | **Page** | 7 | add, delete, duplicate, move, getInfo, listAll, applyMaster | | **Preview** | 1 | document — render a page as an image the agent can see | | **Recipe** | 2 | flow a placed text story across pages, export with a named PDF preset — each in one undo group | | **Resources** | 6 | list/update/embed/unembed links, getLinkInfo | | **Section** | 4 | create, list, setNumbering, delete | | **Shape** | 6 | rectangle/ellipse/line/polygon create, delete, modify | | **Style** | 7 | paragraph/character/object styles CRUD | | **Table** | 16 | create, cells, rows/columns, merge/split, alignment, fills, strokes, header/footer | | **TableStyle** | 4 | tableStyle, cellStyle CRUD | | **Text** | 7 | frames, content, stories, findReplace, **BOM filtering, timeout** | | **TextAdvanced** | **20** | columns, wrap, links, drop caps, rules, tabs, **formatting read/write, search** | | **Toc** | 4 | createStyle, generate, update, listStyles | | **Transform** | 5 | align, distribute, rotate, scale, flip | | **Undo** | **5** | undo, redo, history, **beginGroup, endGroup** | | **Xml** | 6 | tags CRUD, tag/untag items, import/export | | **Xref** | 3 | create, list, updateFormat | | | **197** | 34 handlers, no duplicates | `tests/contract/toolInventory.test.ts` pins this number, so the table cannot drift from the code without failing CI. Verified end-to-end against InDesign 2026 (21.3) on the plugin-free macOS path: MCP stdio → WebSocket bridge → JXA proxy → InDesign, creating a document, adding a text frame, reading it back, and closing. > **Closing documents from an agent?** `document_close` defaults to > `saveOptions: "no"` — the only value that cannot raise a modal dialog. `"ask"` > opens a save prompt, and `"yes"` opens a **Save As** dialog for a document that > was never saved; both block the script until the bridge times out. Save first > with `document_save { filePath }`, then close. ### MCP Resources | URI | What it gives you | |---|---| | `mcp://session/status` | Active document session state | | `mcp://bridge/status` | WebSocket bridge health + queue depth | | `mcp://tools/inventory` | Full 197-tool catalog for agent self-discovery | | `mcp://document/active` | Currently active document info | --- ## 🎯 Use Cases ### 🏢 Agency Production > "Create a 200-page catalog from this CSV. Product name in 14pt Arial Bold, price in 12pt Arial Regular, description in 10pt. Add a red 'SALE' badge on page 1, 50, 100, 150. Export as PDF." ### 📚 Book Publishing > "Import this Word document. Map Heading 1 to 'Chapter Title' style, Normal to 'Body Text'. Add running headers with page numbers. Generate a TOC. Export to PDF with crop marks." ### 🎨 Creative Automation > "Take this InDesign template and generate 50 variations with different colors and text from this spreadsheet. Export each as a separate PDF." ### 🏭 Print Production > "Check all 200 files for missing fonts and broken links. Fix them. Export as PDF/X-1a." ### 🔄 Continuous Publishing > "Every morning at 8am, update the daily newspaper template with fresh content from our CMS, preflight, and upload to the web server." --- ## ⚡ Quick Start (30 seconds) Two halves: the **server** your agent runs — one line from npm, no clone and no build — and the **bridge** that reaches InDesign on this machine. ### 1️⃣ Connect InDesign The server listens on `127.0.0.1:8120`; something still has to drive InDesign. Pick by platform: **macOS — with the UXP panel** (also emits change events) 1. Open **UXP Developer Tool** 2. Load the `plugin/` directory — it ships in this repository, so clone it once: `git clone https://github.com/nutriandrea/adobe-indesign-mcp` (no build step) 3. Open the **MCP Bridge** panel — it connects on its own **macOS — without the panel** ```bash git clone https://github.com/nutriandrea/adobe-indesign-mcp cd adobe-indesign-mcp npm install # gives the proxy its `ws` dependency; nothing to build ./start-bridge.sh # launches InDesign, then the JXA proxy ``` **Windows — no bridge process.** The COM bridge drives InDesign in-process, so Windows needs neither the clone nor a second process; it is enabled by the env var in the config you use in step 2 (see [`examples/claude-desktop.windows.json`](examples/claude-desktop.windows.json)). See [WINDOWS.md](WINDOWS.md) for the details and caveats. ### 2️⃣ Connect your AI agent Both hosts start the same published package — nothing to clone, nothing to build. **Claude Desktop:** ```json { "mcpServers": { "indesign": { "command": "npx", "args": ["-y", "indesign-nutria-mcp"] } } } ``` **OpenCode** (project `opencode.json`, or the same block in `~/.config/opencode/opencode.json`): ```json { "mcp": { "servers": { "indesign": { "type": "local", "command": ["npx", "-y", "indesign-nutria-mcp"] } } } } ``` On OpenCode the servers live under `mcp.servers`, not `mcpServers`, and the command is an array — that is [the documented V2 shape](https://opencode.ai/v2/docs/mcp-servers). Ready-made files for Claude Desktop, Cursor and Claude Code — including the Windows COM variant — are in [`examples/`](examples/README.md). Each one is copy-paste. ### 3️⃣ Start creating ``` 🤖 "Create a landscape A3 document with 3 pages." 🤖 "Add a blue rectangle covering the top half of page 1." 🤖 "In the rectangle, add text 'Hello World' in white, Arial Bold 72pt." 🤖 "Export page 1 as JPG." ``` ### 📝 Notes for MCP client developers Building a custom client (script, harness, test runner) against this server? Two lessons from real-world integration: | Pitfall | Fix | |---------|-----| | **Large responses arrive split across stdout chunks.** `preview_document` at 150ppi returns ~100+ KB of base64 — more than one pipe chunk. Parsing each `data` event with `JSON.parse(chunk)` silently drops the pieces and the call appears to hang forever. | Accumulate stdin into a buffer and only `JSON.parse` complete newline-delimited lines: `buf += chunk; while ((i = buf.indexOf('\n')) >= 0) { parse(buf.slice(0, i)); buf = buf.slice(i + 1); }` | | **Image tools return `image` content, not `text`.** `preview_document` responds with `{ type: 'image', mimeType: 'image/png', data: '<base64>' }` — reading `.text` yields `undefined`. | Read the base64 payload from `content[0].data` (check `content[0].type`). | Every message is a single-line JSON-RPC object terminated by `\n`; there is no framing beyond the newline. --- ## 🆕 What's New in v1.6.0 ### Fixed | ⚠️ | Read this before you script | |---|---| | **The layout skill named tools that do not exist** | `skills/indesign/indesign-mcp-layout/SKILL.md` advertised an `mcp_indesign_*` prefix the registry never used, and pointed connectivity checks at `health_check` and `list_ai_skills` — neither is registered by any handler. A skill is instruction, so naming a tool that does not resolve sends a model into a second failure on top of the one it was recovering from. | | Change | What it means for you | |--------|----------------------| | **The skill names real tools now** | It points at the bare tool names the registry actually exposes, and documents the read-only resources (`mcp://bridge/status` and friends), which never touch InDesign and cost no round-trip. | | **Skills are guarded like the instructions are** | `tests/unit/skillGuidance.test.ts` walks every `SKILL.md` under `skills/` and `marketplace/` and fails on a tool name the registry does not know — and on a skill whose frontmatter `name` disagrees with its folder. Regression-proven against the bug above. | | **Marketplace counts are checked too** | `verify:tool-counts` now reads the markdown under `marketplace/`, so the number quoted to a buyer is checked alongside the README, `llms.txt` and the package description. | ### Added | Change | What it means for you | |--------|----------------------| | **Client configs** | `examples/` holds copy-paste configs for Claude Desktop (macOS, and the Windows COM variant), Cursor and Claude Code, plus `examples/README.md`. | | **Registry and bundle metadata** | `server.json` — generated from `package.json` and gated by `verify:server-json` — and `mcpb/manifest.json`, so the MCP Registry and an MCP Bundle can be published from the same release. | | **Release automation** | `release.yml` takes a tag through `verify` and `verify:pack`, publishes to npm with provenance, builds the `.mcpb` and attaches it to the GitHub Release with the CHANGELOG notes. `publish-mcp-registry.yml` chains off the release, so the registry never advertises a version npm does not have. `validate-release-tag.sh` refuses a tag that disagrees with `package.json` or has no CHANGELOG section. | | **A packaged companion skill** | `marketplace/agensi/` prepares the skill for a third-party marketplace, with `npm run build:agensi` asserting the archive shape the reviewer requires — one top-level folder, `SKILL.md` at its root, text files only. Like `mcpb/`, it does not ship to npm. | <details> <summary>v1.5.0</summary> ### For AI agents | ⚠️ | Read this before you script | |---|---| | **Pass `document_id` — don't trust the front tab** | Every tool takes an optional `document_id`: a document name (as `document_listOpen` reports it) or a 0-based index. With more than one document open the front tab is **not** reliably the intended target, and a call that lands on the wrong document edits the wrong file. Call `document_getState`, then pass `document_id` on everything that follows. | | Change | What it means for you | |--------|----------------------| | **`document_id` on every tool** | 197 tools, one extra optional parameter. Omit it and a tool acts on the front document — exactly the previous behaviour, so nothing you already send changes. | | **A target that is not open fails loudly** | `document_id 'Gone.indd' is not open. Open documents: A.indd, B.indd`, classified `document_not_found` and suggesting `document_listOpen`. Previously the script silently edited whichever document happened to be frontmost. | | **One shared resolver** | `app.activeDocument` was written inline in **197 places across 32 handlers**; `__resolveDocument()` is now injected with every script and every document-scoped handler resolves through it, so the target holds for the whole call — even if the front tab changes mid-script. | | **Safe by construction** | `document_id` reaches InDesign as a JSON string literal and is matched by name, so it is never executable. It is bound per call in `AsyncLocalStorage`, so a call that awaits before dispatching cannot be hijacked by a concurrent one. | ### Changed | Change | What it means for you | |--------|----------------------| | **The "pin the document" advice is now executable** | The connect-time contract used to tell the host to *ask which document was meant*. It now names `document_id` and how to pass it, and the shipped `indesign-mcp-layout` skill points at it too. | </details> <details> <summary>v1.4.3</summary> ### For AI agents | ⚠️ | Read this before you script | |---|---| | **Failures now tell you how to recover** | A failing call returns a JSON envelope `{ ok: false, code, message, suggested_next_tool?, suggested_args? }` instead of prose. Branch on `code`, and call `suggested_next_tool` when it is present rather than guessing. | | **State before action** | `document_getState` returns the front document's geometry, its index, every open document, the active layer and the selection count in one round-trip. Call it before mutating instead of assembling that state from four separate calls. | | **A recipe is one call, not a chain** | `recipe_flowTextStory` places a text file and flows it across pages; `recipe_exportPreset` applies a named PDF preset and exports. Measured live, the flow cost **1 call / 215 bytes** against **6 calls / 786 bytes** for the nearest atomic chain — which cannot place the text at all. | | Change | What it means for you | |--------|----------------------| | **Structured error envelopes** | Sixteen failure classes, each with a `suggested_next_tool` checked against the live registry (a bad frame index suggests `document_getInfo`; a timeout suggests `document_listOpen`). ExtendScript errors carry `line`, `file` and `stack`. | | **A workflow contract on connect** | The server advertises roughly 680 tokens of `instructions` — bridge bootstrap, state-before-action, the `document_close` save trap, the error-envelope shape and undo grouping. | | **`document_getState`** | One round-trip replaces the `document_getInfo` + `document_listOpen` + layer + selection sequence. | | **`preview_document` takes `documentIndex`** | Render any open document, not only the front one. Exports are capped at 4 MB and re-rendered once at a fitting resolution before failing with `output_too_large`. | | **Two new recipes** | `recipe_flowTextStory` and `recipe_exportPreset`, bringing the catalog to 197. | | **Opt-in success envelope** | `RESPONSE_ENVELOPE_SUCCESS` (or `responseEnvelope.success`) wraps successful results as `{ ok: true, ... }`, so a single key covers success and failure. **Off by default**, because it changes the response shape. | | **A smaller, correct package** | A `files` allowlist replaces the `.npmignore` denylist: **1.6 MB unpacked**, down from 4.4 MB — and the `bridge-proxy.mjs` that the macOS launcher execs is now actually shipped. | ### Changed | Change | What it means for you | |--------|----------------------| | **Error responses are JSON text** | The failure message is preserved verbatim inside the envelope; `isError: true` is unchanged. | | **`document_close` defaults `saveOptions` to `"no"`** | `"ask"` raised a modal save dialog that blocked until the bridge timed out and could leave InDesign wedged; `"no"` cannot prompt. Call `document_save` first when you want the work kept. | ### Fixed | Fix | What it means | |-----|---------------| | **Every call after `undo_beginGroup` failed** | `wrapExtendScript` set `app.scriptPreferences.undoMode`, a property InDesign does not have. Undo groups now run through `app.doScript(..., UndoModes.ENTIRE_SCRIPT)`. | | **`undo`, `redo` and `undo_history` threw on every call** | They read `document.undoable` / `document.redoable`, which are not part of the DOM. | | **The server reported itself as v1.0.0** | Four releases after v1.0.0 it advertised the old literal on `initialize`. `SERVER_VERSION` is now the single source of truth, and two gates keep it honest. | </details> <details> <summary>v1.4.2</summary> ### For AI agents | ⚠️ | Read this before you script | |---|---| | **Prefer the typed tools** | `export_executeScript` and `script_run` have **no cancellation**. A hung script leaves the bridge busy and every later call queues behind it until the host restarts. Loops, font enumeration and multi-mutation probes belong in the typed tools, which validate arguments and time out. See [skills/indesign/indesign-mcp-layout](skills/indesign/indesign-mcp-layout/SKILL.md). | | Change | What it means for you | |--------|----------------------| | **The bridge protocol is now canonical** | Responses are `{ type: 'result', id, result }` or `{ type: 'error', id, error }`. Legacy `success`/`response` types are still accepted on input, but an unknown type with a valid `id` is now an explicit error instead of a silently resolved promise. | | **Plugin-free macOS setup** | `start-bridge.sh` launches InDesign and the JXA proxy — no UXP panel to load. | | **The JXA proxy no longer blocks or corrupts** | Scripts reach `osascript` through a temp file instead of shell-quoted `-e` strings, and execution is asynchronous with a FIFO queue. A script containing a quote, backslash or newline can no longer be mangled, and the MCP server keeps answering while InDesign works. | | **Configurable InDesign version** | `INDESIGN_APP` replaces the hardcoded "Adobe InDesign 2024" process name. | | **The panel connects itself** | The MCP Bridge panel connects on open, so there is no Connect click to miss. | | **InDesign 2026 anchoring** | Creating an anchored object no longer depends on `move()`, which 2026 rejects for insertion-point targets. | | **The shipped config starts everywhere** | It declared the wrong MCP transport and would have aborted startup on macOS and Linux had it enabled the Windows COM bridge. Both are now covered by a test. | </details> <details> <summary>v1.4.0</summary> | Change | What it means for you | |--------|----------------------| | **Agent vision: `preview_document`** | Render any page as an image the agent can actually see — layout mistakes get caught in the loop, not after export. | | **Batch PDF: `export_batchFolder`** | Export every `.indd` in a folder to PDF in one call, with per-file results. | | **Windows COM bridge** | Run with zero plugins via `COM_BRIDGE_ENABLED=true`. See [WINDOWS.md](WINDOWS.md). | | **Hardened file paths** | Every file-touching tool validates paths up front — traversal attempts (`..`) and system directories are rejected before InDesign ever sees them (now 11 guarded call sites). | </details> <details> <summary>v1.3.0</summary> | Change | What it means for you | |--------|----------------------| | **InDesign 2026 ready** | Color and anchored-object tools work on 2026's renamed enums — no more silent failures after upgrading. | | **Real env var config** | Every setting in `.env.example` is now honored: `BRIDGE_PORT`, `HTTP_BRIDGE_ENABLED`, `LOG_LEVEL`, … Invalid values never block startup. | | **No more 30s hangs** | If the plugin isn't connected, tool calls fail instantly with "Bridge is not connected" instead of timing out. | | **One escaping path** | All handlers share a single battle-tested ExtendScript string escaper. | | **Hardened path validation** | File-path checks now use true containment (no prefix-collision escapes). | | **Honest status** | `getStatus().connected` reflects actual plugin connectivity, and CI enforces coverage gates. | </details> <details> <summary>What's New in v1.1.0</summary> | Feature | Tools | What it solves | |---------|-------|----------------| | **Text formatting read** | `text_getFormatting` | Get font/size/style per text range. No more custom scripts. | | **Character style apply** | `text_applyCharStyle` | Apply to a range in one call. | | **Font apply** | `text_applyFont` | Apply font family/style/size to a range. | | **Text search** | `text_search`, `text_searchFormatting` | GREP + format-aware search with paragraph-relative positions. | | **Story→Page map** | `document_getPageStories`, `document_getStoryPages` | Which stories are on which pages. | | **Undo groups** | `undo_beginGroup`, `undo_endGroup` | Group operations into one undo step. | | **Debug mode** | `script_run(code, debug=true)` | Full ExtendScript stack traces. | | **BOM filtering** | Text reads | `\ufeff` and `\u0004` filtered by default. | | **Timeout/maxResults** | `text_getStories`, etc. | Custom limits for large documents. | | **MCP resources** | `mcp://tools/inventory` | Agent auto-discovers all tools. | </details> --- ## ⚙️ Configuration All settings have defaults — zero config required. To customize, copy `.env.example` to `.env` or pass a JSON file; environment variables win over the file: ```bash BRIDGE_PORT=8120 # WebSocket port the UXP plugin connects to HTTP_BRIDGE_ENABLED=false # optional REST fallback bridge HTTP_BRIDGE_PORT=3000 SERVER_TRANSPORT=stdio # stdio | websocket LOG_LEVEL=info # debug | info | warn | error COM_BRIDGE_ENABLED=false # Windows only: drive InDesign over COM, no plugin RESPONSE_ENVELOPE_SUCCESS=false # wrap successful results as { ok: true, ... } ``` The plugin-free macOS proxy takes its own variables: ```bash INDESIGN_APP="Adobe InDesign 2026" # matches your installed version BRIDGE_WS_URL=ws://127.0.0.1:8120 BRIDGE_TIMEOUT_MS=120000 # a long export is not a hang BRIDGE_RECONNECT_DELAY_MS=3000 ``` Precedence: **environment variables > JSON config file > defaults**. Invalid values are ignored, never fatal. --- ## 🪟 Windows Two ways to run on Windows: the standard UXP plugin flow (identical to macOS) or the new opt-in **COM bridge** that needs no plugin at all. See [WINDOWS.md](WINDOWS.md). --- ## 📦 Project Structure ``` ├── src/ │ ├── server/ # MCP server (STDIO transport) │ ├── bridge/ # WebSocket bridge, ScriptExecutor, protocol, COM executor │ ├── handlers/ # 34 handler modules (197 tools) │ ├── schemas/ # Zod parameter schemas │ ├── core/ # Session tracking │ ├── types/ # TypeScript definitions │ └── utils/ # Config, logger, security, JSON polyfill ├── plugin/ # UXP panel (index.html, index.js, manifest.json) ├── examples/ # Copy-paste client configs (Claude Desktop, Cursor, Claude Code) ├── mcpb/ # MCP Bundle manifest (npm run build:mcpb packs the archive) ├── server.json # MCP Registry manifest (generated from package.json) ├── llms.txt # llms.txt index for agents and directories ├── bridge-proxy.mjs # Plugin-free macOS proxy (JXA/osascript) ├── jxa-driver.js # Runs one ExtendScript inside InDesign ├── start-bridge.sh # Launches InDesign + the proxy ├── skills/ # Agent-facing skills shipped with the server ├── marketplace/ # Store listings that package a skill for third-party channels ├── tests/ # 1131 tests (vitest) ├── .opencode/skills/ # 10 AI agent skills ├── docs/ # Documentation and fork audits ├── media/ # Social preview, hero images ├── dist/ # Compiled output └── opencode.json # MCP configuration ``` --- ## 📋 Requirements | Requirement | Version | |-------------|---------| | **Adobe InDesign** | 2022+ (2024/2025/2026 recommended) | | **Node.js** | 18+ | | **OS** | macOS or Windows (Linux can run the MCP server, but no InDesign automation path exists there) | --- ## 🧪 Development ```bash npm test # Run 1131 tests npm run test:watch # Watch mode npm run build # TypeScript compile npm run lint # ESLint ``` ### Live smoke test (macOS) ```bash npm run smoke:macos ``` `npm test` covers the handlers, the protocol and the startup sequence, but it cannot see the seams between the four separate processes on the plugin-free macOS path. That gap is not hypothetical: 965 tests once passed against a build whose bridge never listened on its port, so every tool call failed in the field and nothing went red. `smoke:macos` drives the real chain — MCP stdio → WebSocket bridge → JXA proxy → InDesign — against a running InDesign, creating a document, writing to it, reading it back, and closing it. It creates one unsaved document and cleans up after itself. It needs a desktop app, so it is not part of `npm test` and does not run on CI; it exits 0 with a SKIP notice if InDesign is not open. Run it by hand before releasing a change to the bridge, the protocol, the proxy or the driver. ```bash npm run smoke:recipes # the live gate for the two recipes ``` `smoke:recipes` does what the unit tests cannot: it flows a long text file with `recipe_flowTextStory`, checks the document grew by exactly what the tool reported, calls `undo` **once** to confirm the whole flow is a single undo step, then exercises both preset paths of `recipe_exportPreset`. Same rules as above — needs a desktop app, exits 0 with a SKIP notice when InDesign is closed. ```bash npm run smoke:target # the live gate for document_id ``` `smoke:target` opens **two** documents and proves the thing `document_id` is for: a call that names the non-front document edits *that* document and leaves the front one alone. It then checks index targeting, that omitting `document_id` still acts on the front document (the additive guarantee), that an unopened target arrives as a `document_not_found` envelope suggesting `document_listOpen`, and that a hostile `document_id` is inert rather than executed. It closes only the documents it created, never saves, and leaves every pre-existing document untouched. Same rules as above — needs a desktop app, exits 0 with a SKIP notice when InDesign is closed. --- ## 🗺️ Roadmap - [ ] **InDesign Server** — headless server support for CI/CD pipelines - [ ] **Live preview** — stream InDesign canvas to agent - [ ] **Template marketplace** — share and discover InDesign templates - [ ] **Natural language → layout** — describe a page, get a page - [ ] **Batch PDF processing** — apply changes across hundreds of files - [ ] **VSCode extension** — control InDesign from your editor --- ## 📚 Deep Dives - [Architecture](docs/architecture.md) — the four-process macOS path, request lifecycle, error contract - [Available tools](docs/available-tools.md) — every tool, generated from the registry - [Troubleshooting](docs/troubleshooting.md) — modal hangs, port conflicts, missing fonts, blocked scripts - [Development](docs/development.md) — build, test, and the live smoke test - [Origin Story](docs/origin.md) — how this project came to life - [Comparison docs](docs/comparison.md) — MCP vs CEP vs ExtendScript in depth - [Launch thread](docs/launch-thread.md) — social launch content --- ## 🤝 Contributing PRs welcome! The handler pattern is designed to be simple: 1. Create `src/handlers/YourHandler.ts` 2. Define tools with Zod schemas 3. Register in `IndesignMcpServer.ts` 4. Add tests Check [CONTRIBUTING.md](CONTRIBUTING.md) for details. --- ## 🙏 Acknowledgements This server is a merge of what four people found in the field. Each of these contributions fixed something that was genuinely broken, not a cosmetic preference. - **[@graydini](https://github.com/graydini)** — built the Windows COM bridge that this project runs on today: a persistent `cscript` process holding one live COM connection, `NEVER_INTERACT` so export dialogs can never block, and the path-containment hardening in `validateFilePath`. See [PR #1](https://github.com/nutriandrea/adobe-indesign-mcp/pull/1) and the [PR #21](https://github.com/nutriandrea/adobe-indesign-mcp/pull/21) merge. Also reported the InDesign 2026 API incompatibilities that shaped official Windows support: renamed and read-only `ColorModel` and `AnchorPoint` enums, and `move()` no longer accepting `InsertionPoint` targets. Earlier fixes from the same line of work landed on `main` as safe `basedOn`/`pointSize` reads in style listing, rich style-creation parameters, `\n` → paragraph-break normalization in text content, and an `eval`-free JSON polyfill that survives the ExtendScript sanitizer. Their branch also carried COM-specific operational knowledge — that a hung script wedges the Windows bridge with no way out, that `fontFamily`, `italic` and `weight` throw under COM, and that InDesign must be visibly running — now documented in [WINDOWS.md](WINDOWS.md) and the layout skill. A file-by-file audit of what was still unmerged is in [docs/forks/graydini-windows-com-bridge-audit.md](docs/forks/graydini-windows-com-bridge-audit.md). - **[@advaitakelkar](https://github.com/advaitakelkar)** — diagnosed why the macOS proxy returned junk, in [PR #22](https://github.com/nutriandrea/adobe-indesign-mcp/pull/22). Three real bugs in one report: `osascript` sends script *results* on **stderr**, so every successful call was read as a failure; the script was passed through shell `-e` quoting, which mangles any quote, backslash or newline; and the app name was hardcoded to "Adobe InDesign 2024", so every other version failed. The same work also moved the connection handshake out of `app.doScript`, where it was being parsed as ExtendScript. Adopted and extended — see [What's New in v1.4.2](CHANGELOG.md#142---2026-09-27). - **[@ijeetu](https://github.com/ijeetu)** — two fixes, both easy to miss and both real. The MCP Bridge panel now connects on open instead of waiting for a Connect click, so the panel no longer looks dead when the server is already running. Earlier, they traced a parse failure in the JSON polyfill to `sanitizeCode()` rewriting `eval(` into a comment and orphaning the parentheses — the shipped `wrapExtendScript` already reflects that fix. --- ## 📄 License MIT © Andrea Cacioppo --- <p align="center"> <b>Made with ❤️ for designers who code and AI agents who design.</b><br> <a href="https://github.com/nutriandrea/adobe-indesign-mcp">GitHub</a> · <a href="https://github.com/nutriandrea/adobe-indesign-mcp/issues">Issues</a> · <a href="https://github.com/nutriandrea/adobe-indesign-mcp/blob/main/CONTRIBUTING.md">Contributing</a> </p>