The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the UI Design to Code listing page.
MCP server for Codex, Cursor, and Claude Code that turns UI screenshots, source images, Figma MCP node JSON, and Figma-plus-screenshot hybrid input into traceable design-to-code artifacts.
Use it when you need more than a one-shot screenshot-to-code prompt:
Links:
io.github.Kinglions/ui-design-to-code-mcpui-design-to-code-mcp 是一个用于 UI design-to-code 流程的 MCP server。它可以把 UI 截图、Figma MCP 节点 JSON，或 Figma 节点 + 截图的混合输入，接入一套结构化、可追踪、可校验的产物流水线。
它不替代真正写代码的 agent/model。它的职责是标准化运行目录、输入清单、Figma 数据集、中间 IR 合约、目标平台布局产物、代码生成记录、精确切图产物、视觉验收门禁、产物校验和清理流程。
generated/ui-design-to-code/<run-id> 或 /private/tmp/ui-design-to-code/<run-id>。source_bbox 的源图精确 bitmap/icon 切图。npx @latest。artifact-run-manifest.json：一次运行的产物清单、保留策略和清理边界。design-source-manifest.json / source image manifest：设计源、像素尺寸、坐标系和输入假设。figma-source-dataset.json：Figma 节点、样式、组件、注释、截图和资产下载信息。配置 Figma token：
该命令会提示粘贴 token，并写入 ~/.codex/config.toml 的
[mcp_servers.ui_design_to_code.env]。如果要在脚本里使用：
配置 Figma token：
如果你在使用中遇到模式选择不清晰、Figma token 检测不符合预期、视觉还原不稳定、资产同步路径错误、运行时验收失败或文档示例缺失，可以直接提交反馈：
提交时建议附带：
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 mockup、Figma URL / node-id、Figma MCP 节点 JSON、Figma 截图或导出图。
不要为 MCP 存在性、版本、安装、doctor 或路由排查请求创建 run，除非用户同时提供设计源并要求解析、实现或视觉验收。
check_figma_token。
configure_figma_token 自动写入全局 Codex 配置，不要创建 run。ui-design-to-code-mcp setup-figma-token。get_run_modes，把返回的模式选择提示展示给用户。
recommendedMode 只能作为默认高亮选项，不能当作用户已同意。decode-only、plan-only、target-ir、codegen、codegen-with-auto-review 或 runtime-review 之一。create_design_run 创建独立产物运行目录。ingest_image_source 或 ingest_figma_source 登记源输入。
ingest_figma_source 支持两种来源：外部已获取的 Figma 节点 JSON，或 Figma URL / fileKey / nodeId + token 直连 Figma REST API 由本 MCP 自行拉取节点树、截图和 image fills。build_reference_analysis 登记 Reference Image Analysis。audit_image_decoding 审计图片解析质量。run_codegen 或 run_codegen_with_auto_review 记录结果。validate_pipeline 校验完整产物链路。cleanup_design_run 清理生成产物。当前流程已经具备 token gate、mode gate、独立 runRoot、manifest 追踪、结构校验、视觉验收和 cleanup dry-run。后续更值得优化的是下面几类：
codegen-with-auto-review 和 runtime-review 需要宿主项目具备可运行命令、截图入口和目标页面定位。缺少这些条件时，应明确返回 blocked，而不是把未截图的实现标记为可交付。validate_pipeline 目前偏结构性、依赖少。未来可以在不显著增加安装成本的前提下，引入更完整的 JSON Schema 校验。| 模式 | 是否需要 target | 主要用途 |
|---|---|---|
decode-only | 否 | 只采集源输入、vision/compression/semantic 产物，不生成平台计划或代码。 |
plan-only | 否 | 生成跨平台节点数据和转换计划，不生成目标布局或代码。 |
target-ir | 是 | 登记目标平台布局 IR，不修改代码。 |
codegen | 是 | 生成或修改实现代码，并记录常规验证结果。 |
codegen-with-auto-review | 是 | 记录代码生成、视觉验收依据，并执行相似度门禁。 |
runtime-review | 是 | 对已有运行时实现进行截图验收，不修改代码。 |
目标平台示例：
| 输入类型 | 适用场景 | 推荐工具 |
|---|---|---|
| 截图或图片 | 设计源是渲染后的图像。 | 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。
项目内默认目录：
临时运行目录：
Codex 安装器会写入用户级 MCP 配置，并让运行时启动路径脱离网络依赖。
Codex plugin marketplace 安装：
安装后检查 MCP server：
该插件会把 ui_design_to_code 注册为：
仍然可以使用 npm 方式直接安装 MCP：
安装包路径：
Codex serve 命令：
macOS 每日更新任务：
更新命令：
当安装规格是 ui-design-to-code-mcp@latest 时，更新脚本每天 04:15 检查一次 npm latest，只有版本变化时才下载更新。更新后的包会在 Codex 下一次启动或重新加载该 MCP server 时生效。
Codex 配置示例：
卸载：
项目级配置：
安装：
卸载：
项目级安装：
用户级安装：
get_run_modes返回支持的执行模式、目标平台、触发示例和模式选择提示。
当用户提供 UI 截图、参考图、Figma 设计或 design-to-code 任务，但没有明确指定模式时，应先调用它。
典型输入：
create_design_run创建运行目录和 artifact-run-manifest.json。
关键入参：
workspace：生成目录所在项目根目录。slug：可读的 run 名称后缀。mode：执行模式。targets：target/codegen/review 模式必填。useTmp：为 true 时写入 /private/tmp。返回：
runRootmanifestPathmodeingest_image_source把截图或图片登记为源输入。
输出：
关键入参：
runRootimagePathsourceIdwidthPx、heightPxknownViewportlogicalUnitingest_figma_source登记 Figma 输入源。支持：
figma.fileKey / figma.nodeId，并通过 apiToken 或环境变量（默认尝试 FIGMA_API_TOKEN、FIGMA_ACCESS_TOKEN、FIGMA_OAUTH_TOKEN）让 MCP 直接调用 Figma REST API。projectRoot，MCP 会在下载完成后把资产自动同步到目标工程的默认资源目录，同时保留 runRoot 中的归档副本。输出：
关键入参：
runRootfigmaUrlfigma.fileKeyfigma.nodeIdnodeJson 或 nodeJsonPathscreenshotPathfigmaBoundsfetchFromApiapiToken / tokenEnvVardownloadScreenshotdownloadAssetsscreenshotScaleprojectRoot资源同步规则：
web-react / web-next：默认同步到 public/ui-design-to-code/figma/...；若无 public/，回退到 src/assets/ui-design-to-code/figma/...ios-uikit / ios-swiftui：优先同步到首个发现的 .xcassets，自动创建 .imagesetandroid-compose / android-view：默认同步到 app/src/main/res/drawable；若无则搜索 src/main/res也可以显式单独调用：
如果缺少 token，MCP 会要求用户直接输入 Figma token，并通过 configure_figma_token 自动写入全局 Codex 配置；只有自动配置不可用时，才使用备用命令：
slice_image_assets根据 layers.manifest.json 中的 source_bbox，从源图精确裁切 bitmap/icon 资源。
这是显式调用的独立工具，不会改变 decode、plan、target IR 或 codegen 的默认流程。
输入 manifest 示例：
典型 tool 入参：
默认输出：
切图脚本使用源图像素坐标，不自动 trim，不改变输出画布尺寸。它会保留源像素和源 alpha。当前版本不引入额外图像依赖，因此不做背景抠除；当无法读取 alpha 细节时，审计报告会把透明/贴边检查标记为不可用。
build_reference_analysis登记模型生成的 Reference Image Analysis。它位于 Vision IR 之前，用来记录原始像素尺寸、根画板、语义顶层分组、文本/媒体/图标/材质清单、底部导航、严格提取设置、高风险区域和后续审计计划。
如果没有传 artifactPath，工具会返回需要生成该产物的 schema 和参考说明。
默认 artifact type：
build_semantic_ir登记 model 生成的 Platform-neutral Semantic UI IR。
如果没有传 artifactPath，工具会返回需要生成该产物的 schema 和参考说明。
默认 artifact type：
build_cross_platform_nodes登记 Cross-platform Node Data。
如果没有传 artifactPath，工具会返回对应 schema 合约。
默认 artifact type：
build_target_ir登记目标平台布局 IR。
schema 提示按 target 名称选择：
ios-uikit 使用 UIKit layout schema。ios-swiftui 使用 iOS SwiftUI layout schema。run_codegen记录实现代码变更和常规验证结果，不执行视觉验收门禁。
输出：
run_codegen_with_auto_review记录代码生成结果和视觉验收依据。
当提供 visualReviewResultPath 时，只有满足下面条件才标记为可交付：
输出：
validate_pipeline校验现有 run 的跨产物链路。它会检查必需产物是否存在，以及 vision、compression、semantic、cross-platform、target planning 之间的 traceability 是否一致。
audit_image_decoding审计截图/图片解析产物。它会检查 reference analysis 是否匹配源图尺寸、顶层分组是否越界、审计章节是否齐全、文本是否有字体度量、媒体/图标区域是否被纳入、semantic node 是否保留 traceability、单行文本是否存在换行风险、底部导航是否包含槽位，以及低置信节点是否提供 alternatives。
默认输出：
cleanup_design_run运行产物清理，默认 dry-run。
典型入参：
只有确认要删除可清理产物时，才设置 apply: true。
get_run_modes。create_design_run，选择 mode: "codegen" 或 mode: "codegen-with-auto-review"，并设置 targets: ["web-react"]。ingest_image_source 登记截图。build_reference_analysis。audit_image_decoding。run_codegen 或 run_codegen_with_auto_review。validate_pipeline。create_design_run，设置 mode: "target-ir" 和目标平台。ingest_figma_source，传入 nodeJson 和 screenshotPath。build_target_ir 登记产物。validate_pipeline。create_design_run。ingest_image_source。layers.manifest.json。slice_image_assets。assets/slices/ 下的 PNG。qa/bbox-preview.svg 和 qa/png-asset-audit.json。更新客户端配置到指定 channel：
安装固定版本：
稳定生产环境建议使用固定版本。需要 Codex 每日自动更新或 npx 客户端动态获取新版时，使用 @latest。
运行校验：
打包预览：
推荐公共 npm 发布路径：
配置 npm Trusted Publishing：
从 main 分支触发 GitHub Actions 的 Release workflow。
Release workflow 使用 GitHub Actions OIDC（id-token: write），不需要 NPM_TOKEN 或长期 MCP Registry token。npm 账号 2FA 应保持开启。
完整发布、Registry、回滚和安全策略见：
ui-design-to-code-mcp is an MCP server that standardizes the artifact pipeline for converting UI screenshots, Figma MCP node JSON, or Figma-plus-screenshot hybrid sources into implementation-ready design-to-code outputs.
It does not replace the coding agent or model. Instead, it gives agents a reliable workflow for run directories, source manifests, Figma datasets, intermediate IR contracts, target layout artifacts, codegen records, asset slicing outputs, visual review gates, validation, and cleanup.
generated/ui-design-to-code/<run-id> or /private/tmp/ui-design-to-code/<run-id>.source_bbox layer manifests.npx @latest on every startup.artifact-run-manifest.json: run-level artifact list, retention policy, and cleanup boundary.design-source-manifest.json / source image manifest: source metadata, pixel size, coordinate system, and assumptions.figma-source-dataset.json: Figma nodes, styles, components, comments, screenshots, and asset download metadata.Use these links when mode selection is unclear, Figma token detection does not behave as expected, visual restoration is unstable, asset sync paths are wrong, runtime review is blocked, or documentation examples are missing:
Useful details to include:
decode-only, plan-only, target-ir, codegen, codegen-with-auto-review, or runtime-review.web-react, web-next, ios-uikit, ios-swiftui, android-compose, or android-view.artifact-run-manifest.json, validate_pipeline output, visual-review-result.json, or doctor output.get_run_modes when the user has not specified one.create_design_run.ingest_image_source or ingest_figma_source.build_reference_analysis.audit_image_decoding when Vision/Compression/Semantic artifacts exist.run_codegen or run_codegen_with_auto_review.validate_pipeline.cleanup_design_run.The current workflow already has token gating, mode gating, isolated run roots, manifest traceability, structural validation, visual review, and cleanup dry-runs. The next high-value improvements are:
codegen-with-auto-review and runtime-review need runnable host-app commands, screenshot capture configuration, and page routing. Missing prerequisites should return blocked, not deliverable.validate_pipeline is intentionally lightweight and structural. A future version can add deeper JSON Schema validation if dependency impact is acceptable.| Mode | Target required | Main use |
|---|---|---|
decode-only | No | Capture source manifests, vision/compression/semantic artifacts. No target plan or code. |
plan-only | No | Add cross-platform node data and conversion planning. No target layout or code. |
target-ir | Yes | Register target-platform layout IR. No code changes. |
codegen | Yes | Generate or modify implementation code and record validation. |
codegen-with-auto-review | Yes | Record codegen plus visual review evidence and similarity gate. |
runtime-review | Yes | Review an existing runtime implementation against the source. No code changes. |
Target platform examples:
| Source type | Use when | Recommended tool |
|---|---|---|
| Screenshot or image | The design source is a rendered image. | ingest_image_source |
| Figma MCP node JSON | You need structure, names, text, components, styles, and layout metadata. | ingest_figma_source |
| Figma node JSON + screenshot | You need both structural metadata and pixel-level visual truth. | ingest_figma_source |
Hybrid Figma input is preferred when available because Figma nodes provide structure while screenshots provide the pixel baseline for visual review.
Every workflow starts with create_design_run, which creates a dedicated runRoot and an artifact-run-manifest.json.
Project run layout:
Temporary runs use:
The Codex installer writes a user-level MCP config and keeps runtime startup off the network path.
Codex plugin marketplace install:
After installation, verify the MCP server:
The plugin registers ui_design_to_code with:
Direct npm-based MCP install remains available:
Installed package:
Codex serve command:
Daily updater on macOS:
Updater command:
When the install spec is ui-design-to-code-mcp@latest, the updater checks npm once per day at 04:15 and downloads a new version only when npm latest changes. The updated package is used the next time Codex starts or reloads this MCP server.
Codex config example:
Uninstall:
Project config:
Install:
Uninstall:
Project install:
User-scope install:
get_run_modesReturns supported modes, target platforms, trigger examples, and the mode-selection prompt.
Use it when the user provides a UI screenshot, reference image, Figma design, or design-to-code request without naming a mode.
Typical input:
create_design_runCreates the run directory and artifact-run-manifest.json.
Key inputs:
workspace: project root for generated outputs.slug: readable run suffix.mode: one supported execution mode.targets: required for target/codegen/review modes.useTmp: writes under /private/tmp when true.Returns:
runRootmanifestPathmodeingest_image_sourceRegisters a screenshot or image into:
Key inputs:
runRootimagePathsourceIdwidthPx and heightPx when size cannot be inferredknownViewportlogicalUnitingest_figma_sourceRegisters Figma MCP node JSON, an optional screenshot, or both.
Outputs:
Key inputs:
runRootfigma.fileKeyfigma.nodeIdnodeJson or nodeJsonPathscreenshotPathfigmaBoundsslice_image_assetsCrops bitmap/icon assets from a source image using a layers.manifest.json with source_bbox entries.
This tool is opt-in and does not alter decode, planning, target IR, or codegen flows.
Layer manifest example:
Typical tool input:
Default outputs:
The slicer uses exact source pixel bboxes and never auto-trims output canvases. It preserves source pixels and source alpha. Background removal is not performed without an external alpha-capable image decoder, so the audit report marks alpha-specific checks as unavailable when it cannot inspect them.
build_reference_analysisRegisters model-generated Reference Image Analysis before Vision IR. This captures the original pixel size, root frame, semantic top-level groups, text/media/icon/material inventory, bottom navigation, strict extraction settings, high-risk zones, and the audit plan used for later decoding.
When artifactPath is missing, the tool returns the schema and reference path.
Default artifact type:
build_semantic_irRegisters model-generated Platform-neutral Semantic UI IR.
When artifactPath is missing, the tool returns the schema and reference path.
Default artifact type:
build_cross_platform_nodesRegisters Cross-platform Node Data.
When artifactPath is missing, the tool returns the required schema contract.
Default artifact type:
build_target_irRegisters target-platform layout IR for a selected target.
Schema hint selection:
ios-uikit uses the UIKit layout schema.ios-swiftui uses the iOS SwiftUI layout schema.run_codegenRecords implementation output and validation summary without enforcing visual review.
Output:
run_codegen_with_auto_reviewRecords implementation output plus visual review evidence.
When visualReviewResultPath is provided, delivery is ready only when:
Output:
validate_pipelineValidates an existing run by checking required artifacts and traceability links between vision, compression, semantic, cross-platform, and target planning artifacts.
audit_image_decodingAudits screenshot/image decoding artifacts. It checks that reference analysis matches source dimensions, top-level groups stay in bounds, audit sections are present, text runs carry font metrics, media/icon regions are accounted for, semantic nodes keep traceability, single-line text avoids wrap risk, bottom navigation exposes slots, and uncertain nodes provide alternatives.
Default output:
cleanup_design_runRuns artifact cleanup in dry-run mode by default.
Use:
Set apply: true only when cleanup should actually remove eligible artifacts.
get_run_modes if the user has not chosen a mode.create_design_run with mode: "codegen" or mode: "codegen-with-auto-review" and targets: ["web-react"].ingest_image_source with the source screenshot.build_reference_analysis after analyzing the screenshot structure.audit_image_decoding after Vision/Compression/Semantic artifacts are available.run_codegen or run_codegen_with_auto_review.validate_pipeline.create_design_run with mode: "target-ir" and the target platform.ingest_figma_source with nodeJson and screenshotPath.build_target_ir.validate_pipeline.create_design_run.ingest_image_source.layers.manifest.json with source pixel bboxes for bitmap/icon layers.slice_image_assets.assets/slices/ in generated code.qa/bbox-preview.svg and qa/png-asset-audit.json.Update client configs to a channel:
Install a pinned version:
Use pinned versions for stable production environments. Use @latest when you want the Codex daily updater or npx-based clients to pick up future releases.
Run checks:
Package dry run:
Recommended public npm release path:
Configure npm Trusted Publishing:
Trigger the GitHub Actions Release workflow from main.
The workflow uses GitHub Actions OIDC (id-token: write) and does not require NPM_TOKEN or a long-lived MCP Registry token. Keep npm account 2FA enabled.
For full release, registry, rollback, and security policy, see: