ethbak/icon-composer-mcp

42 stars 0 forks 质量 90 趋势 90

CLI and MCP server for creating images, icons, and logos with Liquid Glass effects (iOS 26+). Not affiliated with Apple .

概览

CLI and MCP server for creating images, icons, and logos with Liquid Glass effects (iOS 26+). Not affiliated with Apple .

README

Icon Composer MCP

CLI and MCP server for creating images, icons, and logos with Liquid Glass effects (iOS 26+). Not affiliated with Apple .

Demo

Key Features

Create .icon bundles programmatically from PNG or SVG glyphs
Full Liquid Glass support: specular highlights, blur material, shadows, translucency
Dark mode + appearance variants with per-appearance fill specializations
AI-agent ready: 12 MCP tools + 3 workflow prompts with built-in instructions

Installation

How It Works

Provide a glyph — any PNG or SVG logo/image
Create a .icon bundle — sets background fill, layer scale, and glass effects
Apple’s ictool renders Liquid Glass — specular highlights, shadows, depth, and translucency
Export — preview PNGs, App Store marketing icon, or the .icon bundle for Xcode

Requirements

Node.js 18+
macOS with Icon Composer for Liquid Glass rendering
```
brew install --cask icon-composer
```
Flat previews, bundle creation/editing, and marketing export work on any platform without Icon Composer

Run icon-composer doctor to check your setup.

CLI Commands

Command	Description
`create`	Create a new `.icon` bundle from a foreground image
`add-layer`	Add a layer to an existing bundle
`remove`	Remove a layer or group
`inspect`	Read and display bundle contents
`glass`	Configure Liquid Glass effects on a group
`appearance`	Set dark/tinted mode overrides
`fill`	Set background fill (solid, gradient, automatic, none)
`position`	Set layer/group scale and offset
`fx`	Toggle all glass effects on/off
`preview`	Export a preview PNG (Liquid Glass or flat)
`render`	Render pixel-perfect Liquid Glass via ictool
`export-marketing`	Export flat 1024x1024 PNG for App Store Connect (no alpha)
`doctor`	Check system setup and dependencies

Details

MCP Tools

Tool	Description
`create_icon`	Create a `.icon` bundle from a foreground image and background color
`add_layer_to_icon`	Add a new layer to an existing bundle
`remove_layer`	Remove a layer or group, optionally clean up assets
`read_icon`	Inspect bundle manifest and assets
`set_glass_effects`	Configure specular, blur, shadow, translucency
`set_appearances`	Set dark/tinted mode overrides
`set_fill`	Set background fill
`set_layer_position`	Adjust layer scale and offset
`toggle_fx`	Enable/disable all glass effects at once
`export_preview`	Render a preview PNG
`render_liquid_glass`	Render via Apple’s ictool (requires Icon Composer)
`export_marketing`	Export flat opaque PNG for App Store Connect

All tools return { content: [{ type: "text", text: "..." }], isError?: true }.

Details

MCP Prompts

Prompt	Parameters	Description
`create-app-icon`	`image_path`, `output_dir`, `brand_color`, `dark_color?`	Guided workflow: create icon from a logo, preview, iterate, export
`add-dark-mode`	`bundle_path`, `dark_color`	Add dark mode to an existing icon with before/after preview
`export-for-app-store`	`bundle_path`, `output_dir`	Export marketing PNG + preview for App Store submission

Example Workflows

Create a branded icon

# Create with brand color
icon-composer create logo.svg ./out --bg-color "#0A66C2"

# Add dark mode
icon-composer appearance ./out/AppIcon.icon --target fill --appearance dark --bg-color "#0D1B2A"

# Configure glass effects
icon-composer glass ./out/AppIcon.icon --specular --shadow-kind layer-color --blur-material 0.3

# Preview
icon-composer preview ./out/AppIcon.icon preview.png

Export for App Store

# Marketing icon (flat, no alpha, 1024x1024)
icon-composer export-marketing ./out/AppIcon.icon marketing.png

# The .icon bundle goes into your Xcode project's asset catalog

Multi-layer icon with glass

# Create base icon
icon-composer create background.svg ./out --bg-color "#1C1C2E"

# Add foreground layers
icon-composer add-layer ./out/AppIcon.icon glyph.svg --name glyph --opacity 0.8
icon-composer add-layer ./out/AppIcon.icon badge.svg --name badge --create-group

# Configure glass per group
icon-composer glass ./out/AppIcon.icon --group-index 0 --specular --blur-material 0.3
icon-composer glass ./out/AppIcon.icon --group-index 1 --specular --shadow-kind neutral

# Render Liquid Glass
icon-composer render ./out/AppIcon.icon glass-preview.png

Limitations

Liquid Glass rendering requires macOS with Apple’s Icon Composer.app installed. Flat rendering works everywhere.
ClearLight/ClearDark renditions render against gray. Apple’s glass transparency requires Metal GPU, not available via CLI.

Architecture

src/lib/          Pure library (bundle, manifest, render, ictool)
src/lib/ops-*.ts  Operations layer (MCP result format)
src/cli.ts        CLI (Commander.js, 14 commands)
src/server.ts     MCP server (thin wrapper, 12 tools + 3 prompts)

Contributing

# Install dependencies
bun install

# Run tests
bun test              # 175 unit tests
npm run test:mcp      # 16 MCP integration tests

# Build
bun run build

# Visual test gallery
bun src/cli.ts visual-test --out ./gallery

View this README on GitHub

安装

npx -y icon-composer-mcp

配置

{
  "mcpServers": {
    "icon-composer": {
      "command": "npx",
      "args": ["-y", "icon-composer-mcp"]
    }
  }
}