UI Design to Code

UI Design to Code MCP

中国語 | 英語

Codex、Cursor、Claude Code向けのMCP サーバーです。UIスクリーンショット、ソース画像、Figma MCPノードJSON、Figmaとスクリーンショットを組み合わせた入力から、追跡可能なデザインからコードへの成果物を生成します。

npx -y ui-design-to-code-mcp@latest install --client codex

単発のスクリーンショットからコードを生成するプロンプト以上のものが必要な場合にご利用ください。

• UIスクリーンショットとFigmaデータを解析し、ソースマニフェスト、参照画像分析、Vision IR、Node Compression IR、Semantic UIノードツリーを生成します。
• 生成されたコード計画から、視覚的プリミティブ、グループ化された候補、ソースピクセルまで追跡可能な関係を維持します。
• Web、iOS、AndroidなどのUI実装対象向けに、アダプター対応の成果物を生成します。
• テキストのはみ出し、メディアの網羅率、ナビゲーション構造、ビジュアルレビューの証跡、クリーンアップの監査ゲートを実行します。

リンク：

• npm：https://www.npmjs.com/package/ui-design-to-code-mcp
• MCP Registry：io.github.Kinglions/ui-design-to-code-mcp
• GitHub：https://github.com/Kinglions/ui-design-to-code-mcp
• フィードバックはこちら：https://github.com/Kinglions/ui-design-to-code-mcp/issues/new?title=%5BFeedback%5D%20
• GitHub Issues：https://github.com/Kinglions/ui-design-to-code-mcp/issues/new/choose

中国語

ui-design-to-code-mcp は、UIのデザインからコードへのワークフローに使用するMCP サーバーです。UIスクリーンショット、Figma MCPノードJSON、またはFigmaノードとスクリーンショットを組み合わせた入力を、構造化され、追跡・検証可能な成果物パイプラインに取り込めます。

このツールは、実際にコードを書くエージェント／モデルに取って代わるものではありません。実行ディレクトリ、入力マニフェスト、Figmaデータセット、中間IRの契約、ターゲットプラットフォームのレイアウト成果物、コード生成記録、正確な切り出し成果物、ビジュアル受け入れゲート、成果物の検証およびクリーンアップのワークフローを標準化します。

機能紹介

適した用途

• UIスクリーンショット、参考画像、GPT Imageのモックアップ、Figma URL、Figma MCPノードJSON、Figmaのエクスポート画像を、追跡可能なデザイン実装ワークフローに取り込みたい場合。
• デザイン構造、ノードツリー、レイアウトの意味、コンポーネント階層、状態、アセットを解析してからコード実装に進みたい場合。
• Web、iOS、Androidなど、複数のターゲットプラットフォーム向けのTarget Layout IRまたは実装計画が必要な場合。
• 生成された実装に対して、スクリーンショットによる受け入れ確認、ビジュアル差分の再確認、テキストのはみ出しチェック、下部ナビゲーションの確認、アセットの網羅性チェック、成果物のクリーンアップを行いたい場合。

適さない用途

• 中間成果物、追跡可能な関係、受け入れの証跡を必要とせず、1枚の画像をもとにモデルに最終コードを直接書かせたい場合。
• MCPのインストール、バージョン、doctor、設定のトラブルシューティングだけを行いたい場合。このような依頼ではdesign runを作成すべきではありません。
• デザインのソースがなく、デザインからコードへの変換やデザイン解析の意図もない、一般的なフロントエンド開発タスク。

主な機能

• Codex、Cursor、Claude Codeに対応します。
• 分離された標準実行ディレクトリを作成します：generated/ui-design-to-code/<run-id> または /private/tmp/ui-design-to-code/<run-id>。
• スクリーンショット、画像、FigmaノードJSON、Figmaとスクリーンショットを組み合わせた入力をまとめて取り込みます。
• decode、planning、target IR、codegen、自動ビジュアル受け入れ、runtime review、validate、cleanupの全工程を網羅します。
• Semantic UI IR、Cross-platform Node Data、Target Layout IR、ビジュアル受け入れ、成果物のライフサイクルなどのスキーマ契約を提供します。
• source_bbox に基づく、ソース画像からの正確なビットマップ／アイコン切り出しに対応します。
• Codexへのインストール後は、安定したローカルのserveコマンドを使用し、MCPの起動ごとに npx @latest を実行する必要がありません。

出力成果物

• artifact-run-manifest.json：1回の実行における成果物一覧、保持ポリシー、クリーンアップ範囲。
• design-source-manifest.json / source image manifest：デザインソース、ピクセル寸法、座標系、入力に関する前提。
• figma-source-dataset.json：Figmaのノード、スタイル、コンポーネント、注釈、スクリーンショット、アセットのダウンロード情報。
• Reference Image Analysis、Vision IR、Node Compression IR、Semantic UI IR、Cross-platform Node Data。
• Target Layout IR、codegen記録、visual review plan/result、QA audit、cleanup dry-runの結果。

使い方

クイックスタート

Codexへのインストール

npx -y ui-design-to-code-mcp@latest install --client codex

Figmaトークンを設定します。

ui-design-to-code-mcp setup-figma-token

このコマンドを実行すると、トークンの貼り付けを求められ、~/.codex/config.toml の [mcp_servers.ui_design_to_code.env] に書き込まれます。スクリプトで使用する場合は、次のようにします。

printf %s '<YOUR_FIGMA_TOKEN>' | ui-design-to-code-mcp configure-figma-token --client codex --stdin

Cursorのプロジェクトレベル設定へのインストール

npx -y ui-design-to-code-mcp@latest install \
  --client cursor \
  --scope project \
  --project-dir .

Figmaトークンを設定します。

ui-design-to-code-mcp configure-figma-token --client cursor --scope project --project-dir . --token <YOUR_FIGMA_TOKEN>

対応するすべてのローカルクライアントへの一括インストール

npx -y ui-design-to-code-mcp@latest install \
  --clients cursor,claude-code,codex \
  --scope project \
  --project-dir .

サービスの確認または直接起動

npx -y ui-design-to-code-mcp@latest doctor
npx -y ui-design-to-code-mcp@latest serve

