• AI 应用
• MCP 服务

导读

ROADMAP.md 是 Figma-Context-MCP（即figma-developer-mcp，一个为 Cursor 等 AI 编码助手提供 Figma 设计数据的 Model Context Protocol 服务器）的官方发展蓝图，按开发阶段与工作量维度组织规划了组件/原型支持、布局与样式增强、企业级功能、开发者体验、技术债清理以及研究探索等多项演进方向。本文将以该路线图为骨架，逐项解读每一条规划背后的动机、落地形态，并结合仓库现有源码（src/extractors、src/transformers、src/mcp/tools 等）说明当前实现基础与规划之间的承接关系，帮助你理解这个项目的能力边界、下一阶段发力点，以及如何参与共建。

一、项目定位与路线图概览

Figma-Context-MCP 的核心价值在于：让 AI 编码助手直接访问 Figma 设计数据，从而显著提升"设计转代码"一次成型的准确度。与粘贴截图等替代方案相比，直接消费结构化设计数据让模型拿到的是布局、颜色、文本、组件等精确信息而非像素。

路线图将演进目标分为六个方向，每个方向按"影响程度 × 工作量"排序：

路线图最后标注"Last updated: June 2025"，并说明会随社区反馈与优先级变化而调整。

二、核心功能增强：高影响的地基性改进

2.1 组件与原型支持（最高优先级）

这是路线图标记为High Priority的第一块，包含三个子方向：

独立组件提取工具。规划新增get_figma_components工具，用于获取完整的组件/组件集（Component Set）设计数据，包括 variants（变体）与属性。这一规划与当前实现是衔接的：仓库目前已有get_figma_data工具（见 src/mcp/tools/get-figma-data-tool.ts），且 src/transformers/component.ts 已实现了组件数据的简化逻辑——simplifyComponents与simplifyComponentSets将原始 Figma 组件结构精简为包含id、key、name、componentSetId与propertyDefinitions的扁平定义，simplifyPropertyDefinitions当前只提取BOOLEAN与TEXT两类属性（注释中明确写着"Phase 1"），说明变体属性支持是刻意分阶段推进的。

INSTANCE（实例）支持改进。规划两项：一是"只返回被覆盖（overridden）的值"，即实例中未改动的属性不再重复输出，压缩上下文；二是"默认隐藏 INSTANCE 的子节点，除非是插槽（slot）类型子节点或通过新工具调用参数显式请求完整数据"。这直接关系到 MCP 输出体积——INSTANCE 在真实文件中往往嵌套极深（工具参数甚至支持I5666:180910;1:10515;1:10336这种分号连接的重叠链节点 ID），全量输出会严重浪费 LLM 上下文窗口。

原型（Prototype）支持。规划提取交互数据（hover、click 等动作）、动画/过渡数据，并探索状态管理提示。目前仓库源码中尚未见原型交互相关的 transformer，这是纯新增能力；但底层SimplifiedNode类型（见 src/extractors/types.ts）的开放式设计（textStyle、layout、fills等字段既可携带内联值也可携带 globalVars 引用）为未来扩展原型字段留出了空间。

2.2 解析逻辑：变量内联

规划"仅出现一次的变量直接内联，只有被复用的变量才保留为全局变量"。这条在路线图写为待办，但仓库中其实已有对应实现——src/extractors/finalize.ts 的finalizeDesign正是"count-gated style hoisting"（计数门控样式提升）：遍历完成后统计每个样式引用的次数，单次使用的样式内联回节点本身，2 次及以上使用的（或 Figma 命名样式）才保留在globalVars.styles中。对应测试见 src/tests/finalize.test.ts。从源码结构看，路线图此条可能针对的是变量（Variables）体系而非样式引用，但其思路与 finalize 通道同源，可作为参考实现。

2.3 图片与资源处理

修复被遮罩/裁剪的图片导出。规划正确导出裁剪图片（对应 issue #162）、支持复杂遮罩形状与变换、把图片填充/矢量提升到顶层以便 AI 可见。当前实现的裁剪基础在 src/utils/image-processing.ts：applyCropTransform依据 Figma 变换矩阵[[scaleX, skewX, translateX], [skewY, scaleY, translateY]]计算可见区域并调用 Jimp 完成裁剪；download_figma_images工具参数中已有needsCropping、cropTransform、filenameSuffix等字段（见 src/mcp/tools/download-figma-images-tool.ts）。"复杂遮罩形状"则是明显超出线性变换范围的探索项。

