figbridge

Figbridge

Figma ↔ 代码，双向打通。 免费、开源、本地运行，为社区而建。

Figbridge 是一个 Figma 插件 + 本地 MCP 服务。在任意文件中打开插件，启用 Live bridge，任何支持 MCP 的 Agent（Claude Desktop、Claude Code、Cursor、Continue、Cline……）都可以通过 127.0.0.1 读取画面、设计令牌和组件，将整个 URL 导入 Figma、审查导入的设计、与源文件进行差异比较，并为源代码仓库生成补丁。

┌──────────┐   postMessage   ┌──────────┐   HTTP + SSE    ┌───────────────┐     stdio     ┌──────────────┐
│  Figma   │ ──────────────▶ │  Plugin  │ ──────────────▶ │  MCP Server   │ ◀──────────── │  AI agent    │
│  Desktop │                  │   UI     │   :7331/push    │  (localhost)  │   tools/call  │  (Claude …)  │
└──────────┘                  └──────────┘                 └───────────────┘               └──────────────┘

为什么选择 Figbridge

Figbridge 为社区打造：免费、开源、本地运行，从网页采集到生成源代码补丁，全程实用。

Figbridge：

• 免费。 MIT 许可。完全在你的设备上运行。
• 无需账号或令牌。 使用你现有的 Figma 桌面会话。
• 54 个 MCP 工具。 读取、编目、回写、检查、将 Figma 组件映射到代码（无需 Dev 席位即可使用 Code Connect）、打包 Agent 交接包、将实时 URL 导入 Figma、从 5 个维度审查导入的设计、将更改回传到源代码仓库并生成补丁，还能运行闭环视觉差异比对，让运行中的应用与设计稿保持一致。
• 导入前诊断，无需干等。 preflight_import 会在完整导入前标记机器人页面、深层 DOM、低分辨率图像、SVG 密集页面和可下载字体资源。
• 为复杂页面提供混合回退方案。 import_url({ hybridSnapshot: true }) 可以将整页截图作为参考放置在可编辑图层下方，适用于视频密集型或生成式网站等需要像素级还原的场景。
• 支持 Chrome/Edge 当前标签页采集。 将 chrome-extension/ 作为未打包扩展加载，即可将可见视口、整页、选定元素、已认证标签页、localhost 或暂存页面直接发送到本地桥接服务。
• 离线 Agent 工具包。 get_agent_bundle 可生成 zip（层级结构 · 令牌 · 组件 · AGENTS.md · CHANGES.md），Agent 无需连接实时 MCP 即可使用。
• 结果确定。 不会由大模型改写。你选择什么，就会得到什么。
• 实时同步。 启用“Live bridge”后，每次选择变更都会自动推送；Agent 可以即时拉取当前选择。

安装 — 约 3 分钟

该插件尚未上架 Figma Community，因此需要克隆仓库获取。MCP 服务通过 npm 安装。

# 1. Get the Figma plugin (clone the repo)
git clone https://github.com/rudraptpsingh/figbridge

# 2. Patch Claude Desktop's MCP config
npx figbridge-mcp init

然后：

1. 退出并重新打开 Claude Desktop——它只会在启动时读取 MCP 配置。
2. 在 Figma 中选择：Plugins → Development → Import plugin from manifest… → 选择上方克隆仓库中的 plugin/manifest.json。（仅需执行一次。）
3. 在任意画板上运行 Figbridge 插件，并启用 Live bridge。插件标题栏中的绿点表示已连接到本地桥接服务。页脚会显示端口。
4. 在 Claude 中询问：“figbridge 提供哪些工具？”——你应该能看到 40 多个工具。

对于其他 MCP 客户端（Cursor、Cline、VS Code，……），将其指向同一个可执行文件：npx figbridge-mcp。

通过 MCP 注册表安装

Figbridge 也已列入官方 Model Context Protocol 注册表，名称为 io.github.rudraptpsingh/figbridge。支持注册表的客户端（Claude Desktop、Cursor、VS Code）可以直接发现并安装，无需手动编辑配置。

故障排除

如果 Claude Desktop 显示 “Server disconnected” 或端口 7331 卡住，请运行：

npx figbridge-mcp doctor

该命令会清理孤立的 figbridge-mcp 进程，并报告哪些端口处于活动状态。如果 7331 被占用，桥接服务会自动回退到 7332..7340；插件也会自动探测相同范围，因此“端口已被占用”不会造成阻碍。FIGBRIDGE_PORT=NNNN 可覆盖首选起始端口。

