Was macht Stitch MCP?
Überblick
Google Stitch generiert UI-Screens aus Prompts und speichert jeden als HTML-Dokument plus Screenshot. stitch-mcp (npm-Paket @_davideast/stitch-mcp, ein unabhängiges Open-Source-Projekt) ist die Brücke zu einer Codebasis. Es übernimmt drei Aufgaben: Es registriert Stitch als MCP-Server in einem Coding-Agenten, es fügt Hilfswerkzeuge hinzu, die dem Agenten das Markup eines Screens in einem einzigen Aufruf übergeben, und es kann Screens als Vorschau anzeigen oder als Astro-Projekt exportieren. Die folgenden Fakten wurden mit Version 0.9.0 überprüft; führen Sie jeden Befehl mit --help aus, falls ein Flag abgelehnt wird.
Die eigentliche Arbeit des Agenten beginnt nach dem Abruf: Die Stitch-Ausgabe ist eine statische HTML-Seite pro Screen, und die Aufgabe besteht darin, sie in Komponenten zu übersetzen, die in das Repository passen.
Anleitung
1. Ausgangspunkt ermitteln
Fragen Sie oder schlagen Sie in dieser Reihenfolge nach:
- Welcher MCP-Client verwendet wird (Claude Code, Cursor, VS Code, Codex, OpenCode, Gemini CLI, Antigravity) und ob ein
stitch-Server bereits registriert ist. - Ob der Benutzer einen Stitch-API-Key hat. Ohne diesen erfolgt die Einrichtung über Google Cloud OAuth, was einen Browser und ein Projekt mit aktivierter Abrechnung erfordert.
- Das Stitch-Projekt und die zu implementierenden Screens. Eine Projekt-ID ist eine lange Zahl wie
7302915846120394175; eine Screen-ID besteht aus 32 Hexadezimalzeichen. Anzeigenamen werden nicht akzeptiert. - Den Ziel-Stack, aus dem Repository ausgelesen: Framework, Styling-System, vorhandene Komponenten und Design-Tokens. Gehen Sie niemals von React und Tailwind aus.
2. Authentifizierung wählen
| Modus | Wie wird er bereitgestellt? | Wählen Sie ihn, wenn… |
|---|---|---|
| API-Key | STITCH_API_KEY in der Umgebung, einer .env-Datei oder dem env-Block des MCP-Servers | Standard. Funktioniert headless, in CI und über SSH; nichts muss erneuert werden |
| OAuth via Assistent | init lädt ein eigenes gcloud-SDK in ~/.stitch-mcp/ herunter und meldet sich an | Der Benutzer hat keinen Key, besitzt aber ein Google Cloud-Projekt |
| OAuth via vorhandenem gcloud | STITCH_USE_SYSTEM_GCLOUD=1 plus die drei Befehle unten | gcloud ist bereits installiert und angemeldet |
Vorhandene gcloud-Route, die vom Benutzer ausgeführt werden muss, da sie einen Browser öffnet:
gcloud auth application-default login
gcloud config set project orchard-design-prod
gcloud beta services mcp enable stitch.googleapis.com --project=orchard-design-prod
Ohne vorhandenen Key nimmt die CLI OAuth an. Bei einem Probelauf hat doctor auf einer sauberen Maschine etwa 500 MB des gcloud-SDKs in ~/.stitch-mcp/ heruntergeladen, bevor es etwas meldete. Exportieren Sie daher zuerst den Key, wenn die Key-Route beabsichtigt ist.
3. Verbindung wählen
| Proxy über stdio | Direktes HTTP | |
|---|---|---|
| Was der Client startet | npx @_davideast/stitch-mcp proxy als Kindprozess | Nichts; er ruft https://stitch.googleapis.com/mcp auf |
| Werkzeuge, die der Agent sieht | Stitchs eigene Werkzeuge plus die vier Hilfswerkzeuge aus Schritt 6 | Nur Stitchs eigene Werkzeuge |
| OAuth-Token-Lebensdauer | Vom Proxy für Sie erneuert | Eine Stunde, dann von Hand ersetzt |
| Passt zu | Interaktiven Design-zu-Code-Sitzungen | Pipelines und Sandboxen, die keine Prozesse starten können |
Wählen Sie den Proxy, es sei denn, es gibt einen konkreten Grund dagegen: Ohne get_screen_code muss der Agent get_screen aufrufen, die Download-URL finden und das Markup selbst abrufen.
4. Server registrieren
Claude Code, Proxy mit einem API-Key aus der Shell-Umgebung:
claude mcp add stitch -e STITCH_API_KEY="$STITCH_API_KEY" -- npx @_davideast/stitch-mcp proxy
Claude Code, direktes HTTP (-s user schreibt in ~/.claude.json, -s project in ./.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) und Antigravity teilen sich eine Form. Diese Variante verwendet OAuth, sodass die Datei kein Geheimnis enthält und sicher eingecheckt werden kann:
{
"mcpServers": {
"stitch": {
"command": "npx",
"args": ["@_davideast/stitch-mcp", "proxy"],
"env": { "STITCH_PROJECT_ID": "orchard-design-prod" }
}
}
}
Für die API-Key-Route enthält der env-Block stattdessen STITCH_API_KEY; halten Sie diese Datei aus der Versionskontrolle heraus oder verwenden Sie die Umgebungsinterpolation des Clients.
Unterschiede bei anderen Clients:
- VS Code (
.vscode/mcp.json): Der Top-Level-Schlüssel istservers, und jeder Eintrag benötigt"type": "stdio"(oder"type": "http"miturlundheaders). - Codex (
~/.codex/config.toml): Eine Tabelle[mcp_servers.stitch]mitcommand = "npx"undargs = ["@_davideast/stitch-mcp", "proxy"]; Variablen stehen unter[mcp_servers.stitch.env]. - OpenCode (
opencode.json):"mcp": { "stitch": { "type": "local", "command": ["npx", "@_davideast/stitch-mcp", "proxy"], "environment": { } } }. - Antigravity, nur Direktmodus: Das Feld heißt
serverUrl, nichturl. - Gemini CLI:
gemini extensions install https://github.com/gemini-cli-extensions/stitch.
npx @_davideast/stitch-mcp init schreibt dieselbe Konfiguration über Eingabeaufforderungen. Es akzeptiert -c, --client (claude-code, cursor, vscode, codex, opencode, gemini-cli, antigravity) und -t, --transport (stdio oder http), um zwei davon zu überspringen, bleibt aber ein Assistent: Übergeben Sie es dem Benutzer, anstatt es von einer Agenten-Shell aus auszuführen.
Starten Sie den Client nach jeder Änderung seiner MCP-Konfiguration neu.
5. Überprüfung vor der Verwendung
npx @_davideast/stitch-mcp doctor --verbose # --json für maschinenlesbare Ergebnisse hinzufügen
npx @_davideast/stitch-mcp tool # listet alle Werkzeuge auf, die die CLI erreichen kann
doctor überprüft je nach Modus: Key vorhanden, Key von der API akzeptiert, gcloud 400.0.0 oder neuer, Benutzer angemeldet, Standardanmeldedaten der Anwendung, aktives Projekt, API erreichbar. Wenn die tool-Auflistung build_site enthält, sind die Hilfswerkzeuge verfügbar.
6. Screens finden und abrufen
Mehrere Befehle öffnen eine Terminal-UI und bleiben in einer Agenten-Shell hängen: init, screens, view und site ohne --routes oder einen seiner JSON-Flags. Verwenden Sie stattdessen diese:
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 gibt { success, projectId, screens: [{ screenId, title, suggestedRoute, hasHtml }] } aus. Ein Screen mit hasHtml: false hat noch kein abrufbares Markup.
| Werkzeug | Quelle | Eingabe | Rückgabewert |
|---|---|---|---|
list_projects, get_project | Stitch | keine / name (projects/ID) | Projekte, die das Konto öffnen kann |
list_screens, get_screen | Stitch | projectId / name (projects/ID/screens/SCREEN_ID) | Metadaten und Download-URLs, kein Markup |
generate_screen_from_text, edit_screens, generate_variants | Stitch | promptgesteuert | Neue oder geänderte Screens im Projekt |
get_screen_code | Proxy | projectId, screenId | { screenId, projectId, htmlContent } |
get_screen_image | Proxy | projectId, screenId | { screenId, projectId, imageContent }, der Screenshot als base64 |
build_site | Proxy | projectId, routes[] von { screenId, route } | { success, pages: [{ screenId, route, title, html }], message } |
list_tools | Proxy | keine | Namen, Beschreibungen und Eingabeschemata |
tool NAME -s gibt das Eingabeschema jedes Werkzeugs aus. -f, --data-file liest den JSON-Body aus einer Datei, und -o akzeptiert json, pretty (Standard) oder raw.
7. Markup in Projektcode umwandeln
- Rufen Sie
get_screen_codeundget_screen_imagefür jeden Screen ab. Das HTML enthält exakte Farben, Abstände und Schriftfamilien; das Bild zeigt, wie das Ergebnis aussehen soll. - Inventarisieren Sie, was screensübergreifend wiederholt wird (Navigation, Footer, Buttons, Karten), bevor Sie eine Datei schreiben, und ordnen Sie jedes einem vorhandenen oder einem neuen gemeinsamen Bestandteil zu.
- Ordnen Sie Rohwerte den Projekt-Tokens zu. Ein Hex-Farbwert, der einer Theme-Variable entspricht, wird zur Variable; ein einmaliger Wert bleibt literal und wird im Übergabevermerk aufgeführt.
- Bauen Sie die Struktur mit semantischen Elementen, echten Links und Formularsteuerelementen sowie der Datenebene des Projekts anstelle von hartcodierten Beispielinhalten neu auf.
- Vergleichen Sie die laufende Seite mit dem Screenshot in der Designbreite, dann in einer Telefonbreite, und melden Sie jede bewusste Abweichung.
Die generierenden Werkzeuge create_project, delete_project und die Designsystem-Werkzeuge ändern das Stitch-Konto des Benutzers. Rufen Sie sie nur auf, wenn der Benutzer dies ausdrücklich verlangt, niemals als Nebeneffekt der Implementierung eines Designs.
8. Vorschau oder Export ohne Agenten
| Befehl | Zweck | Wissenswerte Flags |
|---|---|---|
serve -p ID | Lokaler Vite-Server, eine URL pro Screen unter /screens/ | --list-screens gibt Pfade als JSON aus; --json startet headless und gibt JSON aus, sobald der Server bereit ist |
site -p ID | Schreibt ein Astro-Projekt aus einer Screen-zu-Route-Zuordnung | -o DIR Ausgabeverzeichnis; -r JSON liefert die Zuordnung und überspringt die UI; -e gibt die Zuordnung als build_site-Eingabe aus |
upload -p ID -f DATEI | Fügt eine PNG-, JPG-, WEBP- oder HTML-Datei als neuen Screen hinzu | --title |
proxy | Der MCP-Server selbst | --debug protokolliert nach /tmp/stitch-proxy-debug.log |
logout | Widerruft die OAuth-Anmeldung | --force, --clear-config (fragt zuerst den Benutzer: Es löscht die gebündelte gcloud-Konfiguration) |
Die Astro-Ausgabe enthält src/layouts/Layout.astro, eine Datei pro Route in src/pages/ und heruntergeladene Assets in public/assets/; sie startet mit npm install && npm run dev auf Port 4321.
Beispiele
Beispiel 1: Einen Stitch-Screen in einer bestehenden Next.js-App implementieren
Ilse Brandt betreut eine Buchungs-App (Next.js App Router, Tailwind mit Tokens in tailwind.config.ts). Sie verwendet Claude Code, hat einen Stitch-API-Key in ihrem Shell-Profil und fragt: "Implementiere den Pricing-Screen aus meinem Stitch-Projekt."
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
Die Auflistung zeigt {"screenId":"c41f0a9e7d2b4c6385a1f09b3e7d5a12","title":"Pricing","suggestedRoute":"/pricing","hasHtml":true}. Nach einem Client-Neustart ruft der Agent get_screen_code und get_screen_image mit diesen IDs auf und meldet dann:
Screen: Pricing (c41f0a9e…5a12) -> app/pricing/page.tsx
Wiederverwendet: components/SiteHeader.tsx, components/Button.tsx (Variante "primary")
Erstellt: components/pricing/PlanCard.tsx, components/pricing/BillingToggle.tsx
Tokens: #1F6F5C -> colors.brand.600; 24px Kartenabstand -> gap-6; 44px Überschrift beibehalten als text-[44px]
Absichtlich geändert: Preise aus lib/plans.ts statt aus den Beispielwerten
Geprüft: 1440px und 390px gegen den Screenshot; Umschalter ist tastaturbedienbar
Beispiel 2: Drei Screens als Astro-Site aus einer headless Shell exportieren
Tomasz Wrona arbeitet über SSH auf einem Build-Server und möchte eine statische Marketing-Site aus einem Stitch-Projekt ohne Terminal-UI. Der Key ist bereits in der Sitzung exportiert.
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
Ergebnis: src/pages/index.astro, services.astro und contact.astro im gemeinsam genutzten Layout, mit Bildern und Schriftarten unter public/assets/. Der Agent ersetzt dann das duplizierte Header- und Footer-Markup in den drei Seiten durch jeweils eine Astro-Komponente und stellt fest, dass zwei Routen sich keinen Pfad teilen dürfen und eine unbekannte Screen-ID den Build mit einer Liste der fehlenden IDs abbricht.
Richtlinien
- Eine "Permission Denied"-Antwort unter OAuth bedeutet normalerweise eines von drei Dingen: Die Abrechnung ist deaktiviert, die Stitch-API ist nicht im Projekt aktiviert, oder das Konto hat nicht die Rolle "Owner" oder "Editor".
doctor --verbosezeigt den HTTP-Fehler. - Zwei gcloud-Installationen sind eine häufige Falle. Die gebündelte Version speichert Anmeldedaten in
~/.stitch-mcp/config/; eine Anmeldung mit dem systemweiten gcloud ändert daran nichts, es sei denn,STITCH_USE_SYSTEM_GCLOUD=1ist gesetzt. - Andere Variablen, die die CLI liest:
STITCH_ACCESS_TOKEN(ein anderweitig bezogener Token),STITCH_PROJECT_IDoderGOOGLE_CLOUD_PROJECT(Projektüberschreibung),STITCH_HOST(alternativer Endpunkt). - Unter WSL, SSH und in Containern wird der OAuth-Link ausgegeben statt geöffnet; der Benutzer kopiert ihn in einen Browser. Ein API-Key vermeidet das Problem vollständig.
snapshotrendert die eigenen Terminal-Screens der CLI aus einer Datendatei für ihre Entwickler. Es speichert oder versioniert keine Stitch-Designs; bewahren Sie abgerufenes HTML im Repository auf, falls eine Aufzeichnung benötigt wird.- Behandeln Sie abgerufenes HTML als Design-Referenz. Das Einfügen in eine Seite bringt Inline-Styles, entfernte Schrift- und Bild-URLs und keine Barrierefreiheitsarbeit mit sich.
- Fixieren Sie das Paket (
@_davideast/[email protected]) in der gemeinsamen Konfiguration, damit alle Teammitglieder und die CI denselben Werkzeugsatz verwenden; das Projekt ist experimentell und nicht mit Google verbunden. - Kombinieren Sie dies für den finalen visuellen Feinschliff nach der Implementierung mit den Skills
impeccableundfrontend-design. - Nicht das richtige Werkzeug, wenn das Design in Figma oder als statisches Mockup-Bild vorliegt, oder wenn der Benutzer ein Design generiert, aber nicht implementiert haben möchte: Im letzteren Fall reicht die Stitch-Weboberfläche aus.