フィードバックと改善のための窓口

ご利用中に、モードの選択がわかりにくい、Figmaトークンの検出が想定どおりでない、ビジュアルの再現が不安定、アセットの同期パスが誤っている、実行時の受け入れ確認に失敗する、ドキュメントの例が不足しているといった問題があれば、フィードバックをお寄せください。

• 簡単なフィードバック：https://github.com/Kinglions/ui-design-to-code-mcp/issues/new?title=%5BFeedback%5D%20
• バグ／機能リクエスト／利用上の質問：https://github.com/Kinglions/ui-design-to-code-mcp/issues/new/choose
• 既存の課題一覧：https://github.com/Kinglions/ui-design-to-code-mcp/issues

報告時には、次の情報を添えることをおすすめします。

• クライアント：Codex / Cursor / Claude Code。
• 入力タイプ：スクリーンショット、Figma URL、Figma node JSON、混合入力。
• 選択したモード：decode-only、plan-only、target-ir、codegen、codegen-with-auto-review または runtime-review。
• ターゲットプラットフォーム：web-react、web-next、ios-uikit、ios-swiftui、android-compose、android-view。
• 主な成果物またはログ：artifact-run-manifest.json、validate_pipeline の出力、visual-review-result.json、doctorの出力。

推奨実行フロー

リクエストにデザインソースと design-to-code／design-decoding の意図が含まれる場合、クライアントは純粋なローカル実装フローを先に進めるのではなく、まず ui_design_to_code MCP を自動検出して呼び出す必要があります。代表的なデザインソースには、UI のスクリーンショット、プレビュー画像、GPT Image のモックアップ、Figma URL／node-id、Figma MCP ノード JSON、Figma のスクリーンショットまたはエクスポート画像があります。

MCP の存在、バージョン、インストール、doctor、ルーティングのトラブルシューティングに関するリクエストでは、ユーザーがデザインソースも提供し、解析、実装、または視覚的な受け入れ確認を求めている場合を除き、run を作成しないでください。

1. フローに Figma のデザインデータが含まれる場合は、まず check_figma_token を呼び出します。
   • トークンがない場合は、ユーザーに Figma トークンの入力を直接求めます。受け取ったら configure_figma_token を呼び出して、グローバル Codex 設定に自動で書き込みます。run は作成しないでください。
   • 対話形式での自動書き込みが利用できない場合に限り、代替コマンド ui-design-to-code-mcp setup-figma-token を案内します。
   • トークンが設定済みの場合は、続けて実行モードを選択します。
2. ユーザーがモードを明示的に指定していない場合は、get_run_modes を呼び出し、返されたモード選択の案内をユーザーに表示します。
   • recommendedMode はデフォルトの強調表示オプションとしてのみ使用でき、ユーザーの同意と見なしてはいけません。
   • ユーザーは decode-only、plan-only、target-ir、codegen、codegen-with-auto-review、runtime-review のいずれかを選択する必要があります。
3. ユーザーがモードを確認した後、create_design_run を呼び出して、独立した成果物の実行ディレクトリを作成します。
4. ingest_image_source または ingest_figma_source を使用して、ソース入力を登録します。
   • ingest_figma_source は、外部で取得済みの Figma ノード JSON、または Figma URL／fileKey／nodeId とトークンを使って Figma REST API に直接接続し、本 MCP がノードツリー、スクリーンショット、image fills を取得する方法の 2 種類のソースに対応しています。
5. スクリーンショット／画像入力の場合は、まず Reference Image Analysis を生成して、build_reference_analysis で登録します。
6. Semantic UI IR、Cross-platform Node Data、Target Layout IR を生成して登録します。
7. Vision／Compression／Semantic の成果物がそろったら、audit_image_decoding を呼び出して画像解析の品質を監査します。
8. ホストプロジェクトでターゲットコードを生成または変更します。
9. run_codegen または run_codegen_with_auto_review を使用して、結果を記録します。
10. validate_pipeline を呼び出して、成果物の完全なパイプラインを検証します。
11. 必要に応じて cleanup_design_run を使用し、生成された成果物をクリーンアップします。

現在のフローに関する改善案

現在のフローには、token gate、mode gate、独立した runRoot、manifest による追跡、構造検証、視覚的な受け入れ確認、cleanup dry-run がすでに備わっています。今後は、以下の点を優先して改善することをお勧めします。

• IR 自動生成の範囲：MCP が現在担うのは、成果物の登録、検証、追跡です。Vision IR、Compression IR、Semantic IR と実際のコードは、引き続き呼び出し元のエージェント／モデルが生成します。README とクライアントへの案内では、MCP 単体でスクリーンショットからコードまでを完全自動で生成できるかのような表現を引き続き避ける必要があります。
• ランタイム受け入れ確認の前提条件：codegen-with-auto-review と runtime-review では、ホストプロジェクトに実行可能なコマンド、スクリーンショット取得手段、ターゲットページの特定方法が必要です。これらの条件が不足している場合は、未撮影の実装を納品可能と見なすのではなく、明確に blocked と返す必要があります。
• Schema 検証の深さ：現在の validate_pipeline は構造中心で、依存関係が少ない設計です。今後はインストールコストを大幅に増やさず、より完全な JSON Schema 検証を導入できます。
• 成果物サイズと孤立ファイルの監査：既存の size accounting は、主に manifest に登録されたファイルを対象としています。今後は runRoot の orphan artifact audit を追加し、削除はせずに報告のみ行うことができます。
• revision 管理：複数回の patch／review の後、manifest に supersedes 関係を記録することで、古い失敗バージョンを自動的に cleanup eligible にできます。
• アセットの重複排除：source crop と Figma アセットのダウンロードでは、hash による重複排除をさらに進め、複数回の review で重複する画像が作成されるのを減らせます。

実行モード

モード	target が必要か	主な用途
decode-only	いいえ	ソース入力と vision／compression／semantic の成果物のみを収集し、プラットフォーム計画やコードは生成しません。
plan-only	いいえ	クロスプラットフォームのノードデータと変換計画を生成し、ターゲットレイアウトやコードは生成しません。
target-ir	はい	ターゲットプラットフォームのレイアウト IR を登録し、コードは変更しません。
codegen	はい	実装コードを生成または変更し、通常の検証結果を記録します。
codegen-with-auto-review	はい	コード生成と視覚的な受け入れ確認の根拠を記録し、類似度ゲートを実行します。
runtime-review	はい	既存のランタイム実装をスクリーンショットで受け入れ確認し、コードは変更しません。

ターゲットプラットフォームの例：

ios-uikit / ios-swiftui / web-react / web-next / android-compose / android-view / cocos-creator

cocos-creator のターゲットコントラクトは Cocos Creator 3.x TypeScript です。Canvas デザイン解像度ポリシーを使用し、アスペクト比を維持します。各向きにつき比例モードを 1 つ（fit_width、fit_height、show_all、または明確な根拠がある場合の no_border）選択します。コントロールには SafeArea／Widget を使用し、Node + Component の階層、UITransform／Widget／Layout、明示的な ScrollView view/content ノード、assets/ 配下のアセットを使用します。DOM／CSS、ExactFit 形式の歪み、デバイスのピクセル単位のブレークポイントは生成しません。references/cocos-creator-development-rules.md と references/platform-adapters/cocos-creator.adapter-contract.json を参照してください。

入力ソースの選択

入力タイプ	適した用途	推奨ツール
スクリーンショットまたは画像	デザインソースがレンダリング済みの画像である場合。	ingest_image_source
Figma ノード JSON または Figma REST への直接接続	構造、命名、テキスト、コンポーネント、スタイル、レイアウトのメタデータが必要な場合。	ingest_figma_source
Figma ノード + スクリーンショット／REST でエクスポートしたスクリーンショット	構造化情報とピクセル単位の視覚的な基準の両方が必要な場合。	ingest_figma_source

Figma ノードとスクリーンショットの両方を取得できる場合は、混合入力を優先してください。Figma ノードから構造化情報を取得し、スクリーンショットをピクセル単位の視覚的な基準として使うことで、後続の視覚的な確認が容易になります。

成果物の実行ディレクトリ

すべてのフローは create_design_run から開始します。これにより、独立した runRoot と artifact-run-manifest.json が作成されます。

プロジェクト内のデフォルトディレクトリ：

generated/ui-design-to-code/<timestamp>-<slug>/
  artifact-run-manifest.json
  source/
  figma/
  analysis/
  vision/
  compression/
  semantic/
  cross-platform/
  targets/
  assets/
  qa/
  review/

一時実行ディレクトリ：

/private/tmp/ui-design-to-code/<timestamp>-<slug>/

クライアントのインストール

Codex

Codex インストーラーはユーザーレベルの MCP 設定を書き込み、実行時の起動パスがネットワークに依存しないようにします。

Codex plugin marketplace からインストール：

codex plugin marketplace add Kinglions/ui-design-to-code-mcp --ref main
codex plugin list --marketplace ui-design-to-code
codex plugin add ui-design-to-code@ui-design-to-code

インストール後に MCP サーバーを確認：

codex mcp list

このプラグインは ui_design_to_code を次のように登録します：

npx -y ui-design-to-code-mcp@latest serve

npm を使用して MCP を直接インストールすることもできます：

npx -y ui-design-to-code-mcp@latest install --client codex

インストールパッケージのパス：

~/.codex/mcp-packages/ui-design-to-code-mcp

Codex serve コマンド：

~/.codex/bin/serve-ui-design-to-code-mcp

macOS の毎日の更新タスク：

~/Library/LaunchAgents/com.wuyb.codex.update-mcp-packages.plist

更新コマンド：

~/.codex/bin/update-mcp-packages

インストール仕様が ui-design-to-code-mcp@latest の場合、更新スクリプトは毎日 04:15 に npm の latest を確認し、バージョンが変わった場合にのみ更新をダウンロードします。更新後のパッケージは、Codex の次回起動時、またはこの MCP サーバーの再読み込み時に適用されます。

Codex の設定例：

[mcp_servers.ui_design_to_code]
command = "/Users/<user>/.codex/bin/serve-ui-design-to-code-mcp"
args = []
startup_timeout_sec = 30

アンインストール：

npx -y ui-design-to-code-mcp@latest uninstall --client codex

Cursor

プロジェクトレベルの設定：

{
  "mcpServers": {
    "ui-design-to-code": {
      "command": "npx",
      "args": ["-y", "ui-design-to-code-mcp@latest", "serve"]
    }
  }
}

インストール：

npx -y ui-design-to-code-mcp@latest install \
  --client cursor \
  --scope project \
  --project-dir .

アンインストール：

npx -y ui-design-to-code-mcp@latest uninstall \
  --client cursor \
  --scope project \
  --project-dir .

Claude Code

プロジェクトレベルでインストール：

npx -y ui-design-to-code-mcp@latest install \
  --client claude-code \
  --scope project \
  --project-dir .

ユーザーレベルでインストール：

claude mcp add-json ui-design-to-code \
  '{"type":"stdio","command":"npx","args":["-y","ui-design-to-code-mcp@latest","serve"]}' \
  --scope user

ツールリファレンス

get_run_modes

サポートされている実行モード、対象プラットフォーム、トリガーの例、モード選択のヒントを返します。

ユーザーが UI のスクリーンショット、参考画像、Figma デザイン、またはデザインからコードを生成するタスクを提示したものの、モードを明示していない場合は、最初にこれを呼び出してください。

典型的な入力：

{ "requestText": "convert this screenshot to web code" }

create_design_run

実行ディレクトリと artifact-run-manifest.json を作成します。

主な引数：

• workspace：生成ディレクトリを配置するプロジェクトのルートディレクトリ。
• slug：読みやすい run 名のサフィックス。
• mode：実行モード。
• targets：target/codegen/review モードでは必須です。
• useTmp：true の場合、/private/tmp に書き込みます。

戻り値：

• runRoot
• manifestPath
• mode

ingest_image_source

スクリーンショットまたは画像をソース入力として登録します。

出力：

