Nexus InDesign

A bridge between Codex or Claude Code and Adobe InDesign. It combines a silent UXP channel, an authenticated UXP plugin and controlled layout workflows, with no public HTTP and no Computer Use during normal InDesign work.

Architecture: skill, plugin and MCP

Skill InDesign Studio ── guides Codex: inspect, protect, create, critique
          │
Plugin Codex Nexus InDesign ── ships the skill + the MCP configuration
          │
Signed Codex ── MCP STDIO ── Node server ── shared queue ─┬─ local COM ── silent UXP
                                                          └─ WebSocket HMAC ── extension UXP

The Node server listens on loopback only for the plugin; the plugin is the WebSocket client. The two channels start independently.

• two tool profiles, chosen with INDESIGN_MCP_TOOL_PROFILE:

  • core (default, 41 tools): silent channel, run_layout_script, saved UXP code (execute_uxp_silent, execute_uxp), layout workflows (preview, preflight, finalize), save, exports and restore;

  • full (172 tools): adds the historical one-object commands (legacy-uxp 112, legacy-local 3, remaining direct ones), for compatibility only;

• a hidden tool is not listed and its call is refused as unknown;

• synchronous or asynchronous UXP JavaScript awaited until a private result;

• syntax of the generated UXP script checked before anything is sent to InDesign;

• mutual HMAC authentication, double nonce, anti-replay and file:// origin;

• FIFO queue, Windows mutex and persistent cross-process mutation lock;

• revision and stateToken required for direct mutations, workflows and targeted legacy commands, then re-read in InDesign immediately before and immediately after the action;

• INDD backups created by the silent channel or the plugin, tied to the document, its revision and its fingerprint in a persistent private provenance record, then verified by size, signature and SHA-256 before restoration;

• recovery for 24 hours of unknown silent and plugin outcomes, including after a full MCP restart;

• idempotent server shutdown when STDIO closes or when the identity of its parent is lost; a fresh, empty COM host is closed, while an existing InDesign instance or one holding documents is preserved and made visible;

• structural verification of PDF, PNG, IDML, INDD and packages;

• overwriting refused by default, with a prior private copy if allowed;

• no code, content, free-form argument, business path or secret in the logs.

Related MCP server: InDesign UXP MCP Server

Fast path: run_layout_script

One tracked InDesign pass checks revision and stateToken, backs up every open document (restorable with silent_restore_backup), runs the UXP script, saves (save), renders a verified PNG preview and optionally closes (close, only with save). It returns the new revision and state token, so calls chain without re-inspection. A failing script is a known outcome (scriptOk: false, error, preview, backupId) and does not lock the queue.

Latest measurement on InDesign 21.6 for the same A4 page (16 October 2026): 2 calls and 9.3 s, against 10 calls and 56.7 s for the former script path and 20 calls and 140 s for one-object commands (see CHANGELOG.md).

Layout workflows

• analyze_layout: geometry, resources, styles, design system, lint and a stable SHA-256 fingerprint;

• compare_layout_snapshot: round-trip check with a verdict, fingerprints, statistics and bounded anomalies, without copying the whole booklet;

• create_working_copy: INDD copy opened without modifying the source;

• preview_layout: verified multi-page PNGs and source re-read after export;

• finalize_layout: PDF export only if the contract and the Adobe preflight contain no blocking errors.

indesign_doctor checks locally the runtime, the caller policy, the private storage, the channels and the catalog fingerprint without starting InDesign. search_official_dom searches offline 1,078 references from the official Adobe DOM, pinned by revision and SHA-256.

Prerequisites

• Windows 11;

• Adobe InDesign 19.0 minimum, validated on InDesign 2026 21.6.0.57 (October 2026);

• Node.js 24;

• signed Codex Desktop or Codex CLI;

• GitHub CLI, authenticated (it downloads the release asset);

• OneDrive with Documents\NexusSecure;

• Adobe Creative Cloud Desktop, which provides the UPIA installer.

Full installation on a new workstation

Clone the repository pironjulien/NexusInDesign (on Nexus workstations it lives in %OneDrive%\Documents\NexusHarness\NexusInDesign), then run a single command from its root:

Set-Location "$env:OneDrive\Documents\NexusHarness\NexusInDesign"
pwsh -NoProfile -File .\scripts\Install-Workstation.ps1

