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.