项目概述

illustrator-mcp-server 是一个开源的 Model Context Protocol（MCP）服务器，专门用于将 Adobe Illustrator 与人工智能助手（如 Claude Code）进行集成。该项目由 ie3jp 开发维护，旨在让设计师和开发者能够通过自然语言指令直接控制 Illustrator 的各项功能。 资料来源：manifest.json:1-20

通过这个 MCP 服务器，用户可以执行文本提取、SVG 和 PDF 导出、入稿前预检等操作，目前提供超过 26 种工具函数，覆盖了从文档创建、对象编辑到颜色管理等完整的设计工作流程。项目的设计理念是将 Illustrator 的专业功能以 AI 友好的方式暴露出来，使得人工智能能够像专业设计师一样与矢量图形软件进行交互。 资料来源：README.md:1-50

核心功能

主要能力

该服务器提供了四大类工具函数，总计超过 50 个操作命令，能够满足从简单的图形创建到复杂的印前检查等各种设计需求。核心项目括文档的读取与解析、图形对象的创建与修改、图像的导入导出以及高级的颜色管理和预检功能。 资料来源：README.md:50-100

项目特别注重印刷行业的工作流程支持，包括 CMYK 颜色管理、PDF/X 标准合规检查、裁切标记生成等专业功能。同时也照顾到网页设计场景，提供了 RGB 颜色模式和 Web 坐标系统的原生支持。这种双重支持使得同一套工具可以在不同的设计领域中灵活使用。 资料来源：README.md:100-150

坐标系统处理

项目的一个显著特点是智能坐标系统检测。对于 CMYK/印刷文档，系统使用 Illustrator 原生坐标系统，原点位于左下角，Y 轴向上。对于 RGB/网页文档，则使用艺术画板左上角为原点的网页坐标系，Y 轴向下。这种自动检测机制免去了用户手动配置的麻烦，同时也可以通过 set_workflow 工具强制指定工作模式。 资料来源：README.md:150-200

工具分类详解

读取工具（21个）

读取工具用于获取文档中的各类信息，从基础元数据到高级分析功能都有覆盖。

资料来源：README.md:200-280

修改工具（38个）

修改工具是创作功能的核心，支持创建各种图形对象、编辑现有元素以及管理文档结构。

资料来源：README.md:280-350

导出工具（2个）

导出功能专注于高质量输出，支持多种格式以满足不同用途的需求。

资料来源：README.md:350-380

实用工具（3个）

实用工具提供了预检和工作流控制功能，确保设计作品符合专业标准。

资料来源：README.md:380-420

架构设计

系统架构图

