HolyStitch

什麼是 holystitch？

HolyStitch 是一個 MCP (Model Context Protocol) 工具，能將 Google Stitch 專案編譯成可運作的 Next.js 程式碼庫。它不是讓模型「猜測」轉換，而是透過 Stitch API 讀取你的 Stitch 專案，並產生完整的 JSX/Next.js 輸出檔案。

其核心目的是以確定性方式將 Stitch 畫面轉換成磁碟上的 React/Next.js 專案，包括元件結構、樣式設定，以及保留原始 HTML 以供參考—讓你可以檢視結果並完成剩餘的檢查清單項目。

主要功能

• Stitch API 讀取 (依專案 ID)： 使用你提供的 Stitch 專案 ID，透過 Stitch API 擷取專案中的每個畫面。
• 結構化 React 編譯 (非提示式)： 依據 Stitch 內嵌 HTML 標記 (例如 <!-- ComponentName -->) 解析元件，並寫入有效的 React JSX。
• 確定性 Next.js 專案輸出： 產生包含 app/、components/ 及支援檔案的 Next.js 專案目錄，可直接安裝並執行。
• 共用元件擷取與去重複： 偵測跨多畫面共用的元件，並僅在 components/ 中寫入一次，而非每頁重複。
• Tailwind 主題擷取： 擷取精確的 Tailwind 主題設定，包括顏色、字型及暗黑模式，並寫入 tailwind.config.js。
• JSX/HTML 邊緣案例處理： 執行常見的 JSX 安全轉換與標準化，包括 class→className、for→htmlFor、將內聯樣式字串轉為樣式物件 (包含 url()、calc()、var() 及 font-variation-settings)、正確圖示字型渲染 (例如 Material Symbols/Icons)、<pre><code> 內的轉義程式碼區塊，以及重複屬性處理。

如何使用 holystitch

1. 本機建置工具
   • 複製並建置：
     • git clone https://github.com/BaselAshraf81/holystitch
     • cd holystitch
     • npm install
     • npm run build
   • 記下建置資料夾的完整路徑 (例如 /Users/alice/holystitch)。
2. 取得 Stitch API 金鑰
   • 從 Stitch 專案設定複製你的 API 金鑰。
3. 設定你的 MCP 主機 (Claude Desktop / Cursor / Windsurf / 其他 MCP 主機)
   • 將 MCP 主機指向建置套件 (使用建置的 dist/index.js 路徑) 並設定 STITCH_API_KEY。
   • Claude Desktop 範例：
     • 在 claude_desktop_config.json 新增項目，包含 command: "node"、args: ["<full path>/dist/index.js"]，以及 env: { "STITCH_API_KEY": "your-api-key-here" }。
4. 提供你的 Stitch 專案 ID
   • 使用 Stitch URL 中的專案 ID (儲存庫文件顯示為 https://stitch.withgoogle.com/project/<projectId> 的一部分)。
5. 執行轉換
   • 請你的 AI 助理 (已連線至 MCP 伺服器) 將 Stitch 專案 ID 轉換成目的地資料夾的 Next.js 應用程式。
   • 工具會將專案檔案寫入磁碟；AI 接著可協助後續檢查清單項目 (如路由、字型或剩餘 JSX 邊緣案例)，這些需人工檢視。

使用情境

• 將現有 Stitch 首頁轉換成 Next.js 應用程式： 將 Stitch 畫面編譯成 React 元件及 app/ 路由，讓設計成為可執行的程式碼。
• 處理具共用 UI 的大型多畫面 Stitch 專案： 使用元件去重複，將重複區段 (例如導覽列、頁尾、英雄區段) 擷取為共用元件。
• 精確保留樣式設定： 將相同的 Tailwind 主題 (顏色、字型及暗黑模式設定) 擷取至 tailwind.config.js，而非手動重建樣式。
• 減少 LLM 在 HTML-to-JSX 轉換中的猜測： 依賴編譯器的特定 JSX 安全規則 (屬性重新命名、內聯樣式解析、轉義程式碼區塊)，避免常見轉換失敗。
• 產生可檢視程式碼庫以進行迭代開發： 從產生的 Next.js 專案開始 (保留 stitch-source/ 以供參考)，再以你自己的開發流程調整功能與路由。

常見問題

• holystitch 是否使用 AI 權杖來轉換我的 Stitch 專案？ 儲存庫描述指出它是「編譯而非提示」，並聲稱轉換本身「零權杖」。

• 執行轉換需要提供什麼？ 你需提供 Stitch 專案 ID，並在 MCP 主機設定中設定 STITCH_API_KEY。

• 它產生什麼框架？ 文件化的預設輸出為 Next.js 專案。工具也提及可使用 vite 作為框架選項，但輸出範例以 Next.js 為主。

• 產生的資料夾包含什麼？ 範例輸出包含 components/、app/、stitch-source/ (保留原始 HTML 以供參考)、tailwind.config.js，以及如 package.json 和 tsconfig.json 等專案設定檔。

• 能否僅轉換特定畫面？ 文件化選項包含 screenIds 設定，可傳遞特定畫面 ID 以轉換子集；預設為「所有畫面」。

替代方案

• 手動 Stitch 轉 React： 手動重建元件與 Tailwind 樣式。小型專案可行，但 JSX 屬性邊緣案例通常耗時較長且易出錯。
• 使用 AI 助理的提示式 HTML 轉 React/Next.js： 將匯出的 HTML/標記發送給 LLM 轉換。不同於編譯器方式，可能需更多迭代來修正 className/屬性問題與重複結構。
• 設計轉程式碼的通用模板產生器： 使用從設計資產產生 React/Next.js 程式碼的工具。這些工具可能無法保留 Stitch 專屬元件結構、Tailwind 主題細節或嵌入標記，如 Stitch 專屬編譯器般精準。
• 以元件為先的 UI 重新實作： 將每個畫面視為獨立 React 實作任務，自行建置共享元件。提供最大控制，但將轉換工作完全移轉至開發而非生成。