stitch-mcp

Stitch MCP

你是 Google Stitch 的资深设计系统负责人和提示词工程师。你通过 Stitch 的 AI 设计工具，在模糊想法与精确设计规范之间搭建桥梁，帮助用户创建高保真且一致的 UI 设计。

此技能采用混合方案：

• @_davideast/stitch-mcp（Agent 首选）： 面向开发者的 CLI 和 MCP 代理。它提供本地服务、网站脚手架（Astro）和资源管理等高级“虚拟工具”，因此是 AI Agent 的首选工具。
• @google/stitch-sdk（官方引擎）： Google Labs 提供的官方程序化库。可用于编写自定义 Node.js 脚本，或将 Stitch 功能集成到自己的应用中。
• 直接连接 Stitch HTTP MCP： 在无法使用本地 CLI 代理时，可直接连接以提供基本的 Agent 工具访问。

工具对比

功能	@_davideast/stitch-mcp	@google/stitch-sdk
主要受众	AI 编码 Agent（Claude、Gemini）	应用开发者
本地服务	是（serve 命令）	否
网站脚手架	是（site 命令）	否
虚拟工具	是（build_site、get_screen_code）	否（仅原始 API）
身份验证	OAuth 向导（init）	API 密钥 / 手动设置

建议： 对于由 Agent 驱动的开发和本地构建循环，始终使用 @_davideast/stitch-mcp。它充当桥梁，让 Agent 能够在本地“查看”并使用你的 Stitch 设计进行“构建”。只有在编写需要以编程方式调用 Stitch API 的自定义应用时，才使用 SDK。

设置

MCP 连接（用于 Agent 工具访问）

使用你的 API 密钥添加 Stitch MCP 服务。对于 Claude Code：

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

对于其他 MCP 客户端（Cursor、VS Code、Gemini CLI）：

{
  "mcpServers": {
    "stitch": {
      "url": "https://stitch.googleapis.com/mcp",
      "headers": { "X-Goog-Api-Key": "your-api-key" }
    }
  }
}

身份验证

API 密钥（最简单）：

export STITCH_API_KEY="your-api-key"

从 Stitch 设置 获取密钥。

OAuth（引导式向导）：

pnpx @_davideast/stitch-mcp init

通过一条命令处理 gcloud 安装、OAuth、凭据和 MCP 客户端配置。

验证设置

pnpx @_davideast/stitch-mcp doctor --verbose

---

快速参考

意图	方式	命令/工具
列出项目	CLI	pnpx @_davideast/stitch-mcp view --projects
浏览屏幕	CLI	pnpx @_davideast/stitch-mcp view --project <id>
在本地预览屏幕	CLI	pnpx @_davideast/stitch-mcp serve -p <id>
构建 Astro 网站	CLI	pnpx @_davideast/stitch-mcp site -p <id>
生成屏幕	MCP 工具	generate_screen_from_text
编辑屏幕	MCP 工具	edit_screens
生成变体	MCP 工具	generate_variants
获取屏幕 HTML	虚拟工具	get_screen_code
获取屏幕图像	虚拟工具	get_screen_image
根据屏幕构建网站	虚拟工具	build_site
创建设计系统	MCP 工具	create_design_system
通过 CLI 调用任意 MCP 工具	CLI	pnpx @_davideast/stitch-mcp tool <name>

---

平台概览（2026 年 3 月）

Stitch 使用 AI 原生无限画布，让多种资源（图像、文本、代码、UI 屏幕）共存于同一工作区。

• 通过 modelId 使用 4 种 AI 生成模式：
  • GEMINI_3_FLASH -- 生成速度快、成本较低（默认用于迭代）
  • GEMINI_3_1_PRO -- 质量最高，最适合最终屏幕
  • GEMINI_3_PRO -- 已弃用。请勿使用。
• 每条提示词同时生成 5 个屏幕
• 设计系统是核心功能 -- 可通过 MCP 工具创建、更新、列出和应用
• 变体生成 -- 通过创意范围控制探索不同方案
• 设备类型：DESKTOP、MOBILE、TABLET、AGNOSTIC
• 每日积分系统，用于生成操作

---

CLI 命令

CLI 为 Agent 提供 Bash 级别的访问能力，无需依赖 MCP 工具是否可用。使用 --json 标志获取机器可读的输出。

浏览项目和屏幕

# Interactive browser (human)
pnpx @_davideast/stitch-mcp view --projects

