UI Design to Code

UI Design to Code MCP

中文 | English

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.

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

Use it when you need more than a one-shot screenshot-to-code prompt:

• Decode UI screenshots and Figma data into source manifests, reference analysis, Vision IR, Node Compression IR, and Semantic UI node trees.
• Preserve traceability from generated code plans back to visual primitives, grouped candidates, and source pixels.
• Generate adapter-ready artifacts for Web, iOS, Android, and other UI implementation targets.
• Run audit gates for text overflow, media coverage, navigation structure, visual review evidence, and cleanup.

Links:

• 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
• Quick feedback: 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 design-to-code 流程的 MCP server。它可以把 UI 截图、Figma MCP 节点 JSON，或 Figma 节点 + 截图的混合输入，接入一套结构化、可追踪、可校验的产物流水线。

它不替代真正写代码的 agent/model。它的职责是标准化运行目录、输入清单、Figma 数据集、中间 IR 合约、目标平台布局产物、代码生成记录、精确切图产物、视觉验收门禁、产物校验和清理流程。

功能介绍

适用场景

• 需要把 UI 截图、参考图、GPT Image mockup、Figma URL、Figma MCP 节点 JSON 或 Figma 导出图转成可追踪的设计实现流程。
• 需要先解析设计结构、节点树、布局语义、组件层级、状态和资产，再进入代码实现。
• 需要 Web、iOS、Android 等多目标平台的 Target Layout IR 或实现计划。
• 需要对生成实现做截图验收、视觉差异复核、文本溢出检查、底部导航检查、资产覆盖检查和产物清理。

不适用场景

• 只想让模型基于一张图直接写最终代码，且不需要中间产物、追踪关系或验收证据。
• 纯 MCP 安装、版本、doctor、配置排查请求；这类请求不应该创建 design run。
• 没有设计源，也没有 design-to-code / design-decoding 意图的普通前端开发任务。

核心能力

• 支持 Codex、Cursor、Claude Code。
• 创建隔离的标准运行目录：generated/ui-design-to-code/ 或 /private/tmp/ui-design-to-code/ 。
• 统一接入截图、图片、Figma 节点 JSON、Figma + 截图混合输入。
• 覆盖完整流程：decode、planning、target IR、codegen、自动视觉验收、runtime review、validate、cleanup。
• 提供 Semantic UI IR、Cross-platform Node Data、Target Layout IR、视觉验收、产物生命周期等 schema 合约。
• 支持基于 source_bbox 的源图精确 bitmap/icon 切图。
• Codex 安装后使用本地稳定 serve 命令，避免每次 MCP 启动都执行 npx @latest。

产出物

• artifact-run-manifest.json：一次运行的产物清单、保留策略和清理边界。
• 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 token：

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

该命令会提示粘贴 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 token：

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 token 检测不符合预期、视觉还原不稳定、资产同步路径错误、运行时验收失败或文档示例缺失，可以直接提交反馈：

• 快捷反馈：https://github.com/Kinglions/ui-design-to-code-mcp/issues/new?title=%5BFeedback%5D%20
• Bug / 功能请求 / 使用问题：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 mockup、Figma URL / node-id、Figma MCP 节点 JSON、Figma 截图或导出图。

不要为 MCP 存在性、版本、安装、doctor 或路由排查请求创建 run，除非用户同时提供设计源并要求解析、实现或视觉验收。

1. 如果流程包含 Figma 设计稿，先调用 check_figma_token。

• token 缺失时，直接要求用户输入 Figma token；收到后调用 configure_figma_token 自动写入全局 Codex 配置，不要创建 run。
• 只有交互式自动写入不可用时，才提示备用命令 ui-design-to-code-mcp setup-figma-token。
• token 已配置后，继续进入执行模式选择。

1. 用户没有显式指定模式时，再调用 get_run_modes，把返回的模式选择提示展示给用户。

• recommendedMode 只能作为默认高亮选项，不能当作用户已同意。
• 用户必须选择 decode-only、plan-only、target-ir、codegen、codegen-with-auto-review 或 runtime-review 之一。

1. 用户确认模式后，再调用 create_design_run 创建独立产物运行目录。
2. 使用 ingest_image_source 或 ingest_figma_source 登记源输入。

• ingest_figma_source 支持两种来源：外部已获取的 Figma 节点 JSON，或 Figma URL / fileKey / nodeId + token 直连 Figma REST API 由本 MCP 自行拉取节点树、截图和 image fills。

1. 对截图/图片输入，先生成并用 build_reference_analysis 登记 Reference Image Analysis。
2. 生成并登记 Semantic UI IR、Cross-platform Node Data、Target Layout IR。
3. 当已有 Vision/Compression/Semantic 产物后，调用 audit_image_decoding 审计图片解析质量。
4. 在宿主项目中生成或修改目标代码。
5. 使用 run_codegen 或 run_codegen_with_auto_review 记录结果。
6. 调用 validate_pipeline 校验完整产物链路。
7. 需要时使用 cleanup_design_run 清理生成产物。

当前流程优化建议

当前流程已经具备 token gate、mode gate、独立 runRoot、manifest 追踪、结构校验、视觉验收和 cleanup dry-run。后续更值得优化的是下面几类：

• IR 自动生成边界：MCP 当前负责登记、校验和追踪产物；Vision IR、Compression IR、Semantic IR 和真实代码仍由调用 agent/model 生成。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 asset 下载可以进一步用 hash 去重，减少多轮 review 产生的重复图片。

执行模式

目标平台示例：

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

For cocos-creator, the target contract is Cocos Creator 3.x TypeScript. It uses a Canvas design-resolution policy, preserves aspect ratio, selects one proportional mode per orientation (fit_width, fit_height, show_all, or explicitly justified no_border), uses SafeArea/Widget for controls, a Node + Component hierarchy, UITransform/Widget/Layout, explicit ScrollView view/content nodes, and assets under assets/. It does not generate DOM/CSS, ExactFit-style distortion, or per-device-pixel breakpoints. See references/cocos-creator-development-rules.md and references/platform-adapters/cocos-creator.adapter-contract.json.

输入源选择

能同时拿到 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 server：

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 server 时生效。

Codex 配置示例：

[mcp_servers.ui_design_to_code]

command = "/Users/ /.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 设计或 design-to-code 任务，但没有明确指定模式时，应先调用它。

典型输入：

{ "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
• `downloadAsset