pi-stitch-tools

Google Stitch integration for pi — generate, edit, and manage UI designs directly from your coding session.

What it does

Registers all Google Stitch tools as native pi tools under the stitch_ prefix, so you can:

• List, get, and create Stitch projects
• List and get screens
• Generate screens from text prompts
• Edit existing screens
• Generate design variants
• Create and apply design systems
• Upload DESIGN.md files

Install

pi install npm:@zyvra-labs/pi-stitch-tools

After installation, restart pi or run /reload to activate the tools.

On first run, if the API key is missing, the status bar shows:

🎨 stitch: ⚠ setup needed

Then run:

/stitch-setup

Setup — API Key

You need a Google Stitch API key. Pick one method:

Option 1: Environment variable

export STITCH_API_KEY="your-key-here"
# or
export GOOGLE_STITCH_API_KEY="your-key-here"

Option 2: File

echo "your-key-here" > ~/.pi/stitch-api-key

Or let the package guide you:

/stitch-setup file
/stitch-write-key <your-key>

Option 3: Legacy mcp.json (existing users)

If you already have Stitch configured in ~/.pi/agent/mcp.json with the X-Goog-Api-Key header or --api-key flag, the extension will pick it up automatically.

Once the key is set, restart pi and run:

/stitch-status

Or validate in-place without restarting:

/stitch-reload

If everything is working you'll see the loaded Stitch tools, usage stats, and any active generation cooldowns.

Built-in setup commands

| Command | Usage | |---------|-------| | /stitch-setup | Show setup options and guide the user | | /stitch-setup file | File-based setup flow (~/.pi/stitch-api-key) | | /stitch-setup env | Show env-var based setup | | /stitch-setup legacy | Show mcp.json legacy setup | | /stitch-write-key <key> | Save and validate a key immediately | | /stitch-reload | Re-read and validate the key without restarting Pi |

Usage

All tools follow the stitch_<upstream-name> convention. Examples:

# List your projects
stitch_list_projects

# Get project details
stitch_get_project name=projects/14082150201392761251

# List screens in a project
stitch_list_screens projectId=14082150201392761251

# Generate a screen from text
stitch_generate_screen_from_text projectId=14082150201392761251 prompt="A login page with email and password fields"

# Create a design system
stitch_create_design_system projectId=14082150201392761251 designSystem='{"displayName":"My Theme","theme":{...}}'

Pro tip: In pi, you don't need to construct the JSON by hand. Just describe what you want in natural language and pi will call the right tool with the right parameters.

Convenience commands

Quick-access slash commands for common operations:

| Command | Usage | |---------|-------| | /stitch-status | Show loaded tools, usage stats, active cooldowns, or setup diagnostics | | /stitch-projects | List your Stitch projects | | /stitch-new-screen <id> <prompt> | Generate a screen from a description | | /stitch-theme <id> | List design systems for a project | | /stitch-help | Show all available Stitch commands |

Dynamic skills

Version 0.4.0 adds a dynamic Stitch skill layer that enriches generation prompts with production UI guidance before calling Stitch, plus opt-in style stacks, presets, minimal status bar states, and guided API-key onboarding. Skills help avoid flat/generic screens by adding standards for visual hierarchy, realistic content, spacing, states, accessibility, and domain-specific UX.

Bundled dynamic skills:

| Skill | Category | Default | Focus | |-------|----------|---------|-------| | generate-screen | 🧱 foundation | on | Base production UI standard for all generated screens | | design-system | 🧱 foundation | on | Brand-ready themes, semantic tokens, typography, spacing, contrast | | mobile-app | 🎯 domain | off | Mobile-first patterns, safe areas, touch targets, keyboard and offline states | | dashboard | 🎯 domain | off | KPI hierarchy, accessible charts, filters, responsive data layouts | | ecommerce | 🎯 domain | off | Product hierarchy, trust signals, cart UX, checkout and conversion patterns | | style-glassmorphism | 🎨 style | off | Translucent surfaces, backdrop blur, soft borders, layered glass | | style-brutalist | 🎨 style | off | Raw typography, thick borders, off-grid layouts, anti-corporate | | style-editorial | 🎨 style | off | Magazine-grade typography, generous grids, storytelling rhythm | | style-minimal-swiss | 🎨 style | off | Maximum white space, geometric sans, restrained palette |

