Create, open, save, or close an Illustrator document.

CONTRACT: readOnly=False, destructive=True, idempotent=False, openWorld=True

WHEN TO USE:

• Starting a new illustration (action='create')

• Opening an existing .ai file (action='open', file_path required)

• Saving current work (action='save', file_path for save-as)

• Closing the active document (action='close')

EXAMPLES: illustrator_document(action="create", width=800, height=600, color_mode="RGB") illustrator_document(action="open", file_path="C:/art/figure.ai") illustrator_document(action="save", file_path="C:/art/figure_v2.ai") illustrator_document(action="close", save_before_close=True)

NOTES:

• close without save_before_close=True discards unsaved changes

• open/save interact with the filesystem (openWorld)

Execute raw JavaScript/ExtendScript code in Adobe Illustrator.

CONTRACT: readOnly=False, destructive=True, idempotent=False, openWorld=True

WHEN TO USE:

• Single one-off items, quick prototypes, or operations not covered by higher-level tools

• Full DOM access when structured tools are insufficient

• Reading document state with custom logic

ABSTRACTION LADDER — prefer higher levels before using raw script: Level 5 — illustrator_path_boolean: boolean sculpt (unite/subtract/intersect/xor) Level 4 — illustrator_execute_task + element_create_batch: batch-create identical shapes Level 3 — illustrator_path_import_svg: import SVG d-string paths Level 2 — illustrator_execute_task + element_create: smooth curves, handles, mirror Level 1 — illustrator_execute_script (THIS tool): raw ExtendScript

DECISION RULES:

• Subtract/unite shapes — MUST use illustrator_path_boolean

• Creating >=3 identical shapes — MUST use illustrator_execute_task + element_create_batch

• setEntirePath with >12 coord pairs — STOP and use smooth:true or illustrator_path_import_svg

COORDINATE SYSTEM:

• API coordinates use top-left origin with y increasing downward (screen space)

• ExtendScript expects Y-up internally; use -y when calling Illustrator DOM methods

• Units: points (1 pt = 1/72 inch)

• Example: to place at visual position (100, 200), use position = [100, -200]

EXAMPLES: Rectangle: doc.pathItems.rectangle(top, left, width, height) ⚠ width & height must be POSITIVE. Negative height → shape above artboard (invisible). Ellipse: doc.pathItems.ellipse(top, left, width, height) Line: var p = doc.pathItems.add(); p.setEntirePath([[x1,-y1], [x2,-y2]]) Color: var c = new RGBColor(); c.red=255; c.green=0; c.blue=0; shape.fillColor = c; Text: var tf = doc.textFrames.add(); tf.contents = "text"; tf.position = [x, -y]; Grid helpers: artboardGrid(cols, rows), itemsInCell(cell, mode)

ELEMENT DISCOVERY:

• Use artboardGrid(cols, rows) to partition the artboard into a labeled grid

• Use itemsInCell(cell, mode) to find items in a specific grid cell

• Modes: 'containsCenter' (default) or 'intersects'

• Cell labels follow A1 scheme (letter row + number col, e.g. A1, B3)

MUTATION SAFETY:

• Each call increments a mutation counter for VLM QA cadence tracking

• Failed executions auto-decrement the counter to avoid cadence drift

• Use final_step=true on the last mutation to force a visual checkpoint

NOTES:

• Every call increments a mutation counter; annotated preview auto-injected at VLM cadence

• Set final_step=true on the last mutation to force a VLM checkpoint

• setEntirePath() creates corner points only; set handles after creation

• ExtendScript can access File/Folder and OS — treat as open-world

SAFETY:

• __mcp_check() watchdog: call as FIRST line inside every for/while body

• Never iterate live Illustrator collections if adding/removing items

• Use __mcp_forEachSnapshot(collection, fn) or __mcp_snapshot(collection) instead

Execute a structured task using the Task Protocol v2.1.

CONTRACT: readOnly=False, destructive=True, idempotent=False, openWorld=False

WHEN TO USE:

• Creating/modifying elements with declarative ops (element_create, style_set, etc.)

• Batch element creation (element_create_batch)

• Any operation that benefits from structured error reports and target selectors