对于通过 POST /command 操作 Figma 的长时间本地 Agent 会话，请运行持久桥接服务：

npx figbridge-mcp bridge

此命令只会启动本地 HTTP+SSE 桥接服务，并在标准输入关闭后继续运行。当桌面或终端工具会启动短时命令，但你希望 Figma 插件连接在多次 Agent 操作期间保持稳定时，请使用此命令。

更新

init 会写入一份配置，其中会运行 npx -y figbridge-mcp@latest，因此每次启动 Claude Desktop 时都会拉取当前版本——新版本发布后无需执行任何操作。

如果你安装的是较旧版本（≤ 0.1.1），且配置中写入了绝对路径，请运行一次以下命令以自动修复：

npx figbridge-mcp@latest update

如果你希望锁定到当前已安装的版本（不自动更新），请使用 npx figbridge-mcp init --pin。npx figbridge-mcp --version 会打印已安装的版本。

MCP 工具

读取（8） — get_current_selection · get_last_export · list_history · get_tokens · bridge_status · diff_since · list_pages · list_frames

目录（8） — list_screens · list_components · describe_screen · export_app_spec · export_all_pages · list_assets · select_node · export_node

操作与交接（5） — get_agent_bundle · clone_screen · recolor · apply_tokens · lint_ds

浏览器（11） — preflight_import（导入前进行风险检查，包括字体下载 URL）、import_url（实时 URL → Figma 画板；可选的 hybridSnapshot 截图参考）、import_responsive_set（桌面 / 平板 / 移动端，以及可选的浅色 / 深色主题捕获）、import_url_batch（批量导入 URL）、screenshot_url、probe_url、fingerprint_url、audit_interactions（发现悬停 / 聚焦状态）、verify_text_fidelity、measure_fidelity、audit_regression（对比基准 URL 与候选 URL，审查前端 / UI 回归）

支柱 1 — 往返编辑（2） — diff_to_source（导入画板与实时源代码之间逐文本节点的字段差异） · generate_patch（将差异转为针对源代码目录的最小 HTML/JSX 等补丁；样式替换会提供结构化的 CSS 文件提示）

支柱 2 — 设计智能审查（5） — audit_palette · audit_typography · audit_a11y（WCAG 2.x 对比度、地标、替代文本） · audit_whitespace（内边距 / 间距节奏、是否符合 4/8 网格） · audit_mobile（多视口响应式检查：水平滚动、overflow-x、小于 44px 的触控目标、小于 12px 的文本）

Code Connect（3） — connect_components（创建 / 编辑 figbridge.connect.json：将 Figma 组件映射到代码组件及其属性） · get_code_connect（获取已映射的组件、属性，以及可直接粘贴的实例 JSX 代码片段） · lint_connect（CI 门禁：检查文件、导出项、属性、字面值和 Figma 属性是否仍然存在）。请参阅 无需 Dev 席位的 Code Connect。

支柱 3 — 匹配设计稿（3） — match_mockup（闭环渲染 → 对比 → 优化：渲染运行中的应用及其目标设计稿，返回各视口的视觉评分，以及按优先级排列的文案 / 颜色 / 字体 / 间距 / 阴影 / 图标 / 结构差异清单、设计语言风格指纹；若提供 sourceDir，还会列出每项差异对应的待编辑源文件） · diff_specs（对渲染后的 URL 或捕获的 spec JSON 文件进行精确的结构化字段级差异比较） · map_components（为应用的源代码树建立索引——data-testid / 组件 → 文件，以及设计令牌——以便差异结果指出要修改的文件，以及字面值应替换成的令牌）

对照 Figma 检查组件。 使用任意 Figma 导出工具为一个变体截图（插件 export_frame，或 Figma MCP 截图），然后用 screenshot_url（width + height，fullPage: false）按其尺寸渲染同一组件，最后对两张图运行 diff_images：即可获得评分、SSIM 和拼接 PNG。提供一个能渲染所有变体的套件页面（例如 ?kit 路由），并将 match_mockup 指向该页面，即可运行整张图集的比对。 在代码中查找尺寸规则。 对于匹配的设计 HTML 视图和应用状态，将仓库根目录作为 sourceDir 传给 match_mockup 或 diff_specs。差异包括视口 x/y 坐标和尺寸。FigBridge 会将 data-testid 与 data-state（或 figbridge.connect.json 中的组件名称）解析到源文件，并显示附近的 JSX 类名。如果当前尺寸只有一个匹配的代码字面量，codeChange 会给出准确行号、当前规则和建议替换内容；否则会将该编辑标记为未解决。它还会比较 tokens.json 中从 Figma 导出的浮点变量与生成的 v2Tokens.json，并报告 tokenDrift。单独的截图只能用于像素比较，不同的照片或 UI 状态无法证明整个屏幕匹配。

