跪拜 Guibai
← Back to the summary

Figma Agent Kit Bridges Local Design Files to Any AI Editor Without a Paid MCP Plan

A long-form technical article for frontend developers, designers, design engineers, and AI coding practitioners. Project: Figma Agent Kit · Stable version v1.0.0 · MIT Documentation site: https://chinacarlos.github.io/figma-agent-kit/ Repository: https://github.com/ChinaCarlos/figma-agent-kit

First, a clarification on positioning (to avoid misunderstandings): The technical route of "Desktop plugin + local MCP bridge" is not our original invention. There are already multiple local Figma ↔ Agent bridging practices in the community; this article introduces an implementation—Figma Agent Kit—that we referenced, learned from these open-source solutions, and then adapted, reorganized, and open-sourced according to our own engineering goals.

Figma Agent Kit — Local Bridging of Figma and AI Agent

Figma Desktop ↔ Local MCP ↔ Cursor / Claude Code / Codex … Real-time read/write of the current canvas

Preface: What This Article Aims to Clarify

Over the past year, "AI can write code" is no longer news; what truly bottlenecks delivery efficiency is often the gap between design and code:

The community has already provided a clear path: use a Figma Desktop plugin to access the canvas, and use a local process to expose capabilities as MCP, allowing Agents like Cursor to call them directly. We did not invent this path from scratch; rather, after researching existing open-source projects, we created a maintainable, versionable, and well-documented adaptation based on our own needs—Figma Agent Kit (Figma Desktop plugin + npm package figma-agent-mcp), connecting Cursor / Claude Code / Codex / Qoder / CodeBuddy / Trae, etc., to the currently open design file.

This article will unfold in the following order (bookmark for selective reading):

  1. Background and industry status (including the cost threshold of commercial Figma MCP)
  2. Conceptualization: How we selected and adapted after referencing community solutions
  3. Benefits for developers / designers
  4. The implementation plan and end-to-end architecture of this repository
  5. Key technical implementation points (election, MsgPack, RPC, dual AI paths, etc.)
  6. Complete usage workflow (with screenshots)
  7. Plugin + MCP + Cursor Skill: A universal 1:1 UI restoration workflow
  8. Who it's for / Who it's not for
  9. Open-source address, documentation, acknowledgments, and participation methods
  10. Final words

The goal is not "another README translation" or to "praise one and disparage another," but to: clearly explain the adaptation motivations, architectural trade-offs, onboarding path, and how to link the toolchain to a real restoration process, making it easy for you to reproduce, compare, and raise Issues.

1. Background: The "Last Mile" Between Design and Code

1.1 AI Coding Has Accelerated, but the Delivery Chain Remains Broken

AI Coding has significantly sped up "writing functions, modifying components, and supplementing tests." But in real business scenarios, a lot of time is wasted on:

The core contradiction is simple:

The model is powerful, but it lacks a standard tool interface that can "touch the current canvas."

1.2 Common Practices and Their Costs

Pain Point Common Practice Cost
Agent cannot read the current file Paste screenshots / verbal descriptions Loss of precision, difficult to iterate, difficult to regress
Agent cannot modify layers Read-only export / manual editing The loop is broken on the design side
Need structured node information Figma REST / Export JSON Token, permissions, not the "current selection"
Want official MCP experience Figma Official / Commercial MCP Costs money, seat and usage limits
Using Agent in multiple windows simultaneously Each starts its own process, fighting for local ports Unstable bridge, difficult to troubleshoot

The experience we want can be summed up in one sentence:

Open Figma Desktop → Open Cursor → Tell the Agent "look at the currently selected Frame and change the title to xxx" → The canvas changes immediately.

This is not about making another design tool, but about: connecting the AI editor you are already using to the design file you are currently editing.

1.3 Key Point: Figma MCP "Costs Money," Blocking Many Out

In recent years, MCP (Model Context Protocol) has standardized "connecting tools to Agents." In the Figma ecosystem, official or commercially-oriented MCP capabilities quickly emerged—great in experience, but often presenting real barriers for individual developers, small teams, students, and side projects:

