illustrator_execute_script
Execute raw JavaScript/ExtendScript in Adobe Illustrator for one-off tasks, prototypes, or direct DOM access not covered by structured tools.
Instructions
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
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| params | Yes |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| result | Yes |