Figma Pilot

🚀 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 客戶端以加載新技能。

3. 安裝 Figma 插件

1. 從 Releases 下載 figma-pilot-plugin-vX.X.X.zip
2. 解壓文件
3. 在 Figma 中：插件 > 開發 > 從清單導入插件...
4. 從解壓後的文件夾中選擇 manifest.json
5. 運行：插件 > 開發 > figma-pilot

4. 驗證連接

向你的 AI 智能體詢問：

檢查 Figma 連接狀態

✨ 主要特性

本項目受到 Anthropic 的 Code execution with MCP 方法的啟發。

與暴露數十個單獨的 MCP 工具（這會使上下文窗口臃腫並減慢智能體速度）不同，figma-pilot 僅提供 3 個工具：

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"

🐞 故障排除

插件無法連接

1. 確保 MCP 服務器正在運行（檢查你的 AI 客戶端的 MCP 狀態）
2. 插件應在 Figma 中顯示“已連接”
3. 嘗試重新打開插件
4. 檢查端口 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 文件夾。這可能發生在以下情況：

1. 下載的 zip 文件不完整
2. 你直接使用源代碼而未進行構建

解決方案： 如果你有源代碼，請構建插件：

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