Stitch MCP CLI

stitch-mcp-cli

CLI + MCP Server para Google Stitch con scaffolding multi-framework

Características

• ⚡ Setup en 30 segundos - Solo necesitas una API key
• 🔐 Seguridad - API key encriptada con AES-256-GCM
• 🎨 Scaffolding universal - Exporta a React, Vue, Svelte, Next.js, y más
• 👀 Watch mode - Sincronización continua cuando cambia el diseño
• 💾 Offline cache - Trabaja sin conexión con proyectos cacheados
• 🔧 Multi-IDE - Configura automáticamente Cursor, Claude Code, VS Code, OpenCode, Antigravity, Codex CLI
• 🧪 Evaluaciones MCP - Benchmark tools para LLMs
• 📡 HTTP + stdio - Dos transportes MCP disponibles
• 🚦 Rate limiting - 60 req/min para evitar bloqueos
• 📝 Logging estructurado - Pino logger con niveles configurables
• ✅ TypeScript strict - Tipado completo y verificado

Quickstart

# 1. Instalar (recomendado con pnpm)
pnpm add -g stitch-mcp-cli

# O con npm
npm install -g stitch-mcp-cli

# O con npx (sin instalar)
npx stitch-mcp-cli auth --api-key TU_API_KEY

# 2. Configurar API key (encriptada automáticamente)
stitch-mcp-cli auth --api-key TU_API_KEY

# 3. Configurar IDEs
stitch-mcp-cli setup

# 4. Listar proyectos
stitch-mcp-cli projects

Obtén tu API key en: https://stitch.withgoogle.com/settings

MCP Server

El CLI también funciona como MCP Server para integrar con AI coding agents:

# Modo stdio (local) - Para IDEs
stitch-mcp-cli mcp

# Modo HTTP (remoto) - Puerto 3100 por defecto
stitch-mcp-cli mcp:http

# Puerto personalizado
MCP_PORT=8080 stitch-mcp-cli mcp:http

# Host personalizado
MCP_HOST=0.0.0.0 MCP_PORT=8080 stitch-mcp-cli mcp:http

Tools disponibles en MCP:

Ejemplo de uso con MCP Inspector

# Inspeccionar servidor MCP
npx @modelcontextprotocol/inspector node dist/index.js

# O conpnpm
pnpm run inspector

Comandos

Auth

# Configurar API key (se encripta automáticamente)
stitch-mcp-cli auth --api-key 

# Verificar configuración
stitch-mcp-cli auth --check

Projects

# Listar todos los proyectos
stitch-mcp-cli projects

# Listar con formato JSON
stitch-mcp-cli projects --json

# Filtrar por nombre
stitch-mcp-cli projects --search "dashboard"

# Modo offline
stitch-mcp-cli projects --offline

Generate

# Generar pantalla desde prompt
stitch-mcp-cli generate "Login form with email and password" --project-id 

# Generar con tipo de dispositivo
stitch-mcp-cli generate "Mobile navigation" --project-id  --device mobile

Sync

# Sync pantalla específica
stitch-mcp-cli sync 
  --output ./src/stitch

# Sync todos los diseños de un proyecto
stitch-mcp-cli sync --project-id  --output ./designs

Export

# Exportar a React
stitch-mcp-cli export 
 --framework react --output ./src/components

# Exportar a Vue
stitch-mcp-cli export 
 --framework vue --output ./src/views

# Exportar a Next.js
stitch-mcp-cli export 
 --framework nextjs --output ./app

# Exportar a Svelte
stitch-mcp-cli export 
 --framework svelte --output ./src/lib

# Exportar a Nuxt
stitch-mcp-cli export 
 --framework nuxt --output ./pages

# Exportar a SolidJS
stitch-mcp-cli export 
 --framework solid --output ./src/components

# Exportar a Angular
stitch-mcp-cli export 
 --framework angular --output ./src/app/components

# Exportar a HTML vanilla
stitch-mcp-cli export 
 --framework vanilla --output ./designs

Frameworks soportados: react, vue, svelte, nextjs, nuxt, solid, angular, vanilla

Eval

Ejecuta evaluaciones MCP para benchmarking de LLMs:

# Ejecutar evaluaciones con archivo por defecto
stitch-mcp-cli eval