flowchart TB
  subgraph pain [Real Barriers]
    A[Charged per seat / plan]
    B[Cloud file and permission binding]
    C[Usage or feature tiering]
    D[Slow company procurement process]
  end

  subgraph result [Result]
    E[Individuals and small teams cannot afford or are unwilling to pay]
    F[Those wanting to try bringing design files into Agent are deterred]
    G[Learning and open-source communities lack a reproducible foundation]
  end

  A --> E
  B --> E
  C --> F
  D --> G

This is not a denial of official products—enterprise-level security, compliance, and cloud collaboration should indeed be handled by someone. The problem is: "I want to try it locally, on the currently open file, using Cursor" should not be blocked by a paywall from the start.

In this context, continuing to adopt the community-verified "local bridge" direction is more pragmatic for us: not to replace official commercial products, but to provide a self-hostable, auditable-by-default supplementary path.

For this repository, we set our engineering goals as:

Dimension This Repository's Trade-offs
Cost MIT, directly installable via npm / GitHub
Data Bridge traffic defaults to localhost; MCP tool paths do not upload entire documents via REST for read/write
Capability A read/write toolset targeting the currently open file (see documentation tool table for specifics)
Ecosystem Standard stdio MCP, minimizing binding to a single IDE
Engineering Plugin and MCP versioned and released together, bilingual documentation site, reproducible CI

One sentence (as rigorous as possible):

Commercial Figma MCP can be excellent, but may also come with cost and procurement thresholds; the community local bridge route solves a different type of need—first, being able to reproduce locally, auditable by default, and easy to modify secondarily. What we have built is one open-source implementation of this, not the only answer.

2. Conceptualization: Referencing Existing Open Source, Then Deciding How to Adapt

2.0 Standing on the Shoulders of the Community (Important)

"Using a plugin to access the canvas + a local process to expose to the Agent" has repeatedly appeared in the open-source community. During the research phase, we could clearly see several commonalities:

Figma Agent Kit does not claim to have invented the above architecture. What we did was: after reading and comparing existing open-source practices, rewrite/adapt a version according to our own maintenance goals, and supplement the parts needed for "long-term use," such as versioning, documentation, and multi-client instructions. If you are already using other excellent local Figma MCP / bridge projects, feel free to continue using them; this article only introduces the trade-offs of this repository. You are welcome to read comparatively and point out any imprecise expressions in our documentation.

flowchart LR
  Community[Community_Existing_Local_Bridge_Practices] -->|Learn & Compare| Goals[Our Engineering Goals]
  Goals --> Rebuild[Adapt_Reorganize_Document]
  Rebuild --> Kit[Figma_Agent_Kit_This_Repository]

2.1 How to Choose Among Three Technical Routes (For This Repository)

flowchart LR
  subgraph opt1 [Option A]
    R1[Figma REST / Cloud API]
  end
  subgraph opt2 [Option B]
    R2[Browser Plugin Hijacking Web]
  end
  subgraph opt3 [Option C]
    R3[Desktop Plugin API + Local Bridge + MCP]
  end

  opt1 -.->|Snapshot feel / Token / Not current selection| X1[Large deviation from goal]
  opt2 -.->|Fragile / Tab sleep breaks WS| X2[High maintenance cost]
  opt3 --> Y[Closer to_Current Canvas_Local_Standard MCP]

  1. Pure REST / Official API Heavily dependent on cloud files and Tokens; the model leans towards "document snapshots," often unfriendly to the "currently open page, current selection."

  2. Browser Plugin Hijacking Fragile, easily broken by Figma Web updates; tab sleeping can also break WebSocket connections.

  3. Figma Desktop Plugin API + Local Bridge + MCP (Adopted by this repository, also a common community direction)

    • Closer to real-time canvas capabilities;
    • Bridge defaults to staying local;
    • Agent side uses standard MCP, mainly changing host configuration when switching editors.

2.2 How This Repository Splits Packages: Plugin + MCP, Versioned Together

Building upon the common community "two-end separation," we fixed the delivery form as:

Component Distribution Responsibility
figma-agent-plugin GitHub Releases ZIP Bridge client, panel UI, optional AI rename/group, 3× slice export
figma-agent-mcp npm stdio MCP + HTTP/WS bridge (including Leader / Follower handling for multi-process scenarios)

