figma-bridge

一个基于 MCP (Model Context Protocol) 的工具，用于从 Figma 获取设计节点数据并转换为 AI 可理解的结构化 DSL，辅助生成 Vue 3 / React / HTML 组件代码。

功能特性

• Figma API 集成: 通过 Figma REST API 获取设计文件节点数据
• 智能数据清洗: 过滤坐标、阴影等无关信息，保留组件树和布局结构
• 布局感知过滤: 自动识别并过滤页面级菜单、头部等布局元素
• 组件白名单: 保护组件内部的菜单、头部等元素不被误过滤
• 矢量地狱优化: 检测并简化图标/插画中的大量矢量节点，减少数据量 90%+
• 智能指纹采样: 针对 Table、List 等重复组件，保留不同结构样本，压缩数据量
• 多框架支持: 支持生成 Vue 3、React、HTML 代码

快速开始

1. 安装依赖

npm install

2. 配置环境变量

创建 .env 文件：

FIGMA_TOKEN=your_figma_api_token
FILE_KEY=your_figma_file_key

获取方式：

• FIGMA_TOKEN: Figma Personal Access Tokens
• FILE_KEY: Figma 文件 URL 中的 key，如 https://www.figma.com/file/ABC123/... 中的 ABC123

3. 编译

npm run build

4. 配置 MCP

在 Claude Code 或其他 MCP 客户端中添加配置：

{
  "mcpServers": {
    "figma-bridge": {
      "command": "node",
      "args": ["/path/to/figma-bridge/dist/index.js"]
    }
  }
}

使用方式

工具: get-figma-node

获取 Figma 节点的结构化数据。

参数：

参数	类型	默认值	说明
nodeId	string	必填	Figma 节点 ID
framework	enum	'vue'	目标框架: vue, react, html
filterNames	string[]	[]	额外过滤的节点名称
useDefaultFilter	boolean	true	是否启用默认过滤
siderWidth	number	220	左侧菜单栏宽度阈值(px)
headerHeight	number	64	顶部头部高度阈值(px)
maxDepth	number	10	最大递归深度
enableFingerprintSampling	boolean	false	启用智能指纹采样（默认禁用，仅在显式开启时生效）
fingerprintConfig	object	{}	指纹采样配置
enableVectorHellOptimization	boolean	true	启用矢量地狱优化

示例调用：

// 获取节点数据（默认输出紧凑 codegen DSL）
const result = await getFigmaNode({
  nodeId: "1-16253",  // 支持 1-16253 或 1:16253 格式
  framework: "vue",
  siderWidth: 220,
  headerHeight: 64,
  enableFingerprintSampling: false  // 默认禁用，且不会被 codegen 隐式开启
});

返回数据结构（默认 codegen）:

{
  "_meta": {
    "framework": "vue",
    "target": "Vue 3 with Composition API, <script setup lang=\"ts\">",
    "conventions": "Follow Vue best practices: small focused components, props down events up, composables for reusable logic",
    "dslVersion": "2.0",
    "mode": "codegen",
    "hints": {
      "semanticComponents": true,
      "compactOutput": true,
      "childrenStrategy": "pruned"
    }
  },
  "id": "1:100",
  "name": "Button",
  "type": "FRAME",
  "component": "Button",
  "layout": "flex-row",
  "layoutInfo": {
    "gap": 8,
    "padding": {
      "top": 12,
      "right": 16,
      "bottom": 12,
      "left": 16
    },
    "justify": "SPACE_BETWEEN",
    "align": "CENTER"
  },
  "props": {
    "disabled": false
  },
  "children": [
    {
      "id": "1:101",
      "name": "Text",
      "type": "TEXT",
      "component": "Text",
      "layout": "grid",
      "children": []
    }
  ]
}

说明：

• 默认 codegen 仅保留最小 _meta，不会回显 options / fingerprintConfig 等详细配置。
• 默认 codegen 会输出精简版 layoutInfo，仅保留 gap / padding / justify / align；如需完整布局语义请显式传 includeLayoutDetails: true。
• 默认 codegen 使用 childrenStrategy: 'pruned'，但不会隐式开启 fingerprint sampling。