# Inspect a screen
pnpx @_davideast/stitch-mcp view --project <project-id> --screen <screen-id>

在本地预览屏幕

# Start a Vite dev server with all project screens
pnpx @_davideast/stitch-mcp serve -p <project-id>

# Agent-friendly: list screens as JSON without starting server
pnpx @_davideast/stitch-mcp serve -p <project-id> --list-screens

# Agent-friendly: start server and output JSON with URLs
pnpx @_davideast/stitch-mcp serve -p <project-id> --json

根据屏幕构建 Astro 网站

# Interactive route builder (human)
pnpx @_davideast/stitch-mcp site -p <project-id>

# Agent-friendly: list screens with suggested routes
pnpx @_davideast/stitch-mcp site -p <project-id> --list-screens

# Agent-friendly: generate site with explicit routes
pnpx @_davideast/stitch-mcp site -p <project-id> --routes '[
  {"screenId": "abc123", "route": "/"},
  {"screenId": "def456", "route": "/about"}
]'

从 CLI 调用任意 MCP 工具

# List all available tools
pnpx @_davideast/stitch-mcp tool

# See a tool's schema
pnpx @_davideast/stitch-mcp tool generate_screen_from_text -s

# Call a tool with data
pnpx @_davideast/stitch-mcp tool create_project -d '{"title": "My App"}'

pnpx @_davideast/stitch-mcp tool generate_screen_from_text -d '{
  "projectId": "123456",
  "prompt": "A modern dashboard with stat cards and activity chart",
  "deviceType": "DESKTOP"
}'

---

MCP 工具（通过 SDK 或代理）

官方 @google/stitch-sdk 提供了 stitchTools() 辅助函数，可公开与代理相同的核心工具。基于代理的工具还包括额外的“虚拟工具”，用于简化资源下载。

标准 Stitch 工具

项目管理：

• create_project -- 创建新项目。参数：{ title }
• get_project -- 获取项目详情。参数：{ name: "projects/<id>" }
• list_projects -- 列出所有项目。参数：{} 或 { filter: "view=owned" }

屏幕管理：

• list_screens -- 列出项目中的屏幕。参数：{ projectId }
• get_screen -- 获取屏幕详情和下载 URL。参数：{ name, projectId, screenId }

生成：

• generate_screen_from_text -- 根据提示词生成屏幕。参数：{ projectId, prompt, deviceType?, modelId? }
• edit_screens -- 编辑现有屏幕。参数：{ projectId, selectedScreenIds, prompt, modelId? }
• generate_variants -- 生成设计变体。参数：{ projectId, selectedScreenIds, prompt, variantOptions }

设计系统：

• create_design_system -- 创建并附加设计系统
• update_design_system -- 更新现有设计系统
• list_design_systems -- 列出项目的设计系统
• apply_design_system -- 将设计系统应用于屏幕

虚拟工具（由代理添加）

这些工具将多个 API 调用合并为单次操作：

get_screen_code -- 获取屏幕并在一次调用中下载其 HTML。

get_screen_image -- 获取屏幕并将其截图下载为 base64。

build_site -- 将屏幕映射到路由，并返回每个页面的设计 HTML。

{
  "projectId": "123456",
  "routes": [
    { "screenId": "abc", "route": "/" },
    { "screenId": "def", "route": "/about" }
  ]
}

---

生成

生成屏幕

{
  "projectId": "4044680601076201931",
  "prompt": "A modern dashboard for a fitness app with real-time stats cards, activity chart, and weekly goals tracker. Clean, minimal, dark theme with electric blue (#2563eb) accents.",
  "deviceType": "DESKTOP",
  "modelId": "GEMINI_3_1_PRO"
}

生成可能需要几分钟。超时后不要重试——生成仍可能成功。之后可使用 get_screen 检查。

使用场景	模型
快速迭代、草稿	GEMINI_3_FLASH
最终屏幕、高保真	GEMINI_3_1_PRO
快速编辑	GEMINI_3_FLASH

编辑屏幕

{
  "projectId": "4044680601076201931",
  "selectedScreenIds": ["98b50e2ddc9943efb387052637738f61"],
  "prompt": "Change the primary button color to deep blue (#1a365d) and add a subtle drop shadow. Keep everything else the same.",
  "modelId": "GEMINI_3_FLASH"
}

提示：

• 每次调用只进行一项重点修改，效果更好
• 使用名称引用组件：“导航栏”“主视觉区域”“卡片网格”
• 指定十六进制代码，以精确匹配颜色
• 说“其他内容保持不变”，以避免不需要的更改

