Bridge

#What is Bridge

SXL Studio Bridge is magic for the user. Launch Bridge, enable Remote Connect in the plugin — and your AI agent in Cursor (or any MCP-compatible tool) gets full access to Figma through SXL Studio: creating components, exporting tokens, applying data, managing canvas nodes, running the exact same Dev Mode code generators, and much more.

Bridge is a Node.js process that connects IDEs and HTTP clients to the SXL Studio plugin in Figma. It runs on a single port and supports three protocols simultaneously:

• WebSocket — for plugin UI connection
• HTTP REST API — for integration with scripts and tools
• MCP (Model Context Protocol) — for AI agents in Cursor, VS Code, and others

#Why it's needed

The official Figma MCP does not execute your plugin code. Bridge is needed for SXL Studio-specific operations:

• Generating and applying Composition components
• Exporting/importing tokens and variables
• Managing Database data
• Git operations (Push, Pull)
• Creating and modifying canvas nodes
• Binding variables, importing components, CRUD on local styles
• Running the plugin's Dev Mode codegen (Designer JSON / Vue3 / SwiftUI / Kotlin) with no drift
• And dozens of other commands

#Installation and launch

#From npm (recommended)

npm install -g @sxl-studio/bridge
sxl-bridge

#From source (monorepo)

cd Utils/bridge
npm install
npm run build
npm start

#Port

By default, Bridge runs on port 37830. If the port is occupied, specify another via an environment variable:

BRIDGE_PORT=38000 sxl-bridge

When changing the port, update the MCP client and plugin configuration.

#Optional: authentication

Set BRIDGE_AUTH_TOKEN to require a shared secret on every request (REST and MCP):

BRIDGE_AUTH_TOKEN=s3cret sxl-bridge

Clients must then send Authorization: Bearer s3cret. Without the token, requests get 401 BRIDGE_UNAUTHORIZED. By default the token is not set and Bridge is localhost-only and unauthenticated.

#Connecting to Figma

1. Launch Bridge — make sure it's running (check terminal logs)
2. Open SXL Studio in Figma
3. Enable Remote Connect — connection status appears in the plugin
4. Bridge shows a connected session message

#Checking status

curl http://127.0.0.1:37830/api/status

Response:

{
  "ports": { "websocket": 37830, "http": 37830 },
  "mcpStreamableHttp": "http://127.0.0.1:37830/mcp",
  "session": { "connected": true, "sessionId": "abc123" },
  "queueLength": 0,
  "currentCommand": null,
  "authEnabled": false
}

#Configuring MCP for Cursor

#Option 1 — URL (recommended)

In .cursor/mcp.json:

{
  "mcpServers": {
    "sxl-studio": {
      "url": "http://127.0.0.1:37830/mcp"
    }
  }
}

#Option 2 — stdio

{
  "mcpServers": {
    "sxl-studio": {
      "command": "node",
      "args": ["/path/to/sxl-studio/Utils/bridge/dist/index.js"]
    }
  }
}

When using stdio, Bridge launches the MCP server via stdin/stdout. Stdout is occupied by JSON-RPC — logging only through console.error.

#Tool discovery

Use list_tools (MCP) or GET /api/tools (HTTP) to get an authoritative catalogue of every tool Bridge exposes, grouped by category, with flags for requiresDesignMode and requiresComposition.

# Every tool
curl http://127.0.0.1:37830/api/tools

# Only tools usable in Figma Dev Mode (reads + file ops)
curl 'http://127.0.0.1:37830/api/tools?devModeReadableOnly=true'

#Available commands

Bridge provides dozens of tools for AI agents. Main categories:

#Diagnostics

#Tokens + config (workspace CRUD)

#Compositions and Dev Mode codegen

Why this matters: Bridge uses the exact same codegen pipeline as Dev Mode. When an agent asks for "JSON" or "the same code Get Code produces", it MUST call export_composition_json or get_codegen. Synthesising JSON from get_node_tree / get_selection produces drift-prone output that the plugin parser cannot round-trip.

