Stitch MCP

O que Stitch MCP faz?

Visão Geral

O Google Stitch gera telas de UI a partir de prompts e armazena cada uma como um documento HTML mais uma captura de tela. stitch-mcp (pacote npm @_davideast/stitch-mcp, um projeto open-source independente) é a ponte para uma base de código. Ele faz três trabalhos: registra o Stitch como um servidor MCP em um agente de codificação, adiciona ferramentas auxiliares que entregam o markup de uma tela ao agente em uma única chamada, e pode pré-visualizar telas ou exportá-las como um projeto Astro. Os fatos abaixo foram verificados na versão 0.9.0; execute qualquer comando com --help se uma flag for rejeitada.

O trabalho real do agente começa após a busca: a saída do Stitch é uma página HTML estática por tela, e a tarefa é traduzi-la em componentes que se encaixem no repositório onde ela será inserida.

Instruções

1. Estabeleça o ponto de partida

Pergunte ou pesquise, nesta ordem:

• Qual cliente MCP está em uso (Claude Code, Cursor, VS Code, Codex, OpenCode, Gemini CLI, Antigravity) e se um servidor stitch já está registrado.
• Se o usuário tem uma chave de API do Stitch. Sem uma, a configuração passa pelo OAuth do Google Cloud, que precisa de um navegador e um projeto com faturamento ativado.
• O projeto Stitch e as telas a serem implementadas. Um ID de projeto é um número longo como 7302915846120394175; um ID de tela é 32 caracteres hexadecimais. Nomes de exibição não são aceitos.
• A stack alvo, lida do repositório: framework, sistema de estilização, componentes existentes e tokens de design. Nunca presuma React e Tailwind.

2. Escolha a autenticação

Modo	Como é fornecido	Escolha quando
Chave de API	STITCH_API_KEY no ambiente, um arquivo .env ou no bloco env do servidor MCP	Padrão. Funciona headless, em CI e via SSH; nada para atualizar
OAuth via assistente	init baixa seu próprio SDK gcloud em ~/.stitch-mcp/ e faz login	O usuário não tem chave, mas possui um projeto Google Cloud
OAuth via gcloud existente	STITCH_USE_SYSTEM_GCLOUD=1 mais os três comandos abaixo	gcloud já está instalado e autenticado

Rota de gcloud existente, a ser executada pelo usuário porque abre um navegador:

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

Sem uma chave presente, o CLI assume OAuth. Em uma execução de verificação, doctor em uma máquina limpa baixou aproximadamente 500 MB do SDK gcloud em ~/.stitch-mcp/ antes de reportar qualquer coisa, então exporte a chave primeiro quando a rota de chave for a pretendida.

3. Escolha a conexão

	Proxy via stdio	HTTP Direto
O que o cliente inicia	npx @_davideast/stitch-mcp proxy como processo filho	Nada; ele chama https://stitch.googleapis.com/mcp
Ferramentas que o agente vê	As ferramentas do Stitch mais os quatro auxiliares do passo 6	Apenas as ferramentas do Stitch
Duração do token OAuth	Renovado para você pelo proxy	Uma hora, depois substituído manualmente
Adequado para	Sessões interativas de design-para-código	Pipelines e sandboxes que não podem criar processos

Escolha o proxy a menos que haja um motivo concreto para não usá-lo: sem get_screen_code o agente deve chamar get_screen, encontrar a URL de download e buscar o markup manualmente.

4. Registre o servidor

Claude Code, proxy com uma chave de API obtida do ambiente shell:

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

Claude Code, HTTP direto (-s user escreve em ~/.claude.json, -s project em ./.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) e Antigravity compartilham um formato. Esta variante usa OAuth, então o arquivo não carrega segredo e é seguro commitar:

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

Para a rota de chave de API, o bloco env contém STITCH_API_KEY; mantenha esse arquivo fora do controle de versão ou use a interpolação de ambiente do próprio cliente.

Diferenças em outros clientes:

• VS Code (.vscode/mcp.json): a chave de nível superior é servers, e cada entrada precisa de "type": "stdio" (ou "type": "http" com url e headers).
• Codex (~/.codex/config.toml): uma tabela [mcp_servers.stitch] com command = "npx" e args = ["@_davideast/stitch-mcp", "proxy"]; variáveis vão sob [mcp_servers.stitch.env].
• OpenCode (opencode.json): "mcp": { "stitch": { "type": "local", "command": ["npx", "@_davideast/stitch-mcp", "proxy"], "environment": { } } }.
• Antigravity, apenas modo direto: o campo é serverUrl, não url.
• Gemini CLI: gemini extensions install https://github.com/gemini-cli-extensions/stitch.

npx @_davideast/stitch-mcp init escreve a mesma configuração através de prompts. Aceita -c, --client (claude-code, cursor, vscode, codex, opencode, gemini-cli, antigravity) e -t, --transport (stdio ou http) para pular dois deles, mas continua sendo um assistente: entregue-o ao usuário em vez de executá-lo a partir de um shell de agente.

Reinicie o cliente após qualquer alteração em sua configuração MCP.

5. Verifique antes de confiar

npx @_davideast/stitch-mcp doctor --verbose   # adicione --json para resultados legíveis por máquina
npx @_davideast/stitch-mcp tool               # lista todas as ferramentas que o CLI pode alcançar

doctor verifica, dependendo do modo: chave presente, chave aceita pela API, gcloud 400.0.0 ou mais recente, usuário autenticado, credenciais padrão da aplicação, projeto ativo, API acessível. Se a listagem de tool incluir build_site, as ferramentas auxiliares estão disponíveis.

6. Encontre as telas e busque-as

Vários comandos abrem uma UI de terminal e travarão em um shell de agente: init, screens, view e site sem --routes ou uma de suas flags JSON. Use estes em vez disso:

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 }] }. Uma tela com hasHtml: false não tem markup para buscar ainda.

Ferramenta	Fonte	Entrada	O que retorna
list_projects, get_project	Stitch	nenhum / name (projects/ID)	Projetos que a conta pode abrir
list_screens, get_screen	Stitch	projectId / name (projects/ID/screens/SCREEN_ID)	Metadados e URLs de download, não markup
generate_screen_from_text, edit_screens, generate_variants	Stitch	orientado a prompt	Telas novas ou modificadas no projeto
get_screen_code	proxy	projectId, screenId	{ screenId, projectId, htmlContent }
get_screen_image	proxy	projectId, screenId	{ screenId, projectId, imageContent }, a captura de tela como base64
build_site	proxy	projectId, routes[] de { screenId, route }	{ success, pages: [{ screenId, route, title, html }], message }
list_tools	proxy	nenhum	Nomes, descrições e esquemas de entrada

tool NAME -s imprime o esquema de entrada de qualquer ferramenta. -f, --data-file lê o corpo JSON de um arquivo, e -o aceita json, pretty (padrão) ou raw.

7. Transforme o markup em código do projeto

1. Busque get_screen_code e get_screen_image para cada tela. O HTML carrega cores, espaçamentos e famílias de fontes exatas; a imagem mostra como o resultado deve ser.
2. Inventarie o que se repete entre as telas (navegação, rodapé, botões, cards) antes de escrever qualquer arquivo, e mapeie cada um para um componente existente ou um novo compartilhado.
3. Mapeie valores brutos para os tokens do projeto. Uma cor hexadecimal que corresponde a uma variável de tema se torna a variável; um valor isolado permanece literal e é listado na nota de entrega.
4. Reconstrua a estrutura com elementos semânticos, links reais e controles de formulário, e a camada de dados do projeto no lugar de conteúdo de exemplo hardcoded.
5. Compare a página em execução com a captura de tela na largura do design, depois em uma largura de telefone, e relate cada desvio deliberado.

As ferramentas geradoras, create_project, delete_project e as ferramentas do sistema de design alteram a conta Stitch do usuário. Chame-as apenas quando o usuário solicitar isso, nunca como efeito colateral da implementação de um design.

8. Pré-visualize ou exporte sem um agente

