Stitch MCP 連接器

Stitch MCP

概述

Google Stitch 會根據提示詞產生 UI 畫面，並將每個畫面儲存為一份 HTML 文件與一張截圖。stitch-mcp（npm 套件 @_davideast/stitch-mcp，是一個獨立的開源專案）是連接程式碼庫的橋樑。它有三項工作：在 Coding Agent 中將 Stitch 註冊為 MCP 伺服器、加入輔助工具讓 Agent 一次呼叫即可取得畫面的標記、以及能預覽畫面或將其匯出為 Astro 專案。以下資訊已根據 0.9.0 版驗證；若指令被拒絕，請在任何指令後加上 --help。

Agent 真正的任務始於擷取之後：Stitch 的輸出是每個畫面一份靜態 HTML 頁面，而任務是將其翻譯成適合目標儲存庫的元件。

使用說明

1. 確認起點

依序詢問或查詢：

• 目前使用的是哪個 MCP 客戶端（Claude Code、Cursor、VS Code、Codex、OpenCode、Gemini CLI、Antigravity），以及是否已註冊 stitch 伺服器。
• 使用者是否有 Stitch API Key。若無，安裝流程需透過 Google Cloud OAuth，這需要瀏覽器與已啟用計費的專案。
• Stitch 專案與要實作的畫面。專案 ID 是一串長數字，例如 7302915846120394175；畫面 ID 則是 32 個十六進位字元。不接受顯示名稱。
• 目標技術棧，從儲存庫中讀取：框架、樣式系統、現有元件與設計令牌。絕不要假設是 React 與 Tailwind。

2. 選擇驗證方式

模式	如何提供	何時選擇
API Key	環境變數 STITCH_API_KEY、.env 檔案或 MCP 伺服器的 env 區塊	預設。可在無頭模式、CI 與 SSH 下運作；無需重新整理
透過精靈的 OAuth	init 會將自己的 gcloud SDK 下載到 ~/.stitch-mcp/ 並進行登入	使用者沒有 Key，但擁有 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

如果沒有 Key，CLI 會預設使用 OAuth。在測試中，doctor 指令在乾淨的機器上會先下載大約 500 MB 的 gcloud SDK 到 ~/.stitch-mcp/，然後才會報告其他資訊。因此，如果預定使用 Key 路線，請先匯出 Key。

3. 選擇連線方式

	透過 stdio 的 Proxy	直接 HTTP
客戶端啟動的內容	將 npx @_davideast/stitch-mcp proxy 作為子程序執行	無；它直接呼叫 https://stitch.googleapis.com/mcp
Agent 看到的工具	Stitch 本身的工具加上步驟 6 中的四個輔助工具	僅 Stitch 本身的工具
OAuth 權杖生命週期	Proxy 會自動為你更新	一小時，之後需手動更換
適用場景	互動式設計轉碼工作	無法產生子程序的管線或沙盒環境

除非有具體理由，否則請選擇 Proxy：沒有 get_screen_code，Agent 就必須自己呼叫 get_screen、找到下載網址並擷取標記。

4. 註冊伺服器

Claude Code，使用從 Shell 環境取得的 API Key 的 Proxy 方式：

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 Key 路線，env 區塊則放置 STITCH_API_KEY；請將該檔案排除在版本控制之外，或使用客戶端自身的環境變數插值。

其他客戶端的差異：

• VS Code（.vscode/mcp.json）：頂層 key 為 servers，每個項目需要 "type": "stdio"（或使用 "type": "http" 搭配 url 與 headers）。
• 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）來略過其中兩個步驟，但它仍然是個精靈：請將它交給使用者執行，而不是從 Agent Shell 中執行。

對 MCP 配置進行任何變更後，請重新啟動客戶端。

5. 使用前先驗證

npx @_davideast/stitch-mcp doctor --verbose   # 加上 --json 可取得機器可讀的結果
npx @_davideast/stitch-mcp tool               # 列出 CLI 可存取的每個工具

doctor 會根據模式檢查：Key 是否存在、Key 是否被 API 接受、gcloud 版本是否為 400.0.0 或更新、使用者是否已登入、應用程式預設憑證、已啟用的專案、API 是否可連線。如果 tool 列表包含 build_site，表示輔助工具可用。

6. 尋找並擷取畫面

