Figma-Context-MCP（figma-developer-mcp）版本演进全解析：从 v0.2 到 v0.13 的核心能力与实现原理

本文以仓库根目录 CHANGELOG.md 为主线，系统梳理 Figma-Context-MCP 项目（npm 包名 figma-developer-mcp，当前版本 0.13.2，见 package.json）从 v0.2 到 v0.13 的功能演进脉络。该项目的定位是为 Cursor 等 AI 编程 Agent 提供 Figma 布局信息的 MCP 服务器：在把 Figma API 原始数据交给大模型之前，先进行"简化与翻译"，只保留对实现界面最有用的布局与样式信息，从而降低上下文开销、提升一次性实现设计的准确率。读完本文，你将掌握该项目三大技术主线——输出格式（YAML/JSON/tree）的演进、设计数据简化引擎（布局/样式/文本/效果）的实现原理、以及认证与传输模式的变迁，并能对照源码定位每一处关键实现。

---

一、项目概览：它解决什么问题

Figma-Context-MCP 的工作流程非常直观（参见 README.md）：

1. 在 IDE 的聊天窗口（如 Cursor 的 Agent 模式）中粘贴 Figma 文件、Frame 或 Group 的链接；
2. 让 Cursor 对设计稿做点什么（例如"实现这个设计"）；
3. MCP 服务器从 Figma API 拉取元数据，先简化再交付，Agent 据此编写代码。

其核心价值在于"简化"。原始 Figma API 响应中充斥着大量与前端实现无关的字段（坐标体系差异、内部 ID、auto-generated 层名等），直接塞给 LLM 既浪费 token 又引入噪声。因此项目的几乎所有版本迭代都围绕一个目标：让序列化输出更小、更准、更贴近 CSS 语义。

从源码结构看，该项目采用典型的三层架构：

• 提取层（extractors）：src/extractors/ 负责遍历 Figma 节点树（含异步 tree walker）并收集原始设计信息；
• 转换层（transformers）：src/transformers/ 将原始 Figma 数据翻译为 CSS 语义（布局、样式、渐变、效果、文本）；
• 服务与序列化层（services / utils）：src/services/get-figma-data.ts 组织拉取流程，src/utils/serialize.ts 决定最终输出格式。

---

二、输出格式的演进：YAML → JSON → tree

输出格式是该项目迭代最频繁的一条主线，也直接体现了"为 LLM 压缩上下文"的设计哲学。

2.1 早期：YAML 与 JSON（v0.4.x）

• v0.4.1 引入 --json CLI 标志与 OUTPUT_FORMAT 环境变量，在 YAML 之外支持 JSON 输出，方便与 jq 等标准 shell 工具链配合；
• v0.3.0 起简化输出会移除空 key（"Remove empty keys from simplified design output"），避免序列化结果中出现无信息的字段。

这一时期的默认输出是 YAML，因为 YAML 相比 JSON 更省 token、可读性更好，适合直接注入 LLM 上下文。

2.2 实验性 tree 格式（v0.12.0）

v0.12.0 引入实验性的 tree 输出格式，目标非常明确："better token efficiency"（更好的 token 效率）。tree 格式不再输出完整字段名（如 fontSize: 16），而是采用带缩进的紧凑层级写法，类似：

Frame 1
  Text: "Hello" [16, "Inter"]

这种格式把"字段名 + 值"压缩为"值"，在节点树嵌套较深时能显著削减 token 占用。

2.3 tree 成为默认（v0.13.0）

v0.13.0 将 MCP 服务器端的默认输出从 yaml 切换为 tree（"default output to tree instead of yaml"）。但请注意一个关键差异（实现细节见 src/commands/fetch.ts）：

CLI fetch 子命令仍然默认 yaml。因为它的输出要喂给 shell 管道（> out.yaml、| jq），而 tree 的专属缩进格式无法被标准工具解析；tree 的 token 优势只属于 LLM 消费方，不属于命令行管道。

三种格式的最终分发逻辑集中在 src/utils/serialize.ts：serializeResult 根据 format 分别调用 JSON.stringify（json）、serializeAsTree（tree，见 src/utils/serialize-tree.ts）或 dumpYaml（yaml，见 src/utils/yaml-dump.ts）。格式的合法性校验由 src/config.ts 的 parseOutputFormat 完成——非法的 --format 值会在启动时直接抛错，而不是静默降级。

