sol-indesign-mcp: Instructions file for Codex

Repository instructions

These rules apply to the entire sol-indesign-mcp repository. More specific AGENTS.md files may add constraints for a subtree but may not weaken these safety rules.

Mission and supported architecture

Build and maintain a production-quality local Codex-to-InDesign integration for native Windows:

Codex STDIO -> Node MCP server -> authenticated 127.0.0.1 bridge -> InDesign UXP plugin -> InDesign DOM

UXP is the only implemented InDesign adapter. Preserve the adapter boundary for a possible future COM/ExtendScript implementation, but do not add that fallback without an approved ADR and explicit task scope. Do not use UI automation.

Supported pinned foundations are native Windows Node 22.22.3, pnpm 11.13.0, TypeScript 6.0.3, stable @modelcontextprotocol/sdk 1.29.0, and Zod 4.4.3 imported through zod/v4. Do not add an MCP SDK v2 beta dependency.

Non-negotiable implementation rules

• Preserve strict TypeScript project references, noUncheckedIndexedAccess, and exactOptionalPropertyTypes.
• Do not use explicit any, @ts-ignore, unchecked casts, or disabled lint/type rules to bypass a design problem. Narrow unknown with explicit guards.
• Define all bridge messages, tool inputs/outputs, references, operations, and structured errors once in packages/protocol with strict Zod schemas.
• Keep MCP SDK-specific registration isolated in the MCP server registration module.
• Do not add arbitrary script execution, eval, indirect eval, new Function, string-form app.doScript, shell execution, arbitrary ExtendScript/VBScript, dynamic DOM member names, or arbitrary property bags.
• Do not broaden UXP permissions without an accepted ADR, threat-model update, and tests. Network permission must remain limited to the two port-qualified localhost origins in ADR 0005; plugin transport code stays fixed to those origins and the server remains bound only to 127.0.0.1:32145.
• Do not write logs, banners, diagnostics, or ordinary text to stdout in the MCP server. Stdout is MCP protocol only; use structured stderr or rotating audit files.
• Do not add an absolute-path input to an MCP tool or send a native path across the bridge. Validate workspace-relative paths independently on server and plugin.
• Do not change the default overwrite: false. Existing files return FILE_EXISTS; replacement requires explicit overwrite: true and destructive approval.
• Do not modify documents from read-only tools, including assigning persistent UUID labels during inspection.
• Never resolve a write target solely by name, collection index, current selection, or geometry. Re-resolve explicit references inside the serial queue and verify ownership, kind, revision, UUID, and fingerprint when supplied.
• Send every InDesign DOM read and write through the single plugin FIFO queue.
• Validate an operation batch completely before calling function-form app.doScript. Report partial changes and the exact Undo label; never blindly call global Undo after failure.
• Snapshot and restore every touched readable preference in finally.
• Keep outputs bounded. Do not expose complete stories, raw DOM objects, secrets, authentication messages, environment dumps, native paths, file contents, or raw stack traces.
• Return structured, user-safe errors with code, message, traceId, retryable, and bounded optional details.
• Fail closed with UNSUPPORTED_CAPABILITY when a runtime-dependent Adobe API is absent.