# https://github.com/ie3jp/illustrator-mcp-server Project Manual
Generated on: 2026-05-25 04:41:40 UTC
## Table of Contents
- [Project Overview](#project-overview)
- [Getting Started](#getting-started)
- [System Architecture](#architecture)
- [Execution Flow](#execution-flow)
- [Read Tools](#read-tools)
- [Modify Tools](#modify-tools)
- [Export Tools](#export-tools)
- [Utility Tools](#utility-tools)
- [Coordinate Systems](#coordinate-systems)
- [Development Guide](#development-guide)
## Project Overview
### Related Pages
Related topics: [Getting Started](#getting-started), [System Architecture](#architecture)
Relevant source files
The following source files were used to generate this page:
- [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
- [README.ko.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.ko.md)
- [README.de.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.de.md)
- [README.pt-BR.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.pt-BR.md)
- [README.es.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.es.md)
- [README.zh-CN.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.zh-CN.md)
- [plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md)
# Project Overview
## Introduction
**illustrator-mcp-server** is a Model Context Protocol (MCP) server that enables Claude, an AI assistant, to control Adobe Illustrator programmatically through natural language commands. This open-source project bridges the gap between AI capabilities and professional design workflows, allowing designers and developers to automate repetitive tasks, perform batch operations, and generate complex artwork through conversational interfaces.
Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
## Purpose and Scope
The primary purpose of illustrator-mcp-server is to provide a comprehensive automation layer for Adobe Illustrator, making it accessible to users who may not have scripting experience while offering power users a flexible scripting alternative. The project serves multiple use cases:
- **Design Automation**: Automate repetitive design tasks such as batch exports, color replacements, and object alignment
- **Pre-press Validation**: Perform comprehensive print-readiness checks including PDF/X compliance verification
- **Document Generation**: Create new documents with specific dimensions, color modes, and structures programmatically
- **Design Assistance**: Enable AI-driven design workflows where Claude can generate artwork, layout suggestions, and style guides
Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
## Architecture Overview
The system follows a client-server architecture built on the Model Context Protocol:
```mermaid
graph TD
subgraph "Client Layer"
Claude[Claude AI Assistant]
ClaudeCode[Claude Code CLI]
ClaudeDesktop[Claude Desktop App]
end
subgraph "MCP Protocol Layer"
MCPServer[MCP Server
illustrator-mcp-server]
end
subgraph "Adobe Illustrator"
AI[Adobe Illustrator]
AS[AppleScript / COM]
end
Claude -->|MCP Protocol| MCPServer
MCPServer -->|Node.js 20+| AS
AS -->|Automation API| AI
ClaudeCode -.->|mcp add| MCPServer
ClaudeDesktop -.->|npx / .mcpb| MCPServer
```
### Technology Stack
| Component | Technology | Version Requirement |
|-----------|------------|---------------------|
| Runtime | Node.js | 20+ |
| Language | TypeScript | - |
| Protocol | Model Context Protocol | Latest |
| Automation | AppleScript (macOS) / COM (Windows) | - |
| Target App | Adobe Illustrator | CS6 or later |
Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
## Core Feature Summary
### Tool Categories
The server provides over **60 tools** organized into functional categories:
| Category | Count | Primary Functions |
|----------|-------|-------------------|
| Read Tools | 21 | Document inspection, layer structure, color analysis, image quality |
| Modify/Create Tools | 21+ | Shape creation, text manipulation, object modification |
| Export Tools | 2 | SVG, PNG, JPG, PDF export with options |
| Utility | 3 | Pre-flight checks, text consistency, workflow mode |
Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
### Automatic Coordinate System Detection
One of the distinguishing features is intelligent coordinate system detection based on document color mode:
```mermaid
graph LR
A[Document Opens] --> B{Color Mode?}
B -->|CMYK| C[document
coordinate system]
B -->|RGB| D[artboard-web
coordinate system]
C --> E[Origin: Bottom-left
Y-axis: Up]
D --> F[Origin: Top-left
Y-axis: Down]
E -.->|Print designers
expect| C
F -.->|Web developers
expect| D
```
| Document Type | Coordinate System | Origin | Y Axis Direction |
|---------------|-------------------|--------|------------------|
| CMYK / Print | `document` | Bottom-left | Up |
| RGB / Web | `artboard-web` | Top-left of artboard | Down |
Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
### Print Production Tools
The project includes specialized tools for print production workflows:
- **preflight_check**: Validates RGB color mixing, broken links, low resolution images, white overprint, transparency conflicts, and PDF/X compliance
- **check_text_consistency**: Detects placeholders, notation variations (including Japanese double-line/Western single-line), and provides full text listing for LLM analysis
- **export_pdf**: Generates print-ready PDFs with crop marks, bleed settings, selective downsampling, and output intent
Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
## Installation Methods
### Claude Code
```bash
claude mcp add illustrator-mcp -- npx illustrator-mcp-server
```
### Claude Desktop
#### Method 1: Direct Installation
1. Download **`illustrator-mcp-server.mcpb`** from GitHub Releases
2. Open Claude Desktop → Settings → Extensions
3. Drag and drop the `.mcpb` file
4. Click Install
#### Method 2: Manual Configuration
```json
{
"mcpServers": {
"illustrator": {
"command": "npx",
"args": ["illustrator-mcp-server"]
}
}
}
```
> **Note**: If Node.js is installed via a version manager (nvm, mise, fnm), use the full path: `"command": "/full/path/to/npx"`
Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
## Example Workflows
### Video Test Pattern Generation
A complete SMPTE color bar test pattern created entirely through natural language prompts:
**Prompt:**
> Create a 1920x1080 video test pattern
**Result:**
- SMPTE color bars with PLUGE patterns
- Title safe and action safe zones
- Center crosshair markers
- Resolution and format labels
**Tools Used:**
`create_document`, `manage_layers` ×4, `create_rectangle` ×2, `create_gradient` ×2, `create_path` ×11, `create_ellipse` ×14, `create_line` ×4, `create_text_frame` ×2, `modify_object`, `set_z_order`, `export`
Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
### PDF/X-1a Compliance Check
```mermaid
sequenceDiagram
participant User
participant Claude
participant MCP_Server
participant Illustrator
User->>Claude: Check if document is PDF/X-1a compliant
Claude->>MCP_Server: preflight_check(target_pdf_profile: "x1a")
MCP_Server->>Illustrator: Run preflight analysis
Illustrator-->>MCP_Server: Return compliance results
MCP_Server-->>Claude: Display errors and warnings
Claude-->>User: Structured report with issues
Note over MCP_Server: Flags: transparency,
RGB colors in CMYK,
non-outlined fonts
```
Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
## Platform Support
| Platform | Status | Automation Method |
|----------|--------|-------------------|
| macOS | Fully Tested | AppleScript |
| Windows | Partial | PowerShell COM (not fully tested) |
Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
## Known Limitations
| Limitation | Description |
|------------|-------------|
| Windows Support | PowerShell COM automation used; not yet tested on real hardware |
| Live Effects | Drop shadow and similar effect parameters can be detected but not read |
| Color Profiles | Only profile assignment available; full conversion not supported |
| Bleed Settings | Cannot read bleed settings (API limitation) |
| WebP Export | Not supported; use PNG or SVG instead |
| Japanese Trim Marks | Uses TrimMark command approach for PDF export |
Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
## Testing Infrastructure
### Test Categories
| Test Type | Command | Requirements |
|-----------|---------|--------------|
| Unit Tests | `npm test` | Node.js environment |
| E2E Smoke Tests | `npx tsx test/e2e/smoke-test.ts` | Adobe Illustrator running |
The E2E smoke test performs:
- Creates fresh documents (RGB + CMYK)
- Places test objects
- Executes **182 test cases** across **10 phases**
- Covers all registered tools and coordinate system auto-detection
- Automatic cleanup after completion
Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
## Disclaimer
This tool automates many Illustrator operations, but AI can make mistakes. Extracted data, preflight results, and document modifications should always be reviewed by a human. The tool should not be relied upon as the sole quality check, especially for print submissions and client deliverables.
> **Important**: The authors are not responsible for any damages or losses arising from the use of this software or its outputs.
Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
## License
This project is released under the [MIT License](LICENSE).
---
## Getting Started
### Related Pages
Related topics: [Project Overview](#project-overview), [Development Guide](#development-guide)
Relevant source files
The following source files were used to generate this page:
- [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
- [README.ko.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.ko.md)
- [README.de.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.de.md)
- [README.pt-BR.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.pt-BR.md)
- [README.es.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.es.md)
- [README.zh-CN.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.zh-CN.md)
- [plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md)
# Getting Started
## Overview
This guide provides comprehensive instructions for setting up and running the illustrator-mcp-server, a Model Context Protocol (MCP) server that enables AI assistants like Claude to control Adobe Illustrator through natural language commands. The server acts as a bridge between Claude and Illustrator's scripting capabilities, allowing users to create, modify, and export artwork programmatically. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
## System Requirements
Before installation, ensure your system meets the following requirements:
| Requirement | Specification | Notes |
|-------------|---------------|-------|
| Node.js | 20+ | Required runtime environment |
| Operating System | macOS / Windows | Windows uses PowerShell COM automation |
| Adobe Illustrator | Any recent version | Multiple versions supported |
| Claude | Code or Desktop | MCP client compatibility |
Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
## Installation Methods
The illustrator-mcp-server supports multiple installation approaches depending on your workflow and preferences.
### Method 1: Claude Code (Recommended)
The simplest installation method for Claude Code users requires only the `npx` command execution. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
```bash
claude mcp add illustrator-mcp -- npx illustrator-mcp-server
```
This command registers the illustrator-mcp-server as an MCP tool that Claude Code can access. The server will be downloaded and executed on-demand via npx.
### Method 2: Claude Desktop with .mcpb File
For Claude Desktop users, download the pre-built `.mcpb` file from GitHub Releases. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
**Steps:**
1. Download **`illustrator-mcp-server.mcpb`** from [GitHub Releases](https://github.com/ie3jp/illustrator-mcp-server/releases/latest)
2. Open Claude Desktop → **Settings** → **Extensions**
3. Drag and drop the `.mcpb` file into the Extensions panel
4. Click the **Install** button
> [!NOTE]
> The `.mcpb` extension does not auto-update. To update, download the new version and reinstall. If you prefer automatic updates, use the npx method instead. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
### Method 3: Claude Desktop Manual Configuration
For users who prefer automatic updates or need custom configuration, manually edit the Claude Desktop configuration file. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
#### Step 1: Open the Configuration File
From the Claude Desktop menu bar:
- **Claude** → **Settings...** → **Developer** (in the left sidebar) → Click the **Edit Config** button
#### Step 2: Add Server Configuration
```json
{
"mcpServers": {
"illustrator": {
"command": "npx",
"args": ["illustrator-mcp-server"]
}
}
}
```
> [!NOTE]
> If you installed Node.js via a version manager (nvm, mise, fnm, etc.), Claude Desktop may not find `npx`. In that case, use the full path. Run `which npx` in your terminal to find the path. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
```json
"command": "/full/path/to/npx"
```
#### Step 3: Save and Restart
1. Save the file and close the text editor
2. **Fully quit** Claude Desktop (⌘Q / Ctrl+Q) and reopen
## Building from Source
For development, testing, or customization purposes, build the server from the source code. Source: [README.pt-BR.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.pt-BR.md)
### Prerequisites
- Git
- Node.js 20+
- npm
### Build Steps
```bash
git clone https://github.com/ie3jp/illustrator-mcp-server.git
cd illustrator-mcp-server
npm install
npm run build
```
After building, register the local server:
```bash
claude mcp add illustrator-mcp -- node /path/to/illustrator-mcp-server/dist/index.js
```
## Verification
After installation, verify that the server is properly configured by running the MCP inspector. Source: [README.pt-BR.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.pt-BR.md)
```bash
npx @modelcontextprotocol/inspector npx illustrator-mcp-server
```
The inspector provides an interactive interface to test MCP tool calls and confirm connectivity.
## Testing
The project includes comprehensive test suites to validate functionality across different scenarios.
### Unit Tests
Run the unit test suite to verify core functionality:
```bash
npm test
```
### End-to-End Smoke Tests
The E2E smoke test creates new documents (RGB + CMYK), inserts test objects, executes 182 test cases across 10 phases covering all registered tools and automatic coordinate system detection, then performs automatic cleanup. Source: [README.pt-BR.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.pt-BR.md)
```bash
npx tsx test/e2e/smoke-test.ts
```
> [!NOTE]
> E2E tests require Illustrator to be running. The smoke test will connect to the running instance and perform operations on temporary documents.
## Initial Configuration
### macOS Automation Permissions
On first run, macOS requires explicit permission for automation access. Navigate to:
**System Settings** → **Privacy & Security** → **Automation**
Locate Claude Desktop in the list and enable access for the automation permissions requested. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
### Multiple Illustrator Versions
If you have multiple versions of Illustrator installed, you can specify which version to use during conversation. Simply say "Use Illustrator 2024" and the `set_illustrator_version` tool will target that version. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
> [!NOTE]
> If Illustrator is already running, the server connects to the running instance automatically.
### Windows PowerShell Configuration
Windows uses PowerShell COM automation for Illustrator control. This functionality has not been tested on real hardware yet. Source: [README.es.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.es.md)
## Workflow Modes
The server supports different workflow modes that affect coordinate system handling. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
| Document Type | Coordinate System | Origin | Y Axis Direction |
|---------------|-------------------|--------|------------------|
| CMYK / Print | `document` | Bottom-left | Up |
| RGB / Web | `artboard-web` | Top-left of artboard | Down |
- **CMYK documents** use Illustrator's native coordinate system, matching what print designers expect
- **RGB documents** use a web-based coordinate system with origin at the top-left
Use the `set_workflow` tool to override the auto-detected coordinate system when needed.
## Quick Start Workflow
The following diagram illustrates the typical workflow when using the illustrator-mcp-server:
```mermaid
graph TD
A[User Input] --> B{Server Running?}
B -->|No| C[Start Illustrator]
B -->|Yes| D[Connect to Illustrator]
C --> D
D --> E[Send MCP Request]
E --> F[Process Tool Call]
F --> G{Modify or Read?}
G -->|Modify| H[Execute Illustrator Action]
G -->|Read| I[Query Illustrator State]
H --> J[Return Result]
I --> J
J --> K[User Receives Response]
L[Export Tools] --> M[SVG / PNG / PDF]
H --> L
```
## First-Time Usage Example
A typical first session might involve creating a new document and adding basic elements. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
```bash
# Create a new 1920x1080 document
You: Create a new Full HD document
Claude: → create_document (width: 1920, height: 1080, color_mode: "rgb")
✅ Created new document "Untitled-1"
# Add a rectangle
You: Add a blue rectangle in the center
Claude: → create_rectangle (x: 760, y: 390, width: 400, height: 300, fill: "#007AFF")
✅ Rectangle created
# Export the result
You: Export as PNG
Claude: → export (format: "png", artboard: 0)
✅ Exported to /output/Untitled-1.png
```
## Known Limitations
Before starting your project, be aware of the following limitations: Source: [README.es.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.es.md)
| Limitation | Details |
|------------|---------|
| Windows Support | Uses PowerShell COM automation (not tested on real hardware) |
| Live Effects | Drop shadow and effect parameters can be detected but not read |
| Color Profiles | Only profile assignment available — full conversion not supported |
| Bleed Settings | Cannot read bleed settings (Illustrator API limitation) |
| WebP Export | Not supported — use PNG or SVG instead |
| Japanese Trim Marks | PDF export uses TrimMark command approach, generates marks as document paths |
| Font Embedding | Embedding mode (full/subset) cannot be controlled directly |
| Size Variations | Only proportional scaling available — text may need manual adjustment |
## Troubleshooting
### npx Not Found
If Claude Desktop cannot find `npx`, install Node.js via the official installer from [nodejs.org](https://nodejs.org/) instead of using version managers like nvm, mise, or fnm. Alternatively, use the full path to npx. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
### Illustrator Not Launching
Modify and export tools will bring Illustrator to the foreground during execution. If Illustrator fails to launch, ensure it is properly installed and you have the necessary permissions. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
### Permission Denied on macOS
Grant automation permissions in **System Settings** → **Privacy & Security** → **Automation** and ensure Claude Desktop is listed with appropriate access.
## Next Steps
After successful installation, explore the available tools:
- **Read Tools** (21): `get_document_info`, `get_artboards`, `get_layers`, `get_document_structure`, `list_text_frames`, `get_colors`, `get_path_items`, `get_images`, and more
- **Modify Tools** (38): `create_rectangle`, `create_ellipse`, `create_text_frame`, `create_path`, `modify_object`, `align_objects`, `manage_layers`, and more
- **Export Tools** (2): `export`, `export_pdf`
- **Utility Tools** (3): `preflight_check`, `check_text_consistency`, `set_workflow`
Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
> [!CAUTION]
> AI can make mistakes. Do not over-rely on the output — **always have a human perform the final check on submission data**. The user is responsible for the results. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
---
## System Architecture
### Related Pages
Related topics: [Execution Flow](#execution-flow), [Project Overview](#project-overview)
Relevant source files
The following source files were used to generate this page:
- [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
- [README.ko.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.ko.md)
- [README.de.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.de.md)
- [README.pt-BR.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.pt-BR.md)
- [README.fr.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.fr.md)
# System Architecture
## Overview
The illustrator-mcp-server is a Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with Adobe Illustrator through a standardized interface. The server acts as a bridge between natural language instructions from AI systems and the Adobe Illustrator scripting API, providing automation capabilities for document manipulation, design tasks, and pre-press operations.
The architecture follows a tool-based pattern where each Illustrator operation is exposed as an individual MCP tool. The server handles connection management, coordinate system transformations, and result serialization to provide a seamless experience for AI-driven design workflows.
## High-Level Architecture
```mermaid
graph TB
subgraph "Client Layer"
AI[AI Assistant
Claude, etc.]
MCP[MCP Client]
end
subgraph "Server Layer"
Server[MCP Server]
Registry[Tool Registry]
Executor[Tool Executor]
end
subgraph "Adobe Illustrator"
API[ExtendScript API
JavaScript Bridge]
App[Illustrator Application]
end
AI --> MCP
MCP --> Server
Server --> Registry
Server --> Executor
Executor --> API
API --> App
style AI fill:#e1f5fe
style App fill:#fff3e0
```
## Core Components
### Tool Registry
The tool registry maintains a catalog of all available MCP tools organized into functional categories. Each tool is registered with metadata including its name, description, input schema, and handler function.
**Tool Categories:**
| Category | Count | Description |
|----------|-------|-------------|
| Read Tools | 21 | Extract document information, colors, text, images, and structure |
| Modify Tools | 38 | Create, modify, and manage objects, layers, and documents |
| Export Tools | 2 | Export artwork to SVG, PNG, JPG, and PDF formats |
| Utility Tools | 3 | Preflight checks, text consistency, and workflow settings |
Source: [README.md](README.md)
### Coordinate System Management
The server implements automatic coordinate system detection based on document color mode:
| Document Type | Coordinate System | Origin | Y-Axis Direction |
|---------------|-------------------|--------|------------------|
| CMYK / Print | `document` | Bottom-left | Up |
| RGB / Web | `artboard-web` | Top-left of artboard | Down |
CMYK documents use Illustrator's native coordinate system matching print designer expectations, while RGB documents use a web-friendly coordinate system with origin at the top-left of the artboard. The `set_workflow` tool allows manual override of the auto-detected system.
Source: [README.md](README.md)
### Tool Execution Flow
```mermaid
sequenceDiagram
participant AI as AI Assistant
participant MCP as MCP Server
participant Registry as Tool Registry
participant Exec as Executor
participant App as Illustrator API
AI->>MCP: Tool Request
MCP->>Registry: Lookup Tool Definition
Registry-->>MCP: Tool Schema
MCP->>Exec: Execute Tool Call
Exec->>App: Invoke Illustrator Script
App-->>Exec: Script Result
Exec-->>MCP: Serialized Response
MCP-->>AI: JSON-RPC Response
```
## System Architecture Layers
### Layer 1: Client Interface
The MCP protocol defines how AI assistants communicate with the server. Clients connect using the MCP handshake protocol and receive the tool manifest during initialization.
**Connection Methods:**
```json
// Claude Desktop Configuration
{
"mcpServers": {
"illustrator": {
"command": "npx",
"args": ["illustrator-mcp-server"]
}
}
}
```
Source: [README.md](README.md)
### Layer 2: Server Implementation
The server layer handles:
- MCP protocol message parsing and routing
- Tool registration and discovery
- Request validation and error handling
- Response serialization
The server automatically manages Illustrator application connections, including support for multiple installed versions. The `set_illustrator_version` tool allows targeting specific Illustrator versions during a session.
### Layer 3: Illustrator Bridge
The bridge layer communicates with Adobe Illustrator through the ExtendScript/JavaScript API. This layer handles:
- Application state management (launch, connect, disconnect)
- Script execution and result parsing
- Coordinate transformation between coordinate systems
- Error translation from Illustrator errors to MCP-friendly messages
Source: [README.md](README.md)
## Tool Organization
### Read Tools (21 tools)
These tools extract information from the active Illustrator document:
| Tool | Purpose |
|------|---------|
| `get_document_info` | Document metadata (dimensions, color mode, profile) |
| `get_artboards` | Artboard information (position, size, orientation) |
| `get_layers` | Layer structure as a tree |
| `get_document_structure` | Full tree: layers → groups → objects |
| `get_colors` | Color swatches, gradients, spot colors |
| `get_path_items` | Path/shape data (fill, stroke, anchor points) |
| `get_images` | Embedded/linked image info with print quality |
| `get_symbols` | Symbol definitions and instances |
| `get_guidelines` | Guide information |
| `get_overprint_info` | Overprint settings and K only plate info |
Source: [README.md](README.md)
### Modify Tools (38 tools)
These tools create and modify document elements:
| Category | Capabilities |
|----------|-------------|
| Creation | Rectangles, ellipses, lines, text frames, paths, images |
| Modification | Object properties, z-order, grouping, alignment |
| Document | Create, open, save, close documents |
| Layers | Add, rename, show/hide, lock/unlock, delete |
| Styling | Convert to outlines, assign color profiles |
Source: [README.md](README.md)
### Export Tools (2 tools)
| Tool | Formats |
|------|---------|
| `export` | SVG, PNG, JPG by artboard, selection, or UUID |
| `export_pdf` | Print-ready PDF with crop marks, bleed, output intent |
Source: [README.md](README.md)
### Utility Tools (3 tools)
| Tool | Purpose |
|------|---------|
| `preflight_check` | Pre-press validation (RGB mixing, broken links, PDF/X compliance) |
| `check_text_consistency` | Placeholder detection, notation patterns |
| `set_workflow` | Override auto-detected coordinate system |
Source: [README.md](README.md)
## Data Flow Architecture
```mermaid
graph LR
subgraph "Input Processing"
Req[Tool Request] --> Parse[Parse & Validate]
Parse --> Transform[Coordinate Transform]
end
subgraph "Illustrator Processing"
Transform --> Script[Generate Script]
Script --> Execute[Execute in Illustrator]
Execute --> Result[Capture Result]
end
subgraph "Output Processing"
Result --> Serialize[Serialize Response]
Serialize --> Out[JSON-RPC Response]
end
style Input Processing fill:#e8f5e9
style Illustrator Processing fill:#fff8e1
style Output Processing fill:#e3f2fd
```
## Multiple Illustrator Version Support
The architecture supports concurrent installation of multiple Illustrator versions. The server can detect available versions and route requests to the appropriate application instance.
```mermaid
graph TD
Start[Start Session] --> Check{Running Instance?}
Check -->|Yes| Connect[Connect to Running]
Check -->|No| Detect[Detect Versions]
Detect --> Select[Select Version]
Select --> Launch[Launch Illustrator]
Connect --> Ready
Launch --> Ready
Ready[Ready for Commands]
User[User: "Use Illustrator 2024"] --> Override
Override[Call set_illustrator_version]
Override --> Ready
```
Source: [README.md](README.md)
## Workflow Modes
The server operates in two primary workflow modes that affect coordinate handling:
### Web/Print Workflow
| Mode | Use Case | Coordinate System |
|------|----------|-------------------|
| Web | RGB documents, screen output | `artboard-web` (top-left origin, Y-down) |
| Print | CMYK documents, commercial printing | `document` (bottom-left origin, Y-up) |
The server automatically detects the appropriate mode based on the document's color mode. Manual override is available via the `set_workflow` tool when AI needs consistent coordinate behavior.
Source: [README.md](README.md)
## Error Handling Architecture
```mermaid
graph TD
Script[Script Execution] --> Success{Success?}
Success -->|Yes| Return[Return Result]
Success -->|No| Identify[Identify Error Type]
Identify -->|API Error| IllustratorError[Illustrator Error]
Identify -->|Connection Error| ConnectionError[Connection Lost]
Identify -->|Validation Error| ValidationError[Invalid Parameters]
IllustratorError --> MCPError[Format as MCP Error]
ConnectionError --> Reconnect[Attempt Reconnect]
ValidationError --> MCPError
Reconnect --> Success
MCPError --> Response[Error Response]
Return --> Response
style Response fill:#ffcdd2
```
## Build and Deployment
### Project Structure
```
illustrator-mcp-server/
├── dist/ # Compiled JavaScript output
├── src/ # TypeScript source files
│ ├── server.ts # MCP server implementation
│ ├── index.ts # Entry point
│ └── tools/ # Tool implementations
├── test/ # Test files
│ └── e2e/ # End-to-end smoke tests
└── package.json # Dependencies and scripts
```
### Build Commands
```bash
npm install # Install dependencies
npm run build # Compile TypeScript to JavaScript
npm test # Run unit tests
```
Source: [README.md](README.md)
### Verification
```bash
npx @modelcontextprotocol/inspector npx illustrator-mcp-server
```
The MCP inspector tool validates that the server correctly implements the protocol and exposes all registered tools.
## Limitations and Architecture Constraints
| Limitation | Impact | Mitigation |
|------------|--------|------------|
| Windows COM automation | Untested on real hardware | Uses PowerShell for COM bridge |
| Live effects | Cannot read shadow parameters | Effects detected but not fully readable |
| Color profile conversion | Only profile assignment, not value conversion | Use Illustrator for conversion |
| Bleed settings | Cannot be read from document | Configure in export settings |
| WebP export | Not supported | Use PNG or SVG alternatives |
Source: [README.pt-BR.md](README.pt-BR.md)
## Security Considerations
The architecture includes several safety mechanisms:
1. **Manual Verification Required**: All extracted data, preflight results, and document modifications require human review before final submission
2. **Foreground Execution**: Modify and export tools bring Illustrator to the foreground during execution
3. **Automation Permissions**: macOS requires explicit automation access in System Settings → Privacy & Security → Automation
Source: [README.md](README.md)
---
## Execution Flow
### Related Pages
Related topics: [System Architecture](#architecture), [Coordinate Systems](#coordinate-systems)
Relevant source files
The following source files were used to generate this page:
- [src/executor/file-transport.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/executor/file-transport.ts)
- [src/executor/jsx-runner.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/executor/jsx-runner.ts)
- [src/tools/tool-executor.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/tool-executor.ts)
- [src/jsx/helpers/common.jsx](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/jsx/helpers/common.jsx)
- [src/tools/export/export.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export.ts)
- [src/tools/modify/place-symbol.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/place-symbol.ts)
- [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
# Execution Flow
## Overview
The execution flow is the core mechanism by which the MCP server communicates with Adobe Illustrator to perform design operations. Since Illustrator does not natively support the MCP (Model Context Protocol) or direct Node.js integration, the server acts as an intermediary that translates tool requests into ExtendScript (JSX) commands that Illustrator can execute. This architectural pattern enables Claude and other MCP-compatible AI assistants to control Adobe Illustrator programmatically.
The execution flow handles tool parameter serialization, cross-platform script generation (AppleScript for macOS, PowerShell for Windows), and result retrieval through a file-based transport mechanism. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
## Architecture Overview
```mermaid
flowchart LR
Claude <-->|MCP Protocol| Server["MCP Server\n(TypeScript/Node.js)"]
Server -.->|generate| Runner["run-{uuid}.scpt / .ps1"]
Server -.->|generate| JSX["script-{uuid}.jsx\n(BOM UTF-8)"]
Server -.->|write| PF["params-{uuid}.json"]
Runner -->|execFile| osascript
Runner -->|execFile| PS["powershell.exe"]
osascript -->|do javascript| AI["Adobe Illustrator\n(ExtendScript/JSX)"]
PS -->|DoJavaScript| AI
JSX -.->|execute| AI
PF -.->|read| AI
AI -.->|write| RF["result-{uuid}.json"]
RF -.->|read| Server
```
The system comprises four primary components that communicate through the file system:
| Component | Technology | Role |
|-----------|------------|------|
| MCP Server | TypeScript/Node.js | Receives tool requests, generates scripts, coordinates execution |
| Runner Script | AppleScript/PowerShell | Bridges the OS shell to Illustrator's scripting engine |
| JSX Script | ExtendScript | Contains the actual Illustrator operations |
| Parameter File | JSON | Passes typed parameters from the server to the JSX execution context |
Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
## Execution Pipeline Stages
### Stage 1: Tool Registration and Discovery
The MCP server registers all available tools during initialization. Each tool defines a name, input schema, and handler function. Tools are organized into categories (read, modify, export, utility) and are exposed to Claude through the MCP protocol. Source: [src/tools/tool-executor.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/tool-executor.ts)
### Stage 2: Request Handling
When a tool request arrives, the server performs the following validation and preparation steps:
1. **Schema validation** — Verify all required parameters are present
2. **Coordinate system detection** — Determine whether the document uses `document` (CMYK/print) or `artboard-web` (RGB/web) coordinates
3. **UUID generation** — Create a unique identifier for tracking this execution cycle
4. **Script selection** — Load the appropriate JSX template for the requested operation
Source: [src/tools/tool-executor.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/tool-executor.ts)
### Stage 3: Parameter Serialization
Parameters are serialized into a JSON file using the file transport mechanism. This file-based approach is necessary because ExtendScript and the Illustrator DOM cannot directly receive complex JavaScript objects from the Node.js process. Source: [src/executor/file-transport.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/executor/file-transport.ts)
The parameter file follows the naming convention `params-{uuid}.json` and contains typed parameters that the JSX script will read during execution.
### Stage 4: Script Generation
The server generates two scripts for each execution:
**JSX Script (`script-{uuid}.jsx`)**
- Written in BOM-encoded UTF-8 (required for Illustrator compatibility with non-ASCII characters)
- Contains the ExtendScript code that manipulates the Illustrator document
- References the parameter file path
- Writes results to `result-{uuid}.json`
**Runner Script**
- macOS: AppleScript (`.scpt`) that executes `osascript` with the JSX path
- Windows: PowerShell (`.ps1`) that executes Illustrator via COM automation
- Handles platform-specific execution context and error propagation
Source: [src/executor/jsx-runner.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/executor/jsx-runner.ts)
### Stage 5: Cross-Platform Execution
```mermaid
flowchart TD
subgraph macOS
A[Node.js Server] --> B[Generate .scpt]
B --> C[osascript]
C --> D[do javascript]
D --> E[Adobe Illustrator]
end
subgraph Windows
F[Node.js Server] --> G[Generate .ps1]
G --> H[powershell.exe]
H --> I[DoJavaScript]
I --> J[Adobe Illustrator]
end
```
The runner script invokes the appropriate shell command based on the operating system:
**macOS Execution Path**
```applescript
osascript -l JavaScript "/path/to/script-{uuid}.jsx"
```
**Windows Execution Path**
```powershell
$ai = New-Object -ComObject Illustrator.Application
$ai.DoJavaScript("/path/to/script-{uuid}.jsx")
```
Source: [src/executor/jsx-runner.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/executor/jsx-runner.ts)
### Stage 6: JSX Execution
The ExtendScript environment within Illustrator reads the parameter file and executes the DOM operations. The script has access to:
- The active document and its properties
- The parameter values serialized by the server
- Helper utilities from `src/jsx/helpers/common.jsx`
Common helper functions include UUID management, artboard coordinate conversion, and result file writing. Source: [src/jsx/helpers/common.jsx](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/jsx/helpers/common.jsx)
### Stage 7: Result Collection
After execution completes, the JSX script writes a result file (`result-{uuid}.json`) containing:
| Field | Description |
|-------|-------------|
| `success` | Boolean indicating whether the operation completed |
| `error` | Boolean flag for error state |
| `message` | Human-readable status or error message |
| `uuid` | Identifier of the created or modified object |
| `data` | Operation-specific result payload |
Source: [src/executor/file-transport.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/executor/file-transport.ts)
### Stage 8: Response Assembly
The MCP server reads the result file, parses the JSON payload, and constructs an MCP-formatted response that is sent back to Claude. If the operation failed, the response includes error details for debugging.
## Coordinate System Handling
The server automatically detects and handles coordinate system differences between document types:
| Document Type | Coordinate System | Origin | Y Axis Direction |
|---------------|-------------------|--------|-------------------|
| CMYK / Print | `document` | Bottom-left | Up |
| RGB / Web | `artboard-web` | Top-left of artboard | Down |
Conversion utilities in the JSX helpers transform coordinates between systems as needed. Source: [src/jsx/helpers/common.jsx](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/jsx/helpers/common.jsx)
## Error Handling
The execution flow includes multiple error handling layers:
1. **Parameter validation** — Invalid inputs are rejected before script generation
2. **Script compilation errors** — Malformed JSX is caught and reported
3. **Runtime errors** — Illustrator DOM errors are captured in the result file
4. **File system errors** — Missing or unwritable paths are detected
Example error response structure:
```json
{
"error": true,
"message": "Symbol not found: MySymbol",
"line": 42
}
```
Source: [src/tools/modify/place-symbol.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/place-symbol.ts)
## Export-Specific Execution
Export operations follow the standard flow but include additional file verification steps:
```mermaid
flowchart TD
Start[export tool called] --> Validate[Validate format & artboard]
Validate --> Generate[Generate export script]
Generate --> Execute[Run JSX via runner]
Execute --> Check{Output file exists?}
Check -->|Yes| DpiCalc[Calculate effective DPI]
Check -->|No| Error[Write error result]
DpiCalc --> Write[Write success result]
Write --> Done[Return to Claude]
Error --> Done
```
The export handler verifies the output file was created and includes effective DPI calculations in the result. Source: [src/tools/export/export.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export.ts)
## Build and Packaging
The server is compiled using a custom build script that:
1. Compiles TypeScript to JavaScript via `tsc`
2. Copies JSX files to the distribution directory
3. Bundles the server into a CommonJS module for Node.js compatibility
```bash
npm run build
```
Source: [package.json](https://github.com/ie3jp/illustrator-mcp-server/blob/main/package.json)
## Testing the Execution Flow
End-to-end smoke tests validate the complete flow by:
1. Creating fresh RGB and CMYK documents
2. Placing test objects via all registered tools
3. Running 182 test cases across 10 phases
4. Verifying coordinate system auto-detection
5. Cleaning up automatically
```bash
npx tsx test/e2e/smoke-test.ts
```
Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
## Summary
The execution flow transforms high-level tool requests from Claude into Illustrator DOM operations through a file-based transport mechanism. This architecture enables:
- Cross-platform support (macOS and Windows)
- Type-safe parameter passing via JSON
- BOM UTF-8 encoding for international character support
- Automatic coordinate system handling
- Comprehensive error reporting
- Asynchronous execution with UUID tracking
The separation between the MCP server, runner scripts, and JSX execution ensures that Illustrator remains isolated from the Node.js process, preventing compatibility issues between the different scripting environments.
---
## Read Tools
### Related Pages
Related topics: [Modify Tools](#modify-tools), [Export Tools](#export-tools)
Relevant source files
The following source files were used to generate this page:
- [src/tools/read/get-document-info.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-document-info.ts)
- [src/tools/read/get-document-structure.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-document-structure.ts)
- [src/tools/read/list-text-frames.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/list-text-frames.ts)
- [src/tools/read/get-text-frame-detail.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-text-frame-detail.ts)
- [src/tools/read/get-colors.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-colors.ts)
- [src/tools/read/get-images.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-images.ts)
- [src/tools/read/check-contrast.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/check-contrast.ts)
- [src/tools/read/extract-design-tokens.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/extract-design-tokens.ts)
# Read Tools
Read Tools in illustrator-mcp-server provide comprehensive read-only access to Adobe Illustrator documents. These 21 tools enable AI assistants like Claude to inspect, analyze, and extract information from open documents without modifying them. Read Tools serve as the foundation for document analysis, design auditing, preflight checks, and AI-driven content understanding.
## Overview
Read Tools are categorized into four functional areas:
| Category | Tool Count | Purpose |
|----------|-----------|---------|
| Document Analysis | 4 | Metadata, structure, coordinate systems |
| Text Analysis | 2 | Text frame inspection and attribute details |
| Visual Element Analysis | 10 | Colors, images, paths, effects, symbols |
| Accessibility & Compliance | 5 | Contrast checking, design token extraction, object search |
The tool architecture follows a consistent pattern where each tool returns structured JSON data suitable for AI consumption and analysis. All Read Tools operate on the currently active Illustrator document and do not modify document state.
## Architecture
```mermaid
graph TD
A[AI Assistant] -->|MCP Protocol| B[illustrator-mcp-server]
B -->|COM/AppleScript| C[Adobe Illustrator]
C -->|Document Data| B
B -->|Structured JSON| A
B --> D[Read Tools]
B --> E[Modify Tools]
B --> F[Export Tools]
B --> G[Utility Tools]
D --> D1[Document Tools]
D --> D2[Text Tools]
D --> D3[Visual Tools]
D --> D4[Compliance Tools]
```
### Tool Registration Pattern
Read Tools are registered as MCP (Model Context Protocol) handlers in the server initialization. Each tool follows this standard structure:
```
Tool Name → Handler Function → Illustrator Script → JSON Response
```
Source: [src/tools/read/get-document-info.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-document-info.ts)
## Document Analysis Tools
### get_document_info
Retrieves comprehensive metadata about the active Illustrator document.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `none` | - | - | Operates on currently active document |
**Returns:**
| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Document filename |
| `path` | string | Full file path |
| `width` | number | Document width in points |
| `height` | number | Document height in points |
| `colorMode` | string | "RGB" or "CMYK" |
| `colorProfile` | string | Assigned ICC profile |
| `artboards` | array | Array of artboard objects |
| `layers` | number | Layer count |
Source: [src/tools/read/get-document-info.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-document-info.ts)
### get_artboards
Returns information about all artboards in the document.
**Returns:**
| Field | Type | Description |
|-------|------|-------------|
| `artboards[]` | array | List of artboard objects |
| `artboards[].name` | string | Artboard name |
| `artboards[].rect` | object | Position and dimensions `{x, y, width, height}` |
| `artboards[].position` | string | Origin point reference |
Source: [src/tools/read/get-document-structure.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-document-structure.ts)
### get_document_structure
Provides a complete hierarchical tree of the document contents.
**Returns:** Nested tree structure:
```
Document
└── Layers
├── Groups
│ └── Objects
├── Text Frames
├── Paths
├── Images
└── Symbols
```
**Object Properties Returned:**
| Property | Applicable To | Description |
|----------|--------------|-------------|
| `name` | all | Object name |
| `type` | all | Object type (text, path, group, etc.) |
| `uuid` | all | Unique identifier |
| `bounds` | all | Bounding box coordinates |
| `visible` | all | Visibility state |
| `locked` | all | Lock state |
Source: [src/tools/read/get-document-structure.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-document-structure.ts)
### convert_coordinate
Converts coordinates between the document coordinate system and artboard coordinate system.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `x` | number | Yes | X coordinate |
| `y` | number | Yes | Y coordinate |
| `from` | string | Yes | Source system: "document" or "artboard" |
| `to` | string | Yes | Target system: "document" or "artboard" |
**Coordinate System Reference:**
| Document Type | Coordinate System | Origin | Y-axis Direction |
|---------------|-------------------|--------|------------------|
| CMYK/Print | `document` | Bottom-left | Up |
| RGB/Web | `artboard-web` | Top-left of artboard | Down |
Source: [src/tools/read/get-document-info.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-document-info.ts)
## Text Analysis Tools
### list_text_frames
Enumerates all text frames in the document with key attributes.
**Returns:**
| Field | Type | Description |
|-------|------|-------------|
| `textFrames[]` | array | List of text frame objects |
| `textFrames[].name` | string | Object name |
| `textFrames[].uuid` | string | Unique identifier |
| `textFrames[].contents` | string | Text content |
| `textFrames[].font` | string | Font family |
| `textFrames[].fontSize` | number | Font size in points |
| `textFrames[].style` | string | Style name (e.g., "Bold", "Italic") |
| `textFrames[].position` | object | {x, y} coordinates |
Source: [src/tools/read/list-text-frames.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/list-text-frames.ts)
### get_text_frame_detail
Returns comprehensive attributes for a specific text frame.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `uuid` | string | Yes | Text frame UUID |
**Returns:**
| Category | Fields |
|----------|--------|
| Basic | name, uuid, contents, font, fontSize |
| Style | style, fillColor, paragraphSpacing |
| Spacing | tracking, kerning, leading, baselineShift |
| Paragraph | alignment, firstLineIndent, leftIndent, rightIndent |
| Hyphenation | hyphenation, hyphenatedWordSize, hyphenationPreference |
| Position | x, y, width, height, rotation |
Source: [src/tools/read/get-text-frame-detail.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-text-frame-detail.ts)
## Color Analysis Tools
### get_colors
Extracts all color definitions used in the document.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `include_diagnostics` | boolean | No | Enable print-specific diagnostics |
**Returns:**
| Color Type | Description |
|------------|-------------|
| Swatches | Named colors from swatch panel |
| Gradients | Gradient definitions (linear/radial) |
| Spot Colors | Spot color definitions |
| Process Colors | CMYK/RGB process colors |
**Diagnostics (when enabled):**
| Check | Description |
|-------|-------------|
| RGB in CMYK | Detects RGB colors in CMYK documents |
| Unnamed Colors | Colors not defined in swatches |
| Gradient Issues | Missing gradient stops |
Source: [src/tools/read/get-colors.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-colors.ts)
### extract_design_tokens
Exports document colors and typography as design system tokens.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `format` | string | No | Output format: "css", "json", or "tailwind" |
| `scope` | string | No | "colors", "typography", or "all" |
**Output Formats:**
| Format | Example |
|--------|---------|
| CSS | `--color-primary: #34A853;` |
| JSON | `{"color": {"primary": "#34A853"}}` |
| Tailwind | `primary: '#34A853'` |
Source: [src/tools/read/extract-design-tokens.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/extract-design-tokens.ts)
## Image Analysis Tools
### get_images
Returns information about all embedded and linked images.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `include_print_info` | boolean | No | Enable print-quality analysis |
**Returns:**
| Field | Type | Description |
|-------|------|-------------|
| `name` | string | Image filename |
| `type` | string | "embedded" or "linked" |
| `linkStatus` | string | "ok", "missing", or "modified" |
| `actualPpi` | number | Actual resolution |
| `effectivePpi` | number | Resolution after scaling |
| `colorSpace` | string | Color mode of image |
**Print Information (when enabled):**
| Check | Field | Threshold |
|-------|-------|-----------|
| Resolution | effectivePpi | 300 for print |
| Color Space | colorSpace | Match document mode |
| Scale Factor | scale | Affects effective resolution |
Source: [src/tools/read/get-images.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-images.ts)
## Visual Element Tools
### get_path_items
Returns path and shape data for vector objects.
**Returns:**
| Data Category | Fields |
|--------------|--------|
| Fill | fillColor, opacity, blendMode |
| Stroke | strokeColor, strokeWidth, strokeCap, strokeJoin, dashArray |
| Geometry | anchorPoints, pathPoints, closed, pathType |
**Path Types:**
| Type | Description |
|------|-------------|
| `path` | Custom path with anchor points |
| `compound` | Compound path with multiple subpaths |
| `textPath` | Text on a path |
### get_groups
Returns group hierarchy and structure.
**Returns:**
| Field | Type | Description |
|-------|------|-------------|
| `groups[]` | array | List of group objects |
| `clips` | array | Clipping mask references |
| `compoundPaths` | array | Compound path structures |
### get_symbols
Returns symbol definitions and all instances in use.
**Returns:**
| Field | Type | Description |
|-------|------|-------------|
| `definitions[]` | array | Symbol library items |
| `instances[]` | array | Placed symbol instances |
| `usageCount` | number | How many times each symbol is used |
### get_effects
Returns effects and appearance settings.
**Returns:**
| Effect Type | Properties |
|-------------|------------|
| Opacity | opacity, blendMode |
| Drop Shadow | xOffset, yOffset, blur, color |
| Glow | blurRadius, spread, color |
| Inner Effects | innerShadow, innerGlow |
### get_guidelines
Returns guide line information.
**Returns:**
| Field | Type | Description |
|-------|------|-------------|
| `guidelines[]` | array | All guide lines |
| `orientation` | string | "horizontal" or "vertical" |
| `position` | number | Coordinate position |
## Compliance & Accessibility Tools
### check_contrast
Performs WCAG color contrast ratio analysis.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `foreground` | string | Yes | Foreground color (hex) |
| `background` | string | Yes | Background color (hex) |
**Returns:**
| Field | Type | Description |
|-------|------|-------------|
| `contrastRatio` | number | WCAG contrast ratio |
| `wcagAA` | object | AA level pass/fail for normal and large text |
| `wcagAAA` | object | AAA level pass/fail for normal and large text |
**WCAG Thresholds:**
| Level | Normal Text | Large Text |
|-------|-------------|------------|
| AA | 4.5:1 | 3:1 |
| AAA | 7:1 | 4.5:1 |
Source: [src/tools/read/check-contrast.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/check-contrast.ts)
### find_objects
Searches document objects by various criteria.
**Parameters:**
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `name` | string | No | Object name (partial match) |
| `type` | string | No | Object type filter |
| `color` | string | No | Color match |
| `font` | string | No | Font name filter |
| `layer` | string | No | Layer name filter |
### get_overprint_info
Returns overprint settings and rich black detection.
**Returns:**
| Check | Description |
|-------|-------------|
| Overprint Settings | Objects with overprint enabled |
| K100 Black | Pure black (K=100) usage |
| Rich Black | Multi-channel black usage |
| Intent | Classification as "process" or "spot" |
### get_separation_info
Returns color separation information for print production.
**Returns:**
| Plate Type | Description |
|------------|-------------|
| CMYK Process | Cyan, Magenta, Yellow, Black plates |
| Spot Colors | Named spot color inks |
| Usage Count | Object count per color plate |
### get_selection
Returns details of currently selected objects.
**Returns:**
| Field | Type | Description |
|-------|------|-------------|
| `selectedItems[]` | array | All selected objects |
| `count` | number | Number of selected items |
| `bounds` | object | Combined bounding box |
## Workflow Integration
Read Tools integrate with Modify and Export Tools in complex workflows:
```mermaid
graph LR
A[Read Tools] -->|Inspect| B[Document Analysis]
A -->|Validate| C[Preflight Check]
A -->|Extract| D[Design Tokens]
B --> E[Modify Tools]
C --> F[Utility Tools]
D --> G[Export Tools]
E --> H[Document Updates]
F --> I[Compliance Report]
G --> J[Asset Export]
```
### Example Workflow: Export with Text Outlining
```
get_artboards → Identify target artboards
convert_to_outlines → Convert fonts to paths
export → Export as SVG/PNG
```
### Example Workflow: Print Preflight
```
get_document_info → Check color mode
get_colors → Validate color definitions
get_images → Verify image resolution
get_overprint_info → Check overprint settings
preflight_check → Comprehensive report
```
## Common Usage Patterns
### Document Analysis Pattern
```typescript
// Get full document context
const docInfo = await get_document_info();
const structure = await get_document_structure();
const colors = await get_colors({ include_diagnostics: true });
```
### Text Audit Pattern
```typescript
// Comprehensive text analysis
const textFrames = await list_text_frames();
const details = await Promise.all(
textFrames.map(tf => get_text_frame_detail({ uuid: tf.uuid }))
);
```
### Design System Extraction Pattern
```typescript
// Export as CSS custom properties
const tokens = await extract_design_tokens({
format: "css",
scope: "all"
});
```
## Limitations
| Limitation | Details |
|------------|---------|
| Live Effects | Effect parameters (e.g., drop shadow settings) can be detected but not fully read |
| Bleed Settings | Bleed settings cannot be read (Illustrator API limitation) |
| Windows COM | Requires PowerShell for Windows COM automation |
| Document Required | Most tools require an open document (except `list_fonts`) |
## See Also
- [Modify Tools](modify-tools.md) - Tools for editing document content
- [Export Tools](export-tools.md) - Tools for exporting documents
- [Utility Tools](utility-tools.md) - Pre-flight and workflow utilities
- [Preflight Workflow](../workflows/print-preflight-workflow.md) - Complete print compliance workflow
---
## Modify Tools
### Related Pages
Related topics: [Read Tools](#read-tools), [Export Tools](#export-tools)
# Modify Tools
Relevant source files
The following source files were used to generate this page:
- [src/tools/modify/create-document.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/create-document.ts)
- [src/tools/modify/create-rectangle.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/create-rectangle.ts)
- [src/tools/modify/create-text-frame.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/create-text-frame.ts)
- [src/tools/modify/manage-layers.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/manage-layers.ts)
- [src/tools/modify/align-objects.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/align-objects.ts)
- [src/tools/modify/group-objects.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/group-objects.ts)
- [src/tools/modify/save-document.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/save-document.ts)
- [src/tools/modify/manage-swatches.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/manage-swatches.ts)
## Overview
The **Modify Tools** are a collection of 38 tools within the illustrator-mcp-server that enable AI assistants (specifically Claude) to create, modify, and manipulate objects in Adobe Illustrator documents through natural language commands. These tools form the core of the server's ability to perform design operations by bridging natural language instructions with the Adobe Illustrator scripting API.
The Modify Tools handle everything from basic shape creation (rectangles, ellipses, lines) to complex operations like object grouping, layer management, and document saving. They are designed to work seamlessly with the Read Tools and Export Tools to provide a complete workflow for automated design tasks.
## Architecture
### Tool Categories
The Modify Tools are organized into several functional categories:
```mermaid
graph TD
A[Modify Tools] --> B[Shape Creation]
A --> C[Text Creation]
A --> D[Object Manipulation]
A --> E[Layer Management]
A --> F[Document Operations]
A --> G[Color Management]
B --> B1[create_rectangle]
B --> B2[create_ellipse]
B --> B3[create_line]
B --> B4[create_path]
C --> C1[create_text_frame]
D --> D1[modify_object]
D --> D2[group_objects]
D --> D3[ungroup_objects]
D --> D4[duplicate_objects]
D --> D5[align_objects]
D --> D6[set_z_order]
D --> D7[move_to_layer]
E --> E1[manage_layers]
F --> F1[create_document]
F --> F2[open_document]
F --> F3[save_document]
F --> F4[close_document]
G --> G1[manage_swatches]
G --> G2[replace_color]
G --> G3[assign_color_profile]
```
### Relationship with Coordinate Systems
All Modify Tools automatically adapt to the document's coordinate system, which is auto-detected based on the document type:
| Document Type | Coordinate System | Origin | Y-axis Direction |
|---------------|-------------------|--------|------------------|
| CMYK / Print | `document` | Bottom-left | Up |
| RGB / Web | `artboard-web` | Top-left of artboard | Down |
Source: [README.md - Coordinate System](README.md)
---
## Shape Creation Tools
### create_rectangle
Creates a rectangle shape in the active document. Supports rounded corners through optional parameters.
**Key Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `x` | number | X position of the rectangle |
| `y` | number | Y position of the rectangle |
| `width` | number | Width of the rectangle |
| `height` | number | Height of the rectangle |
| `cornerRadius` | number | Optional corner radius for rounded rectangles |
**Usage Example:**
```typescript
// Create a basic rectangle
await create_rectangle({
x: 100,
y: 100,
width: 200,
height: 150
});
// Create a rounded rectangle
await create_rectangle({
x: 100,
y: 100,
width: 200,
height: 150,
cornerRadius: 20
});
```
Source: [src/tools/modify/create-rectangle.ts](src/tools/modify/create-rectangle.ts)
### create_ellipse
Creates an ellipse shape in the active document.
**Key Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `x` | number | X position of the ellipse center |
| `y` | number | Y position of the ellipse center |
| `radiusX` | number | Horizontal radius |
| `radiusY` | number | Vertical radius |
### create_line
Creates a line segment between two points.
**Key Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `startX` | number | Starting X coordinate |
| `startY` | number | Starting Y coordinate |
| `endX` | number | Ending X coordinate |
| `endY` | number | Ending Y coordinate |
### create_path
Creates a custom path with Bezier curve handles for complex shapes.
**Key Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `pathData` | string | SVG path data string defining the shape |
---
## Text Creation Tools
### create_text_frame
Creates a text frame that can be either point text (single line) or area text (paragraph text within bounds).
**Key Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `x` | number | X position |
| `y` | number | Y position |
| `contents` | string | The text content to display |
| `textType` | "point" \| "area" | Type of text frame |
| `width` | number | Width (required for area text) |
| `height` | number | Height (required for area text) |
| `fontSize` | number | Font size in points |
| `fontFamily` | string | Font family name |
| `fontStyle` | string | Font style (Bold, Italic, etc.) |
| `justification` | string | Text alignment |
| `lineSpacing` | number | Line height/spacing |
Source: [src/tools/modify/create-text-frame.ts](src/tools/modify/create-text-frame.ts)
---
## Object Manipulation Tools
### modify_object
Modifies properties of an existing object. This is a versatile tool that can update fill, stroke, position, size, and other attributes of any selected or referenced object.
**Modifiable Properties:**
| Property Category | Attributes |
|-------------------|------------|
| Position | `x`, `y`, `width`, `height` |
| Fill | `fillColor`, `fillPattern`, `fillGradient` |
| Stroke | `strokeColor`, `strokeWidth`, `strokeCap`, `strokeJoin` |
| Transform | `rotation`, `shear`, `flip` |
| Appearance | `opacity`, `blendMode` |
**Usage Example:**
```typescript
await modify_object({
target: "object-uuid",
properties: {
fillColor: "#FF5733",
strokeColor: "#000000",
strokeWidth: 2,
opacity: 0.8
}
});
```
Source: [src/tools/modify/group-objects.ts](src/tools/modify/group-objects.ts)
### duplicate_objects
Creates a copy of specified objects with an optional positional offset.
**Key Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `sourceIds` | string[] | Array of object UUIDs to duplicate |
| `offsetX` | number | Horizontal offset for the copy |
| `offsetY` | number | Vertical offset for the copy |
### align_objects
Aligns and distributes multiple objects relative to each other or to a container.
**Alignment Options:**
| Option | Description |
|--------|-------------|
| `alignHorizontal` | Left, Center, Right |
| `alignVertical` | Top, Center, Bottom |
| `distributeHorizontal` | Equal horizontal spacing |
| `distributeVertical` | Equal vertical spacing |
Source: [src/tools/modify/align-objects.ts](src/tools/modify/align-objects.ts)
### set_z_order
Changes the stacking order of objects within their layer.
**Options:**
| Value | Description |
|-------|-------------|
| `front` | Move to front of layer |
| `back` | Move to back of layer |
| `forward` | Move one position forward |
| `backward` | Move one position backward |
### move_to_layer
Transfers objects from their current layer to a specified target layer.
**Key Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `objectIds` | string[] | UUIDs of objects to move |
| `targetLayer` | string | Name or UUID of destination layer |
---
## Grouping Tools
### group_objects
Combines multiple objects into a group. Supports clipping masks for advanced composition.
**Key Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `objectIds` | string[] | Array of object UUIDs to group |
| `createClippingMask` | boolean | Optional flag to create a clipping mask group |
Source: [src/tools/modify/group-objects.ts](src/tools/modify/group-objects.ts)
### ungroup_objects
Separates a group into its constituent child objects.
**Key Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `groupId` | string | UUID of the group to ungroup |
---
## Layer Management Tools
### manage_layers
Provides comprehensive layer operations including creation, renaming, visibility control, locking, reordering, and deletion.
**Operations:**
| Operation | Description |
|-----------|-------------|
| `add` | Create a new layer |
| `rename` | Change layer name |
| `delete` | Remove a layer |
| `show` / `hide` | Toggle layer visibility |
| `lock` / `unlock` | Toggle layer editability |
| `move` | Reorder layer position |
| `merge` | Combine layers |
**Key Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `operation` | string | The action to perform |
| `layerName` | string | Name of the layer |
| `targetLayer` | string | Optional target for move/merge operations |
Source: [src/tools/modify/manage-layers.ts](src/tools/modify/manage-layers.ts)
---
## Document Operations
### create_document
Creates a new Illustrator document with specified dimensions and color mode.
**Key Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `width` | number | Document width in points |
| `height` | number | Document height in points |
| `colorMode` | "RGB" \| "CMYK" | Color mode for the document |
| `name` | string | Document name |
**Example - Creating a Full HD document:**
```typescript
await create_document({
width: 1920,
height: 1080,
colorMode: "RGB",
name: "Web Banner"
});
```
Source: [src/tools/modify/create-document.ts](src/tools/modify/create-document.ts)
### open_document
Opens an existing Illustrator document from a file path.
**Key Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `filePath` | string | Full path to the document |
### save_document
Saves or performs a save-as operation on the active document.
**Key Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `filePath` | string | Optional path for save-as |
| `options` | object | Save options (format-specific) |
Source: [src/tools/modify/save-document.ts](src/tools/modify/save-document.ts)
### close_document
Closes the active document with optional save prompt handling.
---
## Color Management Tools
### manage_swatches
Manages color swatches in the document's Swatches panel.
**Operations:**
| Operation | Description |
|-----------|-------------|
| `add` | Add a new swatch |
| `remove` | Delete a swatch |
| `rename` | Change swatch name |
| `list` | Get all swatches |
Source: [src/tools/modify/manage-swatches.ts](src/tools/modify/manage-swatches.ts)
### replace_color
Finds and replaces colors throughout the document with configurable tolerance for similar colors.
**Key Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `sourceColor` | string | Color to find (hex, RGB, CMYK) |
| `targetColor` | string | Replacement color |
| `tolerance` | number | Similarity threshold (0-100) |
### assign_color_profile
Assigns (tags) a color profile to the document without converting color values.
---
## Utility Operations
### convert_to_outlines
Converts text characters to vector paths (outlines), ensuring consistent rendering regardless of font availability.
**Use Cases:**
- Preparing files for print production
- Ensuring exact character shapes
- Removing font dependencies
**Note:** This operation is irreversible. Always confirm before converting.
### place_image
Places an image file as either a linked or embedded object.
**Key Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `filePath` | string | Path to the image file |
| `x` | number | X position |
| `y` | number | Y position |
| `width` | number | Display width |
| `height` | number | Display height |
| `link` | boolean | Whether to link (true) or embed (false) |
### resize_for_variation
Creates proportional size variations from a source artboard.
**Key Parameters:**
| Parameter | Type | Description |
|-----------|------|-------------|
| `sourceArtboard` | string | UUID of source artboard |
| `scaleFactors` | number[] | Array of scale percentages |
---
## Workflow Integration
The Modify Tools work in conjunction with Read Tools to enable intelligent modifications:
```mermaid
graph LR
A[Read Tools] --> B[Analyze Current State]
B --> C[Determine Required Changes]
C --> D[Modify Tools]
D --> E[Execute Operations]
E --> F[Read Tools]
F --> G[Verify Results]
```
### Typical Workflow Pattern
1. **Read** current document state using Read Tools
2. **Plan** modifications based on requirements
3. **Execute** Modify Tools in appropriate order
4. **Verify** changes using Read Tools
5. **Export** final result using Export Tools
---
## Coordinate System Handling
All Modify Tools automatically handle coordinate system conversion based on document type:
```mermaid
graph TD
A[Document Type Detected] --> B{CMYK or RGB?}
B -->|CMYK / Print| C[Use document coordinate system]
B -->|RGB / Web| D[Use artboard-web coordinate system]
C --> E[Origin: Bottom-left]
D --> F[Origin: Top-left]
E --> G[Calculate Absolute Position]
F --> G
```
For RGB documents, the `convert_coordinate` tool can manually convert between coordinate systems when needed.
---
## Error Handling
The Modify Tools implement robust error handling for common scenarios:
| Scenario | Handling |
|----------|----------|
| Invalid object UUID | Return error with suggestion to verify object exists |
| Out-of-bounds coordinates | Clamp to document bounds or return warning |
| Unsupported color format | Attempt auto-conversion or return error |
| Layer operation on locked layer | Return error with unlock suggestion |
| File access permission denied | Return specific error for save/open operations |
---
## Known Limitations
| Limitation | Details |
|------------|---------|
| Live Effects | Drop shadow and other effect parameters can be detected but not read |
| Color Profiles | Only profile assignment available; full conversion not supported |
| Bleed Settings | Cannot read bleed settings (API limitation) |
| WebP Export | Not supported; use PNG or SVG instead |
Source: [README.md - Known Limitations](README.md)
---
## Quick Reference
| Tool Category | Tools |
|---------------|-------|
| Shape Creation | `create_rectangle`, `create_ellipse`, `create_line`, `create_path` |
| Text | `create_text_frame`, `convert_to_outlines` |
| Object Manipulation | `modify_object`, `duplicate_objects`, `align_objects`, `set_z_order`, `move_to_layer` |
| Grouping | `group_objects`, `ungroup_objects` |
| Layers | `manage_layers` |
| Document | `create_document`, `open_document`, `save_document`, `close_document` |
| Color | `manage_swatches`, `replace_color`, `assign_color_profile` |
| Media | `place_image`, `resize_for_variation` |
---
## See Also
- **Read Tools** - Tools for inspecting document content
- **Export Tools** - Tools for exporting documents to various formats
- **Utility Tools** - Preflight, text consistency, and workflow configuration
---
## Export Tools
### Related Pages
Related topics: [Read Tools](#read-tools), [Modify Tools](#modify-tools)
Relevant source files
The following source files were used to generate this page:
- [src/tools/export/export.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export.ts)
- [src/tools/export/export-pdf.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export-pdf.ts)
- [src/tools/registry.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/registry.ts)
- [server.json](https://github.com/ie3jp/illustrator-mcp-server/blob/main/server.json)
- [manifest.json](https://github.com/ie3jp/illustrator-mcp-server/blob/main/manifest.json)
# Export Tools
The Export Tools module provides capabilities for exporting Adobe Illustrator documents and artwork to various file formats suitable for web, print, and digital distribution. This module consists of two primary tools: `export` for raster and vector formats (SVG, PNG, JPG), and `export_pdf` for print-ready PDF production with professional prepress features.
## Overview
Export Tools are classified under Phase 3 of the illustrator-mcp-server architecture, focusing on export operations and print-oriented reading capabilities. These tools enable Claude to transform Illustrator documents into standardized output formats while maintaining design integrity and supporting industry-standard print production workflows.
| Tool | Primary Use Case | Formats Supported |
|------|------------------|-------------------|
| `export` | Web assets, screen output, image formats | SVG, PNG, JPG |
| `export_pdf` | Print production, prepress workflows | PDF with presets |
Source: [src/tools/registry.ts:9-10](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/registry.ts)
## Architecture
### Component Interaction
```mermaid
flowchart TD
subgraph Server["illustrator-mcp-server"]
ExportTool["export tool"]
ExportPdfTool["export_pdf tool"]
end
subgraph Illustrator["Adobe Illustrator"]
JSX["JSX Script\n(ExtendScript)"]
Document["Active Document"]
Artboards["Artboards Collection"]
end
ExportTool -->|generates| ExportJSX["script-{uuid}.jsx"]
ExportPdfTool -->|generates| PdfJSX["script-{uuid}.jsx"]
ExportJSX -->|executes| Illustrator
PdfJSX -->|executes| Illustrator
Illustrator -->|writes| ResultFile["result-{uuid}.json"]
ResultFile -->|reads| Server
Document -->|exports to| SVG["SVG File"]
Document -->|exports to| PNG["PNG File"]
Document -->|exports to| PDF["PDF File"]
```
### Export Workflow Sequence
```mermaid
sequenceDiagram
participant Client as Claude/Client
participant Server as MCP Server
participant AI as Adobe Illustrator
Client->>Server: Request export (format, options)
Server->>Server: Generate UUID
Server->>Server: Create params-{uuid}.json
Server->>Server: Create script-{uuid}.jsx
Server->>Server: Execute via osascript/PS
rect rgb(200, 220, 240)
Note over AI: Illustrator executes JSX script
AI->>AI: Load parameters
AI->>AI: Open/access document
AI->>AI: Apply export settings
AI->>AI: Write output file
AI->>AI: Write result-{uuid}.json
end
Server->>Server: Read result-{uuid}.json
Server->>Client: Return export result
alt Verification Required
Server->>Server: Check file existence
alt File not created
Server->>Client: Error with path details
end
end
```
## Export Tool (`export`)
The `export` tool handles conversion of Illustrator content to web-friendly and raster formats. It supports exporting by artboard, selection, or specific object UUID.
### Tool Registration
```typescript
server.registerTool(
'export',
{
title: 'Export',
description: 'Export objects, groups, artboards...',
inputSchema: {
// Parameters defined in source
}
}
);
```
Source: [src/tools/export/export.ts:55-60](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export.ts)
### Supported Formats
| Format | Use Case | Color Support | Transparency |
|--------|----------|---------------|--------------|
| SVG | Web vector graphics, scalable icons | RGB/CMYK | Preserved |
| PNG | Web images with transparency | RGB/RGBA | Preserved |
| JPG | Compressed photographic output | RGB | Not supported |
### Export Options
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `format` | string | Yes | Output format: `svg`, `png`, `jpg` |
| `output_path` | string | No | Output file path. Auto-generates in document directory or ~/Desktop for unsaved documents |
| `artboard_index` | number | No | Zero-based artboard index for multi-artboard documents |
| `scale` | number | No | Scale factor for raster exports (PNG/JPG) |
| `dpi` | number | No | Target DPI for raster exports (default: 72) |
### Raster Export Details
For PNG and JPG exports, the effective DPI is calculated by multiplying the specified DPI by the scale factor:
```json
{
"success": true,
"output_path": "/path/to/output.png",
"format": "png",
"dpi": 144,
"scale": 2
}
```
Source: [src/tools/export/export.ts:42-45](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export.ts)
### SVG Export Behavior
The SVG export includes special handling for artboard-named files:
1. When exporting an artboard with format `svg` and an `artboard_index` is specified
2. The output filename follows pattern: `{baseName}_{artboardName}.svg`
3. Artboard names have spaces replaced with hyphens
Example:
- Document: `design.ai` in `/output/`
- Artboard: `hero section`
- Output: `/output/design_hero-section.svg`
Source: [src/tools/export/export.ts:18-28](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export.ts)
### Verification and Error Handling
The tool performs post-export verification:
```typescript
var finalFile = new File(actualPath);
if (!finalFile.exists) {
writeResultFile(RESULT_PATH, {
error: true,
message: "Export completed but output file was not created. The path may not be writable: " + outputPath
});
}
```
Source: [src/tools/export/export.ts:46-48](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export.ts)
## Export PDF Tool (`export_pdf`)
The `export_pdf` tool generates print-ready PDF files with comprehensive prepress options including crop marks, bleed settings, and PDF preset support.
### Tool Registration
```typescript
server.registerTool(
'export_pdf',
{
title: 'Export PDF',
description: 'Export print-ready PDF. Note: Illustrator will be activated (brought to foreground) during execution.',
inputSchema: {
output_path: z.string().optional(),
preset: z.string().optional(),
options: z.object({...})
}
}
);
```
Source: [src/tools/export/export-pdf.ts:54-68](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export-pdf.ts)
### PDF Export Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `output_path` | string | No | Output file path. Auto-generates in document directory or ~/Desktop |
| `preset` | string | No | PDF preset name (e.g., `"[PDF/X-4:2008]"`) |
| `options.trim_marks` | boolean | No | Add trim marks to the export |
| `options.marks_style` | enum | No | Trim mark style: `japanese` (double-line) or `roman` (single-line) |
| `options.trim_mark_weight` | enum | No | Trim mark weight: `"0.125"`, `"0.25"`, `"0.5"` (in points) |
| `options.registration_marks` | boolean | No | Include registration marks |
| `options.color_bars` | boolean | No | Include color bars |
| `options.page_information` | boolean | No | Include page information |
### Japanese Crop Marks
The PDF export includes specialized handling for Japanese crop marks. When `marks_style` is set to `japanese`, the system:
1. Generates Japanese crop marks using the Illustrator TrimMark command
2. Creates marks as document paths for reliable rendering
3. Removes marks after PDF export via undo operation
4. Includes a note in the result indicating this behavior
```typescript
if (writeResult.japanese_marks_note) {
result.japanese_marks_note = "Japanese crop marks were generated as document paths via TrimMark command for reliable rendering, then removed after export.";
}
```
Source: [src/tools/export/export-pdf.ts:21-23](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export-pdf.ts)
### PDF Presets
Common PDF presets supported by Illustrator include:
| Preset | Standard | Use Case |
|--------|----------|----------|
| `[PDF/X-1a:2001]` | PDF/X-1a | Print production with strict requirements |
| `[PDF/X-4:2008]` | PDF/X-4 | Modern print workflows with transparency |
| `[Press Quality]` | General | High-quality print output |
| `[Smallest File Size]` | General | Web delivery |
### PDF Export Result
Successful PDF export returns:
```json
{
"success": true,
"output_path": "/path/to/document.pdf",
"format": "pdf"
}
```
### Error Handling
PDF export errors include line number information for debugging:
```typescript
catch (e) {
writeResultFile(RESULT_PATH, {
error: true,
message: "PDF export failed: " + e.message,
line: e.line
});
}
```
Source: [src/tools/export/export-pdf.ts:30-32](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export-pdf.ts)
## Coordinate System Considerations
Export tools automatically handle coordinate system differences based on document color mode:
| Document Type | Coordinate System | Origin | Y-Axis Direction |
|---------------|-------------------|--------|------------------|
| CMYK/Print | `document` | Bottom-left | Up |
| RGB/Web | `artboard-web` | Top-left of artboard | Down |
This affects how coordinates are interpreted during export, particularly for SVG output where coordinate transformation may be required.
## Integration with Preflight
Export tools are commonly used in conjunction with the preflight check tool for print workflows:
```mermaid
flowchart LR
Preflight["preflight_check"] --> |Validates| Doc["Document"]
Doc --> |If compliant| ExportPDF["export_pdf"]
ExportPDF --> |Generates| PrintReady["Print-Ready PDF"]
Preflight --> |If issues found| Review["Manual Review Required"]
```
The typical print workflow:
1. Run `preflight_check` with target profile (e.g., `x1a`)
2. Review compliance errors and warnings
3. Fix issues in Illustrator
4. Export using `export_pdf` with appropriate settings
## Usage Examples
### Export Artboard as SVG
```
You: Export the hero artboard as SVG with outlined text
Claude: → get_artboards → convert_to_outlines → export
```
### Export Selection as PNG
```json
{
"format": "png",
"output_path": "/output/banner.png",
"scale": 2,
"dpi": 144
}
```
### Export Print-Ready PDF
```json
{
"preset": "[PDF/X-4:2008]",
"options": {
"trim_marks": true,
"marks_style": "japanese",
"registration_marks": true,
"color_bars": true
}
}
```
## Limitations and Notes
| Feature | Limitation | Workaround |
|---------|------------|------------|
| Illustrator activation | `export_pdf` brings Illustrator to foreground | User should close other apps if needed |
| Bleed settings | Cannot be controlled directly via API | Use PDF presets that include bleed |
| Font embedding mode | Full/subset mode not directly controllable | Use PDF presets |
| Size variations | Only proportional scaling supported | Manual text adjustment may be needed |
Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
## Related Tools
| Tool Category | Tools |
|---------------|-------|
| Read Tools | `get_artboards`, `get_document_structure` |
| Modify Tools | `convert_to_outlines` |
| Utility | `preflight_check`, `check_text_consistency` |
---
## Utility Tools
### Related Pages
Related topics: [Read Tools](#read-tools)
Relevant source files
The following source files were used to generate this page:
- [src/tools/utility/preflight-check.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/utility/preflight-check.ts)
- [src/tools/utility/check-text-consistency.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/utility/check-text-consistency.ts)
- [src/tools/utility/set-workflow.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/utility/set-workflow.ts)
- [src/tools/utility/set-illustrator-version.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/utility/set-illustrator-version.ts)
# Utility Tools
Utility Tools in the illustrator-mcp-server provide essential辅助功能 for document validation, workflow configuration, and system integration. These tools enable quality assurance workflows, coordinate system management, and environment setup essential for reliable Illustrator automation.
## Overview
The Utility Tools category encompasses three primary tools that support document preparation, validation, and configuration:
| Tool | Purpose |
|------|---------|
| `preflight_check` | Comprehensive pre-press quality validation |
| `check_text_consistency` | Text content validation and consistency analysis |
| `set_workflow` | Coordinate system and workflow mode configuration |
These tools serve as the foundation for print-ready production workflows, ensuring documents meet industry standards before export or submission.
## Preflight Check
The `preflight_check` tool performs automated pre-press validation to identify issues that could compromise print quality or PDF/X compliance.
### Purpose and Scope
The preflight check analyzes documents for print-critical issues including color space violations, missing assets, resolution problems, and PDF/X compliance failures. It provides a structured report with severity classification to prioritize fixes.
Source: [README.md](README.md)
### Supported Checks
The tool performs the following validations:
| Check Category | Detects |
|----------------|---------|
| Color Mode | RGB colors in CMYK documents |
| Links | Broken or missing linked images |
| Resolution | Images below minimum DPI threshold |
| Overprint | White objects set to overprint |
| Transparency | Transparency interactions with overprint |
| PDF/X | Profile compliance (X-1a, X-4) |
| Spot Colors | Unused or unexpected spot colors |
Source: [README.md](README.md)
### Parameters
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `target_pdf_profile` | string | No | - | Target PDF profile: `"x1a"` or `"x4"` |
| `min_dpi` | number | No | 300 | Minimum acceptable image resolution for print |
| `include_print_info` | boolean | No | false | Include detailed print-specific diagnostics |
Source: [src/tools/utility/preflight-check.ts](src/tools/utility/preflight-check.ts)
### Output Structure
The preflight check returns categorized results:
```typescript
interface PreflightResult {
critical: PreflightIssue[];
warnings: PreflightIssue[];
info: PreflightInfo[];
}
```
### PDF/X Compliance Profiles
| Profile | Characteristics | Transparency |
|---------|-----------------|--------------|
| PDF/X-1a | CMYK/spot only, no transparency, no layers | Prohibited |
| PDF/X-4 | Supports transparency and layers, ICC-based | Allowed |
Source: [README.md](README.md)
### Example Output
```
❌ PDF/X-1a compliance errors:
- Transparency on 3 objects (X-1a prohibits transparency)
- RGB colors found in 2 places (X-1a requires CMYK/spot only)
⚠ Warnings:
- 5 non-outlined fonts (embedding recommended)
- Image "photo_02.jpg" at 150dpi (300dpi recommended)
```
Source: [README.md](README.md)
## Check Text Consistency
The `check_text_consistency` tool validates text content to ensure documents are production-ready and free of placeholder or inconsistent text.
### Purpose and Scope
This tool detects common text issues in design documents: dummy/placeholder text that must be replaced, notation variations that indicate inconsistencies, and provides a complete text dump for LLM-driven analysis.
Source: [README.md](README.md)
### Detection Capabilities
| Detection Type | Description |
|----------------|-------------|
| Placeholder Text | Detects common placeholder patterns (Lorem ipsum, sample text) |
| Notation Variations | Identifies katakana/halfwidth/fullwidth inconsistencies |
| Full Text Listing | Exports all text content for external analysis |
Source: [plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md](plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md)
### Return Values
| Field | Type | Description |
|-------|------|-------------|
| `hasPlaceholder` | boolean | Whether placeholder text was detected |
| `placeholderMatches` | string[] | Array of detected placeholder patterns |
| `notationVariations` | NotationIssue[] | Array of notation inconsistencies |
| `allTexts` | TextItem[] | Complete listing of all text in document |
Source: [src/tools/utility/check-text-consistency.ts](src/tools/utility/check-text-consistency.ts)
### Workflow Integration
The tool integrates with the illustrator-preflight skill to provide LLM-driven deeper analysis:
```mermaid
flowchart TD
A[check_text_consistency] --> B[allTexts Array]
B --> C[LLM Analysis]
C --> D{Typo Detection}
C --> E{Version Mismatch}
C --> F{Terminology Check}
D --> G[Critical Issues]
E --> G
F --> G
```
Source: [plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md](plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md)
## Set Workflow
The `set_workflow` tool configures the coordinate system and workflow mode to override auto-detected settings.
### Purpose and Scope
The tool enables manual override of the automatic coordinate system detection, ensuring consistent behavior regardless of document type. This is essential when working with documents that have unconventional settings or when specific coordinate conventions are required.
Source: [README.md](README.md)
### Coordinate System Detection
The server automatically detects coordinate systems based on document type:
| Document Type | Coordinate System | Origin | Y Axis Direction |
|---------------|-------------------|--------|-------------------|
| CMYK / Print | `document` | Bottom-left | Up |
| RGB / Web | `artboard-web` | Top-left of artboard | Down |
Source: [README.md](README.md)
### Workflow Modes
| Mode | Use Case |
|------|----------|
| `web` | RGB documents, web assets, screen output |
| `print` | CMYK documents, print production, PDF export |
### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `mode` | string | Yes | Workflow mode: `"web"` or `"print"` |
### Behavior
When `set_workflow` is called:
1. The specified mode overrides auto-detection
2. All subsequent coordinate conversions use the configured system
3. Tools like `convert_coordinate` respect the active workflow mode
```mermaid
flowchart LR
A[Document Opens] --> B{User calls set_workflow?}
B -->|No| C[Auto-detect coordinate system]
B -->|Yes| D[Use specified mode]
C --> E[Return coordinates]
D --> E
```
Source: [src/tools/utility/set-workflow.ts](src/tools/utility/set-workflow.ts)
## Set Illustrator Version
The `set_illustrator_version` tool configures the target Illustrator version for script generation compatibility.
### Purpose and Scope
Different Illustrator versions support different scripting APIs and features. This tool ensures generated scripts target the correct version, preventing compatibility issues when working with legacy or specific version requirements.
Source: [src/tools/utility/set-illustrator-version.ts](src/tools/utility/set-illustrator-version.ts)
### Supported Versions
| Version | Script Engine | Notes |
|---------|---------------|-------|
| CC 2017+ | ExtendScript / UXP | Modern scripting support |
| Legacy | ExtendScript | Older version compatibility |
### Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `version` | string | Yes | Illustrator version string (e.g., "2024", "CC 2023") |
## Utility Tool Architecture
```mermaid
flowchart TB
subgraph "Utility Tools"
PC[preflight_check]
CTC[check_text_consistency]
SW[set_workflow]
SIV[set_illustrator_version]
end
subgraph "Supporting Infrastructure"
GSI[get_separation_info]
GOI[get_overprint_info]
CC[convert_coordinate]
end
PC --> GSI
PC --> GOI
PC --> CTC
SW --> CC
SIV --> PC
subgraph "Output"
Reports[Preflight Reports]
TextDump[Text Analysis]
Config[Workflow Config]
end
PC --> Reports
CTC --> TextDump
SW --> Config
```
## Integration with illustrator-preflight Skill
The Utility Tools are orchestrated by the `illustrator-preflight` skill for comprehensive pre-press workflows:
```mermaid
sequenceDiagram
participant User
participant Skill
participant Tools
User->>Skill: Run preflight check
Skill->>Tools: preflight_check
Skill->>Tools: get_overprint_info
Skill->>Tools: check_text_consistency
Tools-->>Skill: Results
Skill->>Skill: Analyze & Classify
Skill->>Tools: get_separation_info (conditional)
Tools-->>Skill: Plate info
Skill-->>User: Structured Report
```
Source: [plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md](plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md)
### Preflight Workflow Steps
The skill executes a 7-step comprehensive pre-press workflow:
| Step | Name | Actions |
|------|------|---------|
| 1 | Document | Get document info and structure |
| 2 | Preflight | Run preflight_check |
| 3 | Overprint | Run get_overprint_info |
| 4 | Separations | Run get_separation_info (if spot colors) |
| 5 | Images | Check image quality and resolution |
| 6 | Colors | Validate color space compliance |
| 7 | Text | Run check_text_consistency |
Source: [README.md](README.md)
## Common Usage Patterns
### Pre-Delivery Validation
```typescript
// Run comprehensive preflight before submission
const preflight = await preflight_check({
target_pdf_profile: "x1a",
min_dpi: 300
});
const overprint = await get_overprint_info();
const textCheck = await check_text_consistency();
```
### Workflow Configuration for Print
```typescript
// Configure for CMYK print workflow
await set_workflow({ mode: "print" });
// All subsequent operations use document coordinates
const coords = await convert_coordinate({
x: 100,
y: 100,
from: "artboard",
to: "document"
});
```
### Text Content Audit
```typescript
const textResult = await check_text_consistency();
// Check for placeholders
if (textResult.hasPlaceholder) {
console.log("Replace placeholder text:", textResult.placeholderMatches);
}
// LLM-driven analysis of all text
const allText = textResult.allTexts.map(t => t.content);
```
## Error Handling and Limitations
### Known Constraints
| Limitation | Details |
|------------|---------|
| Live Effects | Effect parameters can be detected but not read |
| Bleed Settings | Cannot be read due to Illustrator API limitation |
| Font Embedding | Embedding mode cannot be controlled directly |
Source: [README.md](README.md)
### Best Practices
1. Always run `preflight_check` before print submission
2. Use `check_text_consistency` to catch placeholder text before delivery
3. Set workflow mode explicitly when working with mixed document types
4. Configure Illustrator version when targeting specific deployment environments
---
## Coordinate Systems
### Related Pages
Related topics: [Execution Flow](#execution-flow), [Modify Tools](#modify-tools)
Relevant source files
The following source files were used to generate this page:
- [src/tools/read/convert-coordinate.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/convert-coordinate.ts)
- [src/tools/session.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/session.ts)
# Coordinate Systems
Adobe Illustrator uses two distinct coordinate systems with different origins and Y-axis orientations. The illustrator-mcp-server provides unified coordinate handling that automatically detects the appropriate system based on the document type, while also allowing manual override when needed.
## Overview
Coordinate systems in Illustrator determine how positions are interpreted across the application. The illustrator-mcp-server abstracts the complexity of coordinate transformations, allowing AI assistants to work with positions in a consistent manner regardless of the underlying document configuration.
The server automatically detects which coordinate system is in use based on document properties and includes coordinate system information in all tool responses via the `coordinateSystem` field.
## Coordinate System Types
The illustrator-mcp-server supports two coordinate systems:
| System | Document Type | Origin | Y-Axis | Use Case |
|--------|--------------|--------|--------|----------|
| `document` | CMYK / Print | Bottom-left | Up | Traditional print design |
| `artboard-web` | RGB / Web | Top-left of artboard | Down | Web and digital design |
### Document Coordinate System
The `document` coordinate system uses Illustrator's native coordinate space:
- **Origin**: Bottom-left corner of the document
- **Y-Axis**: Positive values extend upward
- **Application**: CMYK documents, print workflows
- **Behavior**: Matches what print designers expect from traditional illustration software
This system is detected when the document color mode is set to CMYK.
### Artboard Web Coordinate System
The `artboard-web` coordinate system uses a web-style coordinate space:
- **Origin**: Top-left corner of the active artboard
- **Y-Axis**: Positive values extend downward
- **Application**: RGB documents, web and digital workflows
- **Behavior**: Matches browser and screen coordinate conventions
This system is detected when the document color mode is set to RGB.
## Auto-Detection Mechanism
The server automatically determines the appropriate coordinate system based on document properties. This detection happens on session start and when documents change.
```mermaid
graph TD
A[Document Open] --> B{Color Mode?}
B -->|CMYK| C[Use document System]
B -->|RGB| D[Use artboard-web System]
C --> E[Set coordinateSystem Field]
D --> E
E --> F[Cache Detection Result]
```
### Detection Signals
The auto-detection process analyzes multiple document signals:
| Signal | Purpose | Indicates CMYK | Indicates RGB |
|--------|---------|---------------|---------------|
| `colorMode` | Primary color space | "CMYK" | "RGB" |
| `rulerUnits` | Measurement system | mm, cm, inches | px |
| `rasterEffectResolution` | Output resolution | Lower DPI | Higher DPI |
| `colorProfile` | Color profile type | Print profiles | sRGB, display profiles |
Source: [src/tools/session.ts:40-55](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/session.ts)
### Detection Caching
To optimize performance, the auto-detection result is cached:
```typescript
// Cache key structure
autoDetectCache = {
documentId: string,
colorMode: string,
timestamp: number
}
```
Source: [src/tools/session.ts:20-35](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/session.ts)
The cache is invalidated when:
1. The document changes
2. The color mode changes
3. The artboard changes
4. Manual override via `set_workflow` is called
## Manual Override with set_workflow
When auto-detection does not produce the desired behavior, use the `set_workflow` tool to explicitly set the coordinate system:
```json
{
"tool": "set_workflow",
"parameters": {
"mode": "web"
}
}
```
### Available Workflow Modes
| Mode | Coordinate System | Effect |
|------|-------------------|--------|
| `web` | `artboard-web` | Forces web-style coordinates |
| `print` | `document` | Forces print-style coordinates |
| `auto` | (auto-detected) | Resets to auto-detection |
When `set_workflow` is called with a specific mode:
1. The auto-detection cache is bypassed
2. All subsequent coordinate operations use the specified system
3. The `coordinateSystem` field reflects the manually set value
## Coordinate Conversion
The `convert_coordinate` tool transforms points between coordinate systems within the active document.
### Tool Parameters
| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `point` | `{x: number, y: number}` | Yes | Point to convert |
| `from` | `enum` | Yes | Source system: "artboard" or "document" |
| `to` | `enum` | Yes | Destination system: "artboard" or "document" |
### Conversion Behavior
```typescript
// Internal mapping to Illustrator constants
const fromMap = {
"artboard": CoordinateSystem.ARTBOARDCOORDINATESYSTEM,
"document": CoordinateSystem.DOCUMENTCOORDINATESYSTEM
};
const toMap = {
"artboard": CoordinateSystem.ARTBOARDCOORDINATESYSTEM,
"document": CoordinateSystem.DOCUMENTCOORDINATESYSTEM
};
```
Source: [src/tools/read/convert-coordinate.ts:1-10](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/convert-coordinate.ts)
### Conversion Example
Converting a point from artboard (web) coordinates to document (Illustrator native) coordinates:
```json
{
"tool": "convert_coordinate",
"parameters": {
"point": { "x": 100, "y": 200 },
"from": "artboard",
"to": "document"
}
}
```
Response includes the converted coordinates and system identifiers:
```json
{
"x": 100,
"y": 868, // Y inverted based on artboard height
"from": "artboard",
"to": "document"
}
```
### Y-Axis Transformation
The conversion handles Y-axis inversion automatically:
| From System | To System | Y Transformation |
|-------------|-----------|------------------|
| `artboard-web` | `document` | `y = artboardHeight - y` |
| `document` | `artboard-web` | `y = artboardHeight - y` |
The artboard height is obtained from the active artboard rectangle to ensure accurate transformation.
## Coordinate System in Tool Responses
All tool responses include a `coordinateSystem` field indicating which system is currently active:
```json
{
"success": true,
"uuid": "abc123",
"coordinateSystem": "artboard-web"
}
```
This field helps AI assistants interpret position values correctly and choose appropriate coordinate systems for subsequent operations.
## Workflow Detection Logic
The `detectWorkflow` function in session.ts determines the appropriate coordinate system based on document signals:
```typescript
export function detectWorkflow(signals: DocumentSignals): WorkflowHint {
const { colorMode, rulerUnits, rasterEffectResolution, colorProfile } = signals;
const isCMYK = colorMode === 'CMYK';
const isRGB = colorMode === 'RGB';
const isPixelUnit = rulerUnits === 'px';
const isPrintUnit = ['mm', 'cm'].includes(rulerUnits);
// Decision logic based on signals
// Returns WorkflowHint with detectedWorkflow and recommendedCoordinateSystem
}
```
Source: [src/tools/session.ts:40-65](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/session.ts)
The detection considers:
- **Primary signal**: Color mode (CMYK vs RGB)
- **Supporting signals**: Ruler units, raster resolution, color profile
- **Consistency check**: Verify all signals align
## Best Practices
### When to Use `document` System
- Working with CMYK print documents
- Creating content for physical output
- Using print-specific measurements (mm, cm, inches)
### When to Use `artboard-web` System
- Working with RGB web documents
- Creating content for digital display
- Using pixel-based measurements
### When to Override with `set_workflow`
- Document auto-detection fails
- Mixed workflow (e.g., RGB document for print preview)
- Specific AI task requirements
### Coordinate Conversion Strategy
1. Determine the current coordinate system from tool response
2. Use matching coordinates for the active system
3. Convert when bridging between systems
4. Cache conversion results for repeated operations
---
## Development Guide
### Related Pages
Related topics: [Getting Started](#getting-started)
Relevant source files
The following source files were used to generate this page:
- [tsconfig.json](https://github.com/ie3jp/illustrator-mcp-server/blob/main/tsconfig.json)
- [package.json](https://github.com/ie3jp/illustrator-mcp-server/blob/main/package.json)
- [src/tools/registry.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/registry.ts)
- [src/prompts/registry.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/prompts/registry.ts)
- [manifest.json](https://github.com/ie3jp/illustrator-mcp-server/blob/main/manifest.json)
- [server.json](https://github.com/ie3jp/illustrator-mcp-server/blob/main/server.json)
# Development Guide
This document serves as the comprehensive development guide for **illustrator-mcp-server**, a Model Context Protocol (MCP) server that enables AI assistants like Claude to read, manipulate, and export Adobe Illustrator design data. The server provides 26 tools for automation and inspection of Illustrator documents across macOS and Windows platforms.
## Project Overview
The illustrator-mcp-server acts as a bridge between AI assistants and Adobe Illustrator's ExtendScript scripting engine. It leverages the MCP SDK to expose Illustrator functionality as discrete tools that AI can invoke through natural language commands.
### Key Characteristics
| Attribute | Value |
|-----------|-------|
| Platform | macOS, Windows |
| Runtime | Node.js ≥20.0.0 |
| License | MIT |
| Repository | github.com/ie3jp/illustrator-mcp-server |
| Current Version | 1.2.6 (server.json), 1.2.10 (manifest.json) |
| Transport | stdio |
## Project Structure
The repository follows a standard Node.js TypeScript project structure with MCP-specific components:
```
illustrator-mcp-server/
├── src/
│ ├── tools/
│ │ └── registry.ts # Tool registration and definition
│ └── prompts/
│ └── registry.ts # Prompt templates for AI interaction
├── dist/ # Compiled JavaScript output
├── test/
│ └── e2e/
│ └── smoke-test.ts # End-to-end smoke tests
├── manifest.json # MCP extension manifest
├── server.json # MCP server configuration
├── package.json # npm package configuration
└── tsconfig.json # TypeScript configuration
```
## Development Environment Setup
### Prerequisites
| Requirement | Version | Purpose |
|-------------|---------|---------|
| Node.js | ≥20.0.0 | Server runtime |
| npm | Latest | Package management |
| Adobe Illustrator | Any supported version | Target application |
| TypeScript | 6.0.2+ | Source compilation |
### Installation
```bash
git clone https://github.com/ie3jp/illustrator-mcp-server.git
cd illustrator-mcp-server
npm install
```
The `npm install` command installs both runtime dependencies and development dependencies as defined in package.json.
Source: [package.json:1-50]()
### Build Process
```bash
npm run build
```
The build command compiles TypeScript source files from `src/` to JavaScript in the `dist/` directory. The pre-publish lifecycle hook ensures the build completes before any publish operation:
```json
"prepublishOnly": "npm run build"
```
Source: [package.json:14]() [package.json:18]()
## TypeScript Configuration
The project uses TypeScript for type safety and modern JavaScript features. The `tsconfig.json` defines compilation targets and module resolution:
### Key Configuration Options
| Option | Value | Purpose |
|--------|-------|---------|
| Target | ES2022+ | Modern JavaScript features |
| Module | CommonJS or ESNext | Module system compatibility |
| Strict | Enabled | Type safety enforcement |
| OutDir | dist/ | Compilation output directory |
| RootDir | src/ | Source root directory |
## Tool Registration System
The MCP server exposes tools through a registration system defined in `src/tools/registry.ts`. Each tool corresponds to a specific Illustrator operation.
### Tool Categories
The server provides 26 tools organized into functional categories:
| Category | Count | Examples |
|----------|-------|----------|
| Document | 3 | `get_document_info`, `get_artboards`, `get_layers` |
| Object | 11 | `create_rectangle`, `create_text_frame`, `modify_object` |
| Text | 2 | `list_text_frames`, `get_text_frame_detail` |
| Style | 4 | `create_gradient`, `create_symbol`, `get_effects` |
| Asset | 3 | `get_images`, `get_symbols`, `get_selection` |
| Style Guide | 1 | `extract_design_tokens`, `place_style_guide` |
| Export | 2 | `export`, `export_pdf` |
| Utility | 3 | `preflight_check`, `check_text_consistency`, `set_workflow` |
| Edit | 1 | `undo` |
Source: [manifest.json:15-30]()
### Tool Registration Flow
```mermaid
graph TD
A[Start] --> B[Load tool definitions from registry.ts]
B --> C[Parse ExtendScript handlers]
C --> D[Register with MCP SDK]
D --> E[Server starts listening for requests]
E --> F[Tool invocation received]
F --> G[Execute ExtendScript in Illustrator]
G --> H[Return JSON response to AI]
```
### Adding New Tools
To add a new tool to the server:
1. **Define the tool handler** in the appropriate source file within `src/`
2. **Register the tool** in `src/tools/registry.ts` with:
- Tool name and description
- Parameter schema (JSON Schema format)
- ExtendScript handler function
3. **Update manifest.json** if exposing through MCP extension format
## Prompt System
The prompt registry (`src/prompts/registry.ts`) contains templates that guide the AI's behavior when interacting with Illustrator through the MCP server. Prompts are particularly important for:
- **Preflight workflows**: Structured validation steps for print-ready documents
- **Design token extraction**: Systematic extraction of design system values
- **Text consistency checking**: Pattern recognition for placeholder and inconsistency detection
### Preflight Prompt Structure
The preflight skill uses a structured prompt approach:
```mermaid
graph LR
A[Start Preflight] --> B[Step 1: Asset Checks]
B --> C[Step 2: Text Checks]
C --> D[Step 3: Report Generation]
D --> E[Critical Issues]
D --> F[Warnings]
D --> G[Info Items]
```
Source: [plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md:1-50]()
## Testing
### Unit Tests
```bash
npm test
```
The project uses Vitest for unit testing. Test files are located alongside source files with the `.test.ts` or `.spec.ts` extension.
Source: [package.json:15]()
### End-to-End Smoke Tests
```bash
npx tsx test/e2e/smoke-test.ts
```
The E2E smoke test requires Adobe Illustrator to be running. It performs:
| Phase | Description |
|-------|-------------|
| Document creation | Creates RGB and CMYK test documents |
| Object placement | Inserts test objects of various types |
| Tool coverage | Tests all 26 registered tools |
| Coordinate detection | Validates coordinate system auto-detection |
| Cleanup | Automatically removes test documents |
**Test Statistics:**
- **182 test cases** across **10 phases**
- Validates all tool registrations
- Confirms coordinate system behavior for different document types
Source: [README.md:1-50]()
### Verification with MCP Inspector
```bash
npx @modelcontextprotocol/inspector npx illustrator-mcp-server
```
The MCP Inspector tool allows verification of the server configuration and tool registration without running a full AI client.
## Build Outputs
### Standard Build
```bash
npm run build
```
Outputs compiled JavaScript to the `dist/` directory:
- `dist/index.js` - Main server entry point
- `dist/bundle.cjs` - CommonJS bundle for MCP packaging
### MCP Extension Package
```bash
npm run pack:mcpb
```
This command:
1. Builds the project
2. Installs production dependencies only (`--omit=dev`)
3. Packs the server using the Anthropic MCPB packager
4. Reinstalls development dependencies
Output: `illustrator-mcp-server.mcpb` - Distributable extension package for Claude Desktop
Source: [package.json:19]()
## Release Process
```bash
npm run release
```
The release pipeline executes:
1. `npm run build` - Compile TypeScript
2. `npm test` - Run unit tests
3. `git push` - Push to remote
4. `git push --tags` - Publish version tags
Source: [package.json:20]()
## Server Configuration
### MCP Server Manifest
The `server.json` defines the MCP server metadata:
```json
{
"name": "io.github.ie3jp/illustrator-mcp-server",
"description": "Read, manipulate, and export Adobe Illustrator design data. 26 tools. macOS | Windows.",
"version": "1.2.6",
"packages": [{
"identifier": "illustrator-mcp-server",
"version": "1.2.6",
"transport": { "type": "stdio" }
}]
}
```
Source: [server.json:1-25]()
### Claude Desktop Integration
For Claude Desktop integration, add to the MCP configuration:
```json
{
"mcpServers": {
"illustrator": {
"command": "npx",
"args": ["illustrator-mcp-server"]
}
}
}
```
> **Note:** If using a Node.js version manager (nvm, mise, fnm), use the full path to npx:
> ```json
> "command": "/full/path/to/npx"
> ```
## Dependencies
### Runtime Dependencies
| Package | Version | Purpose |
|---------|---------|---------|
| @modelcontextprotocol/sdk | ^1.27.1 | MCP protocol implementation |
| p-limit | ^7.3.0 | Concurrent operation limiting |
Source: [package.json:33-35]()
### Development Dependencies
| Package | Version | Purpose |
|---------|---------|---------|
| typescript | ^6.0.2 | TypeScript compiler |
| vitest | ^4.1.1 | Unit testing framework |
| tsx | ^4.21.0 | TypeScript execution |
| @types/node | ^25.5.0 | Node.js type definitions |
Source: [package.json:37-41]()
## ExtendScript Integration
The server communicates with Adobe Illustrator via ExtendScript (JavaScript for Adobe applications). Each tool maps to one or more ExtendScript commands that execute within Illustrator's scripting environment.
### macOS Implementation
On macOS, the server uses AppleScript to invoke Illustrator:
```applescript
tell application "Adobe Illustrator"
-- ExtendScript code executes here
end tell
```
### Windows Implementation
On Windows, the server uses PowerShell COM automation:
```powershell
$illustrator = New-Object -ComObject Illustrator.Application
```
Source: [README.md:80-90]()
## Known Development Constraints
| Constraint | Impact | Workaround |
|------------|--------|------------|
| Windows testing | Not yet tested on real hardware | Use macOS for initial development |
| Live effects | Parameters detectable but not readable | Manual verification required |
| Color profiles | Limited support | Document-level color space awareness |
| Font data | Limited access to font metadata | Use text extraction tools |
Source: [README.md:95-100]()
## Contributing
When contributing to the project:
1. **Follow TypeScript strict mode** - Enable all type checking options
2. **Add unit tests** for new tools in the `test/` directory
3. **Update manifest.json** if the tool count changes
4. **Document in SKILL.md** for skills that require structured prompts
5. **Test E2E smoke tests** before submitting pull requests
## License
The project is licensed under the MIT License. See the [LICENSE](https://github.com/ie3jp/illustrator-mcp-server/blob/main/LICENSE) file for full terms.
---
---
## Doramagic Pitfall Log
Project: ie3jp/illustrator-mcp-server
Summary: Found 8 potential pitfall items; 0 are high/blocking. Highest priority: configuration - 可能修改宿主 AI 配置.
## 1. configuration · 可能修改宿主 AI 配置
- Severity: medium
- Evidence strength: source_linked
- Finding: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- User impact: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。
- Guardrail action: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
- Evidence: capability.host_targets | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | host_targets=mcp_host, claude, claude_code
## 2. capability · 能力判断依赖假设
- Severity: medium
- Evidence strength: source_linked
- Finding: README/documentation is current enough for a first validation pass.
- User impact: 假设不成立时，用户拿不到承诺的能力。
- Suggested check: 将假设转成下游验证清单。
- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。
- Evidence: capability.assumptions | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | README/documentation is current enough for a first validation pass.
## 3. runtime · 来源证据：編集可能な Illustrator アートワークのための SVG インポート動作の明確化と改善
- Severity: medium
- Evidence strength: source_linked
- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：編集可能な Illustrator アートワークのための SVG インポート動作の明確化と改善
- User impact: 可能增加新用户试用和生产接入成本。
- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
- Evidence: community_evidence:github | cevd_c7b420ed6123436eb6d2b27f460dc2c8 | https://github.com/ie3jp/illustrator-mcp-server/issues/35 | 来源类型 github_issue 暴露的待验证使用条件。
## 4. maintenance · 维护活跃度未知
- Severity: medium
- Evidence strength: source_linked
- Finding: 未记录 last_activity_observed。
- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。
- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。
- Evidence: evidence.maintainer_signals | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | last_activity_observed missing
## 5. security_permissions · 下游验证发现风险项
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: 下游已经要求复核，不能在页面中弱化。
- Suggested check: 进入安全/权限治理复核队列。
- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。
- Evidence: downstream_validation.risk_items | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | no_demo; severity=medium
## 6. security_permissions · 存在评分风险
- Severity: medium
- Evidence strength: source_linked
- Finding: no_demo
- User impact: 风险会影响是否适合普通用户安装。
- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。
- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。
- Evidence: risks.scoring_risks | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | no_demo; severity=medium
## 7. maintenance · issue/PR 响应质量未知
- Severity: low
- Evidence strength: source_linked
- Finding: issue_or_pr_quality=unknown。
- User impact: 用户无法判断遇到问题后是否有人维护。
- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。
- Guardrail action: issue/PR 响应未知时，必须提示维护风险。
- Evidence: evidence.maintainer_signals | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | issue_or_pr_quality=unknown
## 8. maintenance · 发布节奏不明确
- Severity: low
- Evidence strength: source_linked
- Finding: release_recency=unknown。
- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。
- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。
- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。
- Evidence: evidence.maintainer_signals | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | release_recency=unknown