source/design-source-manifest.json
source/page.source-manifest.json

主な引数：

• runRoot
• imagePath
• sourceId
• 寸法を自動で読み取れない場合は、widthPx、heightPx を指定します
• knownViewport
• logicalUnit

ingest_figma_source

Figma 入力ソースを登録します。次の方法に対応しています：

1. 既存の Figma ノード JSON を渡します。
2. Figma URL / figma.fileKey / figma.nodeId を指定し、apiToken または環境変数（デフォルトで FIGMA_API_TOKEN、FIGMA_ACCESS_TOKEN、FIGMA_OAUTH_TOKEN を順に試します）を使用して、MCP から Figma REST API を直接呼び出します。
3. 1 または 2 にスクリーンショットを添付するか、MCP にスクリーンショットと target-aware アセットを自動でエクスポートさせます。
4. projectRoot も指定した場合、MCP はダウンロード完了後にアセットを対象プロジェクトのデフォルトリソースディレクトリに自動で同期し、runRoot 内のアーカイブ済みコピーも保持します。

出力：

source/design-source-manifest.json
figma/figma-source-dataset.json
figma/figma-node-index.json
figma/figma-asset-plan.json
figma/raw-node-response.json
figma/raw-file-metadata.json
figma/raw-image-fills.json
figma/figma-asset-downloads.json
targets/asset-sync-manifest.json

主な引数：

• runRoot
• figmaUrl
• figma.fileKey
• figma.nodeId
• nodeJson または nodeJsonPath
• screenshotPath
• figmaBounds
• fetchFromApi
• apiToken / tokenEnvVar
• downloadScreenshot
• downloadAssets
• screenshotScale
• projectRoot

リソースの同期ルール：

• web-react / web-next：デフォルトでは public/ui-design-to-code/figma/... に同期します。public/ がない場合は、src/assets/ui-design-to-code/figma/... にフォールバックします。
• ios-uikit / ios-swiftui：最初に見つかった .xcassets を優先して同期し、.imageset を自動作成します。
• android-compose / android-view：デフォルトでは app/src/main/res/drawable に同期します。存在しない場合は、src/main/res を検索します。

次のツールを明示的に個別に呼び出すこともできます：

sync_target_assets

トークンがない場合、MCP はユーザーに Figma token を直接入力するよう求め、configure_figma_token を通じてグローバルな Codex 設定に自動で書き込みます。自動設定を利用できない場合に限り、代替コマンドを使用します：

ui-design-to-code-mcp setup-figma-token

slice_image_assets

layers.manifest.json の source_bbox に基づいて、元画像から bitmap/icon リソースを正確に切り出します。

これは明示的に呼び出す独立したツールであり、decode、plan、target IR、codegen のデフォルトの流れには影響しません。

入力 manifest の例：

[
  {
    "id": "icon-tab-home",
    "type": "bitmap",
    "source_bbox": { "x": 120, "y": 980, "width": 72, "height": 72 },
    "asset": "icon-tab-home.png",
    "transparent_required": true,
    "z_index": 20
  }
]

典型的な tool 引数：

{
  "runRoot": "/path/to/run",
  "sourcePath": "/path/to/source.png",
  "layersManifestPath": "/path/to/layers.manifest.json",
  "canvasWidth": 750,
  "onlyType": "bitmap"
}

デフォルトの出力：

assets/slices/<asset>.png
assets/slices/layers.manifest.normalized.json
qa/bbox-preview.svg
qa/png-asset-audit.json

画像切り出しスクリプトは元画像のピクセル座標を使用し、自動で trim せず、出力キャンバスのサイズも変更しません。元のピクセルと元の alpha を保持します。現行バージョンでは追加の画像依存関係を導入しないため、背景の除去は行いません。alpha の詳細を読み取れない場合、監査レポートでは透明度／端への接触のチェックを利用不可とします。

build_reference_analysis

モデルが生成した Reference Image Analysis を登録します。Vision IR の前段に位置し、元のピクセル寸法、ルートアートボード、意味的な最上位グループ、テキスト／メディア／アイコン／マテリアルの一覧、下部ナビゲーション、厳密な抽出設定、高リスク領域、後続の監査計画を記録します。

artifactPath を渡さない場合、この成果物の生成に必要な schema と参考説明を返します。

デフォルトの artifact type：

reference_analysis

build_semantic_ir

モデルが生成した Platform-neutral Semantic UI IR を登録します。

artifactPath を渡さない場合、この成果物の生成に必要な schema と参考説明を返します。

デフォルトの artifact type：

platform_neutral_semantic_ui_ir

build_cross_platform_nodes

Cross-platform Node Data を登録します。

artifactPath を渡さない場合、対応する schema contract を返します。

デフォルトの artifact type：

cross_platform_node_data

build_target_ir

対象プラットフォームのレイアウト IR を登録します。

schema のヒントは target 名に基づいて選択します：

• Android target では Android layout schema を使用します。
• ios-uikit では UIKit layout schema を使用します。
• ios-swiftui では iOS SwiftUI layout schema を使用します。
• その他の target では Web React layout schema を使用します。

run_codegen

実装コードの変更と通常の検証結果を記録します。視覚的な受け入れゲートは実行しません。

出力：

review/codegen-result.json

run_codegen_with_auto_review

コード生成の結果と視覚的な受け入れの根拠を記録します。

visualReviewResultPath が指定されている場合、次の条件を満たすときに限り、納品可能とマークします：

review.status == "passed"
minimum non-material similarity >= 0.9

出力：

review/codegen-with-auto-review-result.json

validate_pipeline

既存の run の成果物間の連携を検証します。必須の成果物が存在すること、および vision、compression、semantic、cross-platform、target planning の間で traceability に一貫性があることを確認します。

audit_image_decoding

スクリーンショット／画像の解析成果物を監査します。reference analysis が元画像の寸法と一致すること、最上位グループが範囲外に出ていないこと、監査セクションがすべて揃っていること、テキストにフォントの計測情報があること、メディア／アイコン領域が含まれていること、semantic node が traceability を保持していること、単一行テキストに改行のリスクがないこと、下部ナビゲーションにスロットが含まれていること、信頼度の低いノードに alternatives が用意されていることを確認します。

