{
"canonical_name": "ie3jp/illustrator-mcp-server",
"compilation_id": "pack_c692de4ed6b04e4b802b3f9c03021ef9",
"created_at": "2026-05-25T04:43:26.318943+00:00",
"created_by": "project-pack-compiler",
"feedback": {
"carrier_selection_notes": [
"viable_asset_types=mcp_config, recipe, host_instruction, eval, preflight",
"recommended_asset_types=mcp_config, recipe, host_instruction, eval, preflight"
],
"evidence_delta": {
"confirmed_claims": [
"identity_anchor_present",
"capability_and_host_targets_present",
"install_path_declared_or_better"
],
"missing_required_fields": [],
"must_verify_forwarded": [
"Run or inspect `npx illustrator-mcp-server` in an isolated environment.",
"Confirm the project exposes the claimed capability to at least one target host."
],
"quickstart_execution_scope": "allowlisted_sandbox_smoke",
"sandbox_command": "npx illustrator-mcp-server",
"sandbox_container_image": "node:22-slim",
"sandbox_execution_backend": "docker",
"sandbox_planner_decision": "deterministic_isolated_install",
"sandbox_validation_id": "sbx_dc1b829f1ed647059d71e7bec5d91eab"
},
"feedback_event_type": "project_pack_compilation_feedback",
"learning_candidate_reasons": [],
"template_gaps": []
},
"identity": {
"canonical_id": "project_e25557c3aff7e4de9523b4220a2fd12a",
"canonical_name": "ie3jp/illustrator-mcp-server",
"homepage_url": null,
"license": "unknown",
"repo_url": "https://github.com/ie3jp/illustrator-mcp-server",
"slug": "illustrator-mcp-server",
"source_packet_id": "phit_9b1b81ba794342a68d0ac649c338c293",
"source_validation_id": "dval_4519fc73675449d6afd2f4a0610dfb93"
},
"merchandising": {
"best_for": "需要工具连接与集成能力，并使用 mcp_host的用户",
"github_forks": null,
"github_stars": null,
"one_liner_en": "**🇺🇸 English** | [🇯🇵 日本語](README.ja.md) | [🇨🇳 简体中文](README.zh-CN.md) | [🇰🇷 한국어](README.ko.md) | [🇪🇸 Español](README.es.md) | [🇩🇪 Deutsch](README.de.md) | [🇫🇷 Français](README.fr.md) | [🇵🇹 Português (BR)](README.pt-BR.md)",
"one_liner_zh": "**🇺🇸 English** | [🇯🇵 日本語](README.ja.md) | [🇨🇳 简体中文](README.zh-CN.md) | [🇰🇷 한국어](README.ko.md) | [🇪🇸 Español](README.es.md) | [🇩🇪 Deutsch](README.de.md) | [🇫🇷 Français](README.fr.md) | [🇵🇹 Português (BR)](README.pt-BR.md)",
"primary_category": {
"category_id": "tool-integrations",
"confidence": "high",
"name_en": "Tool Integrations",
"name_zh": "工具连接与集成",
"reason": "matched_keywords:mcp, server, github"
},
"target_user": "使用 mcp_host, claude, claude_code 等宿主 AI 的用户",
"title_en": "illustrator-mcp-server",
"title_zh": "illustrator-mcp-server 能力包",
"visible_tags": [
{
"label_en": "Browser Agents",
"label_zh": "浏览器 Agent",
"source": "repo_evidence_project_characteristics",
"tag_id": "product_domain-browser-agents",
"type": "product_domain"
},
{
"label_en": "Web Task Automation",
"label_zh": "网页任务自动化",
"source": "repo_evidence_project_characteristics",
"tag_id": "user_job-web-task-automation",
"type": "user_job"
},
{
"label_en": "Natural-language Web Actions",
"label_zh": "自然语言网页操作",
"source": "repo_evidence_project_characteristics",
"tag_id": "core_capability-natural-language-web-actions",
"type": "core_capability"
},
{
"label_en": "Node-based Workflow",
"label_zh": "节点式流程编排",
"source": "repo_evidence_project_characteristics",
"tag_id": "workflow_pattern-node-based-workflow",
"type": "workflow_pattern"
},
{
"label_en": "Evaluation Suite",
"label_zh": "评测体系",
"source": "repo_evidence_project_characteristics",
"tag_id": "selection_signal-evaluation-suite",
"type": "selection_signal"
}
]
},
"packet_id": "phit_9b1b81ba794342a68d0ac649c338c293",
"page_model": {
"artifacts": {
"artifact_slug": "illustrator-mcp-server",
"files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json",
"REPO_INSPECTION.md",
"CAPABILITY_CONTRACT.json",
"EVIDENCE_INDEX.json",
"CLAIM_GRAPH.json"
],
"required_files": [
"PROJECT_PACK.json",
"QUICK_START.md",
"PROMPT_PREVIEW.md",
"HUMAN_MANUAL.md",
"AI_CONTEXT_PACK.md",
"BOUNDARY_RISK_CARD.md",
"PITFALL_LOG.md",
"REPO_INSPECTION.json"
]
},
"detail": {
"capability_source": "Project Hit Packet + DownstreamValidationResult",
"commands": [
{
"command": "npx illustrator-mcp-server",
"label": "Node.js / npx · 官方安装入口",
"source": "https://github.com/ie3jp/illustrator-mcp-server#readme",
"verified": true
}
],
"display_tags": [
"浏览器 Agent",
"网页任务自动化",
"自然语言网页操作",
"节点式流程编排",
"评测体系"
],
"eyebrow": "工具连接与集成",
"glance": [
{
"body": "判断自己是不是目标用户。",
"label": "最适合谁",
"value": "需要工具连接与集成能力，并使用 mcp_host的用户"
},
{
"body": "先理解能力边界，再决定是否继续。",
"label": "核心价值",
"value": "**🇺🇸 English** | [🇯🇵 日本語](README.ja.md) | [🇨🇳 简体中文](README.zh-CN.md) | [🇰🇷 한국어](README.ko.md) | [🇪🇸 Español](README.es.md) | [🇩🇪 Deutsch](README.de.md) | [🇫🇷 Français](README.fr.md) | [🇵🇹 Português (BR)](README.pt-BR.md)"
},
{
"body": "未完成验证前保持审慎。",
"label": "继续前",
"value": "publish to Doramagic.ai project surfaces"
}
],
"guardrail_source": "Boundary & Risk Card",
"guardrails": [
{
"body": "Prompt Preview 只展示流程，不证明项目已安装或运行。",
"label": "Check 1",
"value": "不要把试用当真实运行"
},
{
"body": "mcp_host, claude, claude_code",
"label": "Check 2",
"value": "确认宿主兼容"
},
{
"body": "publish to Doramagic.ai project surfaces",
"label": "Check 3",
"value": "先隔离验证"
}
],
"mode": "mcp_config, recipe, host_instruction, eval, preflight",
"pitfall_log": {
"items": [
{
"body": "项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。",
"category": "配置坑",
"evidence": [
"capability.host_targets | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | host_targets=mcp_host, claude, claude_code"
],
"severity": "medium",
"suggested_check": "列出会写入的配置文件、目录和卸载/回滚步骤。",
"title": "可能修改宿主 AI 配置",
"user_impact": "安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。"
},
{
"body": "README/documentation is current enough for a first validation pass.",
"category": "能力坑",
"evidence": [
"capability.assumptions | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | README/documentation is current enough for a first validation pass."
],
"severity": "medium",
"suggested_check": "将假设转成下游验证清单。",
"title": "能力判断依赖假设",
"user_impact": "假设不成立时，用户拿不到承诺的能力。"
},
{
"body": "GitHub 社区证据显示该项目存在一个运行相关的待验证问题：編集可能な Illustrator アートワークのための SVG インポート動作の明確化と改善",
"category": "运行坑",
"evidence": [
"community_evidence:github | cevd_c7b420ed6123436eb6d2b27f460dc2c8 | https://github.com/ie3jp/illustrator-mcp-server/issues/35 | 来源类型 github_issue 暴露的待验证使用条件。"
],
"severity": "medium",
"suggested_check": "来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。",
"title": "来源证据：編集可能な Illustrator アートワークのための SVG インポート動作の明確化と改善",
"user_impact": "可能增加新用户试用和生产接入成本。"
},
{
"body": "未记录 last_activity_observed。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | last_activity_observed missing"
],
"severity": "medium",
"suggested_check": "补 GitHub 最近 commit、release、issue/PR 响应信号。",
"title": "维护活跃度未知",
"user_impact": "新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"downstream_validation.risk_items | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "进入安全/权限治理复核队列。",
"title": "下游验证发现风险项",
"user_impact": "下游已经要求复核，不能在页面中弱化。"
},
{
"body": "no_demo",
"category": "安全/权限坑",
"evidence": [
"risks.scoring_risks | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | no_demo; severity=medium"
],
"severity": "medium",
"suggested_check": "把风险写入边界卡，并确认是否需要人工复核。",
"title": "存在评分风险",
"user_impact": "风险会影响是否适合普通用户安装。"
},
{
"body": "issue_or_pr_quality=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | issue_or_pr_quality=unknown"
],
"severity": "low",
"suggested_check": "抽样最近 issue/PR，判断是否长期无人处理。",
"title": "issue/PR 响应质量未知",
"user_impact": "用户无法判断遇到问题后是否有人维护。"
},
{
"body": "release_recency=unknown。",
"category": "维护坑",
"evidence": [
"evidence.maintainer_signals | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | release_recency=unknown"
],
"severity": "low",
"suggested_check": "确认最近 release/tag 和 README 安装命令是否一致。",
"title": "发布节奏不明确",
"user_impact": "安装命令和文档可能落后于代码，用户踩坑概率升高。"
}
],
"source": "ProjectPitfallLog + ProjectHitPacket + validation + community signals",
"summary": "发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。",
"title": "踩坑日志"
},
"snapshot": {
"contributors": null,
"forks": null,
"license": "unknown",
"note": "站点快照，非实时质量证明；用于开工前背景判断。",
"stars": null
},
"source_url": "https://github.com/ie3jp/illustrator-mcp-server",
"steps": [
{
"body": "不安装项目，先体验能力节奏。",
"code": "preview",
"title": "先试 Prompt"
},
{
"body": "理解输入、输出、失败模式和边界。",
"code": "manual",
"title": "读说明书"
},
{
"body": "把上下文交给宿主 AI 继续工作。",
"code": "context",
"title": "带给 AI"
},
{
"body": "进入主力环境前先完成安装入口与风险边界验证。",
"code": "verify",
"title": "沙箱验证"
}
],
"subtitle": "**🇺🇸 English** | [🇯🇵 日本語](README.ja.md) | [🇨🇳 简体中文](README.zh-CN.md) | [🇰🇷 한국어](README.ko.md) | [🇪🇸 Español](README.es.md) | [🇩🇪 Deutsch](README.de.md) | [🇫🇷 Français](README.fr.md) | [🇵🇹 Português (BR)](README.pt-BR.md)",
"title": "illustrator-mcp-server 能力包",
"trial_prompt": "# illustrator-mcp-server - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for ie3jp/illustrator-mcp-server.\n\nProject:\n- Name: illustrator-mcp-server\n- Repository: https://github.com/ie3jp/illustrator-mcp-server\n- Summary: Preview illustrator-mcp-server safely before installing or changing a host AI environment.\n- Host target: mcp_host, claude, claude_code\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: I want to evaluate whether this project fits a real AI workflow before installing it.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n- Capability 2: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. project-overview: Project Overview. Produce one small intermediate artifact and wait for confirmation.\n2. getting-started: Getting Started. Produce one small intermediate artifact and wait for confirmation.\n3. architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. execution-flow: Execution Flow. Produce one small intermediate artifact and wait for confirmation.\n5. read-tools: Read Tools. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/ie3jp/illustrator-mcp-server#readme\n- plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md\n- README.md\n- package.json\n- manifest.json\n- CLAUDE.md\n- src/server.ts\n- src/index.ts\n- src/tools/registry.ts\n- src/executor/file-transport.ts\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"voices": [
{
"body": "来源平台：github, x。github/github_issue: 編集可能な Illustrator アートワークのための SVG インポート動作の明確化と改善（https://github.com/ie3jp/illustrator-mcp-server/issues/35）；github/github_release: v1.4.0（https://github.com/ie3jp/illustrator-mcp-server/releases/tag/v1.4.0）；github/github_release: v1.3.2（https://github.com/ie3jp/illustrator-mcp-server/releases/tag/v1.3.2）；github/github_release: v1.3.1（https://github.com/ie3jp/illustrator-mcp-server/releases/tag/v1.3.1）；github/github_release: v1.3.0（https://github.com/ie3jp/illustrator-mcp-server/releases/tag/v1.3.0）；github/github_release: v1.2.12（https://github.com/ie3jp/illustrator-mcp-server/releases/tag/v1.2.12）；github/github_release: v1.2.11（https://github.com/ie3jp/illustrator-mcp-server/releases/tag/v1.2.11）；github/github_release: v1.2.9（https://github.com/ie3jp/illustrator-mcp-server/releases/tag/v1.2.9）；github/github_release: v1.2.8（https://github.com/ie3jp/illustrator-mcp-server/releases/tag/v1.2.8）；github/github_release: v1.2.7（https://github.com/ie3jp/illustrator-mcp-server/releases/tag/v1.2.7）；x: ミヤマ on X: \"Claude Codeなど、AIからイラレを直接操作できるMCPサーバーが！？ 👇\" / X（https://x.com/mmmiyama_D/status/2036575601566556241）。这些是项目级外部声音，不作为单独质量证明。",
"items": [
{
"kind": "github_issue",
"source": "github",
"title": "編集可能な Illustrator アートワークのための SVG インポート動作の明確化と改善",
"url": "https://github.com/ie3jp/illustrator-mcp-server/issues/35"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.4.0",
"url": "https://github.com/ie3jp/illustrator-mcp-server/releases/tag/v1.4.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.3.2",
"url": "https://github.com/ie3jp/illustrator-mcp-server/releases/tag/v1.3.2"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.3.1",
"url": "https://github.com/ie3jp/illustrator-mcp-server/releases/tag/v1.3.1"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.3.0",
"url": "https://github.com/ie3jp/illustrator-mcp-server/releases/tag/v1.3.0"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.2.12",
"url": "https://github.com/ie3jp/illustrator-mcp-server/releases/tag/v1.2.12"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.2.11",
"url": "https://github.com/ie3jp/illustrator-mcp-server/releases/tag/v1.2.11"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.2.9",
"url": "https://github.com/ie3jp/illustrator-mcp-server/releases/tag/v1.2.9"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.2.8",
"url": "https://github.com/ie3jp/illustrator-mcp-server/releases/tag/v1.2.8"
},
{
"kind": "github_release",
"source": "github",
"title": "v1.2.7",
"url": "https://github.com/ie3jp/illustrator-mcp-server/releases/tag/v1.2.7"
},
{
"kind": "searxng_indexed",
"source": "x",
"title": "ミヤマ on X: \"Claude Codeなど、AIからイラレを直接操作できるMCPサーバーが！？ 👇\" / X",
"url": "https://x.com/mmmiyama_D/status/2036575601566556241"
}
],
"status": "已收录 11 条来源",
"title": "社区讨论"
}
]
},
"homepage_card": {
"category": "工具连接与集成",
"desc": "**🇺🇸 English** | [🇯🇵 日本語](README.ja.md) | [🇨🇳 简体中文](README.zh-CN.md) | [🇰🇷 한국어](README.ko.md) | [🇪🇸 Español](README.es.md) | [🇩🇪 Deutsch](README.de.md) | [🇫🇷 Français](README.fr.md) | [🇵🇹 Português (BR)](README.pt-BR.md)",
"effort": "安装已验证",
"forks": null,
"icon": "link",
"name": "illustrator-mcp-server 能力包",
"risk": "可发布",
"slug": "illustrator-mcp-server",
"stars": null,
"tags": [
"浏览器 Agent",
"网页任务自动化",
"自然语言网页操作",
"节点式流程编排",
"评测体系"
],
"thumb": "gray",
"type": "MCP 配置"
},
"manual": {
"markdown": "# https://github.com/ie3jp/illustrator-mcp-server Project Manual\n\nGenerated on: 2026-05-25 04:41:40 UTC\n\n## Table of Contents\n\n- [Project Overview](#project-overview)\n- [Getting Started](#getting-started)\n- [System Architecture](#architecture)\n- [Execution Flow](#execution-flow)\n- [Read Tools](#read-tools)\n- [Modify Tools](#modify-tools)\n- [Export Tools](#export-tools)\n- [Utility Tools](#utility-tools)\n- [Coordinate Systems](#coordinate-systems)\n- [Development Guide](#development-guide)\n\n\n\n## Project Overview\n\n### Related Pages\n\nRelated topics: [Getting Started](#getting-started), [System Architecture](#architecture)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n- [README.ko.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.ko.md)\n- [README.de.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.de.md)\n- [README.pt-BR.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.pt-BR.md)\n- [README.es.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.es.md)\n- [README.zh-CN.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.zh-CN.md)\n- [plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md)\n \n\n# Project Overview\n\n## Introduction\n\n**illustrator-mcp-server** is a Model Context Protocol (MCP) server that enables Claude, an AI assistant, to control Adobe Illustrator programmatically through natural language commands. This open-source project bridges the gap between AI capabilities and professional design workflows, allowing designers and developers to automate repetitive tasks, perform batch operations, and generate complex artwork through conversational interfaces.\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Purpose and Scope\n\nThe primary purpose of illustrator-mcp-server is to provide a comprehensive automation layer for Adobe Illustrator, making it accessible to users who may not have scripting experience while offering power users a flexible scripting alternative. The project serves multiple use cases:\n\n- **Design Automation**: Automate repetitive design tasks such as batch exports, color replacements, and object alignment\n- **Pre-press Validation**: Perform comprehensive print-readiness checks including PDF/X compliance verification\n- **Document Generation**: Create new documents with specific dimensions, color modes, and structures programmatically\n- **Design Assistance**: Enable AI-driven design workflows where Claude can generate artwork, layout suggestions, and style guides\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Architecture Overview\n\nThe system follows a client-server architecture built on the Model Context Protocol:\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n Claude[Claude AI Assistant]\n ClaudeCode[Claude Code CLI]\n ClaudeDesktop[Claude Desktop App]\n end\n \n subgraph \"MCP Protocol Layer\"\n MCPServer[MCP Server
illustrator-mcp-server]\n end\n \n subgraph \"Adobe Illustrator\"\n AI[Adobe Illustrator]\n AS[AppleScript / COM]\n end\n \n Claude -->|MCP Protocol| MCPServer\n MCPServer -->|Node.js 20+| AS\n AS -->|Automation API| AI\n \n ClaudeCode -.->|mcp add| MCPServer\n ClaudeDesktop -.->|npx / .mcpb| MCPServer\n```\n\n### Technology Stack\n\n| Component | Technology | Version Requirement |\n|-----------|------------|---------------------|\n| Runtime | Node.js | 20+ |\n| Language | TypeScript | - |\n| Protocol | Model Context Protocol | Latest |\n| Automation | AppleScript (macOS) / COM (Windows) | - |\n| Target App | Adobe Illustrator | CS6 or later |\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Core Feature Summary\n\n### Tool Categories\n\nThe server provides over **60 tools** organized into functional categories:\n\n| Category | Count | Primary Functions |\n|----------|-------|-------------------|\n| Read Tools | 21 | Document inspection, layer structure, color analysis, image quality |\n| Modify/Create Tools | 21+ | Shape creation, text manipulation, object modification |\n| Export Tools | 2 | SVG, PNG, JPG, PDF export with options |\n| Utility | 3 | Pre-flight checks, text consistency, workflow mode |\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n### Automatic Coordinate System Detection\n\nOne of the distinguishing features is intelligent coordinate system detection based on document color mode:\n\n```mermaid\ngraph LR\n A[Document Opens] --> B{Color Mode?}\n B -->|CMYK| C[document
coordinate system]\n B -->|RGB| D[artboard-web
coordinate system]\n \n C --> E[Origin: Bottom-left
Y-axis: Up]\n D --> F[Origin: Top-left
Y-axis: Down]\n \n E -.->|Print designers
expect| C\n F -.->|Web developers
expect| D\n```\n\n| Document Type | Coordinate System | Origin | Y Axis Direction |\n|---------------|-------------------|--------|------------------|\n| CMYK / Print | `document` | Bottom-left | Up |\n| RGB / Web | `artboard-web` | Top-left of artboard | Down |\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n### Print Production Tools\n\nThe project includes specialized tools for print production workflows:\n\n- **preflight_check**: Validates RGB color mixing, broken links, low resolution images, white overprint, transparency conflicts, and PDF/X compliance\n- **check_text_consistency**: Detects placeholders, notation variations (including Japanese double-line/Western single-line), and provides full text listing for LLM analysis\n- **export_pdf**: Generates print-ready PDFs with crop marks, bleed settings, selective downsampling, and output intent\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Installation Methods\n\n### Claude Code\n\n```bash\nclaude mcp add illustrator-mcp -- npx illustrator-mcp-server\n```\n\n### Claude Desktop\n\n#### Method 1: Direct Installation\n\n1. Download **`illustrator-mcp-server.mcpb`** from GitHub Releases\n2. Open Claude Desktop → Settings → Extensions\n3. Drag and drop the `.mcpb` file\n4. Click Install\n\n#### Method 2: Manual Configuration\n\n```json\n{\n \"mcpServers\": {\n \"illustrator\": {\n \"command\": \"npx\",\n \"args\": [\"illustrator-mcp-server\"]\n }\n }\n}\n```\n\n> **Note**: If Node.js is installed via a version manager (nvm, mise, fnm), use the full path: `\"command\": \"/full/path/to/npx\"`\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Example Workflows\n\n### Video Test Pattern Generation\n\nA complete SMPTE color bar test pattern created entirely through natural language prompts:\n\n**Prompt:**\n> Create a 1920x1080 video test pattern\n\n**Result:**\n- SMPTE color bars with PLUGE patterns\n- Title safe and action safe zones\n- Center crosshair markers\n- Resolution and format labels\n\n**Tools Used:**\n`create_document`, `manage_layers` ×4, `create_rectangle` ×2, `create_gradient` ×2, `create_path` ×11, `create_ellipse` ×14, `create_line` ×4, `create_text_frame` ×2, `modify_object`, `set_z_order`, `export`\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n### PDF/X-1a Compliance Check\n\n```mermaid\nsequenceDiagram\n participant User\n participant Claude\n participant MCP_Server\n participant Illustrator\n \n User->>Claude: Check if document is PDF/X-1a compliant\n Claude->>MCP_Server: preflight_check(target_pdf_profile: \"x1a\")\n MCP_Server->>Illustrator: Run preflight analysis\n Illustrator-->>MCP_Server: Return compliance results\n MCP_Server-->>Claude: Display errors and warnings\n Claude-->>User: Structured report with issues\n \n Note over MCP_Server: Flags: transparency,
RGB colors in CMYK,
non-outlined fonts\n```\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Platform Support\n\n| Platform | Status | Automation Method |\n|----------|--------|-------------------|\n| macOS | Fully Tested | AppleScript |\n| Windows | Partial | PowerShell COM (not fully tested) |\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Known Limitations\n\n| Limitation | Description |\n|------------|-------------|\n| Windows Support | PowerShell COM automation used; not yet tested on real hardware |\n| Live Effects | Drop shadow and similar effect parameters can be detected but not read |\n| Color Profiles | Only profile assignment available; full conversion not supported |\n| Bleed Settings | Cannot read bleed settings (API limitation) |\n| WebP Export | Not supported; use PNG or SVG instead |\n| Japanese Trim Marks | Uses TrimMark command approach for PDF export |\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Testing Infrastructure\n\n### Test Categories\n\n| Test Type | Command | Requirements |\n|-----------|---------|--------------|\n| Unit Tests | `npm test` | Node.js environment |\n| E2E Smoke Tests | `npx tsx test/e2e/smoke-test.ts` | Adobe Illustrator running |\n\nThe E2E smoke test performs:\n- Creates fresh documents (RGB + CMYK)\n- Places test objects\n- Executes **182 test cases** across **10 phases**\n- Covers all registered tools and coordinate system auto-detection\n- Automatic cleanup after completion\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Disclaimer\n\nThis tool automates many Illustrator operations, but AI can make mistakes. Extracted data, preflight results, and document modifications should always be reviewed by a human. The tool should not be relied upon as the sole quality check, especially for print submissions and client deliverables.\n\n> **Important**: The authors are not responsible for any damages or losses arising from the use of this software or its outputs.\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## License\n\nThis project is released under the [MIT License](LICENSE).\n\n---\n\n\n\n## Getting Started\n\n### Related Pages\n\nRelated topics: [Project Overview](#project-overview), [Development Guide](#development-guide)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n- [README.ko.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.ko.md)\n- [README.de.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.de.md)\n- [README.pt-BR.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.pt-BR.md)\n- [README.es.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.es.md)\n- [README.zh-CN.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.zh-CN.md)\n- [plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md)\n \n\n# Getting Started\n\n## Overview\n\nThis guide provides comprehensive instructions for setting up and running the illustrator-mcp-server, a Model Context Protocol (MCP) server that enables AI assistants like Claude to control Adobe Illustrator through natural language commands. The server acts as a bridge between Claude and Illustrator's scripting capabilities, allowing users to create, modify, and export artwork programmatically. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## System Requirements\n\nBefore installation, ensure your system meets the following requirements:\n\n| Requirement | Specification | Notes |\n|-------------|---------------|-------|\n| Node.js | 20+ | Required runtime environment |\n| Operating System | macOS / Windows | Windows uses PowerShell COM automation |\n| Adobe Illustrator | Any recent version | Multiple versions supported |\n| Claude | Code or Desktop | MCP client compatibility |\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Installation Methods\n\nThe illustrator-mcp-server supports multiple installation approaches depending on your workflow and preferences.\n\n### Method 1: Claude Code (Recommended)\n\nThe simplest installation method for Claude Code users requires only the `npx` command execution. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n```bash\nclaude mcp add illustrator-mcp -- npx illustrator-mcp-server\n```\n\nThis command registers the illustrator-mcp-server as an MCP tool that Claude Code can access. The server will be downloaded and executed on-demand via npx.\n\n### Method 2: Claude Desktop with .mcpb File\n\nFor Claude Desktop users, download the pre-built `.mcpb` file from GitHub Releases. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n**Steps:**\n\n1. Download **`illustrator-mcp-server.mcpb`** from [GitHub Releases](https://github.com/ie3jp/illustrator-mcp-server/releases/latest)\n2. Open Claude Desktop → **Settings** → **Extensions**\n3. Drag and drop the `.mcpb` file into the Extensions panel\n4. Click the **Install** button\n\n> [!NOTE]\n> The `.mcpb` extension does not auto-update. To update, download the new version and reinstall. If you prefer automatic updates, use the npx method instead. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n### Method 3: Claude Desktop Manual Configuration\n\nFor users who prefer automatic updates or need custom configuration, manually edit the Claude Desktop configuration file. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n#### Step 1: Open the Configuration File\n\nFrom the Claude Desktop menu bar:\n- **Claude** → **Settings...** → **Developer** (in the left sidebar) → Click the **Edit Config** button\n\n#### Step 2: Add Server Configuration\n\n```json\n{\n \"mcpServers\": {\n \"illustrator\": {\n \"command\": \"npx\",\n \"args\": [\"illustrator-mcp-server\"]\n }\n }\n}\n```\n\n> [!NOTE]\n> If you installed Node.js via a version manager (nvm, mise, fnm, etc.), Claude Desktop may not find `npx`. In that case, use the full path. Run `which npx` in your terminal to find the path. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n```json\n\"command\": \"/full/path/to/npx\"\n```\n\n#### Step 3: Save and Restart\n\n1. Save the file and close the text editor\n2. **Fully quit** Claude Desktop (⌘Q / Ctrl+Q) and reopen\n\n## Building from Source\n\nFor development, testing, or customization purposes, build the server from the source code. Source: [README.pt-BR.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.pt-BR.md)\n\n### Prerequisites\n\n- Git\n- Node.js 20+\n- npm\n\n### Build Steps\n\n```bash\ngit clone https://github.com/ie3jp/illustrator-mcp-server.git\ncd illustrator-mcp-server\nnpm install\nnpm run build\n```\n\nAfter building, register the local server:\n\n```bash\nclaude mcp add illustrator-mcp -- node /path/to/illustrator-mcp-server/dist/index.js\n```\n\n## Verification\n\nAfter installation, verify that the server is properly configured by running the MCP inspector. Source: [README.pt-BR.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.pt-BR.md)\n\n```bash\nnpx @modelcontextprotocol/inspector npx illustrator-mcp-server\n```\n\nThe inspector provides an interactive interface to test MCP tool calls and confirm connectivity.\n\n## Testing\n\nThe project includes comprehensive test suites to validate functionality across different scenarios.\n\n### Unit Tests\n\nRun the unit test suite to verify core functionality:\n\n```bash\nnpm test\n```\n\n### End-to-End Smoke Tests\n\nThe E2E smoke test creates new documents (RGB + CMYK), inserts test objects, executes 182 test cases across 10 phases covering all registered tools and automatic coordinate system detection, then performs automatic cleanup. Source: [README.pt-BR.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.pt-BR.md)\n\n```bash\nnpx tsx test/e2e/smoke-test.ts\n```\n\n> [!NOTE]\n> E2E tests require Illustrator to be running. The smoke test will connect to the running instance and perform operations on temporary documents.\n\n## Initial Configuration\n\n### macOS Automation Permissions\n\nOn first run, macOS requires explicit permission for automation access. Navigate to:\n\n**System Settings** → **Privacy & Security** → **Automation**\n\nLocate Claude Desktop in the list and enable access for the automation permissions requested. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n### Multiple Illustrator Versions\n\nIf you have multiple versions of Illustrator installed, you can specify which version to use during conversation. Simply say \"Use Illustrator 2024\" and the `set_illustrator_version` tool will target that version. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n> [!NOTE]\n> If Illustrator is already running, the server connects to the running instance automatically.\n\n### Windows PowerShell Configuration\n\nWindows uses PowerShell COM automation for Illustrator control. This functionality has not been tested on real hardware yet. Source: [README.es.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.es.md)\n\n## Workflow Modes\n\nThe server supports different workflow modes that affect coordinate system handling. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n| Document Type | Coordinate System | Origin | Y Axis Direction |\n|---------------|-------------------|--------|------------------|\n| CMYK / Print | `document` | Bottom-left | Up |\n| RGB / Web | `artboard-web` | Top-left of artboard | Down |\n\n- **CMYK documents** use Illustrator's native coordinate system, matching what print designers expect\n- **RGB documents** use a web-based coordinate system with origin at the top-left\n\nUse the `set_workflow` tool to override the auto-detected coordinate system when needed.\n\n## Quick Start Workflow\n\nThe following diagram illustrates the typical workflow when using the illustrator-mcp-server:\n\n```mermaid\ngraph TD\n A[User Input] --> B{Server Running?}\n B -->|No| C[Start Illustrator]\n B -->|Yes| D[Connect to Illustrator]\n C --> D\n D --> E[Send MCP Request]\n E --> F[Process Tool Call]\n F --> G{Modify or Read?}\n G -->|Modify| H[Execute Illustrator Action]\n G -->|Read| I[Query Illustrator State]\n H --> J[Return Result]\n I --> J\n J --> K[User Receives Response]\n \n L[Export Tools] --> M[SVG / PNG / PDF]\n H --> L\n```\n\n## First-Time Usage Example\n\nA typical first session might involve creating a new document and adding basic elements. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n```bash\n# Create a new 1920x1080 document\nYou: Create a new Full HD document\n\nClaude: → create_document (width: 1920, height: 1080, color_mode: \"rgb\")\n ✅ Created new document \"Untitled-1\"\n\n# Add a rectangle\nYou: Add a blue rectangle in the center\n\nClaude: → create_rectangle (x: 760, y: 390, width: 400, height: 300, fill: \"#007AFF\")\n ✅ Rectangle created\n\n# Export the result\nYou: Export as PNG\n\nClaude: → export (format: \"png\", artboard: 0)\n ✅ Exported to /output/Untitled-1.png\n```\n\n## Known Limitations\n\nBefore starting your project, be aware of the following limitations: Source: [README.es.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.es.md)\n\n| Limitation | Details |\n|------------|---------|\n| Windows Support | Uses PowerShell COM automation (not tested on real hardware) |\n| Live Effects | Drop shadow and effect parameters can be detected but not read |\n| Color Profiles | Only profile assignment available — full conversion not supported |\n| Bleed Settings | Cannot read bleed settings (Illustrator API limitation) |\n| WebP Export | Not supported — use PNG or SVG instead |\n| Japanese Trim Marks | PDF export uses TrimMark command approach, generates marks as document paths |\n| Font Embedding | Embedding mode (full/subset) cannot be controlled directly |\n| Size Variations | Only proportional scaling available — text may need manual adjustment |\n\n## Troubleshooting\n\n### npx Not Found\n\nIf Claude Desktop cannot find `npx`, install Node.js via the official installer from [nodejs.org](https://nodejs.org/) instead of using version managers like nvm, mise, or fnm. Alternatively, use the full path to npx. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n### Illustrator Not Launching\n\nModify and export tools will bring Illustrator to the foreground during execution. If Illustrator fails to launch, ensure it is properly installed and you have the necessary permissions. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n### Permission Denied on macOS\n\nGrant automation permissions in **System Settings** → **Privacy & Security** → **Automation** and ensure Claude Desktop is listed with appropriate access.\n\n## Next Steps\n\nAfter successful installation, explore the available tools:\n\n- **Read Tools** (21): `get_document_info`, `get_artboards`, `get_layers`, `get_document_structure`, `list_text_frames`, `get_colors`, `get_path_items`, `get_images`, and more\n- **Modify Tools** (38): `create_rectangle`, `create_ellipse`, `create_text_frame`, `create_path`, `modify_object`, `align_objects`, `manage_layers`, and more\n- **Export Tools** (2): `export`, `export_pdf`\n- **Utility Tools** (3): `preflight_check`, `check_text_consistency`, `set_workflow`\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n> [!CAUTION]\n> AI can make mistakes. Do not over-rely on the output — **always have a human perform the final check on submission data**. The user is responsible for the results. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n---\n\n\n\n## System Architecture\n\n### Related Pages\n\nRelated topics: [Execution Flow](#execution-flow), [Project Overview](#project-overview)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n- [README.ko.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.ko.md)\n- [README.de.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.de.md)\n- [README.pt-BR.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.pt-BR.md)\n- [README.fr.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.fr.md)\n\n \n\n# System Architecture\n\n## Overview\n\nThe illustrator-mcp-server is a Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with Adobe Illustrator through a standardized interface. The server acts as a bridge between natural language instructions from AI systems and the Adobe Illustrator scripting API, providing automation capabilities for document manipulation, design tasks, and pre-press operations.\n\nThe architecture follows a tool-based pattern where each Illustrator operation is exposed as an individual MCP tool. The server handles connection management, coordinate system transformations, and result serialization to provide a seamless experience for AI-driven design workflows.\n\n## High-Level Architecture\n\n```mermaid\ngraph TB\n subgraph \"Client Layer\"\n AI[AI Assistant
Claude, etc.]\n MCP[MCP Client]\n end\n \n subgraph \"Server Layer\"\n Server[MCP Server]\n Registry[Tool Registry]\n Executor[Tool Executor]\n end\n \n subgraph \"Adobe Illustrator\"\n API[ExtendScript API
JavaScript Bridge]\n App[Illustrator Application]\n end\n \n AI --> MCP\n MCP --> Server\n Server --> Registry\n Server --> Executor\n Executor --> API\n API --> App\n \n style AI fill:#e1f5fe\n style App fill:#fff3e0\n```\n\n## Core Components\n\n### Tool Registry\n\nThe tool registry maintains a catalog of all available MCP tools organized into functional categories. Each tool is registered with metadata including its name, description, input schema, and handler function.\n\n**Tool Categories:**\n\n| Category | Count | Description |\n|----------|-------|-------------|\n| Read Tools | 21 | Extract document information, colors, text, images, and structure |\n| Modify Tools | 38 | Create, modify, and manage objects, layers, and documents |\n| Export Tools | 2 | Export artwork to SVG, PNG, JPG, and PDF formats |\n| Utility Tools | 3 | Preflight checks, text consistency, and workflow settings |\n\nSource: [README.md](README.md)\n\n### Coordinate System Management\n\nThe server implements automatic coordinate system detection based on document color mode:\n\n| Document Type | Coordinate System | Origin | Y-Axis Direction |\n|---------------|-------------------|--------|------------------|\n| CMYK / Print | `document` | Bottom-left | Up |\n| RGB / Web | `artboard-web` | Top-left of artboard | Down |\n\nCMYK documents use Illustrator's native coordinate system matching print designer expectations, while RGB documents use a web-friendly coordinate system with origin at the top-left of the artboard. The `set_workflow` tool allows manual override of the auto-detected system.\n\nSource: [README.md](README.md)\n\n### Tool Execution Flow\n\n```mermaid\nsequenceDiagram\n participant AI as AI Assistant\n participant MCP as MCP Server\n participant Registry as Tool Registry\n participant Exec as Executor\n participant App as Illustrator API\n \n AI->>MCP: Tool Request\n MCP->>Registry: Lookup Tool Definition\n Registry-->>MCP: Tool Schema\n MCP->>Exec: Execute Tool Call\n Exec->>App: Invoke Illustrator Script\n App-->>Exec: Script Result\n Exec-->>MCP: Serialized Response\n MCP-->>AI: JSON-RPC Response\n```\n\n## System Architecture Layers\n\n### Layer 1: Client Interface\n\nThe MCP protocol defines how AI assistants communicate with the server. Clients connect using the MCP handshake protocol and receive the tool manifest during initialization.\n\n**Connection Methods:**\n\n```json\n// Claude Desktop Configuration\n{\n \"mcpServers\": {\n \"illustrator\": {\n \"command\": \"npx\",\n \"args\": [\"illustrator-mcp-server\"]\n }\n }\n}\n```\n\nSource: [README.md](README.md)\n\n### Layer 2: Server Implementation\n\nThe server layer handles:\n- MCP protocol message parsing and routing\n- Tool registration and discovery\n- Request validation and error handling\n- Response serialization\n\nThe server automatically manages Illustrator application connections, including support for multiple installed versions. The `set_illustrator_version` tool allows targeting specific Illustrator versions during a session.\n\n### Layer 3: Illustrator Bridge\n\nThe bridge layer communicates with Adobe Illustrator through the ExtendScript/JavaScript API. This layer handles:\n\n- Application state management (launch, connect, disconnect)\n- Script execution and result parsing\n- Coordinate transformation between coordinate systems\n- Error translation from Illustrator errors to MCP-friendly messages\n\nSource: [README.md](README.md)\n\n## Tool Organization\n\n### Read Tools (21 tools)\n\nThese tools extract information from the active Illustrator document:\n\n| Tool | Purpose |\n|------|---------|\n| `get_document_info` | Document metadata (dimensions, color mode, profile) |\n| `get_artboards` | Artboard information (position, size, orientation) |\n| `get_layers` | Layer structure as a tree |\n| `get_document_structure` | Full tree: layers → groups → objects |\n| `get_colors` | Color swatches, gradients, spot colors |\n| `get_path_items` | Path/shape data (fill, stroke, anchor points) |\n| `get_images` | Embedded/linked image info with print quality |\n| `get_symbols` | Symbol definitions and instances |\n| `get_guidelines` | Guide information |\n| `get_overprint_info` | Overprint settings and K only plate info |\n\nSource: [README.md](README.md)\n\n### Modify Tools (38 tools)\n\nThese tools create and modify document elements:\n\n| Category | Capabilities |\n|----------|-------------|\n| Creation | Rectangles, ellipses, lines, text frames, paths, images |\n| Modification | Object properties, z-order, grouping, alignment |\n| Document | Create, open, save, close documents |\n| Layers | Add, rename, show/hide, lock/unlock, delete |\n| Styling | Convert to outlines, assign color profiles |\n\nSource: [README.md](README.md)\n\n### Export Tools (2 tools)\n\n| Tool | Formats |\n|------|---------|\n| `export` | SVG, PNG, JPG by artboard, selection, or UUID |\n| `export_pdf` | Print-ready PDF with crop marks, bleed, output intent |\n\nSource: [README.md](README.md)\n\n### Utility Tools (3 tools)\n\n| Tool | Purpose |\n|------|---------|\n| `preflight_check` | Pre-press validation (RGB mixing, broken links, PDF/X compliance) |\n| `check_text_consistency` | Placeholder detection, notation patterns |\n| `set_workflow` | Override auto-detected coordinate system |\n\nSource: [README.md](README.md)\n\n## Data Flow Architecture\n\n```mermaid\ngraph LR\n subgraph \"Input Processing\"\n Req[Tool Request] --> Parse[Parse & Validate]\n Parse --> Transform[Coordinate Transform]\n end\n \n subgraph \"Illustrator Processing\"\n Transform --> Script[Generate Script]\n Script --> Execute[Execute in Illustrator]\n Execute --> Result[Capture Result]\n end\n \n subgraph \"Output Processing\"\n Result --> Serialize[Serialize Response]\n Serialize --> Out[JSON-RPC Response]\n end\n \n style Input Processing fill:#e8f5e9\n style Illustrator Processing fill:#fff8e1\n style Output Processing fill:#e3f2fd\n```\n\n## Multiple Illustrator Version Support\n\nThe architecture supports concurrent installation of multiple Illustrator versions. The server can detect available versions and route requests to the appropriate application instance.\n\n```mermaid\ngraph TD\n Start[Start Session] --> Check{Running Instance?}\n \n Check -->|Yes| Connect[Connect to Running]\n Check -->|No| Detect[Detect Versions]\n \n Detect --> Select[Select Version]\n Select --> Launch[Launch Illustrator]\n \n Connect --> Ready\n Launch --> Ready\n \n Ready[Ready for Commands]\n \n User[User: \"Use Illustrator 2024\"] --> Override\n Override[Call set_illustrator_version]\n Override --> Ready\n```\n\nSource: [README.md](README.md)\n\n## Workflow Modes\n\nThe server operates in two primary workflow modes that affect coordinate handling:\n\n### Web/Print Workflow\n\n| Mode | Use Case | Coordinate System |\n|------|----------|-------------------|\n| Web | RGB documents, screen output | `artboard-web` (top-left origin, Y-down) |\n| Print | CMYK documents, commercial printing | `document` (bottom-left origin, Y-up) |\n\nThe server automatically detects the appropriate mode based on the document's color mode. Manual override is available via the `set_workflow` tool when AI needs consistent coordinate behavior.\n\nSource: [README.md](README.md)\n\n## Error Handling Architecture\n\n```mermaid\ngraph TD\n Script[Script Execution] --> Success{Success?}\n \n Success -->|Yes| Return[Return Result]\n Success -->|No| Identify[Identify Error Type]\n \n Identify -->|API Error| IllustratorError[Illustrator Error]\n Identify -->|Connection Error| ConnectionError[Connection Lost]\n Identify -->|Validation Error| ValidationError[Invalid Parameters]\n \n IllustratorError --> MCPError[Format as MCP Error]\n ConnectionError --> Reconnect[Attempt Reconnect]\n ValidationError --> MCPError\n \n Reconnect --> Success\n MCPError --> Response[Error Response]\n Return --> Response\n \n style Response fill:#ffcdd2\n```\n\n## Build and Deployment\n\n### Project Structure\n\n```\nillustrator-mcp-server/\n├── dist/ # Compiled JavaScript output\n├── src/ # TypeScript source files\n│ ├── server.ts # MCP server implementation\n│ ├── index.ts # Entry point\n│ └── tools/ # Tool implementations\n├── test/ # Test files\n│ └── e2e/ # End-to-end smoke tests\n└── package.json # Dependencies and scripts\n```\n\n### Build Commands\n\n```bash\nnpm install # Install dependencies\nnpm run build # Compile TypeScript to JavaScript\nnpm test # Run unit tests\n```\n\nSource: [README.md](README.md)\n\n### Verification\n\n```bash\nnpx @modelcontextprotocol/inspector npx illustrator-mcp-server\n```\n\nThe MCP inspector tool validates that the server correctly implements the protocol and exposes all registered tools.\n\n## Limitations and Architecture Constraints\n\n| Limitation | Impact | Mitigation |\n|------------|--------|------------|\n| Windows COM automation | Untested on real hardware | Uses PowerShell for COM bridge |\n| Live effects | Cannot read shadow parameters | Effects detected but not fully readable |\n| Color profile conversion | Only profile assignment, not value conversion | Use Illustrator for conversion |\n| Bleed settings | Cannot be read from document | Configure in export settings |\n| WebP export | Not supported | Use PNG or SVG alternatives |\n\nSource: [README.pt-BR.md](README.pt-BR.md)\n\n## Security Considerations\n\nThe architecture includes several safety mechanisms:\n\n1. **Manual Verification Required**: All extracted data, preflight results, and document modifications require human review before final submission\n2. **Foreground Execution**: Modify and export tools bring Illustrator to the foreground during execution\n3. **Automation Permissions**: macOS requires explicit automation access in System Settings → Privacy & Security → Automation\n\nSource: [README.md](README.md)\n\n---\n\n\n\n## Execution Flow\n\n### Related Pages\n\nRelated topics: [System Architecture](#architecture), [Coordinate Systems](#coordinate-systems)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/executor/file-transport.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/executor/file-transport.ts)\n- [src/executor/jsx-runner.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/executor/jsx-runner.ts)\n- [src/tools/tool-executor.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/tool-executor.ts)\n- [src/jsx/helpers/common.jsx](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/jsx/helpers/common.jsx)\n- [src/tools/export/export.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export.ts)\n- [src/tools/modify/place-symbol.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/place-symbol.ts)\n- [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n \n\n# Execution Flow\n\n## Overview\n\nThe execution flow is the core mechanism by which the MCP server communicates with Adobe Illustrator to perform design operations. Since Illustrator does not natively support the MCP (Model Context Protocol) or direct Node.js integration, the server acts as an intermediary that translates tool requests into ExtendScript (JSX) commands that Illustrator can execute. This architectural pattern enables Claude and other MCP-compatible AI assistants to control Adobe Illustrator programmatically.\n\nThe execution flow handles tool parameter serialization, cross-platform script generation (AppleScript for macOS, PowerShell for Windows), and result retrieval through a file-based transport mechanism. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Architecture Overview\n\n```mermaid\nflowchart LR\n Claude <-->|MCP Protocol| Server[\"MCP Server\\n(TypeScript/Node.js)\"]\n\n Server -.->|generate| Runner[\"run-{uuid}.scpt / .ps1\"]\n Server -.->|generate| JSX[\"script-{uuid}.jsx\\n(BOM UTF-8)\"]\n Server -.->|write| PF[\"params-{uuid}.json\"]\n\n Runner -->|execFile| osascript\n Runner -->|execFile| PS[\"powershell.exe\"]\n\n osascript -->|do javascript| AI[\"Adobe Illustrator\\n(ExtendScript/JSX)\"]\n PS -->|DoJavaScript| AI\n\n JSX -.->|execute| AI\n PF -.->|read| AI\n AI -.->|write| RF[\"result-{uuid}.json\"]\n RF -.->|read| Server\n```\n\nThe system comprises four primary components that communicate through the file system:\n\n| Component | Technology | Role |\n|-----------|------------|------|\n| MCP Server | TypeScript/Node.js | Receives tool requests, generates scripts, coordinates execution |\n| Runner Script | AppleScript/PowerShell | Bridges the OS shell to Illustrator's scripting engine |\n| JSX Script | ExtendScript | Contains the actual Illustrator operations |\n| Parameter File | JSON | Passes typed parameters from the server to the JSX execution context |\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Execution Pipeline Stages\n\n### Stage 1: Tool Registration and Discovery\n\nThe MCP server registers all available tools during initialization. Each tool defines a name, input schema, and handler function. Tools are organized into categories (read, modify, export, utility) and are exposed to Claude through the MCP protocol. Source: [src/tools/tool-executor.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/tool-executor.ts)\n\n### Stage 2: Request Handling\n\nWhen a tool request arrives, the server performs the following validation and preparation steps:\n\n1. **Schema validation** — Verify all required parameters are present\n2. **Coordinate system detection** — Determine whether the document uses `document` (CMYK/print) or `artboard-web` (RGB/web) coordinates\n3. **UUID generation** — Create a unique identifier for tracking this execution cycle\n4. **Script selection** — Load the appropriate JSX template for the requested operation\n\nSource: [src/tools/tool-executor.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/tool-executor.ts)\n\n### Stage 3: Parameter Serialization\n\nParameters are serialized into a JSON file using the file transport mechanism. This file-based approach is necessary because ExtendScript and the Illustrator DOM cannot directly receive complex JavaScript objects from the Node.js process. Source: [src/executor/file-transport.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/executor/file-transport.ts)\n\nThe parameter file follows the naming convention `params-{uuid}.json` and contains typed parameters that the JSX script will read during execution.\n\n### Stage 4: Script Generation\n\nThe server generates two scripts for each execution:\n\n**JSX Script (`script-{uuid}.jsx`)**\n- Written in BOM-encoded UTF-8 (required for Illustrator compatibility with non-ASCII characters)\n- Contains the ExtendScript code that manipulates the Illustrator document\n- References the parameter file path\n- Writes results to `result-{uuid}.json`\n\n**Runner Script**\n- macOS: AppleScript (`.scpt`) that executes `osascript` with the JSX path\n- Windows: PowerShell (`.ps1`) that executes Illustrator via COM automation\n- Handles platform-specific execution context and error propagation\n\nSource: [src/executor/jsx-runner.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/executor/jsx-runner.ts)\n\n### Stage 5: Cross-Platform Execution\n\n```mermaid\nflowchart TD\n subgraph macOS\n A[Node.js Server] --> B[Generate .scpt]\n B --> C[osascript]\n C --> D[do javascript]\n D --> E[Adobe Illustrator]\n end\n\n subgraph Windows\n F[Node.js Server] --> G[Generate .ps1]\n G --> H[powershell.exe]\n H --> I[DoJavaScript]\n I --> J[Adobe Illustrator]\n end\n```\n\nThe runner script invokes the appropriate shell command based on the operating system:\n\n**macOS Execution Path**\n```applescript\nosascript -l JavaScript \"/path/to/script-{uuid}.jsx\"\n```\n\n**Windows Execution Path**\n```powershell\n$ai = New-Object -ComObject Illustrator.Application\n$ai.DoJavaScript(\"/path/to/script-{uuid}.jsx\")\n```\n\nSource: [src/executor/jsx-runner.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/executor/jsx-runner.ts)\n\n### Stage 6: JSX Execution\n\nThe ExtendScript environment within Illustrator reads the parameter file and executes the DOM operations. The script has access to:\n\n- The active document and its properties\n- The parameter values serialized by the server\n- Helper utilities from `src/jsx/helpers/common.jsx`\n\nCommon helper functions include UUID management, artboard coordinate conversion, and result file writing. Source: [src/jsx/helpers/common.jsx](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/jsx/helpers/common.jsx)\n\n### Stage 7: Result Collection\n\nAfter execution completes, the JSX script writes a result file (`result-{uuid}.json`) containing:\n\n| Field | Description |\n|-------|-------------|\n| `success` | Boolean indicating whether the operation completed |\n| `error` | Boolean flag for error state |\n| `message` | Human-readable status or error message |\n| `uuid` | Identifier of the created or modified object |\n| `data` | Operation-specific result payload |\n\nSource: [src/executor/file-transport.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/executor/file-transport.ts)\n\n### Stage 8: Response Assembly\n\nThe MCP server reads the result file, parses the JSON payload, and constructs an MCP-formatted response that is sent back to Claude. If the operation failed, the response includes error details for debugging.\n\n## Coordinate System Handling\n\nThe server automatically detects and handles coordinate system differences between document types:\n\n| Document Type | Coordinate System | Origin | Y Axis Direction |\n|---------------|-------------------|--------|-------------------|\n| CMYK / Print | `document` | Bottom-left | Up |\n| RGB / Web | `artboard-web` | Top-left of artboard | Down |\n\nConversion utilities in the JSX helpers transform coordinates between systems as needed. Source: [src/jsx/helpers/common.jsx](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/jsx/helpers/common.jsx)\n\n## Error Handling\n\nThe execution flow includes multiple error handling layers:\n\n1. **Parameter validation** — Invalid inputs are rejected before script generation\n2. **Script compilation errors** — Malformed JSX is caught and reported\n3. **Runtime errors** — Illustrator DOM errors are captured in the result file\n4. **File system errors** — Missing or unwritable paths are detected\n\nExample error response structure:\n```json\n{\n \"error\": true,\n \"message\": \"Symbol not found: MySymbol\",\n \"line\": 42\n}\n```\n\nSource: [src/tools/modify/place-symbol.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/place-symbol.ts)\n\n## Export-Specific Execution\n\nExport operations follow the standard flow but include additional file verification steps:\n\n```mermaid\nflowchart TD\n Start[export tool called] --> Validate[Validate format & artboard]\n Validate --> Generate[Generate export script]\n Generate --> Execute[Run JSX via runner]\n Execute --> Check{Output file exists?}\n Check -->|Yes| DpiCalc[Calculate effective DPI]\n Check -->|No| Error[Write error result]\n DpiCalc --> Write[Write success result]\n Write --> Done[Return to Claude]\n Error --> Done\n```\n\nThe export handler verifies the output file was created and includes effective DPI calculations in the result. Source: [src/tools/export/export.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export.ts)\n\n## Build and Packaging\n\nThe server is compiled using a custom build script that:\n\n1. Compiles TypeScript to JavaScript via `tsc`\n2. Copies JSX files to the distribution directory\n3. Bundles the server into a CommonJS module for Node.js compatibility\n\n```bash\nnpm run build\n```\n\nSource: [package.json](https://github.com/ie3jp/illustrator-mcp-server/blob/main/package.json)\n\n## Testing the Execution Flow\n\nEnd-to-end smoke tests validate the complete flow by:\n\n1. Creating fresh RGB and CMYK documents\n2. Placing test objects via all registered tools\n3. Running 182 test cases across 10 phases\n4. Verifying coordinate system auto-detection\n5. Cleaning up automatically\n\n```bash\nnpx tsx test/e2e/smoke-test.ts\n```\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Summary\n\nThe execution flow transforms high-level tool requests from Claude into Illustrator DOM operations through a file-based transport mechanism. This architecture enables:\n\n- Cross-platform support (macOS and Windows)\n- Type-safe parameter passing via JSON\n- BOM UTF-8 encoding for international character support\n- Automatic coordinate system handling\n- Comprehensive error reporting\n- Asynchronous execution with UUID tracking\n\nThe separation between the MCP server, runner scripts, and JSX execution ensures that Illustrator remains isolated from the Node.js process, preventing compatibility issues between the different scripting environments.\n\n---\n\n\n\n## Read Tools\n\n### Related Pages\n\nRelated topics: [Modify Tools](#modify-tools), [Export Tools](#export-tools)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/tools/read/get-document-info.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-document-info.ts)\n- [src/tools/read/get-document-structure.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-document-structure.ts)\n- [src/tools/read/list-text-frames.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/list-text-frames.ts)\n- [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)\n- [src/tools/read/get-colors.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-colors.ts)\n- [src/tools/read/get-images.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-images.ts)\n- [src/tools/read/check-contrast.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/check-contrast.ts)\n- [src/tools/read/extract-design-tokens.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/extract-design-tokens.ts)\n \n\n# Read Tools\n\nRead Tools in illustrator-mcp-server provide comprehensive read-only access to Adobe Illustrator documents. These 21 tools enable AI assistants like Claude to inspect, analyze, and extract information from open documents without modifying them. Read Tools serve as the foundation for document analysis, design auditing, preflight checks, and AI-driven content understanding.\n\n## Overview\n\nRead Tools are categorized into four functional areas:\n\n| Category | Tool Count | Purpose |\n|----------|-----------|---------|\n| Document Analysis | 4 | Metadata, structure, coordinate systems |\n| Text Analysis | 2 | Text frame inspection and attribute details |\n| Visual Element Analysis | 10 | Colors, images, paths, effects, symbols |\n| Accessibility & Compliance | 5 | Contrast checking, design token extraction, object search |\n\nThe tool architecture follows a consistent pattern where each tool returns structured JSON data suitable for AI consumption and analysis. All Read Tools operate on the currently active Illustrator document and do not modify document state.\n\n## Architecture\n\n```mermaid\ngraph TD\n A[AI Assistant] -->|MCP Protocol| B[illustrator-mcp-server]\n B -->|COM/AppleScript| C[Adobe Illustrator]\n C -->|Document Data| B\n B -->|Structured JSON| A\n \n B --> D[Read Tools]\n B --> E[Modify Tools]\n B --> F[Export Tools]\n B --> G[Utility Tools]\n \n D --> D1[Document Tools]\n D --> D2[Text Tools]\n D --> D3[Visual Tools]\n D --> D4[Compliance Tools]\n```\n\n### Tool Registration Pattern\n\nRead Tools are registered as MCP (Model Context Protocol) handlers in the server initialization. Each tool follows this standard structure:\n\n```\nTool Name → Handler Function → Illustrator Script → JSON Response\n```\n\nSource: [src/tools/read/get-document-info.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-document-info.ts)\n\n## Document Analysis Tools\n\n### get_document_info\n\nRetrieves comprehensive metadata about the active Illustrator document.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `none` | - | - | Operates on currently active document |\n\n**Returns:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `name` | string | Document filename |\n| `path` | string | Full file path |\n| `width` | number | Document width in points |\n| `height` | number | Document height in points |\n| `colorMode` | string | \"RGB\" or \"CMYK\" |\n| `colorProfile` | string | Assigned ICC profile |\n| `artboards` | array | Array of artboard objects |\n| `layers` | number | Layer count |\n\nSource: [src/tools/read/get-document-info.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-document-info.ts)\n\n### get_artboards\n\nReturns information about all artboards in the document.\n\n**Returns:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `artboards[]` | array | List of artboard objects |\n| `artboards[].name` | string | Artboard name |\n| `artboards[].rect` | object | Position and dimensions `{x, y, width, height}` |\n| `artboards[].position` | string | Origin point reference |\n\nSource: [src/tools/read/get-document-structure.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-document-structure.ts)\n\n### get_document_structure\n\nProvides a complete hierarchical tree of the document contents.\n\n**Returns:** Nested tree structure:\n\n```\nDocument\n└── Layers\n ├── Groups\n │ └── Objects\n ├── Text Frames\n ├── Paths\n ├── Images\n └── Symbols\n```\n\n**Object Properties Returned:**\n\n| Property | Applicable To | Description |\n|----------|--------------|-------------|\n| `name` | all | Object name |\n| `type` | all | Object type (text, path, group, etc.) |\n| `uuid` | all | Unique identifier |\n| `bounds` | all | Bounding box coordinates |\n| `visible` | all | Visibility state |\n| `locked` | all | Lock state |\n\nSource: [src/tools/read/get-document-structure.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-document-structure.ts)\n\n### convert_coordinate\n\nConverts coordinates between the document coordinate system and artboard coordinate system.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `x` | number | Yes | X coordinate |\n| `y` | number | Yes | Y coordinate |\n| `from` | string | Yes | Source system: \"document\" or \"artboard\" |\n| `to` | string | Yes | Target system: \"document\" or \"artboard\" |\n\n**Coordinate System Reference:**\n\n| Document Type | Coordinate System | Origin | Y-axis Direction |\n|---------------|-------------------|--------|------------------|\n| CMYK/Print | `document` | Bottom-left | Up |\n| RGB/Web | `artboard-web` | Top-left of artboard | Down |\n\nSource: [src/tools/read/get-document-info.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-document-info.ts)\n\n## Text Analysis Tools\n\n### list_text_frames\n\nEnumerates all text frames in the document with key attributes.\n\n**Returns:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `textFrames[]` | array | List of text frame objects |\n| `textFrames[].name` | string | Object name |\n| `textFrames[].uuid` | string | Unique identifier |\n| `textFrames[].contents` | string | Text content |\n| `textFrames[].font` | string | Font family |\n| `textFrames[].fontSize` | number | Font size in points |\n| `textFrames[].style` | string | Style name (e.g., \"Bold\", \"Italic\") |\n| `textFrames[].position` | object | {x, y} coordinates |\n\nSource: [src/tools/read/list-text-frames.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/list-text-frames.ts)\n\n### get_text_frame_detail\n\nReturns comprehensive attributes for a specific text frame.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `uuid` | string | Yes | Text frame UUID |\n\n**Returns:**\n\n| Category | Fields |\n|----------|--------|\n| Basic | name, uuid, contents, font, fontSize |\n| Style | style, fillColor, paragraphSpacing |\n| Spacing | tracking, kerning, leading, baselineShift |\n| Paragraph | alignment, firstLineIndent, leftIndent, rightIndent |\n| Hyphenation | hyphenation, hyphenatedWordSize, hyphenationPreference |\n| Position | x, y, width, height, rotation |\n\nSource: [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)\n\n## Color Analysis Tools\n\n### get_colors\n\nExtracts all color definitions used in the document.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `include_diagnostics` | boolean | No | Enable print-specific diagnostics |\n\n**Returns:**\n\n| Color Type | Description |\n|------------|-------------|\n| Swatches | Named colors from swatch panel |\n| Gradients | Gradient definitions (linear/radial) |\n| Spot Colors | Spot color definitions |\n| Process Colors | CMYK/RGB process colors |\n\n**Diagnostics (when enabled):**\n\n| Check | Description |\n|-------|-------------|\n| RGB in CMYK | Detects RGB colors in CMYK documents |\n| Unnamed Colors | Colors not defined in swatches |\n| Gradient Issues | Missing gradient stops |\n\nSource: [src/tools/read/get-colors.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-colors.ts)\n\n### extract_design_tokens\n\nExports document colors and typography as design system tokens.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `format` | string | No | Output format: \"css\", \"json\", or \"tailwind\" |\n| `scope` | string | No | \"colors\", \"typography\", or \"all\" |\n\n**Output Formats:**\n\n| Format | Example |\n|--------|---------|\n| CSS | `--color-primary: #34A853;` |\n| JSON | `{\"color\": {\"primary\": \"#34A853\"}}` |\n| Tailwind | `primary: '#34A853'` |\n\nSource: [src/tools/read/extract-design-tokens.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/extract-design-tokens.ts)\n\n## Image Analysis Tools\n\n### get_images\n\nReturns information about all embedded and linked images.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `include_print_info` | boolean | No | Enable print-quality analysis |\n\n**Returns:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `name` | string | Image filename |\n| `type` | string | \"embedded\" or \"linked\" |\n| `linkStatus` | string | \"ok\", \"missing\", or \"modified\" |\n| `actualPpi` | number | Actual resolution |\n| `effectivePpi` | number | Resolution after scaling |\n| `colorSpace` | string | Color mode of image |\n\n**Print Information (when enabled):**\n\n| Check | Field | Threshold |\n|-------|-------|-----------|\n| Resolution | effectivePpi | 300 for print |\n| Color Space | colorSpace | Match document mode |\n| Scale Factor | scale | Affects effective resolution |\n\nSource: [src/tools/read/get-images.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-images.ts)\n\n## Visual Element Tools\n\n### get_path_items\n\nReturns path and shape data for vector objects.\n\n**Returns:**\n\n| Data Category | Fields |\n|--------------|--------|\n| Fill | fillColor, opacity, blendMode |\n| Stroke | strokeColor, strokeWidth, strokeCap, strokeJoin, dashArray |\n| Geometry | anchorPoints, pathPoints, closed, pathType |\n\n**Path Types:**\n\n| Type | Description |\n|------|-------------|\n| `path` | Custom path with anchor points |\n| `compound` | Compound path with multiple subpaths |\n| `textPath` | Text on a path |\n\n### get_groups\n\nReturns group hierarchy and structure.\n\n**Returns:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `groups[]` | array | List of group objects |\n| `clips` | array | Clipping mask references |\n| `compoundPaths` | array | Compound path structures |\n\n### get_symbols\n\nReturns symbol definitions and all instances in use.\n\n**Returns:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `definitions[]` | array | Symbol library items |\n| `instances[]` | array | Placed symbol instances |\n| `usageCount` | number | How many times each symbol is used |\n\n### get_effects\n\nReturns effects and appearance settings.\n\n**Returns:**\n\n| Effect Type | Properties |\n|-------------|------------|\n| Opacity | opacity, blendMode |\n| Drop Shadow | xOffset, yOffset, blur, color |\n| Glow | blurRadius, spread, color |\n| Inner Effects | innerShadow, innerGlow |\n\n### get_guidelines\n\nReturns guide line information.\n\n**Returns:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `guidelines[]` | array | All guide lines |\n| `orientation` | string | \"horizontal\" or \"vertical\" |\n| `position` | number | Coordinate position |\n\n## Compliance & Accessibility Tools\n\n### check_contrast\n\nPerforms WCAG color contrast ratio analysis.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `foreground` | string | Yes | Foreground color (hex) |\n| `background` | string | Yes | Background color (hex) |\n\n**Returns:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `contrastRatio` | number | WCAG contrast ratio |\n| `wcagAA` | object | AA level pass/fail for normal and large text |\n| `wcagAAA` | object | AAA level pass/fail for normal and large text |\n\n**WCAG Thresholds:**\n\n| Level | Normal Text | Large Text |\n|-------|-------------|------------|\n| AA | 4.5:1 | 3:1 |\n| AAA | 7:1 | 4.5:1 |\n\nSource: [src/tools/read/check-contrast.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/check-contrast.ts)\n\n### find_objects\n\nSearches document objects by various criteria.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `name` | string | No | Object name (partial match) |\n| `type` | string | No | Object type filter |\n| `color` | string | No | Color match |\n| `font` | string | No | Font name filter |\n| `layer` | string | No | Layer name filter |\n\n### get_overprint_info\n\nReturns overprint settings and rich black detection.\n\n**Returns:**\n\n| Check | Description |\n|-------|-------------|\n| Overprint Settings | Objects with overprint enabled |\n| K100 Black | Pure black (K=100) usage |\n| Rich Black | Multi-channel black usage |\n| Intent | Classification as \"process\" or \"spot\" |\n\n### get_separation_info\n\nReturns color separation information for print production.\n\n**Returns:**\n\n| Plate Type | Description |\n|------------|-------------|\n| CMYK Process | Cyan, Magenta, Yellow, Black plates |\n| Spot Colors | Named spot color inks |\n| Usage Count | Object count per color plate |\n\n### get_selection\n\nReturns details of currently selected objects.\n\n**Returns:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `selectedItems[]` | array | All selected objects |\n| `count` | number | Number of selected items |\n| `bounds` | object | Combined bounding box |\n\n## Workflow Integration\n\nRead Tools integrate with Modify and Export Tools in complex workflows:\n\n```mermaid\ngraph LR\n A[Read Tools] -->|Inspect| B[Document Analysis]\n A -->|Validate| C[Preflight Check]\n A -->|Extract| D[Design Tokens]\n \n B --> E[Modify Tools]\n C --> F[Utility Tools]\n D --> G[Export Tools]\n \n E --> H[Document Updates]\n F --> I[Compliance Report]\n G --> J[Asset Export]\n```\n\n### Example Workflow: Export with Text Outlining\n\n```\nget_artboards → Identify target artboards\nconvert_to_outlines → Convert fonts to paths\nexport → Export as SVG/PNG\n```\n\n### Example Workflow: Print Preflight\n\n```\nget_document_info → Check color mode\nget_colors → Validate color definitions\nget_images → Verify image resolution\nget_overprint_info → Check overprint settings\npreflight_check → Comprehensive report\n```\n\n## Common Usage Patterns\n\n### Document Analysis Pattern\n\n```typescript\n// Get full document context\nconst docInfo = await get_document_info();\nconst structure = await get_document_structure();\nconst colors = await get_colors({ include_diagnostics: true });\n```\n\n### Text Audit Pattern\n\n```typescript\n// Comprehensive text analysis\nconst textFrames = await list_text_frames();\nconst details = await Promise.all(\n textFrames.map(tf => get_text_frame_detail({ uuid: tf.uuid }))\n);\n```\n\n### Design System Extraction Pattern\n\n```typescript\n// Export as CSS custom properties\nconst tokens = await extract_design_tokens({ \n format: \"css\",\n scope: \"all\" \n});\n```\n\n## Limitations\n\n| Limitation | Details |\n|------------|---------|\n| Live Effects | Effect parameters (e.g., drop shadow settings) can be detected but not fully read |\n| Bleed Settings | Bleed settings cannot be read (Illustrator API limitation) |\n| Windows COM | Requires PowerShell for Windows COM automation |\n| Document Required | Most tools require an open document (except `list_fonts`) |\n\n## See Also\n\n- [Modify Tools](modify-tools.md) - Tools for editing document content\n- [Export Tools](export-tools.md) - Tools for exporting documents\n- [Utility Tools](utility-tools.md) - Pre-flight and workflow utilities\n- [Preflight Workflow](../workflows/print-preflight-workflow.md) - Complete print compliance workflow\n\n---\n\n\n\n## Modify Tools\n\n### Related Pages\n\nRelated topics: [Read Tools](#read-tools), [Export Tools](#export-tools)\n\n# Modify Tools\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/tools/modify/create-document.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/create-document.ts)\n- [src/tools/modify/create-rectangle.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/create-rectangle.ts)\n- [src/tools/modify/create-text-frame.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/create-text-frame.ts)\n- [src/tools/modify/manage-layers.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/manage-layers.ts)\n- [src/tools/modify/align-objects.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/align-objects.ts)\n- [src/tools/modify/group-objects.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/group-objects.ts)\n- [src/tools/modify/save-document.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/save-document.ts)\n- [src/tools/modify/manage-swatches.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/manage-swatches.ts)\n\n \n\n## Overview\n\nThe **Modify Tools** are a collection of 38 tools within the illustrator-mcp-server that enable AI assistants (specifically Claude) to create, modify, and manipulate objects in Adobe Illustrator documents through natural language commands. These tools form the core of the server's ability to perform design operations by bridging natural language instructions with the Adobe Illustrator scripting API.\n\nThe Modify Tools handle everything from basic shape creation (rectangles, ellipses, lines) to complex operations like object grouping, layer management, and document saving. They are designed to work seamlessly with the Read Tools and Export Tools to provide a complete workflow for automated design tasks.\n\n## Architecture\n\n### Tool Categories\n\nThe Modify Tools are organized into several functional categories:\n\n```mermaid\ngraph TD\n A[Modify Tools] --> B[Shape Creation]\n A --> C[Text Creation]\n A --> D[Object Manipulation]\n A --> E[Layer Management]\n A --> F[Document Operations]\n A --> G[Color Management]\n \n B --> B1[create_rectangle]\n B --> B2[create_ellipse]\n B --> B3[create_line]\n B --> B4[create_path]\n \n C --> C1[create_text_frame]\n \n D --> D1[modify_object]\n D --> D2[group_objects]\n D --> D3[ungroup_objects]\n D --> D4[duplicate_objects]\n D --> D5[align_objects]\n D --> D6[set_z_order]\n D --> D7[move_to_layer]\n \n E --> E1[manage_layers]\n \n F --> F1[create_document]\n F --> F2[open_document]\n F --> F3[save_document]\n F --> F4[close_document]\n \n G --> G1[manage_swatches]\n G --> G2[replace_color]\n G --> G3[assign_color_profile]\n```\n\n### Relationship with Coordinate Systems\n\nAll Modify Tools automatically adapt to the document's coordinate system, which is auto-detected based on the document type:\n\n| Document Type | Coordinate System | Origin | Y-axis Direction |\n|---------------|-------------------|--------|------------------|\n| CMYK / Print | `document` | Bottom-left | Up |\n| RGB / Web | `artboard-web` | Top-left of artboard | Down |\n\nSource: [README.md - Coordinate System](README.md)\n\n---\n\n## Shape Creation Tools\n\n### create_rectangle\n\nCreates a rectangle shape in the active document. Supports rounded corners through optional parameters.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `x` | number | X position of the rectangle |\n| `y` | number | Y position of the rectangle |\n| `width` | number | Width of the rectangle |\n| `height` | number | Height of the rectangle |\n| `cornerRadius` | number | Optional corner radius for rounded rectangles |\n\n**Usage Example:**\n\n```typescript\n// Create a basic rectangle\nawait create_rectangle({\n x: 100,\n y: 100,\n width: 200,\n height: 150\n});\n\n// Create a rounded rectangle\nawait create_rectangle({\n x: 100,\n y: 100,\n width: 200,\n height: 150,\n cornerRadius: 20\n});\n```\n\nSource: [src/tools/modify/create-rectangle.ts](src/tools/modify/create-rectangle.ts)\n\n### create_ellipse\n\nCreates an ellipse shape in the active document.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `x` | number | X position of the ellipse center |\n| `y` | number | Y position of the ellipse center |\n| `radiusX` | number | Horizontal radius |\n| `radiusY` | number | Vertical radius |\n\n### create_line\n\nCreates a line segment between two points.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `startX` | number | Starting X coordinate |\n| `startY` | number | Starting Y coordinate |\n| `endX` | number | Ending X coordinate |\n| `endY` | number | Ending Y coordinate |\n\n### create_path\n\nCreates a custom path with Bezier curve handles for complex shapes.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `pathData` | string | SVG path data string defining the shape |\n\n---\n\n## Text Creation Tools\n\n### create_text_frame\n\nCreates a text frame that can be either point text (single line) or area text (paragraph text within bounds).\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `x` | number | X position |\n| `y` | number | Y position |\n| `contents` | string | The text content to display |\n| `textType` | \"point\" \\| \"area\" | Type of text frame |\n| `width` | number | Width (required for area text) |\n| `height` | number | Height (required for area text) |\n| `fontSize` | number | Font size in points |\n| `fontFamily` | string | Font family name |\n| `fontStyle` | string | Font style (Bold, Italic, etc.) |\n| `justification` | string | Text alignment |\n| `lineSpacing` | number | Line height/spacing |\n\nSource: [src/tools/modify/create-text-frame.ts](src/tools/modify/create-text-frame.ts)\n\n---\n\n## Object Manipulation Tools\n\n### modify_object\n\nModifies properties of an existing object. This is a versatile tool that can update fill, stroke, position, size, and other attributes of any selected or referenced object.\n\n**Modifiable Properties:**\n\n| Property Category | Attributes |\n|-------------------|------------|\n| Position | `x`, `y`, `width`, `height` |\n| Fill | `fillColor`, `fillPattern`, `fillGradient` |\n| Stroke | `strokeColor`, `strokeWidth`, `strokeCap`, `strokeJoin` |\n| Transform | `rotation`, `shear`, `flip` |\n| Appearance | `opacity`, `blendMode` |\n\n**Usage Example:**\n\n```typescript\nawait modify_object({\n target: \"object-uuid\",\n properties: {\n fillColor: \"#FF5733\",\n strokeColor: \"#000000\",\n strokeWidth: 2,\n opacity: 0.8\n }\n});\n```\n\nSource: [src/tools/modify/group-objects.ts](src/tools/modify/group-objects.ts)\n\n### duplicate_objects\n\nCreates a copy of specified objects with an optional positional offset.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `sourceIds` | string[] | Array of object UUIDs to duplicate |\n| `offsetX` | number | Horizontal offset for the copy |\n| `offsetY` | number | Vertical offset for the copy |\n\n### align_objects\n\nAligns and distributes multiple objects relative to each other or to a container.\n\n**Alignment Options:**\n\n| Option | Description |\n|--------|-------------|\n| `alignHorizontal` | Left, Center, Right |\n| `alignVertical` | Top, Center, Bottom |\n| `distributeHorizontal` | Equal horizontal spacing |\n| `distributeVertical` | Equal vertical spacing |\n\nSource: [src/tools/modify/align-objects.ts](src/tools/modify/align-objects.ts)\n\n### set_z_order\n\nChanges the stacking order of objects within their layer.\n\n**Options:**\n\n| Value | Description |\n|-------|-------------|\n| `front` | Move to front of layer |\n| `back` | Move to back of layer |\n| `forward` | Move one position forward |\n| `backward` | Move one position backward |\n\n### move_to_layer\n\nTransfers objects from their current layer to a specified target layer.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `objectIds` | string[] | UUIDs of objects to move |\n| `targetLayer` | string | Name or UUID of destination layer |\n\n---\n\n## Grouping Tools\n\n### group_objects\n\nCombines multiple objects into a group. Supports clipping masks for advanced composition.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `objectIds` | string[] | Array of object UUIDs to group |\n| `createClippingMask` | boolean | Optional flag to create a clipping mask group |\n\nSource: [src/tools/modify/group-objects.ts](src/tools/modify/group-objects.ts)\n\n### ungroup_objects\n\nSeparates a group into its constituent child objects.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `groupId` | string | UUID of the group to ungroup |\n\n---\n\n## Layer Management Tools\n\n### manage_layers\n\nProvides comprehensive layer operations including creation, renaming, visibility control, locking, reordering, and deletion.\n\n**Operations:**\n\n| Operation | Description |\n|-----------|-------------|\n| `add` | Create a new layer |\n| `rename` | Change layer name |\n| `delete` | Remove a layer |\n| `show` / `hide` | Toggle layer visibility |\n| `lock` / `unlock` | Toggle layer editability |\n| `move` | Reorder layer position |\n| `merge` | Combine layers |\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `operation` | string | The action to perform |\n| `layerName` | string | Name of the layer |\n| `targetLayer` | string | Optional target for move/merge operations |\n\nSource: [src/tools/modify/manage-layers.ts](src/tools/modify/manage-layers.ts)\n\n---\n\n## Document Operations\n\n### create_document\n\nCreates a new Illustrator document with specified dimensions and color mode.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `width` | number | Document width in points |\n| `height` | number | Document height in points |\n| `colorMode` | \"RGB\" \\| \"CMYK\" | Color mode for the document |\n| `name` | string | Document name |\n\n**Example - Creating a Full HD document:**\n\n```typescript\nawait create_document({\n width: 1920,\n height: 1080,\n colorMode: \"RGB\",\n name: \"Web Banner\"\n});\n```\n\nSource: [src/tools/modify/create-document.ts](src/tools/modify/create-document.ts)\n\n### open_document\n\nOpens an existing Illustrator document from a file path.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `filePath` | string | Full path to the document |\n\n### save_document\n\nSaves or performs a save-as operation on the active document.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `filePath` | string | Optional path for save-as |\n| `options` | object | Save options (format-specific) |\n\nSource: [src/tools/modify/save-document.ts](src/tools/modify/save-document.ts)\n\n### close_document\n\nCloses the active document with optional save prompt handling.\n\n---\n\n## Color Management Tools\n\n### manage_swatches\n\nManages color swatches in the document's Swatches panel.\n\n**Operations:**\n\n| Operation | Description |\n|-----------|-------------|\n| `add` | Add a new swatch |\n| `remove` | Delete a swatch |\n| `rename` | Change swatch name |\n| `list` | Get all swatches |\n\nSource: [src/tools/modify/manage-swatches.ts](src/tools/modify/manage-swatches.ts)\n\n### replace_color\n\nFinds and replaces colors throughout the document with configurable tolerance for similar colors.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `sourceColor` | string | Color to find (hex, RGB, CMYK) |\n| `targetColor` | string | Replacement color |\n| `tolerance` | number | Similarity threshold (0-100) |\n\n### assign_color_profile\n\nAssigns (tags) a color profile to the document without converting color values.\n\n---\n\n## Utility Operations\n\n### convert_to_outlines\n\nConverts text characters to vector paths (outlines), ensuring consistent rendering regardless of font availability.\n\n**Use Cases:**\n- Preparing files for print production\n- Ensuring exact character shapes\n- Removing font dependencies\n\n**Note:** This operation is irreversible. Always confirm before converting.\n\n### place_image\n\nPlaces an image file as either a linked or embedded object.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `filePath` | string | Path to the image file |\n| `x` | number | X position |\n| `y` | number | Y position |\n| `width` | number | Display width |\n| `height` | number | Display height |\n| `link` | boolean | Whether to link (true) or embed (false) |\n\n### resize_for_variation\n\nCreates proportional size variations from a source artboard.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `sourceArtboard` | string | UUID of source artboard |\n| `scaleFactors` | number[] | Array of scale percentages |\n\n---\n\n## Workflow Integration\n\nThe Modify Tools work in conjunction with Read Tools to enable intelligent modifications:\n\n```mermaid\ngraph LR\n A[Read Tools] --> B[Analyze Current State]\n B --> C[Determine Required Changes]\n C --> D[Modify Tools]\n D --> E[Execute Operations]\n E --> F[Read Tools]\n F --> G[Verify Results]\n```\n\n### Typical Workflow Pattern\n\n1. **Read** current document state using Read Tools\n2. **Plan** modifications based on requirements\n3. **Execute** Modify Tools in appropriate order\n4. **Verify** changes using Read Tools\n5. **Export** final result using Export Tools\n\n---\n\n## Coordinate System Handling\n\nAll Modify Tools automatically handle coordinate system conversion based on document type:\n\n```mermaid\ngraph TD\n A[Document Type Detected] --> B{CMYK or RGB?}\n B -->|CMYK / Print| C[Use document coordinate system]\n B -->|RGB / Web| D[Use artboard-web coordinate system]\n C --> E[Origin: Bottom-left]\n D --> F[Origin: Top-left]\n E --> G[Calculate Absolute Position]\n F --> G\n```\n\nFor RGB documents, the `convert_coordinate` tool can manually convert between coordinate systems when needed.\n\n---\n\n## Error Handling\n\nThe Modify Tools implement robust error handling for common scenarios:\n\n| Scenario | Handling |\n|----------|----------|\n| Invalid object UUID | Return error with suggestion to verify object exists |\n| Out-of-bounds coordinates | Clamp to document bounds or return warning |\n| Unsupported color format | Attempt auto-conversion or return error |\n| Layer operation on locked layer | Return error with unlock suggestion |\n| File access permission denied | Return specific error for save/open operations |\n\n---\n\n## Known Limitations\n\n| Limitation | Details |\n|------------|---------|\n| Live Effects | Drop shadow and other effect parameters can be detected but not read |\n| Color Profiles | Only profile assignment available; full conversion not supported |\n| Bleed Settings | Cannot read bleed settings (API limitation) |\n| WebP Export | Not supported; use PNG or SVG instead |\n\nSource: [README.md - Known Limitations](README.md)\n\n---\n\n## Quick Reference\n\n| Tool Category | Tools |\n|---------------|-------|\n| Shape Creation | `create_rectangle`, `create_ellipse`, `create_line`, `create_path` |\n| Text | `create_text_frame`, `convert_to_outlines` |\n| Object Manipulation | `modify_object`, `duplicate_objects`, `align_objects`, `set_z_order`, `move_to_layer` |\n| Grouping | `group_objects`, `ungroup_objects` |\n| Layers | `manage_layers` |\n| Document | `create_document`, `open_document`, `save_document`, `close_document` |\n| Color | `manage_swatches`, `replace_color`, `assign_color_profile` |\n| Media | `place_image`, `resize_for_variation` |\n\n---\n\n## See Also\n\n- **Read Tools** - Tools for inspecting document content\n- **Export Tools** - Tools for exporting documents to various formats\n- **Utility Tools** - Preflight, text consistency, and workflow configuration\n\n---\n\n\n\n## Export Tools\n\n### Related Pages\n\nRelated topics: [Read Tools](#read-tools), [Modify Tools](#modify-tools)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/tools/export/export.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export.ts)\n- [src/tools/export/export-pdf.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export-pdf.ts)\n- [src/tools/registry.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/registry.ts)\n- [server.json](https://github.com/ie3jp/illustrator-mcp-server/blob/main/server.json)\n- [manifest.json](https://github.com/ie3jp/illustrator-mcp-server/blob/main/manifest.json)\n \n\n# Export Tools\n\nThe Export Tools module provides capabilities for exporting Adobe Illustrator documents and artwork to various file formats suitable for web, print, and digital distribution. This module consists of two primary tools: `export` for raster and vector formats (SVG, PNG, JPG), and `export_pdf` for print-ready PDF production with professional prepress features.\n\n## Overview\n\nExport Tools are classified under Phase 3 of the illustrator-mcp-server architecture, focusing on export operations and print-oriented reading capabilities. These tools enable Claude to transform Illustrator documents into standardized output formats while maintaining design integrity and supporting industry-standard print production workflows.\n\n| Tool | Primary Use Case | Formats Supported |\n|------|------------------|-------------------|\n| `export` | Web assets, screen output, image formats | SVG, PNG, JPG |\n| `export_pdf` | Print production, prepress workflows | PDF with presets |\n\nSource: [src/tools/registry.ts:9-10](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/registry.ts)\n\n## Architecture\n\n### Component Interaction\n\n```mermaid\nflowchart TD\n subgraph Server[\"illustrator-mcp-server\"]\n ExportTool[\"export tool\"]\n ExportPdfTool[\"export_pdf tool\"]\n end\n \n subgraph Illustrator[\"Adobe Illustrator\"]\n JSX[\"JSX Script\\n(ExtendScript)\"]\n Document[\"Active Document\"]\n Artboards[\"Artboards Collection\"]\n end\n \n ExportTool -->|generates| ExportJSX[\"script-{uuid}.jsx\"]\n ExportPdfTool -->|generates| PdfJSX[\"script-{uuid}.jsx\"]\n \n ExportJSX -->|executes| Illustrator\n PdfJSX -->|executes| Illustrator\n \n Illustrator -->|writes| ResultFile[\"result-{uuid}.json\"]\n ResultFile -->|reads| Server\n \n Document -->|exports to| SVG[\"SVG File\"]\n Document -->|exports to| PNG[\"PNG File\"]\n Document -->|exports to| PDF[\"PDF File\"]\n```\n\n### Export Workflow Sequence\n\n```mermaid\nsequenceDiagram\n participant Client as Claude/Client\n participant Server as MCP Server\n participant AI as Adobe Illustrator\n \n Client->>Server: Request export (format, options)\n Server->>Server: Generate UUID\n Server->>Server: Create params-{uuid}.json\n Server->>Server: Create script-{uuid}.jsx\n Server->>Server: Execute via osascript/PS\n \n rect rgb(200, 220, 240)\n Note over AI: Illustrator executes JSX script\n AI->>AI: Load parameters\n AI->>AI: Open/access document\n AI->>AI: Apply export settings\n AI->>AI: Write output file\n AI->>AI: Write result-{uuid}.json\n end\n \n Server->>Server: Read result-{uuid}.json\n Server->>Client: Return export result\n \n alt Verification Required\n Server->>Server: Check file existence\n alt File not created\n Server->>Client: Error with path details\n end\n end\n```\n\n## Export Tool (`export`)\n\nThe `export` tool handles conversion of Illustrator content to web-friendly and raster formats. It supports exporting by artboard, selection, or specific object UUID.\n\n### Tool Registration\n\n```typescript\nserver.registerTool(\n 'export',\n {\n title: 'Export',\n description: 'Export objects, groups, artboards...',\n inputSchema: {\n // Parameters defined in source\n }\n }\n);\n```\n\nSource: [src/tools/export/export.ts:55-60](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export.ts)\n\n### Supported Formats\n\n| Format | Use Case | Color Support | Transparency |\n|--------|----------|---------------|--------------|\n| SVG | Web vector graphics, scalable icons | RGB/CMYK | Preserved |\n| PNG | Web images with transparency | RGB/RGBA | Preserved |\n| JPG | Compressed photographic output | RGB | Not supported |\n\n### Export Options\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `format` | string | Yes | Output format: `svg`, `png`, `jpg` |\n| `output_path` | string | No | Output file path. Auto-generates in document directory or ~/Desktop for unsaved documents |\n| `artboard_index` | number | No | Zero-based artboard index for multi-artboard documents |\n| `scale` | number | No | Scale factor for raster exports (PNG/JPG) |\n| `dpi` | number | No | Target DPI for raster exports (default: 72) |\n\n### Raster Export Details\n\nFor PNG and JPG exports, the effective DPI is calculated by multiplying the specified DPI by the scale factor:\n\n```json\n{\n \"success\": true,\n \"output_path\": \"/path/to/output.png\",\n \"format\": \"png\",\n \"dpi\": 144,\n \"scale\": 2\n}\n```\n\nSource: [src/tools/export/export.ts:42-45](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export.ts)\n\n### SVG Export Behavior\n\nThe SVG export includes special handling for artboard-named files:\n\n1. When exporting an artboard with format `svg` and an `artboard_index` is specified\n2. The output filename follows pattern: `{baseName}_{artboardName}.svg`\n3. Artboard names have spaces replaced with hyphens\n\nExample:\n- Document: `design.ai` in `/output/`\n- Artboard: `hero section`\n- Output: `/output/design_hero-section.svg`\n\nSource: [src/tools/export/export.ts:18-28](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export.ts)\n\n### Verification and Error Handling\n\nThe tool performs post-export verification:\n\n```typescript\nvar finalFile = new File(actualPath);\nif (!finalFile.exists) {\n writeResultFile(RESULT_PATH, { \n error: true, \n message: \"Export completed but output file was not created. The path may not be writable: \" + outputPath \n });\n}\n```\n\nSource: [src/tools/export/export.ts:46-48](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export.ts)\n\n## Export PDF Tool (`export_pdf`)\n\nThe `export_pdf` tool generates print-ready PDF files with comprehensive prepress options including crop marks, bleed settings, and PDF preset support.\n\n### Tool Registration\n\n```typescript\nserver.registerTool(\n 'export_pdf',\n {\n title: 'Export PDF',\n description: 'Export print-ready PDF. Note: Illustrator will be activated (brought to foreground) during execution.',\n inputSchema: {\n output_path: z.string().optional(),\n preset: z.string().optional(),\n options: z.object({...})\n }\n }\n);\n```\n\nSource: [src/tools/export/export-pdf.ts:54-68](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export-pdf.ts)\n\n### PDF Export Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `output_path` | string | No | Output file path. Auto-generates in document directory or ~/Desktop |\n| `preset` | string | No | PDF preset name (e.g., `\"[PDF/X-4:2008]\"`) |\n| `options.trim_marks` | boolean | No | Add trim marks to the export |\n| `options.marks_style` | enum | No | Trim mark style: `japanese` (double-line) or `roman` (single-line) |\n| `options.trim_mark_weight` | enum | No | Trim mark weight: `\"0.125\"`, `\"0.25\"`, `\"0.5\"` (in points) |\n| `options.registration_marks` | boolean | No | Include registration marks |\n| `options.color_bars` | boolean | No | Include color bars |\n| `options.page_information` | boolean | No | Include page information |\n\n### Japanese Crop Marks\n\nThe PDF export includes specialized handling for Japanese crop marks. When `marks_style` is set to `japanese`, the system:\n\n1. Generates Japanese crop marks using the Illustrator TrimMark command\n2. Creates marks as document paths for reliable rendering\n3. Removes marks after PDF export via undo operation\n4. Includes a note in the result indicating this behavior\n\n```typescript\nif (writeResult.japanese_marks_note) {\n result.japanese_marks_note = \"Japanese crop marks were generated as document paths via TrimMark command for reliable rendering, then removed after export.\";\n}\n```\n\nSource: [src/tools/export/export-pdf.ts:21-23](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export-pdf.ts)\n\n### PDF Presets\n\nCommon PDF presets supported by Illustrator include:\n\n| Preset | Standard | Use Case |\n|--------|----------|----------|\n| `[PDF/X-1a:2001]` | PDF/X-1a | Print production with strict requirements |\n| `[PDF/X-4:2008]` | PDF/X-4 | Modern print workflows with transparency |\n| `[Press Quality]` | General | High-quality print output |\n| `[Smallest File Size]` | General | Web delivery |\n\n### PDF Export Result\n\nSuccessful PDF export returns:\n\n```json\n{\n \"success\": true,\n \"output_path\": \"/path/to/document.pdf\",\n \"format\": \"pdf\"\n}\n```\n\n### Error Handling\n\nPDF export errors include line number information for debugging:\n\n```typescript\ncatch (e) {\n writeResultFile(RESULT_PATH, { \n error: true, \n message: \"PDF export failed: \" + e.message, \n line: e.line \n });\n}\n```\n\nSource: [src/tools/export/export-pdf.ts:30-32](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export-pdf.ts)\n\n## Coordinate System Considerations\n\nExport tools automatically handle coordinate system differences based on document color mode:\n\n| Document Type | Coordinate System | Origin | Y-Axis Direction |\n|---------------|-------------------|--------|------------------|\n| CMYK/Print | `document` | Bottom-left | Up |\n| RGB/Web | `artboard-web` | Top-left of artboard | Down |\n\nThis affects how coordinates are interpreted during export, particularly for SVG output where coordinate transformation may be required.\n\n## Integration with Preflight\n\nExport tools are commonly used in conjunction with the preflight check tool for print workflows:\n\n```mermaid\nflowchart LR\n Preflight[\"preflight_check\"] --> |Validates| Doc[\"Document\"]\n Doc --> |If compliant| ExportPDF[\"export_pdf\"]\n ExportPDF --> |Generates| PrintReady[\"Print-Ready PDF\"]\n \n Preflight --> |If issues found| Review[\"Manual Review Required\"]\n```\n\nThe typical print workflow:\n1. Run `preflight_check` with target profile (e.g., `x1a`)\n2. Review compliance errors and warnings\n3. Fix issues in Illustrator\n4. Export using `export_pdf` with appropriate settings\n\n## Usage Examples\n\n### Export Artboard as SVG\n\n```\nYou: Export the hero artboard as SVG with outlined text\n\nClaude: → get_artboards → convert_to_outlines → export\n```\n\n### Export Selection as PNG\n\n```json\n{\n \"format\": \"png\",\n \"output_path\": \"/output/banner.png\",\n \"scale\": 2,\n \"dpi\": 144\n}\n```\n\n### Export Print-Ready PDF\n\n```json\n{\n \"preset\": \"[PDF/X-4:2008]\",\n \"options\": {\n \"trim_marks\": true,\n \"marks_style\": \"japanese\",\n \"registration_marks\": true,\n \"color_bars\": true\n }\n}\n```\n\n## Limitations and Notes\n\n| Feature | Limitation | Workaround |\n|---------|------------|------------|\n| Illustrator activation | `export_pdf` brings Illustrator to foreground | User should close other apps if needed |\n| Bleed settings | Cannot be controlled directly via API | Use PDF presets that include bleed |\n| Font embedding mode | Full/subset mode not directly controllable | Use PDF presets |\n| Size variations | Only proportional scaling supported | Manual text adjustment may be needed |\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Related Tools\n\n| Tool Category | Tools |\n|---------------|-------|\n| Read Tools | `get_artboards`, `get_document_structure` |\n| Modify Tools | `convert_to_outlines` |\n| Utility | `preflight_check`, `check_text_consistency` |\n\n---\n\n\n\n## Utility Tools\n\n### Related Pages\n\nRelated topics: [Read Tools](#read-tools)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/tools/utility/preflight-check.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/utility/preflight-check.ts)\n- [src/tools/utility/check-text-consistency.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/utility/check-text-consistency.ts)\n- [src/tools/utility/set-workflow.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/utility/set-workflow.ts)\n- [src/tools/utility/set-illustrator-version.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/utility/set-illustrator-version.ts)\n \n\n# Utility Tools\n\nUtility Tools in the illustrator-mcp-server provide essential辅助功能 for document validation, workflow configuration, and system integration. These tools enable quality assurance workflows, coordinate system management, and environment setup essential for reliable Illustrator automation.\n\n## Overview\n\nThe Utility Tools category encompasses three primary tools that support document preparation, validation, and configuration:\n\n| Tool | Purpose |\n|------|---------|\n| `preflight_check` | Comprehensive pre-press quality validation |\n| `check_text_consistency` | Text content validation and consistency analysis |\n| `set_workflow` | Coordinate system and workflow mode configuration |\n\nThese tools serve as the foundation for print-ready production workflows, ensuring documents meet industry standards before export or submission.\n\n## Preflight Check\n\nThe `preflight_check` tool performs automated pre-press validation to identify issues that could compromise print quality or PDF/X compliance.\n\n### Purpose and Scope\n\nThe preflight check analyzes documents for print-critical issues including color space violations, missing assets, resolution problems, and PDF/X compliance failures. It provides a structured report with severity classification to prioritize fixes.\n\nSource: [README.md](README.md)\n\n### Supported Checks\n\nThe tool performs the following validations:\n\n| Check Category | Detects |\n|----------------|---------|\n| Color Mode | RGB colors in CMYK documents |\n| Links | Broken or missing linked images |\n| Resolution | Images below minimum DPI threshold |\n| Overprint | White objects set to overprint |\n| Transparency | Transparency interactions with overprint |\n| PDF/X | Profile compliance (X-1a, X-4) |\n| Spot Colors | Unused or unexpected spot colors |\n\nSource: [README.md](README.md)\n\n### Parameters\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `target_pdf_profile` | string | No | - | Target PDF profile: `\"x1a\"` or `\"x4\"` |\n| `min_dpi` | number | No | 300 | Minimum acceptable image resolution for print |\n| `include_print_info` | boolean | No | false | Include detailed print-specific diagnostics |\n\nSource: [src/tools/utility/preflight-check.ts](src/tools/utility/preflight-check.ts)\n\n### Output Structure\n\nThe preflight check returns categorized results:\n\n```typescript\ninterface PreflightResult {\n critical: PreflightIssue[];\n warnings: PreflightIssue[];\n info: PreflightInfo[];\n}\n```\n\n### PDF/X Compliance Profiles\n\n| Profile | Characteristics | Transparency |\n|---------|-----------------|--------------|\n| PDF/X-1a | CMYK/spot only, no transparency, no layers | Prohibited |\n| PDF/X-4 | Supports transparency and layers, ICC-based | Allowed |\n\nSource: [README.md](README.md)\n\n### Example Output\n\n```\n❌ PDF/X-1a compliance errors:\n- Transparency on 3 objects (X-1a prohibits transparency)\n- RGB colors found in 2 places (X-1a requires CMYK/spot only)\n\n⚠ Warnings:\n- 5 non-outlined fonts (embedding recommended)\n- Image \"photo_02.jpg\" at 150dpi (300dpi recommended)\n```\n\nSource: [README.md](README.md)\n\n## Check Text Consistency\n\nThe `check_text_consistency` tool validates text content to ensure documents are production-ready and free of placeholder or inconsistent text.\n\n### Purpose and Scope\n\nThis tool detects common text issues in design documents: dummy/placeholder text that must be replaced, notation variations that indicate inconsistencies, and provides a complete text dump for LLM-driven analysis.\n\nSource: [README.md](README.md)\n\n### Detection Capabilities\n\n| Detection Type | Description |\n|----------------|-------------|\n| Placeholder Text | Detects common placeholder patterns (Lorem ipsum, sample text) |\n| Notation Variations | Identifies katakana/halfwidth/fullwidth inconsistencies |\n| Full Text Listing | Exports all text content for external analysis |\n\nSource: [plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md](plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md)\n\n### Return Values\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `hasPlaceholder` | boolean | Whether placeholder text was detected |\n| `placeholderMatches` | string[] | Array of detected placeholder patterns |\n| `notationVariations` | NotationIssue[] | Array of notation inconsistencies |\n| `allTexts` | TextItem[] | Complete listing of all text in document |\n\nSource: [src/tools/utility/check-text-consistency.ts](src/tools/utility/check-text-consistency.ts)\n\n### Workflow Integration\n\nThe tool integrates with the illustrator-preflight skill to provide LLM-driven deeper analysis:\n\n```mermaid\nflowchart TD\n A[check_text_consistency] --> B[allTexts Array]\n B --> C[LLM Analysis]\n C --> D{Typo Detection}\n C --> E{Version Mismatch}\n C --> F{Terminology Check}\n D --> G[Critical Issues]\n E --> G\n F --> G\n```\n\nSource: [plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md](plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md)\n\n## Set Workflow\n\nThe `set_workflow` tool configures the coordinate system and workflow mode to override auto-detected settings.\n\n### Purpose and Scope\n\nThe tool enables manual override of the automatic coordinate system detection, ensuring consistent behavior regardless of document type. This is essential when working with documents that have unconventional settings or when specific coordinate conventions are required.\n\nSource: [README.md](README.md)\n\n### Coordinate System Detection\n\nThe server automatically detects coordinate systems based on document type:\n\n| Document Type | Coordinate System | Origin | Y Axis Direction |\n|---------------|-------------------|--------|-------------------|\n| CMYK / Print | `document` | Bottom-left | Up |\n| RGB / Web | `artboard-web` | Top-left of artboard | Down |\n\nSource: [README.md](README.md)\n\n### Workflow Modes\n\n| Mode | Use Case |\n|------|----------|\n| `web` | RGB documents, web assets, screen output |\n| `print` | CMYK documents, print production, PDF export |\n\n### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `mode` | string | Yes | Workflow mode: `\"web\"` or `\"print\"` |\n\n### Behavior\n\nWhen `set_workflow` is called:\n\n1. The specified mode overrides auto-detection\n2. All subsequent coordinate conversions use the configured system\n3. Tools like `convert_coordinate` respect the active workflow mode\n\n```mermaid\nflowchart LR\n A[Document Opens] --> B{User calls set_workflow?}\n B -->|No| C[Auto-detect coordinate system]\n B -->|Yes| D[Use specified mode]\n C --> E[Return coordinates]\n D --> E\n```\n\nSource: [src/tools/utility/set-workflow.ts](src/tools/utility/set-workflow.ts)\n\n## Set Illustrator Version\n\nThe `set_illustrator_version` tool configures the target Illustrator version for script generation compatibility.\n\n### Purpose and Scope\n\nDifferent Illustrator versions support different scripting APIs and features. This tool ensures generated scripts target the correct version, preventing compatibility issues when working with legacy or specific version requirements.\n\nSource: [src/tools/utility/set-illustrator-version.ts](src/tools/utility/set-illustrator-version.ts)\n\n### Supported Versions\n\n| Version | Script Engine | Notes |\n|---------|---------------|-------|\n| CC 2017+ | ExtendScript / UXP | Modern scripting support |\n| Legacy | ExtendScript | Older version compatibility |\n\n### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `version` | string | Yes | Illustrator version string (e.g., \"2024\", \"CC 2023\") |\n\n## Utility Tool Architecture\n\n```mermaid\nflowchart TB\n subgraph \"Utility Tools\"\n PC[preflight_check]\n CTC[check_text_consistency]\n SW[set_workflow]\n SIV[set_illustrator_version]\n end\n \n subgraph \"Supporting Infrastructure\"\n GSI[get_separation_info]\n GOI[get_overprint_info]\n CC[convert_coordinate]\n end\n \n PC --> GSI\n PC --> GOI\n PC --> CTC\n SW --> CC\n SIV --> PC\n \n subgraph \"Output\"\n Reports[Preflight Reports]\n TextDump[Text Analysis]\n Config[Workflow Config]\n end\n \n PC --> Reports\n CTC --> TextDump\n SW --> Config\n```\n\n## Integration with illustrator-preflight Skill\n\nThe Utility Tools are orchestrated by the `illustrator-preflight` skill for comprehensive pre-press workflows:\n\n```mermaid\nsequenceDiagram\n participant User\n participant Skill\n participant Tools\n \n User->>Skill: Run preflight check\n Skill->>Tools: preflight_check\n Skill->>Tools: get_overprint_info\n Skill->>Tools: check_text_consistency\n Tools-->>Skill: Results\n Skill->>Skill: Analyze & Classify\n Skill->>Tools: get_separation_info (conditional)\n Tools-->>Skill: Plate info\n Skill-->>User: Structured Report\n```\n\nSource: [plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md](plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md)\n\n### Preflight Workflow Steps\n\nThe skill executes a 7-step comprehensive pre-press workflow:\n\n| Step | Name | Actions |\n|------|------|---------|\n| 1 | Document | Get document info and structure |\n| 2 | Preflight | Run preflight_check |\n| 3 | Overprint | Run get_overprint_info |\n| 4 | Separations | Run get_separation_info (if spot colors) |\n| 5 | Images | Check image quality and resolution |\n| 6 | Colors | Validate color space compliance |\n| 7 | Text | Run check_text_consistency |\n\nSource: [README.md](README.md)\n\n## Common Usage Patterns\n\n### Pre-Delivery Validation\n\n```typescript\n// Run comprehensive preflight before submission\nconst preflight = await preflight_check({\n target_pdf_profile: \"x1a\",\n min_dpi: 300\n});\n\nconst overprint = await get_overprint_info();\nconst textCheck = await check_text_consistency();\n```\n\n### Workflow Configuration for Print\n\n```typescript\n// Configure for CMYK print workflow\nawait set_workflow({ mode: \"print\" });\n\n// All subsequent operations use document coordinates\nconst coords = await convert_coordinate({\n x: 100,\n y: 100,\n from: \"artboard\",\n to: \"document\"\n});\n```\n\n### Text Content Audit\n\n```typescript\nconst textResult = await check_text_consistency();\n\n// Check for placeholders\nif (textResult.hasPlaceholder) {\n console.log(\"Replace placeholder text:\", textResult.placeholderMatches);\n}\n\n// LLM-driven analysis of all text\nconst allText = textResult.allTexts.map(t => t.content);\n```\n\n## Error Handling and Limitations\n\n### Known Constraints\n\n| Limitation | Details |\n|------------|---------|\n| Live Effects | Effect parameters can be detected but not read |\n| Bleed Settings | Cannot be read due to Illustrator API limitation |\n| Font Embedding | Embedding mode cannot be controlled directly |\n\nSource: [README.md](README.md)\n\n### Best Practices\n\n1. Always run `preflight_check` before print submission\n2. Use `check_text_consistency` to catch placeholder text before delivery\n3. Set workflow mode explicitly when working with mixed document types\n4. Configure Illustrator version when targeting specific deployment environments\n\n---\n\n\n\n## Coordinate Systems\n\n### Related Pages\n\nRelated topics: [Execution Flow](#execution-flow), [Modify Tools](#modify-tools)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/tools/read/convert-coordinate.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/convert-coordinate.ts)\n- [src/tools/session.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/session.ts)\n \n\n# Coordinate Systems\n\nAdobe Illustrator uses two distinct coordinate systems with different origins and Y-axis orientations. The illustrator-mcp-server provides unified coordinate handling that automatically detects the appropriate system based on the document type, while also allowing manual override when needed.\n\n## Overview\n\nCoordinate systems in Illustrator determine how positions are interpreted across the application. The illustrator-mcp-server abstracts the complexity of coordinate transformations, allowing AI assistants to work with positions in a consistent manner regardless of the underlying document configuration.\n\nThe server automatically detects which coordinate system is in use based on document properties and includes coordinate system information in all tool responses via the `coordinateSystem` field.\n\n## Coordinate System Types\n\nThe illustrator-mcp-server supports two coordinate systems:\n\n| System | Document Type | Origin | Y-Axis | Use Case |\n|--------|--------------|--------|--------|----------|\n| `document` | CMYK / Print | Bottom-left | Up | Traditional print design |\n| `artboard-web` | RGB / Web | Top-left of artboard | Down | Web and digital design |\n\n### Document Coordinate System\n\nThe `document` coordinate system uses Illustrator's native coordinate space:\n\n- **Origin**: Bottom-left corner of the document\n- **Y-Axis**: Positive values extend upward\n- **Application**: CMYK documents, print workflows\n- **Behavior**: Matches what print designers expect from traditional illustration software\n\nThis system is detected when the document color mode is set to CMYK.\n\n### Artboard Web Coordinate System\n\nThe `artboard-web` coordinate system uses a web-style coordinate space:\n\n- **Origin**: Top-left corner of the active artboard\n- **Y-Axis**: Positive values extend downward\n- **Application**: RGB documents, web and digital workflows\n- **Behavior**: Matches browser and screen coordinate conventions\n\nThis system is detected when the document color mode is set to RGB.\n\n## Auto-Detection Mechanism\n\nThe server automatically determines the appropriate coordinate system based on document properties. This detection happens on session start and when documents change.\n\n```mermaid\ngraph TD\n A[Document Open] --> B{Color Mode?}\n B -->|CMYK| C[Use document System]\n B -->|RGB| D[Use artboard-web System]\n C --> E[Set coordinateSystem Field]\n D --> E\n E --> F[Cache Detection Result]\n```\n\n### Detection Signals\n\nThe auto-detection process analyzes multiple document signals:\n\n| Signal | Purpose | Indicates CMYK | Indicates RGB |\n|--------|---------|---------------|---------------|\n| `colorMode` | Primary color space | \"CMYK\" | \"RGB\" |\n| `rulerUnits` | Measurement system | mm, cm, inches | px |\n| `rasterEffectResolution` | Output resolution | Lower DPI | Higher DPI |\n| `colorProfile` | Color profile type | Print profiles | sRGB, display profiles |\n\nSource: [src/tools/session.ts:40-55](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/session.ts)\n\n### Detection Caching\n\nTo optimize performance, the auto-detection result is cached:\n\n```typescript\n// Cache key structure\nautoDetectCache = {\n documentId: string,\n colorMode: string,\n timestamp: number\n}\n```\n\nSource: [src/tools/session.ts:20-35](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/session.ts)\n\nThe cache is invalidated when:\n1. The document changes\n2. The color mode changes\n3. The artboard changes\n4. Manual override via `set_workflow` is called\n\n## Manual Override with set_workflow\n\nWhen auto-detection does not produce the desired behavior, use the `set_workflow` tool to explicitly set the coordinate system:\n\n```json\n{\n \"tool\": \"set_workflow\",\n \"parameters\": {\n \"mode\": \"web\"\n }\n}\n```\n\n### Available Workflow Modes\n\n| Mode | Coordinate System | Effect |\n|------|-------------------|--------|\n| `web` | `artboard-web` | Forces web-style coordinates |\n| `print` | `document` | Forces print-style coordinates |\n| `auto` | (auto-detected) | Resets to auto-detection |\n\nWhen `set_workflow` is called with a specific mode:\n1. The auto-detection cache is bypassed\n2. All subsequent coordinate operations use the specified system\n3. The `coordinateSystem` field reflects the manually set value\n\n## Coordinate Conversion\n\nThe `convert_coordinate` tool transforms points between coordinate systems within the active document.\n\n### Tool Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `point` | `{x: number, y: number}` | Yes | Point to convert |\n| `from` | `enum` | Yes | Source system: \"artboard\" or \"document\" |\n| `to` | `enum` | Yes | Destination system: \"artboard\" or \"document\" |\n\n### Conversion Behavior\n\n```typescript\n// Internal mapping to Illustrator constants\nconst fromMap = {\n \"artboard\": CoordinateSystem.ARTBOARDCOORDINATESYSTEM,\n \"document\": CoordinateSystem.DOCUMENTCOORDINATESYSTEM\n};\n\nconst toMap = {\n \"artboard\": CoordinateSystem.ARTBOARDCOORDINATESYSTEM,\n \"document\": CoordinateSystem.DOCUMENTCOORDINATESYSTEM\n};\n```\n\nSource: [src/tools/read/convert-coordinate.ts:1-10](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/convert-coordinate.ts)\n\n### Conversion Example\n\nConverting a point from artboard (web) coordinates to document (Illustrator native) coordinates:\n\n```json\n{\n \"tool\": \"convert_coordinate\",\n \"parameters\": {\n \"point\": { \"x\": 100, \"y\": 200 },\n \"from\": \"artboard\",\n \"to\": \"document\"\n }\n}\n```\n\nResponse includes the converted coordinates and system identifiers:\n\n```json\n{\n \"x\": 100,\n \"y\": 868, // Y inverted based on artboard height\n \"from\": \"artboard\",\n \"to\": \"document\"\n}\n```\n\n### Y-Axis Transformation\n\nThe conversion handles Y-axis inversion automatically:\n\n| From System | To System | Y Transformation |\n|-------------|-----------|------------------|\n| `artboard-web` | `document` | `y = artboardHeight - y` |\n| `document` | `artboard-web` | `y = artboardHeight - y` |\n\nThe artboard height is obtained from the active artboard rectangle to ensure accurate transformation.\n\n## Coordinate System in Tool Responses\n\nAll tool responses include a `coordinateSystem` field indicating which system is currently active:\n\n```json\n{\n \"success\": true,\n \"uuid\": \"abc123\",\n \"coordinateSystem\": \"artboard-web\"\n}\n```\n\nThis field helps AI assistants interpret position values correctly and choose appropriate coordinate systems for subsequent operations.\n\n## Workflow Detection Logic\n\nThe `detectWorkflow` function in session.ts determines the appropriate coordinate system based on document signals:\n\n```typescript\nexport function detectWorkflow(signals: DocumentSignals): WorkflowHint {\n const { colorMode, rulerUnits, rasterEffectResolution, colorProfile } = signals;\n\n const isCMYK = colorMode === 'CMYK';\n const isRGB = colorMode === 'RGB';\n const isPixelUnit = rulerUnits === 'px';\n const isPrintUnit = ['mm', 'cm'].includes(rulerUnits);\n \n // Decision logic based on signals\n // Returns WorkflowHint with detectedWorkflow and recommendedCoordinateSystem\n}\n```\n\nSource: [src/tools/session.ts:40-65](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/session.ts)\n\nThe detection considers:\n- **Primary signal**: Color mode (CMYK vs RGB)\n- **Supporting signals**: Ruler units, raster resolution, color profile\n- **Consistency check**: Verify all signals align\n\n## Best Practices\n\n### When to Use `document` System\n- Working with CMYK print documents\n- Creating content for physical output\n- Using print-specific measurements (mm, cm, inches)\n\n### When to Use `artboard-web` System\n- Working with RGB web documents\n- Creating content for digital display\n- Using pixel-based measurements\n\n### When to Override with `set_workflow`\n- Document auto-detection fails\n- Mixed workflow (e.g., RGB document for print preview)\n- Specific AI task requirements\n\n### Coordinate Conversion Strategy\n1. Determine the current coordinate system from tool response\n2. Use matching coordinates for the active system\n3. Convert when bridging between systems\n4. Cache conversion results for repeated operations\n\n---\n\n\n\n## Development Guide\n\n### Related Pages\n\nRelated topics: [Getting Started](#getting-started)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [tsconfig.json](https://github.com/ie3jp/illustrator-mcp-server/blob/main/tsconfig.json)\n- [package.json](https://github.com/ie3jp/illustrator-mcp-server/blob/main/package.json)\n- [src/tools/registry.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/registry.ts)\n- [src/prompts/registry.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/prompts/registry.ts)\n- [manifest.json](https://github.com/ie3jp/illustrator-mcp-server/blob/main/manifest.json)\n- [server.json](https://github.com/ie3jp/illustrator-mcp-server/blob/main/server.json)\n \n\n# Development Guide\n\nThis document serves as the comprehensive development guide for **illustrator-mcp-server**, a Model Context Protocol (MCP) server that enables AI assistants like Claude to read, manipulate, and export Adobe Illustrator design data. The server provides 26 tools for automation and inspection of Illustrator documents across macOS and Windows platforms.\n\n## Project Overview\n\nThe illustrator-mcp-server acts as a bridge between AI assistants and Adobe Illustrator's ExtendScript scripting engine. It leverages the MCP SDK to expose Illustrator functionality as discrete tools that AI can invoke through natural language commands.\n\n### Key Characteristics\n\n| Attribute | Value |\n|-----------|-------|\n| Platform | macOS, Windows |\n| Runtime | Node.js ≥20.0.0 |\n| License | MIT |\n| Repository | github.com/ie3jp/illustrator-mcp-server |\n| Current Version | 1.2.6 (server.json), 1.2.10 (manifest.json) |\n| Transport | stdio |\n\n## Project Structure\n\nThe repository follows a standard Node.js TypeScript project structure with MCP-specific components:\n\n```\nillustrator-mcp-server/\n├── src/\n│ ├── tools/\n│ │ └── registry.ts # Tool registration and definition\n│ └── prompts/\n│ └── registry.ts # Prompt templates for AI interaction\n├── dist/ # Compiled JavaScript output\n├── test/\n│ └── e2e/\n│ └── smoke-test.ts # End-to-end smoke tests\n├── manifest.json # MCP extension manifest\n├── server.json # MCP server configuration\n├── package.json # npm package configuration\n└── tsconfig.json # TypeScript configuration\n```\n\n## Development Environment Setup\n\n### Prerequisites\n\n| Requirement | Version | Purpose |\n|-------------|---------|---------|\n| Node.js | ≥20.0.0 | Server runtime |\n| npm | Latest | Package management |\n| Adobe Illustrator | Any supported version | Target application |\n| TypeScript | 6.0.2+ | Source compilation |\n\n### Installation\n\n```bash\ngit clone https://github.com/ie3jp/illustrator-mcp-server.git\ncd illustrator-mcp-server\nnpm install\n```\n\nThe `npm install` command installs both runtime dependencies and development dependencies as defined in package.json.\n\nSource: [package.json:1-50]()\n\n### Build Process\n\n```bash\nnpm run build\n```\n\nThe build command compiles TypeScript source files from `src/` to JavaScript in the `dist/` directory. The pre-publish lifecycle hook ensures the build completes before any publish operation:\n\n```json\n\"prepublishOnly\": \"npm run build\"\n```\n\nSource: [package.json:14]() [package.json:18]()\n\n## TypeScript Configuration\n\nThe project uses TypeScript for type safety and modern JavaScript features. The `tsconfig.json` defines compilation targets and module resolution:\n\n### Key Configuration Options\n\n| Option | Value | Purpose |\n|--------|-------|---------|\n| Target | ES2022+ | Modern JavaScript features |\n| Module | CommonJS or ESNext | Module system compatibility |\n| Strict | Enabled | Type safety enforcement |\n| OutDir | dist/ | Compilation output directory |\n| RootDir | src/ | Source root directory |\n\n## Tool Registration System\n\nThe MCP server exposes tools through a registration system defined in `src/tools/registry.ts`. Each tool corresponds to a specific Illustrator operation.\n\n### Tool Categories\n\nThe server provides 26 tools organized into functional categories:\n\n| Category | Count | Examples |\n|----------|-------|----------|\n| Document | 3 | `get_document_info`, `get_artboards`, `get_layers` |\n| Object | 11 | `create_rectangle`, `create_text_frame`, `modify_object` |\n| Text | 2 | `list_text_frames`, `get_text_frame_detail` |\n| Style | 4 | `create_gradient`, `create_symbol`, `get_effects` |\n| Asset | 3 | `get_images`, `get_symbols`, `get_selection` |\n| Style Guide | 1 | `extract_design_tokens`, `place_style_guide` |\n| Export | 2 | `export`, `export_pdf` |\n| Utility | 3 | `preflight_check`, `check_text_consistency`, `set_workflow` |\n| Edit | 1 | `undo` |\n\nSource: [manifest.json:15-30]()\n\n### Tool Registration Flow\n\n```mermaid\ngraph TD\n A[Start] --> B[Load tool definitions from registry.ts]\n B --> C[Parse ExtendScript handlers]\n C --> D[Register with MCP SDK]\n D --> E[Server starts listening for requests]\n E --> F[Tool invocation received]\n F --> G[Execute ExtendScript in Illustrator]\n G --> H[Return JSON response to AI]\n```\n\n### Adding New Tools\n\nTo add a new tool to the server:\n\n1. **Define the tool handler** in the appropriate source file within `src/`\n2. **Register the tool** in `src/tools/registry.ts` with:\n - Tool name and description\n - Parameter schema (JSON Schema format)\n - ExtendScript handler function\n3. **Update manifest.json** if exposing through MCP extension format\n\n## Prompt System\n\nThe prompt registry (`src/prompts/registry.ts`) contains templates that guide the AI's behavior when interacting with Illustrator through the MCP server. Prompts are particularly important for:\n\n- **Preflight workflows**: Structured validation steps for print-ready documents\n- **Design token extraction**: Systematic extraction of design system values\n- **Text consistency checking**: Pattern recognition for placeholder and inconsistency detection\n\n### Preflight Prompt Structure\n\nThe preflight skill uses a structured prompt approach:\n\n```mermaid\ngraph LR\n A[Start Preflight] --> B[Step 1: Asset Checks]\n B --> C[Step 2: Text Checks]\n C --> D[Step 3: Report Generation]\n D --> E[Critical Issues]\n D --> F[Warnings]\n D --> G[Info Items]\n```\n\nSource: [plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md:1-50]()\n\n## Testing\n\n### Unit Tests\n\n```bash\nnpm test\n```\n\nThe project uses Vitest for unit testing. Test files are located alongside source files with the `.test.ts` or `.spec.ts` extension.\n\nSource: [package.json:15]()\n\n### End-to-End Smoke Tests\n\n```bash\nnpx tsx test/e2e/smoke-test.ts\n```\n\nThe E2E smoke test requires Adobe Illustrator to be running. It performs:\n\n| Phase | Description |\n|-------|-------------|\n| Document creation | Creates RGB and CMYK test documents |\n| Object placement | Inserts test objects of various types |\n| Tool coverage | Tests all 26 registered tools |\n| Coordinate detection | Validates coordinate system auto-detection |\n| Cleanup | Automatically removes test documents |\n\n**Test Statistics:**\n- **182 test cases** across **10 phases**\n- Validates all tool registrations\n- Confirms coordinate system behavior for different document types\n\nSource: [README.md:1-50]()\n\n### Verification with MCP Inspector\n\n```bash\nnpx @modelcontextprotocol/inspector npx illustrator-mcp-server\n```\n\nThe MCP Inspector tool allows verification of the server configuration and tool registration without running a full AI client.\n\n## Build Outputs\n\n### Standard Build\n\n```bash\nnpm run build\n```\n\nOutputs compiled JavaScript to the `dist/` directory:\n- `dist/index.js` - Main server entry point\n- `dist/bundle.cjs` - CommonJS bundle for MCP packaging\n\n### MCP Extension Package\n\n```bash\nnpm run pack:mcpb\n```\n\nThis command:\n1. Builds the project\n2. Installs production dependencies only (`--omit=dev`)\n3. Packs the server using the Anthropic MCPB packager\n4. Reinstalls development dependencies\n\nOutput: `illustrator-mcp-server.mcpb` - Distributable extension package for Claude Desktop\n\nSource: [package.json:19]()\n\n## Release Process\n\n```bash\nnpm run release\n```\n\nThe release pipeline executes:\n1. `npm run build` - Compile TypeScript\n2. `npm test` - Run unit tests\n3. `git push` - Push to remote\n4. `git push --tags` - Publish version tags\n\nSource: [package.json:20]()\n\n## Server Configuration\n\n### MCP Server Manifest\n\nThe `server.json` defines the MCP server metadata:\n\n```json\n{\n \"name\": \"io.github.ie3jp/illustrator-mcp-server\",\n \"description\": \"Read, manipulate, and export Adobe Illustrator design data. 26 tools. macOS | Windows.\",\n \"version\": \"1.2.6\",\n \"packages\": [{\n \"identifier\": \"illustrator-mcp-server\",\n \"version\": \"1.2.6\",\n \"transport\": { \"type\": \"stdio\" }\n }]\n}\n```\n\nSource: [server.json:1-25]()\n\n### Claude Desktop Integration\n\nFor Claude Desktop integration, add to the MCP configuration:\n\n```json\n{\n \"mcpServers\": {\n \"illustrator\": {\n \"command\": \"npx\",\n \"args\": [\"illustrator-mcp-server\"]\n }\n }\n}\n```\n\n> **Note:** If using a Node.js version manager (nvm, mise, fnm), use the full path to npx:\n> ```json\n> \"command\": \"/full/path/to/npx\"\n> ```\n\n## Dependencies\n\n### Runtime Dependencies\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| @modelcontextprotocol/sdk | ^1.27.1 | MCP protocol implementation |\n| p-limit | ^7.3.0 | Concurrent operation limiting |\n\nSource: [package.json:33-35]()\n\n### Development Dependencies\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| typescript | ^6.0.2 | TypeScript compiler |\n| vitest | ^4.1.1 | Unit testing framework |\n| tsx | ^4.21.0 | TypeScript execution |\n| @types/node | ^25.5.0 | Node.js type definitions |\n\nSource: [package.json:37-41]()\n\n## ExtendScript Integration\n\nThe server communicates with Adobe Illustrator via ExtendScript (JavaScript for Adobe applications). Each tool maps to one or more ExtendScript commands that execute within Illustrator's scripting environment.\n\n### macOS Implementation\n\nOn macOS, the server uses AppleScript to invoke Illustrator:\n\n```applescript\ntell application \"Adobe Illustrator\"\n -- ExtendScript code executes here\nend tell\n```\n\n### Windows Implementation\n\nOn Windows, the server uses PowerShell COM automation:\n\n```powershell\n$illustrator = New-Object -ComObject Illustrator.Application\n```\n\nSource: [README.md:80-90]()\n\n## Known Development Constraints\n\n| Constraint | Impact | Workaround |\n|------------|--------|------------|\n| Windows testing | Not yet tested on real hardware | Use macOS for initial development |\n| Live effects | Parameters detectable but not readable | Manual verification required |\n| Color profiles | Limited support | Document-level color space awareness |\n| Font data | Limited access to font metadata | Use text extraction tools |\n\nSource: [README.md:95-100]()\n\n## Contributing\n\nWhen contributing to the project:\n\n1. **Follow TypeScript strict mode** - Enable all type checking options\n2. **Add unit tests** for new tools in the `test/` directory\n3. **Update manifest.json** if the tool count changes\n4. **Document in SKILL.md** for skills that require structured prompts\n5. **Test E2E smoke tests** before submitting pull requests\n\n## License\n\nThe project is licensed under the MIT License. See the [LICENSE](https://github.com/ie3jp/illustrator-mcp-server/blob/main/LICENSE) file for full terms.\n\n---\n\n---\n\n## Doramagic Pitfall Log\n\nProject: ie3jp/illustrator-mcp-server\n\nSummary: Found 8 potential pitfall items; 0 are high/blocking. Highest priority: configuration - 可能修改宿主 AI 配置.\n\n## 1. configuration · 可能修改宿主 AI 配置\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- User impact: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Guardrail action: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- Evidence: capability.host_targets | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | host_targets=mcp_host, claude, claude_code\n\n## 2. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | README/documentation is current enough for a first validation pass.\n\n## 3. runtime · 来源证据：編集可能な Illustrator アートワークのための SVG インポート動作の明確化と改善\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：編集可能な Illustrator アートワークのための SVG インポート動作の明確化と改善\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_c7b420ed6123436eb6d2b27f460dc2c8 | https://github.com/ie3jp/illustrator-mcp-server/issues/35 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | last_activity_observed missing\n\n## 5. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | no_demo; severity=medium\n\n## 6. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | no_demo; severity=medium\n\n## 7. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | issue_or_pr_quality=unknown\n\n## 8. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | release_recency=unknown\n\n\n",
"markdown_key": "illustrator-mcp-server",
"pages": "draft",
"source_refs": [
{
"evidence_id": "art_a1317fdd77604ec08836eb8f2de42a23",
"kind": "docs",
"supports_claim_ids": [
"claim_identity",
"claim_distribution",
"claim_capability"
],
"url": "https://github.com/ie3jp/illustrator-mcp-server#readme"
}
],
"summary": "DeepWiki/Human Wiki output with a Doramagic pitfall appendix.",
"title": "illustrator-mcp-server 说明书",
"toc": [
"https://github.com/ie3jp/illustrator-mcp-server Project Manual",
"Table of Contents",
"Project Overview",
"Introduction",
"Purpose and Scope",
"Architecture Overview",
"Core Feature Summary",
"Installation Methods",
"Doramagic 踩坑日志"
]
}
},
"quality_gate": {
"blocking_gaps": [],
"category_confidence": "medium",
"compile_status": "ready_for_review",
"five_assets_present": true,
"install_sandbox_verified": true,
"missing_evidence": [],
"next_action": "publish to Doramagic.ai project surfaces",
"prompt_preview_boundary_ok": true,
"publish_status": "publishable",
"quick_start_verified": true,
"repo_clone_verified": true,
"repo_commit": "26a8d7033a222747a23605b651c9a33ed76225df",
"repo_inspection_error": null,
"repo_inspection_files": [
"package.json",
"README.md",
"src/index.ts",
"src/server.ts",
"src/prompts/print-preflight-workflow.ts",
"src/prompts/quick-layout.ts",
"src/prompts/registry.ts",
"src/tools/registry.ts",
"src/tools/tool-executor.ts",
"src/tools/session.ts",
"src/utils/image-header.ts",
"src/executor/file-transport.ts",
"src/executor/jsx-runner.ts",
"src/tools/utility/set-workflow.ts",
"src/tools/utility/check-text-consistency.ts",
"src/tools/utility/preflight-check.ts",
"src/tools/utility/set-illustrator-version.ts",
"src/tools/read/get-layers.ts",
"src/tools/read/convert-coordinate.ts",
"src/tools/read/get-separation-info.ts",
"src/tools/read/get-images.ts",
"src/tools/read/get-path-items.ts",
"src/tools/read/get-document-info.ts",
"src/tools/read/get-artboards.ts",
"src/tools/read/get-selection.ts",
"src/tools/read/find-objects.ts",
"src/tools/read/extract-design-tokens.ts",
"src/tools/read/list-text-frames.ts",
"src/tools/read/get-text-frame-detail.ts",
"src/tools/read/get-overprint-info.ts",
"src/tools/read/get-guidelines.ts",
"src/tools/read/check-contrast.ts",
"src/tools/read/get-document-structure.ts",
"src/tools/read/list-fonts.ts",
"src/tools/read/get-effects.ts",
"src/tools/read/get-colors.ts",
"src/tools/read/get-symbols.ts",
"src/tools/read/get-groups.ts",
"src/tools/export/export-pdf.ts",
"src/tools/export/export.ts"
],
"repo_inspection_verified": true,
"review_reasons": [],
"tag_count_ok": true,
"unsupported_claims": []
},
"schema_version": "0.1",
"user_assets": {
"ai_context_pack": {
"asset_id": "ai_context_pack",
"filename": "AI_CONTEXT_PACK.md",
"markdown": "# illustrator-mcp-server - Doramagic AI Context Pack\n\n> 定位：安装前体验与判断资产。它帮助宿主 AI 有一个好的开始，但不代表已经安装、执行或验证目标项目。\n\n## 充分原则\n\n- **充分原则，不是压缩原则**：AI Context Pack 应该充分到让宿主 AI 在开工前理解项目价值、能力边界、使用入口、风险和证据来源；它可以分层组织，但不以最短摘要为目标。\n- **压缩策略**：只压缩噪声和重复内容，不压缩会影响判断和开工质量的上下文。\n\n## 给宿主 AI 的使用方式\n\n你正在读取 Doramagic 为 illustrator-mcp-server 编译的 AI Context Pack。请把它当作开工前上下文：帮助用户理解适合谁、能做什么、如何开始、哪些必须安装后验证、风险在哪里。不要声称你已经安装、运行或执行了目标项目。\n\n## Claim 消费规则\n\n- **事实来源**：Repo Evidence + Claim/Evidence Graph；Human Wiki 只提供显著性、术语和叙事结构。\n- **事实最低状态**：`supported`\n- `supported`：可以作为项目事实使用，但回答中必须引用 claim_id 和证据路径。\n- `weak`：只能作为低置信度线索，必须要求用户继续核实。\n- `inferred`：只能用于风险提示或待确认问题，不能包装成项目事实。\n- `unverified`：不得作为事实使用，应明确说证据不足。\n- `contradicted`：必须展示冲突来源，不得替用户强行选择一个版本。\n\n## 它最适合谁\n\n- **正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**：README 或插件配置提到多个宿主 AI。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **希望把专业流程带进宿主 AI 的用户**：仓库包含 Skill 文档。 证据：`plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md` Claim：`clm_0005` supported 0.86\n\n## 它能做什么\n\n- **AI Skill / Agent 指令资产库**（可做安装前预览）：项目包含可被宿主 AI 读取的 Skill 或 Agent 指令文件，可用于把专业流程带入 Claude、Codex、Cursor 等宿主。 证据：`plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md` Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**（需要安装后验证）：项目包含插件或 marketplace 配置，说明它面向一个或多个 AI 宿主的安装和分发。 证据：`plugins/illustrator-preflight/.claude-plugin/plugin.json` Claim：`clm_0002` supported 0.86\n- **命令行启动或安装流程**（需要安装后验证）：项目文档中存在可执行命令，真实使用需要在本地或宿主环境中运行这些命令。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n## 怎么开始\n\n- `claude mcp add illustrator-mcp -- npx illustrator-mcp-server` 证据：`README.md` Claim：`clm_0006` supported 0.86\n- `git clone https://github.com/ie3jp/illustrator-mcp-server.git` 证据：`README.md` Claim：`clm_0007` supported 0.86\n- `claude mcp add illustrator-mcp -- node /path/to/illustrator-mcp-server/dist/index.js` 证据：`README.md` Claim：`clm_0008` supported 0.86\n- `npx @modelcontextprotocol/inspector npx illustrator-mcp-server` 证据：`README.md` Claim：`clm_0009` supported 0.86\n- `npx tsx test/e2e/smoke-test.ts` 证据：`README.md` Claim：`clm_0010` supported 0.86\n\n## 继续前判断卡\n\n- **当前建议**：先做权限沙盒试用\n- **为什么**：项目存在安装命令、宿主配置或本地写入线索，不建议直接进入主力环境，应先在隔离环境试装。\n\n### 30 秒判断\n\n- **现在怎么做**：先做权限沙盒试用\n- **最小安全下一步**：先跑 Prompt Preview；若仍要安装，只在隔离环境试装\n- **先别相信**：工具权限边界不能在安装前相信。\n- **继续会触碰**：命令执行、宿主 AI 配置、本地环境或项目文件\n\n### 现在可以相信\n\n- **适合人群线索：正在使用 Claude/Codex/Cursor/Gemini 等宿主 AI 的开发者**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`README.md` Claim：`clm_0004` supported 0.86\n- **适合人群线索：希望把专业流程带进宿主 AI 的用户**（supported）：有 supported claim 或项目证据支撑，但仍不等于真实安装效果。 证据：`plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md` Claim：`clm_0005` supported 0.86\n- **能力存在：AI Skill / Agent 指令资产库**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md` Claim：`clm_0001` supported 0.86\n- **能力存在：多宿主安装与分发**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`plugins/illustrator-preflight/.claude-plugin/plugin.json` Claim：`clm_0002` supported 0.86\n- **能力存在：命令行启动或安装流程**（supported）：可以相信项目包含这类能力线索；是否适合你的具体任务仍要试用或安装后验证。 证据：`README.md` Claim：`clm_0003` supported 0.86\n- **存在 Quick Start / 安装命令线索**（supported）：可以相信项目文档出现过启动或安装入口；不要因此直接在主力环境运行。 证据：`README.md` Claim：`clm_0006` supported 0.86\n\n### 现在还不能相信\n\n- **工具权限边界不能在安装前相信。**（unverified）：MCP/tool 类项目通常会触碰文件、网络、浏览器或外部 API，必须真实检查权限和日志。\n- **真实输出质量不能在安装前相信。**（unverified）：Prompt Preview 只能展示引导方式，不能证明真实项目中的结果质量。\n- **宿主 AI 版本兼容性不能在安装前相信。**（unverified）：Claude、Cursor、Codex、Gemini 等宿主加载规则和版本差异必须在真实环境验证。\n- **不会污染现有宿主 AI 行为，不能直接相信。**（inferred）：Skill、plugin、AGENTS/CLAUDE/GEMINI 指令可能改变宿主 AI 的默认行为。 证据：`plugins/illustrator-preflight/.claude-plugin/plugin.json`, `plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md`\n- **可安全回滚不能默认相信。**（unverified）：除非项目明确提供卸载和恢复说明，否则必须先在隔离环境验证。\n- **真实安装后是否与用户当前宿主 AI 版本兼容？**（unverified）：兼容性只能通过实际宿主环境验证。 证据：`plugins/illustrator-preflight/.claude-plugin/plugin.json`\n- **项目输出质量是否满足用户具体任务？**（unverified）：安装前预览只能展示流程和边界，不能替代真实评测。\n- **安装命令是否需要网络、权限或全局写入？**（unverified）：这影响企业环境和个人环境的安装风险。 证据：`README.md`\n\n### 继续会触碰什么\n\n- **命令执行**：包管理器、网络下载、本地插件目录、项目配置或用户主目录。 原因：运行第一条命令就可能产生环境改动；必须先判断是否值得跑。 证据：`README.md`\n- **宿主 AI 配置**：Claude/Codex/Cursor/Gemini/OpenCode 等宿主的 plugin、Skill 或规则加载配置。 原因：宿主配置会改变 AI 后续工作方式，可能和用户已有规则冲突。 证据：`plugins/illustrator-preflight/.claude-plugin/plugin.json`, `plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md`\n- **本地环境或项目文件**：安装结果、插件缓存、项目配置或本地依赖目录。 原因：安装前无法证明写入范围和回滚方式，需要隔离验证。 证据：`README.md`, `plugins/illustrator-preflight/.claude-plugin/plugin.json`\n- **宿主 AI 上下文**：AI Context Pack、Prompt Preview、Skill 路由、风险规则和项目事实。 原因：导入上下文会影响宿主 AI 后续判断，必须避免把未验证项包装成事实。\n\n### 最小安全下一步\n\n- **先跑 Prompt Preview**：用安装前交互式试用判断工作方式是否匹配，不需要授权或改环境。（适用：任何项目都适用，尤其是输出质量未知时。）\n- **只在隔离目录或测试账号试装**：避免安装命令污染主力宿主 AI、真实项目或用户主目录。（适用：存在命令执行、插件配置或本地写入线索时。）\n- **先备份宿主 AI 配置**：Skill、plugin、规则文件可能改变 Claude/Cursor/Codex 的默认行为。（适用：存在插件 manifest、Skill 或宿主规则入口时。）\n- **安装后只验证一个最小任务**：先验证加载、兼容、输出质量和回滚，再决定是否深用。（适用：准备从试用进入真实工作流时。）\n\n### 退出方式\n\n- **保留安装前状态**：记录原始宿主配置和项目状态，后续才能判断是否可恢复。\n- **准备移除宿主 plugin / Skill / 规则入口**：如果试装后行为异常，可以把宿主 AI 恢复到试装前状态。\n- **记录安装命令和写入路径**：没有明确卸载说明时，至少要知道哪些目录或配置需要手动清理。\n- **如果没有回滚路径，不进入主力环境**：不可回滚是继续前阻断项，不应靠信任或运气继续。\n\n## 哪些只能预览\n\n- 解释项目适合谁和能做什么\n- 基于项目文档演示典型对话流程\n- 帮助用户判断是否值得安装或继续研究\n\n## 哪些必须安装后验证\n\n- 真实安装 Skill、插件或 CLI\n- 执行脚本、修改本地文件或访问外部服务\n- 验证真实输出质量、性能和兼容性\n\n## 边界与风险判断卡\n\n- **把安装前预览误认为真实运行**：用户可能高估项目已经完成的配置、权限和兼容性验证。 处理方式：明确区分 prompt_preview_can_do 与 runtime_required。 Claim：`clm_0011` inferred 0.45\n- **宿主 AI 插件或 Skill 规则冲突**：新规则可能改变用户现有宿主 AI 的工作方式。 处理方式：安装前先检查插件 manifest 和 Skill 文件，必要时隔离测试。 证据：`plugins/illustrator-preflight/.claude-plugin/plugin.json` Claim：`clm_0012` supported 0.86\n- **命令执行会修改本地环境**：安装命令可能写入用户主目录、宿主插件目录或项目配置。 处理方式：先在隔离环境或测试账号中运行。 证据：`README.md` Claim：`clm_0013` supported 0.86\n- **待确认**：真实安装后是否与用户当前宿主 AI 版本兼容？。原因：兼容性只能通过实际宿主环境验证。\n- **待确认**：项目输出质量是否满足用户具体任务？。原因：安装前预览只能展示流程和边界，不能替代真实评测。\n- **待确认**：安装命令是否需要网络、权限或全局写入？。原因：这影响企业环境和个人环境的安装风险。\n\n## 开工前工作上下文\n\n### 加载顺序\n\n- 先读取 how_to_use.host_ai_instruction，建立安装前判断资产的边界。\n- 读取 claim_graph_summary，确认事实来自 Claim/Evidence Graph，而不是 Human Wiki 叙事。\n- 再读取 intended_users、capabilities 和 quick_start_candidates，判断用户是否匹配。\n- 需要执行具体任务时，优先查 role_skill_index，再查 evidence_index。\n- 遇到真实安装、文件修改、网络访问、性能或兼容性问题时，转入 risk_card 和 boundaries.runtime_required。\n\n### 任务路由\n\n- **AI Skill / Agent 指令资产库**：先基于 role_skill_index / evidence_index 帮用户挑选可用角色、Skill 或工作流。 边界：可做安装前 Prompt 体验。 证据：`plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md` Claim：`clm_0001` supported 0.86\n- **多宿主安装与分发**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`plugins/illustrator-preflight/.claude-plugin/plugin.json` Claim：`clm_0002` supported 0.86\n- **命令行启动或安装流程**：先说明这是安装后验证能力，再给出安装前检查清单。 边界：必须真实安装或运行后验证。 证据：`README.md` Claim：`clm_0003` supported 0.86\n\n### 上下文规模\n\n- 文件总数：132\n- 重要文件覆盖：38/132\n- 证据索引条目：38\n- 角色 / Skill 条目：1\n\n### 证据不足时的处理\n\n- **missing_evidence**：说明证据不足，要求用户提供目标文件、README 段落或安装后验证记录；不要补全事实。\n- **out_of_scope_request**：说明该任务超出当前 AI Context Pack 证据范围，并建议用户先查看 Human Manual 或真实安装后验证。\n- **runtime_request**：给出安装前检查清单和命令来源，但不要替用户执行命令或声称已执行。\n- **source_conflict**：同时展示冲突来源，标记为待核实，不要强行选择一个版本。\n\n## Prompt Recipes\n\n### 适配判断\n\n- 目标：判断这个项目是否适合用户当前任务。\n- 预期输出：适配结论、关键理由、证据引用、安装前可预览内容、必须安装后验证内容、下一步建议。\n\n```text\n请基于 illustrator-mcp-server 的 AI Context Pack，先问我 3 个必要问题，然后判断它是否适合我的任务。回答必须包含：适合谁、能做什么、不能做什么、是否值得安装、证据来自哪里。所有项目事实必须引用 evidence_refs、source_paths 或 claim_id。\n```\n\n### 安装前体验\n\n- 目标：让用户在安装前感受核心工作流，同时避免把预览包装成真实能力或营销承诺。\n- 预期输出：一段带边界标签的体验剧本、安装后验证清单和谨慎建议；不含真实运行承诺或强营销表述。\n\n```text\n请把 illustrator-mcp-server 当作安装前体验资产，而不是已安装工具或真实运行环境。\n\n请严格输出四段：\n1. 先问我 3 个必要问题。\n2. 给出一段“体验剧本”：用 [安装前可预览]、[必须安装后验证]、[证据不足] 三种标签展示它可能如何引导工作流。\n3. 给出安装后验证清单：列出哪些能力只有真实安装、真实宿主加载、真实项目运行后才能确认。\n4. 给出谨慎建议：只能说“值得继续研究/试装”“先补充信息后再判断”或“不建议继续”，不得替项目背书。\n\n硬性边界：\n- 不要声称已经安装、运行、执行测试、修改文件或产生真实结果。\n- 不要写“自动适配”“确保通过”“完美适配”“强烈建议安装”等承诺性表达。\n- 如果描述安装后的工作方式，必须使用“如果安装成功且宿主正确加载 Skill，它可能会……”这种条件句。\n- 体验剧本只能写成“示例台词/假设流程”：使用“可能会询问/可能会建议/可能会展示”，不要写“已写入、已生成、已通过、正在运行、正在生成”。\n- Prompt Preview 不负责给安装命令；如用户准备试装，只能提示先阅读 Quick Start 和 Risk Card，并在隔离环境验证。\n- 所有项目事实必须来自 supported claim、evidence_refs 或 source_paths；inferred/unverified 只能作风险或待确认项。\n\n```\n\n### 角色 / Skill 选择\n\n- 目标：从项目里的角色或 Skill 中挑选最匹配的资产。\n- 预期输出：候选角色或 Skill 列表，每项包含适用场景、证据路径、风险边界和是否需要安装后验证。\n\n```text\n请读取 role_skill_index，根据我的目标任务推荐 3-5 个最相关的角色或 Skill。每个推荐都要说明适用场景、可能输出、风险边界和 evidence_refs。\n```\n\n### 风险预检\n\n- 目标：安装或引入前识别环境、权限、规则冲突和质量风险。\n- 预期输出：环境、权限、依赖、许可、宿主冲突、质量风险和未知项的检查清单。\n\n```text\n请基于 risk_card、boundaries 和 quick_start_candidates，给我一份安装前风险预检清单。不要替我执行命令，只说明我应该检查什么、为什么检查、失败会有什么影响。\n```\n\n### 宿主 AI 开工指令\n\n- 目标：把项目上下文转成一次对话开始前的宿主 AI 指令。\n- 预期输出：一段边界明确、证据引用明确、适合复制给宿主 AI 的开工前指令。\n\n```text\n请基于 illustrator-mcp-server 的 AI Context Pack，生成一段我可以粘贴给宿主 AI 的开工前指令。这段指令必须遵守 not_runtime=true，不能声称项目已经安装、运行或产生真实结果。\n```\n\n\n## 角色 / Skill 索引\n\n- 共索引 1 个角色 / Skill / 项目文档条目。\n\n- **illustrator-preflight**（skill）：Run comprehensive pre-press preflight checks on Adobe Illustrator documents using illustrator-mcp tools. Detects print-critical issues RGB in CMYK, broken links, low-res images, white overprint, text not outlined , text consistency problems dummy text, notation variations , and PDF/X compliance. Use when user asks to check a document before printing, submission, or handoff — or mentions \"preflight\", \"pre-press check… 激活提示：当用户任务与“illustrator-preflight”描述的流程高度相关时，先用它做安装前体验，再决定是否安装。 证据：`plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md`\n\n## 证据索引\n\n- 共索引 38 条证据。\n\n- **Illustrator MCP Server**（documentation）：🇺🇸 English 🇯🇵 日本語 README.ja.md 🇨🇳 简体中文 README.zh-CN.md 🇰🇷 한국어 README.ko.md 🇪🇸 Español README.es.md 🇩🇪 Deutsch README.de.md 🇫🇷 Français README.fr.md 🇵🇹 Português BR README.pt-BR.md 证据：`README.md`\n- **Windows Diagnostic Tools**（documentation）：Windows 上で Illustrator MCP Server の COM 連携をテストする診断ツール。 证据：`test/windows-diag/README.md`\n- **Package**（package_manifest）：{ \"name\": \"illustrator-mcp-server\", \"version\": \"1.4.0\", \"mcpName\": \"io.github.ie3jp/illustrator-mcp-server\", \"description\": \"MCP server for reading, manipulating, and exporting Adobe Illustrator design data\", \"type\": \"module\", \"main\": \"dist/index.js\", \"bin\": { \"illustrator-mcp-server\": \"dist/index.js\" }, \"files\": \"dist/ / \" , \"scripts\": { \"build\": \"tsc && node -e \\\"require 'fs' .cpSync 'src/jsx','dist/jsx',{recursive:true} \\\" && node -e \\\"require 'esbuild' .buildSync {entryPoints: 'src/index.ts' ,bundle:true,platform:'node',format:'cjs',outfile:'dist/bundle.cjs',define:{'import.meta.url':' importMetaUrl'},banner:{js:'const importMetaUrl = require \\\\\\\"url\\\\\\\" .pathToFileURL filename .href;'}… 证据：`package.json`\n- **Illustrator Preflight Check**（skill_instruction）：Comprehensive pre-press quality check workflow for Illustrator documents. 证据：`plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md`\n- **Plugin**（structured_config）：{ \"name\": \"illustrator-preflight\", \"version\": \"1.0.0\", \"description\": \"Pre-press preflight checks for Adobe Illustrator documents via illustrator-mcp tools. Detects print-critical issues, text consistency problems, and PDF/X compliance.\", \"author\": { \"name\": \"ie3jp\", \"url\": \"https://github.com/ie3jp\" }, \"repository\": \"https://github.com/ie3jp/illustrator-mcp-server\", \"license\": \"MIT\", \"keywords\": \"illustrator\", \"preflight\", \"print\", \"prepress\", \"pdf\", \"mcp\" } 证据：`plugins/illustrator-preflight/.claude-plugin/plugin.json`\n- **License**（source_file）：Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files the \"Software\" , to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: 证据：`LICENSE`\n- **Illustrator MCP Server**（documentation）：🇺🇸 English README.md 🇯🇵 日本語 README.ja.md 🇨🇳 简体中文 README.zh-CN.md 🇰🇷 한국어 README.ko.md 🇪🇸 Español README.es.md 🇩🇪 Deutsch 🇫🇷 Français README.fr.md 🇵🇹 Português BR README.pt-BR.md 证据：`README.de.md`\n- **Illustrator MCP Server**（documentation）：🇺🇸 English README.md 🇯🇵 日本語 README.ja.md 🇨🇳 简体中文 README.zh-CN.md 🇰🇷 한국어 README.ko.md 🇪🇸 Español 🇩🇪 Deutsch README.de.md 🇫🇷 Français README.fr.md 🇵🇹 Português BR README.pt-BR.md 证据：`README.es.md`\n- **Illustrator MCP Server**（documentation）：🇺🇸 English README.md 🇯🇵 日本語 README.ja.md 🇨🇳 简体中文 README.zh-CN.md 🇰🇷 한국어 README.ko.md 🇪🇸 Español README.es.md 🇩🇪 Deutsch README.de.md 🇫🇷 Français 🇵🇹 Português BR README.pt-BR.md 证据：`README.fr.md`\n- **Illustrator MCP Server**（documentation）：🇺🇸 English README.md 🇯🇵 日本語 🇨🇳 简体中文 README.zh-CN.md 🇰🇷 한국어 README.ko.md 🇪🇸 Español README.es.md 🇩🇪 Deutsch README.de.md 🇫🇷 Français README.fr.md 🇵🇹 Português BR README.pt-BR.md 证据：`README.ja.md`\n- **Illustrator MCP Server**（documentation）：🇺🇸 English README.md 🇯🇵 日本語 README.ja.md 🇨🇳 简体中文 README.zh-CN.md 🇰🇷 한국어 🇪🇸 Español README.es.md 🇩🇪 Deutsch README.de.md 🇫🇷 Français README.fr.md 🇵🇹 Português BR README.pt-BR.md 证据：`README.ko.md`\n- **Illustrator MCP Server**（documentation）：🇺🇸 English README.md 🇯🇵 日本語 README.ja.md 🇨🇳 简体中文 README.zh-CN.md 🇰🇷 한국어 README.ko.md 🇪🇸 Español README.es.md 🇩🇪 Deutsch README.de.md 🇫🇷 Français README.fr.md 🇵🇹 Português BR 证据：`README.pt-BR.md`\n- **Illustrator MCP Server**（documentation）：🇺🇸 English README.md 🇯🇵 日本語 README.ja.md 🇨🇳 简体中文 🇰🇷 한국어 README.ko.md 🇪🇸 Español README.es.md 🇩🇪 Deutsch README.de.md 🇫🇷 Français README.fr.md 🇵🇹 Português BR README.pt-BR.md 证据：`README.zh-CN.md`\n- **What's New / 新機能**（documentation）：- Auto-generated export paths — When output path is omitted in export , export pdf , or save document save as , the file is saved to the document's directory or ~/Desktop for unsaved documents with collision-safe numbering. - 書き出しパス自動生成 — export 、 export pdf 、 save document save as で output path を省略すると、ドキュメントと同じディレクトリ（未保存時は~/Desktop）に連番付きで自動保存。 证据：`RELEASE_NOTES.md`\n- **Security Policy**（documentation）：Version Supported --------- -------------------- 1.x :white check mark: 证据：`SECURITY.md`\n- **Preflight Rules Reference**（documentation）：Severity levels and judgment criteria for each check category. 证据：`plugins/illustrator-preflight/skills/illustrator-preflight/references/preflight-rules.md`\n- **Design Tokens**（structured_config）：{ \"color\": { \"primary\": \" FFFFFF\", \"secondary\": \" 324B55\", \"tertiary\": \" 000000\", \"color-4\": \" 461724\", \"color-5\": \" 505023\", \"color-6\": \" 6E5028\", \"color-7\": \" 464646\", \"color-8\": \" 785660\", \"color-9\": \" 50646E\", \"color-10\": \" C3A069\", \"color-11\": \" 787855\", \"color-12\": \" 8C8C8C\" }, \"typography\": { \"heading\": { \"family\": \"AkzidGrtskNext-Med\", \"size\": \"20pt\", \"weight\": \"Medium\" }, \"body\": { \"family\": \"AkzidGrtskNext-Med\", \"size\": \"36pt\", \"weight\": \"Medium\" } }, \"spacing\": \"19pt\", \"22pt\", \"23pt\", \"26pt\", \"46pt\", \"53pt\" } 证据：`demo/design-tokens.json`\n- **Glama**（structured_config）：{ \"$schema\": \"https://glama.ai/mcp/schemas/server.json\", \"maintainers\": \"cyocun\" } 证据：`glama.json`\n- **Manifest**（structured_config）：{ \"manifest version\": \"0.3\", \"name\": \"Illustrator MCP\", \"version\": \"1.2.10\", \"description\": \"MCP server for reading, manipulating, and exporting Adobe Illustrator design data\", \"author\": { \"name\": \"cyocun IE3 \", \"email\": \"cyocun@gmail.com\" }, \"icon\": \"icon.png\", \"support\": \"https://github.com/ie3jp/illustrator-mcp-server\", \"server\": { \"type\": \"node\", \"entry point\": \"dist/bundle.cjs\", \"mcp config\": { \"command\": \"node\", \"args\": \"${ dirname}/dist/bundle.cjs\" , \"env\": {} } }, \"compatibility\": { \"platforms\": \"darwin\", \"win32\" , \"runtimes\": { \"node\": \" =20.0.0\" } }, \"tools\": { \"name\": \"get document info\", \"description\": \"Get document metadata\" }, { \"name\": \"get artboards\", \"description\": \"Get all… 证据：`manifest.json`\n- **Server**（structured_config）：{ \"$schema\": \"https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json\", \"name\": \"io.github.ie3jp/illustrator-mcp-server\", \"description\": \"Read, manipulate, and export Adobe Illustrator design data. 26 tools. macOS Windows.\", \"repository\": { \"url\": \"https://github.com/ie3jp/illustrator-mcp-server\", \"source\": \"github\" }, \"version\": \"1.2.6\", \"packages\": { \"registryType\": \"npm\", \"identifier\": \"illustrator-mcp-server\", \"version\": \"1.2.6\", \"transport\": { \"type\": \"stdio\" } } } 证据：`server.json`\n- **Tsconfig**（structured_config）：{ \"compilerOptions\": { \"target\": \"ES2022\", \"module\": \"NodeNext\", \"moduleResolution\": \"NodeNext\", \"outDir\": \"dist\", \"rootDir\": \"src\", \"strict\": true, \"esModuleInterop\": true, \"skipLibCheck\": true, \"types\": \"node\" , \"forceConsistentCasingInFileNames\": true, \"resolveJsonModule\": true, \"declaration\": true, \"declarationMap\": true, \"sourceMap\": true }, \"include\": \"src/ / \" , \"exclude\": \"node modules\", \"dist\", \"test\" } 证据：`tsconfig.json`\n- **Dependabot**（source_file）：version: 2 updates: - package-ecosystem: \"npm\" directory: \"/\" schedule: interval: \"weekly\" open-pull-requests-limit: 10 groups: dev-dependencies: dependency-type: \"development\" production-dependencies: dependency-type: \"production\" 证据：`.github/dependabot.yml`\n- **.gitignore**（source_file）：node modules/ dist/ .tsbuildinfo .env .env. .DS Store .mcpregistry .mcpb docs/ !docs/images/ docs/images/ .ai CLAUDE.md .skill 证据：`.gitignore`\n- **Source dist/ に含まれる**（source_file）：Dev tooling .github/ demo/ docs/ plugins/ 证据：`.mcpbignore`\n- **!/bin/bash**（source_file）：!/bin/bash Start interval screen capture 1 screenshot per second set -euo pipefail 证据：`demo/capture_start.sh`\n- **!/bin/bash**（source_file）：!/bin/bash Stop interval capture. Frames are kept in /tmp/illustrator-mcp-capture/. set -euo pipefail 证据：`demo/capture_stop.sh`\n- **!/bin/bash**（source_file）：!/bin/bash Convert captured frames to timelapse video Usage: capture to video.sh output.mov fps fps: playback frames per second default: 10 = 10x speed set -euo pipefail 证据：`demo/capture_to_video.sh`\n- **Datasets**（source_file）：Tech Conference 2026 The Future of AI & Design April 15, 2026 Tokyo International Forum Register Now — Free Admission Design Summit Tokyo Where Creativity Meets Technology June 8–9, 2026 Shibuya Hikarie Hall Early Bird Tickets Available Startup Pitch Night 10 Startups. 5 Minutes Each. September 20, 2026 Roppongi Hills Arena Apply to Pitch — Deadline Aug 31 证据：`demo/datasets.xml`\n- **Design Tokens**（source_file）：:root { --color-primary: FFFFFF; --color-secondary: 333333; --color-tertiary: 808080; --color-color-4: 324B55; --color-color-5: FFF0CD; --color-color-6: DCE1CD; --color-color-7: AFB9CD; --color-color-8: BEAAC3; --color-color-9: 8C8C8C; --color-color-10: 787855; --color-color-11: C3A069; --color-color-12: 50646E; 证据：`demo/design-tokens.css`\n- **Events**（source_file）：EventTitle,Subtitle,Date,Venue,CTA Tech Conference 2026,The Future of AI & Design,April 15 2026,Tokyo International Forum,Register Now — Free Admission Design Summit Tokyo,Where Creativity Meets Technology,June 8–9 2026,Shibuya Hikarie Hall,Early Bird Tickets Available Startup Pitch Night,10 Startups. 5 Minutes Each.,September 20 2026,Roppongi Hills Arena,Apply to Pitch — Deadline Aug 31 证据：`demo/events.csv`\n- **Exported**（source_file）：Tech Conference 2026 The Future of AI & Design April 15, 2026 Tokyo International Forum Register Now — Free Admission Design Summit Tokyo Where Creativity Meets Technology June 8–9, 2026 Shibuya Hikarie Hall Early Bird Tickets Available Startup Pitch Night 10 Startups. 5 Minutes Each. September 20, 2026 Roppongi Hills Arena Apply to Pitch — Deadline Aug 31 证据：`demo/exported.xml`\n- **!/bin/bash**（source_file）：!/bin/bash Demo: Pattern 1 - Business Card \"KUMO Studio\" Arranges windows and types prompt into Claude Desktop. Start capture start.sh separately before running this. set -euo pipefail 证据：`demo/record_01_business_card.sh`\n- **!/bin/bash**（source_file）：!/bin/bash Demo: Pattern 2 - A3 Poster \"SYNC TOKYO 2026\" Arranges windows and types prompt into Claude Desktop. Start capture start.sh separately before running this. set -euo pipefail 证据：`demo/record_02_poster.sh`\n- **!/bin/bash**（source_file）：!/bin/bash Demo: Pattern 3 - Logo Concepts \"Slow Drip\" Arranges windows and types prompt into Claude Desktop. Start capture start.sh separately before running this. set -euo pipefail 证据：`demo/record_03_logo.sh`\n- **!/usr/bin/env node**（source_file）：!/usr/bin/env node import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'; import { createServer } from './server.js'; import { ensureTmpDir, cleanupTmpDirSync } from './executor/file-transport.js'; import { waitForPendingExecutions } from './executor/jsx-runner.js'; 证据：`src/index.ts`\n- **Server**（source_file）：import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'; import { registerAllTools } from './tools/registry.js'; import { registerAllPrompts } from './prompts/registry.js'; 证据：`src/server.ts`\n- **Integration Check**（source_file）：/ Integration check script — requires a running Illustrator with an open document. Run: npx tsx test/integration-check.mts / import { executeJsx } from '../dist/executor/jsx-runner.js'; import { ensureTmpDir } from '../dist/executor/file-transport.js'; import { readImageDimensions } from '../dist/utils/image-header.js'; import as fs from 'fs'; import as path from 'path'; import as os from 'os'; 证据：`test/integration-check.mts`\n- **Vitest.Config**（source_file）：import { defineConfig } from 'vitest/config'; 证据：`vitest.config.ts`\n\n## 宿主 AI 必须遵守的规则\n\n- **把本资产当作开工前上下文，而不是运行环境。**：AI Context Pack 只包含证据化项目理解，不包含目标项目的可执行状态。 证据：`README.md`, `test/windows-diag/README.md`, `package.json`\n- **回答用户时区分可预览内容与必须安装后才能验证的内容。**：安装前体验的消费者价值来自降低误装和误判，而不是伪装成真实运行。 证据：`README.md`, `test/windows-diag/README.md`, `package.json`\n\n## 用户开工前应该回答的问题\n\n- 你准备在哪个宿主 AI 或本地环境中使用它？\n- 你只是想先体验工作流，还是准备真实安装？\n- 你最在意的是安装成本、输出质量、还是和现有规则的冲突？\n\n## 验收标准\n\n- 所有能力声明都能回指到 evidence_refs 中的文件路径。\n- AI_CONTEXT_PACK.md 没有把预览包装成真实运行。\n- 用户能在 3 分钟内看懂适合谁、能做什么、如何开始和风险边界。\n\n---\n\n## Doramagic Context Augmentation\n\nThe following material strengthens the Repomix/AI Context Pack body. Human Manual is only a reading skeleton; pitfall logs become hard operating constraints for the host AI.\n\n## Human Manual Skeleton\n\nUsage rule: this is only a reading path and salience signal, not factual authority. Concrete facts must still come from repo evidence / Claim Graph.\n\nHard rules for the host AI:\n- Do not treat page titles, order, summaries, or importance as project facts.\n- When explaining the Human Manual skeleton, state that it is only a reading path / salience signal.\n- Capability, installation, compatibility, runtime status, and risk judgments must cite repo evidence, source paths, or Claim Graph.\n\n- **Project Overview**：importance `high`\n - source_paths: README.md, package.json, manifest.json\n- **Getting Started**：importance `high`\n - source_paths: README.md, CLAUDE.md\n- **System Architecture**：importance `high`\n - source_paths: src/server.ts, src/index.ts, src/tools/registry.ts\n- **Execution Flow**：importance `high`\n - source_paths: src/executor/file-transport.ts, src/executor/jsx-runner.ts, src/tools/tool-executor.ts, src/jsx/helpers/common.jsx\n- **Read Tools**：importance `high`\n - source_paths: src/tools/read/get-document-info.ts, src/tools/read/get-document-structure.ts, src/tools/read/list-text-frames.ts, src/tools/read/get-text-frame-detail.ts, src/tools/read/get-colors.ts\n- **Modify Tools**：importance `high`\n - source_paths: src/tools/modify/create-document.ts, src/tools/modify/create-rectangle.ts, src/tools/modify/create-text-frame.ts, src/tools/modify/manage-layers.ts, src/tools/modify/align-objects.ts\n- **Export Tools**：importance `high`\n - source_paths: src/tools/export/export.ts, src/tools/export/export-pdf.ts\n- **Utility Tools**：importance `medium`\n - source_paths: src/tools/utility/preflight-check.ts, src/tools/utility/check-text-consistency.ts, src/tools/utility/set-workflow.ts, src/tools/utility/set-illustrator-version.ts\n\n## Repo Inspection Evidence\n\n- repo_clone_verified: true\n- repo_inspection_verified: true\n- repo_commit: `26a8d7033a222747a23605b651c9a33ed76225df`\n- inspected_files: `package.json`, `README.md`, `src/index.ts`, `src/server.ts`, `src/prompts/print-preflight-workflow.ts`, `src/prompts/quick-layout.ts`, `src/prompts/registry.ts`, `src/tools/registry.ts`, `src/tools/tool-executor.ts`, `src/tools/session.ts`, `src/utils/image-header.ts`, `src/executor/file-transport.ts`, `src/executor/jsx-runner.ts`, `src/tools/utility/set-workflow.ts`, `src/tools/utility/check-text-consistency.ts`, `src/tools/utility/preflight-check.ts`, `src/tools/utility/set-illustrator-version.ts`, `src/tools/read/get-layers.ts`, `src/tools/read/convert-coordinate.ts`, `src/tools/read/get-separation-info.ts`\n\nHard rules for the host AI:\n- Without repo_clone_verified=true, do not claim the source code has been read.\n- Without repo_inspection_verified=true, do not turn README/docs/package observations into facts.\n- Without quick_start_verified=true, do not claim the Quick Start has been successfully run.\n\n## Doramagic Pitfall Constraints\n\nThese rules come from Doramagic discovery, validation, or compilation pitfalls. The host AI must treat them as operating constraints, not general background notes.\n\n### Constraint 1: 可能修改宿主 AI 配置\n\n- Trigger: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- Host AI rule: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Why it matters: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Evidence: capability.host_targets | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | host_targets=mcp_host, claude, claude_code\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 2: 能力判断依赖假设\n\n- Trigger: README/documentation is current enough for a first validation pass.\n- Host AI rule: 将假设转成下游验证清单。\n- Why it matters: 假设不成立时，用户拿不到承诺的能力。\n- Evidence: capability.assumptions | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | README/documentation is current enough for a first validation pass.\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 3: 来源证据：編集可能な Illustrator アートワークのための SVG インポート動作の明確化と改善\n\n- Trigger: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：編集可能な Illustrator アートワークのための SVG インポート動作の明確化と改善\n- Host AI rule: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Why it matters: 可能增加新用户试用和生产接入成本。\n- Evidence: community_evidence:github | cevd_c7b420ed6123436eb6d2b27f460dc2c8 | https://github.com/ie3jp/illustrator-mcp-server/issues/35 | 来源类型 github_issue 暴露的待验证使用条件。\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 4: 维护活跃度未知\n\n- Trigger: 未记录 last_activity_observed。\n- Host AI rule: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Why it matters: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Evidence: evidence.maintainer_signals | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | last_activity_observed missing\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 5: 下游验证发现风险项\n\n- Trigger: no_demo\n- Host AI rule: 进入安全/权限治理复核队列。\n- Why it matters: 下游已经要求复核，不能在页面中弱化。\n- Evidence: downstream_validation.risk_items | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | no_demo; severity=medium\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 6: 存在评分风险\n\n- Trigger: no_demo\n- Host AI rule: 把风险写入边界卡，并确认是否需要人工复核。\n- Why it matters: 风险会影响是否适合普通用户安装。\n- Evidence: risks.scoring_risks | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | no_demo; severity=medium\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 7: issue/PR 响应质量未知\n\n- Trigger: issue_or_pr_quality=unknown。\n- Host AI rule: 抽样最近 issue/PR，判断是否长期无人处理。\n- Why it matters: 用户无法判断遇到问题后是否有人维护。\n- Evidence: evidence.maintainer_signals | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | issue_or_pr_quality=unknown\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n\n### Constraint 8: 发布节奏不明确\n\n- Trigger: release_recency=unknown。\n- Host AI rule: 确认最近 release/tag 和 README 安装命令是否一致。\n- Why it matters: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Evidence: evidence.maintainer_signals | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | release_recency=unknown\n- Hard boundary: do not present this pitfall as solved, verified, or safe to ignore unless later validation evidence explicitly closes it.\n",
"summary": "Context and operating boundaries for host AI agents.",
"title": "AI Context Pack"
},
"boundary_risk_card": {
"asset_id": "boundary_risk_card",
"filename": "BOUNDARY_RISK_CARD.md",
"markdown": "# Boundary & Risk Card\n\nProject: ie3jp/illustrator-mcp-server\n\n## Doramagic Trial Decision\n\nCurrent decision: it can enter pre-publication recommendation checks. First use should still start with least privilege, a temporary directory, and reversible configuration.\n\n## What The User Can Do Now\n\n- Read the Human Manual first to understand the project purpose and main workflows.\n- Use Prompt Preview for pre-install exploration; it validates interaction shape, not real execution.\n- Run official Quick Start commands only inside an isolated environment, not a primary setup.\n\n## Do Not Do Yet\n\n- Do not treat Prompt Preview as a real project execution result.\n- Do not treat metadata-only validation as sandbox installation validation.\n- Do not describe unverified capabilities as supported, working, or safe to install.\n- Do not provide production data, private files, real secrets, or primary host configuration on first trial.\n\n## Pre-Install Checklist\n\n- Host AI match: mcp_host, claude, claude_code\n- Official installation entry status: official entry point found\n- Isolated temporary directory, temporary host, or container validation: required\n- Configuration rollback path: required\n- API keys, network access, file access, or host configuration changes: treat as high risk until confirmed\n- Installation command, actual output, and failure logs: must be recorded\n\n## Current Blockers\n\n- No blockers.\n\n## Project-Specific Pitfalls\n\n- 可能修改宿主 AI 配置 (medium): 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。 Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- 能力判断依赖假设 (medium): 假设不成立时，用户拿不到承诺的能力。 Suggested check: 将假设转成下游验证清单。\n- 来源证据：編集可能な Illustrator アートワークのための SVG インポート動作の明確化と改善 (medium): 可能增加新用户试用和生产接入成本。 Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- 维护活跃度未知 (medium): 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- 下游验证发现风险项 (medium): 下游已经要求复核，不能在页面中弱化。 Suggested check: 进入安全/权限治理复核队列。\n\n## Risk And Permission Notes\n\n- no_demo: medium\n\n## Evidence Gaps\n\n- No structured evidence gaps are currently visible.\n",
"summary": "Installation, permission, validation, and pre-recommendation risks.",
"title": "Boundary & Risk Card"
},
"human_manual": {
"asset_id": "human_manual",
"filename": "HUMAN_MANUAL.md",
"markdown": "# https://github.com/ie3jp/illustrator-mcp-server Project Manual\n\nGenerated on: 2026-05-25 04:41:40 UTC\n\n## Table of Contents\n\n- [Project Overview](#project-overview)\n- [Getting Started](#getting-started)\n- [System Architecture](#architecture)\n- [Execution Flow](#execution-flow)\n- [Read Tools](#read-tools)\n- [Modify Tools](#modify-tools)\n- [Export Tools](#export-tools)\n- [Utility Tools](#utility-tools)\n- [Coordinate Systems](#coordinate-systems)\n- [Development Guide](#development-guide)\n\n\n\n## Project Overview\n\n### Related Pages\n\nRelated topics: [Getting Started](#getting-started), [System Architecture](#architecture)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n- [README.ko.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.ko.md)\n- [README.de.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.de.md)\n- [README.pt-BR.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.pt-BR.md)\n- [README.es.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.es.md)\n- [README.zh-CN.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.zh-CN.md)\n- [plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md)\n \n\n# Project Overview\n\n## Introduction\n\n**illustrator-mcp-server** is a Model Context Protocol (MCP) server that enables Claude, an AI assistant, to control Adobe Illustrator programmatically through natural language commands. This open-source project bridges the gap between AI capabilities and professional design workflows, allowing designers and developers to automate repetitive tasks, perform batch operations, and generate complex artwork through conversational interfaces.\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Purpose and Scope\n\nThe primary purpose of illustrator-mcp-server is to provide a comprehensive automation layer for Adobe Illustrator, making it accessible to users who may not have scripting experience while offering power users a flexible scripting alternative. The project serves multiple use cases:\n\n- **Design Automation**: Automate repetitive design tasks such as batch exports, color replacements, and object alignment\n- **Pre-press Validation**: Perform comprehensive print-readiness checks including PDF/X compliance verification\n- **Document Generation**: Create new documents with specific dimensions, color modes, and structures programmatically\n- **Design Assistance**: Enable AI-driven design workflows where Claude can generate artwork, layout suggestions, and style guides\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Architecture Overview\n\nThe system follows a client-server architecture built on the Model Context Protocol:\n\n```mermaid\ngraph TD\n subgraph \"Client Layer\"\n Claude[Claude AI Assistant]\n ClaudeCode[Claude Code CLI]\n ClaudeDesktop[Claude Desktop App]\n end\n \n subgraph \"MCP Protocol Layer\"\n MCPServer[MCP Server
illustrator-mcp-server]\n end\n \n subgraph \"Adobe Illustrator\"\n AI[Adobe Illustrator]\n AS[AppleScript / COM]\n end\n \n Claude -->|MCP Protocol| MCPServer\n MCPServer -->|Node.js 20+| AS\n AS -->|Automation API| AI\n \n ClaudeCode -.->|mcp add| MCPServer\n ClaudeDesktop -.->|npx / .mcpb| MCPServer\n```\n\n### Technology Stack\n\n| Component | Technology | Version Requirement |\n|-----------|------------|---------------------|\n| Runtime | Node.js | 20+ |\n| Language | TypeScript | - |\n| Protocol | Model Context Protocol | Latest |\n| Automation | AppleScript (macOS) / COM (Windows) | - |\n| Target App | Adobe Illustrator | CS6 or later |\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Core Feature Summary\n\n### Tool Categories\n\nThe server provides over **60 tools** organized into functional categories:\n\n| Category | Count | Primary Functions |\n|----------|-------|-------------------|\n| Read Tools | 21 | Document inspection, layer structure, color analysis, image quality |\n| Modify/Create Tools | 21+ | Shape creation, text manipulation, object modification |\n| Export Tools | 2 | SVG, PNG, JPG, PDF export with options |\n| Utility | 3 | Pre-flight checks, text consistency, workflow mode |\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n### Automatic Coordinate System Detection\n\nOne of the distinguishing features is intelligent coordinate system detection based on document color mode:\n\n```mermaid\ngraph LR\n A[Document Opens] --> B{Color Mode?}\n B -->|CMYK| C[document
coordinate system]\n B -->|RGB| D[artboard-web
coordinate system]\n \n C --> E[Origin: Bottom-left
Y-axis: Up]\n D --> F[Origin: Top-left
Y-axis: Down]\n \n E -.->|Print designers
expect| C\n F -.->|Web developers
expect| D\n```\n\n| Document Type | Coordinate System | Origin | Y Axis Direction |\n|---------------|-------------------|--------|------------------|\n| CMYK / Print | `document` | Bottom-left | Up |\n| RGB / Web | `artboard-web` | Top-left of artboard | Down |\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n### Print Production Tools\n\nThe project includes specialized tools for print production workflows:\n\n- **preflight_check**: Validates RGB color mixing, broken links, low resolution images, white overprint, transparency conflicts, and PDF/X compliance\n- **check_text_consistency**: Detects placeholders, notation variations (including Japanese double-line/Western single-line), and provides full text listing for LLM analysis\n- **export_pdf**: Generates print-ready PDFs with crop marks, bleed settings, selective downsampling, and output intent\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Installation Methods\n\n### Claude Code\n\n```bash\nclaude mcp add illustrator-mcp -- npx illustrator-mcp-server\n```\n\n### Claude Desktop\n\n#### Method 1: Direct Installation\n\n1. Download **`illustrator-mcp-server.mcpb`** from GitHub Releases\n2. Open Claude Desktop → Settings → Extensions\n3. Drag and drop the `.mcpb` file\n4. Click Install\n\n#### Method 2: Manual Configuration\n\n```json\n{\n \"mcpServers\": {\n \"illustrator\": {\n \"command\": \"npx\",\n \"args\": [\"illustrator-mcp-server\"]\n }\n }\n}\n```\n\n> **Note**: If Node.js is installed via a version manager (nvm, mise, fnm), use the full path: `\"command\": \"/full/path/to/npx\"`\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Example Workflows\n\n### Video Test Pattern Generation\n\nA complete SMPTE color bar test pattern created entirely through natural language prompts:\n\n**Prompt:**\n> Create a 1920x1080 video test pattern\n\n**Result:**\n- SMPTE color bars with PLUGE patterns\n- Title safe and action safe zones\n- Center crosshair markers\n- Resolution and format labels\n\n**Tools Used:**\n`create_document`, `manage_layers` ×4, `create_rectangle` ×2, `create_gradient` ×2, `create_path` ×11, `create_ellipse` ×14, `create_line` ×4, `create_text_frame` ×2, `modify_object`, `set_z_order`, `export`\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n### PDF/X-1a Compliance Check\n\n```mermaid\nsequenceDiagram\n participant User\n participant Claude\n participant MCP_Server\n participant Illustrator\n \n User->>Claude: Check if document is PDF/X-1a compliant\n Claude->>MCP_Server: preflight_check(target_pdf_profile: \"x1a\")\n MCP_Server->>Illustrator: Run preflight analysis\n Illustrator-->>MCP_Server: Return compliance results\n MCP_Server-->>Claude: Display errors and warnings\n Claude-->>User: Structured report with issues\n \n Note over MCP_Server: Flags: transparency,
RGB colors in CMYK,
non-outlined fonts\n```\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Platform Support\n\n| Platform | Status | Automation Method |\n|----------|--------|-------------------|\n| macOS | Fully Tested | AppleScript |\n| Windows | Partial | PowerShell COM (not fully tested) |\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Known Limitations\n\n| Limitation | Description |\n|------------|-------------|\n| Windows Support | PowerShell COM automation used; not yet tested on real hardware |\n| Live Effects | Drop shadow and similar effect parameters can be detected but not read |\n| Color Profiles | Only profile assignment available; full conversion not supported |\n| Bleed Settings | Cannot read bleed settings (API limitation) |\n| WebP Export | Not supported; use PNG or SVG instead |\n| Japanese Trim Marks | Uses TrimMark command approach for PDF export |\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Testing Infrastructure\n\n### Test Categories\n\n| Test Type | Command | Requirements |\n|-----------|---------|--------------|\n| Unit Tests | `npm test` | Node.js environment |\n| E2E Smoke Tests | `npx tsx test/e2e/smoke-test.ts` | Adobe Illustrator running |\n\nThe E2E smoke test performs:\n- Creates fresh documents (RGB + CMYK)\n- Places test objects\n- Executes **182 test cases** across **10 phases**\n- Covers all registered tools and coordinate system auto-detection\n- Automatic cleanup after completion\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Disclaimer\n\nThis tool automates many Illustrator operations, but AI can make mistakes. Extracted data, preflight results, and document modifications should always be reviewed by a human. The tool should not be relied upon as the sole quality check, especially for print submissions and client deliverables.\n\n> **Important**: The authors are not responsible for any damages or losses arising from the use of this software or its outputs.\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## License\n\nThis project is released under the [MIT License](LICENSE).\n\n---\n\n\n\n## Getting Started\n\n### Related Pages\n\nRelated topics: [Project Overview](#project-overview), [Development Guide](#development-guide)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n- [README.ko.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.ko.md)\n- [README.de.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.de.md)\n- [README.pt-BR.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.pt-BR.md)\n- [README.es.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.es.md)\n- [README.zh-CN.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.zh-CN.md)\n- [plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md)\n \n\n# Getting Started\n\n## Overview\n\nThis guide provides comprehensive instructions for setting up and running the illustrator-mcp-server, a Model Context Protocol (MCP) server that enables AI assistants like Claude to control Adobe Illustrator through natural language commands. The server acts as a bridge between Claude and Illustrator's scripting capabilities, allowing users to create, modify, and export artwork programmatically. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## System Requirements\n\nBefore installation, ensure your system meets the following requirements:\n\n| Requirement | Specification | Notes |\n|-------------|---------------|-------|\n| Node.js | 20+ | Required runtime environment |\n| Operating System | macOS / Windows | Windows uses PowerShell COM automation |\n| Adobe Illustrator | Any recent version | Multiple versions supported |\n| Claude | Code or Desktop | MCP client compatibility |\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Installation Methods\n\nThe illustrator-mcp-server supports multiple installation approaches depending on your workflow and preferences.\n\n### Method 1: Claude Code (Recommended)\n\nThe simplest installation method for Claude Code users requires only the `npx` command execution. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n```bash\nclaude mcp add illustrator-mcp -- npx illustrator-mcp-server\n```\n\nThis command registers the illustrator-mcp-server as an MCP tool that Claude Code can access. The server will be downloaded and executed on-demand via npx.\n\n### Method 2: Claude Desktop with .mcpb File\n\nFor Claude Desktop users, download the pre-built `.mcpb` file from GitHub Releases. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n**Steps:**\n\n1. Download **`illustrator-mcp-server.mcpb`** from [GitHub Releases](https://github.com/ie3jp/illustrator-mcp-server/releases/latest)\n2. Open Claude Desktop → **Settings** → **Extensions**\n3. Drag and drop the `.mcpb` file into the Extensions panel\n4. Click the **Install** button\n\n> [!NOTE]\n> The `.mcpb` extension does not auto-update. To update, download the new version and reinstall. If you prefer automatic updates, use the npx method instead. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n### Method 3: Claude Desktop Manual Configuration\n\nFor users who prefer automatic updates or need custom configuration, manually edit the Claude Desktop configuration file. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n#### Step 1: Open the Configuration File\n\nFrom the Claude Desktop menu bar:\n- **Claude** → **Settings...** → **Developer** (in the left sidebar) → Click the **Edit Config** button\n\n#### Step 2: Add Server Configuration\n\n```json\n{\n \"mcpServers\": {\n \"illustrator\": {\n \"command\": \"npx\",\n \"args\": [\"illustrator-mcp-server\"]\n }\n }\n}\n```\n\n> [!NOTE]\n> If you installed Node.js via a version manager (nvm, mise, fnm, etc.), Claude Desktop may not find `npx`. In that case, use the full path. Run `which npx` in your terminal to find the path. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n```json\n\"command\": \"/full/path/to/npx\"\n```\n\n#### Step 3: Save and Restart\n\n1. Save the file and close the text editor\n2. **Fully quit** Claude Desktop (⌘Q / Ctrl+Q) and reopen\n\n## Building from Source\n\nFor development, testing, or customization purposes, build the server from the source code. Source: [README.pt-BR.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.pt-BR.md)\n\n### Prerequisites\n\n- Git\n- Node.js 20+\n- npm\n\n### Build Steps\n\n```bash\ngit clone https://github.com/ie3jp/illustrator-mcp-server.git\ncd illustrator-mcp-server\nnpm install\nnpm run build\n```\n\nAfter building, register the local server:\n\n```bash\nclaude mcp add illustrator-mcp -- node /path/to/illustrator-mcp-server/dist/index.js\n```\n\n## Verification\n\nAfter installation, verify that the server is properly configured by running the MCP inspector. Source: [README.pt-BR.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.pt-BR.md)\n\n```bash\nnpx @modelcontextprotocol/inspector npx illustrator-mcp-server\n```\n\nThe inspector provides an interactive interface to test MCP tool calls and confirm connectivity.\n\n## Testing\n\nThe project includes comprehensive test suites to validate functionality across different scenarios.\n\n### Unit Tests\n\nRun the unit test suite to verify core functionality:\n\n```bash\nnpm test\n```\n\n### End-to-End Smoke Tests\n\nThe E2E smoke test creates new documents (RGB + CMYK), inserts test objects, executes 182 test cases across 10 phases covering all registered tools and automatic coordinate system detection, then performs automatic cleanup. Source: [README.pt-BR.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.pt-BR.md)\n\n```bash\nnpx tsx test/e2e/smoke-test.ts\n```\n\n> [!NOTE]\n> E2E tests require Illustrator to be running. The smoke test will connect to the running instance and perform operations on temporary documents.\n\n## Initial Configuration\n\n### macOS Automation Permissions\n\nOn first run, macOS requires explicit permission for automation access. Navigate to:\n\n**System Settings** → **Privacy & Security** → **Automation**\n\nLocate Claude Desktop in the list and enable access for the automation permissions requested. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n### Multiple Illustrator Versions\n\nIf you have multiple versions of Illustrator installed, you can specify which version to use during conversation. Simply say \"Use Illustrator 2024\" and the `set_illustrator_version` tool will target that version. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n> [!NOTE]\n> If Illustrator is already running, the server connects to the running instance automatically.\n\n### Windows PowerShell Configuration\n\nWindows uses PowerShell COM automation for Illustrator control. This functionality has not been tested on real hardware yet. Source: [README.es.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.es.md)\n\n## Workflow Modes\n\nThe server supports different workflow modes that affect coordinate system handling. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n| Document Type | Coordinate System | Origin | Y Axis Direction |\n|---------------|-------------------|--------|------------------|\n| CMYK / Print | `document` | Bottom-left | Up |\n| RGB / Web | `artboard-web` | Top-left of artboard | Down |\n\n- **CMYK documents** use Illustrator's native coordinate system, matching what print designers expect\n- **RGB documents** use a web-based coordinate system with origin at the top-left\n\nUse the `set_workflow` tool to override the auto-detected coordinate system when needed.\n\n## Quick Start Workflow\n\nThe following diagram illustrates the typical workflow when using the illustrator-mcp-server:\n\n```mermaid\ngraph TD\n A[User Input] --> B{Server Running?}\n B -->|No| C[Start Illustrator]\n B -->|Yes| D[Connect to Illustrator]\n C --> D\n D --> E[Send MCP Request]\n E --> F[Process Tool Call]\n F --> G{Modify or Read?}\n G -->|Modify| H[Execute Illustrator Action]\n G -->|Read| I[Query Illustrator State]\n H --> J[Return Result]\n I --> J\n J --> K[User Receives Response]\n \n L[Export Tools] --> M[SVG / PNG / PDF]\n H --> L\n```\n\n## First-Time Usage Example\n\nA typical first session might involve creating a new document and adding basic elements. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n```bash\n# Create a new 1920x1080 document\nYou: Create a new Full HD document\n\nClaude: → create_document (width: 1920, height: 1080, color_mode: \"rgb\")\n ✅ Created new document \"Untitled-1\"\n\n# Add a rectangle\nYou: Add a blue rectangle in the center\n\nClaude: → create_rectangle (x: 760, y: 390, width: 400, height: 300, fill: \"#007AFF\")\n ✅ Rectangle created\n\n# Export the result\nYou: Export as PNG\n\nClaude: → export (format: \"png\", artboard: 0)\n ✅ Exported to /output/Untitled-1.png\n```\n\n## Known Limitations\n\nBefore starting your project, be aware of the following limitations: Source: [README.es.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.es.md)\n\n| Limitation | Details |\n|------------|---------|\n| Windows Support | Uses PowerShell COM automation (not tested on real hardware) |\n| Live Effects | Drop shadow and effect parameters can be detected but not read |\n| Color Profiles | Only profile assignment available — full conversion not supported |\n| Bleed Settings | Cannot read bleed settings (Illustrator API limitation) |\n| WebP Export | Not supported — use PNG or SVG instead |\n| Japanese Trim Marks | PDF export uses TrimMark command approach, generates marks as document paths |\n| Font Embedding | Embedding mode (full/subset) cannot be controlled directly |\n| Size Variations | Only proportional scaling available — text may need manual adjustment |\n\n## Troubleshooting\n\n### npx Not Found\n\nIf Claude Desktop cannot find `npx`, install Node.js via the official installer from [nodejs.org](https://nodejs.org/) instead of using version managers like nvm, mise, or fnm. Alternatively, use the full path to npx. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n### Illustrator Not Launching\n\nModify and export tools will bring Illustrator to the foreground during execution. If Illustrator fails to launch, ensure it is properly installed and you have the necessary permissions. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n### Permission Denied on macOS\n\nGrant automation permissions in **System Settings** → **Privacy & Security** → **Automation** and ensure Claude Desktop is listed with appropriate access.\n\n## Next Steps\n\nAfter successful installation, explore the available tools:\n\n- **Read Tools** (21): `get_document_info`, `get_artboards`, `get_layers`, `get_document_structure`, `list_text_frames`, `get_colors`, `get_path_items`, `get_images`, and more\n- **Modify Tools** (38): `create_rectangle`, `create_ellipse`, `create_text_frame`, `create_path`, `modify_object`, `align_objects`, `manage_layers`, and more\n- **Export Tools** (2): `export`, `export_pdf`\n- **Utility Tools** (3): `preflight_check`, `check_text_consistency`, `set_workflow`\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n> [!CAUTION]\n> AI can make mistakes. Do not over-rely on the output — **always have a human perform the final check on submission data**. The user is responsible for the results. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n---\n\n\n\n## System Architecture\n\n### Related Pages\n\nRelated topics: [Execution Flow](#execution-flow), [Project Overview](#project-overview)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n- [README.ko.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.ko.md)\n- [README.de.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.de.md)\n- [README.pt-BR.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.pt-BR.md)\n- [README.fr.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.fr.md)\n\n \n\n# System Architecture\n\n## Overview\n\nThe illustrator-mcp-server is a Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with Adobe Illustrator through a standardized interface. The server acts as a bridge between natural language instructions from AI systems and the Adobe Illustrator scripting API, providing automation capabilities for document manipulation, design tasks, and pre-press operations.\n\nThe architecture follows a tool-based pattern where each Illustrator operation is exposed as an individual MCP tool. The server handles connection management, coordinate system transformations, and result serialization to provide a seamless experience for AI-driven design workflows.\n\n## High-Level Architecture\n\n```mermaid\ngraph TB\n subgraph \"Client Layer\"\n AI[AI Assistant
Claude, etc.]\n MCP[MCP Client]\n end\n \n subgraph \"Server Layer\"\n Server[MCP Server]\n Registry[Tool Registry]\n Executor[Tool Executor]\n end\n \n subgraph \"Adobe Illustrator\"\n API[ExtendScript API
JavaScript Bridge]\n App[Illustrator Application]\n end\n \n AI --> MCP\n MCP --> Server\n Server --> Registry\n Server --> Executor\n Executor --> API\n API --> App\n \n style AI fill:#e1f5fe\n style App fill:#fff3e0\n```\n\n## Core Components\n\n### Tool Registry\n\nThe tool registry maintains a catalog of all available MCP tools organized into functional categories. Each tool is registered with metadata including its name, description, input schema, and handler function.\n\n**Tool Categories:**\n\n| Category | Count | Description |\n|----------|-------|-------------|\n| Read Tools | 21 | Extract document information, colors, text, images, and structure |\n| Modify Tools | 38 | Create, modify, and manage objects, layers, and documents |\n| Export Tools | 2 | Export artwork to SVG, PNG, JPG, and PDF formats |\n| Utility Tools | 3 | Preflight checks, text consistency, and workflow settings |\n\nSource: [README.md](README.md)\n\n### Coordinate System Management\n\nThe server implements automatic coordinate system detection based on document color mode:\n\n| Document Type | Coordinate System | Origin | Y-Axis Direction |\n|---------------|-------------------|--------|------------------|\n| CMYK / Print | `document` | Bottom-left | Up |\n| RGB / Web | `artboard-web` | Top-left of artboard | Down |\n\nCMYK documents use Illustrator's native coordinate system matching print designer expectations, while RGB documents use a web-friendly coordinate system with origin at the top-left of the artboard. The `set_workflow` tool allows manual override of the auto-detected system.\n\nSource: [README.md](README.md)\n\n### Tool Execution Flow\n\n```mermaid\nsequenceDiagram\n participant AI as AI Assistant\n participant MCP as MCP Server\n participant Registry as Tool Registry\n participant Exec as Executor\n participant App as Illustrator API\n \n AI->>MCP: Tool Request\n MCP->>Registry: Lookup Tool Definition\n Registry-->>MCP: Tool Schema\n MCP->>Exec: Execute Tool Call\n Exec->>App: Invoke Illustrator Script\n App-->>Exec: Script Result\n Exec-->>MCP: Serialized Response\n MCP-->>AI: JSON-RPC Response\n```\n\n## System Architecture Layers\n\n### Layer 1: Client Interface\n\nThe MCP protocol defines how AI assistants communicate with the server. Clients connect using the MCP handshake protocol and receive the tool manifest during initialization.\n\n**Connection Methods:**\n\n```json\n// Claude Desktop Configuration\n{\n \"mcpServers\": {\n \"illustrator\": {\n \"command\": \"npx\",\n \"args\": [\"illustrator-mcp-server\"]\n }\n }\n}\n```\n\nSource: [README.md](README.md)\n\n### Layer 2: Server Implementation\n\nThe server layer handles:\n- MCP protocol message parsing and routing\n- Tool registration and discovery\n- Request validation and error handling\n- Response serialization\n\nThe server automatically manages Illustrator application connections, including support for multiple installed versions. The `set_illustrator_version` tool allows targeting specific Illustrator versions during a session.\n\n### Layer 3: Illustrator Bridge\n\nThe bridge layer communicates with Adobe Illustrator through the ExtendScript/JavaScript API. This layer handles:\n\n- Application state management (launch, connect, disconnect)\n- Script execution and result parsing\n- Coordinate transformation between coordinate systems\n- Error translation from Illustrator errors to MCP-friendly messages\n\nSource: [README.md](README.md)\n\n## Tool Organization\n\n### Read Tools (21 tools)\n\nThese tools extract information from the active Illustrator document:\n\n| Tool | Purpose |\n|------|---------|\n| `get_document_info` | Document metadata (dimensions, color mode, profile) |\n| `get_artboards` | Artboard information (position, size, orientation) |\n| `get_layers` | Layer structure as a tree |\n| `get_document_structure` | Full tree: layers → groups → objects |\n| `get_colors` | Color swatches, gradients, spot colors |\n| `get_path_items` | Path/shape data (fill, stroke, anchor points) |\n| `get_images` | Embedded/linked image info with print quality |\n| `get_symbols` | Symbol definitions and instances |\n| `get_guidelines` | Guide information |\n| `get_overprint_info` | Overprint settings and K only plate info |\n\nSource: [README.md](README.md)\n\n### Modify Tools (38 tools)\n\nThese tools create and modify document elements:\n\n| Category | Capabilities |\n|----------|-------------|\n| Creation | Rectangles, ellipses, lines, text frames, paths, images |\n| Modification | Object properties, z-order, grouping, alignment |\n| Document | Create, open, save, close documents |\n| Layers | Add, rename, show/hide, lock/unlock, delete |\n| Styling | Convert to outlines, assign color profiles |\n\nSource: [README.md](README.md)\n\n### Export Tools (2 tools)\n\n| Tool | Formats |\n|------|---------|\n| `export` | SVG, PNG, JPG by artboard, selection, or UUID |\n| `export_pdf` | Print-ready PDF with crop marks, bleed, output intent |\n\nSource: [README.md](README.md)\n\n### Utility Tools (3 tools)\n\n| Tool | Purpose |\n|------|---------|\n| `preflight_check` | Pre-press validation (RGB mixing, broken links, PDF/X compliance) |\n| `check_text_consistency` | Placeholder detection, notation patterns |\n| `set_workflow` | Override auto-detected coordinate system |\n\nSource: [README.md](README.md)\n\n## Data Flow Architecture\n\n```mermaid\ngraph LR\n subgraph \"Input Processing\"\n Req[Tool Request] --> Parse[Parse & Validate]\n Parse --> Transform[Coordinate Transform]\n end\n \n subgraph \"Illustrator Processing\"\n Transform --> Script[Generate Script]\n Script --> Execute[Execute in Illustrator]\n Execute --> Result[Capture Result]\n end\n \n subgraph \"Output Processing\"\n Result --> Serialize[Serialize Response]\n Serialize --> Out[JSON-RPC Response]\n end\n \n style Input Processing fill:#e8f5e9\n style Illustrator Processing fill:#fff8e1\n style Output Processing fill:#e3f2fd\n```\n\n## Multiple Illustrator Version Support\n\nThe architecture supports concurrent installation of multiple Illustrator versions. The server can detect available versions and route requests to the appropriate application instance.\n\n```mermaid\ngraph TD\n Start[Start Session] --> Check{Running Instance?}\n \n Check -->|Yes| Connect[Connect to Running]\n Check -->|No| Detect[Detect Versions]\n \n Detect --> Select[Select Version]\n Select --> Launch[Launch Illustrator]\n \n Connect --> Ready\n Launch --> Ready\n \n Ready[Ready for Commands]\n \n User[User: \"Use Illustrator 2024\"] --> Override\n Override[Call set_illustrator_version]\n Override --> Ready\n```\n\nSource: [README.md](README.md)\n\n## Workflow Modes\n\nThe server operates in two primary workflow modes that affect coordinate handling:\n\n### Web/Print Workflow\n\n| Mode | Use Case | Coordinate System |\n|------|----------|-------------------|\n| Web | RGB documents, screen output | `artboard-web` (top-left origin, Y-down) |\n| Print | CMYK documents, commercial printing | `document` (bottom-left origin, Y-up) |\n\nThe server automatically detects the appropriate mode based on the document's color mode. Manual override is available via the `set_workflow` tool when AI needs consistent coordinate behavior.\n\nSource: [README.md](README.md)\n\n## Error Handling Architecture\n\n```mermaid\ngraph TD\n Script[Script Execution] --> Success{Success?}\n \n Success -->|Yes| Return[Return Result]\n Success -->|No| Identify[Identify Error Type]\n \n Identify -->|API Error| IllustratorError[Illustrator Error]\n Identify -->|Connection Error| ConnectionError[Connection Lost]\n Identify -->|Validation Error| ValidationError[Invalid Parameters]\n \n IllustratorError --> MCPError[Format as MCP Error]\n ConnectionError --> Reconnect[Attempt Reconnect]\n ValidationError --> MCPError\n \n Reconnect --> Success\n MCPError --> Response[Error Response]\n Return --> Response\n \n style Response fill:#ffcdd2\n```\n\n## Build and Deployment\n\n### Project Structure\n\n```\nillustrator-mcp-server/\n├── dist/ # Compiled JavaScript output\n├── src/ # TypeScript source files\n│ ├── server.ts # MCP server implementation\n│ ├── index.ts # Entry point\n│ └── tools/ # Tool implementations\n├── test/ # Test files\n│ └── e2e/ # End-to-end smoke tests\n└── package.json # Dependencies and scripts\n```\n\n### Build Commands\n\n```bash\nnpm install # Install dependencies\nnpm run build # Compile TypeScript to JavaScript\nnpm test # Run unit tests\n```\n\nSource: [README.md](README.md)\n\n### Verification\n\n```bash\nnpx @modelcontextprotocol/inspector npx illustrator-mcp-server\n```\n\nThe MCP inspector tool validates that the server correctly implements the protocol and exposes all registered tools.\n\n## Limitations and Architecture Constraints\n\n| Limitation | Impact | Mitigation |\n|------------|--------|------------|\n| Windows COM automation | Untested on real hardware | Uses PowerShell for COM bridge |\n| Live effects | Cannot read shadow parameters | Effects detected but not fully readable |\n| Color profile conversion | Only profile assignment, not value conversion | Use Illustrator for conversion |\n| Bleed settings | Cannot be read from document | Configure in export settings |\n| WebP export | Not supported | Use PNG or SVG alternatives |\n\nSource: [README.pt-BR.md](README.pt-BR.md)\n\n## Security Considerations\n\nThe architecture includes several safety mechanisms:\n\n1. **Manual Verification Required**: All extracted data, preflight results, and document modifications require human review before final submission\n2. **Foreground Execution**: Modify and export tools bring Illustrator to the foreground during execution\n3. **Automation Permissions**: macOS requires explicit automation access in System Settings → Privacy & Security → Automation\n\nSource: [README.md](README.md)\n\n---\n\n\n\n## Execution Flow\n\n### Related Pages\n\nRelated topics: [System Architecture](#architecture), [Coordinate Systems](#coordinate-systems)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/executor/file-transport.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/executor/file-transport.ts)\n- [src/executor/jsx-runner.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/executor/jsx-runner.ts)\n- [src/tools/tool-executor.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/tool-executor.ts)\n- [src/jsx/helpers/common.jsx](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/jsx/helpers/common.jsx)\n- [src/tools/export/export.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export.ts)\n- [src/tools/modify/place-symbol.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/place-symbol.ts)\n- [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n \n\n# Execution Flow\n\n## Overview\n\nThe execution flow is the core mechanism by which the MCP server communicates with Adobe Illustrator to perform design operations. Since Illustrator does not natively support the MCP (Model Context Protocol) or direct Node.js integration, the server acts as an intermediary that translates tool requests into ExtendScript (JSX) commands that Illustrator can execute. This architectural pattern enables Claude and other MCP-compatible AI assistants to control Adobe Illustrator programmatically.\n\nThe execution flow handles tool parameter serialization, cross-platform script generation (AppleScript for macOS, PowerShell for Windows), and result retrieval through a file-based transport mechanism. Source: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Architecture Overview\n\n```mermaid\nflowchart LR\n Claude <-->|MCP Protocol| Server[\"MCP Server\\n(TypeScript/Node.js)\"]\n\n Server -.->|generate| Runner[\"run-{uuid}.scpt / .ps1\"]\n Server -.->|generate| JSX[\"script-{uuid}.jsx\\n(BOM UTF-8)\"]\n Server -.->|write| PF[\"params-{uuid}.json\"]\n\n Runner -->|execFile| osascript\n Runner -->|execFile| PS[\"powershell.exe\"]\n\n osascript -->|do javascript| AI[\"Adobe Illustrator\\n(ExtendScript/JSX)\"]\n PS -->|DoJavaScript| AI\n\n JSX -.->|execute| AI\n PF -.->|read| AI\n AI -.->|write| RF[\"result-{uuid}.json\"]\n RF -.->|read| Server\n```\n\nThe system comprises four primary components that communicate through the file system:\n\n| Component | Technology | Role |\n|-----------|------------|------|\n| MCP Server | TypeScript/Node.js | Receives tool requests, generates scripts, coordinates execution |\n| Runner Script | AppleScript/PowerShell | Bridges the OS shell to Illustrator's scripting engine |\n| JSX Script | ExtendScript | Contains the actual Illustrator operations |\n| Parameter File | JSON | Passes typed parameters from the server to the JSX execution context |\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Execution Pipeline Stages\n\n### Stage 1: Tool Registration and Discovery\n\nThe MCP server registers all available tools during initialization. Each tool defines a name, input schema, and handler function. Tools are organized into categories (read, modify, export, utility) and are exposed to Claude through the MCP protocol. Source: [src/tools/tool-executor.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/tool-executor.ts)\n\n### Stage 2: Request Handling\n\nWhen a tool request arrives, the server performs the following validation and preparation steps:\n\n1. **Schema validation** — Verify all required parameters are present\n2. **Coordinate system detection** — Determine whether the document uses `document` (CMYK/print) or `artboard-web` (RGB/web) coordinates\n3. **UUID generation** — Create a unique identifier for tracking this execution cycle\n4. **Script selection** — Load the appropriate JSX template for the requested operation\n\nSource: [src/tools/tool-executor.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/tool-executor.ts)\n\n### Stage 3: Parameter Serialization\n\nParameters are serialized into a JSON file using the file transport mechanism. This file-based approach is necessary because ExtendScript and the Illustrator DOM cannot directly receive complex JavaScript objects from the Node.js process. Source: [src/executor/file-transport.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/executor/file-transport.ts)\n\nThe parameter file follows the naming convention `params-{uuid}.json` and contains typed parameters that the JSX script will read during execution.\n\n### Stage 4: Script Generation\n\nThe server generates two scripts for each execution:\n\n**JSX Script (`script-{uuid}.jsx`)**\n- Written in BOM-encoded UTF-8 (required for Illustrator compatibility with non-ASCII characters)\n- Contains the ExtendScript code that manipulates the Illustrator document\n- References the parameter file path\n- Writes results to `result-{uuid}.json`\n\n**Runner Script**\n- macOS: AppleScript (`.scpt`) that executes `osascript` with the JSX path\n- Windows: PowerShell (`.ps1`) that executes Illustrator via COM automation\n- Handles platform-specific execution context and error propagation\n\nSource: [src/executor/jsx-runner.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/executor/jsx-runner.ts)\n\n### Stage 5: Cross-Platform Execution\n\n```mermaid\nflowchart TD\n subgraph macOS\n A[Node.js Server] --> B[Generate .scpt]\n B --> C[osascript]\n C --> D[do javascript]\n D --> E[Adobe Illustrator]\n end\n\n subgraph Windows\n F[Node.js Server] --> G[Generate .ps1]\n G --> H[powershell.exe]\n H --> I[DoJavaScript]\n I --> J[Adobe Illustrator]\n end\n```\n\nThe runner script invokes the appropriate shell command based on the operating system:\n\n**macOS Execution Path**\n```applescript\nosascript -l JavaScript \"/path/to/script-{uuid}.jsx\"\n```\n\n**Windows Execution Path**\n```powershell\n$ai = New-Object -ComObject Illustrator.Application\n$ai.DoJavaScript(\"/path/to/script-{uuid}.jsx\")\n```\n\nSource: [src/executor/jsx-runner.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/executor/jsx-runner.ts)\n\n### Stage 6: JSX Execution\n\nThe ExtendScript environment within Illustrator reads the parameter file and executes the DOM operations. The script has access to:\n\n- The active document and its properties\n- The parameter values serialized by the server\n- Helper utilities from `src/jsx/helpers/common.jsx`\n\nCommon helper functions include UUID management, artboard coordinate conversion, and result file writing. Source: [src/jsx/helpers/common.jsx](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/jsx/helpers/common.jsx)\n\n### Stage 7: Result Collection\n\nAfter execution completes, the JSX script writes a result file (`result-{uuid}.json`) containing:\n\n| Field | Description |\n|-------|-------------|\n| `success` | Boolean indicating whether the operation completed |\n| `error` | Boolean flag for error state |\n| `message` | Human-readable status or error message |\n| `uuid` | Identifier of the created or modified object |\n| `data` | Operation-specific result payload |\n\nSource: [src/executor/file-transport.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/executor/file-transport.ts)\n\n### Stage 8: Response Assembly\n\nThe MCP server reads the result file, parses the JSON payload, and constructs an MCP-formatted response that is sent back to Claude. If the operation failed, the response includes error details for debugging.\n\n## Coordinate System Handling\n\nThe server automatically detects and handles coordinate system differences between document types:\n\n| Document Type | Coordinate System | Origin | Y Axis Direction |\n|---------------|-------------------|--------|-------------------|\n| CMYK / Print | `document` | Bottom-left | Up |\n| RGB / Web | `artboard-web` | Top-left of artboard | Down |\n\nConversion utilities in the JSX helpers transform coordinates between systems as needed. Source: [src/jsx/helpers/common.jsx](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/jsx/helpers/common.jsx)\n\n## Error Handling\n\nThe execution flow includes multiple error handling layers:\n\n1. **Parameter validation** — Invalid inputs are rejected before script generation\n2. **Script compilation errors** — Malformed JSX is caught and reported\n3. **Runtime errors** — Illustrator DOM errors are captured in the result file\n4. **File system errors** — Missing or unwritable paths are detected\n\nExample error response structure:\n```json\n{\n \"error\": true,\n \"message\": \"Symbol not found: MySymbol\",\n \"line\": 42\n}\n```\n\nSource: [src/tools/modify/place-symbol.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/place-symbol.ts)\n\n## Export-Specific Execution\n\nExport operations follow the standard flow but include additional file verification steps:\n\n```mermaid\nflowchart TD\n Start[export tool called] --> Validate[Validate format & artboard]\n Validate --> Generate[Generate export script]\n Generate --> Execute[Run JSX via runner]\n Execute --> Check{Output file exists?}\n Check -->|Yes| DpiCalc[Calculate effective DPI]\n Check -->|No| Error[Write error result]\n DpiCalc --> Write[Write success result]\n Write --> Done[Return to Claude]\n Error --> Done\n```\n\nThe export handler verifies the output file was created and includes effective DPI calculations in the result. Source: [src/tools/export/export.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export.ts)\n\n## Build and Packaging\n\nThe server is compiled using a custom build script that:\n\n1. Compiles TypeScript to JavaScript via `tsc`\n2. Copies JSX files to the distribution directory\n3. Bundles the server into a CommonJS module for Node.js compatibility\n\n```bash\nnpm run build\n```\n\nSource: [package.json](https://github.com/ie3jp/illustrator-mcp-server/blob/main/package.json)\n\n## Testing the Execution Flow\n\nEnd-to-end smoke tests validate the complete flow by:\n\n1. Creating fresh RGB and CMYK documents\n2. Placing test objects via all registered tools\n3. Running 182 test cases across 10 phases\n4. Verifying coordinate system auto-detection\n5. Cleaning up automatically\n\n```bash\nnpx tsx test/e2e/smoke-test.ts\n```\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Summary\n\nThe execution flow transforms high-level tool requests from Claude into Illustrator DOM operations through a file-based transport mechanism. This architecture enables:\n\n- Cross-platform support (macOS and Windows)\n- Type-safe parameter passing via JSON\n- BOM UTF-8 encoding for international character support\n- Automatic coordinate system handling\n- Comprehensive error reporting\n- Asynchronous execution with UUID tracking\n\nThe separation between the MCP server, runner scripts, and JSX execution ensures that Illustrator remains isolated from the Node.js process, preventing compatibility issues between the different scripting environments.\n\n---\n\n\n\n## Read Tools\n\n### Related Pages\n\nRelated topics: [Modify Tools](#modify-tools), [Export Tools](#export-tools)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/tools/read/get-document-info.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-document-info.ts)\n- [src/tools/read/get-document-structure.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-document-structure.ts)\n- [src/tools/read/list-text-frames.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/list-text-frames.ts)\n- [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)\n- [src/tools/read/get-colors.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-colors.ts)\n- [src/tools/read/get-images.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-images.ts)\n- [src/tools/read/check-contrast.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/check-contrast.ts)\n- [src/tools/read/extract-design-tokens.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/extract-design-tokens.ts)\n \n\n# Read Tools\n\nRead Tools in illustrator-mcp-server provide comprehensive read-only access to Adobe Illustrator documents. These 21 tools enable AI assistants like Claude to inspect, analyze, and extract information from open documents without modifying them. Read Tools serve as the foundation for document analysis, design auditing, preflight checks, and AI-driven content understanding.\n\n## Overview\n\nRead Tools are categorized into four functional areas:\n\n| Category | Tool Count | Purpose |\n|----------|-----------|---------|\n| Document Analysis | 4 | Metadata, structure, coordinate systems |\n| Text Analysis | 2 | Text frame inspection and attribute details |\n| Visual Element Analysis | 10 | Colors, images, paths, effects, symbols |\n| Accessibility & Compliance | 5 | Contrast checking, design token extraction, object search |\n\nThe tool architecture follows a consistent pattern where each tool returns structured JSON data suitable for AI consumption and analysis. All Read Tools operate on the currently active Illustrator document and do not modify document state.\n\n## Architecture\n\n```mermaid\ngraph TD\n A[AI Assistant] -->|MCP Protocol| B[illustrator-mcp-server]\n B -->|COM/AppleScript| C[Adobe Illustrator]\n C -->|Document Data| B\n B -->|Structured JSON| A\n \n B --> D[Read Tools]\n B --> E[Modify Tools]\n B --> F[Export Tools]\n B --> G[Utility Tools]\n \n D --> D1[Document Tools]\n D --> D2[Text Tools]\n D --> D3[Visual Tools]\n D --> D4[Compliance Tools]\n```\n\n### Tool Registration Pattern\n\nRead Tools are registered as MCP (Model Context Protocol) handlers in the server initialization. Each tool follows this standard structure:\n\n```\nTool Name → Handler Function → Illustrator Script → JSON Response\n```\n\nSource: [src/tools/read/get-document-info.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-document-info.ts)\n\n## Document Analysis Tools\n\n### get_document_info\n\nRetrieves comprehensive metadata about the active Illustrator document.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `none` | - | - | Operates on currently active document |\n\n**Returns:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `name` | string | Document filename |\n| `path` | string | Full file path |\n| `width` | number | Document width in points |\n| `height` | number | Document height in points |\n| `colorMode` | string | \"RGB\" or \"CMYK\" |\n| `colorProfile` | string | Assigned ICC profile |\n| `artboards` | array | Array of artboard objects |\n| `layers` | number | Layer count |\n\nSource: [src/tools/read/get-document-info.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-document-info.ts)\n\n### get_artboards\n\nReturns information about all artboards in the document.\n\n**Returns:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `artboards[]` | array | List of artboard objects |\n| `artboards[].name` | string | Artboard name |\n| `artboards[].rect` | object | Position and dimensions `{x, y, width, height}` |\n| `artboards[].position` | string | Origin point reference |\n\nSource: [src/tools/read/get-document-structure.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-document-structure.ts)\n\n### get_document_structure\n\nProvides a complete hierarchical tree of the document contents.\n\n**Returns:** Nested tree structure:\n\n```\nDocument\n└── Layers\n ├── Groups\n │ └── Objects\n ├── Text Frames\n ├── Paths\n ├── Images\n └── Symbols\n```\n\n**Object Properties Returned:**\n\n| Property | Applicable To | Description |\n|----------|--------------|-------------|\n| `name` | all | Object name |\n| `type` | all | Object type (text, path, group, etc.) |\n| `uuid` | all | Unique identifier |\n| `bounds` | all | Bounding box coordinates |\n| `visible` | all | Visibility state |\n| `locked` | all | Lock state |\n\nSource: [src/tools/read/get-document-structure.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-document-structure.ts)\n\n### convert_coordinate\n\nConverts coordinates between the document coordinate system and artboard coordinate system.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `x` | number | Yes | X coordinate |\n| `y` | number | Yes | Y coordinate |\n| `from` | string | Yes | Source system: \"document\" or \"artboard\" |\n| `to` | string | Yes | Target system: \"document\" or \"artboard\" |\n\n**Coordinate System Reference:**\n\n| Document Type | Coordinate System | Origin | Y-axis Direction |\n|---------------|-------------------|--------|------------------|\n| CMYK/Print | `document` | Bottom-left | Up |\n| RGB/Web | `artboard-web` | Top-left of artboard | Down |\n\nSource: [src/tools/read/get-document-info.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-document-info.ts)\n\n## Text Analysis Tools\n\n### list_text_frames\n\nEnumerates all text frames in the document with key attributes.\n\n**Returns:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `textFrames[]` | array | List of text frame objects |\n| `textFrames[].name` | string | Object name |\n| `textFrames[].uuid` | string | Unique identifier |\n| `textFrames[].contents` | string | Text content |\n| `textFrames[].font` | string | Font family |\n| `textFrames[].fontSize` | number | Font size in points |\n| `textFrames[].style` | string | Style name (e.g., \"Bold\", \"Italic\") |\n| `textFrames[].position` | object | {x, y} coordinates |\n\nSource: [src/tools/read/list-text-frames.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/list-text-frames.ts)\n\n### get_text_frame_detail\n\nReturns comprehensive attributes for a specific text frame.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `uuid` | string | Yes | Text frame UUID |\n\n**Returns:**\n\n| Category | Fields |\n|----------|--------|\n| Basic | name, uuid, contents, font, fontSize |\n| Style | style, fillColor, paragraphSpacing |\n| Spacing | tracking, kerning, leading, baselineShift |\n| Paragraph | alignment, firstLineIndent, leftIndent, rightIndent |\n| Hyphenation | hyphenation, hyphenatedWordSize, hyphenationPreference |\n| Position | x, y, width, height, rotation |\n\nSource: [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)\n\n## Color Analysis Tools\n\n### get_colors\n\nExtracts all color definitions used in the document.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `include_diagnostics` | boolean | No | Enable print-specific diagnostics |\n\n**Returns:**\n\n| Color Type | Description |\n|------------|-------------|\n| Swatches | Named colors from swatch panel |\n| Gradients | Gradient definitions (linear/radial) |\n| Spot Colors | Spot color definitions |\n| Process Colors | CMYK/RGB process colors |\n\n**Diagnostics (when enabled):**\n\n| Check | Description |\n|-------|-------------|\n| RGB in CMYK | Detects RGB colors in CMYK documents |\n| Unnamed Colors | Colors not defined in swatches |\n| Gradient Issues | Missing gradient stops |\n\nSource: [src/tools/read/get-colors.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-colors.ts)\n\n### extract_design_tokens\n\nExports document colors and typography as design system tokens.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `format` | string | No | Output format: \"css\", \"json\", or \"tailwind\" |\n| `scope` | string | No | \"colors\", \"typography\", or \"all\" |\n\n**Output Formats:**\n\n| Format | Example |\n|--------|---------|\n| CSS | `--color-primary: #34A853;` |\n| JSON | `{\"color\": {\"primary\": \"#34A853\"}}` |\n| Tailwind | `primary: '#34A853'` |\n\nSource: [src/tools/read/extract-design-tokens.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/extract-design-tokens.ts)\n\n## Image Analysis Tools\n\n### get_images\n\nReturns information about all embedded and linked images.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `include_print_info` | boolean | No | Enable print-quality analysis |\n\n**Returns:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `name` | string | Image filename |\n| `type` | string | \"embedded\" or \"linked\" |\n| `linkStatus` | string | \"ok\", \"missing\", or \"modified\" |\n| `actualPpi` | number | Actual resolution |\n| `effectivePpi` | number | Resolution after scaling |\n| `colorSpace` | string | Color mode of image |\n\n**Print Information (when enabled):**\n\n| Check | Field | Threshold |\n|-------|-------|-----------|\n| Resolution | effectivePpi | 300 for print |\n| Color Space | colorSpace | Match document mode |\n| Scale Factor | scale | Affects effective resolution |\n\nSource: [src/tools/read/get-images.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/get-images.ts)\n\n## Visual Element Tools\n\n### get_path_items\n\nReturns path and shape data for vector objects.\n\n**Returns:**\n\n| Data Category | Fields |\n|--------------|--------|\n| Fill | fillColor, opacity, blendMode |\n| Stroke | strokeColor, strokeWidth, strokeCap, strokeJoin, dashArray |\n| Geometry | anchorPoints, pathPoints, closed, pathType |\n\n**Path Types:**\n\n| Type | Description |\n|------|-------------|\n| `path` | Custom path with anchor points |\n| `compound` | Compound path with multiple subpaths |\n| `textPath` | Text on a path |\n\n### get_groups\n\nReturns group hierarchy and structure.\n\n**Returns:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `groups[]` | array | List of group objects |\n| `clips` | array | Clipping mask references |\n| `compoundPaths` | array | Compound path structures |\n\n### get_symbols\n\nReturns symbol definitions and all instances in use.\n\n**Returns:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `definitions[]` | array | Symbol library items |\n| `instances[]` | array | Placed symbol instances |\n| `usageCount` | number | How many times each symbol is used |\n\n### get_effects\n\nReturns effects and appearance settings.\n\n**Returns:**\n\n| Effect Type | Properties |\n|-------------|------------|\n| Opacity | opacity, blendMode |\n| Drop Shadow | xOffset, yOffset, blur, color |\n| Glow | blurRadius, spread, color |\n| Inner Effects | innerShadow, innerGlow |\n\n### get_guidelines\n\nReturns guide line information.\n\n**Returns:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `guidelines[]` | array | All guide lines |\n| `orientation` | string | \"horizontal\" or \"vertical\" |\n| `position` | number | Coordinate position |\n\n## Compliance & Accessibility Tools\n\n### check_contrast\n\nPerforms WCAG color contrast ratio analysis.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `foreground` | string | Yes | Foreground color (hex) |\n| `background` | string | Yes | Background color (hex) |\n\n**Returns:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `contrastRatio` | number | WCAG contrast ratio |\n| `wcagAA` | object | AA level pass/fail for normal and large text |\n| `wcagAAA` | object | AAA level pass/fail for normal and large text |\n\n**WCAG Thresholds:**\n\n| Level | Normal Text | Large Text |\n|-------|-------------|------------|\n| AA | 4.5:1 | 3:1 |\n| AAA | 7:1 | 4.5:1 |\n\nSource: [src/tools/read/check-contrast.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/check-contrast.ts)\n\n### find_objects\n\nSearches document objects by various criteria.\n\n**Parameters:**\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `name` | string | No | Object name (partial match) |\n| `type` | string | No | Object type filter |\n| `color` | string | No | Color match |\n| `font` | string | No | Font name filter |\n| `layer` | string | No | Layer name filter |\n\n### get_overprint_info\n\nReturns overprint settings and rich black detection.\n\n**Returns:**\n\n| Check | Description |\n|-------|-------------|\n| Overprint Settings | Objects with overprint enabled |\n| K100 Black | Pure black (K=100) usage |\n| Rich Black | Multi-channel black usage |\n| Intent | Classification as \"process\" or \"spot\" |\n\n### get_separation_info\n\nReturns color separation information for print production.\n\n**Returns:**\n\n| Plate Type | Description |\n|------------|-------------|\n| CMYK Process | Cyan, Magenta, Yellow, Black plates |\n| Spot Colors | Named spot color inks |\n| Usage Count | Object count per color plate |\n\n### get_selection\n\nReturns details of currently selected objects.\n\n**Returns:**\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `selectedItems[]` | array | All selected objects |\n| `count` | number | Number of selected items |\n| `bounds` | object | Combined bounding box |\n\n## Workflow Integration\n\nRead Tools integrate with Modify and Export Tools in complex workflows:\n\n```mermaid\ngraph LR\n A[Read Tools] -->|Inspect| B[Document Analysis]\n A -->|Validate| C[Preflight Check]\n A -->|Extract| D[Design Tokens]\n \n B --> E[Modify Tools]\n C --> F[Utility Tools]\n D --> G[Export Tools]\n \n E --> H[Document Updates]\n F --> I[Compliance Report]\n G --> J[Asset Export]\n```\n\n### Example Workflow: Export with Text Outlining\n\n```\nget_artboards → Identify target artboards\nconvert_to_outlines → Convert fonts to paths\nexport → Export as SVG/PNG\n```\n\n### Example Workflow: Print Preflight\n\n```\nget_document_info → Check color mode\nget_colors → Validate color definitions\nget_images → Verify image resolution\nget_overprint_info → Check overprint settings\npreflight_check → Comprehensive report\n```\n\n## Common Usage Patterns\n\n### Document Analysis Pattern\n\n```typescript\n// Get full document context\nconst docInfo = await get_document_info();\nconst structure = await get_document_structure();\nconst colors = await get_colors({ include_diagnostics: true });\n```\n\n### Text Audit Pattern\n\n```typescript\n// Comprehensive text analysis\nconst textFrames = await list_text_frames();\nconst details = await Promise.all(\n textFrames.map(tf => get_text_frame_detail({ uuid: tf.uuid }))\n);\n```\n\n### Design System Extraction Pattern\n\n```typescript\n// Export as CSS custom properties\nconst tokens = await extract_design_tokens({ \n format: \"css\",\n scope: \"all\" \n});\n```\n\n## Limitations\n\n| Limitation | Details |\n|------------|---------|\n| Live Effects | Effect parameters (e.g., drop shadow settings) can be detected but not fully read |\n| Bleed Settings | Bleed settings cannot be read (Illustrator API limitation) |\n| Windows COM | Requires PowerShell for Windows COM automation |\n| Document Required | Most tools require an open document (except `list_fonts`) |\n\n## See Also\n\n- [Modify Tools](modify-tools.md) - Tools for editing document content\n- [Export Tools](export-tools.md) - Tools for exporting documents\n- [Utility Tools](utility-tools.md) - Pre-flight and workflow utilities\n- [Preflight Workflow](../workflows/print-preflight-workflow.md) - Complete print compliance workflow\n\n---\n\n\n\n## Modify Tools\n\n### Related Pages\n\nRelated topics: [Read Tools](#read-tools), [Export Tools](#export-tools)\n\n# Modify Tools\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/tools/modify/create-document.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/create-document.ts)\n- [src/tools/modify/create-rectangle.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/create-rectangle.ts)\n- [src/tools/modify/create-text-frame.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/create-text-frame.ts)\n- [src/tools/modify/manage-layers.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/manage-layers.ts)\n- [src/tools/modify/align-objects.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/align-objects.ts)\n- [src/tools/modify/group-objects.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/group-objects.ts)\n- [src/tools/modify/save-document.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/save-document.ts)\n- [src/tools/modify/manage-swatches.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/modify/manage-swatches.ts)\n\n \n\n## Overview\n\nThe **Modify Tools** are a collection of 38 tools within the illustrator-mcp-server that enable AI assistants (specifically Claude) to create, modify, and manipulate objects in Adobe Illustrator documents through natural language commands. These tools form the core of the server's ability to perform design operations by bridging natural language instructions with the Adobe Illustrator scripting API.\n\nThe Modify Tools handle everything from basic shape creation (rectangles, ellipses, lines) to complex operations like object grouping, layer management, and document saving. They are designed to work seamlessly with the Read Tools and Export Tools to provide a complete workflow for automated design tasks.\n\n## Architecture\n\n### Tool Categories\n\nThe Modify Tools are organized into several functional categories:\n\n```mermaid\ngraph TD\n A[Modify Tools] --> B[Shape Creation]\n A --> C[Text Creation]\n A --> D[Object Manipulation]\n A --> E[Layer Management]\n A --> F[Document Operations]\n A --> G[Color Management]\n \n B --> B1[create_rectangle]\n B --> B2[create_ellipse]\n B --> B3[create_line]\n B --> B4[create_path]\n \n C --> C1[create_text_frame]\n \n D --> D1[modify_object]\n D --> D2[group_objects]\n D --> D3[ungroup_objects]\n D --> D4[duplicate_objects]\n D --> D5[align_objects]\n D --> D6[set_z_order]\n D --> D7[move_to_layer]\n \n E --> E1[manage_layers]\n \n F --> F1[create_document]\n F --> F2[open_document]\n F --> F3[save_document]\n F --> F4[close_document]\n \n G --> G1[manage_swatches]\n G --> G2[replace_color]\n G --> G3[assign_color_profile]\n```\n\n### Relationship with Coordinate Systems\n\nAll Modify Tools automatically adapt to the document's coordinate system, which is auto-detected based on the document type:\n\n| Document Type | Coordinate System | Origin | Y-axis Direction |\n|---------------|-------------------|--------|------------------|\n| CMYK / Print | `document` | Bottom-left | Up |\n| RGB / Web | `artboard-web` | Top-left of artboard | Down |\n\nSource: [README.md - Coordinate System](README.md)\n\n---\n\n## Shape Creation Tools\n\n### create_rectangle\n\nCreates a rectangle shape in the active document. Supports rounded corners through optional parameters.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `x` | number | X position of the rectangle |\n| `y` | number | Y position of the rectangle |\n| `width` | number | Width of the rectangle |\n| `height` | number | Height of the rectangle |\n| `cornerRadius` | number | Optional corner radius for rounded rectangles |\n\n**Usage Example:**\n\n```typescript\n// Create a basic rectangle\nawait create_rectangle({\n x: 100,\n y: 100,\n width: 200,\n height: 150\n});\n\n// Create a rounded rectangle\nawait create_rectangle({\n x: 100,\n y: 100,\n width: 200,\n height: 150,\n cornerRadius: 20\n});\n```\n\nSource: [src/tools/modify/create-rectangle.ts](src/tools/modify/create-rectangle.ts)\n\n### create_ellipse\n\nCreates an ellipse shape in the active document.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `x` | number | X position of the ellipse center |\n| `y` | number | Y position of the ellipse center |\n| `radiusX` | number | Horizontal radius |\n| `radiusY` | number | Vertical radius |\n\n### create_line\n\nCreates a line segment between two points.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `startX` | number | Starting X coordinate |\n| `startY` | number | Starting Y coordinate |\n| `endX` | number | Ending X coordinate |\n| `endY` | number | Ending Y coordinate |\n\n### create_path\n\nCreates a custom path with Bezier curve handles for complex shapes.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `pathData` | string | SVG path data string defining the shape |\n\n---\n\n## Text Creation Tools\n\n### create_text_frame\n\nCreates a text frame that can be either point text (single line) or area text (paragraph text within bounds).\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `x` | number | X position |\n| `y` | number | Y position |\n| `contents` | string | The text content to display |\n| `textType` | \"point\" \\| \"area\" | Type of text frame |\n| `width` | number | Width (required for area text) |\n| `height` | number | Height (required for area text) |\n| `fontSize` | number | Font size in points |\n| `fontFamily` | string | Font family name |\n| `fontStyle` | string | Font style (Bold, Italic, etc.) |\n| `justification` | string | Text alignment |\n| `lineSpacing` | number | Line height/spacing |\n\nSource: [src/tools/modify/create-text-frame.ts](src/tools/modify/create-text-frame.ts)\n\n---\n\n## Object Manipulation Tools\n\n### modify_object\n\nModifies properties of an existing object. This is a versatile tool that can update fill, stroke, position, size, and other attributes of any selected or referenced object.\n\n**Modifiable Properties:**\n\n| Property Category | Attributes |\n|-------------------|------------|\n| Position | `x`, `y`, `width`, `height` |\n| Fill | `fillColor`, `fillPattern`, `fillGradient` |\n| Stroke | `strokeColor`, `strokeWidth`, `strokeCap`, `strokeJoin` |\n| Transform | `rotation`, `shear`, `flip` |\n| Appearance | `opacity`, `blendMode` |\n\n**Usage Example:**\n\n```typescript\nawait modify_object({\n target: \"object-uuid\",\n properties: {\n fillColor: \"#FF5733\",\n strokeColor: \"#000000\",\n strokeWidth: 2,\n opacity: 0.8\n }\n});\n```\n\nSource: [src/tools/modify/group-objects.ts](src/tools/modify/group-objects.ts)\n\n### duplicate_objects\n\nCreates a copy of specified objects with an optional positional offset.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `sourceIds` | string[] | Array of object UUIDs to duplicate |\n| `offsetX` | number | Horizontal offset for the copy |\n| `offsetY` | number | Vertical offset for the copy |\n\n### align_objects\n\nAligns and distributes multiple objects relative to each other or to a container.\n\n**Alignment Options:**\n\n| Option | Description |\n|--------|-------------|\n| `alignHorizontal` | Left, Center, Right |\n| `alignVertical` | Top, Center, Bottom |\n| `distributeHorizontal` | Equal horizontal spacing |\n| `distributeVertical` | Equal vertical spacing |\n\nSource: [src/tools/modify/align-objects.ts](src/tools/modify/align-objects.ts)\n\n### set_z_order\n\nChanges the stacking order of objects within their layer.\n\n**Options:**\n\n| Value | Description |\n|-------|-------------|\n| `front` | Move to front of layer |\n| `back` | Move to back of layer |\n| `forward` | Move one position forward |\n| `backward` | Move one position backward |\n\n### move_to_layer\n\nTransfers objects from their current layer to a specified target layer.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `objectIds` | string[] | UUIDs of objects to move |\n| `targetLayer` | string | Name or UUID of destination layer |\n\n---\n\n## Grouping Tools\n\n### group_objects\n\nCombines multiple objects into a group. Supports clipping masks for advanced composition.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `objectIds` | string[] | Array of object UUIDs to group |\n| `createClippingMask` | boolean | Optional flag to create a clipping mask group |\n\nSource: [src/tools/modify/group-objects.ts](src/tools/modify/group-objects.ts)\n\n### ungroup_objects\n\nSeparates a group into its constituent child objects.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `groupId` | string | UUID of the group to ungroup |\n\n---\n\n## Layer Management Tools\n\n### manage_layers\n\nProvides comprehensive layer operations including creation, renaming, visibility control, locking, reordering, and deletion.\n\n**Operations:**\n\n| Operation | Description |\n|-----------|-------------|\n| `add` | Create a new layer |\n| `rename` | Change layer name |\n| `delete` | Remove a layer |\n| `show` / `hide` | Toggle layer visibility |\n| `lock` / `unlock` | Toggle layer editability |\n| `move` | Reorder layer position |\n| `merge` | Combine layers |\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `operation` | string | The action to perform |\n| `layerName` | string | Name of the layer |\n| `targetLayer` | string | Optional target for move/merge operations |\n\nSource: [src/tools/modify/manage-layers.ts](src/tools/modify/manage-layers.ts)\n\n---\n\n## Document Operations\n\n### create_document\n\nCreates a new Illustrator document with specified dimensions and color mode.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `width` | number | Document width in points |\n| `height` | number | Document height in points |\n| `colorMode` | \"RGB\" \\| \"CMYK\" | Color mode for the document |\n| `name` | string | Document name |\n\n**Example - Creating a Full HD document:**\n\n```typescript\nawait create_document({\n width: 1920,\n height: 1080,\n colorMode: \"RGB\",\n name: \"Web Banner\"\n});\n```\n\nSource: [src/tools/modify/create-document.ts](src/tools/modify/create-document.ts)\n\n### open_document\n\nOpens an existing Illustrator document from a file path.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `filePath` | string | Full path to the document |\n\n### save_document\n\nSaves or performs a save-as operation on the active document.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `filePath` | string | Optional path for save-as |\n| `options` | object | Save options (format-specific) |\n\nSource: [src/tools/modify/save-document.ts](src/tools/modify/save-document.ts)\n\n### close_document\n\nCloses the active document with optional save prompt handling.\n\n---\n\n## Color Management Tools\n\n### manage_swatches\n\nManages color swatches in the document's Swatches panel.\n\n**Operations:**\n\n| Operation | Description |\n|-----------|-------------|\n| `add` | Add a new swatch |\n| `remove` | Delete a swatch |\n| `rename` | Change swatch name |\n| `list` | Get all swatches |\n\nSource: [src/tools/modify/manage-swatches.ts](src/tools/modify/manage-swatches.ts)\n\n### replace_color\n\nFinds and replaces colors throughout the document with configurable tolerance for similar colors.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `sourceColor` | string | Color to find (hex, RGB, CMYK) |\n| `targetColor` | string | Replacement color |\n| `tolerance` | number | Similarity threshold (0-100) |\n\n### assign_color_profile\n\nAssigns (tags) a color profile to the document without converting color values.\n\n---\n\n## Utility Operations\n\n### convert_to_outlines\n\nConverts text characters to vector paths (outlines), ensuring consistent rendering regardless of font availability.\n\n**Use Cases:**\n- Preparing files for print production\n- Ensuring exact character shapes\n- Removing font dependencies\n\n**Note:** This operation is irreversible. Always confirm before converting.\n\n### place_image\n\nPlaces an image file as either a linked or embedded object.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `filePath` | string | Path to the image file |\n| `x` | number | X position |\n| `y` | number | Y position |\n| `width` | number | Display width |\n| `height` | number | Display height |\n| `link` | boolean | Whether to link (true) or embed (false) |\n\n### resize_for_variation\n\nCreates proportional size variations from a source artboard.\n\n**Key Parameters:**\n\n| Parameter | Type | Description |\n|-----------|------|-------------|\n| `sourceArtboard` | string | UUID of source artboard |\n| `scaleFactors` | number[] | Array of scale percentages |\n\n---\n\n## Workflow Integration\n\nThe Modify Tools work in conjunction with Read Tools to enable intelligent modifications:\n\n```mermaid\ngraph LR\n A[Read Tools] --> B[Analyze Current State]\n B --> C[Determine Required Changes]\n C --> D[Modify Tools]\n D --> E[Execute Operations]\n E --> F[Read Tools]\n F --> G[Verify Results]\n```\n\n### Typical Workflow Pattern\n\n1. **Read** current document state using Read Tools\n2. **Plan** modifications based on requirements\n3. **Execute** Modify Tools in appropriate order\n4. **Verify** changes using Read Tools\n5. **Export** final result using Export Tools\n\n---\n\n## Coordinate System Handling\n\nAll Modify Tools automatically handle coordinate system conversion based on document type:\n\n```mermaid\ngraph TD\n A[Document Type Detected] --> B{CMYK or RGB?}\n B -->|CMYK / Print| C[Use document coordinate system]\n B -->|RGB / Web| D[Use artboard-web coordinate system]\n C --> E[Origin: Bottom-left]\n D --> F[Origin: Top-left]\n E --> G[Calculate Absolute Position]\n F --> G\n```\n\nFor RGB documents, the `convert_coordinate` tool can manually convert between coordinate systems when needed.\n\n---\n\n## Error Handling\n\nThe Modify Tools implement robust error handling for common scenarios:\n\n| Scenario | Handling |\n|----------|----------|\n| Invalid object UUID | Return error with suggestion to verify object exists |\n| Out-of-bounds coordinates | Clamp to document bounds or return warning |\n| Unsupported color format | Attempt auto-conversion or return error |\n| Layer operation on locked layer | Return error with unlock suggestion |\n| File access permission denied | Return specific error for save/open operations |\n\n---\n\n## Known Limitations\n\n| Limitation | Details |\n|------------|---------|\n| Live Effects | Drop shadow and other effect parameters can be detected but not read |\n| Color Profiles | Only profile assignment available; full conversion not supported |\n| Bleed Settings | Cannot read bleed settings (API limitation) |\n| WebP Export | Not supported; use PNG or SVG instead |\n\nSource: [README.md - Known Limitations](README.md)\n\n---\n\n## Quick Reference\n\n| Tool Category | Tools |\n|---------------|-------|\n| Shape Creation | `create_rectangle`, `create_ellipse`, `create_line`, `create_path` |\n| Text | `create_text_frame`, `convert_to_outlines` |\n| Object Manipulation | `modify_object`, `duplicate_objects`, `align_objects`, `set_z_order`, `move_to_layer` |\n| Grouping | `group_objects`, `ungroup_objects` |\n| Layers | `manage_layers` |\n| Document | `create_document`, `open_document`, `save_document`, `close_document` |\n| Color | `manage_swatches`, `replace_color`, `assign_color_profile` |\n| Media | `place_image`, `resize_for_variation` |\n\n---\n\n## See Also\n\n- **Read Tools** - Tools for inspecting document content\n- **Export Tools** - Tools for exporting documents to various formats\n- **Utility Tools** - Preflight, text consistency, and workflow configuration\n\n---\n\n\n\n## Export Tools\n\n### Related Pages\n\nRelated topics: [Read Tools](#read-tools), [Modify Tools](#modify-tools)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/tools/export/export.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export.ts)\n- [src/tools/export/export-pdf.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export-pdf.ts)\n- [src/tools/registry.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/registry.ts)\n- [server.json](https://github.com/ie3jp/illustrator-mcp-server/blob/main/server.json)\n- [manifest.json](https://github.com/ie3jp/illustrator-mcp-server/blob/main/manifest.json)\n \n\n# Export Tools\n\nThe Export Tools module provides capabilities for exporting Adobe Illustrator documents and artwork to various file formats suitable for web, print, and digital distribution. This module consists of two primary tools: `export` for raster and vector formats (SVG, PNG, JPG), and `export_pdf` for print-ready PDF production with professional prepress features.\n\n## Overview\n\nExport Tools are classified under Phase 3 of the illustrator-mcp-server architecture, focusing on export operations and print-oriented reading capabilities. These tools enable Claude to transform Illustrator documents into standardized output formats while maintaining design integrity and supporting industry-standard print production workflows.\n\n| Tool | Primary Use Case | Formats Supported |\n|------|------------------|-------------------|\n| `export` | Web assets, screen output, image formats | SVG, PNG, JPG |\n| `export_pdf` | Print production, prepress workflows | PDF with presets |\n\nSource: [src/tools/registry.ts:9-10](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/registry.ts)\n\n## Architecture\n\n### Component Interaction\n\n```mermaid\nflowchart TD\n subgraph Server[\"illustrator-mcp-server\"]\n ExportTool[\"export tool\"]\n ExportPdfTool[\"export_pdf tool\"]\n end\n \n subgraph Illustrator[\"Adobe Illustrator\"]\n JSX[\"JSX Script\\n(ExtendScript)\"]\n Document[\"Active Document\"]\n Artboards[\"Artboards Collection\"]\n end\n \n ExportTool -->|generates| ExportJSX[\"script-{uuid}.jsx\"]\n ExportPdfTool -->|generates| PdfJSX[\"script-{uuid}.jsx\"]\n \n ExportJSX -->|executes| Illustrator\n PdfJSX -->|executes| Illustrator\n \n Illustrator -->|writes| ResultFile[\"result-{uuid}.json\"]\n ResultFile -->|reads| Server\n \n Document -->|exports to| SVG[\"SVG File\"]\n Document -->|exports to| PNG[\"PNG File\"]\n Document -->|exports to| PDF[\"PDF File\"]\n```\n\n### Export Workflow Sequence\n\n```mermaid\nsequenceDiagram\n participant Client as Claude/Client\n participant Server as MCP Server\n participant AI as Adobe Illustrator\n \n Client->>Server: Request export (format, options)\n Server->>Server: Generate UUID\n Server->>Server: Create params-{uuid}.json\n Server->>Server: Create script-{uuid}.jsx\n Server->>Server: Execute via osascript/PS\n \n rect rgb(200, 220, 240)\n Note over AI: Illustrator executes JSX script\n AI->>AI: Load parameters\n AI->>AI: Open/access document\n AI->>AI: Apply export settings\n AI->>AI: Write output file\n AI->>AI: Write result-{uuid}.json\n end\n \n Server->>Server: Read result-{uuid}.json\n Server->>Client: Return export result\n \n alt Verification Required\n Server->>Server: Check file existence\n alt File not created\n Server->>Client: Error with path details\n end\n end\n```\n\n## Export Tool (`export`)\n\nThe `export` tool handles conversion of Illustrator content to web-friendly and raster formats. It supports exporting by artboard, selection, or specific object UUID.\n\n### Tool Registration\n\n```typescript\nserver.registerTool(\n 'export',\n {\n title: 'Export',\n description: 'Export objects, groups, artboards...',\n inputSchema: {\n // Parameters defined in source\n }\n }\n);\n```\n\nSource: [src/tools/export/export.ts:55-60](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export.ts)\n\n### Supported Formats\n\n| Format | Use Case | Color Support | Transparency |\n|--------|----------|---------------|--------------|\n| SVG | Web vector graphics, scalable icons | RGB/CMYK | Preserved |\n| PNG | Web images with transparency | RGB/RGBA | Preserved |\n| JPG | Compressed photographic output | RGB | Not supported |\n\n### Export Options\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `format` | string | Yes | Output format: `svg`, `png`, `jpg` |\n| `output_path` | string | No | Output file path. Auto-generates in document directory or ~/Desktop for unsaved documents |\n| `artboard_index` | number | No | Zero-based artboard index for multi-artboard documents |\n| `scale` | number | No | Scale factor for raster exports (PNG/JPG) |\n| `dpi` | number | No | Target DPI for raster exports (default: 72) |\n\n### Raster Export Details\n\nFor PNG and JPG exports, the effective DPI is calculated by multiplying the specified DPI by the scale factor:\n\n```json\n{\n \"success\": true,\n \"output_path\": \"/path/to/output.png\",\n \"format\": \"png\",\n \"dpi\": 144,\n \"scale\": 2\n}\n```\n\nSource: [src/tools/export/export.ts:42-45](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export.ts)\n\n### SVG Export Behavior\n\nThe SVG export includes special handling for artboard-named files:\n\n1. When exporting an artboard with format `svg` and an `artboard_index` is specified\n2. The output filename follows pattern: `{baseName}_{artboardName}.svg`\n3. Artboard names have spaces replaced with hyphens\n\nExample:\n- Document: `design.ai` in `/output/`\n- Artboard: `hero section`\n- Output: `/output/design_hero-section.svg`\n\nSource: [src/tools/export/export.ts:18-28](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export.ts)\n\n### Verification and Error Handling\n\nThe tool performs post-export verification:\n\n```typescript\nvar finalFile = new File(actualPath);\nif (!finalFile.exists) {\n writeResultFile(RESULT_PATH, { \n error: true, \n message: \"Export completed but output file was not created. The path may not be writable: \" + outputPath \n });\n}\n```\n\nSource: [src/tools/export/export.ts:46-48](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export.ts)\n\n## Export PDF Tool (`export_pdf`)\n\nThe `export_pdf` tool generates print-ready PDF files with comprehensive prepress options including crop marks, bleed settings, and PDF preset support.\n\n### Tool Registration\n\n```typescript\nserver.registerTool(\n 'export_pdf',\n {\n title: 'Export PDF',\n description: 'Export print-ready PDF. Note: Illustrator will be activated (brought to foreground) during execution.',\n inputSchema: {\n output_path: z.string().optional(),\n preset: z.string().optional(),\n options: z.object({...})\n }\n }\n);\n```\n\nSource: [src/tools/export/export-pdf.ts:54-68](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export-pdf.ts)\n\n### PDF Export Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `output_path` | string | No | Output file path. Auto-generates in document directory or ~/Desktop |\n| `preset` | string | No | PDF preset name (e.g., `\"[PDF/X-4:2008]\"`) |\n| `options.trim_marks` | boolean | No | Add trim marks to the export |\n| `options.marks_style` | enum | No | Trim mark style: `japanese` (double-line) or `roman` (single-line) |\n| `options.trim_mark_weight` | enum | No | Trim mark weight: `\"0.125\"`, `\"0.25\"`, `\"0.5\"` (in points) |\n| `options.registration_marks` | boolean | No | Include registration marks |\n| `options.color_bars` | boolean | No | Include color bars |\n| `options.page_information` | boolean | No | Include page information |\n\n### Japanese Crop Marks\n\nThe PDF export includes specialized handling for Japanese crop marks. When `marks_style` is set to `japanese`, the system:\n\n1. Generates Japanese crop marks using the Illustrator TrimMark command\n2. Creates marks as document paths for reliable rendering\n3. Removes marks after PDF export via undo operation\n4. Includes a note in the result indicating this behavior\n\n```typescript\nif (writeResult.japanese_marks_note) {\n result.japanese_marks_note = \"Japanese crop marks were generated as document paths via TrimMark command for reliable rendering, then removed after export.\";\n}\n```\n\nSource: [src/tools/export/export-pdf.ts:21-23](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export-pdf.ts)\n\n### PDF Presets\n\nCommon PDF presets supported by Illustrator include:\n\n| Preset | Standard | Use Case |\n|--------|----------|----------|\n| `[PDF/X-1a:2001]` | PDF/X-1a | Print production with strict requirements |\n| `[PDF/X-4:2008]` | PDF/X-4 | Modern print workflows with transparency |\n| `[Press Quality]` | General | High-quality print output |\n| `[Smallest File Size]` | General | Web delivery |\n\n### PDF Export Result\n\nSuccessful PDF export returns:\n\n```json\n{\n \"success\": true,\n \"output_path\": \"/path/to/document.pdf\",\n \"format\": \"pdf\"\n}\n```\n\n### Error Handling\n\nPDF export errors include line number information for debugging:\n\n```typescript\ncatch (e) {\n writeResultFile(RESULT_PATH, { \n error: true, \n message: \"PDF export failed: \" + e.message, \n line: e.line \n });\n}\n```\n\nSource: [src/tools/export/export-pdf.ts:30-32](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/export/export-pdf.ts)\n\n## Coordinate System Considerations\n\nExport tools automatically handle coordinate system differences based on document color mode:\n\n| Document Type | Coordinate System | Origin | Y-Axis Direction |\n|---------------|-------------------|--------|------------------|\n| CMYK/Print | `document` | Bottom-left | Up |\n| RGB/Web | `artboard-web` | Top-left of artboard | Down |\n\nThis affects how coordinates are interpreted during export, particularly for SVG output where coordinate transformation may be required.\n\n## Integration with Preflight\n\nExport tools are commonly used in conjunction with the preflight check tool for print workflows:\n\n```mermaid\nflowchart LR\n Preflight[\"preflight_check\"] --> |Validates| Doc[\"Document\"]\n Doc --> |If compliant| ExportPDF[\"export_pdf\"]\n ExportPDF --> |Generates| PrintReady[\"Print-Ready PDF\"]\n \n Preflight --> |If issues found| Review[\"Manual Review Required\"]\n```\n\nThe typical print workflow:\n1. Run `preflight_check` with target profile (e.g., `x1a`)\n2. Review compliance errors and warnings\n3. Fix issues in Illustrator\n4. Export using `export_pdf` with appropriate settings\n\n## Usage Examples\n\n### Export Artboard as SVG\n\n```\nYou: Export the hero artboard as SVG with outlined text\n\nClaude: → get_artboards → convert_to_outlines → export\n```\n\n### Export Selection as PNG\n\n```json\n{\n \"format\": \"png\",\n \"output_path\": \"/output/banner.png\",\n \"scale\": 2,\n \"dpi\": 144\n}\n```\n\n### Export Print-Ready PDF\n\n```json\n{\n \"preset\": \"[PDF/X-4:2008]\",\n \"options\": {\n \"trim_marks\": true,\n \"marks_style\": \"japanese\",\n \"registration_marks\": true,\n \"color_bars\": true\n }\n}\n```\n\n## Limitations and Notes\n\n| Feature | Limitation | Workaround |\n|---------|------------|------------|\n| Illustrator activation | `export_pdf` brings Illustrator to foreground | User should close other apps if needed |\n| Bleed settings | Cannot be controlled directly via API | Use PDF presets that include bleed |\n| Font embedding mode | Full/subset mode not directly controllable | Use PDF presets |\n| Size variations | Only proportional scaling supported | Manual text adjustment may be needed |\n\nSource: [README.md](https://github.com/ie3jp/illustrator-mcp-server/blob/main/README.md)\n\n## Related Tools\n\n| Tool Category | Tools |\n|---------------|-------|\n| Read Tools | `get_artboards`, `get_document_structure` |\n| Modify Tools | `convert_to_outlines` |\n| Utility | `preflight_check`, `check_text_consistency` |\n\n---\n\n\n\n## Utility Tools\n\n### Related Pages\n\nRelated topics: [Read Tools](#read-tools)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/tools/utility/preflight-check.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/utility/preflight-check.ts)\n- [src/tools/utility/check-text-consistency.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/utility/check-text-consistency.ts)\n- [src/tools/utility/set-workflow.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/utility/set-workflow.ts)\n- [src/tools/utility/set-illustrator-version.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/utility/set-illustrator-version.ts)\n \n\n# Utility Tools\n\nUtility Tools in the illustrator-mcp-server provide essential辅助功能 for document validation, workflow configuration, and system integration. These tools enable quality assurance workflows, coordinate system management, and environment setup essential for reliable Illustrator automation.\n\n## Overview\n\nThe Utility Tools category encompasses three primary tools that support document preparation, validation, and configuration:\n\n| Tool | Purpose |\n|------|---------|\n| `preflight_check` | Comprehensive pre-press quality validation |\n| `check_text_consistency` | Text content validation and consistency analysis |\n| `set_workflow` | Coordinate system and workflow mode configuration |\n\nThese tools serve as the foundation for print-ready production workflows, ensuring documents meet industry standards before export or submission.\n\n## Preflight Check\n\nThe `preflight_check` tool performs automated pre-press validation to identify issues that could compromise print quality or PDF/X compliance.\n\n### Purpose and Scope\n\nThe preflight check analyzes documents for print-critical issues including color space violations, missing assets, resolution problems, and PDF/X compliance failures. It provides a structured report with severity classification to prioritize fixes.\n\nSource: [README.md](README.md)\n\n### Supported Checks\n\nThe tool performs the following validations:\n\n| Check Category | Detects |\n|----------------|---------|\n| Color Mode | RGB colors in CMYK documents |\n| Links | Broken or missing linked images |\n| Resolution | Images below minimum DPI threshold |\n| Overprint | White objects set to overprint |\n| Transparency | Transparency interactions with overprint |\n| PDF/X | Profile compliance (X-1a, X-4) |\n| Spot Colors | Unused or unexpected spot colors |\n\nSource: [README.md](README.md)\n\n### Parameters\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `target_pdf_profile` | string | No | - | Target PDF profile: `\"x1a\"` or `\"x4\"` |\n| `min_dpi` | number | No | 300 | Minimum acceptable image resolution for print |\n| `include_print_info` | boolean | No | false | Include detailed print-specific diagnostics |\n\nSource: [src/tools/utility/preflight-check.ts](src/tools/utility/preflight-check.ts)\n\n### Output Structure\n\nThe preflight check returns categorized results:\n\n```typescript\ninterface PreflightResult {\n critical: PreflightIssue[];\n warnings: PreflightIssue[];\n info: PreflightInfo[];\n}\n```\n\n### PDF/X Compliance Profiles\n\n| Profile | Characteristics | Transparency |\n|---------|-----------------|--------------|\n| PDF/X-1a | CMYK/spot only, no transparency, no layers | Prohibited |\n| PDF/X-4 | Supports transparency and layers, ICC-based | Allowed |\n\nSource: [README.md](README.md)\n\n### Example Output\n\n```\n❌ PDF/X-1a compliance errors:\n- Transparency on 3 objects (X-1a prohibits transparency)\n- RGB colors found in 2 places (X-1a requires CMYK/spot only)\n\n⚠ Warnings:\n- 5 non-outlined fonts (embedding recommended)\n- Image \"photo_02.jpg\" at 150dpi (300dpi recommended)\n```\n\nSource: [README.md](README.md)\n\n## Check Text Consistency\n\nThe `check_text_consistency` tool validates text content to ensure documents are production-ready and free of placeholder or inconsistent text.\n\n### Purpose and Scope\n\nThis tool detects common text issues in design documents: dummy/placeholder text that must be replaced, notation variations that indicate inconsistencies, and provides a complete text dump for LLM-driven analysis.\n\nSource: [README.md](README.md)\n\n### Detection Capabilities\n\n| Detection Type | Description |\n|----------------|-------------|\n| Placeholder Text | Detects common placeholder patterns (Lorem ipsum, sample text) |\n| Notation Variations | Identifies katakana/halfwidth/fullwidth inconsistencies |\n| Full Text Listing | Exports all text content for external analysis |\n\nSource: [plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md](plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md)\n\n### Return Values\n\n| Field | Type | Description |\n|-------|------|-------------|\n| `hasPlaceholder` | boolean | Whether placeholder text was detected |\n| `placeholderMatches` | string[] | Array of detected placeholder patterns |\n| `notationVariations` | NotationIssue[] | Array of notation inconsistencies |\n| `allTexts` | TextItem[] | Complete listing of all text in document |\n\nSource: [src/tools/utility/check-text-consistency.ts](src/tools/utility/check-text-consistency.ts)\n\n### Workflow Integration\n\nThe tool integrates with the illustrator-preflight skill to provide LLM-driven deeper analysis:\n\n```mermaid\nflowchart TD\n A[check_text_consistency] --> B[allTexts Array]\n B --> C[LLM Analysis]\n C --> D{Typo Detection}\n C --> E{Version Mismatch}\n C --> F{Terminology Check}\n D --> G[Critical Issues]\n E --> G\n F --> G\n```\n\nSource: [plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md](plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md)\n\n## Set Workflow\n\nThe `set_workflow` tool configures the coordinate system and workflow mode to override auto-detected settings.\n\n### Purpose and Scope\n\nThe tool enables manual override of the automatic coordinate system detection, ensuring consistent behavior regardless of document type. This is essential when working with documents that have unconventional settings or when specific coordinate conventions are required.\n\nSource: [README.md](README.md)\n\n### Coordinate System Detection\n\nThe server automatically detects coordinate systems based on document type:\n\n| Document Type | Coordinate System | Origin | Y Axis Direction |\n|---------------|-------------------|--------|-------------------|\n| CMYK / Print | `document` | Bottom-left | Up |\n| RGB / Web | `artboard-web` | Top-left of artboard | Down |\n\nSource: [README.md](README.md)\n\n### Workflow Modes\n\n| Mode | Use Case |\n|------|----------|\n| `web` | RGB documents, web assets, screen output |\n| `print` | CMYK documents, print production, PDF export |\n\n### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `mode` | string | Yes | Workflow mode: `\"web\"` or `\"print\"` |\n\n### Behavior\n\nWhen `set_workflow` is called:\n\n1. The specified mode overrides auto-detection\n2. All subsequent coordinate conversions use the configured system\n3. Tools like `convert_coordinate` respect the active workflow mode\n\n```mermaid\nflowchart LR\n A[Document Opens] --> B{User calls set_workflow?}\n B -->|No| C[Auto-detect coordinate system]\n B -->|Yes| D[Use specified mode]\n C --> E[Return coordinates]\n D --> E\n```\n\nSource: [src/tools/utility/set-workflow.ts](src/tools/utility/set-workflow.ts)\n\n## Set Illustrator Version\n\nThe `set_illustrator_version` tool configures the target Illustrator version for script generation compatibility.\n\n### Purpose and Scope\n\nDifferent Illustrator versions support different scripting APIs and features. This tool ensures generated scripts target the correct version, preventing compatibility issues when working with legacy or specific version requirements.\n\nSource: [src/tools/utility/set-illustrator-version.ts](src/tools/utility/set-illustrator-version.ts)\n\n### Supported Versions\n\n| Version | Script Engine | Notes |\n|---------|---------------|-------|\n| CC 2017+ | ExtendScript / UXP | Modern scripting support |\n| Legacy | ExtendScript | Older version compatibility |\n\n### Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `version` | string | Yes | Illustrator version string (e.g., \"2024\", \"CC 2023\") |\n\n## Utility Tool Architecture\n\n```mermaid\nflowchart TB\n subgraph \"Utility Tools\"\n PC[preflight_check]\n CTC[check_text_consistency]\n SW[set_workflow]\n SIV[set_illustrator_version]\n end\n \n subgraph \"Supporting Infrastructure\"\n GSI[get_separation_info]\n GOI[get_overprint_info]\n CC[convert_coordinate]\n end\n \n PC --> GSI\n PC --> GOI\n PC --> CTC\n SW --> CC\n SIV --> PC\n \n subgraph \"Output\"\n Reports[Preflight Reports]\n TextDump[Text Analysis]\n Config[Workflow Config]\n end\n \n PC --> Reports\n CTC --> TextDump\n SW --> Config\n```\n\n## Integration with illustrator-preflight Skill\n\nThe Utility Tools are orchestrated by the `illustrator-preflight` skill for comprehensive pre-press workflows:\n\n```mermaid\nsequenceDiagram\n participant User\n participant Skill\n participant Tools\n \n User->>Skill: Run preflight check\n Skill->>Tools: preflight_check\n Skill->>Tools: get_overprint_info\n Skill->>Tools: check_text_consistency\n Tools-->>Skill: Results\n Skill->>Skill: Analyze & Classify\n Skill->>Tools: get_separation_info (conditional)\n Tools-->>Skill: Plate info\n Skill-->>User: Structured Report\n```\n\nSource: [plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md](plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md)\n\n### Preflight Workflow Steps\n\nThe skill executes a 7-step comprehensive pre-press workflow:\n\n| Step | Name | Actions |\n|------|------|---------|\n| 1 | Document | Get document info and structure |\n| 2 | Preflight | Run preflight_check |\n| 3 | Overprint | Run get_overprint_info |\n| 4 | Separations | Run get_separation_info (if spot colors) |\n| 5 | Images | Check image quality and resolution |\n| 6 | Colors | Validate color space compliance |\n| 7 | Text | Run check_text_consistency |\n\nSource: [README.md](README.md)\n\n## Common Usage Patterns\n\n### Pre-Delivery Validation\n\n```typescript\n// Run comprehensive preflight before submission\nconst preflight = await preflight_check({\n target_pdf_profile: \"x1a\",\n min_dpi: 300\n});\n\nconst overprint = await get_overprint_info();\nconst textCheck = await check_text_consistency();\n```\n\n### Workflow Configuration for Print\n\n```typescript\n// Configure for CMYK print workflow\nawait set_workflow({ mode: \"print\" });\n\n// All subsequent operations use document coordinates\nconst coords = await convert_coordinate({\n x: 100,\n y: 100,\n from: \"artboard\",\n to: \"document\"\n});\n```\n\n### Text Content Audit\n\n```typescript\nconst textResult = await check_text_consistency();\n\n// Check for placeholders\nif (textResult.hasPlaceholder) {\n console.log(\"Replace placeholder text:\", textResult.placeholderMatches);\n}\n\n// LLM-driven analysis of all text\nconst allText = textResult.allTexts.map(t => t.content);\n```\n\n## Error Handling and Limitations\n\n### Known Constraints\n\n| Limitation | Details |\n|------------|---------|\n| Live Effects | Effect parameters can be detected but not read |\n| Bleed Settings | Cannot be read due to Illustrator API limitation |\n| Font Embedding | Embedding mode cannot be controlled directly |\n\nSource: [README.md](README.md)\n\n### Best Practices\n\n1. Always run `preflight_check` before print submission\n2. Use `check_text_consistency` to catch placeholder text before delivery\n3. Set workflow mode explicitly when working with mixed document types\n4. Configure Illustrator version when targeting specific deployment environments\n\n---\n\n\n\n## Coordinate Systems\n\n### Related Pages\n\nRelated topics: [Execution Flow](#execution-flow), [Modify Tools](#modify-tools)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [src/tools/read/convert-coordinate.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/convert-coordinate.ts)\n- [src/tools/session.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/session.ts)\n \n\n# Coordinate Systems\n\nAdobe Illustrator uses two distinct coordinate systems with different origins and Y-axis orientations. The illustrator-mcp-server provides unified coordinate handling that automatically detects the appropriate system based on the document type, while also allowing manual override when needed.\n\n## Overview\n\nCoordinate systems in Illustrator determine how positions are interpreted across the application. The illustrator-mcp-server abstracts the complexity of coordinate transformations, allowing AI assistants to work with positions in a consistent manner regardless of the underlying document configuration.\n\nThe server automatically detects which coordinate system is in use based on document properties and includes coordinate system information in all tool responses via the `coordinateSystem` field.\n\n## Coordinate System Types\n\nThe illustrator-mcp-server supports two coordinate systems:\n\n| System | Document Type | Origin | Y-Axis | Use Case |\n|--------|--------------|--------|--------|----------|\n| `document` | CMYK / Print | Bottom-left | Up | Traditional print design |\n| `artboard-web` | RGB / Web | Top-left of artboard | Down | Web and digital design |\n\n### Document Coordinate System\n\nThe `document` coordinate system uses Illustrator's native coordinate space:\n\n- **Origin**: Bottom-left corner of the document\n- **Y-Axis**: Positive values extend upward\n- **Application**: CMYK documents, print workflows\n- **Behavior**: Matches what print designers expect from traditional illustration software\n\nThis system is detected when the document color mode is set to CMYK.\n\n### Artboard Web Coordinate System\n\nThe `artboard-web` coordinate system uses a web-style coordinate space:\n\n- **Origin**: Top-left corner of the active artboard\n- **Y-Axis**: Positive values extend downward\n- **Application**: RGB documents, web and digital workflows\n- **Behavior**: Matches browser and screen coordinate conventions\n\nThis system is detected when the document color mode is set to RGB.\n\n## Auto-Detection Mechanism\n\nThe server automatically determines the appropriate coordinate system based on document properties. This detection happens on session start and when documents change.\n\n```mermaid\ngraph TD\n A[Document Open] --> B{Color Mode?}\n B -->|CMYK| C[Use document System]\n B -->|RGB| D[Use artboard-web System]\n C --> E[Set coordinateSystem Field]\n D --> E\n E --> F[Cache Detection Result]\n```\n\n### Detection Signals\n\nThe auto-detection process analyzes multiple document signals:\n\n| Signal | Purpose | Indicates CMYK | Indicates RGB |\n|--------|---------|---------------|---------------|\n| `colorMode` | Primary color space | \"CMYK\" | \"RGB\" |\n| `rulerUnits` | Measurement system | mm, cm, inches | px |\n| `rasterEffectResolution` | Output resolution | Lower DPI | Higher DPI |\n| `colorProfile` | Color profile type | Print profiles | sRGB, display profiles |\n\nSource: [src/tools/session.ts:40-55](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/session.ts)\n\n### Detection Caching\n\nTo optimize performance, the auto-detection result is cached:\n\n```typescript\n// Cache key structure\nautoDetectCache = {\n documentId: string,\n colorMode: string,\n timestamp: number\n}\n```\n\nSource: [src/tools/session.ts:20-35](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/session.ts)\n\nThe cache is invalidated when:\n1. The document changes\n2. The color mode changes\n3. The artboard changes\n4. Manual override via `set_workflow` is called\n\n## Manual Override with set_workflow\n\nWhen auto-detection does not produce the desired behavior, use the `set_workflow` tool to explicitly set the coordinate system:\n\n```json\n{\n \"tool\": \"set_workflow\",\n \"parameters\": {\n \"mode\": \"web\"\n }\n}\n```\n\n### Available Workflow Modes\n\n| Mode | Coordinate System | Effect |\n|------|-------------------|--------|\n| `web` | `artboard-web` | Forces web-style coordinates |\n| `print` | `document` | Forces print-style coordinates |\n| `auto` | (auto-detected) | Resets to auto-detection |\n\nWhen `set_workflow` is called with a specific mode:\n1. The auto-detection cache is bypassed\n2. All subsequent coordinate operations use the specified system\n3. The `coordinateSystem` field reflects the manually set value\n\n## Coordinate Conversion\n\nThe `convert_coordinate` tool transforms points between coordinate systems within the active document.\n\n### Tool Parameters\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `point` | `{x: number, y: number}` | Yes | Point to convert |\n| `from` | `enum` | Yes | Source system: \"artboard\" or \"document\" |\n| `to` | `enum` | Yes | Destination system: \"artboard\" or \"document\" |\n\n### Conversion Behavior\n\n```typescript\n// Internal mapping to Illustrator constants\nconst fromMap = {\n \"artboard\": CoordinateSystem.ARTBOARDCOORDINATESYSTEM,\n \"document\": CoordinateSystem.DOCUMENTCOORDINATESYSTEM\n};\n\nconst toMap = {\n \"artboard\": CoordinateSystem.ARTBOARDCOORDINATESYSTEM,\n \"document\": CoordinateSystem.DOCUMENTCOORDINATESYSTEM\n};\n```\n\nSource: [src/tools/read/convert-coordinate.ts:1-10](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/read/convert-coordinate.ts)\n\n### Conversion Example\n\nConverting a point from artboard (web) coordinates to document (Illustrator native) coordinates:\n\n```json\n{\n \"tool\": \"convert_coordinate\",\n \"parameters\": {\n \"point\": { \"x\": 100, \"y\": 200 },\n \"from\": \"artboard\",\n \"to\": \"document\"\n }\n}\n```\n\nResponse includes the converted coordinates and system identifiers:\n\n```json\n{\n \"x\": 100,\n \"y\": 868, // Y inverted based on artboard height\n \"from\": \"artboard\",\n \"to\": \"document\"\n}\n```\n\n### Y-Axis Transformation\n\nThe conversion handles Y-axis inversion automatically:\n\n| From System | To System | Y Transformation |\n|-------------|-----------|------------------|\n| `artboard-web` | `document` | `y = artboardHeight - y` |\n| `document` | `artboard-web` | `y = artboardHeight - y` |\n\nThe artboard height is obtained from the active artboard rectangle to ensure accurate transformation.\n\n## Coordinate System in Tool Responses\n\nAll tool responses include a `coordinateSystem` field indicating which system is currently active:\n\n```json\n{\n \"success\": true,\n \"uuid\": \"abc123\",\n \"coordinateSystem\": \"artboard-web\"\n}\n```\n\nThis field helps AI assistants interpret position values correctly and choose appropriate coordinate systems for subsequent operations.\n\n## Workflow Detection Logic\n\nThe `detectWorkflow` function in session.ts determines the appropriate coordinate system based on document signals:\n\n```typescript\nexport function detectWorkflow(signals: DocumentSignals): WorkflowHint {\n const { colorMode, rulerUnits, rasterEffectResolution, colorProfile } = signals;\n\n const isCMYK = colorMode === 'CMYK';\n const isRGB = colorMode === 'RGB';\n const isPixelUnit = rulerUnits === 'px';\n const isPrintUnit = ['mm', 'cm'].includes(rulerUnits);\n \n // Decision logic based on signals\n // Returns WorkflowHint with detectedWorkflow and recommendedCoordinateSystem\n}\n```\n\nSource: [src/tools/session.ts:40-65](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/session.ts)\n\nThe detection considers:\n- **Primary signal**: Color mode (CMYK vs RGB)\n- **Supporting signals**: Ruler units, raster resolution, color profile\n- **Consistency check**: Verify all signals align\n\n## Best Practices\n\n### When to Use `document` System\n- Working with CMYK print documents\n- Creating content for physical output\n- Using print-specific measurements (mm, cm, inches)\n\n### When to Use `artboard-web` System\n- Working with RGB web documents\n- Creating content for digital display\n- Using pixel-based measurements\n\n### When to Override with `set_workflow`\n- Document auto-detection fails\n- Mixed workflow (e.g., RGB document for print preview)\n- Specific AI task requirements\n\n### Coordinate Conversion Strategy\n1. Determine the current coordinate system from tool response\n2. Use matching coordinates for the active system\n3. Convert when bridging between systems\n4. Cache conversion results for repeated operations\n\n---\n\n\n\n## Development Guide\n\n### Related Pages\n\nRelated topics: [Getting Started](#getting-started)\n\n\nRelevant source files
\n\nThe following source files were used to generate this page:\n\n- [tsconfig.json](https://github.com/ie3jp/illustrator-mcp-server/blob/main/tsconfig.json)\n- [package.json](https://github.com/ie3jp/illustrator-mcp-server/blob/main/package.json)\n- [src/tools/registry.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/tools/registry.ts)\n- [src/prompts/registry.ts](https://github.com/ie3jp/illustrator-mcp-server/blob/main/src/prompts/registry.ts)\n- [manifest.json](https://github.com/ie3jp/illustrator-mcp-server/blob/main/manifest.json)\n- [server.json](https://github.com/ie3jp/illustrator-mcp-server/blob/main/server.json)\n \n\n# Development Guide\n\nThis document serves as the comprehensive development guide for **illustrator-mcp-server**, a Model Context Protocol (MCP) server that enables AI assistants like Claude to read, manipulate, and export Adobe Illustrator design data. The server provides 26 tools for automation and inspection of Illustrator documents across macOS and Windows platforms.\n\n## Project Overview\n\nThe illustrator-mcp-server acts as a bridge between AI assistants and Adobe Illustrator's ExtendScript scripting engine. It leverages the MCP SDK to expose Illustrator functionality as discrete tools that AI can invoke through natural language commands.\n\n### Key Characteristics\n\n| Attribute | Value |\n|-----------|-------|\n| Platform | macOS, Windows |\n| Runtime | Node.js ≥20.0.0 |\n| License | MIT |\n| Repository | github.com/ie3jp/illustrator-mcp-server |\n| Current Version | 1.2.6 (server.json), 1.2.10 (manifest.json) |\n| Transport | stdio |\n\n## Project Structure\n\nThe repository follows a standard Node.js TypeScript project structure with MCP-specific components:\n\n```\nillustrator-mcp-server/\n├── src/\n│ ├── tools/\n│ │ └── registry.ts # Tool registration and definition\n│ └── prompts/\n│ └── registry.ts # Prompt templates for AI interaction\n├── dist/ # Compiled JavaScript output\n├── test/\n│ └── e2e/\n│ └── smoke-test.ts # End-to-end smoke tests\n├── manifest.json # MCP extension manifest\n├── server.json # MCP server configuration\n├── package.json # npm package configuration\n└── tsconfig.json # TypeScript configuration\n```\n\n## Development Environment Setup\n\n### Prerequisites\n\n| Requirement | Version | Purpose |\n|-------------|---------|---------|\n| Node.js | ≥20.0.0 | Server runtime |\n| npm | Latest | Package management |\n| Adobe Illustrator | Any supported version | Target application |\n| TypeScript | 6.0.2+ | Source compilation |\n\n### Installation\n\n```bash\ngit clone https://github.com/ie3jp/illustrator-mcp-server.git\ncd illustrator-mcp-server\nnpm install\n```\n\nThe `npm install` command installs both runtime dependencies and development dependencies as defined in package.json.\n\nSource: [package.json:1-50]()\n\n### Build Process\n\n```bash\nnpm run build\n```\n\nThe build command compiles TypeScript source files from `src/` to JavaScript in the `dist/` directory. The pre-publish lifecycle hook ensures the build completes before any publish operation:\n\n```json\n\"prepublishOnly\": \"npm run build\"\n```\n\nSource: [package.json:14]() [package.json:18]()\n\n## TypeScript Configuration\n\nThe project uses TypeScript for type safety and modern JavaScript features. The `tsconfig.json` defines compilation targets and module resolution:\n\n### Key Configuration Options\n\n| Option | Value | Purpose |\n|--------|-------|---------|\n| Target | ES2022+ | Modern JavaScript features |\n| Module | CommonJS or ESNext | Module system compatibility |\n| Strict | Enabled | Type safety enforcement |\n| OutDir | dist/ | Compilation output directory |\n| RootDir | src/ | Source root directory |\n\n## Tool Registration System\n\nThe MCP server exposes tools through a registration system defined in `src/tools/registry.ts`. Each tool corresponds to a specific Illustrator operation.\n\n### Tool Categories\n\nThe server provides 26 tools organized into functional categories:\n\n| Category | Count | Examples |\n|----------|-------|----------|\n| Document | 3 | `get_document_info`, `get_artboards`, `get_layers` |\n| Object | 11 | `create_rectangle`, `create_text_frame`, `modify_object` |\n| Text | 2 | `list_text_frames`, `get_text_frame_detail` |\n| Style | 4 | `create_gradient`, `create_symbol`, `get_effects` |\n| Asset | 3 | `get_images`, `get_symbols`, `get_selection` |\n| Style Guide | 1 | `extract_design_tokens`, `place_style_guide` |\n| Export | 2 | `export`, `export_pdf` |\n| Utility | 3 | `preflight_check`, `check_text_consistency`, `set_workflow` |\n| Edit | 1 | `undo` |\n\nSource: [manifest.json:15-30]()\n\n### Tool Registration Flow\n\n```mermaid\ngraph TD\n A[Start] --> B[Load tool definitions from registry.ts]\n B --> C[Parse ExtendScript handlers]\n C --> D[Register with MCP SDK]\n D --> E[Server starts listening for requests]\n E --> F[Tool invocation received]\n F --> G[Execute ExtendScript in Illustrator]\n G --> H[Return JSON response to AI]\n```\n\n### Adding New Tools\n\nTo add a new tool to the server:\n\n1. **Define the tool handler** in the appropriate source file within `src/`\n2. **Register the tool** in `src/tools/registry.ts` with:\n - Tool name and description\n - Parameter schema (JSON Schema format)\n - ExtendScript handler function\n3. **Update manifest.json** if exposing through MCP extension format\n\n## Prompt System\n\nThe prompt registry (`src/prompts/registry.ts`) contains templates that guide the AI's behavior when interacting with Illustrator through the MCP server. Prompts are particularly important for:\n\n- **Preflight workflows**: Structured validation steps for print-ready documents\n- **Design token extraction**: Systematic extraction of design system values\n- **Text consistency checking**: Pattern recognition for placeholder and inconsistency detection\n\n### Preflight Prompt Structure\n\nThe preflight skill uses a structured prompt approach:\n\n```mermaid\ngraph LR\n A[Start Preflight] --> B[Step 1: Asset Checks]\n B --> C[Step 2: Text Checks]\n C --> D[Step 3: Report Generation]\n D --> E[Critical Issues]\n D --> F[Warnings]\n D --> G[Info Items]\n```\n\nSource: [plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md:1-50]()\n\n## Testing\n\n### Unit Tests\n\n```bash\nnpm test\n```\n\nThe project uses Vitest for unit testing. Test files are located alongside source files with the `.test.ts` or `.spec.ts` extension.\n\nSource: [package.json:15]()\n\n### End-to-End Smoke Tests\n\n```bash\nnpx tsx test/e2e/smoke-test.ts\n```\n\nThe E2E smoke test requires Adobe Illustrator to be running. It performs:\n\n| Phase | Description |\n|-------|-------------|\n| Document creation | Creates RGB and CMYK test documents |\n| Object placement | Inserts test objects of various types |\n| Tool coverage | Tests all 26 registered tools |\n| Coordinate detection | Validates coordinate system auto-detection |\n| Cleanup | Automatically removes test documents |\n\n**Test Statistics:**\n- **182 test cases** across **10 phases**\n- Validates all tool registrations\n- Confirms coordinate system behavior for different document types\n\nSource: [README.md:1-50]()\n\n### Verification with MCP Inspector\n\n```bash\nnpx @modelcontextprotocol/inspector npx illustrator-mcp-server\n```\n\nThe MCP Inspector tool allows verification of the server configuration and tool registration without running a full AI client.\n\n## Build Outputs\n\n### Standard Build\n\n```bash\nnpm run build\n```\n\nOutputs compiled JavaScript to the `dist/` directory:\n- `dist/index.js` - Main server entry point\n- `dist/bundle.cjs` - CommonJS bundle for MCP packaging\n\n### MCP Extension Package\n\n```bash\nnpm run pack:mcpb\n```\n\nThis command:\n1. Builds the project\n2. Installs production dependencies only (`--omit=dev`)\n3. Packs the server using the Anthropic MCPB packager\n4. Reinstalls development dependencies\n\nOutput: `illustrator-mcp-server.mcpb` - Distributable extension package for Claude Desktop\n\nSource: [package.json:19]()\n\n## Release Process\n\n```bash\nnpm run release\n```\n\nThe release pipeline executes:\n1. `npm run build` - Compile TypeScript\n2. `npm test` - Run unit tests\n3. `git push` - Push to remote\n4. `git push --tags` - Publish version tags\n\nSource: [package.json:20]()\n\n## Server Configuration\n\n### MCP Server Manifest\n\nThe `server.json` defines the MCP server metadata:\n\n```json\n{\n \"name\": \"io.github.ie3jp/illustrator-mcp-server\",\n \"description\": \"Read, manipulate, and export Adobe Illustrator design data. 26 tools. macOS | Windows.\",\n \"version\": \"1.2.6\",\n \"packages\": [{\n \"identifier\": \"illustrator-mcp-server\",\n \"version\": \"1.2.6\",\n \"transport\": { \"type\": \"stdio\" }\n }]\n}\n```\n\nSource: [server.json:1-25]()\n\n### Claude Desktop Integration\n\nFor Claude Desktop integration, add to the MCP configuration:\n\n```json\n{\n \"mcpServers\": {\n \"illustrator\": {\n \"command\": \"npx\",\n \"args\": [\"illustrator-mcp-server\"]\n }\n }\n}\n```\n\n> **Note:** If using a Node.js version manager (nvm, mise, fnm), use the full path to npx:\n> ```json\n> \"command\": \"/full/path/to/npx\"\n> ```\n\n## Dependencies\n\n### Runtime Dependencies\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| @modelcontextprotocol/sdk | ^1.27.1 | MCP protocol implementation |\n| p-limit | ^7.3.0 | Concurrent operation limiting |\n\nSource: [package.json:33-35]()\n\n### Development Dependencies\n\n| Package | Version | Purpose |\n|---------|---------|---------|\n| typescript | ^6.0.2 | TypeScript compiler |\n| vitest | ^4.1.1 | Unit testing framework |\n| tsx | ^4.21.0 | TypeScript execution |\n| @types/node | ^25.5.0 | Node.js type definitions |\n\nSource: [package.json:37-41]()\n\n## ExtendScript Integration\n\nThe server communicates with Adobe Illustrator via ExtendScript (JavaScript for Adobe applications). Each tool maps to one or more ExtendScript commands that execute within Illustrator's scripting environment.\n\n### macOS Implementation\n\nOn macOS, the server uses AppleScript to invoke Illustrator:\n\n```applescript\ntell application \"Adobe Illustrator\"\n -- ExtendScript code executes here\nend tell\n```\n\n### Windows Implementation\n\nOn Windows, the server uses PowerShell COM automation:\n\n```powershell\n$illustrator = New-Object -ComObject Illustrator.Application\n```\n\nSource: [README.md:80-90]()\n\n## Known Development Constraints\n\n| Constraint | Impact | Workaround |\n|------------|--------|------------|\n| Windows testing | Not yet tested on real hardware | Use macOS for initial development |\n| Live effects | Parameters detectable but not readable | Manual verification required |\n| Color profiles | Limited support | Document-level color space awareness |\n| Font data | Limited access to font metadata | Use text extraction tools |\n\nSource: [README.md:95-100]()\n\n## Contributing\n\nWhen contributing to the project:\n\n1. **Follow TypeScript strict mode** - Enable all type checking options\n2. **Add unit tests** for new tools in the `test/` directory\n3. **Update manifest.json** if the tool count changes\n4. **Document in SKILL.md** for skills that require structured prompts\n5. **Test E2E smoke tests** before submitting pull requests\n\n## License\n\nThe project is licensed under the MIT License. See the [LICENSE](https://github.com/ie3jp/illustrator-mcp-server/blob/main/LICENSE) file for full terms.\n\n---\n\n---\n\n## Doramagic Pitfall Log\n\nProject: ie3jp/illustrator-mcp-server\n\nSummary: Found 8 potential pitfall items; 0 are high/blocking. Highest priority: configuration - 可能修改宿主 AI 配置.\n\n## 1. configuration · 可能修改宿主 AI 配置\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- User impact: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Guardrail action: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- Evidence: capability.host_targets | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | host_targets=mcp_host, claude, claude_code\n\n## 2. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | README/documentation is current enough for a first validation pass.\n\n## 3. runtime · 来源证据：編集可能な Illustrator アートワークのための SVG インポート動作の明確化と改善\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：編集可能な Illustrator アートワークのための SVG インポート動作の明確化と改善\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_c7b420ed6123436eb6d2b27f460dc2c8 | https://github.com/ie3jp/illustrator-mcp-server/issues/35 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | last_activity_observed missing\n\n## 5. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | no_demo; severity=medium\n\n## 6. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | no_demo; severity=medium\n\n## 7. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | issue_or_pr_quality=unknown\n\n## 8. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | release_recency=unknown\n\n\n",
"summary": "DeepWiki/Human Wiki output with a Doramagic pitfall appendix.",
"title": "Human Manual"
},
"pitfall_log": {
"asset_id": "pitfall_log",
"filename": "PITFALL_LOG.md",
"markdown": "# Pitfall Log\n\nProject: ie3jp/illustrator-mcp-server\n\nSummary: Found 8 potential pitfall items; 0 are high/blocking. Highest priority: configuration - 可能修改宿主 AI 配置.\n\n## 1. configuration · 可能修改宿主 AI 配置\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。\n- User impact: 安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。\n- Suggested check: 列出会写入的配置文件、目录和卸载/回滚步骤。\n- Guardrail action: 涉及宿主配置目录时必须给回滚路径，不能只给安装命令。\n- Evidence: capability.host_targets | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | host_targets=mcp_host, claude, claude_code\n\n## 2. capability · 能力判断依赖假设\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: README/documentation is current enough for a first validation pass.\n- User impact: 假设不成立时，用户拿不到承诺的能力。\n- Suggested check: 将假设转成下游验证清单。\n- Guardrail action: 假设必须转成验证项；没有验证结果前不能写成事实。\n- Evidence: capability.assumptions | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | README/documentation is current enough for a first validation pass.\n\n## 3. runtime · 来源证据：編集可能な Illustrator アートワークのための SVG インポート動作の明確化と改善\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: GitHub 社区证据显示该项目存在一个运行相关的待验证问题：編集可能な Illustrator アートワークのための SVG インポート動作の明確化と改善\n- User impact: 可能增加新用户试用和生产接入成本。\n- Suggested check: 来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。\n- Guardrail action: 不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。\n- Evidence: community_evidence:github | cevd_c7b420ed6123436eb6d2b27f460dc2c8 | https://github.com/ie3jp/illustrator-mcp-server/issues/35 | 来源类型 github_issue 暴露的待验证使用条件。\n\n## 4. maintenance · 维护活跃度未知\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: 未记录 last_activity_observed。\n- User impact: 新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。\n- Suggested check: 补 GitHub 最近 commit、release、issue/PR 响应信号。\n- Guardrail action: 维护活跃度未知时，推荐强度不能标为高信任。\n- Evidence: evidence.maintainer_signals | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | last_activity_observed missing\n\n## 5. security_permissions · 下游验证发现风险项\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 下游已经要求复核，不能在页面中弱化。\n- Suggested check: 进入安全/权限治理复核队列。\n- Guardrail action: 下游风险存在时必须保持 review/recommendation 降级。\n- Evidence: downstream_validation.risk_items | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | no_demo; severity=medium\n\n## 6. security_permissions · 存在评分风险\n\n- Severity: medium\n- Evidence strength: source_linked\n- Finding: no_demo\n- User impact: 风险会影响是否适合普通用户安装。\n- Suggested check: 把风险写入边界卡，并确认是否需要人工复核。\n- Guardrail action: 评分风险必须进入边界卡，不能只作为内部分数。\n- Evidence: risks.scoring_risks | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | no_demo; severity=medium\n\n## 7. maintenance · issue/PR 响应质量未知\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: issue_or_pr_quality=unknown。\n- User impact: 用户无法判断遇到问题后是否有人维护。\n- Suggested check: 抽样最近 issue/PR，判断是否长期无人处理。\n- Guardrail action: issue/PR 响应未知时，必须提示维护风险。\n- Evidence: evidence.maintainer_signals | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | issue_or_pr_quality=unknown\n\n## 8. maintenance · 发布节奏不明确\n\n- Severity: low\n- Evidence strength: source_linked\n- Finding: release_recency=unknown。\n- User impact: 安装命令和文档可能落后于代码，用户踩坑概率升高。\n- Suggested check: 确认最近 release/tag 和 README 安装命令是否一致。\n- Guardrail action: 发布节奏未知或过期时，安装说明必须标注可能漂移。\n- Evidence: evidence.maintainer_signals | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | release_recency=unknown\n",
"summary": "Identity, installation, configuration, runtime, and safety pitfalls before user trial.",
"title": "Pitfall Log"
},
"prompt_preview": {
"asset_id": "prompt_preview",
"filename": "PROMPT_PREVIEW.md",
"markdown": "# illustrator-mcp-server - Prompt Preview\n\n> Copy the prompt below into your AI host before installing anything.\n> Its purpose is to let you safely feel the project's workflow, not to claim the project has already run.\n\n## Copy this prompt\n\n```text\nYou are using an independent Doramagic capability pack for ie3jp/illustrator-mcp-server.\n\nProject:\n- Name: illustrator-mcp-server\n- Repository: https://github.com/ie3jp/illustrator-mcp-server\n- Summary: Preview illustrator-mcp-server safely before installing or changing a host AI environment.\n- Host target: mcp_host, claude, claude_code\n\nGoal:\nHelp me evaluate this project for the following task without installing it yet: I want to evaluate whether this project fits a real AI workflow before installing it.\n\nBefore taking action:\n1. Restate my task, success standard, and boundary.\n2. Identify whether the next step requires tools, browser access, network access, filesystem access, credentials, package installation, or host configuration.\n3. Use only the Doramagic Project Pack, the upstream repository, and the source-linked evidence listed below.\n4. If a real command, install step, API call, file write, or host integration is required, mark it as \"requires post-install verification\" and ask for approval first.\n5. If evidence is missing, say \"evidence is missing\" instead of filling the gap.\n\nPreviewable capabilities:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n\nCapabilities that require post-install verification:\n- Capability 1: Use the source-backed project context to guide one small, checkable workflow step.\n- Capability 2: Use the source-backed project context to guide one small, checkable workflow step.\n\nCore service flow:\n1. project-overview: Project Overview. Produce one small intermediate artifact and wait for confirmation.\n2. getting-started: Getting Started. Produce one small intermediate artifact and wait for confirmation.\n3. architecture: System Architecture. Produce one small intermediate artifact and wait for confirmation.\n4. execution-flow: Execution Flow. Produce one small intermediate artifact and wait for confirmation.\n5. read-tools: Read Tools. Produce one small intermediate artifact and wait for confirmation.\n\nSource-backed evidence to keep in mind:\n- https://github.com/ie3jp/illustrator-mcp-server#readme\n- plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md\n- README.md\n- package.json\n- manifest.json\n- CLAUDE.md\n- src/server.ts\n- src/index.ts\n- src/tools/registry.ts\n- src/executor/file-transport.ts\n\nFirst response rules:\n1. Start Step 1 only.\n2. Explain the one service action you will perform first.\n3. Ask exactly three questions about my target workflow, success standard, and sandbox boundary.\n4. Stop and wait for my answers.\n\nStep 1 follow-up protocol:\n- After I answer the first three questions, stay in Step 1.\n- Produce six parts only: clarified task, success standard, boundary conditions, two or three options, tradeoffs for each option, and one recommendation.\n- End by asking whether I confirm the recommendation.\n- Do not move to Step 2 until I explicitly confirm.\n\nConversation rules:\n- Advance one step at a time and wait for confirmation after each small artifact.\n- Write outputs as recommendations or planned checks, not as completed execution.\n- Do not claim tests passed, files changed, commands ran, APIs were called, or the project was installed.\n- If the user asks for execution, first provide the sandbox setup, expected output, rollback, and approval checkpoint.\n```\n",
"summary": "不安装项目也能感受能力节奏的安全试用 Prompt。",
"title": "Prompt Preview / 安装前试用 Prompt"
},
"quick_start": {
"asset_id": "quick_start",
"filename": "QUICK_START.md",
"markdown": "# Quick Start\n\nProject: ie3jp/illustrator-mcp-server\n\n## Official Entry Points\n\n### Node.js / npx · 官方安装入口\n\n```bash\nnpx illustrator-mcp-server\n```\n\nSource：https://github.com/ie3jp/illustrator-mcp-server#readme\n\n## Sources\n\n- docs: https://github.com/ie3jp/illustrator-mcp-server#readme\n",
"summary": "Entry points extracted from official README or installation documentation.",
"title": "Quick Start"
}
},
"validation_id": "dval_4519fc73675449d6afd2f4a0610dfb93"
}