The plugin side is responsible for calling the Figma Plugin API; the MCP side is responsible for being called by the Agent; they are connected via local WebSocket (in this implementation, business frames use MessagePack). This is the module division of this repository; similar splits are common in similar open-source projects, though the detailed implementations differ.

Plugin in Figma Desktop with MCP Bridge Connected

Plugin panel: Green "MCP Bridge Connected" = Agent side can already access the current file

3. What Benefits Does It Bring? Developers × Designers

This chapter specifically answers: "Why should I install it?"

3.1 Benefits for Developers

mindmap
  root((Developer Benefits))
    Restoration Efficiency
      Read real node tree
      Less guessing spacing/border radius
      Selection-level context
    Agent Loop Closure
      Read/write layers
      Modify copy structure
      Export slices to repository
    Cost and Control
      Lower subscription threshold with open-source stack
      Default localhost
      One config for multiple IDEs
    Engineering Friendly
      37 standard tools
      MsgPack for PNG transfer
      Same version as plugin
Benefit Specific Manifestation
Faster Restoration Agent directly uses get_selection / get_node, getting structure instead of a blurry image
Closed-Loop Editing Copy, fills, Auto Layout, creating groups, etc., can use write tools, reducing back-and-forth blame
Lowering Commercial MCP Barrier Individuals / small teams can first use the open-source local stack to run workflows (not excluding future procurement of official solutions)
Better Default Privacy Bridge is local; company files don't need to be synced to a third party just to "let the Agent take a look"
Multi-Editor Reuse Configure MCP once in Cursor; switching to Claude Code / Codex still uses the same npx command
Slices into Repository save_screenshots + compression, aligned with the plugin's 3× slice baseline

Typical Prompt examples:

3.2 Benefits for Designers

Designers may not write MCP configurations, but the plugin itself can also create value independently:

Benefit Specific Manifestation
Layer Hygiene Optional AI visual renaming, reducing Rectangle 128, Group 99
Structure Organization Optional visual grouping, organizing nesting on a copy, reducing the "junk layer" cost for developers
Slice Delivery In-panel 1× preview + 3× PNG / ZIP, no need to open a bunch of export settings separately
Bilingual Interface Teams where design prefers Chinese and development prefers English can switch individually
Alignment with Dev What the developer's Agent reads is the exact frame you are looking at, reducing "you didn't screenshot this version"

Export Slices Module

Export Slices: 1× preview, filename, single download, and ZIP (3×)

Model Settings

Optional: Configure OpenAI-compatible API for in-plugin renaming / grouping (separate from the MCP bridge path)

3.3 Benefits for "Design Engineering / Small Teams"

flowchart LR
  Design[Designer Edits File] --> Desktop[Figma_Desktop]
  Desktop --> Plugin[Figma_Agent_Kit_Plugin]
  Plugin -->|localhost_Bridge| MCP[figma_agent_mcp]
  MCP -->|stdio| Dev[Developer_Agent]
  Dev -->|Read/Write Tools| Plugin
  Plugin -->|Slice_ZIP| Assets[Deliver Assets]
  Dev -->|Code_PR| Repo[Business Repository]

4. Implementation Plan: What Does This Repository's End-to-End Look Like?

The following architecture and sequence descriptions pertain to the current implementation of Figma Agent Kit. Other community projects may differ in port, encoding, and election strategies—please refer to their respective documentation and do not assume "all local bridges look like this."

4.1 Overview

flowchart LR
  Agent[AI_Agent] -->|stdio_MCP| McpProc[figma_agent_mcp]
  McpProc -->|Election| Role{Leader_or_Follower}
  Role -->|WS_MsgPack| PluginUI[Plugin_UI]
  PluginUI -->|postMessage| PluginMain[Plugin_main]
  PluginMain --> FigmaAPI[Figma_Plugin_API]

In this repository, a typical call roughly proceeds as:

  1. Agent connects to the figma-agent-mcp process via stdio MCP;
  2. This process becomes the Leader (successfully binds localhost:PORT) or a Follower (forwards to the existing Leader);
  3. The plugin UI connects to the Leader's WebSocket using MessagePack;
  4. The UI then postMessages to the plugin main;
  5. Main calls the Figma Plugin API, and the result returns to the Agent via the original path.

