11 KiB

Raw Blame History

AI Data Extractor — Figma Plugin

A Figma plugin that extracts design structure, layout properties, text content, and visual assets from your selected layers — and streams them directly to your AI coding agent via the Model Context Protocol (MCP), or packages them into a structured ZIP archive.

What It Does

Select any frame or group of layers in Figma, click Extract, and the plugin will:

Traverse the full node tree of your selection, capturing the parent-child hierarchy
Extract metadata for every node — dimensions, position, fills, strokes, effects, opacity, border radius, and layout properties (auto-layout mode, padding, spacing, alignment)
Capture text content inline, including font family, size, line height, letter spacing, and alignment
Export visual assets — PNG for every non-text node, plus SVG for nodes that don't contain text children
Stream to your AI IDE via the built-in MCP bridge server (if connected), so your coding agent can access the design data directly through tool calls
Package everything into a downloadable .zip archive with a structured data.md file (available as a manual download)
Copy the Developer System Prompt to your clipboard automatically. This prompt instructs code-generation AI agents on how to strictly implement the extracted design with zero guesswork.

Output Structure

The generated data follows a predictable, hierarchical structure (whether accessed via MCP tools or the ZIP archive):

figma-ai-extraction.zip
├── data.md                          # Full hierarchical tree + properties
└── <TopLevelNode>/                  # One folder per selected root node
    ├── <NodeName>.png
    ├── <NodeName>.svg
    └── children/
        └── <ChildNode>/
            ├── <ChildNode>.png
            ├── <ChildNode>.svg
            └── children/
                └── ...              # Recursively nested

`data.md`

The markdown file contains:

AI Interpretation Guide — instructions for how an AI model should parse the data
Hierarchical Tree — indented list of every node with:
- Node name, type, and folder path
- Inline text content (for text nodes)
- Raw properties JSON (dimensions, position, fills, strokes, effects, layout config, typography)

Asset Export Rules

Node Type	PNG	SVG	Reasoning
Text node	✗	✗	Text content is captured inline in `data.md`
Node with text children	✓	✗	PNG preserves visual context; SVG skipped to avoid exposing raw text paths
Node without text	✓	✓	Both formats exported for maximum flexibility

Developer System Prompt

The plugin includes a built-in Zero-Guesswork System Prompt that enforces strict design fidelity when AI agents implement the extracted data. This prompt is:

Automatically served via the get_agent_prompt MCP tool when using the MCP flow
Copied to your clipboard during ZIP extraction for the standard flow

The prompt enforces:

Strict Structural Fidelity: Instructs the agent to prioritize the exact coordinates, properties, and tree structures over generic CSS styling defaults or auto-generated mockups.
Asset Pipeline Rules: Directs the agent to organize visual assets into the target project's /assets/images/ directory and map them correctly in the code.
Visual Verification: Tells the agent to cross-verify SVG assets against matching PNG references to ensure no bounding boxes or layout boxes are missing.
Zero Guesswork: Prohibits the agent from correcting typos, changing text cases, or merging styles from child nodes up to parent containers.

Installation

Only two commands are needed to set up both the Figma plugin and the MCP bridge server:

Clone or download this repository.
Install dependencies (this installs both plugin and bridge server dependencies automatically):
```
npm install
```

Build the project (compiles everything and launches the interactive MCP setup wizard):

npm run build

During the build, you will be prompted to select your AI IDE:

==================================================
            Figma MCP Bridge Auto Setup
==================================================

Select the AI IDE you want to configure:
  1) Gemini / Antigravity IDE
  2) Cursor
  3) Windsurf
  4) Cline (VS Code Extension)
  5) All of the above
  6) Skip (Configure manually later)

The setup script will automatically write the MCP server configuration to your selected IDE's config file.

Load the plugin in Figma:
- Open Figma (browser or desktop app).
- Navigate to Plugins > Development > Import plugin from manifest...
- Select the manifest.json file from the root of this project.
Restart your AI IDE to load the new MCP server configuration.

Note: After the initial setup, you do not need to run any commands again (even after restarting your computer). The IDE automatically starts the MCP bridge server in the background whenever it launches.

How to Use

MCP Flow (Recommended)

Select a frame or layer group in Figma.
Open the plugin and click Extract Selection.
The green MCP dot in the plugin's top-right corner confirms the bridge is connected and the data has been streamed.
In your AI IDE, instruct the agent:

