拓冰网站定制 
Figma Console MCP Desktop Bridge 深度源码解析WebSocket 插件桥接 Figma Plugin API 的通信协议与多实例机制【免费下载链接】figma-console-mcpYour design system as an API. Connect AI to Figma for extraction, creation, and debugging.项目地址: https://gitcode.com/gh_mirrors/fi/figma-console-mcpfigma-console-mcp 是一个把设计系统变成 API的开源项目让 AI 助手能够连接 Figma 完成提取、创建与调试。它的核心桥梁就是Figma Desktop Bridge 插件通过WebSocket把本地 MCP 服务器的指令转发给 Figma 插件再由插件调用Figma Plugin API读写设计文件。本文带你读懂这套桥接架构的通信协议、端口发现与多实例机制——无需任何代码基础也能理解。一、为什么需要这座桥Figma 官方有两条数据通道但都有短板通道局限REST API已知 Bug组件的description字段经常缺失或过期本地变量需要企业版Plugin API数据最完整、最实时但插件运行在沙箱里不能直接监听端口Desktop Bridge 的巧妙之处就在这里插件沙箱里的 Workercode.js碰不到网络但插件的 UI 界面ui.html是一个标准 iframe允许通过白名单域名发起 WebSocket 连接。于是形成了四层数据流MCP Server ←WebSocket(9223–9232)→ 插件 UI(ui.html) ←postMessage→ 插件 Worker(code.js) ←figma.*→ Figma对应三个文件manifest.json — 插件配置声明了 9223–9232 共 10 个端口的网络白名单code.js — 插件 Worker唯一有权调用 Figma Plugin API 的部分ui.html — 插件 UI真正的 WebSocket 客户端二、通信协议详解消息如何在两端流转2.1 握手与身份识别 服务器端websocket-server.ts在连接建立后先发出一帧SERVER_HELLO包含端口、进程 PID 和服务端版本方便调试定位。插件侧连接后ui.html 中的initializeConnection会做两件事把启动时缓存的变量数据以VARIABLES_DATA消息推给服务器请求文件信息后发送FILE_INFO帧携带fileKey、文件名、当前页面等身份信息服务器会等待最多 30 秒——如果连接始终没有FILE_INFO自我报身份直接断开。这一步让服务器能区分哪个 Figma 文件是后面多文件并发的基础。2.2 请求/响应格式 指令采用极简的 JSON-RPC 风格请求{ id, method, params }响应{ id, result }或{ id, error }method就是命令名插件 UI 里有一张methodMap把 70 多个方法映射到本地函数例如方法作用EXECUTE_CODE在插件沙箱内执行任意 Figma API 代码带超时与空结果预警UPDATE_VARIABLE/CREATE_VARIABLE读写设计令牌变量GET_COMPONENT/DEEP_GET_COMPONENT按需获取组件及其描述绕开 REST API BugCREATE_COMPONENT_SET批量生成变体矩阵超时随变体数量自动放大CAPTURE_SCREENSHOT截图回传这就是服务器把 WebSocket 单包上限开到 100MB 的原因LINT_DESIGN/AUDIT_COMPONENT_ACCESSIBILITY设计校验与无障碍审计2.3 一些值得注意的工程细节 控制台捕获code.js 重写了沙箱内的console.log等方法把日志以CONSOLE_CAPTURE帧经 UI 转发到服务器AI 因此能看见插件运行时输出实现远程调试。Origin 校验防劫持服务器只接受nullFigma 沙箱 iframe和figma.com来源的连接精确匹配而非前缀匹配防范跨站 WebSocket 劫持CSWSH。心跳探活服务器周期性 ping客户端 pong 超过阈值即判定连接死亡并清理。版本协商插件在FILE_INFO中携带PLUGIN_VERSION服务器把它与自身打包的插件版本比对若插件过旧会提示用户重新导入 manifestFigma 会在应用层缓存插件文件重启插件并不够。三、多实例机制端口 9223–9232 的故事3.1 端口回退 你很可能同时开着 Claude Desktop 的 Chat 和 Code 两个标签页或一个桌面端加一个 CLI 终端——每个都会启动一个 MCP 服务器。服务器启动时优先绑定9223被占用就自动顺延尝试 9224、9225……最多 10 个端口port-discovery.ts 中DEFAULT_WS_PORT 9223、PORT_RANGE_SIZE 10也可以用FIGMA_WS_PORT环境变量改首选端口。绑定成功后服务器会在/tmp写下一个广告牌文件figma-console-mcp-{port}.json记录端口、PID 和心跳时间lastSeen供外部工具发现。3.2 僵尸进程回收 最经典的故障现象是服务器明明在跑插件却连不上——根因往往是上次关闭时挂死的僵尸进程占着端口把新服务器挤到回退端口。端口发现模块用三重判据识别僵尸PID 已死亡进程不存在心跳超过 5 分钟未刷新进程卡死文件年龄超过 4 小时无心跳兼容旧版本确认为僵尸后先发SIGTERM给 400ms 优雅退出窗口无响应则升级为SIGKILL强杀port-discovery.ts。此外还有每 5 分钟一次的后台收割器且保证收割过程不阻塞事件循环不会冻住正在执行的工具调用。 插件状态栏里的N server(s)徽章就是一个健康检查如果数字大于你实际打开的 AI 客户端数量就说明有僵尸实例下一次服务器启动时它们会被自动清理。3.3 插件端全端口扫描 后台哨兵 插件启动时执行wsScanAndConnectui.html依次向 9223–9232 发起 WebSocket 连接连接成功即保留——不是只连第一个而是连上所有活跃服务器每个连接独立初始化发送FILE_INFO、推送变量缓存因此每个 AI 客户端都能独立获得 Figma 访问权所有实时事件选区变化、文档修改、变量、控制台日志广播给每一条连接如果扫描时一个服务器都没找到比如你先开了插件才启动 AI 客户端并不会卡死先做最多 3 次快速重试之后转入静默的/health探测循环服务器一出现就自动连上——全程无需重启插件。状态栏的Reconnect按钮可随时强制立即重扫。四、多文件隔离与活动文件切换服务器把每个 Figma 文件视为一个独立客户端按 fileKey 存入 Map每个文件单独维护选区状态、文档变更记录、元数据变更环形缓冲、控制台日志。活动文件会随你在某个文件里的交互选区/翻页自动切换服务器还支持锁定目标文件——AI 在一个文件工作时你在另一个文件的操作不会把指令悄悄路由错地方。这让figma_list_open_files、figma_execute_across_files这类跨文件工具成为可能。五、Cloud Mode没有本地 Node.js 也能写 Figma ☁️除了本地模式插件还支持云端配对AI 客户端生成 6 位一次性配对码5 分钟有效、单次使用插件输入后与云中继建立wss://TLS 连接。此后网页端 AI 平台也能把写指令经中继送达你的 Figma 文件。本地与云端连接可同时存在互不干扰。实现见 cloud-websocket-relay.ts 与 cloud-websocket-connector.ts完整架构说明见 docs/architecture.md。六、快速上手与排障清单三步用起来Figma Desktop → Plugins → Development →Import plugin from manifest...选择 manifest.json打开任意 Figma 文件运行Figma Desktop Bridge状态条变绿显示READY即表示 WebSocket 桥已就绪常见问题速查症状原因与解法服务器换端口后工具失效v1.10.0 前的插件只认 9223重新导入一次 manifest 即可启用多端口扫描N server(s)数字偏大存在僵尸实例会在下次服务器启动时被回收组件描述为空确认插件正在运行REST 兜底路径受已知 API Bug 影响变量不更新重开插件刷新或调用时带refreshCache: true缓存 TTL 5 分钟核心文件索引插件三件套figma-desktop-bridge/manifest.json / code.js / ui.htmlWebSocket 服务器src/core/websocket-server.ts端口发现与僵尸回收src/core/port-discovery.ts服务器侧连接器src/core/websocket-connector.ts技术架构全文docs/architecture.md插件使用文档figma-desktop-bridge/README.md七、总结Desktop Bridge 用三个文件解决了一个两难问题Plugin API 数据全但沙箱封网UI iframe 能上网却没有 API 权限——postMessage 把两者拼成一条完整链路。在此之上{ id, method, params }的轻量协议承载了 70 多种指令9223–9232 端口段加心跳广告牌实现了多实例共存与僵尸自愈FILE_INFO 握手则让多文件并发各安其位。理解了这套机制你就能明白为什么 AI 能实时看见你在 Figma 里的每一次点选又为什么多个 AI 客户端可以互不打架地同时操作设计稿。【免费下载链接】figma-console-mcpYour design system as an API. Connect AI to Figma for extraction, creation, and debugging.项目地址: https://gitcode.com/gh_mirrors/fi/figma-console-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Figma Console MCP Desktop Bridge 深度源码解析：WebSocket 插件桥接 Figma Plugin API 的通信协议与多实例机制
Figma Console MCP Desktop Bridge 深度源码解析WebSocket 插件桥接 Figma Plugin API 的通信协议与多实例机制【免费下载链接】figma-console-mcpYour design system as an API. Connect AI to Figma for extraction, creation, and debugging.项目地址: https://gitcode.com/gh_mirrors/fi/figma-console-mcpfigma-console-mcp 是一个把设计系统变成 API的开源项目让 AI 助手能够连接 Figma 完成提取、创建与调试。它的核心桥梁就是Figma Desktop Bridge 插件通过WebSocket把本地 MCP 服务器的指令转发给 Figma 插件再由插件调用Figma Plugin API读写设计文件。本文带你读懂这套桥接架构的通信协议、端口发现与多实例机制——无需任何代码基础也能理解。一、为什么需要这座桥Figma 官方有两条数据通道但都有短板通道局限REST API已知 Bug组件的description字段经常缺失或过期本地变量需要企业版Plugin API数据最完整、最实时但插件运行在沙箱里不能直接监听端口Desktop Bridge 的巧妙之处就在这里插件沙箱里的 Workercode.js碰不到网络但插件的 UI 界面ui.html是一个标准 iframe允许通过白名单域名发起 WebSocket 连接。于是形成了四层数据流MCP Server ←WebSocket(9223–9232)→ 插件 UI(ui.html) ←postMessage→ 插件 Worker(code.js) ←figma.*→ Figma对应三个文件manifest.json — 插件配置声明了 9223–9232 共 10 个端口的网络白名单code.js — 插件 Worker唯一有权调用 Figma Plugin API 的部分ui.html — 插件 UI真正的 WebSocket 客户端二、通信协议详解消息如何在两端流转2.1 握手与身份识别 服务器端websocket-server.ts在连接建立后先发出一帧SERVER_HELLO包含端口、进程 PID 和服务端版本方便调试定位。插件侧连接后ui.html 中的initializeConnection会做两件事把启动时缓存的变量数据以VARIABLES_DATA消息推给服务器请求文件信息后发送FILE_INFO帧携带fileKey、文件名、当前页面等身份信息服务器会等待最多 30 秒——如果连接始终没有FILE_INFO自我报身份直接断开。这一步让服务器能区分哪个 Figma 文件是后面多文件并发的基础。2.2 请求/响应格式 指令采用极简的 JSON-RPC 风格请求{ id, method, params }响应{ id, result }或{ id, error }method就是命令名插件 UI 里有一张methodMap把 70 多个方法映射到本地函数例如方法作用EXECUTE_CODE在插件沙箱内执行任意 Figma API 代码带超时与空结果预警UPDATE_VARIABLE/CREATE_VARIABLE读写设计令牌变量GET_COMPONENT/DEEP_GET_COMPONENT按需获取组件及其描述绕开 REST API BugCREATE_COMPONENT_SET批量生成变体矩阵超时随变体数量自动放大CAPTURE_SCREENSHOT截图回传这就是服务器把 WebSocket 单包上限开到 100MB 的原因LINT_DESIGN/AUDIT_COMPONENT_ACCESSIBILITY设计校验与无障碍审计2.3 一些值得注意的工程细节 控制台捕获code.js 重写了沙箱内的console.log等方法把日志以CONSOLE_CAPTURE帧经 UI 转发到服务器AI 因此能看见插件运行时输出实现远程调试。Origin 校验防劫持服务器只接受nullFigma 沙箱 iframe和figma.com来源的连接精确匹配而非前缀匹配防范跨站 WebSocket 劫持CSWSH。心跳探活服务器周期性 ping客户端 pong 超过阈值即判定连接死亡并清理。版本协商插件在FILE_INFO中携带PLUGIN_VERSION服务器把它与自身打包的插件版本比对若插件过旧会提示用户重新导入 manifestFigma 会在应用层缓存插件文件重启插件并不够。三、多实例机制端口 9223–9232 的故事3.1 端口回退 你很可能同时开着 Claude Desktop 的 Chat 和 Code 两个标签页或一个桌面端加一个 CLI 终端——每个都会启动一个 MCP 服务器。服务器启动时优先绑定9223被占用就自动顺延尝试 9224、9225……最多 10 个端口port-discovery.ts 中DEFAULT_WS_PORT 9223、PORT_RANGE_SIZE 10也可以用FIGMA_WS_PORT环境变量改首选端口。绑定成功后服务器会在/tmp写下一个广告牌文件figma-console-mcp-{port}.json记录端口、PID 和心跳时间lastSeen供外部工具发现。3.2 僵尸进程回收 最经典的故障现象是服务器明明在跑插件却连不上——根因往往是上次关闭时挂死的僵尸进程占着端口把新服务器挤到回退端口。端口发现模块用三重判据识别僵尸PID 已死亡进程不存在心跳超过 5 分钟未刷新进程卡死文件年龄超过 4 小时无心跳兼容旧版本确认为僵尸后先发SIGTERM给 400ms 优雅退出窗口无响应则升级为SIGKILL强杀port-discovery.ts。此外还有每 5 分钟一次的后台收割器且保证收割过程不阻塞事件循环不会冻住正在执行的工具调用。 插件状态栏里的N server(s)徽章就是一个健康检查如果数字大于你实际打开的 AI 客户端数量就说明有僵尸实例下一次服务器启动时它们会被自动清理。3.3 插件端全端口扫描 后台哨兵 插件启动时执行wsScanAndConnectui.html依次向 9223–9232 发起 WebSocket 连接连接成功即保留——不是只连第一个而是连上所有活跃服务器每个连接独立初始化发送FILE_INFO、推送变量缓存因此每个 AI 客户端都能独立获得 Figma 访问权所有实时事件选区变化、文档修改、变量、控制台日志广播给每一条连接如果扫描时一个服务器都没找到比如你先开了插件才启动 AI 客户端并不会卡死先做最多 3 次快速重试之后转入静默的/health探测循环服务器一出现就自动连上——全程无需重启插件。状态栏的Reconnect按钮可随时强制立即重扫。四、多文件隔离与活动文件切换服务器把每个 Figma 文件视为一个独立客户端按 fileKey 存入 Map每个文件单独维护选区状态、文档变更记录、元数据变更环形缓冲、控制台日志。活动文件会随你在某个文件里的交互选区/翻页自动切换服务器还支持锁定目标文件——AI 在一个文件工作时你在另一个文件的操作不会把指令悄悄路由错地方。这让figma_list_open_files、figma_execute_across_files这类跨文件工具成为可能。五、Cloud Mode没有本地 Node.js 也能写 Figma ☁️除了本地模式插件还支持云端配对AI 客户端生成 6 位一次性配对码5 分钟有效、单次使用插件输入后与云中继建立wss://TLS 连接。此后网页端 AI 平台也能把写指令经中继送达你的 Figma 文件。本地与云端连接可同时存在互不干扰。实现见 cloud-websocket-relay.ts 与 cloud-websocket-connector.ts完整架构说明见 docs/architecture.md。六、快速上手与排障清单三步用起来Figma Desktop → Plugins → Development →Import plugin from manifest...选择 manifest.json打开任意 Figma 文件运行Figma Desktop Bridge状态条变绿显示READY即表示 WebSocket 桥已就绪常见问题速查症状原因与解法服务器换端口后工具失效v1.10.0 前的插件只认 9223重新导入一次 manifest 即可启用多端口扫描N server(s)数字偏大存在僵尸实例会在下次服务器启动时被回收组件描述为空确认插件正在运行REST 兜底路径受已知 API Bug 影响变量不更新重开插件刷新或调用时带refreshCache: true缓存 TTL 5 分钟核心文件索引插件三件套figma-desktop-bridge/manifest.json / code.js / ui.htmlWebSocket 服务器src/core/websocket-server.ts端口发现与僵尸回收src/core/port-discovery.ts服务器侧连接器src/core/websocket-connector.ts技术架构全文docs/architecture.md插件使用文档figma-desktop-bridge/README.md七、总结Desktop Bridge 用三个文件解决了一个两难问题Plugin API 数据全但沙箱封网UI iframe 能上网却没有 API 权限——postMessage 把两者拼成一条完整链路。在此之上{ id, method, params }的轻量协议承载了 70 多种指令9223–9232 端口段加心跳广告牌实现了多实例共存与僵尸自愈FILE_INFO 握手则让多文件并发各安其位。理解了这套机制你就能明白为什么 AI 能实时看见你在 Figma 里的每一次点选又为什么多个 AI 客户端可以互不打架地同时操作设计稿。【免费下载链接】figma-console-mcpYour design system as an API. Connect AI to Figma for extraction, creation, and debugging.项目地址: https://gitcode.com/gh_mirrors/fi/figma-console-mcp创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考