デフォルトの出力：

qa/image-decoding-audit.json

cleanup_design_run

実行成果物をクリーンアップします。デフォルトでは dry-run です。

典型的な引数：

{ "runRoot": "/path/to/run", "apply": false }

クリーンアップ可能な成果物を削除することを確認した場合に限り、apply: true を設定してください。

一般的なワークフロー

スクリーンショットから Web コードへの変換

1. ユーザーがモードを指定していない場合は、get_run_modes を呼び出します。
2. create_design_run を呼び出し、mode: "codegen" または mode: "codegen-with-auto-review" を選択して、targets: ["web-react"] を設定します。
3. ingest_image_source を呼び出して、スクリーンショットを登録します。
4. スクリーンショットの構造を分析した後、build_reference_analysis を呼び出します。
5. Semantic UI IR、Cross-platform Node Data、Target Layout IR を生成または登録します。
6. Vision／Compression／Semantic の成果物が準備できたら、audit_image_decoding を呼び出します。
7. ホストプロジェクト内でコードを実装します。
8. run_codegen または run_codegen_with_auto_review を呼び出します。
9. validate_pipeline を呼び出します。

Figma Hybrid から Target IR への変換

1. Figma MCP を通じてノード JSON を取得します。
2. 同じフレームのスクリーンショットを用意するか、撮影します。
3. create_design_run を呼び出し、mode: "target-ir" とターゲットプラットフォームを設定します。
4. ingest_figma_source を呼び出し、nodeJson と screenshotPath を渡します。
5. ターゲットプラットフォームの Layout IR を生成します。
6. build_target_ir を呼び出して成果物を登録します。
7. validate_pipeline を呼び出します。

スクリーンショットからの高精度な画像切り出し

1. create_design_run を呼び出します。
2. ingest_image_source を呼び出します。
3. 元画像のピクセル単位の bbox を含む layers.manifest.json を作成します。
4. slice_image_assets を呼び出します。
5. 生成されたコードで assets/slices/ 内の PNG を使用します。
6. qa/bbox-preview.svg と qa/png-asset-audit.json を確認します。

更新とバージョン管理

クライアントの設定を指定した channel に更新します。

npx -y ui-design-to-code-mcp@latest update \
  --clients cursor,claude-code,codex \
  --channel latest

固定バージョンをインストールします。

npx -y [email protected] install \
  --client codex \
  --package-spec [email protected]

安定した本番環境では、固定バージョンの使用を推奨します。Codex の毎日の自動更新や、npx クライアントによる最新版の動的取得が必要な場合は、@latest を使用します。

開発

検証を実行します。

npm run check
npm run release:check

パッケージをプレビューします。

npm pack --dry-run

リリース

推奨する npm 公開手順は次のとおりです。

1. npm Trusted Publishing を設定します。

   node bin/ui-design-to-code-mcp.js configure-npm-trusted-publishing --dry-run
   

2. main ブランチから GitHub Actions の Release ワークフローを実行します。

Release ワークフローでは GitHub Actions OIDC（id-token: write）を使用するため、NPM_TOKEN や長期間有効な MCP Registry トークンは不要です。npm アカウントでは 2FA を有効にしておいてください。

リリース、Registry、ロールバック、安全性に関する方針の詳細は、以下を参照してください。

• RELEASE.md
• SECURITY.md

リポジトリ

https://github.com/Kinglions/ui-design-to-code-mcp.git

英語

ui-design-to-code-mcp は、UI スクリーンショット、Figma MCP ノード JSON、または Figma とスクリーンショットを組み合わせたソースを、実装可能なデザインからコードへの出力に変換するための成果物パイプラインを標準化する MCP サーバーです。

コーディングエージェントやモデルを置き換えるものではありません。その代わりに、エージェントが実行ディレクトリ、ソースマニフェスト、Figma データセット、中間 IR コントラクト、ターゲットレイアウト成果物、コード生成記録、アセット切り出し出力、ビジュアルレビューのゲート、検証、クリーンアップを確実に処理できるワークフローを提供します。

機能の概要

使用する場面

• UI スクリーンショット、参照画像、GPT Image のモックアップ、Figma URL、Figma MCP ノード JSON、または Figma エクスポートがあり、追跡可能なデザインからコードへのワークフローが必要な場合。
• 実装前に、構造、ノード階層、レイアウトの意味、状態、アセットを解析したい場合。
• Web、iOS、Android、または複数のプラットフォーム向けのターゲットレイアウト成果物や実装計画が必要な場合。
• 実行時のスクリーンショット、ビジュアル差分の証拠、テキストのオーバーフローチェック、ナビゲーションチェック、アセットの網羅性チェック、または成果物のクリーンアップが必要な場合。

使用しない場面

• 中間成果物やレビューの証拠を作成せず、画像から最終コードを一度のプロンプトで生成したいだけの場合。
• MCP のインストール、バージョン、doctor の出力、または設定だけを確認したい場合。これらのリクエストではデザインの実行を作成しないでください。
• デザインソースがなく、デザイン解析やデザインからコードへの変換も目的としていない場合。

主な機能

• Codex、Cursor、Claude Code で動作します。
• generated/ui-design-to-code/<run-id> または /private/tmp/ui-design-to-code/<run-id> に、分離された成果物の実行環境を作成します。
• スクリーンショット、ソース画像、Figma ノード JSON、Figma とスクリーンショットを組み合わせた入力に対応します。
• 解析、計画、ターゲット IR、コード生成、自動レビュー、実行時レビュー、検証、クリーンアップまで、パイプライン全体をカバーします。
• Semantic UI IR、Cross-platform Node Data、Target Layout IR、ビジュアルレビュー、成果物のライフサイクルに対し、スキーマに基づくコントラクトを提供します。
• 明示的な source_bbox レイヤーマニフェストを使用した、ソース画像からの高精度なアセット切り出しに対応します。
• 起動のたびに npx @latest を実行する代わりに、安定したローカルの MCP サーブコマンドをインストールすることで、Codex の起動を最適化します。

出力