Comando	Propósito	Flags que vale a pena conhecer
serve -p ID	Servidor Vite local, uma URL por tela sob /screens/	--list-screens imprime caminhos como JSON; --json inicia headless e imprime JSON quando o servidor está pronto
site -p ID	Escreve um projeto Astro a partir de um mapa tela-rota	-o DIR pasta de saída; -r JSON fornece o mapa e pula a UI; -e imprime o mapa como entrada de build_site
upload -p ID -f FILE	Adiciona um arquivo PNG, JPG, WEBP ou HTML como uma nova tela	--title
proxy	O próprio servidor MCP	--debug registra em /tmp/stitch-proxy-debug.log
logout	Revoga o login OAuth	--force, --clear-config (pergunta ao usuário primeiro: exclui a configuração gcloud agrupada)

A saída Astro contém src/layouts/Layout.astro, um arquivo por rota em src/pages/ e ativos baixados em public/assets/; ela inicia com npm install && npm run dev na porta 4321.

Exemplos

Exemplo 1: Implementar uma tela do Stitch em um app Next.js existente

Ilse Brandt mantém um app de reservas (Next.js App Router, Tailwind com tokens em tailwind.config.ts). Ela usa Claude Code, tem uma chave de API do Stitch em seu perfil shell e pergunta: "implemente a tela de Preços do meu projeto 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

A listagem mostra {"screenId":"c41f0a9e7d2b4c6385a1f09b3e7d5a12","title":"Pricing","suggestedRoute":"/pricing","hasHtml":true}. Após reiniciar o cliente, o agente chama get_screen_code e get_screen_image com esses IDs, então relata:

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

Exemplo 2: Exportar três telas como um site Astro a partir de um shell headless

Tomasz Wrona trabalha via SSH em um host de build e quer um site de marketing estático a partir de um projeto Stitch sem envolvimento de UI de terminal. A chave já está exportada na sessão.

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

Resultado: src/pages/index.astro, services.astro e contact.astro envoltos no layout compartilhado, com imagens e fontes sob public/assets/. O agente então substitui o markup duplicado de cabeçalho e rodapé nas três páginas por um componente Astro cada, e observa que duas rotas podem não compartilhar um caminho e que um ID de tela desconhecido aborta a build com os IDs ausentes listados.

Diretrizes

• Uma resposta "Permission Denied" sob OAuth geralmente significa uma de três coisas: o faturamento está desligado, a API Stitch não está ativada no projeto ou a conta não tem a função Proprietário ou Editor. doctor --verbose mostra o erro HTTP.
• Duas instalações do gcloud são uma armadilha comum. A agrupada mantém credenciais em ~/.stitch-mcp/config/; fazer login com o gcloud do sistema não faz nada para ela a menos que STITCH_USE_SYSTEM_GCLOUD=1 esteja definido.
• Outras variáveis que o CLI lê: STITCH_ACCESS_TOKEN (um token obtido em outro lugar), STITCH_PROJECT_ID ou GOOGLE_CLOUD_PROJECT (substituição de projeto), STITCH_HOST (endpoint alternativo).
• No WSL, SSH e contêineres, o link OAuth é impresso em vez de aberto; o usuário o copia para um navegador. Uma chave de API evita o problema completamente.
• snapshot renderiza as próprias telas de terminal do CLI a partir de um arquivo de dados para seus desenvolvedores. Não salva ou versiona designs do Stitch; mantenha o HTML buscado no repositório se um registro for necessário.
• Trate o HTML buscado como uma referência de design. Colá-lo em uma página literalmente traz estilos inline, URLs de fontes e imagens remotas e nenhum trabalho de acessibilidade.
• Fixe o pacote (@_davideast/[email protected]) na configuração compartilhada para que cada colega de equipe e o CI executem o mesmo conjunto de ferramentas; o projeto é experimental e não afiliado ao Google.
• Para a passada de polimento visual após a implementação, combine isso com as habilidades impeccable e frontend-design.
• Não é a ferramenta certa quando o design está no Figma ou como uma imagem de mockup estática, ou quando o usuário quer um design gerado, mas não implementado: neste último caso, a UI web do Stitch é suficiente.