生成变体

{
  "projectId": "4044680601076201931",
  "selectedScreenIds": ["98b50e2ddc9943efb387052637738f61"],
  "prompt": "Explore alternative layouts for the hero section",
  "variantOptions": {
    "variantCount": 3,
    "creativeRange": "EXPLORE",
    "aspects": ["LAYOUT", "COLOR_SCHEME"]
  }
}

范围	效果
REFINE	细微调整，紧密遵循原设计
EXPLORE	均衡探索（默认）
REIMAGINE	大胆探索，从根本上重新思考设计

可指定的方面： LAYOUT、COLOR_SCHEME、IMAGES、TEXT_FONT、TEXT_CONTENT

设计系统管理

{
  "projectId": "4044680601076201931",
  "designSystem": {
    "displayName": "Pulse Fitness",
    "theme": {
      "colorMode": "DARK",
      "customColor": "#e11d48",
      "headlineFont": "MONTSERRAT",
      "bodyFont": "INTER",
      "labelFont": "SPACE_GROTESK",
      "roundness": "ROUND_EIGHT",
      "colorVariant": "VIBRANT",
      "designMd": "High-energy fitness brand. Bold headlines, dark backgrounds, racing red accents."
    }
  }
}

颜色变体： MONOCHROME、NEUTRAL、TONAL_SPOT、VIBRANT、EXPRESSIVE、FIDELITY、CONTENT、RAINBOW、FRUIT_SALAD

字体（29 种）： INTER、MONTSERRAT、GEIST、DM_SANS、IBM_PLEX_SANS、SORA、RUBIK、SPACE_GROTESK、PLUS_JAKARTA_SANS、WORK_SANS、MANROPE、LEXEND、PUBLIC_SANS、SPLINE_SANS、EPILOGUE、BE_VIETNAM_PRO、HANKEN_GROTESK、NUNITO_SANS、ARIMO、SOURCE_SANS_THREE、METROPOLIS、NEWSREADER、NOTO_SERIF、DOMINE、LIBRE_CASLON_TEXT、EB_GARAMOND、LITERATA、SOURCE_SERIF_FOUR

圆角： ROUND_FOUR、ROUND_EIGHT、ROUND_TWELVE、ROUND_FULL

**designMd：**以自由格式 Markdown 描述设计意图。生成过程中会将其注入 AI 上下文。

下载资源

最简单的方式是使用虚拟工具：

get_screen_code   -> returns HTML directly
get_screen_image  -> returns screenshot as base64

也可以在使用 get_screen 后手动下载：

curl -sL "$HTML_URL" -o .stitch/designs/page.html
curl -sL "${IMAGE_URL}=w1200" -o .stitch/designs/page.png

在截图 URL 后追加 =w{width}，以获取完整分辨率（CDN 默认提供缩略图）。

---

提示词增强流程

调用任何生成或编辑工具前，先增强用户的提示词。

1. 检查设计系统上下文

• 检查本地 .stitch/DESIGN.md 文件，将其作为首要参考。
• 使用 list_design_systems 检查项目是否已关联设计系统。
• 如果存在设计系统，其设计令牌已应用。仅在需要覆盖时才在提示词中重复说明。
• 如果不存在设计系统，始终在提示词中加入设计系统区块。

2. 优化 UI/UX 术语

将模糊术语替换为具体的组件名称。请参阅 references/design-mappings.md。

模糊表述	专业表述
“顶部的菜单”	“带有徽标和列表项的粘性导航栏”
“大照片”	“使用全宽图像的主视觉区块”
“一堆东西的列表”	“带有悬停状态的响应式卡片网格”
“弹出窗口”	“带有遮罩层和流畅入场动画的模态对话框”

3. 构建最终提示词

[Overall vibe, mood, and purpose of the page]

**PAGE STRUCTURE:**
1. **Header:** [Description of navigation and branding]
2. **Hero Section:** [Headline, subtext, and primary CTA]
3. **Primary Content Area:** [Detailed component breakdown]
4. **Footer:** [Links and copyright information]

未关联设计系统时，添加：

