figma-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Build & Test Commands

npm run build              # TypeScript compile (src/shared + src/mcp-server + src/websocket-server → dist/)
npm run build:all          # Same as build (alias)
npm test                   # Run all tests (vitest)
npm run test:watch         # Watch mode
npm run test:coverage      # Coverage report (80% threshold on lines/funcs/branches/stmts)
npx vitest run tests/mcp-server/tools.test.ts  # Single test file
npm run socket             # Start WebSocket bridge (production)
npm run dev:socket         # Start bridge with auto-reload (tsx watch)

Architecture

Three processes connected in a chain:

Claude ←stdio→ MCP Server ←WebSocket→ Bridge (127.0.0.1:9001) ←WebSocket→ Figma Plugin

MCP Server (src/mcp-server/index.ts): Uses McpServer from @modelcontextprotocol/sdk/server/mcp.js. Tool registration loops over TOOL_REGISTRY from tools/index.ts. WebSocket client logic lives in ws-client.ts. On tool call, sends a COMMAND over WebSocket and awaits a RESPONSE matched by requestId. Some tools are server-side only (intercepted before sendCommand) — see "Server-side Tools" below.

WebSocket Bridge (src/websocket-server/index.ts): Accepts exactly two client roles — MCP client (identified by ?role=mcp-client query param) and Figma plugin (identified by sending REGISTER as first message). Config in config.ts, validation in validation.ts. Routes COMMANDs from MCP→plugin and RESPONSEs from plugin→MCP.

Figma Plugin (src/figma-plugin/): Runs in Figma Desktop. code.js is the sandbox with figma.* API access. ui.html is a hidden iframe that holds the WebSocket connection. They communicate via figma.ui.postMessage/figma.ui.onmessage. Plugin is plain JavaScript (no build step needed).

Directory Structure

src/
├── shared/                          Wire protocol & constants (single source of truth)
│   ├── index.ts                     Barrel re-export
│   ├── protocol.ts                  ErrorCode, message types, WireMessage
│   ├── constants.ts                 COMMAND_NAMES, REQUEST_ID_PATTERN, defaults, LOG_LEVELS
│   └── logger/                      Structured logging & metrics module
│       ├── index.ts                 Barrel re-export
│       ├── logger.ts                createLogger() factory (pino-based), LogConfig
│       ├── metrics.ts               MetricsCollector class (counters, histograms)
│       └── redact.ts                Sensitive field redaction paths
│
├── mcp-server/
│   ├── index.ts                     Server setup + startup
│   ├── ws-client.ts                 WebSocket client (connect, reconnect, sendCommand)
│   ├── request-tracker.ts           Promise-based request/response tracking
│   └── tools/                       Tool schemas split by category
│       ├── index.ts                 Barrel: merges partial registries → TOOL_REGISTRY
│       ├── shared-schemas.ts        NodeId, RGBAColor, Fill, Typography, etc.
│       ├── read-tools.ts            get_document_info, get_selection, get_node
│       ├── create-tools.ts          create_frame, create_rectangle, create_ellipse, create_text, create_line, create_polygon
│       ├── modify-tools.ts          set_auto_layout, update_text, update_node, add_shadow
│       ├── organize-tools.ts        group_nodes, delete_node, create_component, clone_node, reorder_node
│       ├── viewport-tools.ts        zoom_to_node
│       ├── style-tools.ts           set_fill, set_stroke, set_corner_radius, set_effects
│       ├── layout-tools.ts          set_node_layout_properties
│       ├── component-tools.ts       create_component_instance, get_local_components, list_available_fonts
│       ├── style-system-tools.ts    create_paint_style, create_text_style, get_local_styles, apply_style
│       ├── image-tools.ts           set_image_fill, set_image_from_url, set_image_from_path
│       ├── export-tools.ts          export_node
│       ├── typography-tools.ts      set_text_decoration, set_text_case, set_text_list
│       ├── constraint-tools.ts      set_constraints, set_layout_grids
│       ├── batch-tools.ts           batch_create, batch_update
│       ├── vector-tools.ts          create_vector, create_boolean_operation
│       ├── page-tools.ts            create_page, create_section
│       ├── traversal-tools.ts       find_nodes
│       ├── variable-tools.ts        create_variable_collection, create_variable, bind_variable
│       ├── workflow-tools.ts        flatten_node, ungroup_nodes, set_selection, set_current_page, create_effect_style, get_variables
│       ├── design-system-tools.ts   combine_as_variants, detach_instance, swap_component, import_component_by_key
│       ├── manipulation-tools.ts    set_rotation, set_blend_mode, lock_node
│       └── extra-shape-tools.ts     create_star, create_svg_node, notify
│
├── websocket-server/
│   ├── index.ts                     FigmaBridge class + entry point
│   ├── config.ts                    BridgeConfig interface + loadConfig()
│   └── validation.ts               ProtocolError + parseAndValidate()
│
└── figma-plugin/                    Plain JS, no build step
    ├── code.js                      Plugin sandbox (figma.* API)
    ├── ui.html                      Hidden iframe (WebSocket connection)
    └── manifest.json                Figma plugin manifest