Stitch MCP

Que fait Stitch MCP ?

Aperçu

Google Stitch génère des interfaces utilisateur à partir de prompts et stocke chacune d'elles sous forme de document HTML et d'une capture d'écran. stitch-mcp (package npm @_davideast/stitch-mcp, un projet open-source indépendant) est le pont vers un codebase. Il fait trois choses : il enregistre Stitch comme serveur MCP dans un agent de codage, il ajoute des outils d'aide qui remettent le balisage d'un écran à l'agent en un seul appel, et il peut prévisualiser les écrans ou les exporter en tant que projet Astro. Les faits ci-dessous ont été vérifiés pour la version 0.9.0 ; exécutez toute commande avec --help si un indicateur est rejeté.

Le vrai travail de l'agent commence après la récupération : la sortie de Stitch est une page HTML statique par écran, et le travail consiste à la traduire en composants qui s'intègrent dans le dépôt où elle atterrit.

Instructions

1. Établir le point de départ

Demandez ou recherchez, dans cet ordre :

• Quel client MCP est utilisé (Claude Code, Cursor, VS Code, Codex, OpenCode, Gemini CLI, Antigravity) et si un serveur stitch est déjà enregistré.
• Si l'utilisateur possède une clé API Stitch. Sans clé, la configuration passe par OAuth Google Cloud, qui nécessite un navigateur et un projet avec facturation activée.
• Le projet Stitch et les écrans à implémenter. Un ID de projet est un long nombre tel que 7302915846120394175 ; un ID d'écran est de 32 caractères hexadécimaux. Les noms d'affichage ne sont pas acceptés.
• La pile cible, lue depuis le dépôt : framework, système de style, composants existants et tokens de design. Ne supposez jamais React et Tailwind.

2. Choisir l'authentification

Mode	Comment il est fourni	Quand le choisir
Clé API	STITCH_API_KEY dans l'environnement, un fichier .env, ou le bloc env du serveur MCP	Par défaut. Fonctionne en mode headless, en CI et via SSH ; rien à rafraîchir
OAuth via l'assistant	init télécharge son propre SDK gcloud dans ~/.stitch-mcp/ et se connecte	L'utilisateur n'a pas de clé mais possède un projet Google Cloud
OAuth via gcloud existant	STITCH_USE_SYSTEM_GCLOUD=1 plus les trois commandes ci-dessous	gcloud est déjà installé et connecté

Route gcloud existante, à exécuter par l'utilisateur car elle ouvre un navigateur :

gcloud auth application-default login
gcloud config set project orchard-design-prod
gcloud beta services mcp enable stitch.googleapis.com --project=orchard-design-prod

Sans clé présente, le CLI suppose OAuth. Lors d'un test, doctor sur une machine propre a récupéré environ 500 Mo de SDK gcloud dans ~/.stitch-mcp/ avant de rapporter quoi que ce soit, alors exportez d'abord la clé lorsque la route par clé est prévue.

3. Choisir la connexion

	Proxy via stdio	HTTP direct
Ce que le client démarre	npx @_davideast/stitch-mcp proxy comme processus enfant	Rien ; il appelle https://stitch.googleapis.com/mcp
Outils que l'agent voit	Les outils de Stitch plus les quatre assistants à l'étape 6	Outils de Stitch uniquement
Durée de vie du token OAuth	Renouvelé pour vous par le proxy	Une heure, puis remplacé manuellement
Convient à	Sessions de design-to-code interactives	Pipelines et sandbox qui ne peuvent pas engendrer de processus

Choisissez le proxy sauf s'il y a une raison concrète de ne pas le faire : sans get_screen_code, l'agent doit appeler get_screen, trouver l'URL de téléchargement et récupérer le balisage lui-même.

4. Enregistrer le serveur

Claude Code, proxy avec une clé API prise de l'environnement shell :

claude mcp add stitch -e STITCH_API_KEY="$STITCH_API_KEY" -- npx @_davideast/stitch-mcp proxy

Claude Code, HTTP direct (-s user écrit dans ~/.claude.json, -s project dans ./.mcp.json) :

claude mcp add stitch --transport http https://stitch.googleapis.com/mcp \
  --header "X-Goog-Api-Key: $STITCH_API_KEY" -s user

Cursor (.cursor/mcp.json) et Antigravity partagent une même forme. Cette variante utilise OAuth, donc le fichier ne porte aucun secret et peut être commité en toute sécurité :

{
  "mcpServers": {
    "stitch": {
      "command": "npx",
      "args": ["@_davideast/stitch-mcp", "proxy"],
      "env": { "STITCH_PROJECT_ID": "orchard-design-prod" }
    }
  }
}

Pour la route avec clé API, le bloc env contient STITCH_API_KEY à la place ; gardez ce fichier hors du contrôle de version ou utilisez l'interpolation d'environnement propre au client.

Différences dans les autres clients :