4.2 Agent → MCP: Standard Tool Surface

figma-agent-mcp is a standard MCP Server. The current stable version has 37 tools, covering:

After configuring Cursor, the MCP panel should show the tools as enabled:

Cursor with 37 tools enabled

Cursor: figma-agent-mcp · 37 tools enabled

4.3 MCP → Plugin: Local Bridge

The default port comes from the repository root bridge.config.json (1998), synchronized at build time into:

This avoids the classic pitfall of "changing one side and forgetting the other."

flowchart TB
  CFG[bridge.config.json] --> SYNC[sync-bridge-config.mjs]
  SYNC --> MCP[MCP_defaultPort]
  SYNC --> UI[Plugin_UI_ws_url]
  SYNC --> MAN[manifest.json]

4.4 Sequence of a Real Call (RPC)

sequenceDiagram
  participant Agent
  participant Tools as tools.ts
  participant Node as Leader_or_Follower
  participant Bridge as bridge.ts
  participant UI as Plugin_UI
  participant Main as Plugin_main

  Agent->>Tools: MCP_tool_call
  Tools->>Node: forwardTool
  Node->>Bridge: sendRequest
  Bridge->>UI: MsgPack_request
  UI->>Main: postMessage_server_request
  Main->>Main: handleBridgeRequest
  Main-->>UI: server_response
  UI-->>Bridge: MsgPack_response
  Bridge-->>Tools: data
  Tools-->>Agent: MCP_result

Key points:

5. Key Technical Implementation Points: Several Critical Trade-offs in This Repository

Again, emphasis: these are engineering trade-offs and implementation details, used to explain "why this repository is written this way," not to claim "this is the first time the industry has done this."

5.1 Leader / Follower: Port Occupation in Multi-Window Scenarios

Reality: Opening 3 Cursor windows might launch 3 MCP processes; but one local port can usually only be successfully listened to by one process. This repository uses a Leader / Follower pattern to handle this constraint (see source code and architecture documentation for specific strategies).

sequenceDiagram
  participant P1 as McpProcess_A
  participant P2 as McpProcess_B
  participant Port as localhost_1998
  participant Plugin as Plugin_UI

  P1->>Port: listen_succeed
  Note over P1: becomes Leader
  P2->>Port: listen_fail
  P2->>P1: GET_/ping
  Note over P2: becomes Follower
  Plugin->>P1: WS_connect
  P2->>P1: POST_/rpc_MsgPack
  P1->>Plugin: WS_forward
  Plugin-->>P1: response
  P1-->>P2: MsgPack_result
Role Responsibility
Leader Binds port, accepts plugin WS, provides /ping /files /rpc
Follower Tool calls → Leader POST /rpc; discovering files → GET /files
Failure Health polling approx. 3–5s; if Leader dies, a Follower can re-campaign

For scenarios requiring multiple windows to use Agents simultaneously, this type of mechanism is closer to daily use than "assuming there will always be only one MCP process"; other open-source implementations may solve the same problem differently.

5.2 Why Does This Implementation Use MessagePack for Business Frames?

flowchart LR
  subgraph jsonPath [JSON_WS]
    J1[PNG] --> J2[base64]
    J2 --> J3[Size approx. +33%]
  end
  subgraph msgPath [MsgPack_WS]
    M1[PNG_bytes] --> M2[bin]
    M2 --> M3[More Compact]
  end

In this repository, bridge business frames and Leader↔Follower POST /rpc use MessagePack (msgpackr, useRecords: false)—this is a choice we made based on size and screenshot transfer needs, not a claim that "local bridges can only use MsgPack":

Health checks still use JSON (GET /ping, GET /files), convenient for human eyes and script probing.

5.3 Two Export Paths for Screenshots and Slices

flowchart TB
  subgraph plugin [Plugin]
    ExportAPI[exportAsync]
    ExportAPI --> Bytes[Uint8Array_PNG]
  end

  subgraph bridge [Bridge_MsgPack]
    Bytes --> Wire[bin_on_WS]
  end

  subgraph mcp [MCP]
    Wire --> GetShot[get_screenshot]
    Wire --> SaveShot[save_screenshots]
    GetShot --> B64[base64_for_Agent]
    SaveShot --> Compress[TinyPNG_style_optional]
    Compress --> Disk[write_filesystem]
  end