EXAMPLES: Smooth curve: illustrator_execute_task(payload={task: "element_create", params: { type: "path", points: [[0,50],[50,0],[100,50],[150,0]], smooth: true, tension: 0.5, fill: {r: 0, g: 150, b: 136}}}) Batch shapes: illustrator_execute_task(payload={task: "element_create_batch", params: { template: {type: "ellipse", rx: 4, ry: 3}, array: {count: 47, startX: 180, spacingX: 15}}}) Grid layout: illustrator_execute_task(payload={task: "element_create_batch", params: { template: {type: "rect", w: 8, h: 8}, array: {count: 50, cols: 10, spacingX: 15, spacingY: 15}}})

TARGET SELECTORS: {type: "selection"} — current selection (default) {type: "layer", layer: "Layer 1"} — all items on layer {type: "query", itemType: "PathItem", pattern: "axis_*"} — pattern match {type: "all", recursive: true} — all items in document {type: "id", ids: ["A1", "A2"]} — stable MCP ID targeting

OPTIONS: dryRun: true — compute actions without applying trace: true — include execution trace in report assignIds: true — write unique IDs to item.note (opt-in)

NOTES:

• All task+params must be wrapped in a 'payload' field

• For boolean ops use illustrator_path_boolean, not execute_task

• For raw SVG path data use illustrator_path_import_svg

Export the active document to PNG, JPG, SVG, or PDF.

CONTRACT: readOnly=False, destructive=True, idempotent=False, openWorld=True

WHEN TO USE:

• Generating raster output (PNG, JPG) with optional scale factor

• Exporting vector formats (SVG, PDF)

• Getting visual feedback by setting return_image=True (PNG/JPG only)

EXAMPLES: illustrator_export_document(file_path="C:/out/fig.png", format="png", scale=2.0) illustrator_export_document(file_path="C:/out/fig.pdf", format="pdf") illustrator_export_document(file_path="C:/out/fig.png", return_image=True, artboard_only=True)

NOTES:

• artboard_only=True clips export to artboard; a pre-check warns if nothing is on it

• PDF export uses saveAs (longer timeout)

• return_image returns base64 image bytes as ImageContent for visual verification

• Overwrites existing file at file_path (destructive to filesystem)

Get complete document information and structure as a JSON tree.

CONTRACT: readOnly=True, destructive=False, idempotent=True, openWorld=False

WHEN TO USE:

• Understanding canvas state before writing modification scripts

• Inspecting layers, items, positions, and properties

• Getting Illustrator application info (scope='app')

OPTIONS: scope: 'document' (default), 'app', or 'both' max_items: items per layer, 1-5000 (default 200) max_layers: layers to return, 1-200 (default 50) offset: skip first N items per layer (for paging) layer_name / layer_index: filter to single layer

EXAMPLES: illustrator_get_document() illustrator_get_document(scope="app") illustrator_get_document(layer_name="Layer 1", offset=200, max_items=200)

NOTES:

• If a layer is truncated, response includes truncated=true and nextOffset

• scope='both' returns {document: {...}, app: {...}}

Undo or redo actions in Illustrator.

CONTRACT: readOnly=False, destructive=True, idempotent=False, openWorld=False

WHEN TO USE:

• Reverting mistakes (action='undo', count=N)

• Restoring undone changes (action='redo')

• Saving/restoring named checkpoints for recovery

EXAMPLES: illustrator_history(action="undo", count=3) illustrator_history(action="checkpoint_save", name="before_boolean") illustrator_history(action="checkpoint_restore", name="before_boolean") illustrator_history(action="checkpoint_list")

NOTES:

• Checkpoints capture MCP-managed items only (those with @mcp:id)

• checkpoint_restore is mutate-in-place; may require multiple undo to revert

• undo/redo change document state (destructive)

Perform boolean operations (subtract, unite, intersect, xor) on paths.

CONTRACT: readOnly=False, destructive=True, idempotent=False, openWorld=False

WHEN TO USE:

• Combining shapes (unite), cutting holes (subtract), finding overlaps (intersect)

• Any shape sculpting that needs boolean geometry

PIPELINE:

1. Extract geometry from Illustrator paths (ExtendScript)

2. Flatten Bezier curves if present (Python)

3. Run boolean operation via Clipper (Python)

4. Reconstruct result as PathItem or CompoundPathItem (ExtendScript)

5. Delete originals on success (if delete_originals=True)