• VS Code (.vscode/mcp.json) : la clé de premier niveau est servers, et chaque entrée nécessite "type": "stdio" (ou "type": "http" avec url et headers).
• Codex (~/.codex/config.toml) : une table [mcp_servers.stitch] avec command = "npx" et args = ["@_davideast/stitch-mcp", "proxy"] ; les variables vont sous [mcp_servers.stitch.env].
• OpenCode (opencode.json) : "mcp": { "stitch": { "type": "local", "command": ["npx", "@_davideast/stitch-mcp", "proxy"], "environment": { } } }.
• Antigravity, mode direct uniquement : le champ est serverUrl, pas url.
• Gemini CLI : gemini extensions install https://github.com/gemini-cli-extensions/stitch.

npx @_davideast/stitch-mcp init écrit la même configuration via des invites. Il accepte -c, --client (claude-code, cursor, vscode, codex, opencode, gemini-cli, antigravity) et -t, --transport (stdio ou http) pour en sauter deux, mais il reste un assistant : confiez-le à l'utilisateur au lieu de l'exécuter depuis un shell d'agent.

Redémarrez le client après toute modification de sa configuration MCP.

5. Vérifier avant de s'y fier

npx @_davideast/stitch-mcp doctor --verbose   # ajoutez --json pour des résultats lisibles par machine
npx @_davideast/stitch-mcp tool               # liste tous les outils que le CLI peut atteindre

doctor vérifie, selon le mode : clé présente, clé acceptée par l'API, gcloud version 400.0.0 ou plus récente, utilisateur connecté, identifiants par défaut de l'application, projet actif, API accessible. Si la liste tool inclut build_site, les outils d'aide sont disponibles.

6. Trouver les écrans et les récupérer

Plusieurs commandes ouvrent une interface utilisateur de terminal et planteront dans un shell d'agent : init, screens, view, et site sans --routes ou l'un de ses indicateurs JSON. Utilisez plutôt celles-ci :

npx @_davideast/stitch-mcp tool list_projects -o json
npx @_davideast/stitch-mcp site -p 7302915846120394175 --list-screens
npx @_davideast/stitch-mcp tool get_screen_code -o json \
  -d '{"projectId":"7302915846120394175","screenId":"c41f0a9e7d2b4c6385a1f09b3e7d5a12"}'

site --list-screens imprime { success, projectId, screens: [{ screenId, title, suggestedRoute, hasHtml }] }. Un écran avec hasHtml: false n'a pas encore de balisage à récupérer.

Outil	Source	Entrée	Ce qui revient
list_projects, get_project	Stitch	aucun / name (projects/ID)	Projets que le compte peut ouvrir
list_screens, get_screen	Stitch	projectId / name (projects/ID/screens/SCREEN_ID)	Métadonnées et URLs de téléchargement, pas le balisage
generate_screen_from_text, edit_screens, generate_variants	Stitch	piloté par prompt	Écrans nouveaux ou modifiés dans le projet
get_screen_code	proxy	projectId, screenId	{ screenId, projectId, htmlContent }
get_screen_image	proxy	projectId, screenId	{ screenId, projectId, imageContent }, la capture d'écran en base64
build_site	proxy	projectId, routes[] de { screenId, route }	{ success, pages: [{ screenId, route, title, html }], message }
list_tools	proxy	aucun	Noms, descriptions et schémas d'entrée

tool NOM -s imprime le schéma d'entrée de n'importe quel outil. -f, --data-file lit le corps JSON depuis un fichier, et -o prend json, pretty (par défaut) ou raw.

7. Transformer le balisage en code du projet

1. Récupérez get_screen_code et get_screen_image pour chaque écran. Le HTML porte des couleurs, espacements et polices exacts ; l'image montre à quoi le résultat devrait ressembler.
2. Inventoriez ce qui se répète sur tous les écrans (navigation, pied de page, boutons, cartes) avant d'écrire un fichier, et mappez chaque élément à un composant existant ou à un nouveau composant partagé.
3. Mappez les valeurs brutes sur les tokens du projet. Une couleur hexadécimale qui correspond à une variable de thème devient la variable ; une valeur isolée reste littérale et est listée dans la note de transfert.
4. Reconstruisez la structure avec des éléments sémantiques, de vrais liens et contrôles de formulaire, et la couche de données du projet à la place du contenu exemple codé en dur.
5. Comparez la page en cours d'exécution avec la capture d'écran à la largeur du design, puis à une largeur de téléphone, et signalez chaque écart délibéré.

Les outils de génération, create_project, delete_project et les outils du système de design modifient le compte Stitch de l'utilisateur. Appelez-les uniquement lorsque l'utilisateur le demande, jamais comme effet secondaire de l'implémentation d'un design.

8. Prévisualiser ou exporter sans agent

Commande	Objectif	Indicateurs utiles
serve -p ID	Serveur Vite local, une URL par écran sous /screens/	--list-screens imprime les chemins en JSON ; --json démarre en mode headless et imprime le JSON une fois le serveur prêt
site -p ID	Écrit un projet Astro à partir d'une map écran-route	-o DIR dossier de sortie ; -r JSON fournit la map et saute l'interface utilisateur ; -e imprime la map comme entrée build_site
upload -p ID -f FICHIER	Ajoute un fichier PNG, JPG, WEBP ou HTML comme nouvel écran	--title
proxy	Le serveur MCP lui-même	--debug journalise dans /tmp/stitch-proxy-debug.log
logout	Révoque la connexion OAuth	--force, --clear-config (demande d'abord à l'utilisateur : cela supprime la configuration gcloud intégrée)

