# 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](https://stitch.withgoogle.com) 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

```bash
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:

```text
🎨 stitch: ⚠ setup needed
```

Then run:

```text
/stitch-setup
```

## Setup — API Key

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

### Option 1: Environment variable

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

### Option 2: File

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

Or let the package guide you:

```text
/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:

```text
/stitch-status
```

Or validate in-place without restarting:

```text
/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:

```text
/stitch-setup
```

Then either restart pi or run:

```text
/stitch-reload
```

### "Stitch unavailable"

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

```text
/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](./LICENSE) file.

Changes are tracked in [CHANGELOG.md](./CHANGELOG.md).

## Contributing

Found a bug or have a feature request? [Open an issue](https://github.com/zyvralabs/pi-stitch-tools/issues).

---

Built by [zyvra-labs](https://github.com/zyvralabs).