2.3.0: argument warnings, UXP capability probe, bridge authentication

Added

• Tool results carry a warnings list when an argument was not used as written: unknown parameters (ignored, with the closest valid name suggested) and deprecated aliases. Results without warnings are unchanged, and a warning never fails a call. Errors thrown before a call runs include the warnings too.
• tests/unit/warnings.test.js, which also checks that handlers read only advertised parameters, so "was ignored" is accurate
• UXP capability probe: indesign_status with probe: true on the UXP backend returns backend.uxpProbe, which reports whether the completion value comes back, how enums compare, native [i], constructor.name, fs path forms and Promise-returning methods. It also lists problems (tools that will misbehave) and handled differences. It is read-only and runs from the plugin (version 1.2.0).

Changed

• objectIndex is accepted only by apply_color; on other tools it is reported as an unknown parameter
• Older names that individual handlers read silently are now aliases in src/handlers/aliases.js, with deprecation warnings: folderPath -> outputPath (export_images, package_document), pageRange -> pages (export_images), applyObjectStyle -> objectStyle (place_image), transparency -> opacity (create_object_style)
• Server instructions and docs/LLM_PROMPT.md describe warnings
• UXP plugin version 1.2.0
• tests/unit/uxp.test.js also covers the token on the bridge's WebSocket port

Security

• With BRIDGE_TOKEN set, the bridge's WebSocket port requires it too. A connection must send { "type": "auth", "token": ... } as its first message; a wrong token or another message closes it (code 4001), and no message within 5 s (UXP_AUTH_TIMEOUT_MS) closes it (4002). Before, any local process could connect as the plugin, receive every script and return fake results. The Bridge Panel has a token field next to the port, stored in localStorage; the plugin and bridge must come from the same version.
• A connected plugin is no longer replaced by a new connection: other connections are closed (4009) while it is open. A connection that closes before authenticating no longer disconnects the plugin.
• The bridge compares tokens in constant time.

Status: tested statically and against a simulated UXP plugin; not yet run against a live InDesign. Previous parameter names keep working, now with deprecation warnings.

2.2.0: canonical parameter names and UXP result parity

Canonical parameter names

One parameter name and one enum vocabulary per concept, so agents stop guessing. The older names and values are still accepted as aliases (mapped in src/handlers/aliases.js before a handler runs) and generate exactly the same scripts; they are no longer advertised in the schemas.

Names

