Stitch MCP
概述
Google Stitch 根据提示生成 UI 屏幕，并将每个屏幕存储为一个 HTML 文档和一张截图。
stitch-mcp（npm 包 @_davideast/stitch-mcp，一个独立的开源项目）是连接代码库的桥梁。它完成三项工作：在编码代理中将 Stitch 注册为 MCP 服务器，添加辅助工具以便代理通过一次调用获取屏幕的标记，以及预览屏幕或将其导出为 Astro 项目。以下事实基于版本 0.9.0 检查；如果某个标志被拒绝，请使用 --help 运行任何命令。
代理在获取屏幕后的实际工作从这里开始：Stitch 的输出是每个屏幕一个静态 HTML 页面，任务是将此翻译成适合目标仓库的组件。
说明
1. 确定起点
按顺序询问或查找：
- 正在使用哪个 MCP 客户端（Claude Code、Cursor、VS Code、Codex、OpenCode、Gemini CLI、Antigravity）以及是否已注册
stitch服务器。 - 用户是否有 Stitch API 密钥。如果没有密钥，设置将需要通过 Google Cloud OAuth，这需要浏览器和一个已启用计费的项目。
- Stitch 项目和要实现的屏幕。项目 ID 是一个长数字，例如
7302915846120394175；屏幕 ID 是 32 个十六进制字符。不接受显示名称。 - 目标技术栈，从仓库中读取：框架、样式系统、现有组件和设计令牌。切勿假设是 React 和 Tailwind。
2. 选择认证方式
| 模式 | 提供方式 | 何时选择 |
|---|---|---|
| API 密钥 | 通过环境变量 STITCH_API_KEY、.env 文件或 MCP 服务器的 env 块提供 | 默认选择。可在无界面环境、CI 和 SSH 中工作；无需刷新 |
| 通过向导进行 OAuth | init 命令将下载自己的 gcloud SDK 到 ~/.stitch-mcp/ 并登录 | 用户没有密钥但拥有 Google Cloud 项目 |
| 通过现有 gcloud 进行 OAuth | 设置 STITCH_USE_SYSTEM_GCLOUD=1 并运行下方三个命令 | gcloud 已安装并登录 |
现有 gcloud 路由，需要用户手动运行，因为会打开浏览器：
gcloud auth application-default login
gcloud config set project orchard-design-prod
gcloud beta services mcp enable stitch.googleapis.com --project=orchard-design-prod
如果没有密钥，CLI 会假定使用 OAuth。在检查运行时，doctor 命令会在干净的机器上向 ~/.stitch-mcp/ 下载大约 500 MB 的 gcloud SDK 后才会报告任何信息，因此如果打算使用密钥路由，请先导出密钥。
3. 选择连接方式
| 基于 stdio 的代理 | 直接 HTTP | |
|---|---|---|
| 客户端启动的内容 | 作为子进程启动 npx @_davideast/stitch-mcp proxy | 无需启动；它直接调用 https://stitch.googleapis.com/mcp |
| 代理看到的工具 | Stitch 自有工具加上步骤 6 中的四个辅助工具 | 仅 Stitch 自有工具 |
| OAuth 令牌生命周期 | 由代理自动续期 | 一小时后需要手动替换 |
| 适用场景 | 交互式设计到编码会话 | 无法生成子进程的流水线和沙箱环境 |
除非有具体理由不这样做，否则选择代理模式：没有 get_screen_code 工具，代理必须调用 get_screen，找到下载 URL 并自己获取标记。
4. 注册服务器
Claude Code，使用取自 shell 环境的 API 密钥的代理模式：
claude mcp add stitch -e STITCH_API_KEY="$STITCH_API_KEY" -- npx @_davideast/stitch-mcp proxy
Claude Code，直接 HTTP 模式（-s user 写入 ~/.claude.json，-s project 写入 ./.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）和 Antigravity 共享一种格式。此变体使用 OAuth，因此文件不包含密钥，可以安全提交：
{
"mcpServers": {
"stitch": {
"command": "npx",
"args": ["@_davideast/stitch-mcp", "proxy"],
"env": { "STITCH_PROJECT_ID": "orchard-design-prod" }
}
}
}
对于 API 密钥路由，env 块中包含 STITCH_API_KEY；请将该文件排除在版本控制之外，或使用客户端自己的环境变量插值功能。
其他客户端的差异：
- VS Code（
.vscode/mcp.json）：顶层键是servers，每个条目需要"type": "stdio"（或带url和headers的"type": "http"）。 - Codex（
~/.codex/config.toml）：一个[mcp_servers.stitch]表，包含command = "npx"和args = ["@_davideast/stitch-mcp", "proxy"]；变量位于[mcp_servers.stitch.env]下。 - OpenCode（
opencode.json）："mcp": { "stitch": { "type": "local", "command": ["npx", "@_davideast/stitch-mcp", "proxy"], "environment": { } } }。 - Antigravity，仅直接模式：字段是
serverUrl，而非url。 - Gemini CLI：
gemini extensions install https://github.com/gemini-cli-extensions/stitch。
npx @_davideast/stitch-mcp init 通过提示写入相同的配置。它接受 -c, --client（claude-code、cursor、vscode、codex、opencode、gemini-cli、antigravity）和 -t, --transport（stdio 或 http）来跳过其中两个步骤，但它仍然是一个向导：请将其交给用户运行，而不是从代理 shell 中执行。
对 MCP 配置进行任何更改后，请重启客户端。
5. 在依赖之前进行验证
npx @_davideast/stitch-mcp doctor --verbose # 添加 --json 以获取机器可读的结果
npx @_davideast/stitch-mcp tool # 列出 CLI 可以访问的每个工具
doctor 会根据模式检查：密钥是否存在、密钥是否被 API 接受、gcloud 版本是否为 400.0.0 或更新、用户是否已登录、应用程序默认凭据、活跃项目、API 是否可访问。如果 tool 列出的内容中包含 build_site，则表示辅助工具可用。
6. 查找屏幕并获取它们
有几个命令会打开终端 UI 并在代理 shell 中挂起：init、screens、view 和没有 --routes 或其某个 JSON 标志的 site。请改用以下命令：
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 打印 { success, projectId, screens: [{ screenId, title, suggestedRoute, hasHtml }] }。一个 hasHtml: false 的屏幕尚无可获取的标记。
| 工具 | 来源 | 输入 | 返回内容 |
|---|---|---|---|
list_projects, get_project | Stitch | 无 / name (projects/ID) | 账户可以打开的项目 |
list_screens, get_screen | Stitch | projectId / name (projects/ID/screens/SCREEN_ID) | 元数据和下载 URL，非标记 |
generate_screen_from_text, edit_screens, generate_variants | Stitch | 提示驱动 | 项目中新建或更改的屏幕 |
get_screen_code | 代理 | projectId, screenId | { screenId, projectId, htmlContent } |
get_screen_image | 代理 | projectId, screenId | { screenId, projectId, imageContent }，截图以 base64 编码 |
build_site | 代理 | projectId, routes[] 数组，每个包含 { screenId, route } | { success, pages: [{ screenId, route, title, html }], message } |
list_tools | 代理 | 无 | 名称、描述和输入模式 |
tool NAME -s 打印任何工具的输入模式。-f, --data-file 从文件中读取 JSON 主体，-o 接受 json、pretty（默认）或 raw。
7. 将标记转换为项目代码
- 为每个屏幕获取
get_screen_code和get_screen_image。HTML 包含精确的颜色、间距和字体栈；图片显示结果应该看起来像什么。 - 在编写任何文件之前，盘点各屏幕之间重复的内容（导航、页脚、按钮、卡片），并将每个内容映射到现有组件或一个新的共享组件。
- 将原始值映射到项目的令牌上。匹配主题变量的十六进制颜色变为变量；一次性的值保持字面量，并在交接说明中列出。
- 使用语义元素、真实链接和表单控件以及项目的数据层重建结构，替换硬编码的示例内容。
- 在设计宽度下比较运行中的页面与截图，然后在手机宽度下比较，并报告每个有意的偏差。
生成工具 create_project、delete_project 以及设计系统工具会更改用户的 Stitch 帐户。仅在用户要求时才调用它们，切勿作为实现设计的副作用。
8. 无需代理即可预览或导出
| 命令 | 目的 | 值得了解的标志 |
|---|---|---|
serve -p ID | 本地 Vite 服务器，每个屏幕在 /screens/ 下有一个 URL | --list-screens 打印路径为 JSON；--json 以无界面模式启动，并在服务器就绪时打印 JSON |
site -p ID | 从屏幕到路由的映射写入一个 Astro 项目 | -o DIR 输出文件夹；-r JSON 提供映射并跳过 UI；-e 将映射打印为 build_site 的输入 |
upload -p ID -f FILE | 将 PNG、JPG、WEBP 或 HTML 文件添加为新屏幕 | --title |
proxy | MCP 服务器本身 | --debug 记录到 /tmp/stitch-proxy-debug.log |
logout | 撤销 OAuth 登录 | --force，--clear-config（会先询问用户：它将删除捆绑的 gcloud 配置） |
Astro 输出包含 src/layouts/Layout.astro，每个路由一个文件在 src/pages/ 中，以及下载的资源在 public/assets/ 中；通过 npm install && npm run dev 在端口 4321 上启动。
示例
示例 1：在现有 Next.js 应用中实现一个 Stitch 屏幕
Ilse Brandt 维护一个预订应用（Next.js App Router，Tailwind，令牌在 tailwind.config.ts 中）。她使用 Claude Code，在其 shell 配置文件中有一个 Stitch API 密钥，并请求：“从我的 Stitch 项目中实现 Pricing 屏幕。”
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
列表显示 {"screenId":"c41f0a9e7d2b4c6385a1f09b3e7d5a12","title":"Pricing","suggestedRoute":"/pricing","hasHtml":true}。重启客户端后，代理使用这些 ID 调用 get_screen_code 和 get_screen_image，然后报告：
屏幕: Pricing (c41f0a9e…5a12) -> app/pricing/page.tsx
已复用: components/SiteHeader.tsx, components/Button.tsx (variant "primary")
已创建: components/pricing/PlanCard.tsx, components/pricing/BillingToggle.tsx
令牌: #1F6F5C -> colors.brand.600; 24px 卡片间距 -> gap-6; 44px 标题保留为 text-[44px]
有意更改: 计划价格从 lib/plans.ts 读取，而非示例数字
已检查: 1440px 和 390px 宽度对截图；切换按钮可通过键盘操作
示例 2：从无界面 shell 将三个屏幕导出为 Astro 站点
Tomasz Wrona 通过 SSH 在构建主机上工作，希望从一个 Stitch 项目中创建一个静态营销网站，不涉及终端 UI。密钥已在会话中导出。
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
结果：src/pages/index.astro、services.astro 和 contact.astro 包裹在共享布局中，图片和字体位于 public/assets/ 下。然后代理将三个页面中重复的页头和页脚标记替换为一个 Astro 组件，并注意两个路由不应共用同一路径，未知屏幕 ID 会中止构建并列出缺失的 ID。
指南
- OAuth 下的“权限被拒绝”响应通常意味着以下三种情况之一：计费未启用、Stitch API 未在项目上启用、或帐户缺少 Owner 或 Editor 角色。
doctor --verbose会显示 HTTP 错误。 - 两个 gcloud 安装是一个常见陷阱。捆绑的 gcloud 将凭据保存在
~/.stitch-mcp/config/中；使用系统 gcloud 登录对其无影响，除非设置了STITCH_USE_SYSTEM_GCLOUD=1。 - CLI 读取的其他变量：
STITCH_ACCESS_TOKEN（从别处获取的令牌）、STITCH_PROJECT_ID或GOOGLE_CLOUD_PROJECT（项目覆盖）、STITCH_HOST（替代端点）。 - 在 WSL、SSH 和容器上，OAuth 链接会打印出来而不是自动打开；用户需要将其复制到浏览器中。使用 API 密钥可以完全避免此问题。
snapshot命令为开发者从其数据文件渲染 CLI 自己的终端屏幕。它不保存或版本化 Stitch 设计；如果需要记录，请将获取的 HTML 保存在仓库中。- 将获取的 HTML 视为设计参考。将其原样粘贴到页面中会带来内联样式、远程字体和图片 URL，并且没有可访问性工作。
- 在共享配置中锁定包版本（
@_davideast/[email protected]），以便每个队友和 CI 运行相同的工具集；该项目是实验性的，且与 Google 无关联。 - 在实现后进行视觉润色时，将此技能与
impeccable和frontend-design技能结合使用。 - 当设计存在于 Figma 或作为静态原型图片，或者用户希望生成设计但不实现时，不要使用此工具：在后一种情况下，Stitch 的 Web UI 就足够了。