• artifact-run-manifest.json：実行単位のアーティファクト一覧、保持ポリシー、クリーンアップ境界。
• design-source-manifest.json／ソース画像マニフェスト：ソースメタデータ、ピクセルサイズ、座標系、前提条件。
• figma-source-dataset.json：Figma ノード、スタイル、コンポーネント、コメント、スクリーンショット、アセットのダウンロードメタデータ。
• 参照画像分析、Vision IR、ノード圧縮 IR、Semantic UI IR、クロスプラットフォームノードデータ。
• ターゲットレイアウト IR、コード生成記録、ビジュアルレビュー計画／結果、QA 監査出力、クリーンアップのドライランレポート。

ユーザーハンドブック

クイックスタート

Codex へのインストール

npx -y ui-design-to-code-mcp@latest install --client codex

Cursor プロジェクト設定へのインストール

npx -y ui-design-to-code-mcp@latest install \
  --client cursor \
  --scope project \
  --project-dir .

サポートされているすべてのローカルクライアントへのインストール

npx -y ui-design-to-code-mcp@latest install \
  --clients cursor,claude-code,codex \
  --scope project \
  --project-dir .

サーバーの確認または実行

npx -y ui-design-to-code-mcp@latest doctor
npx -y ui-design-to-code-mcp@latest serve

フィードバックと問題の報告

モードの選択が不明確な場合、Figma トークンの検出が想定どおりに動作しない場合、ビジュアル復元が不安定な場合、アセット同期パスが間違っている場合、実行時レビューがブロックされる場合、またはドキュメントにサンプルが不足している場合は、以下のリンクを使用してください。

• 簡単なフィードバック：https://github.com/Kinglions/ui-design-to-code-mcp/issues/new?title=%5BFeedback%5D%20
• バグ報告／機能リクエスト／使用方法に関する質問：https://github.com/Kinglions/ui-design-to-code-mcp/issues/new/choose
• 既存の問題：https://github.com/Kinglions/ui-design-to-code-mcp/issues

記載すると役立つ情報：

• クライアント：Codex／Cursor／Claude Code。
• ソースの種類：スクリーンショット、Figma URL、Figma ノード JSON、またはハイブリッド入力。
• モード：decode-only、plan-only、target-ir、codegen、codegen-with-auto-review、またはruntime-review。
• ターゲット：web-react、web-next、ios-uikit、ios-swiftui、android-compose、またはandroid-view。
• 証拠：artifact-run-manifest.json、validate_pipeline の出力、visual-review-result.json、または doctor の出力。

推奨ワークフロー

1. ユーザーがモードを指定していない場合は、get_run_modes でモードを選択します。
2. create_design_run でアーティファクト実行を作成します。
3. ingest_image_source または ingest_figma_source でソース入力を登録します。
4. スクリーンショット／画像入力の場合は、build_reference_analysis で参照画像分析を生成して登録します。
5. Semantic UI IR、クロスプラットフォームノードデータ、ターゲットレイアウト IR を生成して登録します。
6. Vision／Compression／Semantic アーティファクトが存在する場合は、audit_image_decoding で画像デコードの品質を監査します。
7. ホストプロジェクトでコードを生成または変更します。
8. run_codegen または run_codegen_with_auto_review で結果を記録します。
9. validate_pipeline でアーティファクトチェーン全体を検証します。
10. 必要に応じて、cleanup_design_run で生成されたアーティファクトをクリーンアップします。

現在のワークフロー最適化に関する注意事項

現在のワークフローには、トークンによるゲーティング、モードによるゲーティング、分離された実行ルート、マニフェストによるトレーサビリティ、構造検証、ビジュアルレビュー、クリーンアップのドライランがすでに備わっています。次に優先度の高い改善点は以下のとおりです。

• IR 生成の境界：MCP はアーティファクトを登録、検証、追跡しますが、Vision IR、Compression IR、Semantic IR、および実装コードは引き続き呼び出し元のエージェント／モデルが生成します。
• 実行時レビューの前提条件：codegen-with-auto-review と runtime-review には、実行可能なホストアプリのコマンド、スクリーンショットのキャプチャ設定、ページルーティングが必要です。前提条件が不足している場合は、成果物を返すのではなくブロックとして返す必要があります。
• スキーマ検証の深さ：validate_pipeline は意図的に軽量な構造検証を行います。依存関係への影響が許容できる場合は、今後のバージョンでより詳細な JSON Schema 検証を追加できます。
• アーティファクトサイズと孤立ファイルの監査：現在のサイズ計算は、マニフェストに記載されたファイルを対象としています。今後の監査では、削除せずに runRoot 内の未登録ファイルを報告できます。
• リビジョン管理：パッチ／レビューループでは、置き換え関係を記録することで、古い失敗リビジョンをクリーンアップ対象にできるようにする必要があります。
• アセットの重複排除：ソースの切り抜き画像と Figma のダウンロードファイルでは、ハッシュを使用してレビューループ間の画像アセットの重複を避けることができます。

実行モード

モード	ターゲット必須	主な用途
decode-only	いいえ	ソースのマニフェスト、ビジョン／圧縮／セマンティックアーティファクトを取得します。ターゲットの計画やコードは含みません。
plan-only	いいえ	クロスプラットフォームのノードデータと変換計画を追加します。ターゲットのレイアウトやコードは含みません。
target-ir	はい	ターゲットプラットフォームのレイアウト IR を登録します。コードの変更は行いません。
codegen	はい	実装コードを生成または変更し、検証内容を記録します。
codegen-with-auto-review	はい	コード生成に加え、ビジュアルレビューの証拠と類似度ゲートを記録します。
runtime-review	はい	既存のランタイム実装をソースと照らし合わせてレビューします。コードの変更は行いません。

ターゲットプラットフォームの例：

ios-uikit / ios-swiftui / web-react / web-next / android-compose / android-view

ソース入力戦略

ソースの種類	使用する場面	推奨ツール
スクリーンショットまたは画像	デザインソースがレンダリング済みの画像である場合。	ingest_image_source
Figma MCP ノード JSON	構造、名前、テキスト、コンポーネント、スタイル、レイアウトメタデータが必要な場合。	ingest_figma_source
Figma ノード JSON ＋ スクリーンショット	構造メタデータとピクセルレベルの視覚的な正確さの両方が必要な場合。	ingest_figma_source