Concept	Canonical	Still accepted	Tools
Stroke weight (points)	strokeWeight	strokeWidth	create_rectangle, create_ellipse, create_polygon, create_master_rectangle (already strokeWeight: create_object_style, set_page_item_properties)
Font	fontName ("Family\tStyle", InDesign's Font.name, or a family name)	fontFamily; fontFamily + fontStyle	create_paragraph_style, create_character_style, create_master_text_frame (already fontName: create_text_frame, edit_text_frame)
Alignment	alignment with InDesign Justification names: LEFT_ALIGN, CENTER_ALIGN, RIGHT_ALIGN, LEFT_JUSTIFIED, RIGHT_JUSTIFIED, CENTER_JUSTIFIED, FULLY_JUSTIFIED	LEFT, CENTER, RIGHT, JUSTIFY (= LEFT_JUSTIFIED), any case	create_text_frame, edit_text_frame (already Justification: create_paragraph_style, create_master_text_frame)
Item index	itemIndex	objectIndex	apply_color

Changed

• create_text_frame and edit_text_frame now also accept RIGHT_JUSTIFIED, CENTER_JUSTIFIED and FULLY_JUSTIFIED
• Every index parameter is an integer with minimum: 0 (spreadIndex, referenceSpreadIndex and matchIndex were number; the page-item and group indexes had no minimum)
• Every item index description names its collection: page.allPageItems (the list_page_items / list_groups numbering) for the page-item and group tools, page.textFrames for frameIndex, page.allGraphics for get_image_info, and the chosen collection for apply_color / apply_object_style
• Server instructions and docs/LLM_PROMPT.md describe the canonical names and index spaces

Added

• tests/unit/aliases.test.js: each alias generates the same script as its canonical name
• Definition tests: index parameters are bounded integers, aliases are not advertised, alignment enums are the Justification names

UXP backend returns tool results

Under INDESIGN_BACKEND=uxp, most tools returned an empty result: the plugin only passed back an explicit return, while the handler scripts end with a bare expression, and the scripts used ExtendScript globals that UXP does not have. The plugin now runs them with ExtendScript semantics. This is tested against a fake InDesign DOM only; the backend stays experimental until it has been run against InDesign.

Changed

• The UXP plugin (uxp/plugin/runtime.js, plugin version 1.1.0) evaluates each script with eval and returns its completion value, as do script / DoScript do. Code with a top-level return or await still runs as an async function body.
• Enums and classes a script names come from require('indesign'); File, Folder and $ are shims. File.exists and Folder.create() use UXP's fs module, so the plugin manifest now requests localFileSystem: fullAccess.
• app is wrapped so collection[i] falls back to item(i) and constructor.name to constructorName (UXP DOM differences documented by Adobe); File shims reach DOM methods as path strings.
• UXP string results are trimmed, as the AppleScript/COM paths trim stdout.
• The plugin's WebSocket port is set in the Bridge Panel (default 3001, remembered), so UXP_WS_PORT on the bridge no longer breaks the connection. The bridge prints the port to enter when it is not 3001.
• auto re-checks the bridge every 5 s instead of once per process, and falls back to ExtendScript for a call only when the bridge is unreachable or the plugin is not connected (the script cannot have run).
• With BRIDGE_TOKEN set, the bridge requires it on /status as well as /execute.
• A UXP bridge timeout is reported as a timeout, not as "bridge not reachable".

Added

• tests/unit/uxp.test.js (npm run test:uxp, part of npm test): the real bridge with a fake plugin running runtime.js in a Node vm against a UXP-shaped fake DOM. Every handler script must return over UXP what it returns when evaluated ExtendScript-style. It also covers the token, auto re-check and fallback, and the shims.
• tests/audit/collectScripts.js: the script capture shared by the audit and the UXP test.

Known gaps

• Enum comparisons with == may fail if UXP enum values are objects (six handler scripts compare enums). Whether every DOM method that takes a file accepts a path string is unverified. Details in uxp/README.md.

Status: tested statically and against a simulated UXP plugin; not yet run against a live InDesign. Previous parameter names keep working.

2.1.0: ready for agents (instructions, annotations, tool reference)

Ready for public and agent use: agents get instructions, tool annotations and a full reference; docs are rewritten against the code.

Added

• Server instructions sent at initialize (units, indexes, colors, fonts, paths, errors, destructive tools)
• MCP tool annotations and a title on all 137 tools (readOnlyHint, destructiveHint, idempotentHint, openWorldHint), defined in src/types/annotations.js
• docs/TOOLS.md: generated reference for every tool and parameter (npm run docs:tools; npm test fails when it is stale)
• Tests: tool definition quality (descriptions, types, titles, annotations) and path confinement for all 30 file/folder parameters
• SECURITY.md, issue and pull request templates

Changed

• print_book no longer opens the print dialog by default (it blocked unattended calls)
• open_document suppresses InDesign alerts while opening, so missing fonts or links cannot block the call
• create_text_frame and place_image no longer advertise fixed x/y/size defaults; omitted values are placed automatically, as the server does
• npm run check syntax-checks every JavaScript file (it skipped most handlers)
• Descriptions for 10 terse tools and 16 undocumented parameters
• Docs rewritten against the code: setup and troubleshooting (docs/MCP_INSTRUCTIONS.md), agent guide (docs/LLM_PROMPT.md), architecture, examples, contributor guides. The UXP backend is documented as experimental.

Status: not yet published to npm or the MCP Registry, and not yet run against a live InDesign. Until the first npm release, install from a clone (see the README). Every script is checked statically against Adobe's InDesign 2023 scripting DOM in CI.

2.0.0: all 137 tools implemented and checked against the InDesign DOM

Every advertised tool is now implemented and checked against the InDesign 2023 scripting DOM.

An audit of 1.4.0 found that 17 of its 136 advertised tools were never implemented, about 40 generated scripts used properties, methods or enums that do not exist in InDesign, and failed calls were reported as successes. 2.0.0 fixes all of it and adds an audit to CI so it cannot drift again.

Verification status: every script is checked statically: it parses as ExtendScript-compatible ES5, and every property, method, enum and global it uses exists in Adobe's InDesign 2023 DOM. The scripts have not yet been run against a live InDesign in this release, and it is not yet published to npm.

Added

• 17 tools that were listed but returned "not implemented": the 11 spread tools (list_spreads, get_spread_info, duplicate_spread, move_spread, delete_spread, set_spread_properties, create_spread_guides, place_file_on_spread, place_xml_on_spread, select_spread, get_spread_content_summary), create_layer, set_active_layer, list_layers, export_epub, detach_master_items, remove_master_override
• apply_character_style is now advertised (it was implemented but missing from tools/list)
• Script audit (npm run test:audit, part of npm test and CI): every advertised tool must dispatch, generate valid ES5, and use only names that exist in the InDesign 2023 DOM
• Optional pageIndex on text, shape, image and page-item tools (defaults to the active page)
• "#RRGGBB" colors create an RGB swatch where a color is accepted
• dryRun for cleanup_document; GREP search (useRegex) for find_text_in_document; oversetOnly for get_document_stories

Fixed

• Failed calls reported success: "No document open", "Error …" and "… not found" results now return success: false and MCP isError: true
• Nonexistent InDesign APIs replaced with real ones, including grid, guide, text and layout preferences, slug offsets, FitOptions in place_image, polygon creation, rounded corners, table header rows, resize() constraints, layout snapshots, page adjustLayout, section numbering style, XML export, zoom, data merge and preflight
• validate_document and cleanup_document used JSON, which InDesign's ExtendScript does not have
• Enum and color arguments were spliced into scripts as bare identifiers (BLUE, Black), which threw at runtime
• place_file_on_page passed arguments to place() in the wrong order; export_images and package_document read an argument the schema never defined; master spread tools read masterIndex while their schemas said name
• cleanup_document only counted items; it now removes them. organize_document_layers deleted a layer before reading its name and never implemented merge or sort
• Case-sensitive and whole-word options in find tools were set on the wrong object and ignored
• create_document ignored pages; sizes and margins are now applied in millimeters regardless of the document's ruler units
• view_document read properties that do not exist; indesign_status deleted temp scripts that running calls were still using
• help documented about 30 tools (one of them nonexistent); it is now generated from the tool definitions and covers all 137
• Shape tools accept omitted position and size again, as documented (automatic placement)
• Every argument that reaches a script goes through the validated jsxSafe helpers

Changed (breaking)

• set_document_preferences takes grouped settings (general, margins, guides, text, grid) instead of preferenceType + preferences
• Grid and layout preference parameters use InDesign's own property names
• adjust_page_layout takes numbers plus units; resize_page requires width and height
• create_object_style: transparency is now opacity (the old name is still accepted)
• export_images supports JPEG and PNG (InDesign has no TIFF or GIF export); export_pdf drops the DIGITAL option
• Removed parameters that no InDesign API could honor (for example spreadHidden, includeImages on EPUB, several data_merge options)
• create_color_swatch stores RGB by default; colorSpace: "CMYK" keeps the previous conversion

1.4.0: install with npx, MCP Registry, SDK 1.32

Superseded by 2.0.0. An audit after this release found that 17 of its 136 advertised tools were not implemented, about 40 used InDesign APIs that do not exist, and failed calls were reported as successes. Use 2.0.0. This version was never published to npm.

Run it from any MCP client without cloning:

{ "mcpServers": { "indesign": { "command": "npx", "args": ["-y", "indesign-mcp-server"] } } }

Claude Code: claude mcp add indesign -- npx -y indesign-mcp-server

Added

• Published to npm: npx -y indesign-mcp-server starts the server, no clone needed
• indesign-mcp-uxp-bridge command for the optional UXP backend
• server.json and mcpName for the official MCP Registry (io.github.zachshallbetter/indesign-mcp-server)
• MCP protocol test over stdio (handshake, all 136 tools, input schemas); runs in npm test and CI without InDesign

Changed

• @modelcontextprotocol/sdk upgraded from 0.5 to 1.32
• Server name and version over MCP come from package.json
• README and UXP docs use npx

Fixed

• The UXP bridge from 1.3.0 crashed on start (CommonJS require in an ES module package, plus a missing uuid dependency). It now starts and serves /status and /execute.

Releases 1.2.0 and 1.3.0 were not tagged on GitHub; their notes are in docs/CHANGELOG.md.

InDesign MCP Server v1.0.0 Release Information

Release Details

• Version: 1.0.0
• Tag: v1.0.0
• Release Type: Initial Release
• Date: July 27, 2025

Core Features

• 135+ Professional Tools for InDesign automation
• 13 Modular Handlers covering all major InDesign operations
• Complete Session Management with smart positioning and bounds checking
• Real-time Progress Tracking for test execution
• Comprehensive Error Handling with non-blocking operations

Technical Specifications

• Language: Node.js with ExtendScript integration
• Protocol: Model Context Protocol (MCP)
• Platform: macOS with Adobe InDesign 2025
• Architecture: Modular handler-based system
• Testing: 62 test files with 100% coverage

Handler Categories

1. Document Handlers - Document creation, management, and navigation
2. Page Handlers - Page operations, backgrounds, and layout
3. Text Handlers - Text frames, formatting, and typography
4. Graphics Handlers - Shapes, images, and visual elements
5. Style Handlers - Color swatches, paragraph styles, character styles
6. Book Handlers - Book management and multi-document workflows
7. Page Item Handlers - Object manipulation and transformation
8. Group Handlers - Grouping and ungrouping operations
9. Master Spread Handlers - Master page management
10. Export Handlers - Document export and publishing
11. Utility Handlers - Code execution and session utilities
12. Help Handlers - Dynamic documentation and assistance

Key Capabilities

• Smart Content Positioning - Automatic bounds checking and optimal placement
• Color Management - RGB to CMYK conversion and swatch creation
• Typography Control - Font management, sizing, and style application
• Layout Automation - Page backgrounds, object positioning, and grouping
• Image Handling - Placement, scaling, and fitting options
• Style System - Paragraph, character, and object style management
• Export Workflows - PDF, EPUB, and print-ready output
• Session Persistence - State management across operations

Documentation

• README.md - Comprehensive setup and usage guide
• docs/MCP_INSTRUCTIONS.md - Detailed MCP integration instructions
• docs/LLM_PROMPT.md - AI assistant integration prompt
• docs/CHANGELOG.md - Version history and changes
• docs/CONTRIBUTING.md - Development guidelines
• docs/RELEASE_SUMMARY.md - Technical release overview

Installation

npm install indesign-mcp-server

Quick Start

# Start the server
node index.js

# Run tests
npm test

Use Cases

• Document Automation - Batch document creation and formatting
• Design System Implementation - Consistent styling across documents
• Content Publishing - Automated layout and export workflows
• AI-Powered Design - Natural language document creation
• Workflow Integration - MCP-based automation pipelines

System Requirements

• macOS (required for AppleScript integration)
• Adobe InDesign 2025 (or compatible version)
• Node.js 18+
• Git (for installation and updates)

Support

• Issues: GitHub Issues
• Documentation: Comprehensive docs in repository
• Testing: Full test suite for validation
• Examples: Multiple test files demonstrating capabilities

This release represents a complete, production-ready InDesign automation platform with comprehensive tooling for professional document workflows.