IconGen

SVG icon generation system that turns text prompts into clean, optimized SVG icons using Stable Diffusion 1.5 + VTracer vectorization. Exposed as a FastAPI service and as MCP tools so LLMs can call it directly.

Architecture

text prompt
     │
     ▼
┌─────────────────────────────────────────────┐
│            MCP Server (icongen_mcp/)         │
│  generate_svg_icon / batch_generate_svg_icons│
└─────────────────────┬───────────────────────┘
                      │ HTTP
                      ▼
┌─────────────────────────────────────────────┐
│          FastAPI Service (svg-generator/)    │
│                                             │
│  prompt_builder → SD 1.5 FP16 → cleanup     │
│  → VTracer (PNG→SVG) → recolor → SVGO       │
│  → cairosvg (multi-size PNGs) → metadata    │
└─────────────────────────────────────────────┘

Key design decisions:

• color_palette is the source of truth for icon colors — SD generates monochrome shapes, colors are applied post-vectorization
• Model loads once at startup and stays warm — never reloaded per request
• All file writes go through safe_resolve() — path traversal is impossible
• Transparent background throughout the entire pipeline

Repository Layout

svg-generator/          FastAPI service + MCP client
  app/                  Core pipeline modules
    main.py             4 endpoints: /health /profiles /generate-svg /batch-generate-svg
    config.py           All settings (ICONGEN_* env vars)
    backends/           ModelBackend interface + SD 1.5 Diffusers implementation
    prompt_builder.py   Profile prefix/suffix assembly
    image_cleanup.py    Grayscale → threshold → despeckle → transparent RGBA
    recolor.py          color_palette → SVG fill colors
    vectorize.py        VTracer PNG→SVG + SVGO optimize
    raster_export.py    SVG → multi-size transparent PNGs (cairosvg)
    asset_store.py      Sandboxed writes + reproducibility metadata
    safety.py           safe_resolve() path guard
  profiles/             Style presets: flat-icon, filled-icon, outline-icon
  icongen_mcp/          MCP server wrapper
    server.py           Two MCP tools
    client.py           Async HTTP client for the FastAPI service
  scripts/
    download_model.py   One-time model prefetch (~4 GB, no HF login)
    test_generate.py    Live smoke test
  tests/                Unit tests (30 passing)
docs/superpowers/plans/ Implementation plans

Requirements

• Linux (Ubuntu 22.04+ recommended)
• NVIDIA GPU — RTX 3050 8 GB VRAM or better, CUDA 11.8+
• Python 3.10+
• Node.js 18+ (for SVGO)

Quick Start

cd svg-generator

# 1. System packages (Ubuntu/Debian)
sudo apt-get install -y libcairo2-dev libpango1.0-dev libgdk-pixbuf2.0-dev libffi-dev

# 2. Python dependencies
pip install -r requirements.txt

# 3. Node dependencies (SVGO)
npm install

# 4. Prefetch model — one time, ~4 GB, no Hugging Face login required
python scripts/download_model.py

# 5. Create output directories
mkdir -p outputs/svg outputs/png outputs/metadata

# 6. Start the service
uvicorn app.main:app --host 127.0.0.1 --port 8000

Using the MCP Server

With the FastAPI service running, start the MCP server in a second terminal:

cd svg-generator
python -m icongen_mcp.server

See svg-generator/icongen_mcp/README.md for Claude Desktop / Claude Code registration.

Detailed Docs

• svg-generator/README.md — API endpoints, curl examples, environment variables
• svg-generator/icongen_mcp/README.md — MCP server setup, registration JSON, example tool calls

Running Tests

cd svg-generator
python -m pytest tests/ -v

30 tests, all passing. Covers path safety, recoloring, prompt building, and image cleanup.