结构化差异现在可以在应用插入栏或面板时，让具有唯一名称的同级元素保持对齐；报告不同的显式 data-state 标记；并在问题清单达到上限时说明省略了哪些结果。默认情况下会精确报告可比较的颜色、几何和样式值；设置 tolerant: true 可忽略细微的数值差异和低于 JND 的颜色差异。结构化比较缺失或不完整时，不能仅凭像素得分判定通过。这两个 URL 仍需内容和状态匹配，并且设计导出必须可供检查；FigBridge 无法从 PNG 推断 Electron DOM 字段或 Figma token 值。

原生 Electron 状态。 diff_specs 支持使用 appSpecPath 替代 appUrl（以及使用 mockupSpecPath 替代 mockupUrl）。请在目标状态稳定后，捕获实际的 Electron Playwright 页面。读取 mcp/src/dom-to-spec.js，然后运行 await page.evaluate(extractor) 和 await page.evaluate(() => window.domToSpec({ rootSelector: 'body', viewport: 1440, embedImages: false }))；将结果保存为 JSON。Playwright 求值可以在打包后的渲染进程 script-src 'self' 策略下运行，而 page.addScriptTag({ content: extractor }) 可能会被该策略阻止。调用 diff_specs 时，传入已渲染的 Figma HTML mockupUrl、原生 appSpecPath 和 sourceDir，即可获得精确的成对值及其源代码位置。两侧也可以改为使用捕获的 JSON 文件。每一侧都必须且只能提供一个 URL 或 spec 路径。Figma PNG 只能用于像素比较；精确的 Figma 字段需要可供检查的导出，而整个屏幕的判定仍要求内容和状态匹配。

图层树不同。 原生 DOM 树与 Figma 图层嵌套不一致时，将 anchors 传给 diff_specs。每一对锚点都指定一个 Figma 节点（来自结构化 Figma spec 的 mockupId，或唯一的 mockupName）和一个应用 data-testid；fields 可将比较限制为实际检查的属性，例如 ['x','y','width','height']。FigBridge 会比较两个 spec 中的视口几何，并报告各锚点的精确差异及应用源代码映射。coverage 会显示请求的锚点、唯一匹配的锚点以及缺失或匹配不明确的锚点；任何未匹配的锚点都会导致 ok: true 不成立。这是对部分内容的测量，因此请为每个需要验证属性的区域添加锚点。示例：{ "name": "Action pill", "mockupId": "95:2956", "appTestid": "photo-toolbar-pill", "fields": ["x", "y", "width", "height"] }。Figma spec 节点可以包含 _figmaId 以及从其实时节点读取的值；单独的截图无法提供这些数据。

所有审计都是纯确定性测量，不会调用模型。它们会返回数值评分和结构化问题列表，可直接反馈到规划循环中。发布 UI 变更前，可将 audit_regression 用作本地/CI 门禁：它会比较桌面、平板和移动端的截图、缺失的可见文本、响应式问题差异以及 CSS 特性漂移。

Chrome 当前标签页捕获

chrome-extension/ 文件夹包含一个用于已登录页面的未打包 MV3 扩展：

1. 打开 chrome://extensions，启用 Developer mode，并加载未打包的 chrome-extension/ 文件夹。
2. 启动 Figbridge MCP，并打开启用了 Live bridge 的 Figbridge Figma 插件。
3. 使用扩展弹出窗口发送可见视口、选择是否捕获完整页面 DOM、选取页面元素，或在可编辑图层下方添加视口截图引用。

浏览器捕获可以将每个网站或项目归入单独的 Figma 页面，例如 Chrome Capture - Raycast 或 Chrome Capture - Localhost，这样不同项目就能在同一个打开的 Figma 文件中保持易于浏览。

此扩展只会向 127.0.0.1:7331..7340 发送数据；不会将页面数据发送到云服务。

没有 Dev 席位也能使用 Code Connect

Figma Code Connect 需要 Organization 或 Enterprise 方案中的 Dev 或 Full 席位。Figbridge 在本地完成相同的工作，而且免费，只需使用一份与你的代码一起提交的映射文件。

1. 映射文件 — 仓库中的 figbridge.connect.json。 每个 Figma 组件对应一个条目：

