Figma MCP Server Guide 项目结构全解

摘要

这不是一个传统意义上的应用源码仓库，而是一个围绕 Figma 官方 MCP 服务构建的“接入配置 + Agent 工作流 + 参考资料 + 脚本模板”仓库。它的核心价值不在于实现 Figma MCP Server 本身，而在于把 Figma 能力分发给不同客户端，并沉淀成可以被 AI Agent 反复复用的工作流。

一句话定位

figma/mcp-server-guide 更像是一个 Figma MCP 的“知识与集成分发仓库”，而不是“服务端实现仓库”。

文件关系图

这个仓库更像“知识与配置分发链”，不是传统源码调用链。核心关系如下：

flowchart TD
  A["README.md"] --> B["客户端接入说明"]
  B --> C[".mcp.json / server.json / gemini-extension.json / plugin.json"]
  C --> D["远程 Figma MCP 服务"]

  E["figma-power/POWER.md"] --> F["steering/*.md"]
  F --> G["按用户意图选择工作流"]

  H["skills/*.md"] --> I["具体技能入口"]
  I --> J["references/*.md"]
  I --> K["scripts/*.js"]

  L["figma-use/SKILL.md"] --> M["Plugin API 规则层"]
  M --> N["api-reference / gotchas / patterns / d.ts"]

  O["figma-generate-library/SKILL.md"] --> P["多阶段设计系统构建流程"]
  P --> Q["references/*.md"]
  P --> R["scripts/*.js"]

  S["figma-implement-design / code-connect / generate-design"] --> L
  S --> T["Figma 读写与设计到代码流程"]

仓库分层

层级	代表文件	作用
接入层	README.md、server.json、.mcp.json、各类 plugin.json	告诉不同客户端如何连接远程 Figma MCP 服务。
能力路由层	figma-power/POWER.md、figma-power/steering/*	把用户意图分流到不同工作流。
技能层	skills/*/SKILL.md	定义 agent 在具体场景下应该怎样调用 MCP 工具。
参考层	skills/**/references/*	解释 API 规则、设计系统语义、错误恢复和最佳实践。
脚本模板层	skills/figma-generate-library/scripts/*	提供可直接嵌入 use_figma 的 JS helper。

目录总览

.
├── README.md
├── server.json
├── .mcp.json
├── gemini-extension.json
├── .claude-plugin/
├── .cursor-plugin/
├── .github/plugin/
├── figma-power/
│   ├── POWER.md
│   ├── mcp.json
│   └── steering/
└── skills/
    ├── figma-code-connect-components/
    ├── figma-create-design-system-rules/
    ├── figma-create-new-file/
    ├── figma-generate-design/
    ├── figma-generate-library/
    │   ├── references/
    │   └── scripts/
    ├── figma-implement-design/
    └── figma-use/
        └── references/
            └── working-with-design-systems/

文件关系

1. README.md 是项目对外入口，解释每个客户端如何接入、每个工具怎么用。
2. server.json、.mcp.json、gemini-extension.json、plugin.json 负责把同一个远程端点分发给不同客户端。
3. figma-power/POWER.md 站在更高一层，把工作流按意图拆成 implement-design、code-connect、design-system-rules 三大方向。
4. skills/*/SKILL.md 是执行层，定义 agent 在不同任务里的标准步骤。
5. skills/figma-use/SKILL.md 是所有 use_figma 写操作的底层规范。
6. references/ 是知识库，scripts/ 是模板库，两者共同支撑 skill 执行。

---

根目录文件

文件	类型	作用
README.md	主文档	项目总入口，介绍能力、安装方式、工具说明和最佳实践。
server.json	MCP 清单	定义服务标题、版本、仓库来源和远程 Streamable HTTP endpoint。
.mcp.json	MCP 配置	通用客户端接入配置，把 figma server 指向 https://mcp.figma.com/mcp。
gemini-extension.json	Gemini 扩展清单	给 Gemini CLI 用的扩展描述，包含 MCP server 和 OAuth 配置。
Figma Icon (Full-color).svg	资源文件	插件和扩展的展示图标。
.claude-plugin/plugin.json	插件元数据	Claude Code 的插件描述文件。
.cursor-plugin/plugin.json	插件元数据	Cursor 插件描述文件，并声明 skills/ 和 .mcp.json 的位置。
.github/plugin/plugin.json	插件元数据	面向 GitHub 或 marketplace 的插件说明。

figma-power/

文件	类型	作用
figma-power/POWER.md	Power 总入口	把 Figma 能力抽象成高层能力包，并把需求路由到不同 steering 文档。
figma-power/mcp.json	MCP 配置	figma-power 这套能力包附带的 MCP server 配置。
figma-power/steering/implement-design.md	Steering 文档	规定从 Figma 节点到代码实现的高层步骤。
figma-power/steering/code-connect-components.md	Steering 文档	规定 Code Connect 映射的高层流程。
figma-power/steering/create-design-system-rules.md	Steering 文档	规定生成项目级规则文件的流程。

skills/ 顶层技能文件