EXAMPLES: illustrator_path_boolean(operation="unite", subject="body_id", clip=["wing_id"]) illustrator_path_boolean(operation="subtract", subject="plate_id", clip=["hole_id"])

NOTES:

• Operates on fill geometry only — strokes are ignored (warning emitted)

• Simple results produce PathItem; shapes with holes produce CompoundPathItem

• Subject and clip identified by MCP ID (@mcp:id in item.note)

Import an SVG path d attribute into the active document.

CONTRACT: readOnly=False, destructive=False, idempotent=False, openWorld=False

WHEN TO USE:

• Importing existing SVG path data (d strings) into Illustrator

• Complex outlines, organic shapes, arcs described in SVG syntax

EXAMPLES: illustrator_path_import_svg(d="M 10 50 C 20 20, 80 20, 90 50 Z") illustrator_path_import_svg(d="M 0 0 L 100 0 L 100 100 Z", fill={r: 255, g: 0, b: 0})

NOTES:

• Parses SVG d string server-side, converts arcs to cubic Beziers

• Safety limits: 50,000 chars, 5,000 segments, 100 subpaths, +/-100,000 coords

• Returned bounds are [left, top, right, bottom] in Illustrator's native Y-up space

• For new shapes prefer illustrator_execute_task + element_create with smooth:true

Place an external file (EPS, AI, PDF, image) into the document.

CONTRACT: readOnly=False, destructive=True, idempotent=False, openWorld=True

WHEN TO USE:

• Importing raster images (PNG, JPG) into Illustrator

• Placing vector files (EPS, AI, PDF, SVG)

• Vectorizing raster images via Image Trace (trace=True)

KEY CONCEPTS: linked=True (drafting) — file updates automatically when source changes linked=False (final) — file is embedded and fully editable embed_editable=True — opens PDF, copies content as editable vectors (slower) trace=True — place raster, then run Image Trace to vectorize

EXAMPLES: illustrator_place_file(file_path="C:/img/photo.png", x=100, y=50, linked=True) illustrator_place_file(file_path="C:/img/photo.png", trace=True, trace_preset="6 Colors")

NOTES:

• trace + expand=True: editable paths, higher DOM complexity

• trace + expand=False: live trace PluginItem, lighter but limited editability

• High-complexity images may produce >2000 paths (warning emitted)

• Reads external files from filesystem (openWorld)

Perform observational validation on the active document.

CONTRACT: readOnly=True, destructive=False, idempotent=True, openWorld=False

WHEN TO USE:

• Before export to catch common issues

• Validating document state after a series of modifications

KEY CONCEPTS: Checks for: items outside artboard bounds, zero-size items, empty text frames, locked layers/items. Does NOT modify the document.

NOTES:

• Returns ok=true if all checks pass, with warnings for issues found

• Bounds policy: 'warn' (default) emits warnings; 'error' sets ok=false

Query items using the Task Protocol with declarative target selection.

CONTRACT: readOnly=True, destructive=False, idempotent=True, openWorld=False

WHEN TO USE:

• Finding items by type, name pattern, or location before modification

• Inspecting current selection

• Listing all items on a layer or in the document

TARGET SELECTORS: {type: "selection"} — current selection (default) {type: "layer", layer: "Layer 1"} — all items on layer {type: "all", recursive: true} — all items in document {type: "query", itemType: "PathItem", pattern: "axis_*"} — filter by type/name

NOTES:

• Returns ItemRef for each matched item, enabling stable references

• Set include_trace=True for debugging

Set or clear a reference image on a locked background layer for tracing.

CONTRACT: readOnly=False, destructive=True, idempotent=True, openWorld=True

WHEN TO USE:

• Preparing a reference image overlay before manual or automated tracing

• Clearing a previous reference (omit file_path)

KEY CONCEPTS: Places image on a dedicated 'reference' layer at the bottom of the stack. Layer is locked, dimmed, and non-printable to prevent accidental edits. Calling again with the same file replaces the previous reference (idempotent).

EXAMPLES: illustrator_set_reference(file_path="C:/ref/sketch.png", opacity=50) illustrator_set_reference() -- clears the reference layer

NOTES:

• Removal mode (no file_path) is destructive — deletes the reference layer

• Uses the active artboard for fit/center calculations

• Extracts dominant colors from reference image if Pillow is available