对于在展示框架内放置独立变体组件的 UI 套件，将该框架保留为 figma.nodeId，并在 figma.variantNodeIds 中列出精确的组件 ID。FigBridge 会读取实例的主组件 ID 并解析匹配的变体，包括结构化差异；它不会根据相似名称推断归属关系。

{
  "version": 1,
  "fileKey": "WwO2ckSkwjOeusmEQwWrus",
  "imports": { "src/": "@/" },
  "components": [{
    "figma": { "fileKey": "WwO2ckSkwjOeusmEQwWrus", "nodeId": "59:944", "name": "Button",
               "properties": { "Style": { "type": "VARIANT", "options": ["Primary", "Secondary", "Quiet", "Destructive"] } } },
    "code":  { "source": "src/components/primitives/Button.tsx", "export": "Button",
               "import": "import { Button } from '@/components/primitives/Button'" },
    "props": {
      "variant":  { "figma": "Style", "type": "enum", "values": { "Primary": "primary", "Secondary": "secondary" } },
      "loading":  { "figma": "State", "type": "enum", "values": { "Loading": true } },
      "icon":     { "figma": "Icon", "type": "instance", "as": "component", "when": "Show icon", "importFrom": "lucide-react" },
      "children": { "figma": "Label", "type": "text" },
      "testId":   { "type": "static", "expr": "testId" }
    }
  }]
}

Prop type	Code Connect 对应项	映射内容
enum	figma.enum	变体值 → prop 值（values；未映射的值会移除该 prop）。多行可以读取同一个变体，例如 State=Loading → loading、State=Disabled → disabled。
boolean	figma.boolean	布尔属性 → true / 省略，或通过 values 映射
text	figma.string	文本属性 → 字符串 prop，或 JSX children
instance	figma.instance	实例交换 → {Download}（as: "component"）或 {<Download />}；importFrom 会添加导入语句
static	—	固定的 value，或用于 Figma 中没有对应属性的 prop 的 expr 占位符

when 根据 Figma 布尔属性（"Show icon"）控制任意 prop 是否生效。匹配 Figma 名称时会忽略其 #12:34 后缀。可选的 example 模板可使用 {{props}}、{{children}}、{{propName}} 和原始的 {{figma.Label}} 值，适用于代码结构与 Figma 不同的组件（例如，Figma 中是一个分段，代码中则是带有 options 的 Segmented）。

2. 初始化映射。 connect_components 会为你写入条目：组件描述中的 Code: src/…tsx 行、Test id:（通过 map_components 索引）或组件名称会用于确定文件和导出项；props 来自 TSX，变体值则根据每个 prop 的字符串字面量联合类型进行匹配。除非传入 overwrite，否则会保留手动编辑的内容。

# from the open Figma file (plugin running), with @/ imports
npx figbridge-mcp call connect_components '{"fromPlugin": true, "imports": "{\"src/\":\"@/\"}"}'

3. 使用映射。 在 Figma 中选择一个实例，并打开插件的 Code 选项卡：查看映射的组件、当前 props 和可直接粘贴的代码片段，类似 Dev Mode 面板。Agent 可调用 get_code_connect（传入 nodeId、当前选区或离线 node 描述）：

// get_code_connect on a Button instance (Style=Secondary, Show icon, Icon=download, Label "Export 186")
import { Button } from '@/components/primitives/Button'
import { Download } from 'lucide-react'

<Button icon={Download} variant="secondary" size="m" testId={testId}>Export 186</Button>

4. 确保映射准确。 当源文件、导出项或 prop 不存在时，当映射值不再属于该 prop 的字面量联合类型（包括从其他模块导入的联合类型，或 (typeof STATES)[number]），或者当映射的 Figma 属性或变体值不再存在于条目的 Figma 快照中时，lint_connect 会失败。将其加入 CI：

npx figbridge-mcp call lint_connect '{}'    # exit 1 when the map has rotted

从 Shell 或 CI 调用工具

每个工具都可以在没有 MCP 客户端的情况下运行：

npx figbridge-mcp tools                                   # list tools
npx figbridge-mcp call map_components '{"sourceDir":"src"}'
npx figbridge-mcp call get_code_connect @args.json        # args from a file
echo '{"url":"http://localhost:5173"}' | npx figbridge-mcp call audit_mobile -

它会输出工具的 JSON；当结果为 ok: false 时以 1 退出。当 Figbridge bridge 已在运行（Claude 或 figbridge-mcp bridge）时，插件工具会通过它连接到已打开的 Figma 插件。