graph TD
    subgraph "用户层"
        A[Claude Code / AI Assistant]
    end
    
    subgraph "MCP 协议层"
        B[MCP Server<br/>illustrator-mcp-server]
    end
    
    subgraph "通信层"
        C[Adobe Illustrator<br/>ESTK / AppleScript]
    end
    
    subgraph "JSX 辅助层"
        D[jsx/helpers/*.jsx]
    end
    
    A <-->|MCP Protocol| B
    B <-->|Execute Script| C
    C <-->|Import| D
    
    style A fill:#e1f5fe
    style B fill:#b3e5fc
    style C fill:#81d4fa
    style D fill:#4fc3f7

工具执行流程

sequenceDiagram
    participant User as 用户
    participant MCP as MCP Server
    participant AI as Illustrator
    participant JSX as JSX Helpers
    
    User->>MCP: 调用工具函数
    MCP->>MCP: 验证参数
    MCP->>AI: 执行 JSX 脚本
    AI->>JSX: 导入辅助函数
    JSX-->>AI: 返回处理结果
    AI-->>MCP: 脚本执行结果
    MCP-->>User: 格式化响应

预检系统

预检系统是项目为印刷行业工作流设计的重要功能模块，能够在提交印刷前自动检测常见问题。 资料来源：plugins/illustrator-preflight/skills/illustrator-preflight/references/preflight-rules.md:1-50

问题严重性分类

资料来源：plugins/illustrator-preflight/skills/illustrator-preflight/references/preflight-rules.md:50-100

关键检查项

预检系统涵盖七大类检查，每类针对特定的印刷风险：

graph LR
    subgraph "预检类别"
        A[RGB in CMYK] --> E[色彩管理]
        B[Broken Links] --> F[图像完整性]
        C[Low Resolution] --> F
        D[White Overprint] --> G[叠印问题]
        H[Transparency] --> G
        I[Spot Colors] --> H
        J[Non-outlined Text] --> I
    end

Critical 级别检查项：

• RGB in CMYK：CMYK 文档中的 RGB 颜色对象，会导致印刷色偏
• Broken Links：缺失的图像链接，会打印为低分辨率预览或空白
• Low Resolution：低于阈值（印刷 300DPI/Web 72DPI）的图像
• White Overprint：白色对象启用叠印，在印刷中不可见

资料来源：plugins/illustrator-preflight/skills/illustrator-preflight/references/preflight-rules.md:100-150

Warning 级别检查项：

• Non-outlined Text：字体未转曲线的文本，需要确认印刷厂要求
• Spot Colors：专色使用，需要确认是否有意使用特殊油墨
• Transparency：透明度效果，PDF/X-1a 要求拼合，PDF/X-4 允许保留

Info 级别检查项：

• Bleed：出血区域设置，用于裁切容差

版本历史与更新

最新版本 v1.5.1

最新稳定版本修复了 MCP Registry 自动发布失败的问题，并更新了依赖包以消除 7 个安全漏洞。 资料来源：社区上下文 - Latest Release

重要版本里程碑

资料来源：社区上下文 - Release Notes

SVG 导入改进

社区反馈指出 SVG 导入功能存在操作不清晰的问题，用户不清楚应该使用哪个 MCP 操作将 SVG 作为可编辑对象导入现有文档。Issue #35 记录了这一体验改进需求，推动了文档和工具行为的进一步明确化。 资料来源：社区上下文 - Issue #35

安装与使用

系统要求

• Node.js 18.0 或更高版本
• Adobe Illustrator（支持多版本自动检测）
• MCP 兼容的 AI 客户端（如 Claude Desktop）

快速开始

1. 安装 MCP 服务器
2. 配置 AI 客户端的 MCP 设置
3. 启动 Illustrator
4. 通过 AI 助手发送自然语言指令

工作流模板

项目提供了两个预建的 Claude Desktop 模板：

资料来源：README.md:420-460

社区与支持

开发者背景

该项目在日本设计社区获得了关注，开发者通过社交媒体分享了使用该工具创建的示例作品。"Twilight Geometry" 是一个完全由 Claude 生成的抽象几何风景作品，展示了 AI 与 Illustrator 协作的创作潜力。 资料来源：README.md:460-500

国际化支持

项目文档提供多语言版本，包括日语、英语、法语、德语、西班牙语、韩语和葡萄牙语，方便全球设计师了解和使用该工具。 资料来源：README.fr.md, README.ko.md, README.es.md, README.pt-BR.md, README.de.md

参与贡献

• GitHub Issues：报告问题和提出功能建议
• Pull Requests：欢迎代码贡献
• MCP Registry：已集成自动化发布流程

技术规格

资料来源：manifest.json:1-30

概述

クイックスタート是 illustrator-mcp-server 的入门指南，旨在帮助用户快速了解并开始使用这个 MCP（Model Context Protocol）服务器。该项目使 AI 助手（如 Claude Code）能够直接控制 Adobe Illustrator 进行设计操作，包括文档读取、对象修改、SVG/PDF 导出以及印前检查等功能。

资料来源：README.md:1-20

系统要求

支持的环境

资料来源：CLAUDE.md

Illustrator 版本配置

在 macOS 上如果同时运行多个 Illustrator 版本，可以使用 set_illustrator_version 工具指定要连接的版本：

{
  "tool": "set_illustrator_version",
  "params": {
    "version": "2024"
  }
}

资料来源：README.md:1-15, v1.3.2 发布说明

架构概述

illustrator-mcp-server 采用客户端-服务端架构，通过 MCP 协议与 AI 助手通信，后端通过 AppleScript（macOS）或 PowerShell（Windows）调用 Illustrator 的 ExtendScript/JSX 引擎执行实际操作。

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

资料来源：README.es.md:1-20

工具分类总览

服务器提供 70+ 个 MCP 工具，分为以下类别：

读取工具（21个）

资料来源：README.md:20-80, manifest.json

修改工具（38个）

资料来源：README.md:80-150

导出工具（2个）

资料来源：README.md:150-160

实用工具（3个）

资料来源：README.ko.md:1-30

坐标系统

服务器自动从文档检测坐标系统，这是 v1.4.0 版本的重要改进：

资料来源：README.md:160-180, v1.4.0 发布说明

工作流检测逻辑

export function detectWorkflow(signals: DocumentSignals): WorkflowHint {
  const { colorMode, rulerUnits, rasterEffectResolution, colorProfile } = signals;
  const isCMYK = colorMode === 'CMYK';
  const isRGB = colorMode === 'RGB';
  // 根据文档属性自动判断工作流和推荐坐标系统
}

资料来源：src/tools/session.ts:1-50

强制指定坐标系统

如需覆盖自动检测，可使用 set_workflow 工具：

{
  "tool": "set_workflow",
  "params": {
    "workflow": "print"
  }
}

快速使用示例

示例1：获取文档信息

用户：获取当前文档的基本信息
Claude：→ get_document_info

返回结果包含：
- 文档尺寸和画板数量
- 颜色模式（CMYK/RGB）
- 颜色配置文件
- 当前坐标系统

示例2：创建设计元素

用户：创建一个 200x100 的红色圆角矩形
Claude：→ create_rectangle
  {
    "width": 200,
    "height": 100,
    "fill_color": "#FF0000",
    "corner_radius": 10
  }

示例3：导出画板

用户：导出所有画板为 SVG
Claude：→ export (重复调用)
  {
    "format": "svg",
    "artboard_index": 0
  }

  4个画板已导出：
  - /output/header.svg
  - /output/hero.svg
  - /output/feature.svg
  - /output/footer.svg

资料来源：README.de.md:1-30

示例4：印前检查工作流

7步完整印前检查流程：

flowchart TD
    A[1. 文档检查] --> B[2. 预检]
    B --> C[3. 叠印检查]
    C --> D[4. 分色检查]
    D --> E[5. 图像质量]
    E --> F[6. 颜色诊断]
    F --> G[7. 文本一致性]

检查项目包括：

• RGB 颜色混用
• 断开的链接
• 低分辨率图像
• 白色叠印
• 透明度和叠印交互
• PDF/X 合规性

资料来源：src/prompts/print-preflight-workflow.ts:1-30

示例5：生成测试图案

用户：创建一个 1920x1080 的 SMPTE 彩色测试图案

Claude：→ create_rectangle (多个)
  → create_text_frame
  → set_z_order

结果：完整的 SMPTE 彩色测试图案

工作流模板

Claude Desktop 的提示词选择器提供预建工作流模板：

资料来源：README.md:180-200

已知限制

资料来源：README.es.md:1-20

从源码编译

git clone https://github.com/ie3jp/illustrator-mcp-server.git
cd illustrator-mcp-server
npm install
npm run build

安装依赖后，需要在 Claude Desktop 中配置 MCP 服务器路径。

资料来源：README.es.md:20-30

常见问题

坐标系统不匹配

如果发现坐标位置与预期不符，首先检查 get_document_info 返回的 coordinateSystem 字段。对于 CMYK 文档使用 document 系统（左下原点），RGB 文档使用 artboard-web 系统（画板左上原点）。

SVG 导入问题

将 SVG 作为编辑对象导入现有文档时，应使用专门的处理方式而非 place_image。相关改进已记录在 Issue #35 中。

多版本 Illustrator

在 macOS 上同时运行多个 Illustrator 版本时，set_illustrator_version 工具可确保连接到正确的版本。

更多信息

• 完整工具参考：README.md
• 开发者文档：CLAUDE.md
• 最新发布：v1.5.1

概述

illustrator-mcp-server 是一个基于 Model Context Protocol (MCP) 的服务器实现，旨在实现 AI 助手（如 Claude）与 Adobe Illustrator 之间的双向通信。该服务器使 AI 能够通过自然语言指令直接操控 Illustrator，实现文档创建、对象编辑、文本处理、颜色管理、PDF 导出、印前检查等 60+ 项功能。

项目的核心架构采用 TypeScript/Node.js 构建，通过以下两种平台特定机制与 Illustrator 通信：

• macOS: 使用 osascript 执行 AppleScript，再由 AppleScript 执行 JavaScript (ExtendScript/JSX)
• Windows: 使用 PowerShell COM 自动化，通过 DoJavaScript 方法直接执行 JSX

资料来源：manifest.json:1-15

系统架构图

flowchart LR
    AI["Claude / AI Assistant"] <-->|MCP Protocol| Server["MCP Server<br/>(TypeScript/Node.js)"]
    
    Server -->|生成临时脚本| Runner["run-{uuid}.scpt<br/>或 .ps1"]
    Server -->|生成 JSX 代码| JSX["script-{uuid}.jsx<br/>(BOM UTF-8)"]
    Server -->|写入参数| PF["params-{uuid}.json"]
    
    Runner -->|execFile| osascript["osascript<br/>(macOS)"]
    Runner -->|execFile| PS["powershell.exe<br/>(Windows)"]
    
    osascript -->|do javascript| AI_App["Adobe Illustrator<br/>(ExtendScript/JSX)"]
    PS -->|DoJavaScript| AI_App
    
    JSX -.->|execute| AI_App
    PF -.->|read| AI_App
    
    AI_App -.->|write| RF["result-{uuid}.json"]
    RF -.->|read| Server

核心组件

1. MCP 服务器层

MCP 服务器是整个系统的核心入口，负责：

• 接收来自 AI 助手的 MCP 协议请求
• 解析工具调用参数
• 协调工具执行流程
• 返回结构化结果

flowchart TD
    Request["MCP 请求<br/>(工具名称 + 参数)"] --> Validate["参数验证<br/>(Zod Schema)"]
    Validate -->|验证通过| Generate["生成 JSX 代码"]
    Validate -->|验证失败| Error["返回错误"]
    Generate --> Execute["执行脚本"]
    Execute --> Read["读取结果文件"]
    Read --> Format["格式化响应"]
    Format --> Response["MCP 响应"]

2. 工具执行器 (Tool Executor)

工具执行器负责管理所有 MCP 工具的注册和执行。工具按照功能分为以下几类：

资料来源：src/tools/tool-executor.ts:1-50

3. 脚本执行器 (JSX Runner)

JSX Runner 负责跨平台脚本生成和执行，是实现 Illustrator 自动化通信的关键组件。

#### 执行流程

sequenceDiagram
    participant Server as MCP Server
    participant Runner as JSX Runner
    participant File as File Transport
    participant OS as osascript/PowerShell
    participant AI as Adobe Illustrator
    
    Server->>Runner: 调用 executeJsx(code, params)
    Runner->>Runner: 生成唯一 UUID
    Runner->>File: 写入 script-{uuid}.jsx
    Runner->>File: 写入 params-{uuid}.json
    Runner->>File: 写入 run-{uuid}.scpt/.ps1
    Runner->>OS: 执行 Runner 脚本
    OS->>AI: 执行 JSX 代码
    AI-->>File: 写入 result-{uuid}.json
    File-->>Runner: 读取结果
    Runner-->>Server: 返回执行结果

#### 平台差异

资料来源：src/executor/jsx-runner.ts:1-80

4. 文件传输层 (File Transport)

文件传输层负责临时文件的创建、写入和清理，确保脚本执行的安全性。

#### 临时文件生命周期

flowchart LR
    subgraph 生命周期
        Create["创建<br/>(BOM UTF-8)"] --> Use["执行<br/>JSX 脚本"] --> Cleanup["清理<br/>(删除临时文件)"]
    end
    
    subgraph 临时文件类型
        Script["script-{uuid}.jsx<br/>JSX 执行代码"]
        Params["params-{uuid}.json<br/>输入参数"]
        Result["result-{uuid}.json<br/>执行结果"]
        Runner["run-{uuid}.scpt/.ps1<br/>执行器脚本"]
    end
    
    Create --> Script
    Create --> Params
    Create --> Runner
    Use --> Result
    Result --> Cleanup

#### 文件编码规范

所有 JSX 文件必须使用 BOM UTF-8 编码，以确保 Illustrator 正确解析多字节字符（如日文、中文）。

// src/executor/file-transport.ts 中的编码处理
const BOM = '\uFEFF';
const contentWithBOM = BOM + content;

资料来源：src/executor/file-transport.ts:1-30

5. JSX 辅助函数库

JSX 辅助函数库 (common.jsx) 提供跨 Illustrator 版本的兼容性封装，是工具实现的基础。

#### 核心功能模块

// common.jsx 中的坐标转换示例
function convertToDocumentCoords(point, artboard) {
  // artboard-web: 左上原点, Y轴向下
  // document: 左下原点, Y轴向上
  return {
    x: point.x,
    y: artboard.height - point.y
  };
}

资料来源：src/jsx/helpers/common.jsx:1-100

通信协议

MCP 协议交互

MCP 服务器通过标准 MCP 协议与 AI 助手通信：

sequenceDiagram
    participant AI as Claude
    participant MCP as MCP Server
    participant Runner as JSX Runner
    participant AIApp as Illustrator
    
    AI->>MCP: tools/call (tool_name, arguments)
    MCP->>MCP: 验证参数 (Zod)
    MCP->>Runner: executeJsx(jsxCode, params)
    Runner->>AIApp: 执行 JSX 脚本
    AIApp-->>Runner: result.json
    Runner-->>MCP: { success, data, coordinateSystem }
    MCP-->>AI: tool_response

请求格式

interface ToolRequest {
  name: string;           // 工具名称
  arguments: {
    [key: string]: any;   // 工具参数
    coordinate_system?: 'artboard-web' | 'document';
  };
}

响应格式

interface ToolResponse {
  success: boolean;
  data: any;              // 工具执行结果
  coordinateSystem: 'artboard-web' | 'document';
  error?: {
    message: string;
    code: string;
  };
}

坐标系系统

系统自动检测文档类型并选择合适的坐标系，这是 v1.4.0 版本的重要改进。

坐标系对比

自动检测逻辑

flowchart TD
    Start["打开文档"] --> Detect["检测文档属性"]
    Detect -->|colorMode === 'CMYK'| CMYK["坐标系: document"]
    Detect -->|colorMode === 'RGB'| RGB["坐标系: artboard-web"]
    RGB --> Check["rulerUnits === 'px'?"]
    Check -->|是| WebReady["确认 artboard-web"]
    Check -->|否| Manual["需要手动设置"]
    CMYK --> PrintReady["确认 document"]
    
    Manual -->|用户调用| set_workflow["set_workflow 工具"]
    set_workflow --> Override["覆盖自动检测"]

会话状态管理

坐标系状态通过会话 (Session) 管理，确保在连续操作中保持一致：

// src/tools/session.ts
interface WorkflowHint {
  detectedWorkflow: WorkflowType;
  recommendedCoordinateSystem: CoordinateSystem;
  reasoning: string;
  signals: DocumentSignals;
}

资料来源：src/tools/session.ts:1-60

版本兼容性处理

macOS 多版本 Illustrator

当系统上同时安装多个版本的 Illustrator 时，set_illustrator_version 工具允许指定要连接的版本。系统通过检查进程名称来定位正确的 Illustrator 实例。

Illustrator API 限制

部分 Illustrator API 功能存在已知限制：

安全性考虑

临时文件管理

1. 唯一标识: 所有临时文件使用 UUID 命名，避免冲突
2. 自动清理: 执行完成后立即删除临时文件
3. 文件权限: 临时目录设置适当的读写权限

脚本执行隔离

• JSX 代码在 Illustrator 沙盒中执行
• 通过参数文件传递数据，减少直接代码注入风险
• 错误处理包含事务性回滚机制

扩展机制

工具注册流程

flowchart TD
    Define["定义工具"] --> Schema["定义 Zod Schema"]
    Schema --> Register["注册到 MCP Server"]
    Register --> Handler["实现 Handler 函数"]
    Handler --> Export["导出工具元数据"]
    
    Export -->|自动生成| Docs["文档生成"]
    Docs -->|用户可见| ToolList["工具列表"]

插件系统 (Skills)

项目支持通过 Skills 目录扩展功能：

plugins/
└── illustrator-preflight/
    └── skills/
        └── illustrator-preflight/
            └── SKILL.md

Skills 可以定义复杂的复合工作流，如 print-preflight-workflow 提供 7 步印前检查流程。

社区反馈与改进

根据社区反馈，系统架构持续优化：

• v1.4.0: 修复了 CMYK 文档坐标系的错误假设问题，改进了文档属性自动检测
• v1.3.2: 修复了 macOS 多版本 Illustrator 同时运行时的版本定位问题
• v1.2.9: 解决了打包版本 (mcpb) 中 JSX 辅助文件路径问题

总结

illustrator-mcp-server 的架构设计围绕以下核心原则：

1. 平台无关性: 通过抽象执行层支持 macOS 和 Windows
2. 协议标准化: 基于 MCP 协议实现与 AI 助手的无缝通信
3. 自动化兼容性: 处理 Illustrator 版本差异和 API 限制
4. 安全隔离: 临时文件管理和脚本执行隔离
5. 用户体验优先: 自动检测文档类型和坐标系，减少用户配置负担

该架构使得 AI 助手能够以自然语言方式控制 Illustrator，同时保持对专业设计工作流程的完整支持。

概述

JSXスクリプト実行メカニズム是 illustrator-mcp-server 的核心组件，负责将 MCP 工具调用转换为 Adobe Illustrator 可执行的 ExtendScript 代码，并通过操作系统级进程间通信完成执行与结果回收。

该机制的设计目标：

• 跨平台兼容：支持 macOS（osascript）和 Windows（PowerShell）
• 进程隔离：每个执行请求运行独立的脚本实例，避免状态污染
• 可靠传输：通过文件系统实现 TypeScript 服务层与 Illustrator 之间的双向通信
• 版本感知：支持同时运行多个 Illustrator 版本并精确选择目标版本

资料来源：src/executor/jsx-runner.ts:1-50

架构总览

┌─────────────────────────────────────────────────────────────────┐
│                     MCP Server (TypeScript)                     │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────────────────┐ │
│  │  MCP Tools  │→ │ JSX Builder │→ │   File Transport Layer   │ │
│  └─────────────┘  └─────────────┘  └─────────────────────────┘ │
└───────────────────────────┬───────────────────────────────────┘
                            │ Write: script-{uuid}.jsx
                            │ Write: params-{uuid}.json
                            ↓
┌─────────────────────────────────────────────────────────────────┐
│                    File System (Temp Directory)                │
│  ┌───────────────┐  ┌───────────────┐  ┌─────────────────────┐ │
│  │script-{uuid}. │  │params-{uuid}. │  │ result-{uuid}.json  │ │
│  │    jsx        │  │    json       │  │   (AI → Server)     │ │
│  └───────────────┘  └───────────────┘  └─────────────────────┘ │
└───────────────────────────┬───────────────────────────────────┘
                            │
        ┌───────────────────┴───────────────────┐
        ↓                                       ↓
┌───────────────────┐                 ┌───────────────────┐
│   macOS Runner    │                 │   Windows Runner  │
│ (run-{uuid}.scpt) │                 │  (run-{uuid}.ps1) │
│    osascript      │                 │   powershell.exe  │
└─────────┬─────────┘                 └─────────┬─────────┘
          │                                   │
          └─────────────────┬─────────────────┘
                            ↓
┌─────────────────────────────────────────────────────────────────┐
│                 Adobe Illustrator (JSX Engine)                  │
│  ┌─────────────────────────────────────────────────────────────┐│
│  │ 1. Read params-{uuid}.json                                 ││
│  │ 2. Execute script-{uuid}.jsx                               ││
│  │ 3. Write result-{uuid}.json                                ││
│  └─────────────────────────────────────────────────────────────┘│
└─────────────────────────────────────────────────────────────────┘

执行流程详解

1. 请求初始化

当 MCP 工具被调用时，执行引擎生成唯一的执行 UUID：

const executionId = crypto.randomUUID();

此 UUID 作为所有关联文件的命名空间，确保并发执行的隔离性。

资料来源：src/executor/jsx-runner.ts:30-35

2. 参数与脚本生成

执行引擎接收工具参数，生成两类文件：

参数文件结构示例：

{
  "coordinate_system": "artboard-web",
  "artboard_index": 0,
  "output_path": "/Users/xxx/Documents/output.svg"
}

资料来源：src/executor/file-transport.ts:1-40

3. 平台适配执行

根据操作系统类型，选择对应的执行器：

#### macOS 执行路径

run-{uuid}.scpt (AppleScript包装器)
    ↓ do shell script
osascript -l JavaScript
    ↓ DoJavaScript
Adobe Illustrator

AppleScript 包装器负责：

• 定位正确版本的 Illustrator（支持多版本共存场景）
• 传递脚本内容和参数
• 处理执行超时与错误捕获

资料来源：src/executor/jsx-runner.ts:80-120

#### Windows 执行路径

run-{uuid}.ps1 (PowerShell脚本)
    ↓ Start-Process -Wait
powershell.exe -Command "..."
    ↓ DoJavaScript
Adobe Illustrator

v1.3.2 版本修复了 Windows 多版本共存时的版本定位问题，确保 set_illustrator_version 指定的目标版本被正确连接。

资料来源：src/tools/session.ts:1-30

4. JSX 脚本执行

Illustrator 内部的 JSX 引擎执行以下步骤：

// 1. 读取参数文件
var params = readJsonFile(paramsPath);

// 2. 应用坐标系统设置
if (params.coordinate_system === "artboard-web") {
    // 设置为 web 风格坐标系
} else {
    // 使用文档原生坐标系
}

// 3. 执行主逻辑
var result = executeMainLogic(params);

// 4. 写入结果
writeResultFile(resultPath, result);

5. 结果回收

文件传输层监听结果文件写入：

async function awaitResult(executionId: string, timeout: number): Promise<any> {
  const resultPath = getResultPath(executionId);
  const deadline = Date.now() + timeout;
  
  while (Date.now() < deadline) {
    if (fs.existsSync(resultPath)) {
      return JSON.parse(fs.readFileSync(resultPath, 'utf-8'));
    }
    await sleep(100); // 轮询间隔
  }
  throw new Error('Execution timeout');
}

资料来源：src/executor/file-transport.ts:50-80

坐标系统管理

坐标系统是 JSX 执行机制的重要组成部分，服务器自动检测文档类型并应用相应坐标系：

async function resolveCoordinateSystem(requested?: string): Promise<string> {
  if (requested) return requested;
  
  const doc = await getActiveDocument();
  if (doc.colorMode === 'CMYK') return 'document';
  return 'artboard-web';
}

可通过 set_workflow 工具强制覆盖自动检测结果。

资料来源：src/tools/session.ts:60-100

JSX 辅助函数库

common.jsx 提供跨版本兼容的底层操作封装：

// 常见操作封装
var Helpers = {
  // 安全读取文件
  readJsonFile: function(path) { ... },
  
  // 结果写入（带错误处理）
  writeResultFile: function(path, data) { ... },
  
  // 文档信息获取
  getDocumentInfo: function() { ... },
  
  // 坐标转换
  convertPoint: function(point, from, to) { ... }
};

此文件解决了 v1.2.9 版本中发现的捆绑版（mcpb）启动时 JSX 辅助文件路径问题。

资料来源：src/jsx/helpers/common.jsx:1-50

工具调用示例

以 check_text_consistency 工具为例：

1. 用户调用 check_text_consistency
       ↓
2. TypeScript 工具处理器生成 JSX 代码
       ↓
3. 生成 params-{uuid}.json（包含 coordinate_system）
       ↓
4. Runner 执行脚本：
   - Illustrator 读取参数
   - 分析文档中所有文本框
   - 检测占位符文本与记号变体
   - 写入 result-{uuid}.json
       ↓
5. TypeScript 读取结果并格式化返回

资料来源：src/tools/utility/check-text-consistency.ts:30-70

裁剪标记执行细节

create_crop_marks 是执行机制较复杂的工具，包含以下阶段：

1. 样式检测：根据系统区域设置判断日本式（二重线）或西洋式（一重线）
2. 文档修改：扩展画板尺寸以容纳裁剪标记
3. 对象识别：检测接触裁剪线的对象并提示延伸
4. 结果报告：返回新画板尺寸、创建的裁剪标记组数量等

writeResultFile(RESULT_PATH, {
  success: true,
  mode: "artboard",
  crop_mark_style: resolvedStyle,
  mark_groups_created: newGroupCount,
  original_artboard_size: { width: abWidth, height: abHeight },
  new_artboard_size: { width: newWidth, height: newHeight }
});

资料来源：src/tools/modify/create-crop-marks.ts:100-130

已知限制

版本历史相关修复

错误处理

执行过程中可能出现的错误类型：

总结

JSXスクリプト実行メカニズム 通过以下设计实现可靠的多平台执行：

• 文件系统作为通信总线：JSON 文件承载参数与结果，实现无状态解耦
• 平台适配层：osascript/PowerShell 分别处理 macOS/Windows 的进程调用
• 坐标系统抽象：隐藏 Illustrator 内部坐标差异，提供一致的 API 语义
• 版本感知执行：支持设计环境中多版本 Illustrator 共存的现实场景

该机制是 MCP 服务器与 Illustrator 之间唯一的通信桥梁，其稳定性直接影响所有工具的可用性。

概要

読み取りツールは全部で 21 個のツールで構成されており、以下のカテゴリに分類されます：

アーキテクチャ

graph TD
    subgraph "MCP Server (Node.js)"
        RT[読み取りツール群]
        IR[illustrator-readonly.ts<br/>共通基盤]
    end
    
    subgraph "Illustrator (ExtendScript/JSX)"
        AI[Adobe Illustrator<br/>DOM API]
    end
    
    subgraph "生成ファイル"
        JSX[script-{uuid}.jsx]
        JSON[result-{uuid}.json]
    end
    
    RT --> IR
    IR --> JSX
    JSX -->|execute| AI
    AI -->|write| JSON
    JSON -->|read| IR
    IR -->|parse| RT
    
    style RT fill:#e1f5fe
    style AI fill:#fff3e0

読み取りツールは src/common/illustrator-readonly.ts を共通基盤として使用します。このファイルは Illustrator との通信を抽象化し、生成された JSX スクリプトの実行と結果の解析を行います。資料来源：src/common/illustrator-readonly.ts:1-50

ドキュメント情報ツール

get_document_info

ドキュメントの基本情報を取得します。ドキュメント名、サイズ、カラーコレクション等信息を返します。

// 主な返り値
interface DocumentInfo {
  name: string;              // ドキュメント名
  width: number;             // 幅 (pt)
  height: number;            // 高さ (pt)
  colorMode: "CMYK" | "RGB"; // カラーモード
  colorProfile: string;      // カラープロファイル名
  numberOfLayers: number;     // レイヤー数
  numberOfArtboards: number; // アートボード数
  coordinateSystem: string;   // 座標系 (document / artboard-web)
}

资料来源：src/tools/read/get-document-info.ts:1-80

get_artboards

アートボードの情報を取得します。各アートボードの位置、サイズ、向きを返します。

返り値の構造：

• index: アートボードインデックス
• name: アートボード名
• rect: 四隅の座標 [left, top, right, bottom]
• width: 幅 (pt)
• height: 高さ (pt)
• orientation: "landscape" | "portrait" | "square"

get_layers

ドキュメントのレイヤー構造をツリー形式で返します。各レイヤーの名前、表示/非表示状態、ロック状態を含みます。

interface LayerTree {
  name: string;
  visible: boolean;
  locked: boolean;
  children: (LayerTree | PageItemInfo)[];
}

资料来源：src/tools/read/get-layers.ts:1-100

get_document_structure

レイヤー→グループ→オブジェクトの完全なツリー構造を一度の呼び出しで取得します。これは複数の API コールをまとめ、効率的です。

テキストツール

list_text_frames

ドキュメント内のすべてのテキストフレームを一覧で取得します。

资料来源：src/tools/read/list-text-frames.ts:1-60

get_text_frame_detail

特定のテキストフレームの詳細属性を取得します。カーニング、段落設定などを含むすべての属性を返します。

interface TextFrameDetail {
  // 基本情報
  uuid: string;
  name: string;
  layerName: string;
  
  // テキスト内容
  contents: string;
  length: number;
  
  // フォント設定
  font: string;
  fontSize: number;
  fontStyle: string;
  
  // 段落設定
  justification: "Left" | "Center" | "Right" | "Full";
  lineSpacing: number;
  characterSpacing: number;
  
  // 位置・サイズ
  position: { x: number; y: number };
  width: number;
  height: number;
  
  // 颜色
  fillColor: ColorValue;
  strokeColor: ColorValue;
}

资料来源：src/tools/read/get-text-frame-detail.ts:1-120

カラー関連ツール

get_colors

ドキュメントで使用されているカラー情報を取得します。スウォッチ、グラデーション、スポットカラーを含みます。

includeDiagnostics: true の場合、印刷分析情報が追加されます：

• RGB と CMYK の混在警告
• Spot Color の使用状況
• 特色スウォッチの詳細

资料来源：src/tools/read/get-colors.ts:1-150

extract_design_tokens

デザインタトゥokens を抽出します。CSS カスタムプロパティ、JSON、または Tailwind 設定形式で出力できます。

// CSS 出力例
:root {
  --color-primary: #34A853;
  --color-secondary: #34A853;
  --font-heading: "Noto Sans JP", sans-serif;
  --font-body: "Noto Sans JP", sans-serif;
}

資料来源：src/tools/read/extract-design-tokens.ts:1-80

オブジェクトツール

get_path_items

パスとシェイプデータを取得します。塗り、ストローク、アンカーポイント情報を含みます。

get_groups

グループ、クリッピングマスク、複合パスの構造を取得します。

interface GroupInfo {
  uuid: string;
  name: string;
  type: "group" | "compoundPath" | "clippingMask";
  itemCount: number;
  children: PageItemInfo[];
}

get_effects

エフェクトとアピアランス情報を取得します。不透明度、ブレンドモードなどを返します。

制限: ライブエフェクト（ドロップシャドウなど）のパラメータは検出できますが、読み取りはサポートされていません。

画像ツール

get_images

埋め込みまたはリンク画像の情報取得します。

includePrintInfo: true の場合、追加情報が返されます：

• colorSpaceMismatch: カラースペース不一致
• effectiveScale: 実効倍率

资料来源：src/tools/read/get-images.ts:1-100

印刷準備ツール

get_overprint_info

オーバープリント設定と相关信息を取得します。K100/リッチブラックの検出と意図分類を含みます。

get_separation_info

色彩分離情報を取得します。CMYK プロセスプレートとスポットカラープレートの使用回数が含まれます。

interface SeparationInfo {
  processPlates: {
    cyan: number;    // 使用回数
    magenta: number;
    yellow: number;
    black: number;
  };
  spotPlates: {
    name: string;    // 特色名
    count: number;   // 使用回数
  }[];
}

検索・分析ツール

find_objects

条件に基づいてオブジェクトを検索します。名前、タイプ、色、フォントなどで検索可能です。

interface FindObjectsResult {
  count: number;
  matches: {
    uuid: string;
    name: string;
    type: string;
    layerName: string;
  }[];
}

资料来源：src/tools/read/find-objects.ts:1-80

check_contrast

WCAG カラーコントラスト比をチェックします。手動指定または自動検出（重なり合うペア）が可能です。

返り値：

• ratio: コントラスト比 (1-21)
• wcagAA: { normalText: boolean, largeText: boolean }
• wcagAAA: { normalText: boolean, largeText: boolean }

資料来源：src/tools/read/check-contrast.ts:1-60

convert_coordinate

アートボード座標系とドキュメント座標系間の座標変換を行います。

ユーティリティツール

list_fonts

Illustrator で利用可能なフォント一覧を取得します。ドキュメントを開く必要がありません。

interface FontInfo {
  family: string;      // フォントファミリー名
  name: string;        // 完全フォント名
  style: string;       // スタイル (Regular, Bold, Italic, etc.)
  type: string;        // フォントタイプ
}

共通仕様

coordinateSystem フィールド

すべての読み取りツールの返り値には coordinateSystem フィールドが含まれています。このフィールドはアクティブドキュメントの座標系を示します：

资料来源：src/common/illustrator-readonly.ts:50-80

UUID フォーマット

すべてのオブジェクト識別子は UUID 形式です。これはドキュメント間でオブジェクトを一意に識別するために使用されます。

エラーハンドリング

読み取りツールは以下の状況でエラーを返します：

• ドキュメントが開かれていない場合
• 指定されたオブジェクトが存在しない場合
• Illustrator API がエラーを返した場合

コミュニティの課題と改善

Issue #35 では、SVG アートワークを編集可能なオブジェクトとして既存の Illustrator ドキュメントに取り込む際の、操作の不明確さについて報告されています。現在 place_image への SVG ファイルの渡し方が検索結果に影響を与えています。読み取りツール在这方面には直接的な機能はないものの、get_document_structure や find_objects を使って SVG 取り込み後のオブジェクト確認を行うことができます。

资料来源：https://github.com/ie3jp/illustrator-mcp-server/issues/35

制限事項

资料来源：README.md - Known Limitations

変更ツール（Modify Tools）は、Illustrator MCP Serverにおける38個のツール群であり、Adobe Illustratorドキュメント内のオブジェクト作成・編集・構成管理を一括して担う主要機能セットです。AIアシスタント（Claude等）がIllustratorを直接操作し、矩形の生成からテキストフレーム配置、オブジェクト整列・グループ化まで包括的な編集能力を提供します。

概要

変更ツールは読み取りツール（Read Tools）と対になる存在であり、ドキュメントの状態確認ではなく能動的な変更操作を実行します。ツールは以下の5つのカテゴリに大きく分類されます：

资料来源：README.md

アーキテクチャ

変更ツールはIllustratorのExtendScript/JavaScript APIと連携し、以下のフローアーキテクチャで動作します：

flowchart TD
    A[MCP Client<br/>Claude等] -->|MCP Protocol| B[MCP Server<br/>TypeScript/Node.js]
    B -->|生成| C[run-{uuid}.scpt/.ps1]
    B -->|生成| D[script-{uuid}.jsx<br/>BOM UTF-8]
    B -->|書き込み| E[params-{uuid}.json]
    C -->|execFile| F[osascript<br/>PowerShell]
    F -->|DoJavaScript| G[Adobe Illustrator]
    D -->|実行| G
    E -->|読込| G
    G -->|書き込み| H[result-{uuid}.json]
    H -->|読込| B

资料来源：README.md

座標系の自動検出

変更ツールは全てドキュメントの座標系を自動検出します。色モードに基づいて適切な座標系が選択され、各ツールのレスポンスにはcoordinateSystemフィールドが含まれます：

资料来源：src/tools/session.ts:1-100

v1.4.0以前では全ドキュメントに「左上が原点、Yは下向き」と伝える方式이었ため、CMYK印刷ドキュメントで意図しない結果を生じる問題がありました。v1.4.0では各ドキュメントに座標系の自己申告をさせる方式に改められました。

基本図形作成ツール

create_rectangle

新規四角形を作成するツールです。角丸に対応し、塗り・線属性を任意で指定できます。

パラメータ仕様：

资料来源：src/tools/modify/create-rectangle.ts

fill_color / stroke_color オブジェクト形式：

{
  "type": "RGB" | "CMYK" | "spot",
  "color": {
    "r": 255, "g": 0, "b": 0        // RGB時
    // または
    "c": 0, "m": 100, "y": 100, "k": 0  // CMYK時
  }
}

create_ellipse

楕円または真円を作成するツールです。四角形と同様の属性指定が可能で、width = heightで真円になります。

资料来源：src/tools/modify/create-ellipse.ts

create_line

2点間の直線（パスアイテム）を作成するツールです。 stroke_colorとstroke_widthによる線属性の指定のみ可能です（fill_colorは無視されます）。

资料来源：src/tools/modify/create-line.ts

create_path

ベジェハンドルを伴うカスタムパスを生成するツールです。 прямолинейные сегментыと曲線セグメントを組み合わせた複雑な形状を作成できます。

パスポイント配列形式：

{
  "path_points": [
    {
      "anchor": { "x": 100, "y": 100 },
      "left_direction": { "x": 80, "y": 100 },
      "right_direction": { "x": 120, "y": 100 },
      "type": "smooth" | "corner" | "symmetric"
    }
  ]
}

资料来源：src/tools/modify/create-path.ts

create_text_frame

テキストフレーム（ポイントテキストまたはエリアテキスト）を作成するツールです。

资料来源：src/tools/modify/create-text-frame.ts

オブジェクト編集ツール

modify_object

既存オブジェクトのプロパティを変更する汎用的ツールです。変更可能なプロパティはオブジェクトタイプによって異なります。

共通パラメータ：

资料来源：src/tools/modify/modify-object.ts

convert_to_outlines

テキストをアウトライン（パス）に変換する不可逆ツールです。フォント依存性を排除し、印刷入稿时可変性を高めます。

警告: この操作は元に戻せません。実行前にバックアップを推奨します。プリフライトチェックで非アウトラインテキストが検出された場合、印刷所に応じた判断が必要です。

资料来源：src/tools/modify/convert-to-outlines.ts

资料来源：plugins/illustrator-preflight/skills/illustrator-preflight/references/preflight-rules.md

place_image

画像ファイルをリンクまたは埋め込みで配置するツールです。

コミュニティ課題 #35: SVGファイルをplace_imageに渡すことは技術的に可能ですが、結果として得られるのは編集可能なIllustratorオブジェクトではなく、配置されたアートワークになります。SVGを編集可能なオブジェクトとして取り込む場合は、後述のimport_svg_as_editableの使用を検討してください。

资料来源：src/tools/modify/place-image.ts

import_svg_as_editable

SVGアートワークを既存のIllustratorドキュメントに編集可能なオブジェクトとしてインポートする専用ツールです。

资料来源：src/tools/modify/import-svg-as-editable.ts

graph TD
    A[SVGファイル] --> B{place_image?}
    A --> C{import_svg_as_editable?}
    B --> D[リンク/埋め込み配置]
    B --> E[編集不可アセット]
    C --> F[編集可能なIllustratorオブジェクト]
    style D fill:#f9f,stroke:#333
    style F fill:#9f9,stroke:#333

グループ化・整列ツール

group_objects

複数のオブジェクトをグループ化するツールです。クリッピングマスクにも対応しています。

资料来源：src/tools/modify/group-objects.ts

ungroup_objects

グループを解除し、子オブジェクトをリリースします。

align_objects

複数のオブジェクトを整列・分布させるツールです。

资料来源：src/tools/modify/align-objects.ts

duplicate_objects

オブジェクトを複製し、オプションでオフセット配置できます。

資料来源：src/tools/modify/duplicate-objects.ts

set_z_order

オブジェクトのスタック順序（前後関係）を変更します。

资料来源：src/tools/modify/set-z-order.ts

move_to_layer

オブジェクトを異なるレイヤーに移動します。

资料来源：src/tools/modify/move-to-layer.ts

レイヤー管理ツール

manage_layers

レイヤーの追加・名前変更・表示/非表示・ロック/ロック解除・順序変更・削除を実行します。

资料来源：src/tools/modify/manage-layers.ts

カラーツール

replace_color

ドキュメント全体で色を検索・置換するツールです。 容許範囲（tolerance）設定により、近似色の置換も可能です。

资料来源：src/tools/modify/replace-color.ts

place_color_chips

ドキュメント内のユニークな色を抽出し、アートボード外部にカラーチップスウォッチとして配置します。

assign_color_profile

カラープロファイルを割り当てます（値変換なし、 taggedのみ）。

资料来源：src/tools/modify/assign-color-profile.ts

ドキュメント管理ツール

create_document

新規Illustratorドキュメントを作成します。

资料来源：src/tools/modify/create-document.ts

open_document

ファイルパスからドキュメントを開きます。

资料来源：src/tools/modify/open-document.ts

save_document

ドキュメントを保存または名前を付けて保存します。output_pathを省略すると、ドキュメントと同じフォルダに連番付きで自動保存されます。

v1.2.12より、書き出しパス自動生成機能が追加されました。衝突回避のための連番付き命名が行われます。

资料来源：src/tools/modify/save-document.ts

close_document

アクティブドキュメントを閉じます。

プリフライトとの連携

変更ツールはプリフライトチェックと密接に連携します。特に以下のシナリオでは、変更ツールがプリフライト問題の解决方案となります：

graph LR
    A[preflight_check] -->|Critical: 非アウトラインテキスト| B[convert_to_outlines]
    A -->|Critical: 白オーバープリント| C[modify_object]
    A -->|Warning: スポットカラー| D[replace_color]
    A -->|Info: 低解像度| E[place_image]

資料来源：plugins/illustrator-preflight/skills/illustrator-preflight/references/preflight-rules.md

ワークフロー使用例

自然言語によるレイアウト配置

ユーザー: ヘッダー、本文、キャプションとしてアートボード上にテキストを配置して
Claude: → create_text_frame を用いて配置

资料来源：README.md

PDF/X-1a準拠のためのテキスト処理

ユーザー: このドキュメントはPDF/X-1a準拠か確認して
Claude: → preflight_check (target_pdf_profile: "x1a")
       → 非アウトラインテキスト検出時、convert_to_outlines を提供

制限事項と注意点

资料来源：README.md

関連ツール群

概述

書き出しツール（Export Tools）是 illustrator-mcp-server 的核心功能模块，负责将 Illustrator 文档中的内容导出为多种格式。该模块包含两个主要工具：export 和 export_pdf，分别用于 SVG/PNG/JPG 格式的通用导出和印刷用 PDF 导出。

書き出し工具在 MCP 服务器中属于 Export Tools 类别，是 Phase 3（書き出し + 印刷向け読み取り）阶段注册的核心工具之一。资料来源：src/tools/registry.ts:17-18

┌─────────────────────────────────────────────────────────────┐
│                    書き出しツール群                          │
├─────────────────────────────────────────────────────────────┤
│  export        │  SVG / PNG / JPG 書き出し                   │
│  export_pdf    │  印刷用 PDF 書き出し                         │
│  create_crop_marks │  トンボ（トリムマーク）作成              │
└─────────────────────────────────────────────────────────────┘

export ツール

功能描述

export 工具提供灵活的矢量/栅格格式导出能力，支持按アートボード、选择对象或 UUID 进行导出。

资料来源：src/tools/export/export.ts:1-50

支持的格式

参数说明

interface ExportParams {
  format?: 'svg' | 'png' | 'jpg';           // 输出格式
  output_path?: string;                      // 输出路径（可省略）
  artboard_index?: number;                   // アートボード索引
  selected_only?: boolean;                   // 仅导出选中对象
  object_uuid?: string;                      // 对象 UUID
  export_selection?: boolean;                // 导出当前选择
  quality?: number;                          // JPG 质量 (1-100)
  scale?: number;                            // 缩放比例
  embed_images?: boolean;                    // 嵌入图像
  coordinate_system?: 'artboard-web' | 'document'; // 坐标系
}

导出模式

export 工具支持三种导出模式：

1. 按アートボード导出：指定 artboard_index 导出整个アートボード
2. 按选择导出：设置 selected_only: true 或 export_selection: true 导出当前选中对象
3. 按 UUID 导出：使用 object_uuid 导出特定对象

资料来源：src/tools/export/export.ts:60-100

自动路径生成（v1.2.12）

当 output_path 参数省略时，系统会自动生成输出路径：

• 路径规则：文档所在文件夹 + 连番文件名
• 冲突处理：自动添加序号避免文件覆盖
• 回退位置：如果无法确定文档路径，则保存至 ~/Desktop

graph TD
    A[export 调用] --> B{output_path 是否指定?}
    B -->|否| C[获取文档路径]
    C --> D{路径可获取?}
    D -->|是| E[文档同目录]
    D -->|否| F[~/Desktop]
    E --> G[生成连番文件名]
    F --> G
    G --> H[检查文件冲突]
    H --> I{存在冲突?}
    I -->|是| J[序号+1]
    J --> H
    I -->|否| K[返回最终路径]
    B -->|是| L[使用指定路径]
    K --> M[执行导出]
    L --> M

资料来源：README.md - v1.2.12 release notes

SVG 导出注意

• 文本默认转换为轮廓（保持视觉一致性）
• 导出时 Illustrator 可能将アートボード名附加到文件名，导致验证失败（已在 v1.2.12 修复）

资料来源：README.md - v1.2.12 release notes

export_pdf ツール

功能描述

export_pdf 工具专门用于生成印刷就绪的 PDF 文件，支持高级印刷设置如裁切线、出血和选择性降采样。

资料来源：src/tools/export/export-pdf.ts:1-60

PDF 预设与配置

interface ExportPdfParams {
  output_path?: string;                      // 输出路径
  preset?: string;                           // PDF 预设
  artboard_index?: number;                   // アートボード索引
  include_crop_marks?: boolean;              // 包含裁切线
  bleed?: number;                            // 出血设置 (mm)
  crop_style?: 'japanese' | 'western';       // 裁切线样式
  downsample_threshold?: number;             // 降采样阈值 (DPI)
  color_compression?: 'auto' | 'none';       // 颜色压缩
  output_intent?: string;                    // 输出意图 (PDF/X)
  coordinate_system?: 'artboard-web' | 'document';
}

日本式裁切线处理（v1.3.0/v1.3.1）

日本式トンボ（二重线）与西洋式（一重线）的处理方式：

重要：PDF 输出的日本式裁切线使用 TrimMark コマンド方式实现，通过以下流程避免版本兼容性问题：

1. 生成裁切线作为文档路径
2. 执行导出
3. 通过 undo 删除裁切线

资料来源：src/tools/export/export-pdf.ts:100-150

graph LR
    A[设置 TrimMark] --> B[导出 PDF]
    B --> C[撤销裁切线]
    C --> D[最终 PDF]
    
    E[日本式裁切] -->|TrimMark 命令| A
    F[西洋式裁切] -->|标准方式| A

PDF/X 合规性

export_pdf 支持设置输出意图以满足 PDF/X 标准：

• PDF/X-1a：禁止透明度，必须 CMYK/Spot Color
• PDF/X-4：支持透明度，ICC 色彩管理
• 无目标：不强制色彩空间

资料来源：plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md

create_crop_marks 工具

功能描述

create_crop_marks 工具用于在文档中创建裁切标记（トンボ），支持根据系统语言自动判断样式。

资料来源：src/tools/modify/create-crop-marks.ts:1-80

样式自动判定

参数说明

interface CropMarksParams {
  artboard_index?: number;           // アートボード索引
  offset?: number;                    // 偏移量 (mm)
  length?: number;                   // 线条长度
  style?: 'japanese' | 'western';    // 强制样式
  coordinate_system?: string;
}

与 export_pdf 的集成

create_crop_marks 可独立使用，也可通过 export_pdf 的 include_crop_marks 参数自动集成：

• 独立使用：先生成裁切线，再执行标准导出
• 集成使用：设置 include_crop_marks: true 由 export_pdf 自动处理

坐标系处理

自动检测机制

書き出し工具会自动检测文档坐标系：

所有工具响应都包含 coordinateSystem 字段，指示当前激活的坐标系。

资料来源：src/tools/session.ts:60-100

坐标转换

convert_coordinate 工具可在不同坐标系之间转换坐标值：

convert_coordinate(
  x: number,                    // X 坐标
  y: number,                    // Y 坐标
  from_system: 'artboard-web' | 'document',
  to_system: 'artboard-web' | 'document',
  artboard_index?: number
)

使用场景与工作流

场景 1：Web 资产导出

graph TD
    A[打开 RGB 文档] --> B[设置 workflow: web]
    B --> C[选择导出对象]
    C --> D[export format: svg/png]
    D --> E[Web 优化输出]

场景 2：印刷 PDF 导出

graph TD
    A[打开 CMYK 文档] --> B[preflight_check]
    B --> C{检查通过?}
    C -->|否| D[修复问题]
    D --> B
    C -->|是| E[export_pdf with crop marks]
    E --> F[出血 + 裁切线]
    F --> G[印刷用 PDF]

场景 3：批量アートボード导出

1. get_artboards → 获取所有アートボード信息
2. 循环调用 export → 按索引导出各アートボード
3. 文本轮廓化 → convert_to_outlines（可选）
4. 格式选择 → SVG/PNG/JPG

版本历史关键修复

已知限制

资料来源：README.es.md - Known limitations section

相关工具链接

• 读取工具：get_document_info、get_artboards、get_selection
• 修改工具：convert_to_outlines、manage_artboards
• 实用工具：preflight_check、check_text_consistency、set_workflow

これらのツールは、ドキュメントの編集・作成機能ではなく、分析・検証・環境設定を行う補助的な役割を担います。

概述

illustrator-mcp-server 实现了双坐标系自动切换机制，根据文档类型（CMYK/印刷或RGB/Web）智能选择最适合的坐标系统。该系统确保 AI 操作 Illustrator 时，坐标值的语义与用户的预期一致，避免因坐标系差异导致的定位错误。

核心设计原则：

• 自动检测优先：系统自动从文档属性推断坐标系
• 手动覆盖能力：通过 set_workflow 工具显式指定工作模式
• 统一抽象接口：所有工具通过 coordinateSystemSchema 共享坐标系参数定义

资料来源：src/tools/session.ts:40-55

坐标系统类型

系统对比表

资料来源：src/tools/session.ts:48-60

工作流信号检测

系统通过分析文档的多维度属性来判断工作流类型：

graph TD
    A[文档打开] --> B{色彩模式检测}
    B -->|CMYK| C[print 工作流]
    B -->|RGB| D{标尺单位检测}
    D -->|mm/cm| E[print 工作流]
    D -->|px| F[web 工作流]
    C --> G[坐标系: document]
    E --> G
    F --> H[坐标系: artboard-web]

检测参数：

• colorMode：文档色彩模式（RGB/CMYK）
• rulerUnits：标尺单位（mm/cm/px/inch）
• rasterEffectResolution：栅格效果分辨率
• colorProfile：颜色配置文件

资料来源：src/tools/session.ts:90-110

核心工具

set_workflow

手动设置工作流模式，覆盖自动检测结果。

参数定义：

返回值结构：

interface WorkflowResult {
  workflow: 'web' | 'print';
  coordinateSystem: 'artboard-web' | 'document';
  reasoning: string;
  sessionMode: boolean;  // 是否手动设置了会话模式
}

资料来源：src/tools/utility/set-workflow.ts

convert_coordinate

在画板坐标系和文档坐标系之间转换坐标点。

功能特性：

• 支持单个点和批量点转换
• 自动识别当前激活的坐标系
• 转换精度保持与 Illustrator 一致

使用场景：

• 当 AI 使用 artboard-web 坐标系计算位置后，需要在 document 坐标系中验证
• 处理跨画板元素定位时统一坐标基准

资料来源：src/tools/read/convert-coordinate.ts

坐标系缓存机制

缓存策略

mermaid
graph LR
    A[请求坐标系统] --> B{缓存存在?}
    B -->|是| C{缓存有效?}
    C -->|是| D[返回缓存值]
    C -->|否| E[重新检测]
    B -->|否| E
    E --> F[执行自动检测]
    F --> G[更新缓存]
    G --> D

缓存失效条件：

1. 文档结构发生变化（添加/删除画板）
2. 文档色彩模式变更
3. 显式调用 set_workflow
4. 会话重启

资料来源：src/tools/session.ts:30-45

降级策略

当自动检测失败时，系统按以下顺序降级：

1. 尝试使用缓存的坐标系统
2. 缓存不可用时重新执行自动检测
3. 所有检测均失败时默认返回 artboard-web

// 降级伪代码
try {
  return await autoDetectCoordinateSystem();
} catch {
  return 'artboard-web';  // 最终降级值
}

资料来源：src/tools/session.ts:55-65

共享架构

coordinateSystemSchema

所有工具统一导入此 Schema 定义，避免重复声明：

export const coordinateSystemSchema = z
  .enum(['artboard-web', 'document'])
  .optional()
  .describe(
    'Coordinate system. Auto-detected from document by default (CMYK/print → document, RGB/web → artboard-web). ' +
    'artboard-web: origin at active artboard top-left, Y-down. ' +
    'document: Illustrator native coords, origin at bottom-left, Y-up. ' +
    'Call get_document_info to check which system is active.'
  );

优势：

• 类型安全：TypeScript 编译时验证
• 文档统一：所有工具参数描述一致
• 易于扩展：新增坐标系仅需修改一处

资料来源：src/tools/session.ts:48-60

resolveCoordinateSystem 工具函数

异步解析坐标系统的标准方法：

async function resolveCoordinateSystem(
  override?: 'artboard-web' | 'document'
): Promise<'artboard-web' | 'document'> {
  if (override) {
    return override;
  }
  return await getCoordinateSystem();
}

调用链：

工具函数 → resolveCoordinateSystem() → getCoordinateSystem() → autoDetectCoordinateSystem()

资料来源：src/tools/modify/shared.ts

工具响应中的坐标系信息

所有工具响应都包含 coordinateSystem 字段，指示当前活跃的坐标系：

{
  "success": true,
  "coordinateSystem": "artboard-web",
  "data": { ... }
}

最佳实践：

• 读取工具响应时首先检查 coordinateSystem 值
• 在跨工具操作序列中保持坐标系一致性
• 使用 get_document_info 显式确认当前坐标系

资料来源：src/tools/utility/check-text-consistency.ts:40-45

常见问题

CMYK 文档坐标异常

症状：在 CMYK 文档中放置对象时，位置与预期不符。

原因：可能意外使用了 web 模式，Y轴方向相反。

解决方案：

1. 调用 set_workflow({ workflow: 'print' }) 强制切换
2. 或调用 set_workflow({ coordinate_system: 'document' }) 直接指定

macOS 多版本 Illustrator 定位问题

v1.3.2 修复了此问题：当多个 Illustrator 版本同时运行时，set_illustrator_version 需要正确连接到指定版本，否则坐标系检测可能基于错误的文档实例。

版本历史

v1.4.0 之前，系统向所有文档统一声明「左上原点、Y轴向下」，导致 CMYK 文档出现坐标语义错误。现版本会先询问文档类型，再决定坐标系。

资料来源：v1.4.0 Release Notes

SVG导入动作

概述

SVGインポート動作（SVG导入动作）是 illustrator-mcp-server 中用于将 SVG 艺术作品作为可编辑对象导入到现有 Illustrator 文档的功能模块。该功能解决了用户在实际工作流程中的一个关键痛点：当需要将 SVG 格式的外部艺术作品合并到当前文档中时，如何正确选择 MCP 操作以获得可编辑的结果。

根据社区反馈（Issue #35），在 v1.4.0 之前的版本中，用户往往将 SVG 文件传递给 place_image 工具，看似可行但实际上无法获得可编辑的 Illustrator 对象。这导致了工作流程的混乱和预期之外的结果。

资料来源：manifest.json:1-50

核心概念：可编辑 SVG 导入与图片占位

理解 SVG 导入动作的关键在于区分两种截然不同的文件处理方式：

资料来源：src/tools/modify/import-svg-as-editable.ts:1-30

工具架构

工具注册与架构

SVG 导入功能通过 import_svg_as_editable 工具实现，该工具在 MCP 服务器中注册并执行以下操作流程：

flowchart TD
    subgraph MCP服务器层
        A[import_svg_as_editable 工具] --> B[参数验证与解析]
    end
    
    subgraph Illustrator执行层
        B --> C[生成 JSX 脚本]
        C --> D[通过 AppleScript/PowerShell 执行]
        D --> E[Adobe Illustrator ExtendScript API]
    end
    
    subgraph 文件处理层
        E --> F[File.prototype.open]
        F --> G[Document.prototype.place]
        G --> H[返回 UUID 映射]
    end
    
    H --> I[JSON 结果序列化]
    I --> J[响应返回给 MCP 客户端]

资料来源：src/tools/modify/import-svg-as-editable.ts:1-100

工具参数规范

import_svg_as_editable 工具接受以下参数：

资料来源：src/tools/modify/import-svg-as-editable.ts:30-80

工作流程与坐标系统

自动坐标系统检测

服务器会根据文档类型自动选择合适的坐标系统：

资料来源：src/tools/session.ts:80-120

SVG 导入时坐标系统的选择会影响对象的放置位置计算。artboard-web 系统原点位于画板左上角，Y轴向下递增；document 系统原点位于文档左下角，Y轴向上递增。

导入后的 UUID 映射机制

导入完成后，工具返回一个 UUID 映射表，其中包含 SVG 中每个对象的 UUID 与 Illustrator 原生对象路径的对应关系。这个映射对于后续通过 modify_object 等工具操作导入的对象至关重要。

{
  "success": true,
  "coordinateSystem": "artboard-web",
  "placedObjects": [
    { "uuid": "abc123", "type": "path", "name": "SVG 路径 1" },
    { "uuid": "def456", "type": "text", "name": "SVG 文本 1" }
  ]
}

资料来源：src/tools/modify/import-svg-as-editable.ts:80-120

与 place_image 的关键区别

场景对比

graph TD
    A[需要导入文件] --> B{文件类型}
    B -->|SVG| C{需要可编辑对象?}
    B -->|PNG/JPG/PSD| D[使用 place_image]
    C -->|是| E[使用 import_svg_as_editable]
    C -->|否| D
    
    D --> F[作为链接或嵌入图片]
    E --> G[作为原生 Illustrator 对象]
    
    F --> H[不可直接编辑文本/路径]
    G --> I[完全可编辑所有元素]

功能对比表

资料来源：src/tools/modify/place-image.ts:1-50

使用场景与最佳实践

典型使用场景

1. 模板填充：将 SVG 图标或装饰元素导入到设计模板中，后续需要调整颜色或大小
2. 素材整合：将外部 SVG 素材合并到当前文档并进行二次编辑
3. 批处理工作流：通过 AI 批量导入多个 SVG 文件并统一管理
4. 跨文档复用：将一个文档中的 SVG 内容迁移到另一个文档

最佳实践

#### 1. 文件路径规范

始终使用绝对路径而非相对路径：

# 正确
file_path: "/Users/designer/Documents/icons/logo.svg"

# 错误
file_path: "./icons/logo.svg"

#### 2. 坐标系统确认

在调用导入工具前，建议先通过 get_document_info 确认当前文档的坐标系统：

const docInfo = await server.callTool("get_document_info", {});
console.log(docInfo.coordinateSystem);

#### 3. 错误处理

SVG 导入可能因文件格式错误、路径不存在或 Illustrator 权限问题失败。实现时应包含重试机制和用户友好的错误提示。

资料来源：src/tools/modify/import-svg-as-editable.ts:100-150

限制与已知问题

资料来源：manifest.json:1-30

版本历史相关变更

资料来源：src/tools/session.ts:50-80

相关工具链

SVG 导入后，通常需要配合以下工具完成完整工作流：

资料来源：src/tools/utility/check-text-consistency.ts:1-50

快速参考

调用示例

// 导入 SVG 作为可编辑对象
const result = await server.callTool("import_svg_as_editable", {
  file_path: "/path/to/design.svg",
  coordinate_system: "artboard-web",
  artboard_index: 0,
  position: { x: 100, y: 200 }
});

// 检查结果
if (result.success) {
  console.log(`导入了 ${result.placedObjects.length} 个对象`);
}

错误代码参考

Pitfall Log / 踩坑日志

项目：ie3jp/illustrator-mcp-server

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
• 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
• 证据：capability.host_targets | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | host_targets=mcp_host, claude, claude_code

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | README/documentation is current enough for a first validation pass.

3. 运行坑 · 来源证据：編集可能な Illustrator アートワークのための SVG インポート動作の明確化と改善

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：編集可能な Illustrator アートワークのための SVG インポート動作の明確化と改善
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_c7b420ed6123436eb6d2b27f460dc2c8 | https://github.com/ie3jp/illustrator-mcp-server/issues/35 | 来源类型 github_issue 暴露的待验证使用条件。

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | last_activity_observed missing

5. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | no_demo; severity=medium

7. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | issue_or_pr_quality=unknown

8. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | release_recency=unknown