**DESIGN SYSTEM:**
- Platform: [Web/Mobile], [Desktop/Mobile]-first
- Theme: [Light/Dark]
- Palette: [Primary] (#hex), [Secondary] (#hex), [Background] (#hex)
- Style: [Roundness], [Shadow/Elevation], [Typography vibe]

4. 展示 AI 反馈

每次生成或编辑后，始终向用户展示 outputComponents（文本说明和建议）。

---

构建循环

使用“接力棒”系统迭代生成多页面网站。

前置条件

• 一个 Stitch 项目
• 一个记录网站愿景和路线图的 .stitch/SITE.md 文件

接力棒：.stitch/next-prompt.md

---
page: about
---
A page describing how the product works with a clear value proposition.

**Page Structure:**
1. Header with navigation
2. Explanation of methodology
3. Team section with photos
4. Footer with links

执行流程

1. 读取接力棒 —— 解析 .stitch/next-prompt.md，获取 page 名称和提示词
2. 查阅上下文 —— 阅读 .stitch/SITE.md，了解站点地图、路线图和愿景
3. 生成 —— 调用 generate_screen_from_text 或使用 CLI tool 命令
4. 下载 —— 使用 get_screen_code / get_screen_image 虚拟工具
5. 集成 —— 移至网站目录、连接导航并修复资源路径
6. 更新 SITE.md —— 将页面标记为已完成
7. 写入下一个接力棒 —— 使用下一个页面更新 .stitch/next-prompt.md

替代方案：使用 build_site 批量生成

如果你已经生成了多个屏幕，可以使用 build_site 一次性将它们映射到各个路由：

pnpx @_davideast/stitch-mcp site -p <project-id> --routes '[
  {"screenId": "abc", "route": "/"},
  {"screenId": "def", "route": "/about"},
  {"screenId": "ghi", "route": "/contact"}
]'

这会生成一个可部署的 Astro 项目，并将所有屏幕映射到各个路由。

文件结构

project/
  .stitch/
    metadata.json      # Stitch project & screen IDs
    SITE.md            # Site vision, sitemap, roadmap
    next-prompt.md     # Current task (the baton)
    designs/           # Staging area for Stitch output
      {page}.html
      {page}.png
  site/public/         # Production pages

---

Agent 工作流与氛围编程

• 迭代设计： 不要期望首次生成的 UI 就达到像素级完美。先起草 V1 屏幕，检查 HTML/图像输出，找出具体的布局或样式问题，每次只精确调整一个变量（例如颜色、内边距或提示词措辞），然后重新生成，直到符合设计意图。
• 氛围编程： 在尝试高风险的重新设计或将多个生成的屏幕合并到主应用之前，先在本地提交正在使用的 HTML/CSS 状态和 next-prompt.md 文件。

DESIGN.md（官方规范）

DESIGN.md 是一份遵循 google-labs-code/design.md 规范的双重表述设计系统文档。该文件将机器可读的设计令牌（YAML 前置元数据）与人类可读的设计原理（Markdown 正文）结合在一起。令牌给出精确值，正文则说明这些值存在的原因以及如何应用。

创建 DESIGN.md

1. 从概念开始 —— 描述美学意图；生成 YAML 令牌和 Markdown 内容
2. 基于现有品牌 —— 提供 URL 或图像；提取配色方案和字体
3. 基于现有项目 —— 使用 get_project + get_screen 进行综合整理

调用 create_design_system 时，将内容填入 designMd 字段。

文件结构与验证

DESIGN.md 文件包含两个层次：

1. YAML 前置元数据 —— 机器可读的设计令牌，位于文件顶部并由 --- 分隔。支持的令牌架构：colors、typography、rounded、spacing、components。
2. Markdown 正文 —— 按 ## 章节组织的人类可读设计原理。

使用官方 CLI 验证 DESIGN.md 文件、捕获无效的令牌引用并检查 WCAG 对比度：

npx @google/design.md lint DESIGN.md

官方格式示例

---
name: Heritage
colors:
  primary: "#1A1C1E"
  secondary: "#6C7278"
  tertiary: "#B8422E"
  neutral: "#F7F5F2"
typography:
  h1:
    fontFamily: Public Sans
    fontSize: 3rem
  body-md:
    fontFamily: Public Sans
    fontSize: 1rem
  label-caps:
    fontFamily: Space Grotesk
    fontSize: 0.75rem
rounded:
  sm: 4px
  md: 8px
spacing:
  sm: 8px
  md: 16px
---

## Overview
Architectural Minimalism meets Journalistic Gravitas. The UI evokes a premium matte finish — a high-end broadsheet or contemporary gallery.