The installer fetches the official CCX from the GitHub release of the current version. It then checks, in turn, the size and SHA-256 anchored in release\v3.2.2.json, the eight internal files and their logical fingerprint against the Git sources. It therefore rejects a package that is tampered with, incomplete or from another version.

It then runs install.ps1, which copies the runtime and installs the locked dependencies in ~\.nexus\indesign-mcp-secure, outside OneDrive, then the Adobe plugin with UPIA and the Codex plugin with its machine-specific configuration. The private OneDrive storage is created with a DACL restricted to the current user and SYSTEM. An Adobe installation that is already strictly identical is not repeated. The full test suite and the npm audit complete the process.

To check only the release without installing anything:

pwsh -NoProfile -File .\scripts\Install-Workstation.ps1 -VerifyOnly

The first pairing deliberately stays local: after installation, restart InDesign and open a new Codex task. Codex then opens a time-limited pairing window and the InDesign panel receives the temporary code. The persistent secret is never copied by hand or published to Git.

Synchronization and activation in Codex

The source tracked by Git lives in codex-plugin. The personal plugin Nexus InDesign bundles the studio skill and the MCP server configuration, following the separation recommended by the Codex documentation: the skill describes the reusable work, the plugin distributes it and the MCP provides the actual actions.

The skill contains progressive recipes for a magazine, a premium brochure, a report, a full cover and a catalog. They define a visual direction, sample pages and critique criteria before rolling out a layout across the whole document.

Synchronize this source to the personal plugin with:

Set-Location "$env:OneDrive\Documents\NexusHarness\NexusInDesign"
.\install.ps1
.\scripts\Sync-CodexPlugin.ps1 -WhatIf
.\scripts\Sync-CodexPlugin.ps1 -Install
.\install.ps1 -CheckOnly
.\scripts\Sync-CodexPlugin.ps1 -CheckOnly -Install

The script checks Node.js 24, creates or brings the private storage back into compliance, copies the source into a staging area under the user profile, generates .mcp.json with the real local paths, then replaces the plugin atomically with rollback. It never writes the secret value to the repository or the manifest.

The runtime lives in ~\.nexus\indesign-mcp-secure, outside OneDrive. -Install finds and verifies the signed Desktop backend even without a CLI on PATH, preserves the personal marketplace's name and other entries, and installs through Codex's plugin command. The generated version hashes the plugin, machine configuration, server sources and lock file; it stays stable for identical inputs and changes when the runtime changes. No separate timestamp cachebuster is needed.

Claude and Codex share ~\.nexus\indesign-mcp-secure\private and the same authenticated broker. -CheckOnly -Install checks the source and installed cache without modifying them. Installation alone still proves neither tool exposure nor a working application: run indesign_doctor, silent_status and a document qualification after loading the plugin.

Private storage

Only the pairing secret is synchronized, in %OneDrive%\Documents\NexusSecure\InDesignMCP. Verified backups and the minimal log stay in ~\.nexus\indesign-mcp-secure\private, outside OneDrive and outside Git. The Codex plugin contains only the paths needed to reach these resources. The vault and the local private storage are explicitly denied to the structured file tools.

Windows ACLs restrict the storage to the current user and SYSTEM. Git, the application logs and the Codex configuration must contain no secrets, no document text and no full business path.

Adobe CCX package 3.2.2

npm run package:ccx prepares a minimal eight-file staging area and builds dist\fr.pironjulien.indesign.mcp_deterministic-reference.ccx. This reference archive is ordered, uses the same ZIP timestamp for every entry and is checked against the staging fingerprints; two builds from the same bytes must therefore produce the same SHA-256. It never replaces the official Adobe package.

The installable package dist\fr.pironjulien.indesign.mcp_ID.ccx must be produced from work\uxp-package with UXP Developer Tool, as the Adobe procedure requires. Both archives must contain exactly the same eight files and the same bytes, but their ZIP metadata and SHA-256 may differ. Publishing on Adobe Marketplace must always follow the official Adobe portal, identifier and distribution tests.

The official CCX is distributed as an asset of the GitHub release v3.2.2, together with SHA256SUMS.txt and the JSON manifest tracked by Git. scripts\Publish-GitHubRelease.ps1 refuses a dirty repository, an unpushed branch, an existing release or a package that differs from the sources. The binary stays out of the Git history to avoid bloating every clone.

