Skip to main content
Glama
TrungLee003

Figma Agent MCP

by TrungLee003
README.md
# โšก Figma Agent MCP

> **Local-first AI Design Agent for Figma** via **Model Context Protocol (MCP)** โ†’ **WebSocket Bridge** โ†’ **Native Figma Plugin**.
>
> Inspect, create, mutate, style, validate, and optimize Figma designs natively with deterministic typed tools, design-system awareness, token compression, and turnkey composite workflows.

[![CI](https://github.com/TrungLee003/figma-agent-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/TrungLee003/figma-agent-mcp/actions/workflows/ci.yml)
[![TypeScript Strict](https://img.shields.io/badge/TypeScript-Strict_Mode-blue.svg)](https://www.typescriptlang.org)
[![Tests](https://img.shields.io/badge/Tests-171%2F171_Passing-success.svg)](https://github.com/TrungLee003/figma-agent-mcp)
[![MCP Tools](https://img.shields.io/badge/MCP_Tools-50_Deterministic_Tools-orange.svg)](https://github.com/TrungLee003/figma-agent-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

---

## ๐Ÿ›๏ธ System Architecture

```text
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚        AI Client (Claude / Cursor / Antigravity / LLM)      โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                               โ”‚ MCP Protocol (stdio / Hardened SSE)
                               โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚        MCP Server (@figma-agent/mcp-server โ€” 50 Tools)      โ”‚
โ”‚  - Tool Registry & Validation  - Session Router             โ”‚
โ”‚  - Context Compiler (Compact)  - Composite Skills Runtime   โ”‚
โ”‚  - Design System Resolver      - Semantic Token Matching    โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                               โ”‚
                               โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚       Command Engine (@figma-agent/command-engine)          โ”‚
โ”‚  - Batch Command Pipeline      - Scoped Idempotency Cache   โ”‚
โ”‚  - Symbolic Ref Resolution     - Compensating Node Cleanup  โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                               โ”‚ Local WebSocket (ws://127.0.0.1:3055)
                               โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚       Bridge Server (@figma-agent/bridge-server)            โ”‚
โ”‚  - Channel Pairing (128-bit)   - Request/Response Matcher   โ”‚
โ”‚  - Heartbeat & Auto-reconnect  - 50+ Concurrent Sockets     โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                               โ”‚
                               โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚        Figma Plugin (@figma-agent/figma-plugin)             โ”‚
โ”‚  - Typed Command Dispatcher    - Pure Font Engine           โ”‚
โ”‚  - Native Node Mutation        - Zero External Dependencies โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”ฌโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
                               โ”‚ Figma Plugin API
                               โ–ผ
โ”Œโ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”
โ”‚                         Figma Canvas                        โ”‚
โ””โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”€โ”˜
```

---

## ๐ŸŒŸ Key Highlights

- ๐Ÿ”’ **Local-First & Secure**: Binds to `127.0.0.1` by default. 128-bit secret channel pairing. No arbitrary JavaScript execution inside Figma. Hardened SSE transport with Bearer token authentication and origin allowlists.
- ๐Ÿงฉ **50 Deterministic MCP Tools**: Comprehensive coverage across Read, Create, Mutate, Auto Layout, Visual Styles, Components, Variables/Tokens, Typography, Export, and Design System Resolution.
- ๐ŸŽฏ **Semantic Design-System Resolver**: Bridges human intent (`"primary button"`, `"#6366F1"`) to matching Components and Tokens with perceptual color distance ($\Delta E$) and automated node auditing.
- โšก **Context Compiler & Pruning**: Compresses massive node trees into semantic Markdown or Compact DSL with adaptive depth pruning and token budget enforcement under 100ms. Typically achieves substantial context reduction; benchmark fixtures show >70% reduction in tested scenarios.
- ๐Ÿ›ก๏ธ **Built-in Validation & WCAG 2.1 Engine**: Relative luminance and contrast ratio calculation (AA/AAA) for normal text, large text, and UI components; Auto Layout linter; 4px/8px token grid auditor.
- ๐Ÿ”„ **Sequential Batch Execution & Cleanup**: High-throughput execution of command pipelines with dynamic symbolic ref resolution, SHA-256 idempotency deduplication with conflict detection, and compensating creation rollback on failure.
- ๐Ÿš€ **Turnkey Agent Skills**: Pre-packaged composite workflows for instant Design System generation, WCAG accessibility auto-repair, and wireframe-to-hifi card conversion.

---

## ๐Ÿ“ฆ Monorepo Layout

```text
figma-agent-mcp/
โ”œโ”€โ”€ apps/
โ”‚   โ”œโ”€โ”€ mcp-server/        # 50 MCP Tools + Bridge Client + Session Service + Hardened SSE
โ”‚   โ”œโ”€โ”€ bridge-server/     # High-throughput WebSocket router (ws) with 128-bit key pairing
โ”‚   โ””โ”€โ”€ figma-plugin/      # Pure TypeScript native Figma Plugin (IIFE bundle)
โ”œโ”€โ”€ packages/
โ”‚   โ”œโ”€โ”€ protocol/          # CommandEnvelope, CommandResult, Error codes, Zod schemas
โ”‚   โ”œโ”€โ”€ figma-schema/      # Canonical FigmaCommandMap, Layout, Style, Text schemas
โ”‚   โ”œโ”€โ”€ command-engine/    # Batch execution pipeline, transactions, scoped idempotency
โ”‚   โ”œโ”€โ”€ context-compiler/  # Token optimizer, tree pruner, Markdown & DSL serializers
โ”‚   โ”œโ”€โ”€ design-system/     # 4px/8px Spacing, Typography & Corner Radius scale matchers
โ”‚   โ”œโ”€โ”€ validator/         # WCAG 2.1 contrast engine, Auto Layout & design token rules
โ”‚   โ”œโ”€โ”€ skill-runtime/     # Strictly-typed composite skills runtime & execution engine
โ”‚   โ”œโ”€โ”€ telemetry/         # Percentile metrics collector (p50, p95, p99)
โ”‚   โ””โ”€โ”€ shared/            # Hex/RGBA converters, Pino logger, host validation helpers
โ””โ”€โ”€ tests/
    โ””โ”€โ”€ integration/       # 33 Vitest suites (171 tests) covering all phases & benchmarks
```

---

## ๐Ÿš€ Quickstart & Setup

### 1. Build the Monorepo

```bash
git clone https://github.com/TrungLee003/figma-agent-mcp.git
cd figma-agent-mcp
pnpm install
pnpm build
```

### 2. Start the Bridge Server

```bash
pnpm --filter @figma-agent/bridge-server start
# Bridge server listening at ws://127.0.0.1:3055
```

### 3. Load the Figma Plugin

1. In Figma Desktop: go to **Plugins** โ†’ **Development** โ†’ **Import plugin from manifest...**
2. Select `apps/figma-plugin/manifest.json`.
3. Open the plugin: it will automatically generate a cryptographically secure 128-bit Channel ID & Secret pair.
4. Click **๐Ÿ“‹ Copy Config** in the plugin window. The ready-to-use MCP client configuration snippet is copied directly to your clipboard.

### 4. Start the MCP Server (Stdio or Hardened SSE)

```bash
# Mode A: Stdio Transport (standard for Claude Desktop, Cursor, Antigravity)
pnpm --filter @figma-agent/mcp-server start

# Mode B: Hardened SSE Transport (HTTP Server-Sent Events with Bearer Auth & Loopback checks)
pnpm --filter @figma-agent/mcp-server start -- --sse --port=3056 --token=YOUR_BEARER_TOKEN
```

---

## โš™๏ธ AI Client Configuration

### ๐Ÿค– 1. Claude Desktop

Add to your `claude_desktop_config.json` (`%APPDATA%\Claude\claude_desktop_config.json` on Windows or `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "figma": {
      "command": "node",
      "args": ["d:/Code/Figma MCP/apps/mcp-server/dist/cli.js"],
      "env": {
        "FIGMA_AGENT_BRIDGE_HOST": "127.0.0.1",
        "FIGMA_AGENT_BRIDGE_PORT": "3055",
        "FIGMA_AGENT_CHANNEL_ID": "default-channel"
      }
    }
  }
}
```

---

### ๐Ÿ’ป 2. Cursor IDE

Add to your Cursor MCP Configuration (`Settings` โ†’ `Features` โ†’ `MCP` or `.cursor/mcp.json`):

```json
{
  "mcpServers": {
    "figma-agent": {
      "command": "node",
      "args": ["d:/Code/Figma MCP/apps/mcp-server/dist/cli.js"],
      "env": {
        "FIGMA_AGENT_BRIDGE_HOST": "127.0.0.1",
        "FIGMA_AGENT_BRIDGE_PORT": "3055",
        "FIGMA_AGENT_CHANNEL_ID": "default-channel"
      }
    }
  }
}
```

---

### ๐Ÿง  3. Google Antigravity / Gemini CLI

Add to your Antigravity MCP settings (`~/.gemini/antigravity/mcp_config.json`):

```json
{
  "mcpServers": {
    "figma-agent": {
      "command": "node",
      "args": ["d:/Code/Figma MCP/apps/mcp-server/dist/cli.js"],
      "env": {
        "FIGMA_AGENT_BRIDGE_HOST": "127.0.0.1",
        "FIGMA_AGENT_BRIDGE_PORT": "3055"
      }
    }
  }
}
```

---

### โšก 4. OpenAI Codex / Codex CLI / OpenAI Operator

Add to your Codex MCP configuration (`~/.codex/config.json` or `codex-settings.json`):

```json
{
  "mcpServers": {
    "figma-agent": {
      "command": "node",
      "args": ["d:/Code/Figma MCP/apps/mcp-server/dist/cli.js"],
      "env": {
        "FIGMA_AGENT_BRIDGE_HOST": "127.0.0.1",
        "FIGMA_AGENT_BRIDGE_PORT": "3055",
        "FIGMA_AGENT_CHANNEL_ID": "default-channel"
      }
    }
  }
}
```

Or register via **Codex CLI**:

```bash
# Add Figma Agent MCP to Codex CLI
codex mcp add figma-agent -- node "d:/Code/Figma MCP/apps/mcp-server/dist/cli.js"

# Inspect available tools via MCP Inspector
npx @modelcontextprotocol/inspector node "d:/Code/Figma MCP/apps/mcp-server/dist/cli.js"
```

---

### ๐ŸŒŠ 5. Windsurf / Codeium IDE

Add to `~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "figma-agent": {
      "command": "node",
      "args": ["d:/Code/Figma MCP/apps/mcp-server/dist/cli.js"],
      "env": {
        "FIGMA_AGENT_BRIDGE_HOST": "127.0.0.1",
        "FIGMA_AGENT_BRIDGE_PORT": "3055",
        "FIGMA_AGENT_CHANNEL_ID": "default-channel"
      }
    }
  }
}
```

---

## ๐Ÿ“š Complete MCP Tools Reference (50 Tools)

All 50 MCP tools are strictly typed via Zod schemas, execute deterministically, and provide robust failure metadata.

### 1. Connection & Session Management (2 tools)

| Tool Name              | Parameters             | Description                                                                        |
| ---------------------- | ---------------------- | ---------------------------------------------------------------------------------- |
| `figma.get_connection` | _none_                 | Get current WebSocket bridge connection status, latency, and session capabilities. |
| `figma.join_channel`   | `channelId`*, `secret` | Switch or join a specific Figma document channel session.                          |

### 2. Inspection & Read (6 tools)

| Tool Name                    | Parameters                      | Description                                                             |
| ---------------------------- | ------------------------------- | ----------------------------------------------------------------------- |
| `figma.get_document`         | `depth` (0โ€“10)                  | Retrieve the document root hierarchy with bounded depth.                |
| `figma.get_selection`        | `depth` (0โ€“10)                  | Get currently selected nodes in the active Figma canvas.                |
| `figma.get_node`             | `nodeId`*, `depth`              | Read detailed properties and subtree of a specific node.                |
| `figma.get_nodes`            | `nodeIds`*, `depth`             | Batch fetch multiple nodes by ID.                                       |
| `figma.get_local_components` | `query`, `pageOnly`             | Retrieve local Master Components and Component Sets with variant props. |
| `figma.get_local_styles`     | `type` (PAINT/TEXT/EFFECT/GRID) | List local paint, text, and effect styles with serialized paints.       |

### 3. Node Creation (4 tools)

| Tool Name                | Parameters                                                                     | Description                                         |
| ------------------------ | ------------------------------------------------------------------------------ | --------------------------------------------------- |
| `figma.create_frame`     | `width`_, `height`_, `x`, `y`, `name`, `parentId`, `layoutMode`                | Create a container Frame with optional Auto Layout. |
| `figma.create_text`      | `text`*, `x`, `y`, `width`, `font` ({family, style, size}), `name`, `parentId` | Create a Text node with reliable font loading.      |
| `figma.create_rectangle` | `width`_, `height`_, `x`, `y`, `cornerRadius`, `name`, `parentId`              | Create a Rectangle vector node.                     |
| `figma.create_section`   | `width`_, `height`_, `x`, `y`, `name`, `parentId`                              | Create a Section organization container.            |

### 4. Node Mutation & Geometry (6 tools)

| Tool Name           | Parameters                                 | Description                                             |
| ------------------- | ------------------------------------------ | ------------------------------------------------------- |
| `figma.move_node`   | `nodeId`_, `x`_, `y`*                      | Move a node to absolute coordinate positions.           |
| `figma.resize_node` | `nodeId`_, `width`_, `height`*             | Resize node dimensions.                                 |
| `figma.rename_node` | `nodeId`_, `name`_                         | Rename node layer title.                                |
| `figma.delete_node` | `nodeId`_, `destructive`_ (must be `true`) | Permanently delete a node from canvas (safety guarded). |
| `figma.clone_node`  | `nodeId`*, `parentId`, `x`, `y`, `name`    | Duplicate an existing node hierarchy.                   |
| `figma.set_parent`  | `nodeId`_, `targetParentId`_, `index`      | Reparent and reorder a node in the layer tree.          |

### 5. Auto Layout & Responsive Sizing (2 tools)

| Tool Name                 | Parameters                                                                                                                  | Description                                    |
| ------------------------- | --------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| `figma.set_auto_layout`   | `nodeId`_, `mode`_, `itemSpacing`, `padding` ({top, right, bottom, left}), `primaryAxisAlignItems`, `counterAxisAlignItems` | Configure responsive Flexbox-like Auto Layout. |
| `figma.set_layout_sizing` | `nodeId`*, `horizontal` (FIXED/HUG/FILL), `vertical` (FIXED/HUG/FILL)                                                       | Set container and child axis sizing behavior.  |

### 6. Visual Styles & Effects (5 tools)

| Tool Name                 | Parameters                                                            | Description                                             |
| ------------------------- | --------------------------------------------------------------------- | ------------------------------------------------------- |
| `figma.set_fills`         | `nodeId`_, `fills`_ (Array of Solid/Gradient/Image fills)             | Apply background colors, gradients, and images.         |
| `figma.set_strokes`       | `nodeId`_, `strokes`_, `strokeWeight`, `strokeAlign`                  | Apply border strokes, weights, and alignments.          |
| `figma.set_corner_radius` | `nodeId`_, `radius`_ (number or per-corner object), `cornerSmoothing` | Set border corner radius with iOS continuous smoothing. |
| `figma.set_opacity`       | `nodeId`_, `opacity`_ (0.0 โ€“ 1.0)                                     | Adjust layer opacity.                                   |
| `figma.set_effects`       | `nodeId`_, `effects`_ (DROP_SHADOW, INNER_SHADOW, LAYER_BLUR)         | Apply drop shadows, inner shadows, and blurs.           |

### 7. Components & Instances (5 tools)

| Tool Name                        | Parameters                                                             | Description                                                             |
| -------------------------------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------- |
| `figma.create_component`         | `name`*, `width`, `height`, `parentId`, `componentPropertyDefinitions` | Convert a node into a reusable Master Component.                        |
| `figma.create_instance`          | `componentId`*, `x`, `y`, `properties`, `parentId`                     | Instantiate a component variant.                                        |
| `figma.set_component_properties` | `nodeId`_, `properties`_                                               | Override component variant properties.                                  |
| `figma.detach_instance`          | `nodeId`_, `destructive`_ (must be `true`)                             | Detach component instance to regular editable frames (safety guarded).  |
| `figma.get_local_components`     | `query`, `pageOnly`                                                    | Retrieve local Master Components and Component Sets with variant props. |

### 8. Variables & Design Tokens (6 tools)

| Tool Name                   | Parameters                                                                                              | Description                                      |
| --------------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `figma.get_local_variables` | `collectionId`                                                                                          | List local variables and token collections.      |
| `figma.create_variable`     | `name`_, `resolvedType`_ (COLOR/FLOAT/STRING/BOOLEAN), `collectionId`, `collectionName`, `initialValue` | Create a semantic Design Token variable.         |
| `figma.set_variable_value`  | `variableId`_, `modeId`_, `value`*                                                                      | Update variable value for a specific mode.       |
| `figma.bind_variable`       | `nodeId`_, `property`_ (fills/strokes/opacity/itemSpacing/cornerRadius), `variableId`*                  | Bind a node property to a Design Token variable. |
| `figma.create_paint_style`  | `name`_, `paints`_, `description`                                                                       | Create a shared Paint Style in the file.         |
| _(Reused Inspect)_          | `get_local_styles`                                                                                      | Query shared styles.                             |

### 9. Assets, Images & Export (3 tools)

| Tool Name                   | Parameters                                        | Description                                           |
| --------------------------- | ------------------------------------------------- | ----------------------------------------------------- |
| `figma.export_node`         | `nodeId`*, `format` (PNG/JPG/SVG/PDF), `scale`    | Export node as Base64 image data or UTF-8 SVG string. |
| `figma.set_export_settings` | `nodeId`_, `exportSettings`_                      | Configure export presets on a node.                   |
| `figma.set_image_fill`      | `nodeId`_, `imageBase64`_, `scaleMode`, `opacity` | Upload and apply an image fill from Base64.           |

### 10. Text & Typography (6 tools)

| Tool Name                  | Parameters                                                        | Description                                           |
| -------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------- |
| `figma.set_text_content`   | `nodeId`_, `text`_                                                | Update text string content.                           |
| `figma.set_font_size`      | `nodeId`_, `fontSize`_, `start`, `end`                            | Update font size (whole text or range).               |
| `figma.set_font_family`    | `nodeId`_, `family`_, `style`, `start`, `end`                     | Change font family and weight with auto font-loading. |
| `figma.set_text_alignment` | `nodeId`*, `horizontal` (LEFT/CENTER/RIGHT/JUSTIFIED), `vertical` | Set text alignment.                                   |
| `figma.set_line_height`    | `nodeId`*, `unit` (PIXELS/PERCENT/AUTO), `value`                  | Set line height spacing.                              |
| `figma.set_letter_spacing` | `nodeId`_, `unit` (PIXELS/PERCENT), `value`_                      | Set letter spacing (tracking).                        |

### 11. Context Optimization & Pruning (1 tool)

| Tool Name               | Parameters                                                              | Description                                                                                    |
| ----------------------- | ----------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- |
| `figma.compile_context` | `nodeId`, `format` (markdown/dsl/compact/json), `maxTokens`, `maxDepth` | Compile and compress Figma trees with token budget enforcement and compact DSL representation. |

### 12. Validation & Accessibility (2 tools)

| Tool Name              | Parameters                                         | Description                                                                                      |
| ---------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `figma.validate_node`  | `nodeId`, `rules`, `includeChildren`               | Audit node tree for WCAG 2.1 contrast, Auto Layout rules, token scales, and layer naming health. |
| `figma.check_contrast` | `foreground`_, `background`_, `fontSize`, `isBold` | Calculate WCAG 2.1 relative luminance and contrast ratio (AA/AAA).                               |

### 13. Composite Skills & Batch Execution (3 tools)

| Tool Name             | Parameters                                                                                              | Description                                                                                                                                                                                                                                               |
| --------------------- | ------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `figma.list_skills`   | _none_                                                                                                  | Discover available high-level Agent Skills.                                                                                                                                                                                                               |
| `figma.run_skill`     | `skillName`*, `payload`                                                                                 | Execute a multi-step composite workflow.                                                                                                                                                                                                                  |
| `figma.batch_execute` | `commands`*, `rollbackOnFailure` (default: true), `stopOnFirstError`, `transactionId`, `idempotencyKey` | Execute multiple Figma commands sequentially with dynamic symbolic reference resolution (`ref`, `parentRef`, `nodeRef`, `$ref:name`), in-memory idempotency deduplication (`idempotencyKey`), and compensating cleanup of newly created nodes on failure. |

### 14. Design System Semantic Resolution (1 tool)

| Tool Name                     | Parameters                                                                           | Description                                                                                                                                                           |
| ----------------------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `figma.resolve_design_system` | `type`* (component/color/spacing/radius/audit_node), `query`, `intentHint`, `nodeId` | Semantically resolve human intent (e.g. "primary button", "#6366F1", 16px) to matching components/tokens with perceptual $\Delta E$ distance and node token auditing. |

#### ๐Ÿ’ก Example: Building a Hierarchical UI Card in 1 Batch Call

```json
{
  "transactionId": "tx-pricing-01",
  "idempotencyKey": "idem-card-01",
  "rollbackOnFailure": true,
  "commands": [
    {
      "command": "figma.create_frame",
      "ref": "card",
      "payload": { "width": 360, "height": 480, "name": "Pricing Card" }
    },
    {
      "command": "figma.create_text",
      "ref": "title",
      "parentRef": "card",
      "payload": { "text": "Pro Plan", "font": { "family": "Inter", "style": "Bold", "size": 24 } }
    },
    {
      "command": "figma.create_rectangle",
      "ref": "btn",
      "parentRef": "card",
      "payload": { "width": 312, "height": 44, "cornerRadius": 8, "name": "CTA Button" }
    },
    {
      "command": "figma.set_fills",
      "nodeRef": "btn",
      "payload": { "fills": [{ "type": "SOLID", "color": "#3B82F6" }] }
    }
  ]
}
```

_Returns `refMap: { "card": "123:456", "title": "123:457", "btn": "123:458" }`._

---

## ๐Ÿค– Composite Agent Skills (9 Skills)

### ๐Ÿงฑ Core General Skills (6)

1. **`skill.inspect_design`**: Read comprehensive node hierarchy, bounds, styles, typography, layout properties, and design token binding recommendations.
2. **`skill.create_screen`**: Construct a complete responsive screen container with header bar, content area, Auto Layout, and Fill/Hug sizing rules.
3. **`skill.edit_selection`**: Batch mutate visual fills, strokes, opacity, corner radius, and text characters on currently selected canvas nodes.
4. **`skill.create_component`**: Create a reusable Master Component with Auto Layout, styling, and typed component property definitions.
5. **`skill.apply_design_system`**: Audit a node subtree and automatically apply recommended Variable token bindings (`figma.bind_variable`).
6. **`skill.validate_design`**: Run complete WCAG 2.1 contrast, Auto Layout, and token scale rules against a layout subtree.

### โšก Specialized Workflows (3)

7. **`skill.create_design_system`**: Turnkey generation of Color Variable tokens (`color/primary`, `color/background`, `color/surface`, `color/text-primary`), Paint Styles, and a responsive `Button/Primary` master component.
8. **`skill.auto_fix_accessibility`**: Audits layout hierarchy for WCAG 2.1 contrast violations and automatically repairs low-contrast text colors to achieve AA compliance.
9. **`skill.convert_wireframe_to_hifi`**: Transforms a low-fidelity wireframe container into a polished High-Fidelity UI Card with modern surface fills, soft drop shadows, and continuous corner smoothing.

---

## ๐Ÿงช Testing & Verification

Run the comprehensive test suite (171 passing tests across 33 test files):

```bash
# Run format checking
pnpm format:check

# Run full build
pnpm build

# Run unit and integration tests
pnpm test

# Strict TypeScript typechecking
pnpm typecheck

# ESLint audit
pnpm lint
```

### Benchmark Results:

- โšก **WebSocket Concurrency**: 50 concurrent client connections with burst heartbeats: **p95 < 100ms**, 0 dropouts.
- ๐ŸŒณ **Massive Tree Scaling**: Context compilation of **6,111 nodes** with 1,000 token budget: **< 100ms execution time, >70% context reduction in benchmark scenarios**.
- ๐Ÿ›ก๏ธ **Fault Tolerance**: Automatic reconnection and error handling with `retryable` flags on socket dropouts.

---

## ๐Ÿ“„ License

MIT ยฉ 2026 Figma Agent MCP Contributors