2.4 配置优先级链：CLI 标志 → 环境变量 → 默认值

输出格式只是 src/config.ts 管理的大量配置项之一。所有配置项遵循统一的优先级链，由 resolve() 函数实现（src/config.ts）：

CLI 标志（--flag） → 环境变量 → 内置默认值

关键配置及其默认值汇总如下（源码证据：src/config.ts、src/bin.ts）：

配置项	CLI 标志	环境变量	默认值
Figma API Key	--figma-api-key	FIGMA_API_KEY	空（必填或改用 OAuth）
OAuth Token	--figma-oauth-token	FIGMA_OAUTH_TOKEN	空
端口	--port	FRAMELINK_PORT / PORT	3333
监听地址	--host	FRAMELINK_HOST	127.0.0.1
输出格式	--format（--json 为兼容别名）	OUTPUT_FORMAT	tree（服务器端）
跳过图片下载	--skip-image-downloads	SKIP_IMAGE_DOWNLOADS	false
图片下载目录	--image-dir	IMAGE_DIR	当前工作目录
代理	--proxy	FIGMA_PROXY	无
自定义 .env	--env	—	当前目录 .env
关闭遥测	--no-telemetry	FRAMELINK_TELEMETRY / DO_NOT_TRACK	遥测开启

其中 --json 在 src/bin.ts 中被明确注释为"--format=json 的向后兼容别名"；--format 优先级更高。--env 支持自定义 .env 文件（v0.4.2 引入），通过 src/config.ts 的 loadEnvFile 加载，且以 override: true 强制覆盖进程内已有变量。

---

三、简化引擎：让输出更小、更准

"简化"是项目的主旋律，CHANGELOG 中大量条目都属于此类优化。

3.1 节点命名噪声清理（v0.13.1）

v0.13.1 从序列化输出中移除冗余的、自动生成的节点名。实现位于 src/utils/node-names.ts：

• Figma 会为新图层自动命名 Rectangle 12、Frame 5、Ellipse 6 这类"工具名 + 序号"；
• isAutoGeneratedName 通过正则精确匹配 Frame|Rectangle|Ellipse|Line|Vector|Group|Component|... 加空格加数字的形态。源码注释强调：尾部的 \d+ 是必需的——单独的 Line、Group 很可能是设计师起的真名，不能误删；
• isNoiseName 进一步将 TEXT 节点整体丢弃：Figma 用文本内容给 TEXT 层命名，名称几乎总是与已输出的 text 字段重复，甚至是内容修改后残留的旧名，会误导 LLM。

3.2 样式与子树去重（v0.13.0）

v0.13.0 的 extractors 层新增"对重复样式与重复子树去重以压缩输出"（deduplicate repeated styles and subtrees）。其思路与样式引用（style ref）机制一脉相承：多个节点若共享相同的视觉属性（如同一套卡片样式），只输出一次定义，其余节点以引用 ID 指回，从而大幅削减重复字段。

这一机制在文本富文本样式中已有成熟形态（见 3.4 节的 {ts1}...{/ts1} 内联样式引用），并在 v0.8.1 中支持了"重名命名样式的消歧"（disambiguate named styles with duplicate names，v0.8.1）——当 Figma 中存在多个同名命名样式时，返回具名样式而不是自动生成的 ID（v0.6.0 引入具名样式支持）。

3.3 纯色填充栈拍平（v0.13.0）

v0.13.0 的 fills 逻辑新增："将所有纯色填充栈拍平为单一解析颜色"（flatten all-solid fill stacks into a single resolved color）。Figma 中一个图层可以叠加多层纯色填充，视觉上等价于某一层"赢了"；此前会逐层输出，现在直接算出一个最终颜色，既准确又省 token。fills 的解析入口在 src/transformers/style.ts 的 parsePaint。

3.4 文本样式：em 化与富文本（v0.13.0 / v0.11.0）

文本是 CHANGELOG 中反复打磨的领域，两个关键演进是：