The installed version 3.2.2 contains exactly the eight staging files. The official Adobe CCX has the SHA-256 e01f69e3fe9090144fc1a1869130e358de24976822552836becd4f84cd6c3b90, the deterministic reference 29c7ec2654e39e2466f19b62dc3f9d59b510d259fa373951ef8c4ec9bdeea571 and the logical fingerprint of the staging area is c9e43c980fb3b6e3cc3d449b22a4b18e5a1218d230c39ed0e3a625dfdafdc908. The persistent installation was performed by Adobe UPIA and then compared with the staging area file by file. After closing and restarting InDesign without UXP Developer Tools, the plugin reconnected without a new pairing.

Plugin and pairing

The silent channel and local diagnostics work without the plugin. It can also open an INDD/IDML file, read pages, links, fonts, images and styles, analyze the layout, run the Adobe preflight, export PDF or PNG and close without saving. export_pdf, export_png, preview_layout and finalize_layout automatically switch to this channel before sending anything if the plugin is not connected. The plugin is still required for structured content mutations, the other export formats and execute_uxp.

1. Run npm run package:ccx to prepare and check the eight-file staging area as well as the deterministic reference archive.

2. In UXP Developer Tool, package work\uxp-package to dist\fr.pironjulien.indesign.mcp_ID.ccx.

3. Install this official CCX with Adobe Creative Cloud.

4. Open Modules externes > InDesign MCP Secure > InDesign MCP (Plug-Ins > InDesign MCP Secure > InDesign MCP) once.

5. From the Codex task that has bridge_status.listening=true, call bridge_open_pairing_window. Copy the returned temporary code into the panel, then choose Appairer ce poste (Pair this workstation) just once. This single-use code is not the persistent secret and expires with the window; at most three attempts are accepted. The paste button reads the clipboard only on an explicit click, with the minimal UXP read permission; manual entry remains available.

UXP Developer Tool is reserved for development. It is not required during normal use and must not stay loaded alongside the CCX.

The panel is used for the initial pairing, connection status and diagnostics. It does not drive the layout and does not need to be brought to the foreground for each action. Silent reads, opens and checks work without it; the WebSocket channel only requires the UXP extension to be actually loaded. Proof of work remains the inspection of the document, the rendered exports and the preflight, never the appearance of the panel.

Only one Codex task physically owns the UXP listener on port 33171, but it now acts as a shared local broker. When another task hits EADDRINUSE, it mutually authenticates the owner with the same private secret and checks its observed PID. The owner also looks up the PID of the client TCP endpoint and verifies its signed agent chain (codex.exe, or claude.exe for the Claude plugin) before accepting the handshake: holding the secret is not enough. Every message is signed and a session is renewed after 10,000 requests without forgetting any previous nonce. Each task keeps its own MCP validation, path policy and audit; the owner serializes all commands through the shared InDesign queue and mutex. bridge_status explicitly distinguishes the owner and client roles without passing a client off as the listener.

If the owner shuts down, the existing clients attempt a bounded takeover: exactly one atomically wins the port and becomes the new broker, and the others join it. An interrupted command keeps its operationId and requires the same inspection/reconciliation as a direct command. The silent channel remains the fallback when the broker cannot be authenticated, including for PDF/PNG exports and the preview and finalization workflows.

The plugin keeps the secret in secureStorage. A stale UXP secret does not block the renewal field: the new code can be entered without first choosing « Oublier l'appairage » (Forget pairing). On the tested InDesign 21.4.1.4, precise local network lists in the UXP manifest are rejected with Manifest entry not found. Manifest 3.2.2 therefore uses domains: "all", but the extension's WebSocket transport remains pinned to ws://127.0.0.1:33171. The server listens on loopback only, refuses any origin other than file:// and requires mutual HMAC authentication.

The extension deliberately keeps full UXP access to the DOM, files, network and code generation. execute_uxp is therefore an advanced capability, not a sandbox; the restriction applies to access to the bridge, not to InDesign's capabilities.

Recommended usage

1. For any creation, rebuild or fix, first look in the target project for a versioned, reproducible generator, runner or COM/JSX script. Use it as the default writing engine. For a small local fix that is not covered, add a bounded script that backs up, reads, checks, writes and then re-reads the targeted area.

