stitch-setup

stitch-kit 设置指南

指导用户完成两项设置任务：

1. Stitch MCP 服务 — 将 AI 客户端连接到 Google Stitch 的远程生成 API
2. stitch-kit 插件 — 安装用于编排 Stitch 工作流的技能

---

何时使用此技能

• 用户询问“如何设置”“无法正常工作”或“找不到 Stitch”
• Agent 运行 list_tools 后找不到 Stitch MCP 工具
• 在新环境中首次设置

---

步骤 1：确认已安装的内容

运行 list_tools（或检查工具列表）。查找以下任意工具：

• create_project
• generate_screen_from_text
• get_screen

如果找到了： Stitch MCP 服务正常工作。跳到步骤 4（安装插件）。 如果没找到： 继续进行下方的 MCP 设置。

---

步骤 2：获取 Stitch API 密钥

Stitch MCP 是一个远程 HTTP 服务，托管在云端的 stitch.googleapis.com，而非你的计算机上。需要使用 API 密钥进行身份验证。

1. 前往 stitch.withgoogle.com/settings
2. 向下滚动到 API Keys 部分
3. 点击 “Create API Key”
4. 复制密钥，下一步会用到

切勿将 API 密钥提交到公共代码库。 请妥善保管。

---

步骤 3：配置 Stitch MCP

Claude Code

使用命令行（推荐）：

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

或者手动添加到 ~/.claude/settings.json：

{
  "mcpServers": {
    "stitch": {
      "type": "http",
      "url": "https://stitch.googleapis.com/mcp",
      "headers": {
        "X-Goog-Api-Key": "YOUR-API-KEY"
      }
    }
  }
}

Codex CLI

添加到 ~/.codex/config.toml：

[mcp_servers.stitch]
url = "https://stitch.googleapis.com/mcp"

[mcp_servers.stitch.headers]
X-Goog-Api-Key = "YOUR-API-KEY"

Cursor

创建或编辑 .cursor/mcp.json：

{
  "mcpServers": {
    "stitch": {
      "url": "https://stitch.googleapis.com/mcp",
      "headers": {
        "X-Goog-Api-Key": "YOUR-API-KEY"
      }
    }
  }
}

VS Code

打开命令面板 → “MCP: Add Server” → HTTP → https://stitch.googleapis.com/mcp → 名称：“stitch”。然后编辑生成的 mcp.json，添加请求头：

{
  "servers": {
    "stitch": {
      "url": "https://stitch.googleapis.com/mcp",
      "type": "http",
      "headers": {
        "Accept": "application/json",
        "X-Goog-Api-Key": "YOUR-API-KEY"
      }
    }
  }
}

快速安装（所有平台）

也可以使用 NPX 安装程序，它会提示你输入 API 密钥并完成所有配置：

npx @booplex/stitch-kit

手动验证

添加后，重启客户端并运行 list_tools。你应该能看到 create_project、generate_screen_from_text、get_screen 等工具。

---

步骤 4：安装 stitch-kit 插件（Claude Code）

/plugin marketplace add https://github.com/gabelul/stitch-kit.git
/plugin install stitch-kit@stitch-kit

一条命令即可安装全部 34 项技能。其中包含 stitch-kit Agent，重启后会自动显示。

---

步骤 5：验证完整设置

运行编排器，确认一切正常：

"Use Stitch to design a simple login screen"

预期行为：

1. stitch-orchestrator 激活
2. 它运行 list_tools 并找到 Stitch MCP 工具
3. 它生成一份设计规范
4. 它通过 create_project 创建项目
5. 它通过 generate_screen_from_text 生成屏幕
6. 它通过 get_screen 获取屏幕
7. 它询问你要转换为哪种框架

如果以上流程顺利完成，说明设置已全部完成。

---

故障排除

症状	可能原因	解决方法
list_tools 未显示 Stitch 工具	MCP 未配置或客户端未重启	重新执行步骤 3；重启客户端
“Unauthenticated”或 401 错误	API 密钥无效或已过期	在 stitch.withgoogle.com/settings 生成新密钥
create_project 因 403 失败	账号没有 Stitch 使用权限	访问 stitch.withgoogle.com 并申请访问权限
generate_screen_from_text 返回空结果	提示词不正确或项目 ID 格式错误	使用 stitch-mcp-generate-screen-from-text 技能，其中包含 ID 格式规则
get_screen 返回 404	ID 格式错误	projectId 和 screenId 必须仅包含数字，不能带 projects/ 前缀
生成的 HTML 无法下载	GCS URL 已过期或需要重定向	使用 bash scripts/fetch-stitch.sh "[url]" "temp/output.html"
插件未激活	安装命令或代码库 URL 错误	确认使用了 @stitch-kit，而不是 @stitch-pro 或 @stitch-skills

---

网络要求

Stitch MCP 会向以下地址发送出站请求：

• stitch.googleapis.com — 远程 MCP 服务
• storage.googleapis.com — 文件下载（HTML、屏幕截图）
• accounts.google.com — OAuth（使用 OAuth 而非 API 密钥时）

如果你使用企业代理或 VPN，请确保允许访问这些域名。

---

离线 / 无 MCP 模式

如果无法配置 Stitch MCP，编排器仍可在仅提示词模式下工作：

• 步骤 1–3 正常运行（规范生成、提示词组装）
• 它不会生成屏幕，而是输出一段可直接复制的 Stitch 提示词
• 手动将该提示词粘贴到 stitch.withgoogle.com
• 然后仍可对下载的 HTML 使用转换技能

---

身份验证替代方案

OAuth（适用于受限环境）

如果无法在磁盘上存储 API 密钥，Stitch 支持通过 Google Cloud 使用 OAuth：

gcloud auth login
gcloud auth application-default login
gcloud config set project YOUR-PROJECT-ID
gcloud beta services mcp enable stitch.googleapis.com --project=YOUR-PROJECT-ID

然后使用 Bearer 令牌身份验证，而不是 API 密钥。请参阅完整的 OAuth 指南。

注意：OAuth 令牌每小时过期，需要手动刷新。对大多数用户来说，API 密钥更简单。

---

参考资料

• Stitch MCP 官方设置指南：https://stitch.withgoogle.com/docs/mcp/setup
• 插件仓库：https://github.com/gabelul/stitch-kit
• 技能索引：docs/skills-index.md
• MCP 工具参考：docs/mcp-naming-convention.md