# https://github.com/ie3jp/illustrator-mcp-server 项目说明书
生成时间：2026-05-31 19:21:42 UTC
## 目录
- [プロジェクト紹介](#introduction)
- [クイックスタート](#quick-start)
- [システムアーキテクチャ](#architecture)
- [JSXスクリプト実行メカニズム](#jsx-execution)
- [読み取りツール](#read-tools)
- [変更ツール](#modify-tools)
- [書き出しツール](#export-tools)
- [ユーティリティツール](#utility-tools)
- [座標系とワークフロー](#coordinate-system)
- [SVGインポート動作](#svg-import)
## プロジェクト紹介
### 相关页面
相关主题：[クイックスタート](#quick-start), [システムアーキテクチャ](#architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
- [manifest.json](https://github.com/ie3jp/illustrator-mcp-server/blob/main/manifest.json)
- [plugins/illustrator-preflight/skills/illustrator-preflight/references/preflight-rules.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/plugins/illustrator-preflight/skills/illustrator-preflight/references/preflight-rules.md)
- [src/tools/utility/check-text-consistency.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/utility/check-text-consistency.ts)
# プロジェクト紹介
## 项目概述
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个）
读取工具用于获取文档中的各类信息，从基础元数据到高级分析功能都有覆盖。
| 工具名称 | 功能描述 |
|---------|---------|
| `get_document_info` | 文档元数据（尺寸、颜色模式、配置文件等） |
| `get_artboards` | 艺术画板信息（位置、尺寸、方向） |
| `get_layers` | 图层结构树 |
| `get_document_structure` | 完整树结构：图层→组→对象 |
| `list_text_frames` | 文本框架列表（字体、尺寸、样式名称） |
| `get_text_frame_detail` | 特定文本框架的所有属性（字距、段落设置等） |
| `get_colors` | 使用中的颜色信息（色板、渐变、专色）。`include_diagnostics` 用于印刷分析 |
| `get_path_items` | 路径/形状数据（填充、描边、锚点） |
| `get_groups` | 组、剪贴蒙版和复合路径结构 |
| `get_effects` | 效果和外观信息（不透明度、混合模式） |
| `get_images` | 嵌入/链接图像信息（分辨率、断链检测）。`include_print_info` 检查色彩空间不匹配和缩放因子 |
| `get_symbols` | 符号定义和实例 |
| `get_guidelines` | 参考线信息 |
| `get_overprint_info` | 叠印设置 + K100/富黑检测与意图分类 |
| `get_separation_info` | 色彩分离信息（CMYK 过程色版 + 带使用计数的专色版） |
| `get_selection` | 当前选中对象的详细信息 |
| `find_objects` | 按条件搜索（名称、类型、颜色、字体等） |
| `check_contrast` | WCAG 颜色对比度检查（手动或自动检测重叠对） |
| `extract_design_tokens` | 提取设计令牌为 CSS 自定义属性、JSON 或 Tailwind 配置 |
| `list_fonts` | 列出 Illustrator 中可用的字体（无需打开文档） |
| `convert_coordinate` | 在艺术画板和文档坐标系之间转换点 |
资料来源：[README.md:200-280]()
### 修改工具（38个）
修改工具是创作功能的核心，支持创建各种图形对象、编辑现有元素以及管理文档结构。
| 工具类别 | 包含的操作 |
|---------|-----------|
| 基础图形 | `create_rectangle`、`create_ellipse`、`create_line`、`create_path` |
| 文本处理 | `create_text_frame`、`convert_to_outlines`、`create_path_text` |
| 图像处理 | `place_image`、`relink_images`、`manage_datasets` |
| 对象操作 | `modify_object`、`align_objects`、`group_objects`、`ungroup_objects`、`duplicate_objects`、`set_z_order`、`move_to_layer` |
| 文档管理 | `create_document`、`close_document`、`open_document`、`save_document` |
| 样式应用 | `apply_graphic_style`、`list_graphic_styles`、`apply_text_style`、`list_text_styles`、`create_gradient` |
| 颜色管理 | `assign_color_profile`、`replace_color`、`place_color_chips` |
| 高级功能 | `resize_for_variation`、`manage_artboards`、`manage_layers`、`place_symbol`、`select_objects`、`create_crop_marks`、`place_style_guide` |
资料来源：[README.md:280-350]()
### 导出工具（2个）
导出功能专注于高质量输出，支持多种格式以满足不同用途的需求。
| 工具名称 | 功能描述 |
|---------|---------|
| `export` | SVG/PNG/JPG 导出（按艺术画板、选区或 UUID） |
| `export_pdf` | 印刷就绪的 PDF 导出（裁切标记、出血、选择性降采样、输出意图） |
资料来源：[README.md:350-380]()
### 实用工具（3个）
实用工具提供了预检和工作流控制功能，确保设计作品符合专业标准。
| 工具名称 | 功能描述 |
|---------|---------|
| `preflight_check` | 印前检查（RGB 混用、断链、低分辨率、白色叠印、透明度和叠印交互、PDF/X 合规性等） |
| `check_text_consistency` | 文本一致性检查（占位符检测、记号变体模式、LLM 分析用完整文本列表） |
| `set_workflow` | 设置工作流模式（web/print）以覆盖自动检测的坐标系 |
资料来源：[README.md:380-420]()
## 架构设计
### 系统架构图
```mermaid
graph TD
subgraph "用户层"
A[Claude Code / AI Assistant]
end
subgraph "MCP 协议层"
B[MCP Server
illustrator-mcp-server]
end
subgraph "通信层"
C[Adobe Illustrator
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
```
### 工具执行流程
```mermaid
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]()
### 问题严重性分类
| 严重级别 | 说明 | 处理方式 |
|---------|------|---------|
| Critical | 必须修复，阻止提交 | 立即报告并提供修复建议 |
| Warning | 建议审查，根据上下文决定 | 列出问题并询问用户意图 |
| Info | 注意事项，无需强制处理 | 仅作提醒 |
资料来源：[plugins/illustrator-preflight/skills/illustrator-preflight/references/preflight-rules.md:50-100]()
### 关键检查项
预检系统涵盖七大类检查，每类针对特定的印刷风险：
```mermaid
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]()
### 重要版本里程碑
| 版本 | 主要更新内容 |
|-----|------------|
| v1.4.0 | 智能坐标系统检测：自动识别 CMYK（印刷）和 RGB（网页）文档的坐标系 |
| v1.3.1/1.3.2 | 添加裁切标记工具，支持日式（双线）和西式（单线）自动切换 |
| v1.2.12 | 导出路径自动生成：省略输出路径时自动保存到文档目录 |
| v1.2.9 | 修复 macOS 捆绑版本启动时 JSX 辅助文件缺失问题 |
| v1.2.11 | Windows 兼容性改进，使用 Node.js 标准 API 替代 Unix 命令 |
资料来源：[社区上下文 - 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 模板：
| 模板名称 | 用途描述 |
|---------|---------|
| `quick-layout` | 用户粘贴文本内容，Claude 将其排列为标题、正文和说明 |
| `print-preflight-workflow` | 7 步印前检查完整流程：文档→预检→叠印→分色→图像→颜色→文本 |
资料来源：[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：已集成自动化发布流程
## 技术规格
| 规格项 | 说明 |
|-------|------|
| 许可证 | MIT |
| 仓库地址 | https://github.com/ie3jp/illustrator-mcp-server |
| 关键词 | illustrator, adobe, design, mcp, vector, graphics, print, prepress, export, pdf |
| 包管理器 | npm |
| 认证方式 | OIDC 信任发布 |
资料来源：[manifest.json:1-30]()
---
## クイックスタート
### 相关页面
相关主题：[プロジェクト紹介](#introduction)
相关源码文件
以下源码文件用于生成本页说明：
- [CLAUDE.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/CLAUDE.md)
- [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
- [manifest.json](https://github.com/ie3jp/illustrator-mcp-server/blob/main/manifest.json)
- [src/tools/session.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/session.ts)
- [src/prompts/print-preflight-workflow.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/prompts/print-preflight-workflow.ts)
- [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)
# クイックスタート
## 概述
クイックスタート是 illustrator-mcp-server 的入门指南，旨在帮助用户快速了解并开始使用这个 MCP（Model Context Protocol）服务器。该项目使 AI 助手（如 Claude Code）能够直接控制 Adobe Illustrator 进行设计操作，包括文档读取、对象修改、SVG/PDF 导出以及印前检查等功能。
资料来源：[README.md:1-20]()
## 系统要求
### 支持的环境
| 组件 | 要求 |
|------|------|
| 操作系统 | macOS / Windows |
| Node.js | v18 或更高版本 |
| Adobe Illustrator | CC 2018 及以上版本 |
| AI 助手 | Claude Code / Claude Desktop |
资料来源：[CLAUDE.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/CLAUDE.md)
### Illustrator 版本配置
在 macOS 上如果同时运行多个 Illustrator 版本，可以使用 `set_illustrator_version` 工具指定要连接的版本：
```json
{
"tool": "set_illustrator_version",
"params": {
"version": "2024"
}
}
```
资料来源：[README.md:1-15](), [v1.3.2 发布说明](https://github.com/ie3jp/illustrator-mcp-server/releases/tag/v1.3.2)
## 架构概述
illustrator-mcp-server 采用客户端-服务端架构，通过 MCP 协议与 AI 助手通信，后端通过 AppleScript（macOS）或 PowerShell（Windows）调用 Illustrator 的 ExtendScript/JSX 引擎执行实际操作。
```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
```
资料来源：[README.es.md:1-20]()
## 工具分类总览
服务器提供 **70+** 个 MCP 工具，分为以下类别：
### 读取工具（21个）
| 工具 | 功能描述 |
|------|----------|
| `get_document_info` | 获取文档元数据（尺寸、颜色模式、配置文件等） |
| `get_artboards` | 获取画板信息（位置、尺寸、方向） |
| `get_layers` | 以树形结构返回图层 |
| `get_document_structure` | 完整树形结构：图层→组→对象 |
| `list_text_frames` | 文本框列表（字体、字号、样式名） |
| `get_text_frame_detail` | 特定文本框的所有属性 |
| `get_colors` | 颜色信息（色板、渐变、专色） |
| `get_path_items` | 路径/形状数据 |
| `get_groups` | 组、剪贴蒙版、复合路径结构 |
| `get_effects` | 效果和外观信息 |
| `get_images` | 嵌入/链接图像信息 |
| `get_symbols` | 符号定义和实例 |
| `get_overprint_info` | 叠印设置 |
| `get_separation_info` | 颜色分色信息 |
| `check_contrast` | WCAG 颜色对比度检查 |
| `extract_design_tokens` | 提取设计令牌 |
| `list_fonts` | 列出可用字体 |
资料来源：[README.md:20-80](), [manifest.json](https://github.com/ie3jp/illustrator-mcp-server/blob/main/manifest.json)
### 修改工具（38个）
| 工具 | 功能描述 |
|------|----------|
| `create_rectangle` | 创建矩形（支持圆角） |
| `create_ellipse` | 创建椭圆 |
| `create_line` | 创建线条 |
| `create_text_frame` | 创建文本框 |
| `create_path` | 创建自定义路径（含贝塞尔手柄） |
| `place_image` | 放置图像文件 |
| `modify_object` | 修改对象属性 |
| `convert_to_outlines` | 将文本转换为轮廓 |
| `align_objects` | 对齐和分布对象 |
| `manage_layers` | 管理图层 |
| `create_crop_marks` | 创建裁切线 |
| `replace_color` | 查找和替换颜色 |
| `group_objects` | 编组对象 |
| `ungroup_objects` | 解散组 |
资料来源：[README.md:80-150]()
### 导出工具（2个）
| 工具 | 功能描述 |
|------|----------|
| `export` | SVG/PNG/JPG 导出 |
| `export_pdf` | 印刷级 PDF 导出（含裁切线、出血） |
资料来源：[README.md:150-160]()
### 实用工具（3个）
| 工具 | 功能描述 |
|------|----------|
| `preflight_check` | 印前检查 |
| `check_text_consistency` | 文本一致性检查 |
| `set_workflow` | 设置工作流模式（web/print） |
资料来源：[README.ko.md:1-30]()
## 坐标系统
服务器自动从文档检测坐标系统，这是 v1.4.0 版本的重要改进：
| 文档类型 | 坐标系统 | 原点 | Y轴方向 |
|----------|----------|------|---------|
| CMYK / 印刷 | `document` | 左下角 | 向上 |
| RGB / 网页 | `artboard-web` | 画板左上角 | 向下 |
资料来源：[README.md:160-180](), [v1.4.0 发布说明](https://github.com/ie3jp/illustrator-mcp-server/releases/tag/v1.4.0)
### 工作流检测逻辑
```typescript
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` 工具：
```json
{
"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步完整印前检查流程：
```mermaid
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 的提示词选择器提供预建工作流模板：
| 模板 | 描述 |
|------|------|
| `quick-layout` | 粘贴文本内容，Claude 将其排列为标题、正文和说明文字 |
| `print-preflight-workflow` | 7步印前检查（文档→预检→叠印→分色→图像→颜色→文本） |
资料来源：[README.md:180-200]()
## 已知限制
| 限制项 | 说明 |
|--------|------|
| PDF/X-4 出血 | 无法通过 API 设置出血区域 |
| WebP 导出 | 不支持，建议使用 PNG 或 SVG |
| 日本式裁切线 | PDF 导出使用 TrimMark 命令方式 |
| 字体嵌入模式 | 无法直接控制嵌入模式（完整/子集） |
| 尺寸变体 | 仅支持等比缩放，文本可能需要手动调整 |
资料来源：[README.es.md:1-20]()
## 从源码编译
```bash
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](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
- 开发者文档：[CLAUDE.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/CLAUDE.md)
- 最新发布：[v1.5.1](https://github.com/ie3jp/illustrator-mcp-server/releases/tag/v1.5.1)
---
## システムアーキテクチャ
### 相关页面
相关主题：[JSXスクリプト実行メカニズム](#jsx-execution), [座標系とワークフロー](#coordinate-system)
相关源码文件
以下源码文件用于生成本页说明：
- [src/server.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/server.ts)
- [src/executor/jsx-runner.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/executor/jsx-runner.ts)
- [src/executor/file-transport.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/executor/file-transport.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/session.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/session.ts)
- [manifest.json](https://github.com/ie3jp/illustrator-mcp-server/blob/main/manifest.json)
# システムアーキテクチャ
## 概述
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]()
## 系统架构图
```mermaid
flowchart LR
AI["Claude / AI Assistant"] <-->|MCP Protocol| Server["MCP Server
(TypeScript/Node.js)"]
Server -->|生成临时脚本| Runner["run-{uuid}.scpt
或 .ps1"]
Server -->|生成 JSX 代码| JSX["script-{uuid}.jsx
(BOM UTF-8)"]
Server -->|写入参数| PF["params-{uuid}.json"]
Runner -->|execFile| osascript["osascript
(macOS)"]
Runner -->|execFile| PS["powershell.exe
(Windows)"]
osascript -->|do javascript| AI_App["Adobe Illustrator
(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 协议请求
- 解析工具调用参数
- 协调工具执行流程
- 返回结构化结果
```mermaid
flowchart TD
Request["MCP 请求
(工具名称 + 参数)"] --> Validate["参数验证
(Zod Schema)"]
Validate -->|验证通过| Generate["生成 JSX 代码"]
Validate -->|验证失败| Error["返回错误"]
Generate --> Execute["执行脚本"]
Execute --> Read["读取结果文件"]
Read --> Format["格式化响应"]
Format --> Response["MCP 响应"]
```
### 2. 工具执行器 (Tool Executor)
工具执行器负责管理所有 MCP 工具的注册和执行。工具按照功能分为以下几类：
| 类别 | 数量 | 功能描述 |
|------|------|----------|
| 读取工具 | 21 | 获取文档信息、图层结构、颜色、文本、图像等 |
| 修改工具 | 38 | 创建/修改对象、管理图层、颜色替换等 |
| 导出工具 | 2 | SVG/PNG/JPG 和 PDF 导出 |
| 实用工具 | 3 | 印前检查、文本一致性检查、工作流设置 |
资料来源：[src/tools/tool-executor.ts:1-50]()
### 3. 脚本执行器 (JSX Runner)
JSX Runner 负责跨平台脚本生成和执行，是实现 Illustrator 自动化通信的关键组件。
#### 执行流程
```mermaid
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: 返回执行结果
```
#### 平台差异
| 平台 | 执行方式 | 脚本格式 |
|------|----------|----------|
| macOS | `osascript` → AppleScript → JSX | `.scpt` 文件，包含 `do javascript` 命令 |
| Windows | `powershell.exe` → COM | `.ps1` 文件，使用 `DoJavaScript` 方法 |
资料来源：[src/executor/jsx-runner.ts:1-80]()
### 4. 文件传输层 (File Transport)
文件传输层负责临时文件的创建、写入和清理，确保脚本执行的安全性。
#### 临时文件生命周期
```mermaid
flowchart LR
subgraph 生命周期
Create["创建
(BOM UTF-8)"] --> Use["执行
JSX 脚本"] --> Cleanup["清理
(删除临时文件)"]
end
subgraph 临时文件类型
Script["script-{uuid}.jsx
JSX 执行代码"]
Params["params-{uuid}.json
输入参数"]
Result["result-{uuid}.json
执行结果"]
Runner["run-{uuid}.scpt/.ps1
执行器脚本"]
end
Create --> Script
Create --> Params
Create --> Runner
Use --> Result
Result --> Cleanup
```
#### 文件编码规范
所有 JSX 文件必须使用 **BOM UTF-8** 编码，以确保 Illustrator 正确解析多字节字符（如日文、中文）。
```typescript
// 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 版本的兼容性封装，是工具实现的基础。
#### 核心功能模块
| 模块 | 功能 | 兼容性处理 |
|------|------|------------|
| 坐标转换 | 在 artboard-web 和 document 坐标系之间转换 | 处理原点和 Y 轴方向差异 |
| 文档检测 | 检测文档颜色模式、标尺单位等 | 区分 CMYK/RGB 工作流程 |
| 对象操作 | 统一的路径、形状、文本操作接口 | 封装版本差异 |
| 错误处理 | 标准化错误格式和恢复机制 | 支持部分回滚 |
```javascript
// 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 助手通信：
```mermaid
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
```
### 请求格式
```typescript
interface ToolRequest {
name: string; // 工具名称
arguments: {
[key: string]: any; // 工具参数
coordinate_system?: 'artboard-web' | 'document';
};
}
```
### 响应格式
```typescript
interface ToolResponse {
success: boolean;
data: any; // 工具执行结果
coordinateSystem: 'artboard-web' | 'document';
error?: {
message: string;
code: string;
};
}
```
## 坐标系系统
系统自动检测文档类型并选择合适的坐标系，这是 v1.4.0 版本的重要改进。
### 坐标系对比
| 文档类型 | 坐标系标识 | 原点位置 | Y 轴方向 | 适用场景 |
|----------|-----------|----------|----------|----------|
| CMYK / 印刷 | `document` | 左下 | 向上 | 印刷设计 |
| RGB / Web | `artboard-web` | 左上 | 向下 | Web 设计 |
### 自动检测逻辑
```mermaid
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) 管理，确保在连续操作中保持一致：
```typescript
// 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 功能存在已知限制：
| 功能 | 限制说明 | 应对方案 |
|------|----------|----------|
| 实时效果参数 | 可检测但无法读取 | 使用替代属性检测 |
| 色彩配置文件 | 仅支持赋值，不支持转换 | 使用 PDF 预设 |
| 出血设置 | 无法读取 | 手动指定或使用默认值 |
| WebP 导出 | 不支持 | 使用 PNG 或 SVG |
| 日式裁切线 | 版本兼容性问题 | 使用 TrimMark 命令方式 |
| 字体嵌入模式 | 无法直接控制 | 使用 PDF 预设 |
## 安全性考虑
### 临时文件管理
1. **唯一标识**: 所有临时文件使用 UUID 命名，避免冲突
2. **自动清理**: 执行完成后立即删除临时文件
3. **文件权限**: 临时目录设置适当的读写权限
### 脚本执行隔离
- JSX 代码在 Illustrator 沙盒中执行
- 通过参数文件传递数据，减少直接代码注入风险
- 错误处理包含事务性回滚机制
## 扩展机制
### 工具注册流程
```mermaid
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スクリプト実行メカニズム
### 相关页面
相关主题：[システムアーキテクチャ](#architecture), [変更ツール](#modify-tools)
相关源码文件
以下源码文件用于生成本页说明：
- [src/executor/jsx-runner.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/executor/jsx-runner.ts)
- [src/executor/file-transport.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/executor/file-transport.ts)
- [src/jsx/helpers/common.jsx](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/jsx/helpers/common.jsx)
- [src/tools/session.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/session.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/modify/create-crop-marks.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/create-crop-marks.ts)
# JSXスクリプト実行メカニズム
## 概述
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：
```typescript
const executionId = crypto.randomUUID();
```
此 UUID 作为所有关联文件的命名空间，确保并发执行的隔离性。
资料来源：[src/executor/jsx-runner.ts:30-35]()
### 2. 参数与脚本生成
执行引擎接收工具参数，生成两类文件：
| 文件类型 | 命名格式 | 编码 | 内容 |
|---------|---------|------|------|
| JSX脚本 | `script-{uuid}.jsx` | UTF-8 with BOM | 可直接在 Illustrator 中执行的 ExtendScript 代码 |
| 参数文件 | `params-{uuid}.json` | UTF-8 | 工具参数、坐标系统设置、输出路径等元数据 |
参数文件结构示例：
```json
{
"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 引擎执行以下步骤：
```javascript
// 1. 读取参数文件
var params = readJsonFile(paramsPath);
// 2. 应用坐标系统设置
if (params.coordinate_system === "artboard-web") {
// 设置为 web 风格坐标系
} else {
// 使用文档原生坐标系
}
// 3. 执行主逻辑
var result = executeMainLogic(params);
// 4. 写入结果
writeResultFile(resultPath, result);
```
### 5. 结果回收
文件传输层监听结果文件写入：
```typescript
async function awaitResult(executionId: string, timeout: number): Promise {
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 执行机制的重要组成部分，服务器自动检测文档类型并应用相应坐标系：
| 文档类型 | 坐标系统 | 原点 | Y轴方向 |
|---------|---------|------|--------|
| CMYK / 印刷 | `document` | 左下 | 向上 |
| RGB / Web | `artboard-web` | 右上 | 向下 |
```typescript
async function resolveCoordinateSystem(requested?: string): Promise {
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` 提供跨版本兼容的底层操作封装：
```javascript
// 常见操作封装
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. **结果报告**：返回新画板尺寸、创建的裁剪标记组数量等
```typescript
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]()
## 已知限制
| 限制项 | 说明 | 变通方案 |
|-------|------|---------|
| WebP导出 | 不支持直接导出 | 使用 PNG 或 SVG |
| 日式裁剪标记 | PDF导出时使用 TrimMark 命令方式 | 导出后通过撤销删除标记 |
| 字体嵌入模式 | 无法直接控制（full/subset） | 使用 PDF 预设 |
| 尺寸变化 | 仅支持等比缩放 | 手动调整文本 |
## 版本历史相关修复
| 版本 | 修复内容 |
|------|---------|
| v1.5.1 | 修复 MCP Registry 自动发布的版本不匹配问题 |
| v1.4.0 | 修复所有文档强制使用 web 坐标系的问题，改为自动检测 |
| v1.3.2 | 修复 macOS 多版本 Illustrator 共存时的版本定位问题 |
| v1.2.9 | 修复捆绑版启动时 JSX 辅助文件路径缺失问题 |
## 错误处理
执行过程中可能出现的错误类型：
| 错误类型 | 原因 | 处理方式 |
|---------|------|---------|
| `ENOENT` | Illustrator 未运行或文件路径错误 | 自动启动 Illustrator 或提示检查路径 |
| `Timeout` | 脚本执行超时（默认30秒） | 增加超时阈值或分析脚本复杂度 |
| `JSXError` | JSX 代码执行错误 | 返回错误信息并提供堆栈跟踪 |
| `VersionMismatch` | 指定的 Illustrator 版本不可用 | 列出可用版本供选择 |
## 总结
JSXスクリプト実行メカニズム 通过以下设计实现可靠的多平台执行：
- **文件系统作为通信总线**：JSON 文件承载参数与结果，实现无状态解耦
- **平台适配层**：osascript/PowerShell 分别处理 macOS/Windows 的进程调用
- **坐标系统抽象**：隐藏 Illustrator 内部坐标差异，提供一致的 API 语义
- **版本感知执行**：支持设计环境中多版本 Illustrator 共存的现实场景
该机制是 MCP 服务器与 Illustrator 之间唯一的通信桥梁，其稳定性直接影响所有工具的可用性。
---
## 読み取りツール
### 相关页面
相关主题：[変更ツール](#modify-tools), [ユーティリティツール](#utility-tools)
相关源码文件
以下源码文件用于生成本页说明：
- [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-layers.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-layers.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/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/list-text-frames.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/list-text-frames.ts)
- [src/tools/read/extract-design-tokens.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/extract-design-tokens.ts)
- [src/tools/read/find-objects.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/find-objects.ts)
- [src/tools/read/check-contrast.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/check-contrast.ts)
- [src/common/illustrator-readonly.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/common/illustrator-readonly.ts)
# 読み取りツール
読み取りツールは、Adobe Illustrator ドキュメントから情報を取得するための MCP（Model Context Protocol）ツール群です。これらのツールはドキュメントの構造、颜色、テキスト、画像、オブジェクトプロパティなどを読み取り、構造化されたデータとして返します。読み取りツールはドキュメントを変更せず、情報の取得のみを行います。
## 概要
読み取りツールは全部で **21 個**のツールで構成されており、以下のカテゴリに分類されます：
| カテゴリ | ツール数 | 概要 |
|---------|---------|------|
| ドキュメント情報 | 4 | ドキュメントメタデータ、アートボード、レイヤー構造全体 |
| テキスト | 2 | テキストフレーム一覧と詳細属性 |
| 色・グラデーション | 2 | カラースウォッチ情報とデザインタトゥokens抽出 |
| オブジェクト | 4 | パスアイテム、グループ、エフェクト、選択オブジェクト |
| 画像・シンボル | 3 | 埋め込み/リンク画像情報、シンボル定義、ガイドライン |
| 印刷準備 | 2 | オーバープリント設定、色彩分離情報 |
| 検索・分析 | 3 | オブジェクト検索、WCAG コントラストチェック、座標変換 |
| ユーティリティ | 1 | 利用可能フォント一覧 |
## アーキテクチャ
```mermaid
graph TD
subgraph "MCP Server (Node.js)"
RT[読み取りツール群]
IR[illustrator-readonly.ts
共通基盤]
end
subgraph "Illustrator (ExtendScript/JSX)"
AI[Adobe Illustrator
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
ドキュメントの基本情報を取得します。ドキュメント名、サイズ、カラーコレクション等信息を返します。
```typescript
// 主な返り値
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
アートボードの情報を取得します。各アートボードの位置、サイズ、向きを返します。
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|-----|------|
| `artboardIndex` | number | いいえ | 特定のインクルを取得する場合のインデックス |
返り値の構造：
- `index`: アートボードインデックス
- `name`: アートボード名
- `rect`: 四隅の座標 [left, top, right, bottom]
- `width`: 幅 (pt)
- `height`: 高さ (pt)
- `orientation`: "landscape" | "portrait" | "square"
### get_layers
ドキュメントのレイヤー構造をツリー形式で返します。各レイヤーの名前、表示/非表示状態、ロック状態を含みます。
```typescript
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
ドキュメント内のすべてのテキストフレームを一覧で取得します。
| 返り値フィールド | 型 | 説明 |
|-----------------|-----|------|
| `uuid` | string | オブジェクト UUID |
| `name` | string | オブジェクト名 |
| `layerName` | string | 所属レイヤー名 |
| `kind` | string | テキスト種類 (pointText / areaText) |
| `font` | string | フォント名 |
| `fontSize` | number | フォントサイズ |
| `styleName` | string | スタイル名 |
| `contents` | string | テキスト内容（最初の255文字） |
资料来源：[src/tools/read/list-text-frames.ts:1-60]()
### get_text_frame_detail
特定のテキストフレームの詳細属性を取得します。カーニング、段落設定などを含むすべての属性を返します。
```typescript
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` | boolean | false | 印刷診断情報を含める |
`includeDiagnostics: true` の場合、印刷分析情報が追加されます：
- RGB と CMYK の混在警告
- Spot Color の使用状況
- 特色スウォッチの詳細
资料来源：[src/tools/read/get-colors.ts:1-150]()
### extract_design_tokens
デザインタトゥokens を抽出します。CSS カスタムプロパティ、JSON、または Tailwind 設定形式で出力できます。
| パラメータ | 型 | デフォルト | 説明 |
|-----------|-----|-----------|------|
| `format` | "css" \| "json" \| "tailwind" | "css" | 出力フォーマット |
```typescript
// 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
パスとシェイプデータを取得します。塗り、ストローク、アンカーポイント情報を含みます。
| 返り値フィールド | 型 | 説明 |
|-----------------|-----|------|
| `uuid` | string | オブジェクト UUID |
| `name` | string | オブジェクト名 |
| `type` | string | オブジェクトタイプ |
| `fillColor` | ColorValue | 塗り色 |
| `strokeColor` | ColorValue | 線色 |
| `strokeWidth` | number | 線幅 |
| `anchorPoints` | AnchorPoint[] | アンカーポイント配列 |
### get_groups
グループ、クリッピングマスク、複合パスの構造を取得します。
```typescript
interface GroupInfo {
uuid: string;
name: string;
type: "group" | "compoundPath" | "clippingMask";
itemCount: number;
children: PageItemInfo[];
}
```
### get_effects
エフェクトとアピアランス情報を取得します。不透明度、ブレンドモードなどを返します。
| 返り値フィールド | 型 | 説明 |
|-----------------|-----|------|
| `opacity` | number | 不透明度 (0-100) |
| `blendMode` | string | ブレンドモード |
| `isHidden` | boolean | 非表示状態 |
**制限**: ライブエフェクト（ドロップシャドウなど）のパラメータは検出できますが、読み取りはサポートされていません。
## 画像ツール
### get_images
埋め込みまたはリンク画像の情報取得します。
| パラメータ | 型 | デフォルト | 説明 |
|-----------|-----|-----------|------|
| `includePrintInfo` | boolean | false | 色空間不一致と倍率を含める |
| 返り値フィールド | 型 | 説明 |
|-----------------|-----|------|
| `uuid` | string | オブジェクト UUID |
| `fileName` | string | ファイル名 |
| `linkStatus` | "linked" \| "embedded" | リンク状態 |
| `actualPpi` | number | 実効解像度 (PPI) |
| `brokenLink` | boolean | リンク切れフラグ |
`includePrintInfo: true` の場合、追加情報が返されます：
- `colorSpaceMismatch`: カラースペース不一致
- `effectiveScale`: 実効倍率
资料来源：[src/tools/read/get-images.ts:1-100]()
## 印刷準備ツール
### get_overprint_info
オーバープリント設定と相关信息を取得します。K100/リッチブラックの検出と意図分類を含みます。
| 返り値フィールド | 型 | 説明 |
|-----------------|-----|------|
| `objectUuid` | string | オブジェクト UUID |
| `hasOverprint` | boolean | オーバープリント設定有無 |
| `fillOverprint` | boolean | 塗りオーバープリント |
| `strokeOverprint` | boolean | 線オーバープリント |
| `intentType` | string | 意図タイプ (intentional_k100, rich_black_overprint, likely_accidental) |
### get_separation_info
色彩分離情報を取得します。CMYK プロセスプレートとスポットカラープレートの使用回数が含まれます。
```typescript
interface SeparationInfo {
processPlates: {
cyan: number; // 使用回数
magenta: number;
yellow: number;
black: number;
};
spotPlates: {
name: string; // 特色名
count: number; // 使用回数
}[];
}
```
## 検索・分析ツール
### find_objects
条件に基づいてオブジェクトを検索します。名前、タイプ、色、フォントなどで検索可能です。
| パラメータ | 型 | 説明 |
|-----------|-----|------|
| `name` | string | オブジェクト名で部分一致 |
| `type` | string | オブジェクトタイプ |
| `color` | object | 色で検索 |
| `font` | string | フォント名で検索 |
```typescript
interface FindObjectsResult {
count: number;
matches: {
uuid: string;
name: string;
type: string;
layerName: string;
}[];
}
```
资料来源：[src/tools/read/find-objects.ts:1-80]()
### check_contrast
WCAG カラーコントラスト比をチェックします。手動指定または自動検出（重なり合うペア）が可能です。
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|-----|------|
| `foreground` | string | いいえ | 前景色 (hex) |
| `background` | string | いいえ | 背景色 (hex) |
返り値：
- `ratio`: コントラスト比 (1-21)
- `wcagAA`: { normalText: boolean, largeText: boolean }
- `wcagAAA`: { normalText: boolean, largeText: boolean }
資料来源：[src/tools/read/check-contrast.ts:1-60]()
### convert_coordinate
アートボード座標系とドキュメント座標系間の座標変換を行います。
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|-----|------|
| `x` | number | はい | X座標 |
| `y` | number | はい | Y座標 |
| `from` | string | はい | 変換元座標系 |
| `to` | string | はい | 変換先座標系 |
## ユーティリティツール
### list_fonts
Illustrator で利用可能なフォント一覧を取得します。ドキュメントを開く必要がありません。
```typescript
interface FontInfo {
family: string; // フォントファミリー名
name: string; // 完全フォント名
style: string; // スタイル (Regular, Bold, Italic, etc.)
type: string; // フォントタイプ
}
```
## 共通仕様
### coordinateSystem フィールド
すべての読み取りツールの返り値には `coordinateSystem` フィールドが含まれています。このフィールドはアクティブドキュメントの座標系を示します：
| ドキュメントタイプ | coordinateSystem | 原点 | Y軸 |
|------------------|-----------------|------|-----|
| CMYK / 印刷 | `document` | 左下 | 上方向 |
| RGB / Web | `artboard-web` | アートボード左上 | 下方向 |
资料来源：[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]()
## 制限事項
| 制限事項 | 詳細 |
|---------|------|
| ライブエフェクト | ドロップシャドウなどのエフェクトパラメータは検出可能だが読み取り不可 |
| カラープロファイル | 割り当てのみ可能 — 完全な変換は不可 |
| Bleed 設定 | 読み取り不可 (Illustrator API 制限) |
| WebP 画像 | サポートなし — PNG または SVG を使用 |
资料来源：[README.md - Known Limitations]()
---
## 変更ツール
### 相关页面
相关主题：[読み取りツール](#read-tools), [SVGインポート動作](#svg-import)
相关源码文件
以下源码文件用于生成本页说明：
- [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-ellipse.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/create-ellipse.ts)
- [src/tools/modify/create-line.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/create-line.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/create-path.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/create-path.ts)
- [src/tools/modify/place-image.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/place-image.ts)
- [src/tools/modify/modify-object.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/modify-object.ts)
- [src/tools/modify/import-svg-as-editable.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/import-svg-as-editable.ts)
- [src/tools/modify/convert-to-outlines.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/convert-to-outlines.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/manage-layers.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/manage-layers.ts)
- [src/tools/modify/duplicate-objects.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/duplicate-objects.ts)
- [src/tools/modify/set-z-order.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/set-z-order.ts)
- [src/tools/modify/move-to-layer.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/move-to-layer.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/replace-color.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/replace-color.ts)
- [src/tools/modify/create-document.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/create-document.ts)
- [src/tools/modify/open-document.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/open-document.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/close-document.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/close-document.ts)
- [src/tools/modify/assign-color-profile.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/assign-color-profile.ts)
- [src/tools/session.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/session.ts)
- [plugins/illustrator-preflight/skills/illustrator-preflight/references/preflight-rules.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/plugins/illustrator-preflight/skills/illustrator-preflight/references/preflight-rules.md)
# 変更ツール
変更ツール（Modify Tools）は、Illustrator MCP Serverにおける38個のツール群であり、Adobe Illustratorドキュメント内のオブジェクト作成・編集・構成管理を一括して担う主要機能セットです。AIアシスタント（Claude等）がIllustratorを直接操作し、矩形の生成からテキストフレーム配置、オブジェクト整列・グループ化まで包括的な編集能力を提供します。
## 概要
変更ツールは読み取りツール（Read Tools）と対になる存在であり、ドキュメントの状態確認ではなく能動的な変更操作を実行します。ツールは以下の5つのカテゴリに大きく分類されます：
| カテゴリ | ツール数 | 主な役割 |
|---------|---------|---------|
| 図形作成 | 5 | 四角形、楕円、直線、パス、テキストフレーム |
| オブジェクト編集 | 15 | プロパティ変更、アウトレイン化、整列、配置等 |
| レイヤー管理 | 1 | レイヤーの追加・名前変更・表示切替等 |
| ドキュメント管理 | 4 | 新規作成・開く・保存・閉じる |
| ユーティリティ | 13 | グループ化・複製・着色置換等 |
资料来源：[README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
## アーキテクチャ
変更ツールはIllustratorのExtendScript/JavaScript APIと連携し、以下のフローアーキテクチャで動作します：
```mermaid
flowchart TD
A[MCP Client
Claude等] -->|MCP Protocol| B[MCP Server
TypeScript/Node.js]
B -->|生成| C[run-{uuid}.scpt/.ps1]
B -->|生成| D[script-{uuid}.jsx
BOM UTF-8]
B -->|書き込み| E[params-{uuid}.json]
C -->|execFile| F[osascript
PowerShell]
F -->|DoJavaScript| G[Adobe Illustrator]
D -->|実行| G
E -->|読込| G
G -->|書き込み| H[result-{uuid}.json]
H -->|読込| B
```
资料来源：[README.md](README.md)
### 座標系の自動検出
変更ツールは全てドキュメントの座標系を自動検出します。色モードに基づいて適切な座標系が選択され、各ツールのレスポンスには`coordinateSystem`フィールドが含まれます：
| ドキュメント種別 | 座標系 | 原点 | Y軸方向 |
|-----------------|--------|------|--------|
| CMYK / 印刷 | `document` | 左下 | 上方向 |
| RGB / Web | `artboard-web` | アートボード左上 | 下方向 |
资料来源：[src/tools/session.ts:1-100](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/session.ts)
> v1.4.0以前では全ドキュメントに「左上が原点、Yは下向き」と伝える方式이었ため、CMYK印刷ドキュメントで意図しない結果を生じる問題がありました。v1.4.0では各ドキュメントに座標系の自己申告をさせる方式に改められました。
## 基本図形作成ツール
### create_rectangle
新規四角形を作成するツールです。角丸に対応し、塗り・線属性を任意で指定できます。
**パラメータ仕様：**
| パラメータ | 型 | 必須 | デフォルト | 説明 |
|-----------|-----|------|-----------|------|
| `x` | number | ○ | - | X座標（ピクセル） |
| `y` | number | ○ | - | Y座標（ピクセル） |
| `width` | number | ○ | - | 幅（ピクセル） |
| `height` | number | ○ | - | 高さ（ピクセル） |
| `corner_radius` | number | - | 0 | 角丸半径（ピクセル） |
| `fill_color` | object | - | なし | 塗り色設定 |
| `stroke_color` | object | - | なし | 線色設定 |
| `stroke_width` | number | - | 1 | 線幅（ピクセル） |
| `layer_name` | string | - | アクティブレイヤー | 配置先レイヤー名 |
| `artboard_index` | number | - | 0 | 対象アートボード（0起点） |
| `coordinate_system` | string | - | auto | `artboard-web` または `document` |
资料来源：[src/tools/modify/create-rectangle.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/create-rectangle.ts)
**fill_color / stroke_color オブジェクト形式：**
```json
{
"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](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/create-ellipse.ts)
### create_line
2点間の直線（パスアイテム）を作成するツールです。 stroke_colorとstroke_widthによる線属性の指定のみ可能です（fill_colorは無視されます）。
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `start_x` | number | ○ | 始点X座標 |
| `start_y` | number | ○ | 始点Y座標 |
| `end_x` | number | ○ | 終点X座標 |
| `end_y` | number | ○ | 終点Y座標 |
| `stroke_color` | object | - | 線色 |
| `stroke_width` | number | - | 線幅（デフォルト: 1） |
资料来源：[src/tools/modify/create-line.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/create-line.ts)
### create_path
ベジェハンドルを伴うカスタムパスを生成するツールです。 прямолинейные сегментыと曲線セグメントを組み合わせた複雑な形状を作成できます。
**パスポイント配列形式：**
```json
{
"path_points": [
{
"anchor": { "x": 100, "y": 100 },
"left_direction": { "x": 80, "y": 100 },
"right_direction": { "x": 120, "y": 100 },
"type": "smooth" | "corner" | "symmetric"
}
]
}
```
| ポイントタイプ | 説明 |
|--------------|------|
| `smooth` | 連続する曲線を形成、非対称でも可 |
| `corner` | 尖った角を形成 |
| `symmetric` | 左右のハンドルが対称長さを強制 |
资料来源：[src/tools/modify/create-path.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/create-path.ts)
### create_text_frame
テキストフレーム（ポイントテキストまたはエリアテキスト）を作成するツールです。
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `x` | number | ○ | X座標 |
| `y` | number | ○ | Y座標 |
| `contents` | string | - | テキスト内容 |
| `text_type` | string | - | `point` または `area`（デフォルト: `point`） |
| `width` | number | area時○ | エリアテキストの幅 |
| `height` | number | area時○ | エリアテキストの高さ |
| `font_family` | string | - | フォントファミリー名 |
| `font_size` | number | - | フォントサイズ（pt） |
| `fill_color` | object | - | テキスト塗り色 |
| `layer_name` | string | - | 配置先レイヤー |
| `coordinate_system` | string | - | 座標系指定 |
资料来源：[src/tools/modify/create-text-frame.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/create-text-frame.ts)
## オブジェクト編集ツール
### modify_object
既存オブジェクトのプロパティを変更する汎用的ツールです。変更可能なプロパティはオブジェクトタイプによって異なります。
**共通パラメータ：**
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `uuid` | string | ○ | 対象オブジェクトのUUID |
| `contents` | string | - | テキスト内容（テキストフレームのみ） |
| `fill_color` | object | - | 塗り色変更 |
| `stroke_color` | object | - | 線色変更 |
| `stroke_width` | number | - | 線幅変更 |
| `opacity` | number | - | 不透明度（0-100） |
| `blend_mode` | string | - | ブレンドモード |
资料来源：[src/tools/modify/modify-object.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/modify-object.ts)
### convert_to_outlines
テキストをアウトライン（パス）に変換する不可逆ツールです。フォント依存性を排除し、印刷入稿时可変性を高めます。
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `uuid` | string | ○ | 変換対象テキストのUUID |
| `target_uuids` | string[] | - | 複数指定时可変 |
> **警告**: この操作は元に戻せません。実行前にバックアップを推奨します。プリフライトチェックで非アウトラインテキストが検出された場合、印刷所に応じた判断が必要です。
资料来源：[src/tools/modify/convert-to-outlines.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/convert-to-outlines.ts)
资料来源：[plugins/illustrator-preflight/skills/illustrator-preflight/references/preflight-rules.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/plugins/illustrator-preflight/skills/illustrator-preflight/references/preflight-rules.md)
### place_image
画像ファイルをリンクまたは埋め込みで配置するツールです。
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `file_path` | string | ○ | 画像ファイルパス（SVGも可） |
| `x` | number | - | 配置X座標 |
| `y` | number | - | 配置Y座標 |
| `width` | number | - | 幅（省略時自動計算） |
| `height` | number | - | 高さ（省略時自動計算） |
| `link` | boolean | - | true: リンク、false: 埋め込み（デフォルト: true） |
| `layer_name` | string | - | 配置先レイヤー |
> **コミュニティ課題 #35**: SVGファイルを`place_image`に渡すことは技術的に可能ですが、結果として得られるのは編集可能なIllustratorオブジェクトではなく、配置されたアートワークになります。SVGを編集可能なオブジェクトとして取り込む場合は、後述の`import_svg_as_editable`の使用を検討してください。
资料来源：[src/tools/modify/place-image.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/place-image.ts)
### import_svg_as_editable
SVGアートワークを既存のIllustratorドキュメントに編集可能なオブジェクトとしてインポートする専用ツールです。
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `file_path` | string | ○ | SVGファイルパス |
| `x` | number | - | 配置X座標 |
| `y` | number | - | 配置Y座標 |
| `layer_name` | string | - | 配置先レイヤー |
资料来源：[src/tools/modify/import-svg-as-editable.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/import-svg-as-editable.ts)
```mermaid
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
複数のオブジェクトをグループ化するツールです。クリッピングマスクにも対応しています。
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `uuids` | string[] | ○ | グループ化するオブジェクトのUUID配列 |
| `clip_mask` | boolean | - | true: クリッピングマスクとしてグループ化 |
| `layer_name` | string | - | グループ配置先レイヤー |
资料来源：[src/tools/modify/group-objects.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/group-objects.ts)
### ungroup_objects
グループを解除し、子オブジェクトをリリースします。
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `uuid` | string | ○ | 解除対象グループのUUID |
### align_objects
複数のオブジェクトを整列・分布させるツールです。
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `uuids` | string[] | ○ | 整列対象UUID配列 |
| `align_to` | string | - | 整列基準（`selection`, `artboard`, `key_object`） |
| `align_type` | string | - | 整列方向（`left`, `right`, `center_h`, `top`, `bottom`, `center_v`） |
| `distribute_type` | string | - | 分布方向（`horizontal`, `vertical`） |
| `spacing` | number | - | 分布間隔 |
资料来源：[src/tools/modify/align-objects.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/align-objects.ts)
### duplicate_objects
オブジェクトを複製し、オプションでオフセット配置できます。
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `uuids` | string[] | ○ | 複製対象UUID配列 |
| `offset_x` | number | - | X方向オフセット |
| `offset_y` | number | - | Y方向オフセット |
| `repeat` | number | - | 繰り返し回数（デフォルト: 1） |
資料来源：[src/tools/modify/duplicate-objects.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/duplicate-objects.ts)
### set_z_order
オブジェクトのスタック順序（前後関係）を変更します。
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `uuids` | string[] | ○ | 対象UUID配列 |
| `direction` | string | ○ | `front` または `back` |
资料来源：[src/tools/modify/set-z-order.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/set-z-order.ts)
### move_to_layer
オブジェクトを異なるレイヤーに移動します。
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `uuids` | string[] | ○ | 移動対象UUID配列 |
| `target_layer` | string | ○ | 移動先レイヤー名 |
| `layer_action` | string | - | `add`: 存在しない場合作成 |
资料来源：[src/tools/modify/move-to-layer.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/move-to-layer.ts)
## レイヤー管理ツール
### manage_layers
レイヤーの追加・名前変更・表示/非表示・ロック/ロック解除・順序変更・削除を実行します。
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `action` | string | ○ | `add`, `rename`, `show`, `hide`, `lock`, `unlock`, `move_up`, `move_down`, `delete` |
| `layer_name` | string | - | レイヤー名 |
| `new_name` | string | rename時○ | 新規レイヤー名 |
| `target_index` | number | - | 移動先インデックス |
资料来源：[src/tools/modify/manage-layers.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/manage-layers.ts)
## カラーツール
### replace_color
ドキュメント全体で色を検索・置換するツールです。 容許範囲（tolerance）設定により、近似色の置換も可能です。
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `source_color` | object | ○ | 置換元色 |
| `target_color` | object | ○ | 置換先色 |
| `tolerance` | number | - | 類似度許容範囲（0-100、デフォルト: 0） |
资料来源：[src/tools/modify/replace-color.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/replace-color.ts)
### place_color_chips
ドキュメント内のユニークな色を抽出し、アートボード外部にカラーチップスウォッチとして配置します。
### assign_color_profile
カラープロファイルを割り当てます（値変換なし、 taggedのみ）。
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `profile_name` | string | ○ | プロファイル名（例: `Japan Color 2001 Coated`） |
资料来源：[src/tools/modify/assign-color-profile.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/assign-color-profile.ts)
## ドキュメント管理ツール
### create_document
新規Illustratorドキュメントを作成します。
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `width` | number | - | ドキュメント幅（mm、デフォルト: 100） |
| `height` | number | - | ドキュメント高さ（mmデフォルト: 100） |
| `color_mode` | string | - | `RGB` または `CMYK`（デフォルト: `RGB`） |
| `artboard_count` | number | - | アートボード数（デフォルト: 1） |
资料来源：[src/tools/modify/create-document.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/create-document.ts)
### open_document
ファイルパスからドキュメントを開きます。
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `file_path` | string | ○ | 開くファイルパス |
资料来源：[src/tools/modify/open-document.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/open-document.ts)
### save_document
ドキュメントを保存または名前を付けて保存します。`output_path`を省略すると、ドキュメントと同じフォルダに連番付きで自動保存されます。
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `output_path` | string | - | 保存先パス（省略時自動生成） |
> v1.2.12より、書き出しパス自動生成機能が追加されました。衝突回避のための連番付き命名が行われます。
资料来源：[src/tools/modify/save-document.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/save-document.ts)
### close_document
アクティブドキュメントを閉じます。
| パラメータ | 型 | 必須 | 説明 |
|-----------|-----|------|------|
| `save_changes` | boolean | - | true: 保存確認あり、false: 保存せずに閉じる |
## プリフライトとの連携
変更ツールはプリフライトチェックと密接に連携します。特に以下のシナリオでは、変更ツールがプリフライト問題の解决方案となります：
```mermaid
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](https://github.com/ie3jp/illustrator-mcp-server/blob/main/plugins/illustrator-preflight/skills/illustrator-preflight/references/preflight-rules.md)
| プリフライト問題 | 推奨変更ツール | 注意 |
|-----------------|---------------|------|
| 非アウトラインテキスト | `convert_to_outlines` | 不可逆操作、事前確認必須 |
| 白オーバープリント | `modify_object`（overprint: false） | 自動修復不可、デザイナー判断要 |
| RGB色（CMYK文書） | `replace_color` | 色味が変化する可能性あり |
| 低解像度画像 | `place_image`（高解像度ファイル指定） | 元ファイルの差し替えが必要 |
## ワークフロー使用例
### 自然言語によるレイアウト配置
```
ユーザー: ヘッダー、本文、キャプションとしてアートボード上にテキストを配置して
Claude: → create_text_frame を用いて配置
```
资料来源：[README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
### PDF/X-1a準拠のためのテキスト処理
```
ユーザー: このドキュメントはPDF/X-1a準拠か確認して
Claude: → preflight_check (target_pdf_profile: "x1a")
→ 非アウトラインテキスト検出時、convert_to_outlines を提供
```
## 制限事項と注意点
| 制限事項 | 説明 | 回避方法 |
|---------|------|---------|
| WebP書き出し非対応 | 直接WebPエクスポート不可 | PNGまたはSVGを使用 |
| フォント埋め込みモード制御不可 | フル/サブセット選択不可 | PDFプリセット経由 |
| 比例スケールのみ | `resize_for_variation`は縦横比固定 | テキストの手動調整後に要対応 |
| アートボードリサイズ非対応 | 塗り足し設定変更不可（API制限） | 手動設定が必要 |
资料来源：[README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
## 関連ツール群
| カテゴリ | ツール数 | 代表ツール |
|---------|---------|-----------|
| 読み取りツール | 21 | `get_document_info`, `get_layers`, `get_colors` |
| **変更ツール** | **38** | **本ページ記載的全ツール** |
| 書き出しツール | 2 | `export`, `export_pdf` |
| ユーティリティ | 3 | `preflight_check`, `check_text_consistency`, `set_workflow` |
---
## 書き出しツール
### 相关页面
相关主题：[ユーティリティツール](#utility-tools), [クイックスタート](#quick-start)
相关源码文件
以下源码文件用于生成本页说明：
- [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/modify/create-crop-marks.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/create-crop-marks.ts)
- [src/tools/registry.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/registry.ts)
- [src/tools/session.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/session.ts)
- [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/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]()
### 支持的格式
| 格式 | 类型 | 用途 |
|------|------|------|
| SVG | 矢量 | Web、编辑、可缩放图形 |
| PNG | 栅格 | Web、透明度支持 |
| JPG | 栅格 | 照片、压缩输出 |
### 参数说明
```typescript
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`
```mermaid
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 预设与配置
```typescript
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）
日本式トンボ（二重线）与西洋式（一重线）的处理方式：
| 样式 | 特征 | 实现方式 |
|------|------|----------|
| 日本式 | 二重线 | TrimMark コマンド方式 |
| 西洋式 | 一重线 | 标准裁切线 |
**重要**：PDF 输出的日本式裁切线使用 TrimMark コマンド方式实现，通过以下流程避免版本兼容性问题：
1. 生成裁切线作为文档路径
2. 执行导出
3. 通过 undo 删除裁切线
资料来源：[src/tools/export/export-pdf.ts:100-150]()
```mermaid
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]()
### 样式自动判定
| 语言/地区 | 样式 | 线条 |
|----------|------|------|
| ja / 日本 | 二重线 | Japanese double-line |
| 其他 | 一重线 | Western single-line |
### 参数说明
```typescript
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 自动处理
## 坐标系处理
### 自动检测机制
書き出し工具会自动检测文档坐标系：
| 文档类型 | 坐标系 | 原点 | Y轴方向 |
|----------|--------|------|---------|
| CMYK/印刷 | `document` | 左下 | 向上 |
| RGB/Web | `artboard-web` | アートボード左上 | 向下 |
所有工具响应都包含 `coordinateSystem` 字段，指示当前激活的坐标系。
资料来源：[src/tools/session.ts:60-100]()
### 坐标转换
`convert_coordinate` 工具可在不同坐标系之间转换坐标值：
```typescript
convert_coordinate(
x: number, // X 坐标
y: number, // Y 坐标
from_system: 'artboard-web' | 'document',
to_system: 'artboard-web' | 'document',
artboard_index?: number
)
```
## 使用场景与工作流
### 场景 1：Web 资产导出
```mermaid
graph TD
A[打开 RGB 文档] --> B[设置 workflow: web]
B --> C[选择导出对象]
C --> D[export format: svg/png]
D --> E[Web 优化输出]
```
### 场景 2：印刷 PDF 导出
```mermaid
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
```
## 版本历史关键修复
| 版本 | 修复内容 |
|------|----------|
| v1.2.12 | 修复 SVG 导出时 Illustrator 附加アートボード名导致验证失败的问题 |
| v1.2.12 | 新增导出路径自动生成功能 |
| v1.3.0 | 日本式裁切线改用 TrimMark 命令方式，避免版本兼容性问题 |
| v1.3.1 | 进一步完善日本式裁切线处理 |
## 已知限制
| 限制 | 说明 |
|------|------|
| WebP 导出 | 不支持，请使用 PNG 或 SVG |
| 出血设置 | 受 Illustrator API 限制，可能无法完全控制 |
| 字体嵌入模式 | 无法直接控制嵌入方式（full/subset），需通过 PDF 预设 |
| 尺寸变体 | 仅支持比例缩放，文本可能需要手动调整 |
资料来源：[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`
---
## ユーティリティツール
### 相关页面
相关主题：[読み取りツール](#read-tools), [書き出しツール](#export-tools)
相关源码文件
以下源码文件用于生成本页说明：
- [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-illustrator-version.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/utility/set-illustrator-version.ts)
- [src/tools/utility/set-workflow.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/utility/set-workflow.ts)
- [src/tools/session.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/session.ts)
- [plugins/illustrator-preflight/skills/illustrator-preflight/references/preflight-rules.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/plugins/illustrator-preflight/skills/illustrator-preflight/references/preflight-rules.md)
# ユーティリティツール
ユーティリティツールは、illustrator-mcp-serverにおける品質保証・セッション管理・座標系制御等功能を提供するツール群です。主に以下の3つのツールで構成されています：
| ツール名 | 機能概要 |
|---------|---------|
| `preflight_check` | 入稿前チェック（RGB混在、リンク切れ、低解像度、オーバープリント等问题の検出） |
| `check_text_consistency` | テキスト整合性チェック（プレースホルダ検出、表記揺らぎ分析） |
| `set_workflow` | ワークフローモード設定（web/print）による座標系の明示的なオーバーライド |
| `set_illustrator_version` | macOSで複数Illustratorバージョンが起動している際の接続先指定 |
これらのツールは、ドキュメントの編集・作成機能ではなく、分析・検証・環境設定を行う補助的な役割を担います。
---
## 1. プリフライトチェック（preflight_check）
### 概要
`preflight_check`は、印刷入稿前の品質検証を自動化するツールです。CMYKドキュメントにおける色空間問題、リンク切れ、低解像度画像、オーバープリント設定などの潜在的な問題を発見します。
資料来源：[src/tools/utility/preflight-check.ts:1-50]()
### チェック項目
プリフライトチェックは、以下の致命的な問題と警告を検出します：
#### 致命的問題（Critical）
| チェックID | 対象 | 問題内容 | 自動修復 |
|-----------|------|---------|---------|
| `rgb_in_cmyk` | RGB色オブジェクト | CMYKカラースペースでRGB色が使用されている | 不可 |
| `broken_link` | 配置画像 | ソースファイルが見つからない | 不可 |
| `low_resolution` | 画像 | 解像度不足（印刷: 300dpi、Web: 72dpi） | 不可 |
| `white_overprint` | 白オブジェクト | 白色+オーバープリント有効で印刷時に消える | 不可 |
| `transparency_overprint` | 透明オブジェクト | PDF/X-1aでは透明度は допускается不允许 | 条件付き |
資料来源：[plugins/illustrator-preflight/skills/illustrator-preflight/references/preflight-rules.md:1-80]()
#### 警告（Warnings）
| チェックID | 対象 | 説明 |
|-----------|------|-----|
| `non_outlined_text` | テキストフレーム | アウトライン化されていないテキスト |
| `spot_color` | スポットカラー | 特別色スウォッチの使用（意図確認が必要） |
| `transparency` | 透明度オブジェクト | 透明度設定のあるオブジェクト |
| `spot_transparency` | スポット+透明 | スポット色に透明度設定がある場合の色変換リスク |
資料来源：[plugins/illustrator-preflight/skills/illustrator-preflight/references/preflight-rules.md:80-120]()
### プリフライトワークフロー
AI驅動のプリフライトチェックは、7ステップの検証プロセスを実行します：
```mermaid
graph TD
A[ドキュメント開始] --> B[Step 1: ドキュメント検証]
B --> C[Step 2: プリフライトルール適用]
C --> D[Step 3: オーバープリント検査]
D --> E[Step 4: 色分離確認]
E --> F[Step 5: 画像品質検証]
F --> G[Step 6: カラーバリデーション]
G --> H[Step 7: テキスト整合性]
H --> I{問題の分類}
I -->|Critical| J[報告 + 修復提案]
I -->|Warning| K[報告 + 文脈確認]
I -->|Info| L[情報提供]
J --> M[終了]
K --> M
L --> M
```
資料来源：[plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md:1-60]()
### レポート形式
プリフライト結果は以下のように構造化されて出力されます：
```
## Preflight Results: [document name]
### Critical Issues (X items)
- UUID: xxx, 説明, 推奨アクション
### Warnings (X items)
- 文脈依存のガイダンス
### Info (X items)
- 简要メモ
### Summary
- Total issues: X critical, X warnings, X info
- Submission ready: Yes/No
```
自動修復可能な問題（例：白オーバープリント）については、修復提案が即座に提示されます。
資料来源：[plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md:40-80]()
### 使用例
```json
{
"tool": "preflight_check",
"arguments": {
"artboard_index": 0,
"dpi_threshold": 300,
"include_diagnostics": true
}
}
```
---
## 2. テキスト整合性チェック（check_text_consistency）
### 概要
`check_text_consistency`は、ドキュメント内のテキストフレームを分析し、以下の問題を検出します：
- プレースホルダ/ダミーテキスト
- 表記揺らぎパターン（片仮名の長音、 全角/半角）
- 波ダッシュ/チルダの混在
資料来源：[src/tools/utility/check-text-consistency.ts:40-70]()
### 検出パターン
#### ダミーテキスト検出
以下のパターンがダミーテキストとして検出されます：
| パターン | 例 |
|---------|-----|
| Lorem ipsum系 | "Lorem ipsum dolor sit amet" |
| 住所形式 | "東京都渋谷区..." |
| 名前形式 | "山田 太郎"、"John Smith" |
| 日付形式 | "2024/01/01"、"2024年1月1日" |
| 連番 | "Text 1"、"Item 001" |
| 記号のみ | "---"、"===、"★★" |
資料来源：[src/tools/utility/check-text-consistency.ts:20-40]()
#### 表記揺らぎ検出
| 分類 | 問題例 |
|------|--------|
| 片仮名長音 | 「コーヒー」vs「|Coffee」 |
| 全角/半角混在 | 「ＡＢＣ」vs「ABC」 |
| ダッシュ種 | 「〜」(波ダッシュ) vs 「―」(ダーシ) |
### 出力形式
```json
{
"totalFrames": 15,
"mechanicalChecks": {
"_reliability": "deterministic",
"dummyTexts": [
{
"uuid": "xxx",
"text": "Lorem ipsum dolor sit amet",
"layerName": "Layer 1",
"artboardIndex": 0
}
],
"knownVariations": [
{
"type": "dash",
"instances": ["〜", "―"],
"context": "..."
}
]
},
"allTexts": [
{
"uuid": "xxx",
"contents": "実際のテキスト内容",
"layerName": "Layer 1",
"artboardIndex": 0
}
]
}
```
資料来源：[src/tools/utility/check-text-consistency.ts:70-100]()
### LLM分析の留意点
`allTexts`フィールドには全テキスト内容が含まれるため、LLM驅動の更深層分析が可能です。ただし以下の点に注意が必要です：
- 正規表現パターンでは検出できない誤字・脱字
- バージョン不一致の検出
- 不整合な用語統一
> ⚠️ AI分析は万能ではありません。最終的なテキストレビューは人間の確認が必要です。
---
## 3. ワークフロー設定（set_workflow）
### 概要
`set_workflow`は、ワークフローモード（web/print）を明示的に設定し、座標系の自動検出結果をオーバーライドします。
資料来源：[src/tools/utility/set-workflow.ts:1-30]()
### 座標系の自動検出
illustrator-mcp-serverは、ドキュメントの特性に基づいて座標系を自動検出します：
| ドキュメント種別 | カラーモード | 座標系 | 原点 | Y軸方向 |
|----------------|------------|--------|------|--------|
| CMYK / 印刷 | CMYK | `document` | 左下 | 上向き |
| RGB / Web | RGB | `artboard-web` | アートボード左上 | 下向き |
資料来源：[src/tools/session.ts:80-120]()
### ワークフロー検出ロジック
```mermaid
graph LR
A[ドキュメント信号取得] --> B{カラーモード判定}
B -->|CMYK| C[印刷ワークフロー]
B -->|RGB| D{ルーラー単位判定}
D -->|px| E[Webワークフロー]
D -->|mm/cm| C
E --> F[座標系: artboard-web]
C --> G[座標系: document]
```
検出信号には以下が含まれます：
- `colorMode`: CMYK / RGB
- `rulerUnits`: px / mm / cm / inch
- `rasterEffectResolution`: ラスタ効果解像度
- `colorProfile`: カラープロファイル名
資料来源：[src/tools/session.ts:120-150]()
### 使用方法
```json
{
"tool": "set_workflow",
"arguments": {
"workflow": "print"
}
}
```
#### パラメータ
| パラメータ | 型 | 説明 |
|-----------|-----|------|
| `workflow` | `"web"` \| `"print"` | ワークフローモード |
### v1.4.0での改善
v1.4.0では、座標系の自動検出ロジックが改善されました。以前のバージョンでは、すべてのドキュメントに「左上原点・Y軸下向き」を適用していたため、CMYK印刷ドキュメントで意図しない結果になる問題がありました。
> すべてのドキュメントに「左上が原点、Yは下向きね」と言い聞かせてました。印刷入稿するCMYKドキュメントにも。今はちゃんと「あなたはどちら育ち？」って聞いてから決めてます。
資料来源：[src/tools/session.ts:50-80]()
---
## 4. Illustratorバージョン指定（set_illustrator_version）
### 概要
`set_illustrator_version`は、macOSで複数バージョンのIllustratorが同時起動している場合に、接続先のバージョンを明示的に指定します。
資料来源：[src/tools/utility/set-illustrator-version.ts:1-40]()
### 問題背景
macOS環境では、複数のIllustratorバージョン（例：Illustrator 2023、Illustrator 2024）を同時に起動できます。デフォルトでは、最後に起動したインスタンスに接続されますが、`set_illustrator_version`を使用することで意図したバージョンに確実接続できます。
資料来源：[社区动态 - v1.3.2]()
### 使用方法
```json
{
"tool": "set_illustrator_version",
"arguments": {
"version": "2024"
}
}
```
#### パラメータ
| パラメータ | 型 | 説明 |
|-----------|-----|------|
| `version` | `string` | Illustratorバージョン（例："2023"、"2024"） |
### アーキテクチャ
```mermaid
graph TD
A[MCP Server] -->|set_illustrator_version| B{バージョン指定}
B --> C[osascript
macOS]
B --> D[powershell.exe
Windows]
C --> E{Illustrator 2023}
D --> E
C --> F{Illustrator 2024}
D --> F
E -->|接続| G[選択したバージョンに
スクリプト実行]
F -->|接続| G
```
---
## 5. ユーティリティツールの連携
ユーティリティツールは、個別に使用することもできますが連携することで効果的なワークフローを構築できます：
```mermaid
graph LR
A[set_workflow] -->|座標系設定| B[ドキュメント操作]
B --> C[check_text_consistency]
C -->|全テキスト取得| D[LLM分析]
D --> E{問題検出}
E -->|プレースホルダ| F[modify_object]
E -->|表記揺らぎ| G[テキスト修正提案]
B --> H[preflight_check]
H -->|Critical問題| I[修正対応]
H -->|Warning| J[確認・承認]
I --> K[最終確認]
J --> K
G --> K
K --> L[export_pdf]
```
### 推奨ワークフロー例
#### 印刷入稿前チェック
1. `set_workflow` で `print` を指定
2. `check_text_consistency` でテキスト確認
3. `preflight_check` で品質検証
4. 必要に応じて `convert_to_outlines` でテキストアウトライン化
5. `export_pdf` で最終書き出し
資料来源：[plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md:30-50]()
---
## 6. 制限事項と既知の問題
### プリフライトチェックの制限
| 項目 | 説明 |
|------|------|
| 出血領域 | искусствует APIの制限により出血領域の詳細な検証不可 |
| WebPエクスポート | サポート外（PNGまたはSVGを使用） |
| フォント埋め込みモード | 直接制御不可（PDFプリセットを使用） |
| テキストバリアント | アウトライン化のみ（合成可変フォント等） |
資料来源：[plugins/illustrator-preflight/skills/illustrator-preflight/references/preflight-rules.md:100-130]()
### set_workflowの制限
- あくまでOverrides自動検出結果であり、Illustrator本身的座標系は変更しません
- セッション単位で有效的、セッション終了後は自動検出にフォールバックします
資料来源：[src/tools/session.ts:40-50]()
### テキスト整合性チェックの限界
- 正規表現ベースの檢測ため、AI分析では见逃しが発生する可能性があります
- 複雑な專業用語の不整合は人間のレビューが必要です
---
## 7. 関連コミュニティ課題
### SVGインポート動作の明確化（Issue #35）
SVGアートワークを編集可能なオブジェクトとして取り込む場合、`place_image`にSVGを渡すと思った通りに動作しない問題がありました。適切なインポート方法の明確化が求められています。
> SVGアートワークを既存のIllustratorドキュメントに編集可能なオブジェクトとして取り込む際、どのMCP操作を使うべきかが分かりにくい状況でした。
---
## まとめ
ユーティリティツールは、illustrator-mcp-serverにおける品質保証と環境設定の要となるコンポーネントです。主な特徴：
| 特徴 | 説明 |
|------|------|
| プリフライト | 印刷入稿前の問題を自動検出 |
| テキスト分析 | プレースホルダ・表記揺らぎを検出 |
| 座標系制御 | Web/Printモードで適切に切り替え |
| バージョン指定 | 複数Illustrator環境での確実な接続 |
これらのツールを活用することで、AI驅動のIllustrator操作でも品質の高い印刷入稿用データを効率的に作成できます。
---
## 座標系とワークフロー
### 相关页面
相关主题：[JSXスクリプト実行メカニズム](#jsx-execution), [システムアーキテクチャ](#architecture)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/session.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/session.ts)
- [src/tools/utility/set-workflow.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/utility/set-workflow.ts)
- [src/tools/read/convert-coordinate.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/convert-coordinate.ts)
- [src/tools/modify/shared.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/shared.ts)
- [src/tools/utility/check-text-consistency.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/utility/check-text-consistency.ts)
# 座標系とワークフロー
## 概述
illustrator-mcp-server 实现了双坐标系自动切换机制，根据文档类型（CMYK/印刷或RGB/Web）智能选择最适合的坐标系统。该系统确保 AI 操作 Illustrator 时，坐标值的语义与用户的预期一致，避免因坐标系差异导致的定位错误。
核心设计原则：
- **自动检测优先**：系统自动从文档属性推断坐标系
- **手动覆盖能力**：通过 `set_workflow` 工具显式指定工作模式
- **统一抽象接口**：所有工具通过 `coordinateSystemSchema` 共享坐标系参数定义
资料来源：[src/tools/session.ts:40-55]()
## 坐标系统类型
### 系统对比表
| 属性 | `artboard-web` | `document` |
|------|----------------|------------|
| **适用场景** | RGB / Web | CMYK / 印刷 |
| **原点位置** | 活动画板左上角 | 画布左下角 |
| **Y轴方向** | 向下为正 | 向上为正 |
| **典型用户** | Web 设计师、UI 开发者 | 印刷设计师 |
| **单位** | 像素 (px) | 毫米/cm |
资料来源：[src/tools/session.ts:48-60]()
### 工作流信号检测
系统通过分析文档的多维度属性来判断工作流类型：
```mermaid
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
手动设置工作流模式，覆盖自动检测结果。
**参数定义**：
| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `workflow` | `web` \| `print` | 否 | 手动指定工作流类型 |
| `coordinate_system` | `artboard-web` \| `document` | 否 | 直接指定坐标系 |
**返回值结构**：
```typescript
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`
```typescript
// 降级伪代码
try {
return await autoDetectCoordinateSystem();
} catch {
return 'artboard-web'; // 最终降级值
}
```
资料来源：[src/tools/session.ts:55-65]()
## 共享架构
### coordinateSystemSchema
所有工具统一导入此 Schema 定义，避免重复声明：
```typescript
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 工具函数
异步解析坐标系统的标准方法：
```typescript
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` 字段，指示当前活跃的坐标系：
```json
{
"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 | 修复坐标系统一锅端问题，改为按文档分别检测 |
| v1.3.0 | 初始版本实现双坐标系支持 |
v1.4.0 之前，系统向所有文档统一声明「左上原点、Y轴向下」，导致 CMYK 文档出现坐标语义错误。现版本会先询问文档类型，再决定坐标系。
资料来源：[v1.4.0 Release Notes](https://github.com/ie3jp/illustrator-mcp-server/releases/tag/v1.4.0)
---
## SVGインポート動作
### 相关页面
相关主题：[変更ツール](#modify-tools), [書き出しツール](#export-tools)
相关源码文件
以下源码文件用于生成本页说明：
- [src/tools/modify/import-svg-as-editable.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/import-svg-as-editable.ts)
- [src/tools/modify/place-image.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/place-image.ts)
- [src/tools/session.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/session.ts)
- [src/tools/utility/check-text-consistency.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/utility/check-text-consistency.ts)
- [manifest.json](https://github.com/ie3jp/illustrator-mcp-server/blob/main/manifest.json)
- [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)
# 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 导入动作的关键在于区分两种截然不同的文件处理方式：
| 处理方式 | 目标工具 | 结果类型 | 可编辑性 | 适用场景 |
|----------|----------|----------|----------|----------|
| **可编辑 SVG 导入** | `import_svg_as_editable` | 原生 Illustrator 对象（路径、文本、组） | 完全可编辑 | 需要进一步修改 SVG 内容 |
| **图片占位** | `place_image` | 链接或嵌入的图片 | 不可编辑（需转换为轮廓） | 仅展示、不需修改 |
资料来源：[src/tools/modify/import-svg-as-editable.ts:1-30]()
## 工具架构
### 工具注册与架构
SVG 导入功能通过 `import_svg_as_editable` 工具实现，该工具在 MCP 服务器中注册并执行以下操作流程：
```mermaid
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` 工具接受以下参数：
| 参数名 | 类型 | 必填 | 默认值 | 说明 |
|--------|------|------|--------|------|
| `file_path` | string | 是 | - | SVG 文件的绝对路径 |
| `coordinate_system` | enum | 否 | auto | 坐标系：`artboard-web` 或 `document` |
| `artboard_index` | number | 否 | 0 | 目标画板的索引（0-based） |
| `position` | object | 否 | 自动定位 | 放置位置 { x, y } |
资料来源：[src/tools/modify/import-svg-as-editable.ts:30-80]()
## 工作流程与坐标系统
### 自动坐标系统检测
服务器会根据文档类型自动选择合适的坐标系统：
| 文档类型 | 坐标系统 | 原点位置 | Y轴方向 |
|----------|----------|----------|---------|
| CMYK / 印刷 | `document` | 左下角 | 向上 |
| RGB / 网页 | `artboard-web` | 画板左上角 | 向下 |
资料来源：[src/tools/session.ts:80-120]()
SVG 导入时坐标系统的选择会影响对象的放置位置计算。`artboard-web` 系统原点位于画板左上角，Y轴向下递增；`document` 系统原点位于文档左下角，Y轴向上递增。
### 导入后的 UUID 映射机制
导入完成后，工具返回一个 UUID 映射表，其中包含 SVG 中每个对象的 UUID 与 Illustrator 原生对象路径的对应关系。这个映射对于后续通过 `modify_object` 等工具操作导入的对象至关重要。
```json
{
"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 的关键区别
### 场景对比
```mermaid
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[完全可编辑所有元素]
```
### 功能对比表
| 功能特性 | `import_svg_as_editable` | `place_image` |
|----------|-------------------------|---------------|
| 支持 SVG | ✅ | ⚠️ 可放置但非编辑性 |
| 支持 PNG/JPG/PSD | ❌ | ✅ |
| 返回对象 UUID | ✅ | ❌（仅返回图片引用） |
| 文本保持可编辑 | ✅ | ❌（转换为轮廓） |
| 路径保持可编辑 | ✅ | ❌ |
| 组结构保留 | ✅ | ❌ |
| 支持后续修改 | ✅ | ❌ |
资料来源：[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` 确认当前文档的坐标系统：
```typescript
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]()
## 限制与已知问题
| 限制项 | 说明 | 状态 |
|--------|------|------|
| 复杂 SVG 特性 | 某些 SVG 滤镜、动画、foreignObject 可能无法完美转换 | 已知限制 |
| 字体映射 | SVG 中使用的字体在目标系统不可用时可能回退 | 需手动检查 |
| 符号实例 | SVG 符号（symbol）可能展开为普通对象 | 设计决定 |
| Windows 兼容性 | Windows 版本使用 PowerShell 自动化，可能存在路径格式差异 | v1.4.0 已改进 |
资料来源：[manifest.json:1-30]()
## 版本历史相关变更
| 版本 | 变更内容 |
|------|----------|
| v1.4.0 | 修复了坐标系统自动检测问题，CMYK 文档不再错误使用 `artboard-web` 坐标系统 |
| v1.3.x | 增强了 macOS 多版本 Illustrator 同时运行时的版本定位功能 |
| v1.2.12 | 修复了 SVG 导出时 Illustrator 附加画板名导致验证失败的问题 |
资料来源：[src/tools/session.ts:50-80]()
## 相关工具链
SVG 导入后，通常需要配合以下工具完成完整工作流：
| 工具名称 | 功能 | 使用时机 |
|----------|------|----------|
| `modify_object` | 修改已导入对象的属性 | 调整位置、颜色、样式 |
| `get_document_structure` | 获取文档结构树 | 确认导入结果 |
| `group_objects` | 将多个对象分组 | 需要统一管理时 |
| `align_objects` | 对齐与分布 | 排版调整 |
| `convert_to_outlines` | 文本转轮廓 | 最终输出前（非可逆操作） |
| `check_text_consistency` | 文本一致性检查 | 导入包含文本的 SVG 后 |
资料来源：[src/tools/utility/check-text-consistency.ts:1-50]()
## 快速参考
### 调用示例
```typescript
// 导入 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} 个对象`);
}
```
### 错误代码参考
| 错误码 | 含义 | 解决方案 |
|--------|------|----------|
| `FILE_NOT_FOUND` | SVG 文件不存在 | 检查 file_path 是否正确 |
| `INVALID_SVG` | SVG 文件格式无效 | 用 Illustrator 重新保存 SVG |
| `PERMISSION_DENIED` | 缺少文件访问权限 | 检查文件权限设置 |
| `COORDINATE_ERROR` | 坐标系统不匹配 | 确认文档类型并选择正确坐标系 |
---
**最后更新**：基于 illustrator-mcp-server v1.5.1 版本编写。
---
---
## Doramagic 踩坑日志
项目：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