"Use the figma-bridge MCP to retrieve the design data and implement it."
The agent will automatically:
- Call get_agent_prompt to load the zero-guesswork rules.
- Call get_design_data to retrieve the full layout tree.
- Call list_assets and get_asset to fetch individual PNG/SVG assets.

Standard Flow (ZIP Download)

Select a frame or layer group in Figma.
Click Extract Selection.
Once completed, click Download ZIP File.
Extract the ZIP and supply the folder to your AI agent along with the copied clipboard prompt.

MCP Tools

The bridge server exposes the following tools to your AI IDE:

Tool	Description
`get_agent_prompt`	Returns the zero-guesswork implementation guidelines. Must be called first — other data tools are blocked until this is read.
`get_connection_status`	Check if the Figma plugin is connected to the bridge.
`list_extractions`	List all available design extractions with metadata.
`get_design_data`	Get the full hierarchical design tree (markdown format).
`list_assets`	List all exported PNG/SVG assets with paths and MIME types.
`get_asset`	Retrieve a specific asset by path (base64 PNG or raw SVG).
`trigger_extraction`	Remotely trigger a new extraction from the connected Figma plugin.

Limits

500 node maximum per extraction — the plugin counts all nodes (including deeply nested children) and will show an error if the selection exceeds this limit. This prevents performance issues with very large component trees.

Technical Details

Detail	Value
Figma API	`1.0.0`
Editor	Figma (design files)
UI Size	320 × 180 px
ZIP Library	JSZip 3.10.1 (loaded via CDN)
Network Access	`cdnjs.cloudflare.com`, `localhost:3055` (MCP bridge, dev only)
MCP Transport	stdio (IDE spawns the server process automatically)
Bridge Protocol	WebSocket on port `3055` (plugin ↔ bridge server)

Architecture

┌─────────────────┐     WebSocket (3055)     ┌──────────────────┐     stdio      ┌─────────────┐
│  Figma Plugin   │ ◄──────────────────────► │  Bridge Server   │ ◄────────────► │   AI IDE    │
│  (ui.html)      │                          │  (Node.js)       │                │  (MCP Client│
└─────────────────┘                          └──────────────────┘                └─────────────┘

code.ts — Plugin backend running in Figma's sandbox. Handles node traversal, property extraction, and asset export via the Figma Plugin API.
ui.html — Plugin frontend. Manages UI state, generates the ZIP archive, and streams extraction data to the bridge server over WebSocket.
bridge-server/ — Local Node.js MCP server. Receives design data from the plugin via WebSocket, stores it in memory, and exposes it to AI IDEs through MCP tool calls (stdio transport).
scripts/setup-mcp.js — Interactive CLI setup script that auto-configures the MCP bridge in your AI IDE's settings file.
manifest.json — Figma plugin configuration and permissions.

Node Position Handling

Positions are calculated relative to the top-level selected node (not the canvas). The root node is always positioned at (0, 0), and all children use offsets from the root's absoluteBoundingBox. This makes the output self-contained and canvas-position-independent.

States

The plugin UI cycles through these states:

State	Icon	Description
Idle	📦	Waiting for user to click "Extract Selection"
Processing	🔄	Traversing nodes and exporting assets
Exporting	🔄 + progress bar	Generating the ZIP archive
Complete	✅	Extraction sent to MCP bridge (or download finished)
Error	⚠️	Something went wrong (with message)

Development

Build

Compile both the Figma plugin and the bridge server:

npm run build

Re-run MCP Setup

If you need to reconfigure the MCP bridge for a different IDE:

npm run setup-mcp

Project Files

├── manifest.json            # Figma plugin manifest
├── code.ts                  # Plugin backend (TypeScript)
├── code.js                  # Compiled plugin output (loaded by Figma)
├── ui.html                  # Plugin UI + WebSocket bridge client
├── package.json             # Root package with unified build scripts
├── tsconfig.json            # TypeScript config (plugin)
├── scripts/
│   └── setup-mcp.js         # Interactive MCP auto-configuration wizard
├── bridge-server/
│   ├── package.json          # Bridge server dependencies
│   ├── tsconfig.json         # TypeScript config (server)
│   └── src/
│       ├── server.ts         # MCP server + WebSocket handler
│       └── storage.ts        # In-memory extraction store
└── README.md                # This file

11 KiB Raw Blame History