## Colors
The palette is rooted in high-contrast neutrals and a single accent color.
- **Primary (#1A1C1E):** Deep ink for headlines and core text.
- **Secondary (#6C7278):** Sophisticated slate for borders, captions, metadata.
- **Tertiary (#B8422E):** "Boston Clay" — the sole driver for interaction.
- **Neutral (#F7F5F2):** Warm limestone foundation, softer than pure white.

## Typography
Headlines use semi-bold weight. Body text at 14-16px regular.

## Elevation
No shadows. Depth via border contrast and surface color variation.

## Components
- **Buttons**: Rounded (8px), primary uses brand blue fill, secondary uses outline
- **Inputs**: 1px border, surface-variant background, 12px padding
- **Cards**: No elevation, 1px outline border, 12px corner radius

## Do's and Don'ts
- Do use primary color only for the single most important action per screen
- Don't mix rounded and sharp corners in the same view
- Do maintain WCAG AA contrast ratios (4.5:1 for normal text)
- Don't use more than two font weights on a single screen

Stitch 会根据 Material 颜色角色规范，从基础值自动生成命名颜色：surface、on-primary、error、outline 等。

---

设计模式

Stitch 是一套专用设计引擎，而非单个模型。

模式	modelId	最适合
Thinking with 3 Pro	GEMINI_3_1_PRO	复杂逻辑、生产候选方案。速度较慢，但像素级精确。
Redesign (Nano Banana Pro)	(仅限 UI)	风格转换、氛围设计、旧界面现代化改造。
2.5 Pro	(仅限 UI)	高保真 HTML，与 3 Pro 搭配进行 A/B 对比。
Fast	GEMINI_3_FLASH	快速线框设计、Figma 导出、快速迭代。

**提示：**在 Thinking 3 Pro 和 2.5 Pro 中使用相同的提示词进行比较。使用 Fast 进行探索，使用 3 Pro 完成最终设计。

风格关键词库（适用于 Redesign 模式）

结合以下类别中的艺术指导关键词：

布局与结构： Bento Grid、Editorial、Swiss Style、Split-Screen

纹理与纵深： Glassmorphism、Claymorphism、Skeuomorphic、Grainy/Noise

氛围与时代： Brutalist、Cyberpunk、Y2K、Retro-Futurism

色彩与对比： Duotone、Monochromatic、Pastel Goth、Dark Mode OLED

---

官方提示词最佳实践

开始设计：

• 从宽泛的概念或具体的核心功能入手
• 使用形容词设定氛围：“明快且鼓舞人心”与“极简且专注”

编辑屏幕：

• 每次只进行一项重大更改
• 具体明确：指出确切的元素、屏幕和视觉更改
• 示例：“将登录页面上的主 CTA 按钮改大，并使用品牌主蓝色”

主题控制：

• 颜色：指定十六进制值（“将主色改为森林绿”）或基于氛围描述（“温暖、舒适的配色”）
• 字体/边框：“活泼的无衬线字体”“完全圆角的按钮”
• 图片：明确说明位置和内容

变体（区别于编辑）：

• 用于探索“如果……会怎样”，而非渐进式优化
• 进行大幅调整——结合主题和布局更改
• 可以在某个变体基础上继续创建变体
• 选出最佳基础方案，降至 REFINE，并合并其他方案中的元素

---

常见问题

• 超时后不要重试生成——任务仍可能成功。使用 get_screen 检查。
• 不要使用 GEMINI_3_PRO——它已弃用。请使用 GEMINI_3_FLASH 或 GEMINI_3_1_PRO。
• 下载截图前，在截图 URL 末尾添加 =w{width}（或使用 get_screen_image 虚拟工具）。
• 编辑时保持专注。每次调用只做一项更改，效果更好。
• 在构建循环中，完成前务必更新 .stitch/next-prompt.md。
• 不要重新创建站点地图中已有的页面。
• 如果 MCP 工具不可用，请使用 CLI 回退方案：pnpx @_davideast/stitch-mcp tool <name> -d '{...}'
• 要诊断身份验证问题：STITCH_API_KEY=your-key pnpx @_davideast/stitch-mcp doctor STITCH_API_KEY=your-key pnpx @_davideast/stitch-mcp doctor t 已存在于站点地图中。
• 如果 MCP 工具不可用，请使用 CLI 回退方案：pnpx @_davideast/stitch-mcp tool <name> -d '{...}'
• 要诊断身份验证问题：STITCH_API_KEY=your-key pnpx @_davideast/stitch-mcp doctor