文件	类型	作用
skills/figma-implement-design/SKILL.md	Skill	把 Figma 设计实现成生产代码。
skills/figma-code-connect-components/SKILL.md	Skill	建立 Figma 组件与代码组件的 Code Connect 映射。
skills/figma-create-design-system-rules/SKILL.md	Skill	生成项目级 Figma-to-code 规则。
skills/figma-create-new-file/SKILL.md	Skill	创建新的 Figma Design 或 FigJam 文件。
skills/figma-generate-design/SKILL.md	Skill	把页面或屏幕级内容写回 Figma。
skills/figma-generate-library/SKILL.md	Skill	从代码库反推并在 Figma 中构建设计系统。
skills/figma-use/SKILL.md	核心底层 Skill	规定 use_figma 的调用规则、限制和错误恢复。

skills/figma-generate-library/references/

文件	类型	作用
discovery-phase.md	参考文档	Phase 0，分析代码库、Figma 文件和设计库。
token-creation.md	参考文档	Phase 1，创建 token、collection、mode、alias、scope。
documentation-creation.md	参考文档	Phase 2，创建 Cover、Foundations 和文档页。
component-creation.md	参考文档	Phase 3，创建组件、variant、组件页和文档。
code-connect-setup.md	参考文档	设计系统构建场景下的 Code Connect 说明。
error-recovery.md	参考文档	长流程构建下的恢复、清理与幂等策略。
naming-conventions.md	参考文档	统一变量、页面、组件、variant 的命名规则。

skills/figma-generate-library/scripts/

文件	类型	作用
inspectFileStructure.js	Helper 脚本	只读扫描页面、变量集合、组件集和样式。
createVariableCollection.js	Helper 脚本	创建 variable collection 和 mode。
createSemanticTokens.js	Helper 脚本	批量创建 token，支持 alias、scope、code syntax。
bindVariablesToComponent.js	Helper 脚本	把变量绑定到组件的视觉属性。
createComponentWithVariants.js	Helper 脚本	自动生成 variant 组合并拼成 component set。
createDocumentationPage.js	Helper 脚本	创建统一样式的文档页骨架。
validateCreation.js	Helper 脚本	校验节点是否创建成功、名称和结构是否符合预期。
rehydrateState.js	Helper 脚本	恢复长流程构建的状态映射。
cleanupOrphans.js	Helper 脚本	清理失败构建留下的孤儿节点和变量。

skills/figma-use/references/

文件	类型	作用
plugin-api-standalone.d.ts	Typings	Figma Plugin API 的完整类型定义，是最底层事实来源。
plugin-api-standalone.index.md	索引文档	为大型 typings 文件提供索引，便于 grep 和定位 API。
api-reference.md	参考文档	列出 headless use_figma 环境里可用的 API。
plugin-api-patterns.md	参考文档	常见 Plugin API 操作的速查表。
common-patterns.md	参考文档	常见操作的可套用代码模板。
component-patterns.md	参考文档	组件、variant、component property 的 API 用法。
variable-patterns.md	参考文档	变量的创建、绑定、scope、alias 和 code syntax。
text-style-patterns.md	参考文档	text style 的创建、探测和应用。
effect-style-patterns.md	参考文档	effect style 的创建和应用。
gotchas.md	参考文档	收录常见坑和错误写法对照。
validation-and-recovery.md	参考文档	讲 get_metadata、get_screenshot 和错误恢复的组合使用。

skills/figma-use/references/working-with-design-systems/

文件	类型	作用
wwds.md	设计系统总论	解释 Figma 设计系统与代码设计系统的桥接关系。
wwds-components.md	概念文档	解释 Figma 组件模型及其与代码组件的差异。
wwds-components--creating.md	概念文档	讲如何设计组件的 variant 和 property 模型。
wwds-components--using.md	概念文档	讲如何查找、读取和正确使用组件实例。
wwds-variables.md	概念文档	解释 collection、mode、alias、scope 和 code syntax。
wwds-variables--creating.md	概念文档	讲创建变量之前要先理解什么。
wwds-variables--using.md	概念文档	讲使用现有变量时如何判断 collection 和 mode。
wwds-text-styles.md	概念文档	解释 text style 在设计系统中的位置与限制。
wwds-effect-styles.md	概念文档	解释 effect style 与阴影或 elevation token 的关系。

这个仓库最值得记住的 5 点

1. 它不是 Figma MCP Server 的服务端源码，而是“如何接入与使用这个服务”的官方工作流仓库。
2. 真正的核心资产是 skills/，而不是配置文件本身。
3. figma-use 是底层规则层，凡是涉及 use_figma 的写操作都应优先依赖它。
4. figma-generate-library 是最工程化的一套能力，覆盖从发现、建 token、建文档、建组件到 QA 的完整流程。
5. 整个仓库的设计目标是减少 agent 在 Figma 场景下的随机性，把设计到代码、代码到画布、设计系统构建都变成稳定流程。

推荐阅读顺序

1. 先读 README.md，理解项目定位和可用工具。
2. 再读 figma-power/POWER.md，建立能力分类视图。
3. 再读 skills/figma-use/SKILL.md，理解底层规则。
4. 根据任务方向继续读：
   • 做设计到代码：skills/figma-implement-design/SKILL.md
   • 做 Code Connect：skills/figma-code-connect-components/SKILL.md
   • 做设计系统构建：skills/figma-generate-library/SKILL.md

后续可继续补充的方向

• 增加“各 skill 对应 MCP 工具清单”
• 增加“哪些内容重复、哪些文件可能漂移”的维护视角分析
• 增加“新手上手路线”和“维护者更新路径”