Tool Compression Typical Use
get_screenshot None For Agent to view (default scale=2)
save_screenshots PNG default on Delivering slices; scale=3 aligns with plugin UI

5.4 Two AI Paths: Don't Mix Them Up

flowchart TB
  subgraph pathA [MCP Path — No LLM Key Needed]
    Agent2[AI_Agent] --> MCP2[figma_agent_mcp]
    MCP2 --> Bridge2[localhost_bridge]
    Bridge2 --> Canvas[Figma_canvas]
  end

  subgraph pathB [In-Plugin AI — Optional]
    UI2[Plugin_UI] --> Vision[Screenshot + Layer Metadata]
    Vision --> API[OpenAI_Compatible_Interface]
    API --> Rename[Rename_or_Group]
  end

Prompt Settings

Editable rename / group system prompts (with placeholders)

When communicating externally, it's recommended to explain these separately to avoid the misunderstanding that "any local bridge guarantees no AI feature data leaves the machine"—this repository also makes no such absolute promise; please refer to the privacy statement and source code paths.

5.5 Engineering: Version Locking and Release Pipeline (This Repository's Practice)

flowchart LR
  Dev[Modify Code] --> Kit[pnpm_release_kit]
  Kit --> Tag1[figma-agent-mcp-vX.Y.Z]
  Kit --> Tag2[figma-agent-plugin-vX.Y.Z]
  Tag1 --> NPM[npm_publish]
  Tag1 --> GHR1[GitHub_Release_tgz]
  Tag2 --> GHR2[GitHub_Release_ZIP]
  Docs[Docs Changes] --> Pages[GitHub_Pages_Doc_Site]

We require MCP and plugin to be used with the same version whenever possible. pnpm release:kit:* bumps once, tags twice, and runs two CI pipelines, reducing mismatches like "npm upgraded, but the plugin is still from last week"—this is a maintenance strategy, not an architectural invention.

6. Project Architecture (Readable Out of the Box)

6.1 Repository Layout

figma-agent-kit/
├── bridge.config.json           # Single source of truth for default port
├── packages/
│   ├── figma-agent-mcp/         # npm: stdio MCP + Bridge Leader/Follower
│   └── figma-agent-plugin/      # Figma Plugin: Bridge Client + AI + Slices
├── docs/ + docs/zh/             # Source Documentation (Bilingual)
├── docs-site/                   # Rspress → GitHub Pages
├── articles/                    # Long-form articles like tech shares
└── scripts/                     # sync-bridge / sync-docs / release-kit

6.2 Module Responsibilities (MCP)

Module Responsibility
index.ts CLI, Election, MCP stdio
election.ts Leader listen / Follower attachment / Takeover
leader.ts HTTP /ping /files /rpc + WS
follower.ts Forwarding to Leader
bridge.ts WS table per fileKey, heartbeat, timeout
codec.ts MsgPack
tools.ts / schema.ts 37 Tools + Zod
compress-png.ts save_screenshots compression

6.3 Module Responsibilities (Plugin)

Module Responsibility
bridge/handlers.ts Tool implementation (including Motion, write operations)
bridge/serializer.ts Node tree serialization
ui/ui.html WS client, settings, i18n, slices
rename/* · group/* Optional AI Rename / Group
export/slices.ts 1× preview / 3× PNG

6.4 Technology Stack Overview

Layer Technology
MCP TypeScript ESM, @modelcontextprotocol/sdk, ws, msgpackr, Zod
Plugin TypeScript, Rsbuild, esbuild injection, Figma Plugin API
Docs Rspress bilingual, GitHub Actions → Pages
CI build / pack / tag release / Docs

For architectural details and protocol fields, see the documentation site: Architecture Description · Bridge Protocol.

7. Usage Workflow: From 0 to First Successful Call (Illustrated)

7.1 Overall Flow

flowchart TD
  A[Install_Figma_Desktop_and_Node20] --> B[Download_Plugin_ZIP_1.0.0]
  B --> C[Import_plugin_from_manifest]
  C --> D[Run_Figma_Agent_Kit]
  D --> E[Configure_Editor_MCP_npx]
  E --> F[Restart_MCP_See_37_tools]
  F --> G[Plugin_Shows_Bridge_Connected]
  G --> H[Agent_Calls_list_files]
  H --> I[get_selection]
  I --> J[Write_Operation_or_save_screenshots]
  J --> K[Smoke_Test_Complete]

7.2 Environment Requirements

7.3 Step 1 — Install Plugin

  1. Open Releases
  2. Download the same version figma-agent-plugin-v1.0.0.zip as the MCP
  3. Unzip
  4. Figma Desktop → Plugins → Development → Import plugin from manifest…
  5. Select the manifest.json in the directory
  6. Run Figma Agent Kit

Plugin Connected

When you need to focus on the selection, you can enter Mini mode:

Mini Mode

Mini: Bridge status + current selection

The gear menu allows switching languages, entering model / prompt settings, and checking for updates:

Settings Menu

7.4 Step 2 — Configure MCP (Cursor Example)

Edit ~/.cursor/mcp.json (or project-level .cursor/mcp.json):

{
  "mcpServers": {
    "figma-agent-mcp": {
      "command": "npx",
      "args": ["-y", "figma-agent-mcp"]
    }
  }
}

Custom port (must be consistent with the plugin build):

"env": { "FIGMA_AGENT_MCP_PORT": "1998" }

Cursor mcp.json Configuration

Cursor mcp.json connecting to figma-agent-mcp

For copy-paste configurations for other editors (Claude Code / Codex / Qoder / CodeBuddy / Trae), see: https://chinacarlos.github.io/figma-agent-kit/guide/agent-setup

7.5 Step 3 — Smoke Test

Ensure: The plugin is open in Figma, the bridge is green, and MCP shows 37 tools. Then ask the Agent:

  1. Call list_files — should see the current file;
  2. Select a Frame in Figma, call get_selection;
  3. Try a lightweight write operation, or save_screenshots.
sequenceDiagram
  participant U as You
  participant A as Agent
  participant M as figma-agent-mcp
  participant P as Plugin
  participant F as Figma

  U->>A: Please list_files
  A->>M: tools/call list_files
  M->>P: MsgPack RPC
  P->>F: Plugin API
  F-->>P: File List
  P-->>M: result
  M-->>A: MCP result
  A-->>U: The currently open file is…

Once this works, you've completed the minimal closed loop for "bringing the design file into the Agent's context."

7.6 Recommended Daily Workflow

Role Suggested Rhythm
Designer Edit in Desktop → Use plugin for slices / AI layer organization as needed
Developer Keep Cursor open with MCP → Ask about selections / modify structure / export assets
Pair Collaboration Same file; developer clicks the target Frame in Figma before reading the selection
Troubleshooting First check if the plugin light is green → Then check if MCP has 37 tools → Then check if the port is consistent

For more troubleshooting, see the documentation site FAQ.

8. Plugin + MCP + Skill: Upgrading from "Can Connect" to "Can Restore 1:1"

The previous chapters solved: how the toolchain connects to the current canvas. When truly connected to business, there is another common gap—

The Agent can call get_node / save_screenshots, but lacks unified discipline: scope expands arbitrarily, entire pages are forced into one image, TEXT is missed, slice exports bake interface copy, and acceptance slogans precede actual comparison.

Therefore, this repository additionally provides a Cursor Agent Skill: figma-ui-restore, which compiles the Figma Agent Kit plugin + figma-agent-mcp into a reusable universal UI 1:1 restoration process (not tied to any specific campaign scaffold).

Path (after cloning the repository):

.cursor/skills/figma-ui-restore/SKILL.md

In Cursor, you can use @figma-ui-restore, or trigger similar intent in conversation by saying "restore 1:1 according to Figma / export slices to disk / compare and accept."

8.1 How the Three-Piece Set Divides Work

flowchart LR
  subgraph human [Human]
    U[Give_Figma_URL_and_Confirmation_Gate]
  end

  subgraph skill [Cursor_Skill]
    S[figma-ui-restore<br/>Discipline_and_Step_Checklist]
  end

  subgraph mcp [figma-agent-mcp]
    T[list_files_get_node<br/>get_screenshot<br/>save_screenshots]
  end

  subgraph plugin [Figma_Agent_Kit_Plugin]
    P[Plugin_API_Read_Write_Canvas]
  end

  subgraph code [Business_Repository]
    C[Write_Code_Assets_Acceptance]
  end

  U --> S
  S -->|Constrain_Call_Order| T
  T -->|localhost_Bridge| P
  S -->|bounds_Slice_Granularity_Checklist| C
  P --> C
Layer Responsibility Not Responsible For
Plugin Can touch the current file; executes export / node read-write Does not dictate your React/Vue directory structure
MCP Turns capabilities into standard tools for the Agent to call Does not automatically guarantee "1:1 acceptance passed"
Skill Specifies scope, TEXT categorization, slice tagging, block-by-block comparison, acceptance wording Does not replace business PRD / interface codegen

In one sentence:

Plugin + MCP = Capability; Skill = How to responsibly use these capabilities for restoration.

8.2 The Main Process Specified by the Skill (strict default)

Lock scope → (Confirmation Gate) → list_files → get_node read structure → Full TEXT categorization
  → Slice tagging → get_screenshot baseline image → save_screenshots×3 write to disk
  → bounds code generation → Block-by-block comparison → Acceptance checklist all checked before claiming "1:1"

flowchart TD
  A[User gives Figma URL] --> B[Parse scopeNodeId]
  B --> C{Implementation Confirmation Gate?}
  C -->|Not Confirmed| D[Forbid get_node / slice / code generation]
  C -->|Confirmed| E[list_files → connected fileKey]
  E --> F[get_node structure + bounds]
  F --> G[3b Full TEXT Categorization]
  G --> H[4 Slice Tagging skin/whole-btn/panel-bg]
  H --> I[get_screenshot Baseline Image]
  I --> J[save_screenshots scale3]
  J --> K[bounds Code Generation]
  K --> L[Block-by-Block Comparison]
  L --> M{Block Passed?}
  M -->|No| K
  M -->|Yes| N[Acceptance Checklist]
  N --> O{All Passed?}
  O -->|No| K
  O -->|Yes| P[Can Claim Scope 1:1 Comparison Acceptance]

Only when the user explicitly says fast can some structural reading descriptions be compressed and baseline image writing be omitted; must not skip the TEXT checklist and slice granularity, must not default to one image for the entire page.

8.3 Several "Specifically Prevent Failures" Disciplines

Discipline Meaning
Single scope One node-id in URL → Only restore that subtree; forbid casually scanning the entire file
Confirmation Gate Forbid get_node / save_screenshots / code generation before confirmation (allow list_files)
connected fileKey First list_files, do not just use the fileKey from the URL
Full TEXT Checklist Each TEXT categorized into whole-btn-text / dom-fixed / dynamic, etc.; cannot slice before categorization
Slice Granularity Only export skin / whole-btn / panel-bg (including modal-panel-bg); copy/images that will change via API do not go into PNG
3× + Compression Deliver slices using save_screenshots, scale: 3, compress: true
bounds Priority Under strict mode, asymmetric layouts forbid using flex:1 as a crutch
Block-by-Block Comparison If one large block fails, cannot proceed to the next block
Acceptance Wording If the checklist is not fully passed, forbid writing "1:1 comparison acceptance completed"

These entries share the same origin as excellent campaign restoration specifications in the community; we generalized them and wrote them into this repository's Skill, making it convenient for any frontend project to reuse, rather than being tied to a specific business repository.

8.4 How to Choose Between This and "Just Connecting MCP" Daily Usage

What You Want to Do Suggestion
Ask "what is the structure of the current selection" Directly use Agent + MCP tools
Change some copy / export a few images MCP tools + Plugin green light
Do page/modal 1:1 restoration and acceptance based on an artboard Enable figma-ui-restore Skill, follow the complete checklist
Just organize layer naming / grouping Can use other layers-type Skills (if available); does not replace the restoration Skill

8.5 How to Use It in Your Own Project

  1. Install and run the Figma Agent Kit plugin, configure figma-agent-mcp (see Chapter 7 above).
  2. Copy this repository's .cursor/skills/figma-ui-restore/ to your business repository's .cursor/skills/ (or use submodule / document convention reference in a monorepo).
  3. Open the business repository, use Cursor to provide the Figma link, and specify the tech stack and asset directory.
  4. @figma-ui-restore or explicitly "do strict 1:1 restoration according to the Skill."
  5. Require the Agent to output according to the Skill template: TEXT checklist, slice checklist, reference parent, block-by-block comparison, acceptance conclusion.

Please refer to the file in the repository for the Skill text: .cursor/skills/figma-ui-restore/SKILL.md

Note: The Skill is an Agent behavior specification, not part of the npm package; it evolves alongside the repository documentation/engineering assets when the kit is versioned. Separating "capability" from "usage discipline" allows the same set of MCP tools to be used for both conversational exploration and serious restoration.

9. Who It's For / Who It's Not For

Suitable For

Things It Can Do (Examples)

Things Not to Expect

10. Open Source Address, Documentation, Acknowledgments

Resource Link
This Repository (Welcome ⭐ / Issue / PR) https://github.com/ChinaCarlos/figma-agent-kit
Documentation Site (Bilingual) https://chinacarlos.github.io/figma-agent-kit/
UI Restoration Skill https://github.com/ChinaCarlos/figma-agent-kit/blob/main/.cursor/skills/figma-ui-restore/SKILL.md
npm: figma-agent-mcp https://www.npmjs.com/package/figma-agent-mcp
Plugin ZIP https://github.com/ChinaCarlos/figma-agent-kit/releases/tag/figma-agent-plugin-v1.0.0
MCP Release https://github.com/ChinaCarlos/figma-agent-kit/releases/tag/figma-agent-mcp-v1.0.0
Docs Release https://github.com/ChinaCarlos/figma-agent-kit/releases/tag/docs-v1.0.0
License MIT

Run the documentation site locally:

git clone https://github.com/ChinaCarlos/figma-agent-kit.git
cd figma-agent-kit
pnpm install
pnpm dev:docs

One-liner to start this repository's MCP (requires the corresponding version of the plugin installed/imported):

npx -y figma-agent-mcp

Acknowledgments (Please Read)

Figma Agent Kit stands on the existing work of the community. The "local Figma ↔ Agent bridge" direction has been explored jointly by numerous open-source authors, articles, and repositories; we learned the routes and problem domains from them, then adapted, reorganized, and supplemented documentation and release processes according to our own maintenance goals. If your project directly or indirectly inspired this repository, thank you for your public sharing—if there are still imprecise expressions in the text, feel free to open an Issue to correct them, and we will make changes.

We also make clear:

11. Final Words

If one sentence could encapsulate the stance of this article, it would be:

The next mile of AI Coding isn't all about stronger models; local, auditable, modifiable toolchain interfaces are equally important. The community has already paved the way; we just built another section of roadbed more suitable for our own maintenance, and open-sourced it.

For this repository, we care more about these "usable daily" parts: port handling under multi-process, the screenshot pipeline, version locking, bilingual documentation, reproducible releases, and compiling the plugin + MCP into the restoration discipline of the figma-ui-restore Skill—they may not be flashy, but they are critical for real collaboration.

If this article is useful to you, welcome to:

  1. Star the repository ⭐ — https://github.com/ChinaCarlos/figma-agent-kit
  2. Run through list_files → get_selection once according to the docs
  3. When you need to do page restoration, try the full @figma-ui-restore process once
  4. Mention pitfalls and suggestions in Issues; PRs are also welcome if you're able

Bookmark Links

—— Reprinting is welcome, just credit the source and repository link.

Figma Agent Kit Logo

Comments

Top 1 of 4 from juejin.cn, machine-translated. The original thread is authoritative.

星河微尘

You need to use Figma's MCP, right? It seems like it costs money.

八号当铺

No, you just need to download the Figma desktop app yourself and install a custom plugin and MCP service.

星河微尘  → 八号当铺

Is the MCP a local service?