figma-context-mcp

Figma Context MCP

Figma Context MCP（又称 Framelink）的专家指南。介绍高效的 API 使用模式，避免因 429 错误而受到速率限制。

工具

工具	用途	API 层级
get_figma_data	获取文件／节点结构、布局、组件	Tier 1（限制最严格）
download_figma_images	导出指定节点的 PNG／SVG 渲染图	Tier 2-3

关键：速率限制

Figma 会根据套餐实施速率限制。限制取决于文件所有者的套餐，而不是你的套餐：

层级	Starter	Pro	Org
Tier 1（文件）	10/min	15/min	20/min
Tier 2（图像）	25/min	50/min	100/min
Tier 3	50/min	100/min	150/min

查看／协作席位每月只能进行 6 次 Tier-1 调用。如果访问的文件属于 Starter／免费套餐用户，则你也会受到其限制。

429 锁定可能持续 4-5 天。预防至关重要。

工作流：元数据优先流程

切勿一开始就获取所有内容。 采用此流程，使大多数任务的 API 调用次数控制在 2-3 次以内，数据量低于 500 KB：

1. 从目标节点开始，而不是整个文件

当用户提供类似 figma.com/design/FILEKEY/Name?node-id=123-456 的 Figma URL 时，始终提取并传入 nodeId。有指定节点时，切勿获取整个文件。

get_figma_data(fileKey="ABC123", nodeId="123-456", depth=2)

2. 使用最小深度

始终设置 depth，以限制树的遍历范围：

• depth=1：仅顶层框架（布局结构、组件名称）
• depth=2：框架及其直接子级（通常足以用于代码生成）
• depth=3：建议的最大深度——仅在嵌套自动布局有需要时使用

如果省略，默认行为是：API 返回整个子树——对于含有 50-200 多个子级的复杂框架，数据量通常可达数 MB。这是导致 429 错误的首要原因。

3. 先在本地分析，再获取更多内容

收到初始响应后：

• 确定哪些子节点确实需要详细信息（跳过隐藏节点、装饰性节点或引用库的节点）
• 直接从响应中提取设计令牌（颜色、间距、排版）——无需额外调用
• 根据已有信息构建组件结构

4. 仅在必要时获取更深层节点

如果需要了解特定子节点的更多信息，只获取该节点：

get_figma_data(fileKey="ABC123", nodeId="child-node-id", depth=1)

5. 最后再下载图像，且分小批处理

仅为你实际需要的最终去重后的视觉资源集请求图像：

• 按 imageRef 去重——多个节点可能引用同一张填充图像
• 每次调用分批处理 5-10 个节点
• 除非用户明确需要 @2x/@3x 资源，否则使用 pngScale=1

download_figma_images(
  fileKey="ABC123",
  nodes=[{nodeId: "1:2", fileName: "hero", ...}],  # max 5-10 per call
  localPath="./assets",
  pngScale=1
)

遇到 429 时

诊断和恢复步骤请参阅 references/rate-limit-recovery.md。

快速检查清单：

1. 立即停止所有 Figma API 调用——额外调用会延长锁定时间
2. 检查文件是否属于 Starter／免费套餐用户（限制按所有者计算）
3. 如果用户使用 Pro/Org 套餐，建议将文件复制到他们自己的工作区
4. 等待 Retry-After 标头指定的时长后再重试
5. 重试时使用上述最小深度流程

常见模式

设计转代码（单个组件）

1. 使用特定 nodeId 和 depth=2 调用 get_figma_data（1 次调用）
2. 根据响应生成代码——除非组件包含栅格资源，否则无需调用图像工具
3. 如需图像：仅对栅格填充调用 download_figma_images（1 次调用）
4. 总计：1-2 次 API 调用

设计转代码（完整页面）

1. 使用页面 nodeId 和 depth=1 调用 get_figma_data，获取框架列表（1 次调用）
2. 找出 2-3 个关键框架
3. 对每个关键框架使用 depth=2 调用 get_figma_data（2-3 次调用）
4. 在本地提取令牌，仅下载不重复的栅格资源（1 次调用）
5. 总计：4-5 次 API 调用

仅提取设计令牌

1. 使用 get_figma_data，设置 nodeId + depth=2（1 次调用）
2. 从响应中解析颜色、排版和间距——无需调用图像接口
3. 总计：1 次 API 调用

反模式

模式	问题	修复方法
省略 depth	返回整个子树（数 MB 数据）	始终将 depth 设为 2 或更小
省略 nodeId	获取整个文件	始终从 URL 中提取 nodeId
预先下载所有图像	突发的图像请求会触发 Tier 2 限制	仅下载最终去重后的集合
遇到 429 时重试	延长锁定时长	停止，等待 Retry-After，然后以最少调用次数恢复
获取库组件	远程库节点会触发额外的 API 调用	使用初始响应中的本地组件数据