• v0.13.0：letterSpacing 与相对 lineHeight 统一以 em（而非 %）输出。实现见 src/transformers/text.ts 与 formatLineHeight（同文件 L134-L155）：PIXELS 单位输出 24px，FONT_SIZE_% 输出 1.5em，INTRINSIC_%（auto）则直接省略。注释解释了为什么 em 而不是 %：em 可直接粘贴进 CSS，同时 iOS/Flutter 等原生端用同一 textStyle 中的 fontSize 相乘即可还原绝对值；且 em 按 4 位小数舍入（emRound），保留旧 % 形式的精度（0.01% = 0.0001em）。
• v0.11.0：富文本样式（rich text styling），这是文本处理的一次能力跃升。src/transformers/text.ts 的 buildFormattedText 实现了完整的"Markdown + 内联样式引用"双通道渲染：
  • 加粗/斜体/删除线/URL 超链接映射为 Markdown 标记（**、*、~~、text）；
  • Markdown 无法表达的属性（如比基准更轻的字重、反向的"取消下划线"、NODE 型超链接）落入 {tsN}...{/tsN} 样式引用；
  • 嵌套渲染顺序为 {tsN} → [link] → ~~ → ** → *，保证样式引用包裹视觉区域、Markdown 标记贴近文本；
  • 支持有序/无序列表（lineTypes / lineIndentations，CommonMark 2 空格缩进嵌套）；
  • 换行被转义为字面 \n（反斜杠 + n 两个字符），避免 YAML 序列化器把多行文本变成带缩进的块标量（src/transformers/text.ts）。

3.5 效果系统：阴影与模糊（v0.13.0 / v0.3.0）

src/transformers/effects.ts 实现了效果的简化输出，CHANGELOG 中两处关键修正：

• v0.13.0："halve Figma blur radius for CSS and omit zero-radius blur"——Figma 的模糊半径约为 CSS blur() 半径的 2 倍（源码注释引用 Figma Dev Mode 佐证：Figma 的 32 模糊渲染为 CSS blur(16px)），因此输出时除以 2；半径为 0 的模糊是无操作，直接丢弃，不输出 blur(0px) 死代码。
• v0.3.0：文本节点上的阴影应用 text-shadow 而非 box-shadow（src/transformers/effects.ts 中按 n.type === "TEXT" 分流）。

此外 DROP_SHADOW 与 INNER_SHADOW 统一合入 box-shadow（内阴影加 inset 前缀），LAYER_BLUR 走 filter、BACKGROUND_BLUR 走 backdrop-filter。

3.6 渐变：从透传到计算（v0.5.1 → v0.13.2）

渐变处理经历了从"透传原始数据"到"完整计算"的转变：

• v0.5.1："Calculate gradient values instead of passing raw Figma data"——不再把 Figma 的 handle 坐标原样交付；
• v0.13.2："apply paint-level opacity to gradient fills"——渐变整体透明度（paint opacity）要乘入每个色标的 alpha（src/transformers/style/gradient.ts）。

src/transformers/style/gradient.ts 的实现相当细致：线性渐变会把 Figma 的 handle 线段延长到元素边界（findExtendedLineIntersections），再把色标位置映射到延长后的完整渐变线上（L43-L101），从而得到正确的 CSS 角度与色标百分比；四种渐变类型统一映射为 CSS 语法：

Figma 渐变类型	CSS 输出
GRADIENT_LINEAR	linear-gradient(deg, ...)
GRADIENT_RADIAL	radial-gradient(circle at x% y%, ...)
GRADIENT_ANGULAR	conic-gradient(from deg at x% y%, ...)
GRADIENT_DIAMOND	radial-gradient(ellipse at x% y%, ...)（近似）

---

四、布局引擎：从 flex 到 CSS Grid

布局是 Figma-Context-MCP 输出的核心内容，其演进体现了"从 Figma 布局语义到 CSS 布局语义"的映射能力不断增强。

4.1 CSS Grid 支持（v0.13.0，重大特性）

v0.13.0 引入 CSS Grid 布局支持（src/transformers/layout/grid.ts），这是近期最大的功能增量。实现细节值得展开：