核心功能详解

1. 布局过滤

自动识别并过滤页面级布局元素：

元素类型	识别条件	行为
Menu/Sidebar	x≈0, width≈siderWidth	过滤（非白名单时）
Header/Navbar	y≈0, height≈headerHeight	过滤（非白名单时）

组件内部的菜单/头部会被保留（通过白名单机制）。

2. 组件白名单

以下父组件内的子元素会被保护：

• dropdown, select 中的 menu
• card, modal, drawer 中的 header
• list, table 中的 item, row
• 更多见 src/config.ts

3. 矢量地狱优化

检测包含多个 VECTOR 的 GROUP/FRAME，自动简化：

• 移除 vectorPaths, vectorNetwork 等大数据字段
• 扁平化深层嵌套结构
• 添加 _isIcon 标记供 AI 识别

优化效果： 数据量减少 90%+

4. 智能指纹采样

注意： 该功能默认禁用，且默认 codegen 不会隐式开启。只有显式传入 enableFingerprintSampling: true 时，才会对 Table、List 等重复结构进行采样。

针对 Table、List 等重复组件：

• 通过结构指纹识别相同行
• 保留所有不同结构的样本
• 跳过完全重复的行
• 特殊状态（展开、选中）始终保留

启用后的采样标记（debug 输出示意）：

{
  "_isRepresentative": true,
  "_duplicateCount": 17,
  "_note": "此结构共有 18 个相同节点",
  "samplingInfo": {
    "method": "fingerprint",
    "totalChildren": 20,
    "preservedChildren": 3,
    "skippedChildren": 17
  }
}

项目结构

figma-bridge/
├── src/
│   ├── index.ts              # MCP Server 入口
│   ├── transform.ts          # 转换主入口
│   ├── types.ts              # 类型定义
│   ├── config.ts             # 默认配置
│   ├── filter.ts             # 布局过滤逻辑
│   ├── whitelist.ts          # 组件白名单系统
│   ├── vector-optimization.ts # 矢量地狱优化
│   ├── fingerprint-sampling.ts # 智能指纹采样
│   ├── node-processor.ts     # 节点处理器
│   └── meta-builder.ts       # 元信息构建器
├── dist/                     # 编译输出
├── .env                      # 环境变量
├── package.json
├── tsconfig.json
└── record.md                 # 详细修改记录

模块依赖

transform.ts
    ├── types.ts
    ├── config.ts
    ├── filter.ts ──────→ whitelist.ts
    ├── vector-optimization.ts
    ├── fingerprint-sampling.ts
    ├── node-processor.ts ───→ filter.ts, vector-optimization.ts, fingerprint-sampling.ts
    └── meta-builder.ts

开发

编译

npm run build

调试

# 使用 ts-node 直接运行
npx ts-node src/index.ts

技术栈

• MCP SDK: @modelcontextprotocol/sdk
• 语言: TypeScript 5.9+
• 模块: ES Module (NodeNext)
• 运行时: Node.js 18+

配置参考

指纹采样配置

{
  similarityThreshold: 0.95,  // 相似度阈值 (0-1)
  maxUniqueStructures: 3,      // 最大保留唯一结构数
  namePatterns: ['row', 'item', 'option'], // 启用采样的名称匹配
  preservePatterns: ['expand', 'selected', 'header-row'] // 始终保留的节点
}

矢量地狱优化配置

{
  minVectorChildren: 3,    // 判定为图标的最小 VECTOR 数量
  maxIconSize: 200,        // 最大图标尺寸(px)
  maxNestingDepth: 3       // 最大嵌套深度
}

注意事项

1. 节点 ID 格式: 支持 1-16253 或 1:16253 两种格式，会自动转换
2. 环境变量: 使用 .env 文件配置，确保文件在正确位置
3. 深度限制: maxDepth 防止深层嵌套导致数据爆炸，默认 10 层
4. 数据量: 对于大型设计，矢量优化默认启用；指纹采样默认禁用，如需压缩 Table/List 重复结构可手动启用

License

ISC

相关文档

• record.md - 详细修改记录和开发历史
• MCP 协议文档
• Figma API 文档