Only foundation skills are on by default. Domain and style skills activate on demand to keep prompts focused. Smart activation caps at 3 skills per prompt and deduplicates overlapping guidance.

Skill management commands:

| Command | Usage | |---------|-------| | /stitch-skill list | List all skills grouped by category | | /stitch-skill preview <name> | Show what a skill injects into prompts | | /stitch-skill enable <name> | Enable a skill | | /stitch-skill disable <name> | Disable a skill | | /stitch-skill toggle <name> | Toggle a skill on/off | | /stitch-skill recommend | Suggest skills that match your last prompt | | /stitch-skill preset list | List available skill presets | | /stitch-skill preset apply <name> | Apply a preset (enable/disable a group of skills) | | /stitch-skill stats | Show skill usage statistics |

Bundled presets:

| Preset | Enables | Disables | |--------|---------|----------| | mobile-saas | generate-screen, design-system, mobile-app | — | | ecommerce | generate-screen, design-system, ecommerce, mobile-app | — | | admin-panel | generate-screen, design-system, dashboard | mobile-app, ecommerce | | brand-landing | generate-screen, design-system | mobile-app, dashboard, ecommerce |

Prompt enhancement is applied to stitch_generate_screen_from_text, stitch_edit_screens, and stitch_generate_variants. The original user request is preserved and appended after the skill standards.

Available tools

The extension registers all tools advertised by the upstream Stitch MCP server. Run /stitch-status to see the full list.

Common tools include:

| Tool | Description | |------|-------------| | stitch_list_projects | List your Stitch projects | | stitch_get_project | Get project details | | stitch_create_project | Create a new project | | stitch_list_screens | List screens in a project | | stitch_get_screen | Get screen details | | stitch_generate_screen_from_text | Generate a screen from a text prompt | | stitch_edit_screens | Edit existing screens | | stitch_generate_variants | Generate design variants | | stitch_create_design_system | Create a design system | | stitch_update_design_system | Update a design system | | stitch_apply_design_system | Apply a design system to screens | | stitch_list_design_systems | List design systems | | stitch_upload_design_md | Upload a DESIGN.md file | | stitch_create_design_system_from_design_md | Create design system from DESIGN.md |

When to use this package

✅ Use @zyvra-labs/pi-stitch-tools if:

• You want to use Google Stitch from Pi without manually configuring an MCP client
• You need Stitch tools available as native Pi slash commands (/stitch-status, /stitch-projects)
• You want automatic tool discovery — new Stitch tools appear without updating the package
• You prefer a plug-and-play experience: install, set your key, and go

❌ Consider a generic MCP adapter instead if:

• You need to connect many different MCP servers under full custom configuration
• You require fine-grained control over MCP transport, auth, and tool filtering
• You already have an existing MCP workflow and want Stitch as one server among many

Troubleshooting

"API key not found"

The extension cannot find your Stitch API key. Set one of:

• STITCH_API_KEY environment variable
• GOOGLE_STITCH_API_KEY environment variable
• ~/.pi/stitch-api-key file (plain text, key only)

Or simply run:

/stitch-setup

Then either restart pi or run:

/stitch-reload

"Stitch unavailable"

The extension could not reach the Stitch API server, or the key was invalid. Run:

/stitch-status

The diagnostic will tell you whether the problem is:

• missing key
• invalid/expired key (401)
• permissions (403)
• network/proxy/firewall timeout

Tools don't show up

Run /stitch-status to check. If tools show as loaded but you can't use them, try restarting pi.

How it works

The extension connects directly to the Google Stitch MCP endpoint (stitch.googleapis.com/mcp) over HTTP. It registers tools dynamically based on the upstream server's tools/list response, so you always have the latest tools without updating the package.

Key design decisions:

• No MCP dependency: Calls the Stitch MCP endpoint directly over HTTP from the extension.
• Dynamic registration: Tools are registered from tools/list, not hardcoded. New Stitch tools appear automatically.
• Dynamic skills: Production UI standards are loaded from skills/definitions/*.yaml and can be enabled/disabled at runtime.
• Minimal dependencies: Only uses Node.js built-ins (fs/promises, os, path). No npm dependencies needed.

License

MIT — see LICENSE file.

Changes are tracked in CHANGELOG.md.

Contributing

Found a bug or have a feature request? Open an issue.

Built by zyvra-labs.