• 子节点重排序：computeGridChildOrder（L24-L59）按 gridRowAnchorIndex / gridColumnAnchorIndex 对子节点排序。原因（源码注释）：Figma 按 z 序（从后到前）返回 children，与 CSS auto-placement 依据的 DOM 顺序可能不一致，直接按 z 序输出会落错格子。排序后即可输出无需每子节点显式 grid-column / grid-row 的流式网格 CSS。ABSOLUTE 定位子节点不参与网格流，保持原位。
• 打包检测：isPackedGrid（L62-L92）检查网格是否被无空格的子节点填满。打包网格只输出跨列/跨行（span N），非打包网格才输出 1-based 的 gridColumn / gridRow（含 col / span n 形式）。
• zIndex 保留：gridChildrenOverlap（L106-L128）检测子节点 AABB 相交；仅当发生重排且子节点实际重叠时，才输出 zIndex 注解保留 Figma 原始层叠（不重叠时 z 序不影响渲染，输出即噪声）。
• 对齐映射：MIN/CENTER/MAX → start/center/end（justifySelf / alignSelf）。

此外 v0.13.0 的 strokes 输出新增了 strokeAlign（描边对齐方式），让描边内外扩信息不丢失。

4.2 布局细节的持续修正

布局相关 bug fix 贯穿多个版本，代表了坐标与尺寸计算的精准化：

• v0.9.0：使用 SPACE_BETWEEN（两端对齐）时抑制计算出的 gap 值——Figma 不会为 SPACE_BETWEEN 提供固定 gap，输出计算值会误导实现；
• v0.12.0：SECTION 节点的子节点补全位置信息；尺寸计算尊重父轴方向（respect parent axis for dimensions）；修复 auto-layout frame 被错误折叠为单个 IMAGE-SVG 的问题；
• v0.4.0：重构布局定位逻辑并加入像素取整（pixel rounding，见 src/utils/common.ts 的 pixelRound）；
• v0.3.0：支持非 AutoLayout 元素与绝对定位元素的尺寸计算。

4.3 组件与属性

• v0.9.0：支持组件属性 BOOLEAN 与 TEXT（component properties）；
• v0.3.0：输出组件与组件集名称，帮助 LLM 在代码中查找既有组件；
• v0.4.0：改变简化响应中组件属性的格式。

---

五、认证与传输：从单令牌到每请求授权

5.1 认证方式的演进

• 最初：仅支持 Figma Personal Access Token，通过 X-Figma-Token 头发送；
• v0.3.0：新增 OAuth Bearer Token 支持（Authorization: Bearer）；
• v0.12.0：支持每请求 Figma API key（per-request）；
• v0.13.0：支持 HTTP 请求级的 OAuth Bearer token。

src/config.ts 的 resolveAuth 统一解析两种凭证：FIGMA_API_KEY 或 FIGMA_OAUTH_TOKEN（useOAuth 布尔标记）。关键的启动期校验在 requireGlobalCredentials（src/config.ts）：

stdio 模式与 fetch CLI 没有请求级凭证通道，必须在启动时解析出全局凭证，否则报错"Either FIGMA_API_KEY or FIGMA_OAUTH_TOKEN is required"；而 HTTP 模式允许无全局凭证启动，接受每请求的 X-Figma-Token 头。

5.2 传输模式的变迁

• v0.8.0（BREAKING）：切换为无状态 HTTP 传输（stateless HTTP transport），这是影响最大的破坏性变更之一；
• 同时 v0.8.0 加入进度通知（progress notifications）与异步 tree walker，解决大文件的拉取超时问题；
• v0.7.0（BREAKING）：getServerConfig() 不再接收 isStdioMode 参数，改为内部自检 stdio 模式并作为 ServerConfig.isStdioMode 返回；
• stdio 模式的启动另有"后门"：NODE_ENV=cli 环境变量（src/bin.ts）；
• v0.12.0：修复迟到的进度通知导致 stdio 客户端崩溃的问题。

MCP 工具注册方面，v0.6.5 升级 MCP SDK 至 1.27.1 并现代化工具注册方式；工具定义位于 src/mcp/tools/get-figma-data-tool.ts 与 src/mcp/tools/download-figma-images-tool.ts。

5.3 错误处理：让 LLM 能"自愈"

多个版本专注于错误信息可操作性（actionable errors），因为这直接决定 Agent 能否自我修复：