改进 SVG 处理。规划"更好的图标识别：如果 frame 的所有子组件都是 VECTOR，就把整个 frame 作为 SVG 下载"。仓库当前已有一个近似的自动化实现——src/extractors/built-in.ts 的collapseSvgContainersafterChildren 回调：当容器（FRAME/GROUP/INSTANCE/BOOLEAN_OPERATION）的所有子节点都属于 SVG 可导出类型集合时，将容器折叠为IMAGE-SVG节点；对 auto-layout 容器还设置了 10 个子节点的装饰性图案阈值（SVG_COLLAPSE_AUTOLAYOUT_THRESHOLD），避免把有意的图表结构误折叠。路线图在此基础上升级为"主动识别 + 主动导出"。

另外规划探索在响应中支持原始路径（path）数据，并标注"不确定是否有价值"，属于开放式调研。

2.4 布局改进：智能换行检测

规划检测固定宽度子节点并将其转换为百分比宽度、更好的 flexbox 换行支持、对换行项的网格布局检测、以及对 Figma 新网格布局的支持。当前布局层已有完整的 flex/grid 翻译实现：src/transformers/layout/flex.ts 负责justify-content、align-items、gap 的映射（注意SPACE_BETWEEN时抑制 API 返回的过期间距值）；src/transformers/layout/grid.ts 实现了网格子节点排序（computeGridChildOrder将 Figma z-order 重排为网格锚点顺序以生成地道 CSS）、紧密网格检测（isPackedGrid）与zIndex重叠标注。"固定宽度转百分比"是现有实现未覆盖的新逻辑，也正是智能换行布局的攻坚点。

2.5 高级样式

增强渐变支持。规划确保渐变以正确 CSS 语法导出（issue #152）。当前 src/transformers/style/gradient.ts 已实现四类渐变的 CSS 映射：线性渐变通过findExtendedLineIntersections计算延长渐变线与元素边界的交点以正确重映射 stop 位置，径向/角度/菱形渐变分别映射为radial-gradient/conic-gradient/radial-gradient（菱形以椭圆近似）。含 2 个 handle 以下的退化情形会安全回退。

网格系统支持。规划支持 Figma 新版 grid autolayout（区别于长期存在的 flex autolayout）与遗留的"布局参考线"网格。从 src/transformers/layout/common.ts 看，layoutModeToSchema已对GRID模式做了映射，SimplifiedLayout也已包含gridTemplateColumns、gridTemplateRows、gridColumn、gridRow、justifySelf等字段，说明 grid autolayout 的主路径已打通；"布局参考线网格"属于遗留对象支持。

命名样式提取。规划导出与布局、颜色、文本关联的样式名称，方便 LLM 识别（可使用/v1/styles/:key端点）。当前实现的折中方案在 src/extractors/built-in.ts：getStyleMatch从节点的styles映射中查找 Figma 命名样式并直接以样式名（如Heading / Large）作为 globalVars 键，同名不同值时追加 id 消歧，且 finalize 阶段对命名样式"即使单次使用也保持提升"（视为设计系统意图）。路线图规划的是进一步通过 styles 端点获取独立样式元数据。

2.6 文本与排版

规划支持文本字段中的格式化文本（issue #159）与混合文本样式/多色文本（issue #140）。这两项在当前仓库已实质落地：src/transformers/text.ts 的buildFormattedText把 Figma 的characterStyleOverrides+styleOverrideTable转换为 markdown（加粗**、斜体*、删除线~~、URL 链接text）加内联样式引用（{ts1}…{/ts1}）的富文本表示，支持按代码点拆分避免破坏 emoji 代理对、逐行lineTypes/lineIndentations有序/无序列表、以及boldWeight规范权重检测。内联样式 delta 经 src/extractors/built-in.ts 的registerInlineTextStyle注册为顺序编号的tsN全局变量。这为路线图"文本格式化"条目提供了已可复用的核心算法。

三、企业级功能：变量系统与设计令牌

企业方向的核心是Variable System Enhancements：

• 将deduceVariablesFromTokens移植给非企业版用户：路线图引用了一个第三方 fork 的 variable-deduction.ts 作为灵感来源。这一项的目标是让没有 Enterprise 套餐的用户也能从设计令牌推导变量。
• 为企业套餐添加getFigmaVariables：直接通过 Figma API 读取变量数据。
• 以标准格式导出设计令牌：探索性目标。