有幾個指令會開啟終端機 UI，並在 Agent 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）	中繼資料與下載網址，非標記
generate_screen_from_text、edit_screens、generate_variants	Stitch	提示詞驅動	專案中新增或變更的畫面
get_screen_code	proxy	projectId、screenId	{ screenId, projectId, htmlContent }
get_screen_image	proxy	projectId、screenId	{ screenId, projectId, imageContent }，截圖為 base64 格式
build_site	proxy	projectId、routes[]（內容為 { screenId, route }）	{ success, pages: [{ screenId, route, title, html }], message }
list_tools	proxy	無	名稱、描述與輸入結構

tool NAME -s 會輸出任何工具的輸入結構。-f, --data-file 可從檔案讀取 JSON 內容，-o 接受 json、pretty（預設）或 raw。

7. 將標記轉換為專案程式碼

1. 為每個畫面擷取 get_screen_code 與 get_screen_image。HTML 包含確切的顏色、間距與字型；圖片則顯示預期結果的樣貌。
2. 在撰寫任何檔案之前，先盤點各畫面間重複的部分（導覽列、頁尾、按鈕、卡片），並將每個部分對應到現有元件或一個新的共用元件。
3. 將原始值對應到專案的設計令牌。若某個十六進位色碼與主題變數相符，則使用該變數；一次性使用的值則保持字面值，並在交接備註中列出。
4. 使用語義化元素、真實連結與表單控制項，以及專案的資料層來重建結構，取代硬編碼的範例內容。
5. 在設計稿的寬度下，以及在手機寬度下，比較執行中的頁面與截圖，並回報所有刻意的差異。

生成性工具 create_project、delete_project 與設計系統工具會修改使用者的 Stitch 帳戶。僅在使用者要求時呼叫它們，切勿作為實作設計的副作用。

8. 在無 Agent 的情況下預覽或匯出

指令	用途	值得了解的標誌
serve -p ID	本機 Vite 伺服器，每個畫面在 /screens/ 下有一個網址	--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（會先詢問使用者：這會刪除 bundled 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 Key，她要求：「在我的 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}。重新啟動客戶端後，Agent 使用這些 ID 呼叫 get_screen_code 與 get_screen_image，然後報告：

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

範例 2：從無頭 Shell 將三個畫面匯出為 Astro 網站

Tomasz Wrona 在構建主機上透過 SSH 工作，想要從一個 Stitch 專案建立一個靜態行銷網站，且不涉及終端機 UI。該工作階段的環境變數中已匯出 Key。

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/ 下。Agent 接著將三個頁面中重複的頁首與頁尾標記替換為各自的 Astro 元件，並備註說可能會有兩個路由共享同一路徑，以及未知的畫面 ID 會導致建置失敗並列出遺失的 ID。

指導方針

• 在 OAuth 模式下遇到「Permission Denied」回應，通常代表三種情況之一：計費未啟用、該專案未啟用 Stitch API，或該帳戶缺少 Owner 或 Editor 角色。doctor --verbose 會顯示 HTTP 錯誤。
• 兩個 gcloud 安裝是一個常見陷阱。Bundled 版本將憑證保存在 ~/.stitch-mcp/config/；除非設定了 STITCH_USE_SYSTEM_GCLOUD=1，否則使用系統 gcloud 登入對它沒有任何作用。
• CLI 會讀取的其他變數：STITCH_ACCESS_TOKEN（從別處取得的權杖）、STITCH_PROJECT_ID 或 GOOGLE_CLOUD_PROJECT（專案覆蓋）、STITCH_HOST（替代端點）。
• 在 WSL、SSH 與容器中，OAuth 連結會被印出而非開啟；使用者需將其複製到瀏覽器中。使用 API Key 可完全避免此問題。
• snapshot 是為開發者從資料檔渲染 CLI 自己的終端機畫面。它不會儲存或版本化管理 Stitch 設計；如果需要記錄，請將擷取到的 HTML 保留在儲存庫中。
• 將擷取到的 HTML 視為設計參考。直接貼到頁面中會帶來內聯樣式、遠端字型與圖片網址，且沒有無障礙處理。
• 在共享配置中鎖定套件版本（@_davideast/[email protected]），這樣每位團隊成員與 CI 都會執行相同的工具集；此專案為實驗性質，與 Google 無關。
• 在實作完成後的視覺修飾階段，可搭配使用 impeccable 與 frontend-design 技能。
• 當設計稿在 Figma 或靜態模型圖中，或者使用者只想生成設計但不實作時，本工具不適用：在後者的情況中，使用 Stitch 的網頁 UI 即可完成。