#Variables (full CRUD)

#Styles

#Data and mapping

#Canvas operations

create_frame, create_rectangle, create_text, create_ellipse, create_line, create_svg_node, create_vector, create_component, create_component_set, create_component_instance, detach_instance, clone_node, duplicate_subtree, delete_node, delete_nodes, set_auto_layout, modify_node, rename_node, set_node_text, set_node_property, set_node_visibility, set_node_size, set_node_fill, set_node_fill_variable, set_stroke, set_effects, set_fill, set_image_fill, set_constraints, style_text_range, move_to_parent, import_component_by_key, boolean_operation, flatten_nodes, apply_documentation_payload, and more.

#Git

#High-level orchestration

Agent recipes (MCP Resources, JSON):

• sxl://agent/recipes/index — intent router (user phrases → recipe). Always start here.
• sxl://agent/recipes/doc-spec-v2 — section vocabulary.
• sxl://agent/recipes/template-discovery — finding the templateNodeId without use_figma.
• sxl://agent/recipes/doc-tokens, doc-component, doc-composition, doc-flow, variable-palette — concrete flows.

Full contract and architecture: Plugin/sxl/docs/22-doc-spec-v1.md, Plugin/sxl/docs/24-doc-builder-architecture.md.

#Doc Builder — three flows in one tool each

