SuperAPI AI 工具集

bridge-troubleshooting

编程与开发

查看项目

更新于 11-05 16:18

技能介绍

本技能用于诊断 figma-mcp-rust 与 Figma 之间的桥接连接问题。figma-mcp-rust 通过本地 WebSocket(默认 ws://127.0.0.1:1994)与一个配套的 Figma 插件通信,因此每次工具调用都需要该插件在 Figma Desktop 中运行。

主要用途与能力:针对几类典型故障提供排查步骤,包括“plugin not connected”、请求超时、端口 1994 已被占用,以及多个 MCP 客户端同时运行时的连接情况。

一、报错 plugin not connected:说明 MCP 服务已启动,但没有 Figma 插件接入。处理方式是打开 Figma Desktop(不是浏览器)并打开目标文件;若插件未安装,从 GitHub Releases 页面下载 plugin.zip,在 Figma Desktop 中依次点击 Plugins、Development、“Import plugin from manifest”,选择解压后的 manifest.json,然后运行插件(Plugins、Development、figma-mcp-rust)并保持其窗口打开;确认插件界面显示已连接后重试。插件窗口必须保持打开,关闭即断开桥接。

二、请求超时:插件已连接但操作耗时过长(默认 30 秒,get_document 为 60 秒)。对于超大页面,建议改用 get_design_context 并将 detail 设为 minimal 或 compact、使用较小的 depth,而不是 get_document;在超大节点树上执行 scan_text_nodes、scan_nodes_by_types 等扫描工具时,应指定较小的子树 nodeId;若 Figma 本身卡死或弹出对话框,关闭后重试。

三、端口 1994 已被占用:若占用者是另一个 figma-mcp-rust 实例,属于正常情况——各实例会在该端口上选举 leader,其余实例自动跟随,无需处理;若占用者是无关应用,则用 --port 参数启动服务,并在 Figma 插件界面中把 host/port 改为一致。

四、多 MCP 客户端(如 Claude Code 与 Cursor 同时运行):受支持。第一个服务进程绑定 1994 端口并成为 leader,持有 Figma WebSocket,后续进程检测到健康的 leader 后转发请求;leader 退出后,follower 会在下次尝试时接管端口。

适用场景:figma-mcp-rust 工具调用出现连接类异常时的快速排查。限制:本技能只覆盖连接层排查,不涉及 figma-mcp-rust 的其他功能;写操作可用 Ctrl/Cmd+Z 撤销。