JinDaGe - figma-pilot MCP Details

article

README

🚀 figma-pilot

AI 智能体通过代码执行控制 Figma

🚀 快速开始

前提条件

Node.js >= 18
Figma 桌面应用程序
兼容 MCP 的 AI 客户端（Claude Desktop、Claude Code、Cursor、Codex 等）

1. 安装 MCP 服务器

# Claude Code
claude mcp add figma-pilot -- npx @youware-labs/figma-pilot-mcp

# 其他 MCP 客户端 - 添加到你的 MCP 配置中：

{
  "mcpServers": {
    "figma-pilot": {
      "command": "npx",
      "args": ["@youware-labs/figma-pilot-mcp"]
    }
  }
}

配置文件位置：

Claude Desktop：~/.config/claude/claude_desktop_config.json（macOS/Linux）
Cursor：~/.cursor/mcp.json

2. 安装技能（推荐）

skills/ 文件夹包含帮助 AI 智能体正确使用 figma_execute 的 API 文档。将其安装到你的 AI 客户端的技能目录中：

| AI 客户端 | 技能目录 | |-----------|-----------------| | Claude Code / Codex | ~/.codex/skills/figma-pilot | | Cursor | ~/.cursor/skills-cursor/figma-pilot | | Claude Desktop | ~/.claude/skills/figma-pilot |

安装完成后，重启你的 AI 客户端以加载新技能。

3. 安装 Figma 插件

从 Releases 下载 figma-pilot-plugin-vX.X.X.zip
解压文件
在 Figma 中：插件 > 开发 > 从清单导入插件...
从解压后的文件夹中选择 manifest.json
运行：插件 > 开发 > figma-pilot

4. 验证连接

向你的 AI 智能体询问：

检查 Figma 连接状态

✨ 主要特性

本项目受到 Anthropic 的 Code execution with MCP 方法的启发。

与暴露数十个单独的 MCP 工具（这会使上下文窗口臃肿并减慢智能体速度）不同，figma-pilot 仅提供 3 个工具：

| 工具 | 描述 | |------|-------------| | figma_status | 检查连接状态 | | figma_execute | 使用完整的 Figma API 执行 JavaScript 代码 | | figma_get_api_docs | 获取 API 文档 |

AI 编写代码与 Figma 进行交互。这意味着：

工具定义中的 令牌减少 90% 以上
批量操作 - 一次调用中修改 100 个元素
数据过滤 - 在返回上下文之前过滤结果
复杂工作流 - 循环、条件语句、错误处理

💻 使用示例

基础用法

自然语言

创建一个带有标题和描述的卡片

AI 生成的代码

创建卡片：

await figma.create({
  type: 'card',
  name: 'User Card',
  children: [
    { type: 'text', content: 'Card Title', fontSize: 18, fontWeight: 600 },
    { type: 'text', content: 'Description here', fontSize: 14, fill: '#666' }
  ]
});

批量修改元素：

const { nodes } = await figma.query({ target: 'selection' });
const rects = nodes.filter(n => n.type === 'RECTANGLE');
for (const rect of rects) {
  await figma.modify({ target: rect.id, fill: '#0066FF', cornerRadius: 8 });
}
console.log(`Modified ${rects.length} rectangles`);

可访问性检查：

const result = await figma.accessibility({ 
  target: 'page', 
  level: 'AA', 
  autoFix: true 
});
console.log(`Fixed ${result.fixedCount} of ${result.totalIssues} issues`);

📚 详细文档

// 查询与修改
figma.query({ target })           // 查询元素
figma.create({ type, ... })       // 创建元素  
figma.modify({ target, ... })     // 修改元素
figma.delete({ target })          // 删除元素
figma.append({ target, parent })  // 移动到容器中

// 组件
figma.listComponents()            // 列出组件
figma.instantiate({ component })  // 创建实例
figma.toComponent({ target })     // 转换为组件
figma.createVariants({ ... })     // 创建变体

// 可访问性与令牌
figma.accessibility({ target })   // WCAG 检查
figma.createToken({ ... })        // 创建设计令牌
figma.bindToken({ ... })          // 将令牌绑定到元素

// 导出
figma.export({ target, format })  // 导出为图像

完整文档：skills/SKILL.md

🔧 技术细节

┌─────────────┐     stdio      ┌─────────────────┐     HTTP      ┌──────────────┐
│ MCP Client  │ <------------> │  MCP Server     │ <-----------> │ Figma Plugin │
│             │                │  (with bridge)  │   port 38451  │              │
└─────────────┘                └─────────────────┘               └──────────────┘

🛠️ 开发

项目结构

figma-pilot/
├── packages/
│   ├── cli/           # CLI 应用程序
│   ├── plugin/        # Figma 插件
│   ├── mcp-server/    # MCP 服务器（npm 包）
│   └── shared/        # 共享的 TypeScript 类型
├── scripts/
│   ├── install.sh     # 安装脚本
│   └── package-plugin.sh
└── skills/            # AI 智能体的 API 文档

从源代码构建

git clone https://github.com/youware-labs/figma-pilot.git
cd figma-pilot
bun install && bun run build

创建版本

# 构建并打包
bun run build
./scripts/package-plugin.sh 0.x.x

# 发布到 npm
cd packages/mcp-server && npm publish --access public

# 创建 GitHub 版本
gh release create v0.x.x dist/releases/figma-pilot-plugin-v0.x.x.zip \
  --title "v0.x.x" \
  --notes "Release notes here"

🐞 故障排除

插件无法连接

确保 MCP 服务器正在运行（检查你的 AI 客户端的 MCP 状态）
插件应在 Figma 中显示“已连接”
尝试重新打开插件
检查端口 38451 是否被阻塞

端口 38451 已被使用

lsof -i :38451
kill <PID>

找不到 MCP 服务器

对于离线使用，全局安装：

npm install -g @youware-labs/figma-pilot-mcp

插件错误：“ENOENT: no such file or directory, lstat '.../dist/main.js'”

此错误表示插件目录中缺少 dist 文件夹。这可能发生在以下情况：

下载的 zip 文件不完整
你直接使用源代码而未进行构建

解决方案： 如果你有源代码，请构建插件：

cd packages/plugin
bun install
bun run build

或者从项目根目录构建：

bun run build:plugin

构建完成后，验证 packages/plugin/dist/main.js 和 packages/plugin/dist/ui.html 是否存在，然后在 Figma 中重新导入插件。

📄 许可证

MIT - YouWare Labs

figma-pilot