# Ejecutar con archivo personalizado
stitch-mcp-cli eval --file ./custom-eval.xml

# Guardar resultados en JSON
stitch-mcp-cli eval --results

El archivo de evaluación debe estar en evaluations/stitch-mcp-eval.xml con formato:

  Lista todos los proyectos
  Lista de proyectos
  list_projects

Design-MD

Extrae el design system del proyecto a un archivo DESIGN.md:

# Generar DESIGN.md con projectId desde caché
stitch-mcp-cli design-md

# Especificar proyecto
stitch-mcp-cli design-md --project-id 

# Personalizar output
stitch-mcp-cli design-md --output ./docs/DESIGN.md

# Sincronizar pantallas también
stitch-mcp-cli design-md --sync

El archivo generado incluye:

• Tema visual y atmósfera
• Paleta de colores con roles
• Reglas de tipografía
• Estilos de componentes
• Principios de layout
• Tokens para generación Stitch

Cache

# Ver estado de caché
stitch-mcp-cli cache --status

# Limpiar caché
stitch-mcp-cli cache --clear

# Sync proyecto a caché
stitch-mcp-cli cache --sync 

Templates Personalizados

Puedes crear templates custom para frameworks sobrescribiendo los defaults:

~/.stitch-mcp-cli/templates/
├── react/
│   └── component.ejs
├── vue/
│   └── component.ejs
├── svelte/
│   └── component.ejs
└── custom-framework/
    └── component.ejs

Variables disponibles en templates EJS:

Ejemplo de template React custom:

import React from 'react';
import styles from './.module.css';

interface Props {
  className?: string;
}

export const : React.FCProps> = ({ className }) => {
  return (
    

      {``}
      
    

  );
};

Configurar directorio de templates

# En ~/.stitch-mcp-cli/config.json
{
  "templateDir": "/path/to/custom/templates"
}

# O con variable de entorno
STITCH_TEMPLATE_DIR=./templates stitch-mcp-cli export 
 --framework react

Configuración de IDEs

Cursor

Archivo: ~/.cursor/mcp.json

{
  "mcpServers": {
    "stitch": {
      "command": "npx",
      "args": ["stitch-mcp-cli"],
      "env": {
        "STITCH_API_KEY": "${STITCH_API_KEY}"
      }
    }
  }
}

Claude Code

claude mcp add stitch -- npx stitch-mcp-cli

O manualmente en ~/.claude/claude_desktop_config.json:

{
  "mcpServers": {
    "stitch": {
      "command": "npx",
      "args": ["stitch-mcp-cli"],
      "env": {
        "STITCH_API_KEY": "${STITCH_API_KEY}"
      }
    }
  }
}

VS Code

Archivo: .vscode/mcp.json o configuración de workspace

{
  "mcpServers": {
    "stitch": {
      "command": "npx",
      "args": ["stitch-mcp-cli"],
      "env": {
        "STITCH_API_KEY": "${STITCH_API_KEY}"
      }
    }
  }
}

OpenCode

Archivo: ~/.config/opencode/opencode.json

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "stitch": {
      "type": "local",
      "command": ["npx", "stitch-mcp-cli"],
      "enabled": true,
      "environment": {
        "STITCH_API_KEY": "${STITCH_API_KEY}"
      }
    }
  }
}

Kilo Code

Archivo: ~/.config/kilo/opencode.json

{
  "$schema": "https://app.kilo.ai/config.json",
  "mcp": {
    "stitch": {
      "type": "local",
      "command": ["npx", "stitch-mcp-cli"],
      "enabled": true,
      "environment": {
        "STITCH_API_KEY": "${STITCH_API_KEY}"
      }
    }
  }
}

Codex CLI

Archivo: ~/.codex/config.toml

[mcp_servers.stitch]
command = "npx"
args = ["stitch-mcp-cli"]
env_vars = { STITCH_API_KEY = "${STITCH_API_KEY}" }

O usando el CLI de Codex:

codex mcp add stitch --env STITCH_API_KEY=$STITCH_API_KEY -- npx stitch-mcp-cli

Antigravity

Archivo: ~/.antigravity/mcp_config.json

{
  "mcpServers": {
    "stitch": {
      "command": "npx",
      "args": ["stitch-mcp-cli"],
      "env": {
        "STITCH_API_KEY": "${STITCH_API_KEY}"
      }
    }
  }
}