面向 Agent 的交接包

get_agent_bundle 是其差异化优势。一次调用即可返回一个 zip：

DESIGN.md          palette · rhythm · do/don't
hierarchy.md       indented tree with deterministic slugs
components.json    variants + props schema
tokens.json        DTCG-shaped
tokens.css         :root + per-mode blocks
flow.mmd           Figma prototype → Mermaid graph
responsive.md      mobile/tablet/desktop merged
ISSUES.md          a11y audit the agent shouldn't repeat
CHANGES.md         surgical diff since last bundle
AGENTS.md          "when you see slug X, import Y"
manifest.json      sha-256 + token counts, stable order for prompt cache
screenshots/       1:1 paired with hierarchy slugs

有三个预算档位（small 8k / medium 32k / large 128k 个令牌）。Slug 是确定性的——重命名节点后，slug 保持不变——因此 CHANGES.md 是真正精准的差异，而不是对整个文件重新翻译。

闭环：URL → Figma → 差异 → 补丁

Figbridge 是首个能够双向闭环的 MCP 原生工具。

                 import_url                      diff_to_source
   ┌──────────┐  ──────────▶  ┌──────────┐  ──────────▶  ┌──────────┐
   │  Source  │                │  Figma   │                │  changes │
   │  (URL,   │                │  frame   │                │   list   │
   │   repo)  │ ◀──────────    │ (edited) │                └────┬─────┘
   └──────────┘  generate_patch└──────────┘                     │
                                                                ▼
                                                         apply or review

1. import_url 将实时 URL 导入 Figma 页面（通过 pageName 支持多页面；通过 rootSelector 支持按区块导入）。
2. 使用五个 Pillar 2 工具审查结果，找出调色板偏差、对比度问题、间距偏离网格和移动端布局故障。使用 audit_regression 对比生产环境／预发布环境与本地候选版本，在更新 Figma 或发布代码前发现 UI/UX 回归问题。
3. 设计师在 Figma 中编辑画框。
4. diff_to_source 会准确报告哪些文本节点字段与源 URL 不同——字符／fontSize／fontFamily／color／是否存在。
5. generate_patch 根据差异，针对本地源代码目录生成最精简的修改前后列表。样式替换会提供结构化提示（令牌还是字面值），而不是盲目替换文本。

整个流程中没有 LLM 重写。每一步都是确定性的、幂等的。

输出格式

格式	形式
HTML + CSS	自包含文档，采用位置布局以保持像素级还原。
Tailwind	使用 Tailwind 任意值工具类（w-[120px]、bg-[#ff7a29]）的相同树结构 + CDN 脚本。
设计令牌	DTCG JSON 树、:root { --var: value } CSS、Tailwind 配置片段。读取 Figma Variables + 本地绘制样式。

架构

• 插件主线程（plugin/code.js）——读取节点树，以确定性方式计算 HTML/CSS/Tailwind/令牌。兼容 ES2017（不使用 spread / ?? / ?.），适用于 Figma 沙盒。
• 插件 UI（plugin/ui.html）——奶油色／墨色／铁锈色主题、Figma 原生图层导航器、带有每个工具对应“运行”按钮的内嵌 Commands 面板。
• MCP 服务（mcp/src/）——通过 @modelcontextprotocol/sdk 提供 stdio MCP，并在 :7331 上运行同级 HTTP + SSE 服务，供插件推送和双向命令使用。状态保存在内存中，并持久化到 ~/.figbridge/last.json。

Figbridge 不会做什么

• 不会在桌面应用和插件未打开时访问 Figma。不使用 REST API 或 PAT。
• 不会使用 AI 重写代码。它是一个确定性的树遍历器。
• 不会向 Figma 或云端发布内容。

开发

cd mcp && npm install && npm test        # integration smoke test
node test-agent/run.js                   # 130 unit tests on the render pipeline
node test/scenarios.mjs                  # 54 real-world scenario checks
node test/real-figma.mjs                 # 43 checks against a parsed real .fig
node test/tools-all.mjs                  # full MCP tool surface + e2e
node test/code-connect.mjs               # Code Connect: props reader, suggest, snippets, lint
node test/cli.mjs                        # figbridge-mcp call / tools
node --check plugin/code.js              # plugin syntax check

链接

• 落地页：https://rudraptpsingh.github.io/figbridge/
• npm：https://www.npmjs.com/package/figbridge-mcp

许可证

MIT © Rudra Pratap Singh