plumb-mcp

Plumb (plumb-mcp) — AI 原生设计工程平台

⭐ 如果 Plumb 为你节省了 token，或帮你设计了页面，请在 GitHub 上为它点星，让更多人发现它。

Plumb 是一个 AI 原生设计工程平台，以单个 MCP 服务的形式交付。 将它指向 Figma 文件 或 正在运行的网站，它就会把两者规范化为同一张语义设计图——其中包含去重后的设计 token、经 flexbox 解析的布局，以及保守的角色标签（nav / hero / card …）——供编码 Agent 据此构建，并由验证循环进行评估。也可以只给它一行提示词，它就会变身为一位 AI 设计总监：调研一流参考案例、提取品牌风格，并在你的画布上生成完整且符合品牌风格的 Figma 文件，然后反复评审自己的渲染结果，直到达标。

设计 → 代码（Figma 或实时网页，经过验证，而非凭感觉） •  提示词 → 设计（调研 → 品牌 → 生成 → 评审） •  两者底层共用一张语义设计图。 原生支持 MCP，可与 Claude Code、Cursor、Windsurf 或任何支持 Model Context Protocol 的 Agent 配合使用。

📖 完整文档：https://tathagat22.github.io/plumb-mcp/  ·  📦 npm：plumb-mcp  ·  🇨🇳 简体中文  ·  🇯🇵 日本語  ·  🇰🇷 한국어

专为编码 Agent 打造，适用于 Claude Code、Cursor、Windsurf 以及任何兼容 MCP 的工具。Agent 原生的设计工程：无需仪表板，无需另行看管的应用，也无需人工在 Figma 和编辑器之间搬运像素。它通过桌面应用插件读取 Figma（没有 REST 速率限制，所有套餐均可使用，包括 Free），通过无头 Chrome 读取任何正在运行的网站，通过同一插件将新设计写入 Figma，并返回精简的规范化规格，而不是 Figma API 输出的数十万 token JSON。

为什么称为“设计工程平台”，而不是“Figma 转换器”

大多数 Figma MCP 服务，以及一般的 Figma 转代码工具，都是单向转换：输入 Figma JSON，输出某个框架的代码，就此结束。Plumb 的架构是一个枢纽，而不是一根管道：

• 两个独立来源汇入同一张图。 plumb_node 会规范化 Figma 屏幕；plumb_import_web 会规范化实时网页的 DOM。无论像素来自哪里，两者最终都会形成同一个与平台无关的语义图，其中包含包含关系、重复组和角色边。
• 每个使用方都能不经修改地处理任一来源。 无论图来自 Figma 还是 URL，plumb_emit_react 生成的 React/JSX 都同样确定。plumb_diff、plumb_audit 和 plumb_query 的角色筛选器在两种来源上也都能以相同方式工作。这就是它是一个平台，而不是在转换器上另行拼接第二个输入源的有力证明。
• 验证会在输出端闭环，而不仅仅是在输入端。plumb_verify / plumb_fit 会将已交付的代码与真实来源进行差异比较，并返回按优先级排序的修复建议——让“看起来没问题”变成可衡量的事实。
• 生成则反向运行这一闭环。 plumb_studio 会根据简报创作全新的 Figma 文件，而 plumb_review 会像 plumb_verify 评审代码那样评审渲染结果。

一个语义模型。多个输入来源（Figma、Web），多个输出目标（React 代码、Figma 文件），两端都经过验证。这就是这个平台。

两个方向，一个服务

← Figma 或 Web → 代码（读取方向）

你的 Agent 会将屏幕——或通过 plumb_import_web 导入的任意实时 URL——提取为精简的Plumb 设计规范（PDS），并以同一语义图为基础：自动布局已预先解析为 flexbox，设计令牌已去重，角色已标注。它会构建 UI，然后调用 plumb_verify / plumb_fit，将渲染结果与来源进行差异比较，并自行修正至像素级精确。这是唯一一个能让代码闭环的 Figma MCP；也是唯一一个无需 Figma 文件，就能针对普通网页运行完全相同闭环的工具。

→ 提示词 → 设计（写入方向——设计总监）

给 Plumb 一句简短的设计简报——“高端金融科技仪表盘”——它就会像一位资深设计师那样，在你的 Figma 中实时工作：

1. 调研参考案例——为你的简报寻找一流网站（Linear、Stripe、Mercury 等），并将它们的实时截图放到 References 页面。
2. 提取品牌风格——读取这些网站计算后的 CSS，提炼出协调一致的调色板和字体比例，并整理到 Brand 画板上。
3. 生成设计——通过高级设计 DSL 创作完整、符合品牌风格的页面（导航栏、主视觉区、功能、图库、行动号召、页脚），并将其构建为真实的 Figma 节点。
4. 评审自己的渲染结果——调用方 Agent（Claude Code / 任何具备视觉能力的 MCP 客户端——作为 MCP 工具运行时无需额外 API 密钥；独立的 plumb-mcp fit CLI 是唯一例外，详见下文的 独立 CLI）会对截图进行评分；Plumb 会将评分与确定性的设计标准及结构差异相结合，然后返回按优先级排序的修复列表，并持续迭代直至达到标准。