Configuración automática

El comando setup detecta y configura automáticamente todos los IDEs instalados:

stitch-mcp-cli setup

# Configurar solo IDEs específicos
stitch-mcp-cli setup --editors cursor,claude,opencode

Desarrollo

# Clonar repositorio
git clone https://github.com/berriosb/stitch-mcp-cli.git
cd stitch-mcp-cli

# Instalar dependencias
pnpm install

# Desarrollo (watch mode)
pnpm dev

# Build
pnpm run build

# Tests
pnpm test

# Typecheck
pnpm run typecheck

# Inspect MCP server
pnpm run inspector

Seguridad

• La API key se encripta con AES-256-GCM y se guarda en ~/.stitch-mcp-cli/config.json
• La clave de encriptación se guarda en ~/.stitch-mcp-cli/.key con permisos 0600
• El SDK usa header X-Goog-Api-Key, no query params
• Añade restricciones a tu API key en Google Cloud Console
• Rate limiting: 60 requests por minuto

Logging

El servidor usa Pino para logging estructurado:

# Nivel de log (default: info)
LOG_LEVEL=debug stitch-mcp-cli mcp

# Ver logs en desarrollo
NODE_ENV=development stitch-mcp-cli mcp

Environment Variables

Changelog

Ver CHANGELOG.md para historial de cambios.

Para generar changelog con conventional commits:

pnpm run changelog

Roadmap

v1.0.0 - Production Ready ✅

• [x] MCP Server propio con 7 tools
• [x] CLI completa con 10 comandos
• [x] API key encriptada (AES-256-GCM)
• [x] Rate limiting (60 req/min)
• [x] Logging estructurado (Pino)
• [x] Graceful shutdown
• [x] HTTP + stdio transports
• [x] TypeScript strict mode
• [x] Zod validation
• [x] 58 tests (unit + integration)
• [x] CI/CD con GitHub Actions

v1.1.0 - Enhanced Features

• [ ] Template engine mejorado
• [ ] Más frameworks (Angular, Solid)
• [ ] Watch mode avanzado

v1.2.0 - Cloud

• [ ] MCP sobre HTTP con autenticación
• [ ] Deploy a cloud functions
• [ ] Multi-user support

Troubleshooting

Error: Cannot find module '@google/stitch-sdk'

# Reinstalar dependencias
pnpm install

# O limpiar caché y reinstalar
rm -rf node_modules pnpm-lock.yaml
pnpm install

Error: better-sqlite3 compila lentamente

better-sqlite3 es una dependencia opcional para caché offline SQLite. Si no compila, el CLI usa automáticamente JSON como fallback.

# Opción 1: Usar pnpm (más rápido)
pnpm install -g stitch-mcp-cli

# Opción 2: Ignorar scripts de compilación
npm install -g stitch-mcp-cli --ignore-scripts

Error: API key inválida

# Verificar configuración
stitch-mcp-cli auth --check

# Reconfigurar API key
stitch-mcp-cli auth --api-key 

Error: EACCES permission denied

# Permisos del directorio de configuración
chmod 700 ~/.stitch-mcp-cli
chmod 600 ~/.stitch-mcp-cli/config.json
chmod 600 ~/.stitch-mcp-cli/.key

MCP Server no aparece en mi IDE

1. Verifica que el binario esté instalado:

which stitch-mcp-cli
# Debe retornar: /usr/local/bin/stitch-mcp-cli o similar

1. Si usas pnpm global, agrega el path:

# Agregar a ~/.bashrc o ~/.zshrc
export PATH="$(pnpm global bin):$PATH"

1. Reinicia el IDE después de configurar

Rate limiting (429 Too Many Requests)

El CLI tiene rate limiting interno de 60 req/min. Si ves este error:

• Espera 1 minuto antes de continuar
• Usa modo offline: stitch-mcp-cli projects --offline
• Aumenta el límite: STITCH_RATE_LIMIT=120 stitch-mcp-cli mcp

Logs de depuración

# Activar logs detallados
LOG_LEVEL=debug stitch-mcp-cli mcp

# Guardar logs en archivo
LOG_LEVEL=debug stitch-mcp-cli mcp 2>&1 | tee stitch.log

Licencia

MIT