OPEN SOURCE DEEP DIVE
Framelink MCP for Figma:把设计稿压成模型能吃的上下文,而不是一张截图
即 Figma-Context-MCP,npm 包名 figma-developer-mcp,TypeScript,MIT,第三方实现(不是 Figma 官方的 Dev Mode MCP)。对外只有两个工具:get_figma_data(只读)与 download_figma_images(可用 –skip-image-downloads 整个关掉,且只在 –image-dir 之内写文件)。工具面窄是刻意的,工程量全在背后那条 fetch → simplify → serialize 管线:simplify 用可组合抽取器(layout / text / visuals / component,另有 allExtractors、layoutAndText、contentOnly、visualsOnly、layoutOnly 五档组合)在单次树遍历里把 Figma 原始响应压成语义化的布局与样式,支持 maxDepth 与 nodeFilter,输出 tree(默认,最省 token)/ yaml / json 三档。最值得同行学的是它把「压缩有没有效果」做成每次调用都算出来的指标:rawSizeKb 对 simplifiedSizeKb、rawNodeCount 对 simplifiedNodeCount、组件与实例与文本与图片节点数、namedStyleCount(源码注释直说数值高是设计系统成熟度信号)、hasVariables(有没有用上 Figma Variables)、以及 fetch/simplify/serialize 三段分开的耗时;同一批钩子还驱动 MCP progress 通知与心跳,大文件拉几十秒时客户端不会看起来像卡死。细节里全是判断:node ID 支持普通与深层嵌套实例两种形状、depth 的工具描述写着「除非用户明确要求不要用」、代理默认值刻意不在无代理变量时装 EnvHttpProxyAgent 以免陈旧变量把流量导到会返 403 的中间人、stdio 模式没设 image-dir 会在启动时警告。凭据支持 FIGMA_API_KEY 或 FIGMA_OAUTH_TOKEN,遥测可用 –no-telemetry / DO_NOT_TRACK=1 关且上报会脱敏。15.9k★。它不生成任何前端代码——产物是设计事实,翻译成 React/Vue/SwiftUI 的是你的 coding agent。我们未连自己的 Figma 文件跑过,也未做「截图 vs 结构化数据」的准确率对照,记为待复现。
一句话定位
Framelink MCP for Figma(仓库名 GLips/Figma-Context-MCP,npm 包名 figma-developer-mcp)是一个 TypeScript 写的 MCP server,MIT 协议,只做一件事:把 Figma 的设计数据喂给写代码的 agent,让它一次性把设计还原成任意框架的代码。README 的核心主张很直接——拿到结构化的 Figma 数据之后,agent 一次成型的准确率「远高于」贴截图这类替代做法。
它对外只暴露两个工具:get_figma_data(只读,标注 readOnlyHint)与 download_figma_images(标注 openWorldHint,可用 --skip-image-downloads 整个关掉)。工具面这么窄是刻意的:这个项目真正的工程量不在「多几个工具」,而在两个工具背后那条把 Figma API 原始响应压缩成模型能吃的上下文的流水线。
核心机制:一次遍历、可组合的抽取器
get_figma_data 的管线是 fetch → simplify → serialize 三段,同一份代码同时供 MCP 工具与 CLI 的 fetch 命令使用。simplify 这一段是全部价值所在:
| 层 | 实现 | 作用 |
|---|---|---|
| 策略层 | layoutExtractor / textExtractor / visualsExtractor / componentExtractor,以及组合档 allExtractors、layoutAndText、contentOnly、visualsOnly、layoutOnly | 决定「这次要哪些信息」,可按用途切档:内容盘点只要文字,设计系统只要视觉样式 |
| 遍历层 | 单次树遍历(node-walker),支持 maxDepth 与 nodeFilter | 无论挂几个抽取器,树只走一遍;深度与节点类型可裁 |
| 抽取层 | 纯函数,把单个节点的原始字段转成简化结构;收尾还有 collapseSvgContainers | 把 Figma 的冗长原始表示压成布局与样式的语义化描述 |
输出格式有三档:tree(默认)、yaml、json,由 --format 或环境变量 OUTPUT_FORMAT 决定(--json 是 --format=json 的向后兼容别名),取值非法会在启动时直接报错而不是静默降级。默认给 tree 而不是 JSON,是因为同样的信息量下 tree 更省 token。
它自己量了什么:一次调用的完整指标
这个项目最值得同行学的地方,是它把「压缩有没有效果」做成了每次调用都算出来的指标(GetFigmaDataMetrics),而不是停留在口号上:
- 压缩比:
rawSizeKb对simplifiedSizeKb,rawNodeCount对simplifiedNodeCount。前者是用户问的那棵树有多复杂,后者是真正发给模型的负载有多大。 - 结构画像:
componentCount、instanceCount、textNodeCount、imageNodeCount(通过globalVars.styles里含 IMAGE/PATTERN 填充反查)、componentPropertyCount、maxDepth。 - 设计系统成熟度:
namedStyleCount数的是 Figma Styles 面板里用户自己建的可复用样式,源码注释直接写明「数值高是设计系统成熟度信号」;hasVariables看有没有节点带boundVariables,也就是有没有用上 Figma Variables。 - 耗时分解:
fetchMs/simplifyMs/serializeMs三段分开记,慢在哪一段一目了然。
这套指标还顺带解决了 agent 的用户体验问题:管线在每一段边界发 MCP progress 通知(0/3 拉取、1/3 简化、2/3 序列化),并用心跳持续报「Waiting for Figma API response」「Simplifying design data (N nodes processed)」。大文件拉几十秒的时候,客户端不会看起来像卡死。
工程细节里藏着的判断
- node ID 有两种形状:普通的
1234:5678,以及深层嵌套实例的I5666:180910;1:10515;1:10336——分号连起来的其实是同一条实例覆盖链,仍是一个节点 ID 而不是多个。参数 schema 的正则专门为这两种都写了,工具内部再把-换成 Figma API 要的:。 depth的工具描述写着「除非用户明确要求,不要用」。这是在用工具描述本身约束模型行为,防止它自作主张只取浅层、然后基于残缺信息写代码。- 代理的默认值是个安全决定:显式给了 proxy URL 用
ProxyAgent;没给但环境里有代理变量才用EnvHttpProxyAgent;两者都没有就走 Node 默认。源码注释说明这是刻意的——不在无代理变量时装EnvHttpProxyAgent,免得用户 shell 里一个陈旧的或 VPN 客户端留下的变量,悄悄把访问 api.figma.com 的流量导到一个会返 403 的中间人身上。还提供--proxy=none显式退出系统级代理变量。 - 图片落盘位置会警告:stdio 模式下如果没设
--image-dir,启动就往 stderr 打一条警告,因为 MCP 客户端拉起 server 的 cwd 往往不是项目根目录,不设就会把图存到客户端的安装目录里。 - 凭据与遥测:支持
FIGMA_API_KEY(个人访问令牌)或FIGMA_OAUTH_TOKEN;stdio 模式没有按请求传凭据的通道,所以启动时就要求凭据可解析,解析不出来直接失败退出,而且是在装代理、初始化遥测这些副作用之前就退。遥测默认开启,可用--no-telemetry、FRAMELINK_TELEMETRY=off或DO_NOT_TRACK=1关掉;错误上报会主动把 API key 与 OAuth token 脱敏。download_figma_images只允许在--image-dir之内写文件,越界的写入会被拒。
边界:它不是 Figma 官方,也不生成代码
要分清三件事。Figma 官方在桌面端有 Dev Mode MCP server,走的是 Figma 自己的账号体系与选区语义;Framelink 是第三方开源实现,只需要一个个人访问令牌打 Figma REST API,好处是任何支持 MCP 的客户端都能用、可以自己改抽取策略,代价是拿不到官方那套选区与代码连接的深度整合。至于 Figma Make,那是 Figma 自家的「提示词直接生成可运行界面」的产品,与本项目不在同一条路上:一个替你生成,一个把设计事实交给你的 agent 去生成。
本项目也不写任何前端代码。它的产物是一段结构化的设计描述,真正把描述翻译成 React/Vue/SwiftUI 的是你的 coding agent。「一次性还原准确率更高」是 README 的定性说法,它没有给基准数字,我们也没有做对照实验。
在 agientry 里的位置
设计一档里,本站收了 v0 与 lovable 这类「提示词直接出可部署界面」的产品,也收了 ui-ux-pro-max-skill 这类让 agent 自己更会做界面的技能。Framelink 补的是中间那一段——已经存在的设计稿如何无损进入 agent 的上下文。在企业里这一段往往是最贵的:设计系统已经在 Figma 里沉淀好了,重写一遍前端才是浪费。与 img2threejs 的对照也清楚:那个从图像出 3D 场景代码,这个从矢量设计稿出 UI 事实;两者都在解「视觉输入如何变成可执行的结构化输入」。
本页事实来自项目 README(实读全文)与仓库源码:src/mcp/index.ts(工具注册与 annotation)、src/mcp/tools/get-figma-data-tool.ts(参数 schema 与进度钩子)、src/services/get-figma-data.ts(三段管线)、src/services/get-figma-data-metrics.ts(指标定义)、src/extractors/README.md(抽取器架构)、src/config.ts 与 src/server.ts(传输、凭据、代理、遥测);星标、协议、语言取自 GitHub API。我们没有连自己的 Figma 文件跑过它,没有量化压缩比,也没有做「贴截图 vs 结构化数据」的准确率对照,因此这一条记为待复现。