UI Design to Code

Name: UI Design to Code
Author: Kinglions

本地服务

github.com/Kinglions开发工具02 周前更新

代码仓库

关于 UI Design to Code

UI Design to Code 是面向 Codex、Cursor 和 Claude Code 的 MCP 服务，用于组织截图与 Figma 输入，生成可追踪的设计产物并校验流程；代码仍由调用它的 Agent 或模型生成。

主要功能

01接入截图和 Figma 数据
02创建可追踪的设计产物与 IR
03为多平台准备布局产物
04记录代码生成和视觉审查
05校验并清理流程产物
06从源图裁切位图和图标资源

适用场景

01将截图或 Figma 输入整理为结构化实现流程
02为 Web、iOS 或 Android 准备目标布局
03对照截图审查生成的 UI 实现
04整理并审计中间设计产物

MCP 相关

它向 MCP 客户端提供创建设计运行、接入图片与 Figma、追踪产物、校验及清理的工具。服务负责组织和检查流程；IR 与代码由调用它的 Agent 或模型生成。

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

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

启动命令npx -y ui-design-to-code-mcp

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npmui-design-to-code-mcp0.1.12stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

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/<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、视觉验收、产物生命周期等 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 输出。

当前流程优化建议

当前流程已经具备 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 产生的重复图片。

执行模式

模式	是否需要 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

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.

输入源选择

输入类型	适用场景	推荐工具
截图或图片	设计源是渲染后的图像。	`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 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/<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 设计或 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 输入源。支持：

传入现成 Figma 节点 JSON。
提供 Figma URL / figma.fileKey / figma.nodeId，并通过 apiToken 或环境变量（默认尝试 FIGMA_API_TOKEN、FIGMA_ACCESS_TOKEN、FIGMA_OAUTH_TOKEN）让 MCP 直接调用 Figma REST API。
在 1 或 2 的基础上附带截图，或让 MCP 自动导出截图和 target-aware 资产。
如果同时提供 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

如果缺少 token，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`

登记 model 生成的 Platform-neutral Semantic UI IR。

如果没有传 artifactPath，工具会返回需要生成该产物的 schema 和参考说明。

默认 artifact type：

platform_neutral_semantic_ui_ir

`build_cross_platform_nodes`

登记 Cross-platform Node Data。

如果没有传 artifactPath，工具会返回对应 schema 合约。

默认 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 代码

用户未指定模式时，调用 get_run_modes。
调用 create_design_run，选择 mode: "codegen" 或 mode: "codegen-with-auto-review"，并设置 targets: ["web-react"]。
调用 ingest_image_source 登记截图。
分析截图结构后调用 build_reference_analysis。
生成或登记 Semantic UI IR、Cross-platform Node Data、Target Layout IR。
Vision/Compression/Semantic 产物就绪后调用 audit_image_decoding。
在宿主项目里实现代码。
调用 run_codegen 或 run_codegen_with_auto_review。
调用 validate_pipeline。

Figma Hybrid 到 Target IR

通过 Figma MCP 获取节点 JSON。
提供或截取同一 frame 的截图。
调用 create_design_run，设置 mode: "target-ir" 和目标平台。
调用 ingest_figma_source，传入 nodeJson 和 screenshotPath。
生成目标平台 Layout IR。
调用 build_target_ir 登记产物。
调用 validate_pipeline。

截图精确切图

调用 create_design_run。
调用 ingest_image_source。
创建包含源图像素 bbox 的 layers.manifest.json。
调用 slice_image_assets。
在生成代码中使用 assets/slices/ 下的 PNG。
检查 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 发布路径：

配置 npm Trusted Publishing：

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

从 main 分支触发 GitHub Actions 的 Release workflow。

Release workflow 使用 GitHub Actions OIDC（id-token: write），不需要 NPM_TOKEN 或长期 MCP Registry token。npm 账号 2FA 应保持开启。

完整发布、Registry、回滚和安全策略见：

仓库

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

English

ui-design-to-code-mcp 是一款 MCP 服务，用于标准化将 UI 截图、Figma MCP 节点 JSON 或 Figma 与截图混合来源转换为可用于实现的设计转代码产物的工作流。

它不会取代编码 Agent 或模型，而是为 Agent 提供可靠的工作流，用于管理运行目录、源清单、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、视觉审核和产物生命周期提供基于 schema 的契约。
支持使用显式 source_bbox 图层清单对源图像进行精确资源切片。
通过安装稳定的本地 MCP 服务命令，而非每次启动都运行 npx @latest，优化 Codex 启动速度。

输出

artifact-run-manifest.json：运行级产物列表、保留策略和清理边界。
design-source-manifest.json / source image manifest：源元数据、像素尺寸、坐标系和假设。
figma-source-dataset.json：Figma 节点、样式、组件、评论、截图和资源下载元数据。
参考图像分析、视觉 IR、节点压缩 IR、语义 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
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 节点 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 输出。

当前工作流优化说明

当前工作流已具备令牌门控、模式门控、隔离的运行根目录、清单可追溯性、结构验证、视觉审核和清理试运行。下一步最有价值的改进包括：

IR 生成边界：MCP 负责注册、验证和跟踪产物；调用它的 Agent/模型仍负责生成视觉 IR、压缩 IR、语义 IR 和实现代码。
运行时审核前提条件：codegen-with-auto-review 和 runtime-review 需要可运行的宿主应用命令、截图捕获配置和页面路由。缺少前提条件时应返回受阻状态，而不是可交付状态。
架构验证深度：validate_pipeline 有意保持轻量且侧重结构。未来版本可在依赖影响可接受的前提下，增加更深入的 JSON Schema 验证。
产物大小与孤立文件审计：当前大小统计仅涵盖清单中列出的文件。未来审计可报告 runRoot 中未注册的文件，但不删除这些文件。
版本管理：修补/审核循环应记录 supersedes 关系，以便将失败的旧版本纳入可清理范围。
资源去重：源裁剪图和 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 服务命令：