La sortie Astro contient src/layouts/Layout.astro, un fichier par route dans src/pages/, et les actifs téléchargés dans public/assets/ ; elle démarre avec npm install && npm run dev sur le port 4321.

Exemples

Exemple 1 : Implémenter un écran Stitch dans une application Next.js existante

Ilse Brandt maintient une application de réservation (Next.js App Router, Tailwind avec tokens dans tailwind.config.ts). Elle utilise Claude Code, a une clé API Stitch dans son profil shell, et demande : « implémente l'écran Pricing de mon projet Stitch. »

claude mcp add stitch -e STITCH_API_KEY="$STITCH_API_KEY" -- npx @_davideast/stitch-mcp proxy
npx @_davideast/stitch-mcp site -p 7302915846120394175 --list-screens

La liste montre {"screenId":"c41f0a9e7d2b4c6385a1f09b3e7d5a12","title":"Pricing", "suggestedRoute":"/pricing","hasHtml":true}. Après un redémarrage du client, l'agent appelle get_screen_code et get_screen_image avec ces IDs, puis rapporte :

Screen: Pricing (c41f0a9e…5a12) -> app/pricing/page.tsx
Reused:   components/SiteHeader.tsx, components/Button.tsx (variant "primary")
Created:  components/pricing/PlanCard.tsx, components/pricing/BillingToggle.tsx
Tokens:   #1F6F5C -> colors.brand.600; 24px card gap -> gap-6; 44px heading kept as text-[44px]
Changed on purpose: plan prices read from lib/plans.ts instead of the sample figures
Checked:  1440px and 390px against the screenshot; toggle is keyboard-operable

Exemple 2 : Exporter trois écrans en tant que site Astro depuis un shell headless

Tomasz Wrona travaille via SSH sur un hôte de build et veut un site marketing statique à partir d'un projet Stitch sans interface utilisateur de terminal. La clé est déjà exportée dans la session.

npx @_davideast/stitch-mcp site -p 5518204776390142068 --list-screens > screens.json
npx @_davideast/stitch-mcp site -p 5518204776390142068 -o ./harbour-site -r '[
  {"screenId":"0b7e3c915ad84f2e9c6d1a8f4e2b7c30","route":"/"},
  {"screenId":"9a2d6f1c4b8e47a3b5c0e7d19f3a6b48","route":"/services"},
  {"screenId":"e5c81b07d3f24a69a1b4c92d6e0f7a15","route":"/contact"}
]'
cd harbour-site && npm install && npm run build

Résultat : src/pages/index.astro, services.astro et contact.astro enveloppés dans la mise en page partagée, avec images et polices sous public/assets/. L'agent remplace ensuite le balisage d'en-tête et de pied de page dupliqué dans les trois pages par un composant Astro chacun, et note que deux routes peuvent ne pas partager un chemin et qu'un ID d'écran inconnu annule la construction avec les IDs manquants listés.

Directives

• Une réponse « Permission Denied » sous OAuth signifie généralement l'une de ces trois choses : la facturation est désactivée, l'API Stitch n'est pas activée sur le projet, ou le compte ne dispose pas du rôle Propriétaire ou Éditeur. doctor --verbose affiche l'erreur HTTP.
• Deux installations de gcloud sont un piège courant. Celle intégrée conserve les identifiants dans ~/.stitch-mcp/config/ ; se connecter avec le gcloud système ne fait rien pour celle-ci à moins que STITCH_USE_SYSTEM_GCLOUD=1 ne soit défini.
• Autres variables que le CLI lit : STITCH_ACCESS_TOKEN (un token obtenu ailleurs), STITCH_PROJECT_ID ou GOOGLE_CLOUD_PROJECT (remplacement de projet), STITCH_HOST (point de terminaison alternatif).
• Sur WSL, SSH et les conteneurs, le lien OAuth est imprimé au lieu d'être ouvert ; l'utilisateur le copie dans un navigateur. Une clé API évite complètement le problème.
• snapshot rend les propres écrans de terminal du CLI à partir d'un fichier de données pour ses développeurs. Il ne sauvegarde ni ne versionne les designs Stitch ; conservez le HTML récupéré dans le dépôt si un enregistrement est nécessaire.
• Traitez le HTML récupéré comme une référence de design. Le coller textuellement dans une page apporte des styles en ligne, des URLs de polices et d'images distantes, et aucun travail d'accessibilité.
• Épinglez le package (@_davideast/[email protected]) dans la configuration partagée pour que chaque coéquipier et la CI exécutent le même ensemble d'outils ; le projet est expérimental et non affilié à Google.
• Pour la passe de polissage visuel après implémentation, associez cela aux compétences impeccable et frontend-design.
• Ce n'est pas le bon outil lorsque le design vit dans Figma ou en tant qu'image mockup statique, ou lorsque l'utilisateur souhaite un design généré mais non implémenté : dans ce dernier cas, l'interface web de Stitch suffit.