这就是通过提示词生成 Figma 设计，并配备自我改进的总监闭环——而不是一次性的模型图。

Plumb 的不同之处

你可能了解的其他 Figma MCP 服务：

• Figma 官方 Dev Mode MCP — 支持双向操作，但受套餐限制且按量计费。
• Framelink — 简单的 REST 封装。只有两个工具。没有验证，还受速率限制。
• cursor-talk-to-figma — 为在 Figma 中工作的设计师提供双向自动化。

而在 MCP 领域之外，更广泛的设计转代码／AI UI 生成器类别——例如 html.to.design、Anima、Locofy，或 v0 和 Builder.io's Visual Copilot 这类以提示词为先的生成器——通常只能单向操作（输入设计，输出代码；或输入提示词，输出代码），没有贯穿两端的共享模型，也没有内置步骤在生成后对照源内容检查输出。

Plumb 是唯一一个既能闭合代码反馈环，又能引导新设计生成的工具，所有这些都基于同一个语义图，不受源内容来自 Figma 还是 URL 的影响。plumb_verify 会告诉你已交付的代码是否确实符合设计（或参考页面）；plumb_fit 则将其转变为自我修复循环。plumb_import_web + plumb_emit_react 证明了语义图可以跨来源流转：同一个角色分类器和同一个代码生成器可以直接处理实时网站，全程无需 Figma。至于写入端，plumb_studio / plumb_brand / plumb_design / plumb_review 可以将提示词转化为经过设计和评审的 Figma 文件——无需设计技能、无需单独的设计工具，也无需额外的模型密钥（作为 MCP 工具；需要模型密钥的命令，请参阅 独立 CLI）。

你遇到的是以下问题之一吗？

如果你的 Agent 遇到错误后来到这里，Plumb 很可能可以解决。

安装：npm install -g plumb-mcp → plumb-mcp init — 或者让你的 AI Agent 为你完成设置。

30 秒内见证效果——无需账号、密钥或网络

在安装任何内容或连接 Figma 文件之前，先运行这一流程，看看它如何为自己评分：

npx plumb-mcp demo          # or: docker compose up demo

它会读取一份真实的设计规范，将同一屏幕中故意植入 13 处错误 的构建版本交给验证引擎——标题的字体比设计规范低一级、药丸按钮被渲染成圆角矩形、渐变被压平成纯色填充、徽章根本没有构建——然后打印它发现的问题：

  Round 1 · First pass — built straight from the spec, no verification
    ▰▰▰▰▰▰▰▱▱▱  71.0%   8 errors · 1 warnings · 32/34 key nodes built

    ✓ The "MOST POPULAR" badge was never built — no element carries its handle
      pro-badge           not built         no data-plumb-id for this handle in the DOM
    ✓ Headline came out one step down the type scale (48px → 40px)
      title               text.size         expected 48  ·  got 40
    ✓ Primary CTA is a hand-picked purple, not the brand token
      pro-cta             fill              expected #6366f1  ·  got #7c5cf5
    …

  Scoreboard
    Mistakes planted      13
    Caught                13   (100% recall)
    False positives       0   across 27 untouched nodes
    Convergence           71.0% → 96.2% → 100.0%

无需 Figma 令牌、插件、浏览器或网络——docker compose up demo 甚至可以在 network_mode: none 下运行。为演示评分的引擎与 plumb_verify 和 plumb_fit 背后的引擎相同，这些评分结果在 src/demo/demo.test.ts 中进行了断言，因此如果演示结果不再成立，CI 就会失败。plumb-mcp demo --pds 会打印它所依据的设计规范；--json 会输出结果供脚本使用，如果引擎漏掉任何问题，则以非零状态码退出。

让你的 AI Agent 为你完成设置

在你想使用 Plumb 的项目中，将以下内容粘贴到 Claude Code、Cursor、Windsurf 或任何带有 Shell 的编码 Agent 中。Agent 会负责安装和配置。它会暂停操作，引导你完成仅能由你完成的两个步骤：重启编辑器，并在 Figma 中点击 Pair。