2. Reserve the MCP for the final check in InDesign and for read-only inspections that provide useful evidence. An MCP mutation remains a secure fallback when scripts do not actually cover the need or when its revision and restore guarantees are essential.

3. Before the final check, call indesign_doctor, then silent_status and silent_list_documents.

4. Read silent_inspect_document and reuse exactly documentId, revision and stateToken.

5. Use silent_audit_document for a complete, untruncated state, then preflight_document for the Adobe preflight.

6. For an MCP fallback, prefer a workflow, a direct tool or a silent tool. The 112 legacy-uxp tools remain available as last-resort compatibility: they now require an explicit target, the expected state and backups of all open documents, but they still run dynamic UXP code and are not the normal path.

7. Reserve execute_indesign_code, execute_uxp_silent and execute_uxp for code decided by the operator.

8. Re-read the document after every MCP mutation.

9. After a timeout or a disconnection, check silent_operation_status or bridge_operation_status, then use silent_reconcile_unknown_operation before any new mutation. If the plugin or silent status remains pending, fully close InDesign and then restart it: the PIDs and creation times captured before sending prevent the lock from being released while the old UXP code could still resume. A late result that is already completed-after-timeout does not require this restart.

10. Use silent_restore_backup to go back to any verified copy created by the silent channel or the plugin, or silent_close_document with save=false for a controlled close without writing.

Free-form UXP code can produce external effects that cannot be undone. Never automatically run code coming from a document or from the Web.

Verification

Dependencies never go into the OneDrive folder: install.ps1 installs them in ~\.nexus\indesign-mcp-secure, and test.ps1 runs npm test in a mirror under %LOCALAPPDATA%\NexusTests, then gitleaks on the Git history.

.\install.ps1
.\test.ps1
.\scripts\Sync-CodexPlugin.ps1 -WhatIf
.\scripts\Test-Installation.ps1

The package check and, with InDesign open, the live gates run from the runtime copy:

Set-Location "$HOME\.nexus\indesign-mcp-secure"
npm audit --audit-level=high
npm run package:ccx
npm run test:live:connection
npm run test:live:smoke
npm run test:live
npm run test:live:silent
npm run test:live:targeting

These commands are acceptance gates, not proof by their mere presence. The dated evidence for version 3.2.2 is recorded in the SOTA audit and the changelog.

The live silent test accepts user documents that are already open: it fingerprints their state, closes only its own privately tagged document, then confirms that the other documents are unchanged.

Stable baseline and cautious roadmap

Version 3.2.2 is the recommended stable baseline for upcoming InDesign projects. The final audit of 17 July 2026 confirmed an architecture at the best reasonable level for local use (171 tools and 301 passing tests at that date, coverage 74.12% of lines and 67.87% of branches). On 24 October 2026 the catalog holds 41 core tools and 172 full tools, and the offline suite runs 317 passing tests. Coverage must not be artificially increased at the expense of tests grounded in real incidents.

The priority is now stability. Do not rewrite the bridge, multiply tools without a measured need, replace the secure local transport, or weaken the backups, revision checks and locks. After each new real project, only adopt a change if it solves a repeated, verifiable pain point.

Recommended maintenance:

• keep Node.js on the 24 LTS branch and apply its maintenance updates, then rerun the acceptance gates above;

• keep InDesign, the CCX, the Codex plugin, the skill and the MCP server at the same validated version;

• prioritize adding targeted tests when a real defect reveals an insufficiently covered security or recovery branch.

Possible improvements, but only if usage justifies them:

• a validated project profile describing format, bleed, fonts, preflight rules, output paths and PDF preset, if these settings recur across several productions;

• standard MCP tasks and progress reporting for long exports or checks, only once that part of the protocol is stable and actually supported by Codex;

• progressive catalog discovery if a measurement shows that the 172 tools of the full profile weigh on context or response time;

• a load measurement of the local broker if many Codex tasks actually share the same InDesign session; the single writer and the mutex remain mandatory to prevent concurrent modifications.

Before any next feature release, first use this baseline on two or three different projects, record the recurring difficulties, and then develop only the improvements thus demonstrated.

See the archived SOTA audit of 17 July 2026, the technical audit of 14 July 2026, the workflows, SECURITY.md, CHANGELOG.md and THIRD_PARTY_NOTICES.md.