localfig 的目标是把 Figma 桌面应用当作一个 MCP（Model Context Protocol）服务器来使用，从而让 AI 智能体在你当前打开的 Figma 文件中获得完整的 Figma Plugin API 能力。它由两部分组成：一个安装在 Figma 里的极小开发插件，以及一个只绑定本机回环地址的 HTTP 桥接，全部运行在本地。
【用途】 让 AI 智能体直接对打开中的 Figma 文件进行读取与写入操作：帧、文本、自动布局、变量、组件、图片填充、导出、撤销等，凡是 Plugin API 能做到的，智能体都可以做。它不依赖 Figma 云端 API，不需要个人访问令牌，也没有按账号计算的配额，数据不会离开本机。
【主要能力】
- 读写文件：通过 figma_eval 在插件沙箱中执行代码，代码被包裹在异步函数里，支持顶层 await 和 return；可用全局对象 figma 和 helpers。
- helpers 提供一系列便捷方法：createText（创建文本并正确加载字体、先 resize 再设置 textAutoResize）、setText、loadNodeFonts、set（批量赋值，先处理 layoutMode 再 resize）、rgb / rgba（十六进制转填充色）、reveal（滚动缩放视口到新建节点）、notify（弹提示）、collection / token / bind（一行创建设计令牌并绑定属性）、importComponent / instance（团队库组件）、query（极简选择器，支持 TEXT、[name=X]、[name*=X]、A B、a, b 等）、createAutoLayout、command（在脚本内运行类型化命令，如 tokens、metadata、find、changes、export）。
- 设计系统感知：figma_tokens 按设计系统的方式返回文件变量；figma_metadata 在 styles: true 时报告每个节点的 boundVariables、fillStyle / textStyle / effectStyle 名称、实例的主组件及其 componentProperties，css: true 还会附加 Figma 计算出的 CSS，帮助智能体基于设计系统构建而不是硬编码数值。
- 图片进出：figma_place_image 把文件字节送到插件 UI（完整 Chromium iframe），解码任意浏览器支持的格式，按 maxSide 缩放（默认 4096，Figma 硬上限）并做高质量平滑，非原生格式转 PNG；figma_export 把文件写到 ~/.localfig/exports/，并把 PNG/JPG（每个 ≤ 2 MB）作为图片附加到结果中，JSON 导出按 Figma REST API 结构返回子树。
- 撤销、版本与变更跟踪：每个修改类工具调用都用 figma.commitUndo 建立检查点，作为可手动 Ctrl+Z 的一步进入文件撤销历史（最近一次调用在完成后 60 秒或下一次调用时提交）；在该窗口内 figma_history 的 action: "undo" 可从智能体侧回退，triggerUndo 回到最近检查点，action: "snapshot" 在风险编辑前保存命名版本。插件还会记录它见过的每个页面上的节点变更，figma_changes 返回自某 seq 以来的变化，工具调用引起的编辑按时间窗口启发式标记为 byPlugin 并默认隐藏。
- 多会话：第一个 localfig 进程占用桥接端口，后续进程通过 /health 检测并以客户端身份代理转发，工具一致；若属主退出，下一次工具调用会重新绑定端口接管，插件重连后重新注册。
【使用方式】 环境要求：Node.js 18 或更高版本；Figma 桌面应用（开发插件无法在浏览器中导入）；一个 MCP 客户端（如 Claude Code、Cursor、Windsurf、Cline、Claude Desktop 等）。
- 安装与注册：运行 npx localfig 会生成本地密钥，把插件写入 ~/.localfig/plugin/，并把它能找到的每个 MCP 客户端都注册上 localfig，然后打印清单路径。--dry-run 只显示将要做什么而不做改动，--clients=cursor,vscode 可限定只注册指定的客户端。也可克隆仓库后执行 git clone https://github.com/LucasGorgal/localfig.git && cd localfig && node server.mjs --setup。客户端配置文件夹存在即视为已安装；设置会合并进现有文件而不是覆盖，已有 localfig 条目保留其 env，改动前写出 .localfig.bak 备份；无法安全重写的文件（如带注释的 settings.json）保持原样并给出需粘贴的条目；已打开的客户端需重启。
- 未列入的客户端，可将其加入 MCP 配置，命令为 npx -y localfig。在 Windows 上应改用 "command": "cmd", "args": ["/c", "npx", "-y", "localfig"]。
- 导入插件（只需一次）：在桌面应用中打开任意设计文件（Plugins 菜单只在文件内存在），Figma 菜单 → Plugins → Development → Import plugin from manifest…，或按 Ctrl /（Cmd /）输入 import plugin from manifest，选择 ~/.localfig/plugin/manifest.json。清单申请 teamlibrary 和 currentuser 两个权限，并注册一个重新启动按钮。
- 每次使用：打开目标文件，按 Ctrl / 选择 localfig（或 Ctrl Alt P / Cmd Opt P 重跑上一个插件，或用文件属性面板中的 Reconnect localfig 按钮），出现小面板并显示 Connected to localfig 后保持打开，即可让智能体对当前文件执行 Figma 操作。关闭面板或文件会断开，需重新运行插件；这是唯一的手动步骤，因为 Figma 不允许从外部启动插件。
【沙箱与安全】 桥接只绑定回环地址（127.0.0.1 和 ::1）。除 /health 外的每个端点都需要首次运行时生成并写入 ~/.localfig/token 的 32 位十六进制密钥，该密钥也被写入 ~/.localfig/plugin/ui.html。应编辑包中的 plugin/ui.template.html，不要修改生成的 ui.html。不会向任何服务器发送数据。
【适用场景】 希望让 AI 智能体直接在打开的 Figma 文件上读改设计、创建设计令牌、绑定属性、导入团队库组件、导出渲染并看到结果，同时不愿使用云端 API 或令牌、关注数据本地化的团队与个人。
【限制与注意事项】
- 需要 Figma 桌面应用，浏览器中无法导入开发插件。
- 每次会话需手动在 Figma 中运行插件以建立连接。
- 插件主线程没有网络，只有 UI iframe 有；因此采用 HTTP 长轮询而非 WebSocket；Figma 清单校验器不接受 networkAccess 中的裸 IP，因此使用 localhost，并监听 IPv6 镜像地址以应对 Windows 先解析到 ::1 的情况。
- 从 figma_eval 返回真实节点会被折叠为 {id, name, type}，避免结果被淹没，可用 figma_metadata 检查子树。
- 修改文本前必须加载字体；TEXT 节点上 resize() 会把 textAutoResize 重置为 NONE，自动布局帧上会同时把两种 sizing 设为 FIXED，因此应先 resize 再设 sizing。
- 二进制在插件通道保持二进制：导出走 POST /blob，图片经 GET /asset 进入 Uint8Array，只有 JSON 走命令通道（渲染在 MCP 结果中按协议要求做一次 base64 编码）。
- 使用主目录是因为包可能位于 npx 缓存或只读全局安装中，导入的插件文件夹在包更新时不能移动，且用户状态不应放在包内。
- 开发与测试环境为 Windows 11 加 Figma 桌面应用；macOS 和 Linux 理论可用（仅 Node 内置模块、无原生代码）但尚未实际验证。
- 使用 MIT 许可证。
【暂未提供】 未提供具体的收费或定价信息、支持的其他客户端完整清单、性能基准数据以及 macOS/Linux 的实测结果。