Set up Plumb (https://github.com/tathagat22/plumb-mcp), the Figma MCP server, for
this project. Follow these steps in order and tell me what you did at each one.

1. Check prerequisites: Node 20+ (`node -v`) and npm. If Node is older than 20,
   stop and tell me how to upgrade. Don't upgrade it yourself.
2. Install: `npm install -g plumb-mcp`, then confirm it with `plumb-mcp --version`.
   If the global install fails with a permissions error, tell me and don't use sudo.
3. Smoke test: run `plumb-mcp demo`. It works offline and needs no Figma account.
   Its scoreboard should show "Caught 13 (100% recall)". If it doesn't, stop and
   show me the output.
4. Wire up the editor: run `plumb-mcp init` from this project's root. It detects
   Claude Code / Cursor / VS Code / Windsurf and writes the MCP config (for Claude
   Code that's `.mcp.json` here). It also adds those files to .gitignore. Show me
   which files it wrote and the Figma plugin manifest path it printed.
   - Leave the FIGMA_TOKEN placeholder alone unless I give you a token. The plugin
     path doesn't need one. Never commit a real token.
5. Hand off to me. Tell me exactly:
   a. Restart the editor / agent session so it loads the Plumb MCP server.
   b. Open the Figma DESKTOP app (the browser version can't sideload plugins) →
      Plugins → Development → Import plugin from manifest… → pick the manifest
      path from step 4.
   c. Open my design file, run the Plumb plugin, and click "Pair with Plumb".
6. After I restart and pair, call the `plumb_status` tool. Success means
   `connected: true` with a screen count. Then call `plumb_outline` and list my
   screens. If it isn't connected, follow the `note` field in the plumb_status
   response and try again.

Don't change any other files in this project during setup.

当 plumb_status 报告已连接后，就可以提出实际需求，例如：“用 Plumb 提取 Settings 屏幕，完成构建，然后运行 plumb_fit，直到它匹配为止。”

快速开始

# 1. Install
npm install -g plumb-mcp

# 2. Wire into your editor — auto-detects Claude Code / Cursor / VS Code / Windsurf
plumb-mcp init

# 3. Sideload the Figma plugin (one-time). Find the manifest:
echo "$(npm root -g)/plumb-mcp/figma-plugin/manifest.json"
#    Figma desktop → Plugins → Development → Import plugin from manifest…
#    Run Plumb → click "Pair with Plumb" → done. Future runs collapse to a dot.

然后，在你的 Agent 中：

# Figma → code
"Extract the Settings screen with Plumb and build it, then plumb_fit until it matches."

# web → code, no Figma required
"Use plumb_import_web on https://example.com, then plumb_emit_react to scaffold it."

# prompt → design
"Use plumb_studio to design a premium fintech dashboard, then screenshot it and
 run plumb_review as the director until the score clears 90."

其他安装方式：npx plumb-mcp · docker run --rm -i ghcr.io/tathagat22/plumb-mcp:latest。

git clone https://github.com/tathagat22/plumb-mcp
cd plumb-mcp
npm ci
npm run demo        # the offline walkthrough — proves the checkout works
npm test            # 600+ specs
npm run typecheck   # strict TS, server + plugin
npm run lint
npm run build       # bundles the server, the Figma plugin, and Studio into dist/
node dist/index.js --help

二十八种工具，一个语义图

以下每种工具都会读取或写入上文所述的同一个语义设计图——这使得添加新的来源（Web）或新的目标（React）只需增量扩展，而无需重写。

读取 — Figma 或网页 → 代码

编写 — 提示词 → 设计（设计总监）

为什么在令牌效率和质量方面表现出色

• 规格精简。 一个包含 178 个节点、Figma REST JSON 达 351k 令牌的对话，转换为 PDS 后约为 2.6k 令牌——令牌去重、通过 flexbox 解析布局、句柄的深度保持稳定。
• 经过验证，而非凭感觉。 plumb_verify / plumb_fit 会将渲染结果与设计进行对比（ΔE2000 感知色彩、阴影、旋转、flex 子项、填充堆栈）——不做像素差异对比，可在 CI 中运行。
• 精心设计，而非默认设置。 写入方向融入了真正的设计工艺：根据尺寸调整字间距、宽裕的区块节奏、从真实参考中提取的品牌调色板、渐变文字、通栏和非对称布局，以及一个基于视觉的导演，它会评估渲染结果并持续优化。
• 理解结构，而不只是几何——也不只理解 Figma。 Plumb 会在原始树的基础上谨慎标记导航栏/主视觉/页脚/侧边栏/卡片（node.pattern——信号不一致时宁可不标，也不猜），并以此构建功能：plumb_diff 按角色描述变更，plumb_audit 标记对比度和触控目标问题，plumb_query 的 select: "role" 和 plumb_node 的 collapseRoles 会按相同标签筛选并压缩。相同的底层模型也能读取实时网页——plumb_import_web 可从任意 URL 提取结构和角色，无需涉及 Figma——而 plumb_emit_react 则可从任一来源生成确定性的 React/JSX。

两条数据路径

工具会自动选择路径。配对插件后，可省略 fileKey 并传入 id 或 name。

配置

无需配置即可试用 Plumb：npm run demo 完全不需要配置，插件路径（plumb_outline、plumb_node、plumb_selection 等）只需配对 Figma 插件即可。

本地使用时，将 .env.example 复制为 .env（已被 gitignore 忽略）。Plumb 启动时会从工作目录和包根目录加载该文件——但 MCP 客户端会将服务作为全新进程启动，因此最可靠的密钥存放位置是客户端服务的 env 区块。

环境变量

在容器中运行

docker compose up demo      # the offline walkthrough, network disabled — start here
docker compose up bridge    # bridge + Plumb Studio on http://127.0.0.1:31337
docker compose run --rm mcp # the stdio MCP server, for an editor to attach to

桥接服务提供 GET /healthz（别名为 /health）——用于检查存活状态以及是否已与插件配对；Compose 健康检查会探测此端点。它还提供 Prometheus 文本格式的 GET /metrics。

bridge 会发布一个固定端口（容器只能发布已知端口，因此 PLUMB_BRIDGE_PORT 会取代端口扫描），并将其映射到主机的回环地址 — 与原生运行相比，外部可访问范围没有扩大。导出的资源、屏幕截图和缓存会存放在 plumb-data 卷中。

此外还有一个 devcontainer：在 VS Code 或 Codespaces 中打开仓库后，它会安装两个工作区，并在连接时运行演示。

在 Kubernetes 上运行——并按计划捕捉设计偏差

helm install plumb ./deploy/helm/plumb --namespace plumb --create-namespace
helm test plumb --namespace plumb
kubectl -n plumb port-forward svc/plumb 31337:31337   # Studio + plugin pairing

Helm chart、纯清单文件 和 Terraform 模块——三者都会生成相同的加固部署，并且都在 CI 中经过验证（helm lint、针对两个 Kubernetes 版本的真实 API 架构运行 kubeconform -strict、terraform validate、Trivy 和 Checkov 策略扫描，以及重新生成并比较差异，确保纯清单文件不会偏离 chart）。

将 Plumb 部署到集群，而不只是笔记本电脑上的原因，是为了实现持续设计验证：CronJob 会渲染你已提供服务的 URL，将每个 [data-plumb-id] 元素与其对应的 Figma 节点进行差异比较，并在二者出现偏差时失败。

verify:
  enabled: true
  schedule: "0 * * * *"
  targets:
    - name: dashboard
      url: http://app.default.svc.cluster.local/dashboard
      node: "190:109884"

设计回归不再是三周后才有人在评审中注意到的问题，而会成为一个带时间戳和差异列表的失败任务。

该桥接服务本身不提供身份验证——其安全模型依赖回环连接和明确的配对点击。因此，默认配置不会暴露任何内容：ClusterIP、默认拒绝所有流量的 NetworkPolicy、不配置入口，并通过 kubectl port-forward 访问。deploy/README.md 明确说明了哪些功能可在集群中使用、哪些不可用（Figma 插件会扫描 127.0.0.1，因此需要端口转发），以及每个开关具体会暴露什么。

独立 CLI

有两个命令可在任何 MCP 客户端之外直接从终端运行——适用于 CI，或在没有 Agent 参与的情况下驱动 Plumb：

plumb-mcp verify <dev-url> --node <figma-node-id>   # diff a running page against the design
plumb-mcp fit <figma-url>                           # generate + self-correct an HTML build until it matches

plumb-mcp verify 只需要 FIGMA_TOKEN（或已配对的插件）——它会比较差异，不会生成内容，因此不需要模型密钥。整个项目中，只有 plumb-mcp fit 这条命令会直接调用外部模型：它会自行生成 HTML 构建（没有 Agent 替它完成这项工作），因此除 FIGMA_TOKEN 外还需要 ANTHROPIC_API_KEY。包括 plumb_fit 和 plumb_review 在内的所有 MCP 工具都无需密钥，因为调用工具的 Agent 会负责生成内容或作出判断。

网络出站连接

上述连接都不会自动触发——每次网络调用都由你执行的工具或 CLI 命令直接触发。没有后台轮询、遥测或向外发送数据。

安全性

• 仅限回环连接的 WebSocket 桥接服务；每次只能配对一个插件（需主动点击一次）。
• 零遥测。使用插件路径无需个人访问令牌。
• 写入方向绝不会调用外部模型——负责驱动 MCP 服务的 AI Agent 会作出设计判断（独立 plumb-mcp fit CLI 是唯一例外；参见独立 CLI）。

贡献

欢迎贡献——无论是修正拼写错误、添加新的验证检查，还是升级设计总监。请参阅 CONTRIBUTING.md。初来乍到？浏览 good first issue 标签。

许可证

MIT © Tathagat Maitray。请参阅 LICENSE。