• v0.10.1：403 错误附带可操作信息与排查链接；缺失节点抛出可操作错误；
• v0.12.0：把 Figma 的 403 响应体原文透出，让 LLM 基于真实错误自愈；同时引导 LLM 修复错误的 node-id（proto/branch/figjam 链接格式）；
• 错误分类元数据 error_category 会进入遥测（v0.10.1），实现见 src/utils/error-meta.ts 与 src/services/errors/（forbidden.ts、rate-limit.ts 分别映射 403 与限流场景）。

5.4 代理与网络

• v0.9.0：为托管网络（managed networks）增加代理支持（--proxy / FIGMA_PROXY）；
• v0.11.0：修复默认把所有流量路由经 EnvHttpProxyAgent 的问题——标准环境变量（HTTPS_PROXY/HTTP_PROXY/NO_PROXY）由 undici 的 dispatcher 层处理，显式代理配置才走 --proxy（src/config.ts）；
• v0.4.0：加入 curl fallback，在企业网络环境下 API 请求更健壮；v0.4.3 完善了 fetchWithRetry 中 curl 的错误处理选项。

---

六、CLI 与配置系统：从 yargs 到 cleye，再到 fetch 子命令

6.1 参数解析框架

• v0.7.0：用 cleye 替换 yargs 作为 CLI 解析库（src/bin.ts 即 cleye 定义全部标志）；
• v0.9.0：新增 fetch 子命令——无需启动 MCP 服务器即可直接以 CLI 方式拉取设计数据到 stdout。这使项目具备双重使用形态：既可作为 MCP 服务器被 Cursor 等客户端调用，也可作为普通命令行工具嵌入脚本。

6.2 fetch 子命令详解

src/commands/fetch.ts 展示了完整的 CLI 数据流：

# 方式一：直接传 Figma 链接（自动解析 fileKey / nodeId）
figma-developer-mcp fetch "https://www.figma.com/file/xxx/...?node-id=1234:5678"

# 方式二：显式传 fileKey 与 nodeId（覆盖链接）
figma-developer-mcp fetch --file-key=xxx --node-id=1234:5678 --depth=3

# 方式三：指定输出格式
figma-developer-mcp fetch --file-key=xxx --format=json
figma-developer-mcp fetch --file-key=xxx --json

关键行为（源码证据 src/commands/fetch.ts）：

• 传入 URL 时用 parseFigmaUrl（src/utils/figma-url.ts）解析 fileKey 与 nodeId，--file-key / --node-id 优先；
• 两者皆缺则抛 UsageError: Either a Figma URL or --file-key is required；
• 必须存在全局凭证（requireGlobalCredentials），因为 CLI 无请求级凭证通道；
• 遥测只在输入校验通过后初始化，确保每条遥测记录都对应真实拉取（而非用法错误）；
• 拉取完成后打印 result.formatted 到 stdout，方便 > out.yaml 或 | jq 管道消费。

6.3 图片下载工具的安全边界

图片下载工具 download_figma_images 在 v0.12.0 中拒绝歧义的 localPath 输入（防止路径穿越），v0.7.1 则修复了 Windows 驱动器根路径的安全检查（drive root paths），配合 v0.7.0 的 --image-dir 把下载限制在指定目录内（src/config.ts 中 imageDir 默认当前工作目录）。--skip-image-downloads（v0.5.0 加入 CLI 参数与 SKIP_IMAGE_DOWNLOADS 环境变量）可在完全不需要图片下载时直接不注册该工具。

---

七、图像处理：从 sharp 到 jimp，从透传到后处理

图像链路经历了多次重要调整：