Figma ノードは構造を提供し、スクリーンショットはビジュアルレビューのピクセル基準を提供するため、利用可能な場合はハイブリッド形式の Figma 入力を推奨します。

アーティファクトの実行レイアウト

すべてのワークフローは create_design_run から開始し、専用の runRoot と artifact-run-manifest.json を作成します。

プロジェクトの実行レイアウト：

generated/ui-design-to-code/<timestamp>-<slug>/
  artifact-run-manifest.json
  source/
  figma/
  analysis/
  vision/
  compression/
  semantic/
  cross-platform/
  targets/
  assets/
  qa/
  review/

一時的な実行では、次を使用します。

/private/tmp/ui-design-to-code/<timestamp>-<slug>/

クライアントのインストール

Codex

Codex インストーラーはユーザーレベルの MCP 設定を書き込み、ランタイムの起動時にネットワークを経由しないようにします。

Codex プラグインマーケットプレイスからのインストール：

codex plugin marketplace add Kinglions/ui-design-to-code-mcp --ref main
codex plugin list --marketplace ui-design-to-code
codex plugin add ui-design-to-code@ui-design-to-code

インストール後、MCP サーバーを確認します。

codex mcp list

プラグインは ui_design_to_code を次の内容で登録します。

npx -y ui-design-to-code-mcp@latest serve

npm を直接使った MCP のインストールも引き続き利用できます。

npx -y ui-design-to-code-mcp@latest install --client codex

インストール済みパッケージ：

~/.codex/mcp-packages/ui-design-to-code-mcp

Codex の serve コマンド：

~/.codex/bin/serve-ui-design-to-code-mcp

macOS でのデイリーアップデーター：

~/Library/LaunchAgents/com.wuyb.codex.update-mcp-packages.plist

アップデーターのコマンド：

~/.codex/bin/update-mcp-packages

インストール仕様が ui-design-to-code-mcp@latest の場合、アップデーターは毎日 04:15 に npm を確認し、npm latest に変更があった場合にのみ新しいバージョンをダウンロードします。更新されたパッケージは、Codex が次回起動するか、この MCP サーバーを再読み込みしたときに使用されます。

Codex の設定例：

[mcp_servers.ui_design_to_code]
command = "/Users/<user>/.codex/bin/serve-ui-design-to-code-mcp"
args = []
startup_timeout_sec = 30

アンインストール：

npx -y ui-design-to-code-mcp@latest uninstall --client codex

Cursor

プロジェクト設定：

{
  "mcpServers": {
    "ui-design-to-code": {
      "command": "npx",
      "args": ["-y", "ui-design-to-code-mcp@latest", "serve"]
    }
  }
}

インストール：

npx -y ui-design-to-code-mcp@latest install \
  --client cursor \
  --scope project \
  --project-dir .

アンインストール：

npx -y ui-design-to-code-mcp@latest uninstall \
  --client cursor \
  --scope project \
  --project-dir .

Claude Code

プロジェクトへのインストール：

npx -y ui-design-to-code-mcp@latest install \
  --client claude-code \
  --scope project \
  --project-dir .

ユーザースコープへのインストール：

claude mcp add-json ui-design-to-code \
  '{"type":"stdio","command":"npx","args":["-y","ui-design-to-code-mcp@latest","serve"]}' \
  --scope user

ツールリファレンス

get_run_modes

対応するモード、ターゲットプラットフォーム、トリガーの例、モード選択プロンプトを返します。

ユーザーが UI のスクリーンショット、参考画像、Figma デザイン、またはデザインからコードへの変換を依頼し、モードを指定していない場合に使用します。

一般的な入力：

{ "requestText": "convert this screenshot to web code" }

create_design_run

実行ディレクトリと artifact-run-manifest.json を作成します。

主な入力：

• workspace：生成された出力先のプロジェクトルート。
• slug：読みやすい実行名の接尾辞。
• mode：対応している実行モードのいずれか。
• targets：ターゲット／コード生成／レビューの各モードで必須です。
• useTmp：true の場合、/private/tmp 配下に書き込みます。

戻り値：

• runRoot
• manifestPath
• mode

ingest_image_source

スクリーンショットまたは画像を次の場所に登録します。

source/design-source-manifest.json
source/page.source-manifest.json

主な入力：

• runRoot
• imagePath
• sourceId
• サイズを推定できない場合は widthPx と heightPx
• knownViewport
• logicalUnit

ingest_figma_source

Figma MCP ノード JSON、任意のスクリーンショット、またはその両方を登録します。

出力：

source/design-source-manifest.json
figma/figma-source-dataset.json

主な入力：

• runRoot
• figma.fileKey
• figma.nodeId
• nodeJson または nodeJsonPath
• screenshotPath
• figmaBounds

slice_image_assets

source_bbox エントリを含む layers.manifest.json を使って、ソース画像からビットマップ／アイコンのアセットを切り出します。

このツールはオプトイン方式であり、デコード、計画、ターゲット IR、コード生成の各フローには影響しません。

レイヤーマニフェストの例：

[
  {
    "id": "icon-tab-home",
    "type": "bitmap",
    "source_bbox": { "x": 120, "y": 980, "width": 72, "height": 72 },
    "asset": "icon-tab-home.png",
    "transparent_required": true,
    "z_index": 20
  }
]

一般的なツール入力：

{
  "runRoot": "/path/to/run",
  "sourcePath": "/path/to/source.png",
  "layersManifestPath": "/path/to/layers.manifest.json",
  "canvasWidth": 750,
  "onlyType": "bitmap"
}

デフォルトの出力：

assets/slices/<asset>.png
assets/slices/layers.manifest.normalized.json
qa/bbox-preview.svg
qa/png-asset-audit.json