~/.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`

输出：

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

切片器使用精确的源像素边界框，绝不会自动裁剪输出画布。它会保留源像素和源 alpha。若没有外部支持 alpha 的图像解码器，则不会移除背景；因此，当无法检查 alpha 时，审计报告会将 alpha 专项检查标记为不可用。

`build_reference_analysis`

在 Vision IR 之前注册模型生成的参考图像分析。该分析会记录原始像素尺寸、根框架、顶层语义组、文本／媒体／图标／材质清单、底部导航、严格提取设置、高风险区域，以及后续解码所用的审计计划。

缺少 artifactPath 时，工具会返回架构和参考路径。

默认工件类型：

reference_analysis

`build_semantic_ir`

注册模型生成的平台无关语义 UI IR。

缺少 artifactPath 时，工具会返回架构和参考路径。

默认工件类型：

platform_neutral_semantic_ui_ir

`build_cross_platform_nodes`

注册跨平台节点数据。

缺少 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`

通过检查必需工件以及视觉、压缩、语义、跨平台和目标规划工件之间的可追溯链接，验证现有运行。

`audit_image_decoding`

审计截图／图像解码工件。它会检查参考分析是否与源图像尺寸一致、顶层组是否位于边界内、是否包含审计部分、文本段是否带有字体度量、媒体／图标区域是否均已核算、语义节点是否保留可追溯性、单行文本是否避免换行风险、底部导航是否提供插槽，以及不确定节点是否提供备选项。

默认输出：

qa/image-decoding-audit.json

`cleanup_design_run`

默认以试运行模式清理工件。

使用：

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

仅当确实要删除符合条件的工件时，才设置 apply: true。

常见工作流

截图转 Web 代码

如果用户尚未选择模式，请调用 get_run_modes。
调用 create_design_run，设置 mode: "codegen" 或 mode: "codegen-with-auto-review"，并设置 targets: ["web-react"]。
使用源截图调用 ingest_image_source。
分析截图结构后，调用 build_reference_analysis。
生成或注册语义 UI IR、跨平台节点数据和目标布局 IR。
视觉／压缩／语义工件就绪后，调用 audit_image_decoding。
在宿主项目中实现代码。
调用 run_codegen 或 run_codegen_with_auto_review。
调用 validate_pipeline。

Figma 混合流程转目标 IR

通过 Figma MCP 获取 Figma 节点 JSON。
捕获或提供匹配的 Figma 画框截图。
调用 create_design_run，设置 mode: "target-ir" 和目标平台。
使用 nodeJson 和 screenshotPath 调用 ingest_figma_source。
生成目标布局 IR。
调用 build_target_ir。
调用 validate_pipeline。

精确切分截图资源

调用 create_design_run。
调用 ingest_image_source。
创建 layers.manifest.json，为位图／图标图层指定源像素边界框。
调用 slice_image_assets。
在生成的代码中使用 assets/slices/。
检查 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 发布流程：

配置 npm Trusted Publishing：

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

从 main 触发 GitHub Actions 的 Release 工作流。

该工作流使用 GitHub Actions OIDC（id-token: write），不需要 NPM_TOKEN 或长期有效的 MCP Registry 令牌。请保持启用 npm 账户的双重身份验证。

如需了解完整的发布、注册表、回滚和安全策略，请参阅：

仓库

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

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。

UI Design to Code

关于 UI Design to Code

主要功能

适用场景

MCP 相关

配置

工具

详细介绍

UI Design to Code MCP

中文

功能介绍

适用场景

不适用场景

核心能力

产出物

使用手册

快速开始

安装到 Codex

安装到 Cursor 项目级配置

一次安装到所有支持的本地客户端

检查或直接启动服务

反馈与改进入口

推荐执行流程

当前流程优化建议

执行模式

输入源选择

产物运行目录

客户端安装

Codex

Cursor

Claude Code

工具参考

get_run_modes

create_design_run

ingest_image_source

ingest_figma_source

slice_image_assets

build_reference_analysis

build_semantic_ir

build_cross_platform_nodes

build_target_ir

run_codegen

run_codegen_with_auto_review

validate_pipeline

audit_image_decoding

cleanup_design_run

常见工作流

截图转 Web 代码

Figma Hybrid 到 Target IR

截图精确切图

更新和版本管理

开发

发布

仓库

English

功能概览

适用场景

不适用场景

核心功能

输出

用户手册

快速开始

为 Codex 安装

为 Cursor 项目配置安装

为所有受支持的本地客户端安装

检查或运行服务

反馈与问题

推荐工作流

当前工作流优化说明

执行模式

源输入策略

产物运行目录结构

客户端安装

Codex

Cursor

Claude Code

工具参考

get_run_modes

create_design_run

ingest_image_source

`get_run_modes`

`create_design_run`

`ingest_image_source`

`ingest_figma_source`

`slice_image_assets`

`build_reference_analysis`

`build_semantic_ir`

`build_cross_platform_nodes`

`build_target_ir`

`run_codegen`

`run_codegen_with_auto_review`

`validate_pipeline`

`audit_image_decoding`

`cleanup_design_run`

`get_run_modes`

`create_design_run`

`ingest_image_source`

`ingest_figma_source`

`slice_image_assets`

`build_reference_analysis`

`build_semantic_ir`

`build_cross_platform_nodes`

`build_target_ir`

`run_codegen`

`run_codegen_with_auto_review`

`validate_pipeline`

`audit_image_decoding`

`cleanup_design_run`