stitch-mcp-cli

# stitch-mcp CLI > Skill by [ara.so](https://ara.so) — MCP Skills collection. ## Overview `stitch-mcp` is a CLI tool that bridges Google's Stitch AI-generated UI design platform with local development workflows. It enables you to: - Preview all screens from a Stitch project on a local dev server - Generate deployable Astro sites by mapping screens to routes - Proxy Stitch MCP tools to coding agents with automatic token refresh - Browse and explore design data interactively in the terminal - Invoke MCP tools directly from the command line The tool handles authentication, fetching HTML/CSS designs via the Stitch API, and structuring them for development or agent consumption. ## Installation **Run directly with npx (no installation needed):** ```bash npx @_davideast/stitch-mcp <command> ``` **Or install globally:** ```bash npm install -g @_davideast/stitch-mcp ``` ## Quick Start ### 1. Initialize Authentication The `init` command sets up gcloud SDK, OAuth, and MCP client configuration: ```bash npx @_davideast/stitch-mcp init ``` This wizard will: - Install an isolated gcloud SDK (if needed) - Guide you through OAuth authentication - Enable the Stitch API on your project - Generate MCP client configuration ### 2. Verify Setup ```bash npx @_davideast/stitch-mcp doctor ``` Use `--verbose` flag for detailed diagnostics: ```bash npx @_davideast/stitch-mcp doctor --verbose ``` ### 3. Preview Designs Locally Serve all screens from a project on a Vite dev server: ```bash npx @_davideast/stitch-mcp serve -p <project-id> ``` This starts a local server (default: http://localhost:5173) with all project screens accessible. ### 4. Build an Astro Site Generate a deployable Astro project from Stitch screens: ```bash npx @_davideast/stitch-mcp site -p <project-id> ``` The command will: - Prompt you to map screens to routes (e.g., "/" for home, "/about" for about page) - Fetch HTML/CSS for each screen - Generate a complete Astro project structure - Output to `./stitch-site` directory by default **Specify output directory:** ```bash npx @_davideast/stitch-mcp site -p <project-id> -o ./my-site ``` ## Authentication Methods ### Method 1: Automatic OAuth (Recommended) ```bash npx @_davideast/stitch-mcp init ``` Follow the wizard. Your credentials are stored in `~/.stitch-mcp/`. ### Method 2: API Key Set the API key as an environment variable: ```bash export STITCH_API_KEY="your-api-key" ``` This skips OAuth entirely. ### Method 3: System gcloud If you have gcloud CLI already configured: ```bash gcloud auth application-default login gcloud config set project <PROJECT_ID> gcloud beta services mcp enable stitch.googleapis.com --project=<PROJECT_ID> ``` Then use with `STITCH_USE_SYSTEM_GCLOUD=1`: ```bash STITCH_USE_SYSTEM_GCLOUD=1 npx @_davideast/stitch-mcp serve -p <project-id> ``` ### Logout ```bash npx @_davideast/stitch-mcp logout ``` Force logout and clear all config: ```bash npx @_davideast/stitch-mcp logout --force --clear-config ``` ## MCP Integration ### Configure Your Agent Add this to your MCP client config (e.g., `claude_desktop_config.json`, `.cursor/config.json`): ```json { "mcpServers": { "stitch": { "command": "npx", "args": ["@_davideast/stitch-mcp", "proxy"] } } } ``` **Using API key:** ```json { "mcpServers": { "stitch": { "command": "npx", "args": ["@_davideast/stitch-mcp", "proxy"], "env": { "STITCH_API_KEY": "${STITCH_API_KEY}" } } } } ``` **Using system gcloud:** ```json { "mcpServers": { "stitch": { "command": "npx", "args": ["@_davideast/stitch-mcp", "proxy"], "env": { "STITCH_USE_SYSTEM_GCLOUD": "1" } } } } ``` ### Virtual Tools for Agents The proxy exposes high-level tools that combine multiple API calls: #### `build_site` Builds a site from a project by mapping screens to routes. Returns HTML for each page. **Input schema:** ```typescript { projectId: string; // Required routes: Array<{ screenId: string; // Required route: string; // Required, e.g. "/" or "/about" }>; } ``` **Example usage from CLI:** ```bash npx @_davideast/stitch-mcp tool build_site -d '{ "projectId": "123456", "routes": [ { "screenId": "abc123", "route": "/" }, { "screenId": "def456", "route": "/about" }, { "screenId": "ghi789", "route": "/contact" } ] }' ``` **Prompt for agent:** ``` Use the build_site tool to create a website from my Stitch project 123456. Map screen abc123 to the home page, def456 to /about, and ghi789 to /contact. ``` #### `get_screen_code` Retrieves a screen and downloads its HTML code content. ```bash npx @_davideast/stitch-mcp tool get_screen_code -d '{ "projectId": "123456", "screenId": "abc123" }' ``` #### `get_screen_image` Retrieves a screen and downloads its screenshot image as base64. ```bash npx @_davideast/stitch-mcp tool get_screen_image -d '{ "projectId": "123456", "screenId": "abc123" }' ``` ## Key Commands ### Exploration & Browsing #### View Projects ```bash npx @_davideast/stitch-mcp view --projects ``` Opens an interactive browser listing all your Stitch projects. #### View Specific Project ```bash npx @_davideast/stitch-mcp view --project <project-id> ``` Shows all screens in the project. #### View Specific Screen ```bash npx @_davideast/stitch-mcp view --project <project-id> --screen <screen-id> ``` **Interactive browser controls:** - Arrow keys: navigate - Enter: drill into nested data - `c`: copy selected value to clipboard - `s`: preview HTML in browser - `o`: open project in Stitch - `q`: quit #### Browse Screens in Terminal ```bash npx @_davideast/stitch-mcp screens -p <project-id> ``` Displays an interactive list of all screens with preview and copy actions. ### Tool Invocation #### List All Available Tools ```bash npx @_davideast/stitch-mcp tool ``` #### Show Tool Schema ```bash npx @_davideast/stitch-mcp tool <tool-name> -s ``` Example: ```bash npx @_davideast/stitch-mcp tool build_site -s ``` #### Invoke a Tool ```bash npx @_davideast/stitch-mcp tool <tool-name> -d '<json-data>' ``` Example: ```bash npx @_davideast/stitch-mcp tool get_screen_code -d '{ "projectId": "123456", "screenId": "abc123" }' ``` ### Development Workflow #### Serve Project Locally ```bash npx @_davideast/stitch-mcp serve -p <project-id> ``` **Custom port:** ```bash npx @_davideast/stitch-mcp serve -p <project-id> --port 3000 ``` #### Generate Astro Site ```bash npx @_davideast/stitch-mcp site -p <project-id> ``` **Non-interactive mode with config file:** Create `routes.json`: ```json { "routes": [ { "screenId": "abc123", "route": "/" }, { "screenId": "def456", "route": "/about" } ] } ``` Then run: ```bash npx @_davideast/stitch-mcp site -p <project-id> --config routes.json -o ./output ``` #### Save Screen Snapshot ```bash npx @_davideast/stitch-mcp snapshot -p <project-id> -s <screen-id> -o ./snapshot.html ``` ### MCP Proxy Start the proxy server for agent integration: ```bash npx @_davideast/stitch-mcp proxy ``` **Debug mode (logs to `/tmp/stitch-proxy-debug.log`):** ```bash npx @_davideast/stitch-mcp proxy --debug ``` ## Environment Variables | Variable | Description | |----------|-------------| | `STITCH_API_KEY` | API key for direct authentication (skips OAuth) | | `STITCH_ACCESS_TOKEN` | Pre-existing access token | | `STITCH_USE_SYSTEM_GCLOUD` | Use system gcloud config instead of isolated config | | `STITCH_PROJECT_ID` | Override project ID | | `GOOGLE_CLOUD_PROJECT` | Alternative project ID variable | | `STITCH_HOST` | Custom Stitch API endpoint | ## Common Patterns ### Pattern 1: Preview All Designs Before Building ```bash # 1. Browse available screens npx @_davideast/stitch-mcp screens -p <project-id> # 2. Serve locally to review designs npx @_davideast/stitch-mcp serve -p <project-id> # 3. Build site after confirming screens npx @_davideast/stitch-mcp site -p <project-id> ``` ### Pattern 2: Agent-Driven Site Generation **User prompt to agent:** ``` I have a Stitch project with ID 123456. It has three screens: - Home page (screen ID: abc123) - About page (screen ID: def456) - Contact page (screen ID: ghi789) Use the build_site tool to generate HTML for all three pages with routes /, /about, and /contact. Then help me integrate them into my Next.js project. ``` The agent will use `build_site` and can help integrate the resulting HTML. ### Pattern 3: Iterative Design Review ```bash # View specific screen details npx @_davideast/stitch-mcp view --project <project-id> --screen <screen-id> # Preview in browser (press 's' in interactive view) # Or manually: npx @_davideast/stitch-mcp snapshot -p <project-id> -s <screen-id> -o ./preview.html open ./preview.html # Get the HTML code for integration npx @_davideast/stitch-mcp tool get_screen_code -d '{ "projectId": "<project-id>", "screenId": "<screen-id>" }' ``` ### Pattern 4: Automated Site Builds in CI ```bash #!/bin/bash # ci-build-stitch.sh export STITCH_API_KEY="${STITCH_API_KEY}" PROJECT_ID="123456" # Generate site with predefined routes npx @_davideast/stitch-mcp site -p "$PROJECT_ID" \ --config ./stitch-routes.json \ -o ./dist/stitch-site \ --non-interactive # Deploy the generated site cd ./dist/stitch-site npm install npm run build ``` `stitch-routes.json`: ```json { "routes": [ { "screenId": "home_abc", "route": "/" }, { "screenId": "about_def", "route": "/about" }, { "screenId": "contact_ghi", "route": "/contact" } ] } ```