{
  "markdown": "<p align=\"center\">\n  <picture>\n    <source media=\"(prefers-color-scheme: dark)\" srcset=\"assets/banner-dark.png\">\n    <source media=\"(prefers-color-scheme: light)\" srcset=\"assets/banner-light.png\">\n    <img alt=\"icon-composer-mcp\" src=\"assets/banner-light.png\" width=\"700\">\n  </picture>\n</p>\n\n<h1 align=\"center\">Icon Composer MCP</h1>\n\n<p align=\"center\">\n  CLI and MCP server for creating images, icons, and logos with Liquid Glass effects (iOS 26+). Not affiliated with Apple .\n</p>\n\n<p align=\"center\">\n  <a href=\"https://www.npmjs.com/package/icon-composer-mcp\"><img src=\"https://img.shields.io/npm/v/icon-composer-mcp\" alt=\"npm version\"></a>\n  <a href=\"LICENSE\"><img src=\"https://img.shields.io/npm/l/icon-composer-mcp\" alt=\"license\"></a>\n  <img src=\"https://img.shields.io/badge/platform-macOS-blue\" alt=\"platform\">\n  <img src=\"https://img.shields.io/badge/MCP-compatible-green\" alt=\"MCP compatible\">\n  <a href=\"https://glama.ai/mcp/servers/ethbak/icon-composer-mcp\"><img src=\"https://glama.ai/mcp/servers/ethbak/icon-composer-mcp/badges/score.svg\" alt=\"Glama score\"></a>\n\n</p>\n\n---\n\n## Demo\n\n<p align=\"center\">\n  <img alt=\"demo\" src=\"assets/demo.gif\" width=\"650\">\n</p>\n\n## Key Features\n\n- **Create `.icon` bundles** programmatically from PNG or SVG glyphs\n- **Full Liquid Glass** support: specular highlights, blur material, shadows, translucency\n- **Dark mode + appearance variants** with per-appearance fill specializations\n- **AI-agent ready**: 12 MCP tools + 3 workflow prompts with built-in instructions\n\n## Installation\n\n<details open>\n<summary>&nbsp;&nbsp;<img src=\"https://raw.githubusercontent.com/lobehub/lobe-icons/refs/heads/master/packages/static-svg/icons/claudecode-color.svg\" width=\"16\" height=\"16\">&nbsp;<b>Claude Code</b></summary>\n\n&nbsp;\n\n```bash\nclaude mcp add icon-composer -- npx -y icon-composer-mcp\n```\n\n</details>\n\n<details>\n<summary>&nbsp;&nbsp;<img src=\"https://cdn.simpleicons.org/claude/D97757\" width=\"16\" height=\"16\">&nbsp;<b>Claude Desktop</b></summary>\n\n&nbsp;\n\nAdd to `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"icon-composer\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"icon-composer-mcp\"]\n    }\n  }\n}\n```\n\n</details>\n\n<details>\n<summary>&nbsp;&nbsp;<picture><source media=\"(prefers-color-scheme: dark)\" srcset=\"https://cdn.simpleicons.org/cursor/FFFFFF\"><source media=\"(prefers-color-scheme: light)\" srcset=\"https://cdn.simpleicons.org/cursor/000000\"><img src=\"https://cdn.simpleicons.org/cursor/000000\" width=\"16\" height=\"16\"></picture>&nbsp;<b>Cursor</b></summary>\n\n&nbsp;\n\nAdd to `.cursor/mcp.json` in your project root (or `~/.cursor/mcp.json` for global):\n\n```json\n{\n  \"mcpServers\": {\n    \"icon-composer\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"icon-composer-mcp\"]\n    }\n  }\n}\n```\n\nThe server will appear in **Cursor Settings > MCP Servers**. No restart required.\n\n</details>\n\n<details>\n<summary>&nbsp;&nbsp;<img src=\"https://cdn.jsdelivr.net/gh/devicons/devicon/icons/vscode/vscode-original.svg\" width=\"16\" height=\"16\">&nbsp;<b>VS Code</b></summary>\n\n&nbsp;\n\nAdd to `.vscode/mcp.json` in your project root (or open **Command Palette > MCP: Open User Configuration** for global):\n\n> **Note:** VS Code uses `\"servers\"` (not `\"mcpServers\"`) and requires a `\"type\"` field.\n\n```json\n{\n  \"servers\": {\n    \"icon-composer\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"icon-composer-mcp\"]\n    }\n  }\n}\n```\n\nYou'll see Start/Stop/Restart buttons inline in the editor. First launch will prompt a trust confirmation.\n\n</details>\n\n<details>\n<summary>&nbsp;&nbsp;<picture><source media=\"(prefers-color-scheme: dark)\" srcset=\"https://cdn.simpleicons.org/windsurf/FFFFFF\"><source media=\"(prefers-color-scheme: light)\" srcset=\"https://cdn.simpleicons.org/windsurf/0B100F\"><img src=\"https://cdn.simpleicons.org/windsurf/0B100F\" width=\"16\" height=\"16\"></picture>&nbsp;<b>Windsurf</b></summary>\n\n&nbsp;\n\nFirst, enable MCP in **Windsurf Settings > Cascade > Model Context Protocol (MCP)**.\n\nThen add to `~/.codeium/windsurf/mcp_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"icon-composer\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"icon-composer-mcp\"]\n    }\n  }\n}\n```\n\nPress the **refresh button** in Windsurf settings to load the server.\n\n</details>\n\n<details>\n<summary>&nbsp;&nbsp;<b>Other MCP clients</b></summary>\n\n&nbsp;\n\nThe server uses stdio transport. Most MCP clients use this config format:\n\n```json\n{\n  \"mcpServers\": {\n    \"icon-composer\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"icon-composer-mcp\"]\n    }\n  }\n}\n```\n\nOr run the server directly:\n\n```bash\nnpx -y icon-composer-mcp\n```\n\n</details>\n\n<details>\n<summary>&nbsp;&nbsp;<b>CLI only (no MCP)</b></summary>\n\n&nbsp;\n\n```bash\nnpm install -g icon-composer-mcp\nicon-composer --help\n```\n\n</details>\n\n## How It Works\n\n<p align=\"center\">\n  <picture>\n    <source media=\"(prefers-color-scheme: dark)\" srcset=\"assets/how-it-works-dark.png\">\n    <source media=\"(prefers-color-scheme: light)\" srcset=\"assets/how-it-works-light.png\">\n    <img alt=\"how it works\" src=\"assets/how-it-works-light.png\" width=\"700\">\n  </picture>\n</p>\n\n1. **Provide a glyph** — any PNG or SVG logo/image\n2. **Create a `.icon` bundle** — sets background fill, layer scale, and glass effects\n3. **Apple's ictool renders Liquid Glass** — specular highlights, shadows, depth, and translucency\n4. **Export** — preview PNGs, App Store marketing icon, or the `.icon` bundle for Xcode\n\n## Requirements\n\n- **Node.js 18+**\n- **macOS** with [Icon Composer](https://developer.apple.com/icon-composer/) for Liquid Glass rendering\n  ```bash\n  brew install --cask icon-composer\n  ```\n- Flat previews, bundle creation/editing, and marketing export work on **any platform** without Icon Composer\n\nRun `icon-composer doctor` to check your setup.\n\n## CLI Commands\n\n| Command | Description |\n|---------|-------------|\n| `create` | Create a new `.icon` bundle from a foreground image |\n| `add-layer` | Add a layer to an existing bundle |\n| `remove` | Remove a layer or group |\n| `inspect` | Read and display bundle contents |\n| `glass` | Configure Liquid Glass effects on a group |\n| `appearance` | Set dark/tinted mode overrides |\n| `fill` | Set background fill (solid, gradient, automatic, none) |\n| `position` | Set layer/group scale and offset |\n| `fx` | Toggle all glass effects on/off |\n| `preview` | Export a preview PNG (Liquid Glass or flat) |\n| `render` | Render pixel-perfect Liquid Glass via ictool |\n| `export-marketing` | Export flat 1024x1024 PNG for App Store Connect (no alpha) |\n| `doctor` | Check system setup and dependencies |\n\n### Details\n\n<details>\n<summary><b><code>create</code></b> — Create a new <code>.icon</code> bundle</summary>\n\n&nbsp;\n\n```bash\nicon-composer create <foreground_path> <output_dir> --bg-color <hex> [options]\n```\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `--bg-color <hex>` | *required* | Background color (e.g. `\"#0A66C2\"`) |\n| `--bundle-name <name>` | `AppIcon` | Bundle name (without `.icon` extension) |\n| `--dark-bg-color <hex>` | — | Dark mode background color |\n| `--glyph-scale <n>` | `1.0` | Glyph scale (1.0 = standard ~65% of icon area) |\n| `--specular / --no-specular` | `true` | Specular highlight |\n| `--shadow-kind <kind>` | `layer-color` | Shadow type: `neutral`, `layer-color`, `none` |\n| `--shadow-opacity <n>` | `0.5` | Shadow opacity (0–1) |\n| `--blur-material <n>` | — | Blur material value (0–1) |\n| `--translucency-enabled` | `false` | Enable translucency gradient |\n| `--translucency-value <n>` | `0.4` | Translucency amount (0–1) |\n\n**Output:** Creates `<output_dir>/<bundle_name>.icon/` containing `icon.json` manifest and `Assets/` directory.\n\n</details>\n\n<details>\n<summary><b><code>add-layer</code></b> — Add a layer to an existing bundle</summary>\n\n&nbsp;\n\n```bash\nicon-composer add-layer <bundle_path> <image_path> --name <name> [options]\n```\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `--name <name>` | *required* | Layer name |\n| `--group-index <n>` | `0` | Target group index |\n| `--create-group` | `false` | Create a new group for this layer |\n| `--opacity <n>` | `1.0` | Layer opacity (0–1) |\n| `--scale <n>` | `1.0` | Layer scale |\n| `--offset-x <n>` | `0` | X offset in points |\n| `--offset-y <n>` | `0` | Y offset in points |\n| `--blend-mode <mode>` | `normal` | Blend mode (e.g. `multiply`, `screen`, `overlay`) |\n| `--glass / --no-glass` | `true` | Participate in Liquid Glass effects |\n\n**Supported formats:** `.png`, `.jpg`, `.jpeg`, `.svg`, `.webp`, `.heic`, `.heif`\n\n</details>\n\n<details>\n<summary><b><code>remove</code></b> — Remove a layer or group</summary>\n\n&nbsp;\n\n```bash\nicon-composer remove <bundle_path> --target <layer|group> --group-index <n> [--layer-index <n>]\n```\n\n</details>\n\n<details>\n<summary><b><code>inspect</code></b> — Read and display bundle contents</summary>\n\n&nbsp;\n\n```bash\nicon-composer inspect <bundle_path>\n```\n\n**Output:** Prints the full manifest JSON and lists all assets with sizes.\n\n</details>\n\n<details>\n<summary><b><code>glass</code></b> — Configure Liquid Glass effects</summary>\n\n&nbsp;\n\n```bash\nicon-composer glass <bundle_path> [options]\n```\n\n| Option | Description |\n|--------|-------------|\n| `--group-index <n>` | Target group (default: `0`) |\n| `--specular / --no-specular` | Specular highlight |\n| `--blur-material <n>` | Blur amount (0–1) |\n| `--shadow-kind <kind>` | `neutral`, `layer-color`, or `none` |\n| `--shadow-opacity <n>` | Shadow opacity (0–1) |\n| `--translucency-enabled / --no-translucency-enabled` | Translucency toggle |\n| `--translucency-value <n>` | Translucency amount (0–1) |\n| `--opacity <n>` | Group opacity (0–1) |\n| `--blend-mode <mode>` | Group blend mode |\n| `--lighting <type>` | `combined` or `individual` |\n\n</details>\n\n<details>\n<summary><b><code>appearance</code></b> — Set dark/tinted mode overrides</summary>\n\n&nbsp;\n\n```bash\nicon-composer appearance <bundle_path> --target <fill|group|layer> --appearance <dark|tinted> [options]\n```\n\n| Option | Description |\n|--------|-------------|\n| `--target <type>` | `fill` (background color), `group` (glass effects), or `layer` (individual layer) |\n| `--appearance <mode>` | `dark` or `tinted` |\n| `--group-index <n>` | Group index (for `target=group` or `target=layer`) |\n| `--layer-index <n>` | Layer index within the group (required when `target=layer`) |\n| `--bg-color <hex>` | Background color for this appearance |\n| `--specular / --no-specular` | Specular for this appearance |\n| `--shadow-kind <kind>` | Shadow type for this appearance |\n| `--shadow-opacity <n>` | Shadow opacity for this appearance |\n| `--opacity <n>` | Opacity for this appearance |\n| `--blur-material <n>` | Blur material value (0–1) for this appearance |\n| `--translucency-enabled / --no-translucency-enabled` | Translucency toggle for this appearance |\n| `--translucency-value <n>` | Translucency amount (0–1) for this appearance |\n| `--hidden / --no-hidden` | Hidden state for this appearance |\n| `--blend-mode <mode>` | Blend mode for this appearance (target=layer) |\n| `--fill-color <hex>` | Fill color for this appearance (target=layer) |\n| `--position-scale <n>` | Position scale for this appearance |\n| `--position-offset-x <n>` | Position X offset for this appearance |\n| `--position-offset-y <n>` | Position Y offset for this appearance |\n\n</details>\n\n<details>\n<summary><b><code>fill</code></b> — Set background fill</summary>\n\n&nbsp;\n\n```bash\nicon-composer fill <bundle_path> --type <solid|gradient|automatic|none> [options]\n```\n\n| Option | Description |\n|--------|-------------|\n| `--type <type>` | `solid`, `gradient`, `automatic`, or `none` |\n| `--color <hex>` | Primary color (for solid or gradient bottom) |\n| `--color2 <hex>` | Secondary color (gradient top) |\n| `--gradient-angle <n>` | Gradient angle in degrees (default: `0`) |\n\n</details>\n\n<details>\n<summary><b><code>position</code></b> — Set layer/group scale and offset</summary>\n\n&nbsp;\n\n```bash\nicon-composer position <bundle_path> [options]\n```\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `--target <type>` | `layer` | `layer` or `group` |\n| `--group-index <n>` | `0` | Group index |\n| `--layer-index <n>` | — | Layer index (required for `--target layer`) |\n| `--scale <n>` | — | Scale factor (0.05–3.0) |\n| `--offset-x <n>` | — | X offset in points |\n| `--offset-y <n>` | — | Y offset in points |\n\n</details>\n\n<details>\n<summary><b><code>fx</code></b> — Toggle all glass effects</summary>\n\n&nbsp;\n\n```bash\nicon-composer fx <bundle_path> --enable|--disable\n```\n\nEnables or disables specular, shadow, blur, and translucency on every group at once.\n\n</details>\n\n<details>\n<summary><b><code>preview</code></b> — Export a preview PNG</summary>\n\n&nbsp;\n\n```bash\nicon-composer preview <bundle_path> <output_path> [options]\n```\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `--size <n>` | `1024` | Output size in pixels |\n| `--appearance <mode>` | — | `dark` or `tinted` |\n| `--flat` | `false` | Force flat rendering (skip Liquid Glass) |\n| `--canvas-bg <preset>` | — | `light`, `dark`, `checkerboard`, `homescreen-light`, `homescreen-dark` |\n| `--apple-preset <name>` | — | Apple wallpaper: `sine-purple-orange`, `sine-gasflame`, `sine-magenta`, `sine-green-yellow`, `sine-purple-orange-black`, `sine-gray` |\n| `--canvas-bg-color <hex>` | — | Custom background color |\n| `--canvas-bg-image <path>` | — | Custom background image |\n| `--zoom <n>` | `1.0` | Zoom level (icon size relative to canvas) |\n\n**Output:** PNG file. Uses Liquid Glass rendering by default (falls back to flat if Icon Composer is not installed).\n\n</details>\n\n<details>\n<summary><b><code>render</code></b> — Render Liquid Glass via ictool</summary>\n\n&nbsp;\n\n```bash\nicon-composer render <bundle_path> <output_path> [options]\n```\n\n| Option | Default | Description |\n|--------|---------|-------------|\n| `--platform <name>` | `iOS` | `iOS`, `macOS`, or `watchOS` |\n| `--rendition <name>` | `Default` | `Default`, `Dark`, `TintedLight`, `TintedDark`, `ClearLight`, `ClearDark` |\n| `--width <n>` | `1024` | Output width |\n| `--height <n>` | `1024` | Output height |\n| `--scale <n>` | `1` | Scale factor (1x, 2x, 3x) |\n| `--light-angle <n>` | — | Light angle (0–360) |\n| `--tint-color <n>` | — | Tint hue (0–1) |\n| `--tint-strength <n>` | — | Tint strength (0–1) |\n| Canvas options | — | Same as `preview` |\n\n**Requires:** Icon Composer.app installed. Returns an error with install instructions if missing.\n\n</details>\n\n<details>\n<summary><b><code>export-marketing</code></b> — Export for App Store Connect</summary>\n\n&nbsp;\n\n```bash\nicon-composer export-marketing <bundle_path> <output_path> [--size <n>]\n```\n\n**Output:** Flat PNG with no alpha channel (avoids ITMS-90717 rejection). Default 1024x1024.\n\n</details>\n\n<details>\n<summary><b><code>doctor</code></b> — Check system setup</summary>\n\n&nbsp;\n\n```bash\nicon-composer doctor\n```\n\n**Output:** Reports Node version, platform, ictool path and version. Prints install instructions if Icon Composer is missing.\n\n</details>\n\n---\n\n## MCP Tools\n\n| Tool | Description |\n|------|-------------|\n| `create_icon` | Create a `.icon` bundle from a foreground image and background color |\n| `add_layer_to_icon` | Add a new layer to an existing bundle |\n| `remove_layer` | Remove a layer or group, optionally clean up assets |\n| `read_icon` | Inspect bundle manifest and assets |\n| `set_glass_effects` | Configure specular, blur, shadow, translucency |\n| `set_appearances` | Set dark/tinted mode overrides |\n| `set_fill` | Set background fill |\n| `set_layer_position` | Adjust layer scale and offset |\n| `toggle_fx` | Enable/disable all glass effects at once |\n| `export_preview` | Render a preview PNG |\n| `render_liquid_glass` | Render via Apple's ictool (requires Icon Composer) |\n| `export_marketing` | Export flat opaque PNG for App Store Connect |\n\nAll tools return `{ content: [{ type: \"text\", text: \"...\" }], isError?: true }`.\n\n### Details\n\n<details>\n<summary><b><code>create_icon</code></b></summary>\n\n&nbsp;\n\nCreate a `.icon` bundle from a foreground image.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `foreground_path` | string | yes | — | Absolute path to PNG or SVG |\n| `output_dir` | string | yes | — | Output directory |\n| `bundle_name` | string | no | `AppIcon` | Bundle name |\n| `bg_color` | string | yes | — | Background hex color |\n| `dark_bg_color` | string | no | — | Dark mode background color |\n| `glyph_scale` | number | no | `1.0` | Glyph scale (0.1–2.0) |\n| `specular` | boolean | no | `true` | Specular highlight |\n| `shadow_kind` | enum | no | `layer-color` | `neutral`, `layer-color`, `none` |\n| `shadow_opacity` | number | no | `0.5` | Shadow opacity (0–1) |\n| `blur_material` | number | no | — | Blur amount (0–1) |\n| `translucency_enabled` | boolean | no | `false` | Enable translucency |\n| `translucency_value` | number | no | `0.4` | Translucency amount (0–1) |\n\n</details>\n\n<details>\n<summary><b><code>add_layer_to_icon</code></b></summary>\n\n&nbsp;\n\n### `add_layer_to_icon`\n\nAdd a layer to an existing bundle.\n\n| Parameter | Type | Required | Default | Description |\n|-----------|------|----------|---------|-------------|\n| `bundle_path` | string | yes | — | Path to `.icon` bundle |\n| `image_path` | string | yes | — | Path to image file |\n| `layer_name` | string | yes | — | Layer name |\n| `group_index` | number | no | `0` | Target group |\n| `create_group` | boolean | no | `false` | Create new group |\n| `opacity` | number | no | `1.0` | Layer opacity (0–1) |\n| `scale` | number | no | `1.0` | Layer scale (0.1–2.0) |\n| `offset_x` | number | no | `0` | X offset |\n| `offset_y` | number | no | `0` | Y offset |\n| `blend_mode` | enum | no | `normal` | Blend mode |\n| `glass` | boolean | no | `true` | Glass participation |\n\n</details>\n\n<details>\n<summary><b><code>remove_layer</code></b></summary>\n\n&nbsp;\n\n### `remove_layer`\n\nRemove a layer or group. `layer_index` required when `target=layer`.\n\n| Parameter | Type | Required | Default |\n|-----------|------|----------|---------|\n| `bundle_path` | string | yes | — |\n| `target` | enum | yes | — | `layer` or `group` |\n| `group_index` | number | yes | — |\n| `layer_index` | number | no | — |\n| `cleanup_assets` | boolean | no | `true` |\n\n</details>\n\n<details>\n<summary><b><code>read_icon</code></b></summary>\n\n&nbsp;\n\n### `read_icon`\n\nInspect a bundle. Returns full manifest JSON and asset list with sizes.\n\n| Parameter | Type | Required |\n|-----------|------|----------|\n| `bundle_path` | string | yes |\n\n</details>\n\n<details>\n<summary><b><code>set_glass_effects</code></b></summary>\n\n&nbsp;\n\n### `set_glass_effects`\n\nConfigure Liquid Glass on a group. All effect parameters are optional — only provided values are changed.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `bundle_path` | string | — | Path to bundle |\n| `group_index` | number | `0` | Target group |\n| `specular` | boolean | — | Specular toggle |\n| `blur_material` | number\\|null | — | Blur (0–1, null to disable) |\n| `shadow_kind` | enum | — | `neutral`, `layer-color`, `none` |\n| `shadow_opacity` | number | — | Shadow opacity (0–1) |\n| `translucency_enabled` | boolean | — | Translucency toggle |\n| `translucency_value` | number | — | Translucency amount (0–1) |\n| `opacity` | number | — | Group opacity (0–1) |\n| `blend_mode` | enum | — | Blend mode |\n| `lighting` | enum | — | `combined` or `individual` |\n\n</details>\n\n<details>\n<summary><b><code>set_appearances</code></b></summary>\n\n&nbsp;\n\n### `set_appearances`\n\nSet dark/tinted overrides for background fill, group effects, or individual layer properties.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `bundle_path` | string | yes | Path to bundle |\n| `target` | enum | yes | `fill`, `group`, or `layer` |\n| `appearance` | enum | yes | `dark` or `tinted` |\n| `group_index` | number | no | Group index (for `target=group` or `target=layer`) |\n| `layer_index` | number | no | Layer index within the group (required when `target=layer`) |\n| `bg_color` | string | no | Background color for this appearance (target=fill) |\n| `specular` | boolean | no | Specular for this appearance (target=group) |\n| `shadow_kind` | enum | no | Shadow type (target=group) |\n| `shadow_opacity` | number | no | Shadow opacity (target=group) |\n| `opacity` | number | no | Opacity for this appearance (target=group or target=layer) |\n| `blur_material` | number\\|null | no | Blur material for this appearance (target=group) |\n| `translucency_enabled` | boolean | no | Enable translucency for this appearance (target=group) |\n| `translucency_value` | number | no | Translucency amount for this appearance (target=group) |\n| `hidden` | boolean | no | Hidden state for this appearance (target=group or target=layer) |\n| `blend_mode` | enum | no | Blend mode for this appearance (target=layer) |\n| `fill_color` | string | no | Fill color hex for this appearance (target=layer) |\n| `position_scale` | number | no | Position scale for this appearance (0.05–3.0) |\n| `position_offset_x` | number | no | Position X offset for this appearance |\n| `position_offset_y` | number | no | Position Y offset for this appearance |\n\n</details>\n\n<details>\n<summary><b><code>set_fill</code></b></summary>\n\n&nbsp;\n\n### `set_fill`\n\nSet background fill.\n\n| Parameter | Type | Required | Description |\n|-----------|------|----------|-------------|\n| `bundle_path` | string | yes | Path to bundle |\n| `fill_type` | enum | yes | `solid`, `gradient`, `automatic`, `none` |\n| `color` | string | no | Hex color (solid or gradient bottom) |\n| `color2` | string | no | Gradient top color |\n| `gradient_angle` | number | no | Angle in degrees (default: `0`) |\n\n</details>\n\n<details>\n<summary><b><code>set_layer_position</code></b></summary>\n\n&nbsp;\n\n### `set_layer_position`\n\nAdjust layer or group scale and offset.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `bundle_path` | string | — | Path to bundle |\n| `target` | enum | `layer` | `layer` or `group` |\n| `group_index` | number | `0` | Group index |\n| `layer_index` | number | — | Layer index (for `target=layer`) |\n| `scale` | number | — | Scale (0.05–3.0) |\n| `offset_x` | number | — | X offset |\n| `offset_y` | number | — | Y offset |\n\n</details>\n\n<details>\n<summary><b><code>toggle_fx</code></b></summary>\n\n&nbsp;\n\n### `toggle_fx`\n\nEnable or disable all glass effects on every group.\n\n| Parameter | Type | Required |\n|-----------|------|----------|\n| `bundle_path` | string | yes |\n| `enabled` | boolean | yes |\n\n</details>\n\n<details>\n<summary><b><code>export_preview</code></b></summary>\n\n&nbsp;\n\n### `export_preview`\n\nRender a preview PNG. Uses Liquid Glass by default, falls back to flat.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `bundle_path` | string | — | Path to bundle |\n| `output_path` | string | — | Output PNG path |\n| `size` | number | `1024` | Output size (16–2048) |\n| `appearance` | enum | — | `dark` or `tinted` |\n| `flat` | boolean | `false` | Force flat rendering |\n| `canvas_bg` | enum | — | Preset background |\n| `apple_preset` | enum | — | Apple wallpaper preset |\n| `canvas_bg_color` | string | — | Custom background hex |\n| `canvas_bg_image` | string | — | Background image path |\n| `zoom` | number | `1.0` | Zoom level (0.1–3.0) |\n| `return_image` | boolean | `true` | Return rendered image inline as base64 |\n\n</details>\n\n<details>\n<summary><b><code>render_liquid_glass</code></b></summary>\n\n&nbsp;\n\n### `render_liquid_glass`\n\nPixel-perfect Liquid Glass via Apple's ictool. Requires Icon Composer.app.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `bundle_path` | string | — | Path to bundle |\n| `output_path` | string | — | Output PNG path |\n| `platform` | enum | `iOS` | `iOS`, `macOS`, `watchOS` |\n| `rendition` | enum | `Default` | `Default`, `Dark`, `TintedLight`, `TintedDark`, `ClearLight`, `ClearDark` |\n| `width` | number | `1024` | Output width (16–2048) |\n| `height` | number | `1024` | Output height (16–2048) |\n| `scale` | number | `1` | Scale factor (1–3) |\n| `light_angle` | number | — | Light angle (0–360) |\n| `tint_color` | number | — | Tint hue (0–1) |\n| `tint_strength` | number | — | Tint strength (0–1) |\n| Canvas options | — | — | Same as `export_preview` |\n| `return_image` | boolean | `true` | Return rendered image inline as base64 |\n\n</details>\n\n<details>\n<summary><b><code>export_marketing</code></b></summary>\n\n&nbsp;\n\n### `export_marketing`\n\nFlat marketing PNG for App Store Connect. No glass effects, no alpha channel.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `bundle_path` | string | — | Path to bundle |\n| `output_path` | string | — | Output PNG path |\n| `size` | number | `1024` | Output size (16–2048) |\n| `return_image` | boolean | `true` | Return rendered image inline as base64 |\n\n</details>\n\n---\n\n### MCP Prompts\n\n| Prompt | Parameters | Description |\n|--------|------------|-------------|\n| `create-app-icon` | `image_path`, `output_dir`, `brand_color`, `dark_color?` | Guided workflow: create icon from a logo, preview, iterate, export |\n| `add-dark-mode` | `bundle_path`, `dark_color` | Add dark mode to an existing icon with before/after preview |\n| `export-for-app-store` | `bundle_path`, `output_dir` | Export marketing PNG + preview for App Store submission |\n\n## Example Workflows\n\n### Create a branded icon\n\n```bash\n# Create with brand color\nicon-composer create logo.svg ./out --bg-color \"#0A66C2\"\n\n# Add dark mode\nicon-composer appearance ./out/AppIcon.icon --target fill --appearance dark --bg-color \"#0D1B2A\"\n\n# Configure glass effects\nicon-composer glass ./out/AppIcon.icon --specular --shadow-kind layer-color --blur-material 0.3\n\n# Preview\nicon-composer preview ./out/AppIcon.icon preview.png\n```\n\n### Export for App Store\n\n```bash\n# Marketing icon (flat, no alpha, 1024x1024)\nicon-composer export-marketing ./out/AppIcon.icon marketing.png\n\n# The .icon bundle goes into your Xcode project's asset catalog\n```\n\n### Multi-layer icon with glass\n\n```bash\n# Create base icon\nicon-composer create background.svg ./out --bg-color \"#1C1C2E\"\n\n# Add foreground layers\nicon-composer add-layer ./out/AppIcon.icon glyph.svg --name glyph --opacity 0.8\nicon-composer add-layer ./out/AppIcon.icon badge.svg --name badge --create-group\n\n# Configure glass per group\nicon-composer glass ./out/AppIcon.icon --group-index 0 --specular --blur-material 0.3\nicon-composer glass ./out/AppIcon.icon --group-index 1 --specular --shadow-kind neutral\n\n# Render Liquid Glass\nicon-composer render ./out/AppIcon.icon glass-preview.png\n```\n\n## Limitations\n\n- **Liquid Glass rendering requires macOS** with Apple's Icon Composer.app installed. Flat rendering works everywhere.\n- **ClearLight/ClearDark renditions** render against gray. Apple's glass transparency requires Metal GPU, not available via CLI.\n\n## Architecture\n\n```\nsrc/lib/          Pure library (bundle, manifest, render, ictool)\nsrc/lib/ops-*.ts  Operations layer (MCP result format)\nsrc/cli.ts        CLI (Commander.js, 14 commands)\nsrc/server.ts     MCP server (thin wrapper, 12 tools + 3 prompts)\n```\n\n## Contributing\n\n```bash\n# Install dependencies\nbun install\n\n# Run tests\nbun test              # 175 unit tests\nnpm run test:mcp      # 16 MCP integration tests\n\n# Build\nbun run build\n\n# Visual test gallery\nbun src/cli.ts visual-test --out ./gallery\n```\n",
  "bytes": 27581,
  "sha": "39fd368a0b84d1e8c26d8fcde7aba7bcf54811e6e04eb3fcef06d762536ae162",
  "repo_slug": "ethbak/icon-composer-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ethbak_icon_composer_mcp_5bc87b65/readme"
}