1. Variable-collection palette. "Fill content with all colors of the Projects collection" → one call to bind_variable_palette { templateNodeId, collectionName: "Projects", swatchLayerName: "swatch" }. Bridge enumerates the variables, clones the card, binds the fill — no use_figma, no /tmp/*.json payloads.
2. Component documentation. "Document WButton" → build_component_doc { componentNodeId, targetParentId, includeMeasure: false }. Bridge composes title + variants + props and applies sections in order.
3. Multi-page scenario. "Build a flow from these URLs" → build_doc_flow { pages: [{ nodeId, title, description }, ...], targetParentId }. Pages land in an auto-layout container with captions.

#Audit & Usage — analyse a Figma file

Category audit (see list_tools?category=audit). Every command runs over MCP — no use_figma, no /tmp payloads. By default each call returns a compact summary; the matching find_* sibling streams details with cursor + limit.

Audit scopes: "page" (default), "file", "selection", { type: "node", nodeId }. Always start with page or selection; widen to file only after the summary confirms it is worth the cost.

Recipe routers for agents:

• sxl://agent/recipes/variable-usage — picking between analyze / find / render.
• sxl://agent/recipes/audit-coverage — audit_* → find_* → batch_bind_variables.
• sxl://agent/recipes/find-unused — find_unused_* (deletion only after explicit user confirmation).

#Variables orchestration — bulk variable CRUD (Phase B)

Category variables-orchestration (Bridge 1.6.0+ / Plugin 2.3.0+). "Thick" commands for the most common Figma Variable refactors — without use_figma and without atomic-create_variable loops. Every write command supports dryRun (or apply: false) so the agent can preview the plan before committing.

Recipes:

• sxl://agent/recipes/bulk-variables — picking between import_variable_spec / dedupe_variables / rebind_variable_aliases / analyze_variable_order (always dry-run first).
• sxl://agent/recipes/auto-bind-from-audit — Phase A → Phase B: find_variable_coverage_misses → apply_coverage_suggestions (always dry-run preview).

#Styles orchestration — bulk style CRUD (Phase C)

Category styles-orchestration (Bridge 1.6.0+ / Plugin 2.3.0+). Mirror of Phase B for local Figma styles (PaintStyle / TextStyle / EffectStyle). Every write command supports dryRun (or apply: false) so the agent can preview the plan before committing. audit_style_drift is read-only and works in Dev Mode.

Recipes:

• sxl://agent/recipes/bulk-styles — picking between import_style_spec / dedupe_styles / rebind_style_consumers / apply_style_coverage_suggestions (always dry-run first).
• sxl://agent/recipes/style-drift — audit_style_drift byName-vs-variables / explicit; pair with import_style_spec for the fix.

#Mockup-from-DesignSystem — assemble screens from components (Phase D)

Category mockup (Bridge 1.6.0+ / Plugin 2.3.0+). Thick commands that assemble pages / cards / lists out of existing design-system components — no use_figma, no hand-rolled figma.createInstance + setProperties loops. Write commands support dryRun: true; find_components is Dev-Mode compatible.

Recipe: sxl://agent/recipes/mockup-builder — pipeline find_components → build_mockup (dryRun → commit) → optional apply_mockup_dataset. Architecture and rules: Plugin/sxl/docs/29-mockup-builder.md.

#Compositions orchestration — bulk work with composition files (Phase E)

Category compositions-orchestration (Bridge 1.6.0+ / Plugin 2.3.0+). Thick commands that drive the per-file generate_composition / apply_composition pipeline in one MCP call: SXL DS tokens/components/W*.json go from chat instruction to Figma without hand-rolled for-of loops or per-file check_composition_linked polling. The write command supports dryRun: true; audit_composition_drift is fully read-only and Dev-Mode safe.

Recipes:

• sxl://agent/recipes/bulk-compositions — pipeline audit_composition_drift (target list) → bulk_generate_compositions { dryRun: true } (preview) → commit.
• sxl://agent/recipes/composition-drift — read-only audit before any write. Use this when the user asks "what's out of sync?" before touching canvas.

Architecture and rules: Plugin/sxl/docs/30-compositions-orchestration.md.

#HTTP API

Besides MCP, Bridge exposes an HTTP REST API:

#Idempotency

Pass an Idempotency-Key header (or idempotencyKey field in the JSON body) on POST /api/command. Repeating the same key within 10 minutes returns the cached result without re-dispatching the command to the plugin — safe for network retries.

#HTTP command example

curl -X POST http://127.0.0.1:37830/api/command \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: ab12cd34" \
  -d '{
    "commandType": "get_codegen",
    "payload": { "nodeId": "123:456", "language": "vue3" }
  }'

#Typed errors

Every failure comes back with a structured envelope:

{
  "status": "failed",
  "error": "{\"code\":\"EDITOR_MODE_READONLY\",\"message\":\"Command \\\"create_frame\\\" requires Figma Design mode.\",\"retryable\":false,\"details\":{\"editorType\":\"dev\",\"isDevMode\":true}}"
}

MCP tools parse this envelope and surface { code, message, retryable, details } to the agent. Known codes: EDITOR_MODE_READONLY, BRIDGE_TIMEOUT, BRIDGE_CANCELLED, BRIDGE_UNAUTHORIZED, BRIDGE_ERROR.

#MCP Resources

Bridge also exposes addressable resources — Cursor and Claude Desktop can attach them as context without calling tools:

#Dev Mode support

The plugin runs in two Figma contexts:

Recommended Dev Mode workflow for developers:

1. Open the plugin in Dev Mode.
2. Enable Remote Connect — the session works identically to Design mode.
3. Use get_codegen / export_composition_json / get_variables / list_token_files / get_applied_tokens for introspection.
4. Use git_pull / git_push / save_token_file / save_tokens_config on the plugin workspace — these operate on files, not the canvas, so Dev Mode restrictions do not apply.
5. Canvas-write commands (create_frame, modify_node, bind_variable, …) return a typed EDITOR_MODE_READONLY error — surface that error to the user.

#Version compatibility

When updating Bridge, check the minimum supported plugin version. Bridge 1.6.x requires plugin 2.3.0+ for the new audit, variables-orchestration, styles-orchestration, mockup, and compositions-orchestration categories (additional whitelisted commands + dryRun-aware editor mode).

#Related sections

• Git — Integration — Git operations through Bridge
• Composition — component generation
• Transformer — code generation from tokens