需要说明的事实边界：当前仓库中尚未出现getFigmaVariables或变量推导相关服务文件，src/services 目录下现有的是 figma.ts（Figma REST 封装）、get-figma-data.ts、download-figma-images.ts 与错误处理模块。因此该项属于明确的待建设能力。

四、开发者体验：错误处理与测试体系

4.1 错误处理

路线图中"API 失败重试逻辑"已标记完成 ✅，其余规划为"LLM 可向用户展开的详细错误消息"。重试与错误分类的现状可以追溯到 src/utils/fetch-json.ts：连接错误码集合与可重试状态码集合（408/425/429/500/502/503/504）在请求层统一打标（is_retryable）；错误消息的"可供 LLM 展开"特性在 src/services/errors 已有体现——buildRateLimitMessage（rate-limit.ts）会解析 Figma 429 响应头（retry-after、x-figma-plan-tier、x-figma-rate-limit-type）给出针对性指引，buildForbiddenMessage（forbidden.ts）则原样透出响应体并列出常见 403 成因（缺失 scope、令牌失效、文件未共享、代理拦截等），并明确指示 LLM"用通俗语言向用户解释具体原因"。

4.2 文档与测试

规划三档测试覆盖：所有 transformer 的单元测试、mock Figma API 的集成测试、以及端到端测试——后者设想用自定义测试框架后台拉起 Claude Code 等编码 Agent，视觉验证 MCP 输出的落地效果。当前仓库测试在 src/tests 下已有 18 个测试文件，覆盖富文本、渐变、效果、布局对齐、序列化、路径校验、telemetry 脱敏、树遍历与 finalize 去重等，可作为单元测试层的地基；mock API 集成测试与 Agent 级 E2E 测试尚属路线图规划。

五、快速赢点与技术债

快速赢点（低成本高回报）：

• 更好的文本溢出处理：自动宽度、自动高度、固定宽度 + 截断文本设置。相关基础在 src/transformers/layout/common.ts 的sizing字段（fixed/fill/hug/contextual）中已有承载。
• 核对简化响应中混合模式（blend modes）是否正确转发。

技术债：

• 清理图片下载代码（注释标注在mcp.ts中，即 src/mcp 相关文件）。
• 重构convertAlign函数（layout.ts）。从源码看当前布局对齐逻辑已拆分为 flex.ts 的convertJustifyContent/convertAlignItems与 common.ts 的convertSelfAlign，说明重构已部分推进。
• 跨服务标准化错误处理。

六、研究与探索方向

这一部分全部标记为"调研可行性/价值"：

• Figma 插件伴侣（companion）：路线图以 🚀🚀🚀 标注高期待，设想通过插件增强数据获取能力。
• 设计系统集成：令牌提取与映射、组件依赖图。
• Figma 文件元数据：利用标记为 "Ready for Dev" 的 frame、通过 Figma API 拉取批注（annotations）、以及使用乃至修改 "Dev Resources" 链接的可行性与价值评估。

这些方向不改变现有架构，但会显著扩大 MCP 的设计数据覆盖面——从"读设计稿"扩展到"读设计系统资产 + 开发就绪信息"。

七、参与贡献

路线图明确欢迎社区贡献：建议优先挑选标记为good first issue或help wanted的 issue；重大功能请先开 issue 讨论实现方案。仓库配套的贡献说明可参考 CONTRIBUTING.md，开发流程配置见 lefthook.yml 与 package.json（构建使用tsup，测试使用vitest run，另有 benchmark-simplify.ts 可对简化管线做耗时/内存/输出体积基准分析）。

结语

从这份路线图可以清晰看到 Figma-Context-MCP 的演进脉络：先做深组件/原型与布局样式的地基能力，再做企业级变量系统与设计系统集成，同时持续压缩输出上下文、打磨错误信息并补齐测试体系。其中文本富文本格式化、命名样式提取、渐变 CSS 映射、SVG 容器折叠、网格子节点排序等条目在仓库源码中已有成型的实现基础，而独立组件工具、原型交互数据、变量读取、Agent 级 E2E 测试则是下一阶段的主要增量。对于希望在 Cursor 等 AI 编码工具中深度使用 Figma 数据的开发者而言，理解这条路线图，就等于预判了这个 MCP 服务器未来的能力边界与使用方式。

• AI 应用
• MCP 服务