Figma Pilot

🚀 figma-pilot

AIエージェントがコード実行を通じてFigmaを制御します。

English | 中文

🚀 クイックスタート

前提条件

• 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で: Plugins > Development > Import plugin from manifest... を選択します。
4. 解凍したフォルダから manifest.json を選択します。
5. Plugins > Development > figma-pilot を実行します。

4. 接続の確認

AIエージェントに次の問い合わせを行ってください。

Check the Figma connection status

✨ 主な機能

このプロジェクトは、Anthropicの Code execution with MCP アプローチに触発されています。

数十個の個別のMCPツールを公開する代わりに（これはコンテキストウィンドウを肥大化させ、エージェントを遅くします）、figma-pilotはたった3つのツールを提供します。

AIはコードを書いてFigmaとやり取りします。これは以下の意味を持ちます。

• ツール定義における90%以上のトークン削減
• バッチ操作 - 1回の呼び出しで100個の要素を変更する
• データフィルタリング - 結果をコンテキストに返す前にフィルタリングする
• 複雑なワークフロー - ループ、条件分岐、エラーハンドリング

💻 使用例

自然言語

Create a card with a title and description

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`);

📚 ドキュメント

APIリファレンス

// クエリと変更
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で "Connected" と表示されることを確認してください
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