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/に1回だけ出力してページごとの重複を避けます。
• 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. 変換を実行
   • MCPサーバーに接続したAIアシスタントに、StitchプロジェクトIDを指定フォルダのNext.jsアプリに変換するよう依頼。
   • ツールがプロジェクトファイルをディスクに書き込み、AIがルーティング、フォント、残りのJSXエッジケースなどのフォローアップチェック項目を支援。

ユースケース

• 既存StitchランディングページをNext.jsアプリに変換: Stitch画面をReactコンポーネントとapp/ルートにコンパイルし、デザインを実行可能コード化。
• 共有UIを持つ大規模マルチスクリーンプロジェクト対応: コンポーネント重複除去でナビバー、フッター、ヒーローセクションなどの繰り返し部分を共有コンポーネントに抽出。
• スタイリング設定を正確に保持: Tailwindテーマ（色、フォント、ダークモード設定）をtailwind.config.jsに抽出し、手動再作成を回避。
• HTML-to-JSX変換のLLM推測を削減: コンパイラの特定JSX安全ルール（属性名変更、インラインスタイル解析、エスケープコードブロック）で一般的な変換失敗を回避。
• 反復開発用のレビュー済みコードベース生成: 生成Next.jsプロジェクト（参照用stitch-source/付き）から始め、独自の開発ワークフローで機能とルーティングを調整。

FAQ

• holystitchはStitchプロジェクト変換にAIトークンを使いますか？ リポジトリ説明では「コンパイルでプロンプトなし」「変換自体はゼロトークン」と記載。

• 変換実行に何を提供する必要がありますか？ 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-to-React変換： コンポーネントとTailwindスタイルを手作業で再構築。小規模プロジェクトでは機能しますが、JSX属性のエッジケースで通常時間がかかり、エラーが発生しやすい。
• AIアシスタントを使ったプロンプトベースのHTML-to-React/Next.js変換： エクスポートしたHTML/マークアップをLLMに送信して変換。コンパイラアプローチとは異なり、className/属性の問題や重複構造の修正に複数回のイテレーションが必要になる場合があります。
• デザイン-to-コードの汎用テンプレートジェネレータ： デザインアセットからReact/Next.jsコードをスキャフォールドするツールを使用。これらはStitch特有のコンポーネント構造、Tailwindテーマの詳細、埋め込みマーカーをStitch対応コンパイラのように保持しない可能性があります。
• コンポーネントファーストのUI再実装： 各画面をReactでの別々の実装タスクとして扱い、共有コンポーネントを自力で構築。これにより最大の制御が可能ですが、変換作業を生成ではなく開発に完全に移すことになります。