• v0.7.0：用 jimp（纯 JS）替换 sharp 原生依赖，规避原生模块安装问题；支持 gifRef 下载动画 GIF；跳过 SVG 的 jimp 处理并防止 image-fill 被错误折叠（v0.7.0 两个相关修复）；
• v0.8.1：改用选择性 @jimp/* 子包导入修复 ESM 崩溃（package.json 中可见 @jimp/js-png、@jimp/js-jpeg、@jimp/js-gif 等）；
• v0.5.0：支持 Fill / Fit / Crop / Tile 四种图片类型，并新增图像后处理步骤；支持 pattern fills（图案填充）；
• v0.13.0：SVG 上报真实尺寸而非 0x0（v0.13.0 修复）；
• v0.12.0：省略 null imageRef，使外部粘贴的图片可通过 nodeId 渲染；
• v0.4.0：SVG 导出选项——控制文本描边、id 包含与否、描边是否简化；
• v0.3.0：download_figma_images 支持 PNG 缩放（scale）；
• v0.6.4：折叠仅含矢量子节点的容器，以更好处理 SVG 下载并缩小输出；
• v0.8.1：SVG 容器折叠逻辑纳入 BOOLEAN_OPERATION 节点。

图像下载的主流程位于 src/services/download-figma-images.ts，v0.4.0 起 Promise 仅在文件写完后再 resolve，v0.3.x 起支持 scale 参数。

---

八、性能与遥测：O(n²) 修复与匿名统计

8.1 性能改进

• v0.8.0：修复简化与 YAML 序列化中的 O(n²) 瓶颈——这是大型设计文件场景下最关键的优化，直接影响 MCP 调用延迟；
• v0.8.0 同时引入异步 tree walker，配合进度通知解决大文件超时；
• 仓库内 scripts/benchmark-simplify.ts 与 src/tests/benchmark.test.ts 提供了简化的性能基准与回归测试手段。

8.2 匿名遥测

• v0.10.0：引入基于 PostHog 的匿名遥测；
• 可用 --no-telemetry、FRAMELINK_TELEMETRY 或 DO_NOT_TRACK 关闭（src/config.ts）；
• 遥测实现位于 src/telemetry/（capture.ts、client.ts），错误中的 API Key 会被脱敏（redactFromErrors，见 src/commands/fetch.ts），并记录 error_category（v0.10.1）。

---

九、安装与运行：两种使用形态

9.1 作为 MCP 服务器接入 IDE

在 Cursor 等客户端的 MCP 配置文件中加入（参见 README.md）：

{
  "mcpServers": {
    "Framelink MCP for Figma": {
      "command": "npx",
      "args": ["-y", "figma-developer-mcp", "--figma-api-key=YOUR-KEY", "--stdio"]
    }
  }
}

Windows 下改用 cmd /c。也可以把 FIGMA_API_KEY 与 PORT 放进 env 字段。需要 Figma Access Token（个人访问令牌）才能使用。

9.2 作为 CLI 直接拉取

npx -y figma-developer-mcp fetch "https://www.figma.com/file/..." --format=yaml

9.3 本地开发与测试

仓库提供完整的工程化脚本（package.json）：

pnpm install          # 安装依赖（pnpm@10.10.0，Node >= 20.20.0）
pnpm build            # tsup 构建，产出 dist/
pnpm type-check       # TypeScript 类型检查
pnpm test             # vitest 运行全部测试
pnpm dev:cli          # 开发模式以 stdio 启动
pnpm inspect          # MCP Inspector 调试工具

测试覆盖与 CHANGELOG 中的特性一一对应，可作为理解实现行为的活文档：rich-text.test.ts（富文本）、gradient.test.ts（渐变）、effects.test.ts（阴影/模糊）、tree-walker.test.ts（异步树遍历）、http-header-auth.test.ts（请求级认证）等。

---

十、总结：一条清晰的主线

回看 CHANGELOG 从 v0.2.2 到 v0.13.2 的演进，可以发现一条贯穿始终的产品主线：

1. 为 LLM 压缩上下文：空 key 移除 → 具名样式 → 去重（样式/子树）→ 拍平纯色栈 → 丢弃自动生成层名 → tree 格式默认化，token 效率层层递进；
2. 输出语义贴近 CSS：渐变从透传变为计算 → 富文本 Markdown 化 → em 化行高/字距 → CSS Grid → 模糊半径减半，让 Agent 拿到的几乎是"可直接粘贴的 CSS"；
3. 工程健壮性：yargs→cleye、sharp→jimp、O(n²)→线性、同步遍历→异步 walker、可操作的错误信息，让服务器在真实生产环境中可靠运行；
4. 使用形态多元化：stdio/HTTP 双传输、MCP 服务器/CLI fetch 双入口、API Key/OAuth/每请求令牌多认证路径。

如果你要基于该仓库做二次开发或深度集成，建议从三条路径入手：读 CHANGELOG.md 把握能力边界、读 src/config.ts 理解全部配置、读 src/transformers/ 了解 Figma 语义到 CSS 语义的映射细节。