スライサーはソース画像のピクセル単位の正確なバウンディングボックスを使用し、出力キャンバスを自動トリミングすることはありません。ソースのピクセルとアルファ値を保持します。外部のアルファ対応画像デコーダーがない場合、背景の除去は実行されません。そのため、アルファに関する検査ができない場合、監査レポートでは該当する検査を利用不可として示します。

build_reference_analysis

Vision IR の前に、モデル生成の Reference Image Analysis を登録します。元のピクセルサイズ、ルートフレーム、セマンティックなトップレベルグループ、テキスト／メディア／アイコン／マテリアルのインベントリー、下部ナビゲーション、厳密な抽出設定、高リスク領域、後続のデコードで使用する監査計画を記録します。

artifactPath がない場合、ツールはスキーマと参照パスを返します。

デフォルトのアーティファクトタイプ：

reference_analysis

build_semantic_ir

モデル生成の Platform-neutral Semantic UI IR を登録します。

artifactPath がない場合、ツールはスキーマと参照パスを返します。

デフォルトのアーティファクトタイプ：

platform_neutral_semantic_ui_ir

build_cross_platform_nodes

Cross-platform Node Data を登録します。

artifactPath がない場合、ツールは必須のスキーマ契約を返します。

デフォルトのアーティファクトタイプ：

cross_platform_node_data

build_target_ir

選択したターゲット向けのターゲットプラットフォームのレイアウト IR を登録します。

スキーマヒントの選択：

• Android ターゲットでは、Android レイアウトスキーマを使用します。
• ios-uikit では、UIKit レイアウトスキーマを使用します。
• ios-swiftui では、iOS SwiftUI レイアウトスキーマを使用します。
• その他のターゲットでは、Web React レイアウトスキーマを使用します。

run_codegen

実装の出力と検証サマリーを記録しますが、ビジュアルレビューは必須にしません。

出力：

review/codegen-result.json

run_codegen_with_auto_review

実装の出力とビジュアルレビューの証跡を記録します。

visualReviewResultPath が指定されている場合、次の条件を満たしたときにのみ納品準備が完了します。

review.status == "passed"
minimum non-material similarity >= 0.9

出力：

review/codegen-with-auto-review-result.json

validate_pipeline

既存の実行を検証します。必須アーティファクトと、Vision、Compression、Semantic、Cross-platform、Target Planning の各アーティファクト間のトレーサビリティリンクを確認します。

audit_image_decoding

スクリーンショット／画像のデコードアーティファクトを監査します。参照分析がソースの寸法と一致していること、トップレベルグループが範囲内に収まっていること、監査セクションが存在すること、テキストランにフォントメトリクスが含まれていること、メディア／アイコン領域が網羅されていること、セマンティックノードにトレーサビリティが維持されていること、1 行テキストに折り返しのリスクがないこと、下部ナビゲーションにスロットが公開されていること、不確かなノードに代替候補が用意されていることを確認します。

デフォルトの出力：

qa/image-decoding-audit.json

cleanup_design_run

デフォルトでは、アーティファクトのクリーンアップをドライランモードで実行します。

次を使用します。

{ "runRoot": "/path/to/run", "apply": false }

対象となるアーティファクトを実際に削除する場合にのみ、apply: true を設定してください。

一般的なワークフロー

スクリーンショットから Web コードへ

1. ユーザーがモードを選択していない場合は、get_run_modes を呼び出します。
2. mode: "codegen" または mode: "codegen-with-auto-review"、および targets: ["web-react"] を指定して create_design_run を呼び出します。
3. ソースのスクリーンショットを指定して ingest_image_source を呼び出します。
4. スクリーンショットの構造を分析した後、build_reference_analysis を呼び出します。
5. Semantic UI IR、Cross-platform Node Data、Target Layout IR を生成または登録します。
6. Vision／Compression／Semantic のアーティファクトが利用可能になった後、audit_image_decoding を呼び出します。
7. ホストプロジェクトでコードを実装します。
8. run_codegen または run_codegen_with_auto_review を呼び出します。
9. validate_pipeline を呼び出します。

Figma ハイブリッドからターゲット IR へ

1. Figma MCP を通じて Figma ノード JSON を取得します。
2. 対応する Figma フレームのスクリーンショットを撮影するか、指定します。
3. mode: "target-ir" とターゲットプラットフォームを指定して create_design_run を呼び出します。
4. nodeJson と screenshotPath を指定して ingest_figma_source を呼び出します。
5. ターゲットレイアウト IR を生成します。
6. build_target_ir を呼び出します。
7. validate_pipeline を呼び出します。

スクリーンショットアセットの正確な切り出し

1. create_design_run を呼び出します。
2. ingest_image_source を呼び出します。
3. ビットマップ／アイコンレイヤーのソースピクセル座標のバウンディングボックスを含む layers.manifest.json を作成します。
4. slice_image_assets を呼び出します。
5. 生成されたコードで assets/slices/ を使用します。
6. qa/bbox-preview.svg と qa/png-asset-audit.json を確認します。

更新とバージョン管理

クライアント設定をチャンネルに更新します：

npx -y ui-design-to-code-mcp@latest update \
  --clients cursor,claude-code,codex \
  --channel latest

固定バージョンをインストールします：

npx -y [email protected] install \
  --client codex \
  --package-spec [email protected]

安定した本番環境では固定バージョンを使用してください。Codex の日次アップデーターや npx ベースのクライアントで今後のリリースを取得する場合は、@latest を使用してください。

開発

チェックを実行します：

npm run check
npm run release:check

パッケージのドライラン：

npm pack --dry-run

リリース

推奨される npm の公開リリース手順：

1. npm Trusted Publishing を設定します：

   node bin/ui-design-to-code-mcp.js configure-npm-trusted-publishing --dry-run
   

2. main から GitHub Actions の Release ワークフローを実行します。

このワークフローは GitHub Actions の OIDC（id-token: write）を使用し、NPM_TOKEN や長期有効な MCP Registry トークンは必要ありません。npm アカウントでは 2FA を有効にしておいてください。

リリース、レジストリ、ロールバック、セキュリティポリシーの詳細については、以下を参照してください：

• RELEASE.md
• SECURITY.md

リポジトリ

https://github.com/Kinglions/ui-design-to-code-mcp.git