@sxl-studio/bridge

v1.7.3

Published

7 days ago

MCP/HTTP bridge server for SXL Studio Figma plugin — enables remote control from IDE

0High
0Medium
0Low

SXL Studio Bridge

Node.js process that connects Cursor (or any MCP client) and HTTP clients to the SXL Studio Figma plugin while a Remote Connect session is active in the plugin UI.

What it does

WebSocket — plugin UI iframe connects here and forwards remote-command / results.
MCP (Streamable HTTP + stdio) — Cursor / Claude Desktop / any MCP client calls typed tools (export_variables, export_composition_json, get_codegen, compose_from_url, index_icons_for_export, …); each tool maps to one plugin command or an orchestration that chains several.
HTTP — same command queue for scripts, CI, curl, idempotency-safe retries, audit log.

Official Figma MCP does not run your plugin code. Use both: Figma MCP for file/design context; this bridge for SXL-specific operations (compositions, token export, mappings, Git, Dev Mode codegen).

Figma MCP vs SXL Bridge (product split)

| Need | Use | |------|-----| | Native file operations where Figma’s MCP tools are enough (context, many canvas writes, new files, FigJam/Slides, FigJam/Slides asset upload) | Official Figma MCP (often remote https://mcp.figma.com/mcp) | | Plugin-only workflows: compositions, plugin token/Git APIs, whitelisted node helpers, Dev Mode codegen parity | SXL Studio Bridge + plugin Remote Connect | | Cross-file/no-plugin reads for known files or teams (whoami, file/node metadata, screenshots/image URLs, published components/styles, variables REST endpoints), active-file design context, active-file metadata, variable/style definitions, Figma MCP-compatible library discovery/search, Figma Design image insertion, local Code Connect context/suggestions | SXL Studio Bridge (get_design_context, get_metadata, get_variable_defs, get_libraries, search_design_system, figma_rest_*, get_screenshot, upload_assets, get_context_for_code_connect, get_code_connect_suggestions) |

Bridge catalogue entries expose explicit execution metadata:

execution: "plugin" — the MCP tool sends one Remote Connect command to the plugin.
execution: "bridge-orchestration" — Bridge parses/aggregates input and sends one or more plugin commands.
execution: "bridge-local" — Bridge answers locally and does not require a plugin command.

Plugin-routed tools list their exact pluginCommandTypes; each one must exist in the plugin Remote Connect whitelist and handlers. Adding a plugin-routed MCP tool in Bridge without the matching plugin contract will return not_whitelisted.

AI agent operating contract

When this README is used as context for an AI agent, the agent should treat Bridge as the controlled SXL Studio automation layer, not as a generic canvas scripting surface.

Start with get_bridge_runtime_summary or GET /api/runtime-summary.
If the task needs the open Figma file and Remote Connect is not connected, stop and ask the operator to open SXL Studio in Figma and enable Remote Connect. Do not fake live Figma results.
For natural-language tasks, call route_intent, then plan_workflow, then preview_workflow before write tools.
For screen generation, call inspect_design_system, then validate_screen_spec, then build_screen / update_screen with dryRun: true, then apply.
For variable/style export, call preview_export_variables before export_variables; destructive options require top-level confirmDestructive: true.
For Figma documentation, prefer apply_doc_spec, build_component_doc, build_doc_flow, bind_variable_palette, and build_scenario_from_md over ad hoc scripts.
For large scans, request summaries first and use paginated detail tools only for the exact subset you need.
After writes, re-run the relevant read/audit command and report changed/skipped items plus any visual review that remains.

Bridge covers active-file Figma Design + SXL Studio workflows. Official Figma MCP remains the companion for remote-only/new-file work, FigJam/Slides-specific editing, generated diagrams, and hosted-only Code Connect context. Official references:

| User intent | Start with | Then use | |---|---|---| | Build or update a Figma screen | route_intent, inspect_design_system | validate_screen_spec, build_screen / update_screen dry-run, then apply | | Render documentation in Figma | route_intent, sxl://agent/recipes/sxl-doc-builder | apply_doc_spec, build_component_doc, build_doc_flow, build_scenario_from_md | | Export variables/styles | preview_export_variables | export_variables with explicit options | | Audit raw values or missing bindings | audit_variable_coverage, audit_style_coverage | paginated find_*, dry-run apply suggestions | | Analyze component usage/props | analyze_component_usage, analyze_component_prop_usage | find_component_usages, find_component_prop_usages | | Generate/apply compositions | compose_from_url, list_composition_files | bulk_generate_compositions, audit_composition_drift | | Connect Figma components to code | get_context_for_code_connect | get_code_connect_suggestions, generate_code_connect_template, codeconnect_save_binding | | Use repository-backed local storage | Git Sync Local Storage settings | /api/workspace-blob, git_pull, git_push |

Version compatibility (npm Bridge ⟷ plugin)

| @sxl-studio/bridge (npm) | SXL Studio plugin | Highlights | |---------------------------|-------------------|------------| | 1.0.x | same-era | Base remote node tools (create_frame, set_node_fill, …) | | 1.1.x | same-era | set_node_fill_variable, extended create_frame / create_text (parentId, Auto Layout fields) | | 1.2.x | same-era | Remote module split (dispatch/, canvas/, sxl/), MCP instructions, base canvas tools, validated POST /api/command, aligned COMMAND_TIMEOUTS | | 1.3.x | 2.1.0+ | Dev Mode codegen bridge (get_codegen, export_composition_json), full token workspace CRUD (create_token_file, delete_token_file, move_token_file, save_tokens_config, upsert save_token_file), Variables CRUD (modes, scopes, codeSyntax), Styles CRUD, orchestration (compose_from_url, generate_code_from_url, document_component), MCP Resources (sxl://…), typed errors (EDITOR_MODE_READONLY + structured envelope), BRIDGE_AUTH_TOKEN, Idempotency-Key on /api/command, /api/log audit trail, /api/tools + list_tools meta-tool, editor-mode write-guard with typed propagation. | | 1.4.x | 2.1.0+ (plugin with apply_token_doc_spec) | Doc Spec v1 + build_token_documentation / apply_token_doc_spec, MCP resources sxl://agent/recipes/doc-tokens (+ doc-component, doc-composition, doc-flow), expanded MCP instructions for documentation recipes. | | 1.5.x | 2.2.0+ | Doc Builder v2: apply_doc_spec (generic sections), bind_variable_palette, build_component_doc, build_doc_flow. Intent-router resource sxl://agent/recipes/index plus template-discovery, doc-spec-v2. Reinforced anti-patterns in sxl-mcp-instructions.ts (/tmp payloads, base64 loaders, use_figma scripts). | | 1.6.x | 2.3.0+ | Audit & Usage (Phase A) + Variables orchestration (Phase B) + Styles orchestration (Phase C) + Mockup-from-DesignSystem (Phase D) + Compositions orchestration (Phase E). Phase A: audit category — analyze_variable_usage, find_variable_usages, render_variable_usage_page, audit_variable_coverage, find_variable_coverage_misses, audit_style_coverage, find_style_coverage_misses, find_unused_variables, find_unused_styles. Chunked traversal with transitive-alias resolution. Token-economy: summary by default, paginated find_* for details. Phase B: new variables-orchestration category — import_variable_spec (idempotent bulk create / update with aliases), analyze_variable_order (read-only ordering diff), dedupe_variables (merge duplicates, dry-run by default), rebind_variable_aliases (bulk alias rewrite), apply_coverage_suggestions (audit suggestions → real bindings, dry-run by default). Phase C: new styles-orchestration category — import_style_spec (idempotent bulk create / update of Paint / Text / Effect styles), dedupe_styles (merge duplicates byName | bySignature), rebind_style_consumers (bulk styleId rewrite on consumer nodes), audit_style_drift (read-only drift between local Paint styles and Variables / expectations[]), apply_style_coverage_suggestions (Phase A find_style_coverage_misses → real setStyleId* writes). Phase D: new mockup category — find_components (read-only paginated catalogue of local + library-instantiated components with componentPropertyDefinitions, Dev-Mode compatible), build_mockup (declarative auto-layout assembly from an instance | section | spacer | text item tree with property / text / fill-binding overrides; dryRun-aware), apply_mockup_dataset (clone a template per dataset row with row-specific overrides; dryRun-aware). Phase E: new compositions-orchestration category — bulk_generate_compositions (bulk generate / apply of composition files with fileIds | names | prefix filters, operation: auto | generate | apply, per-item error isolation, dryRun-aware), audit_composition_drift (read-only drift detection between workspace composition files and tracked Figma components: linked | unlinked | drift | missing, Dev-Mode safe). All write commands accept dryRun / apply so Dev Mode can be used as a preview surface. Recipes: sxl://agent/recipes/{variable-usage,audit-coverage,find-unused,bulk-variables,auto-bind-from-audit,bulk-styles,style-drift,mockup-builder,bulk-compositions,composition-drift}. | | 1.7.x | 2.3.0+ (plugin with Git Sync Local Storage) | Workspace blobs API (GET|POST|DELETE /api/workspace-blob): disk-backed cache for large Git Sync payloads so token/dataset bodies stay out of Figma clientStorage. Uses OS cache dir (env-paths, product id sxl-studio-bridge) under workspace-blobs/ unless overridden by SXL_BRIDGE_WORKSPACE_BLOB_ROOT. Same BRIDGE_AUTH_TOKEN rules as other /api/*; if auth is enabled, enter the same token in the plugin Sync connection's Bridge Auth Token field. Does not require an active Remote Connect WebSocket session. Contract stabilization: MCP version follows package.json, route_intent maps RU/EN natural language to SXL recipes/tools/schema hints, plan_workflow/preview_workflow add dry-run/approval gates for multi-step chains, list_tools//api/tools expose aliases, natural-language intents, dry-run and large-data flags, get_capability_matrix returns a machine-readable tool matrix, get_contract_audit verifies required meta tools/schema entrypoints/workflow gates, get_bridge_audit_log reads memory or persisted JSONL audit, MCP tools return normalized envelopes, export_variables uses plugin-safe defaults, Code Connect accepts full binding metadata, exposes schema resources, suggests local bindings through get_context_for_code_connect / get_code_connect_suggestions, and generates dry-run-first .figma.ts templates through generate_code_connect_template, enabled libraries can be searched through search_enabled_library_assets and inspected through inspect_enabled_libraries / list_enabled_library_variables, get_metadata reads active-file plugin metadata or hosted REST metadata, get_screenshot renders active-file SVGs or REST image URLs, Design DSL wrappers (inspect_design_system, validate_screen_spec, build_screen, update_screen) plus component usage/prop analytics and database CRUD/portable payload tools are catalogued, build_doc_flow renders both node pages and workspace composition pages (compositionFileId) through the existing composition pipeline, and optional figma_rest_* tools cover Figma REST reads without a plugin session. |

Treat feature alignment by changelog or release tag, not npm name alone.

Ports

One TCP port (BRIDGE_PORT, default 37830): plugin WebSocket, HTTP REST (/api/*), and MCP Streamable HTTP (/mcp) share it. Override with BRIDGE_PORT=3100 npm start if needed, then use the same port in your MCP client and in the plugin Remote Connect overlay.

| On port BRIDGE_PORT | URL (default) | |----------------------|---------------| | Plugin UI | ws://127.0.0.1:37830 | | REST | http://127.0.0.1:37830/api/{status,session,queue,events,tools,capabilities,contract-audit,figma-mcp-parity,figma-mcp-skills-parity,figma-rest-diagnostics,performance-profile,runtime-summary,operator-runbook,ultimate-readiness,log,command,disconnect,workspace-blob} | | Cursor MCP | http://127.0.0.1:37830/mcp |

Optional: shared-secret auth

Set BRIDGE_AUTH_TOKEN in the environment and every /api/*, /mcp, and plugin WebSocket connection must authenticate. HTTP/MCP clients send Authorization: Bearer <token>; the SXL Studio plugin sends the token from the Remote Connect overlay. Requests without the token return 401 BRIDGE_UNAUTHORIZED or a rejected WebSocket handshake. Useful when running Bridge on a shared machine, or behind a local proxy.

BRIDGE_AUTH_TOKEN=s3cret npm start

For live Remote Connect, enter the same token in the plugin Remote Connect overlay. For Git Sync Local Storage, enter the same token in the plugin Sync connection form under Bridge Auth Token. Zero-config mode remains unchanged: leave BRIDGE_AUTH_TOKEN unset and leave the plugin fields empty.

Optional: Figma REST companion

Bridge can also call the Figma REST API directly for read-only hosted context that does not require the plugin to be open:

FIGMA_TOKEN=figd_xxx npm start
# or OAuth/plan token with bearer auth:
FIGMA_ACCESS_TOKEN=xxx FIGMA_AUTH_MODE=bearer npm start

Available MCP tools are figma_rest_diagnose, figma_rest_whoami, figma_rest_get_file_metadata, figma_rest_get_file, figma_rest_get_file_nodes, figma_rest_get_images, figma_rest_get_image_fills, figma_rest_get_file_components, figma_rest_get_file_component_sets, figma_rest_get_file_styles, figma_rest_get_team_components, figma_rest_get_team_component_sets, figma_rest_get_team_styles, figma_rest_get_variables_local, figma_rest_get_variables_published, and figma_rest_search_design_system.

Call figma_rest_diagnose first for token/auth/scopes/permission preflight. HTTP clients can use GET /api/figma-rest-diagnostics?checks=whoami,fileMetadata&fileKey=.... Use the REST tools for known file/team reads, authenticated whoami, REST variables, and known-library search. For Figma MCP-style library discovery, prefer Bridge get_libraries and search_design_system; they combine active-file enabled libraries through Remote Connect with known file/team REST sources when configured. They do not replace official Figma MCP for creating new files or FigJam/Slides asset upload.

For libraries already enabled in the open Figma file, get_libraries and search_design_system are the primary agent-facing tools. Use search_enabled_library_assets for lower-level enabled-library search, inspect_enabled_libraries for raw enabled descriptors, and list_enabled_library_variables for variables in a specific enabled collection. Figma Plugin API cannot enable libraries from code; Bridge reports that limitation in the compatibility tool responses.

For screenshots or rendered node images, use get_screenshot. mode: "plugin-svg" returns inline SVG from active-file nodes or current selection through Remote Connect. mode: "rest-image" returns Figma-hosted PNG/JPG/SVG/PDF URLs for known fileKey/url + nodeIds using the REST Images endpoint.

For metadata, use get_metadata. mode: "plugin" returns active-file selection/page structure or node tree metadata through Remote Connect. mode: "rest" returns hosted file metadata or node metadata for known fileKey/url and optional nodeIds.

For active-file design context, use get_design_context. It bundles SXL codegen/composition JSON, sparse metadata, native variable/style definitions, optional SVG screenshot, and optional local Code Connect suggestions for the current selection or provided node ids. This mirrors the official MCP get_design_context intent as a structured starting point for the agent; it does not claim to be final production code.

For Code Connect template/binding context, use get_context_for_code_connect. It bundles SXL registry/settings, selection status, existing bindings, SXL codegen/composition context, component discovery with props, and local source-file suggestions. It covers the active-file/local-codebase side of the official MCP get_context_for_code_connect workflow; hosted remote-only context remains official Figma MCP companion scope.

For .figma.ts Code Connect template generation, use generate_code_connect_template. It accepts a full SXL CodeConnectBinding or local targets/component names, returns dry-run content/path by default, and writes only when writeFile: true is explicitly passed. Keep includePropertyAttrs off unless you have verified that Figma property names match the code component props.

For variable/style definitions, use get_variable_defs. mode: "selection" is the official-MCP-style route for variables/styles used in the current Figma Design selection; it reads native boundVariables, text segment bindings, style ids, and resolved variable/style definitions through Remote Connect, then adds SXL applied-token metadata as compatibility context. mode: "local" reads active-file local variables/styles; mode: "enabled-libraries" reads variables from libraries already enabled in the open file; mode: "rest" reads known-file REST variable endpoints.

Cursor MCP (recommended)

Add http://127.0.0.1:37830/mcp to .cursor/mcp.json. Start Bridge first (cd Utils/bridge && npm run build && npm start). Then enable Remote Connect in the SXL Studio plugin.

Official Figma MCP (http://127.0.0.1:3845/mcp) reads design context from the file; it does not run SXL Studio plugin commands.

Run locally

cd Utils/bridge
npm install
npm run build
node dist/index.js

If you see EADDRINUSE, pick a free port: BRIDGE_PORT=39999 npm start, then use http://127.0.0.1:39999/mcp in Cursor and set 39999 in the plugin Remote Connect overlay. The plugin remembers the last port locally; the default remains 37830.

The repo .cursor/mcp.json points Cursor at http://127.0.0.1:37830/mcp. Bridge must run before opening Agent chat.

MCP + stdout: the Model Context Protocol uses stdout for JSON-RPC. Do not use console.log in this process (it corrupts the stream). Use console.error for diagnostics.

Health checks

Local health does not require a running Bridge server or Figma plugin. It verifies the local contract audit, local agent workflow routing/planning, and the Ultimate Bridge readiness audit. A healthy build reports PASS; WARN should be reviewed before release, while explicit Figma MCP companion/future scope is listed separately by readiness.

npm run build
npm run health:local
npm run readiness
# installed package alternatives:
sxl-bridge health
sxl-bridge-health
sxl-bridge readiness
sxl-bridge-readiness

Local readiness proves the code/tool surface. It does not prove a live Figma session. To combine local readiness with running HTTP/MCP proof, use:

sxl-bridge-readiness --runtime --url http://127.0.0.1:37830
# package script equivalent:
npm run readiness:runtime

To make the gate fail unless the SXL Studio plugin is connected and live validation passes:

sxl-bridge-readiness --runtime --require-live --suite all
sxl-bridge-readiness --runtime --require-live --suite all --write-canary --cleanup
# non-destructive package script equivalent:
npm run readiness:live

Use --write-canary --cleanup only with explicit approval; it creates a tiny validation frame, verifies the returned rootNodeId, then deletes that same frame.

Runtime smoke checks the running HTTP/MCP surface (/mcp initialize/session/tools-list/tools-call get_libraries + search_design_system zero-config envelopes, get_operator_runbook, list_tools, validate_screen_spec, preview_export_variables, get_figma_mcp_skills_parity, and plan_workflow for Figma Design library discovery routing, resources-list/resources-read for runtime-summary + operator-runbook + figma-mcp-skills-parity, prompts-list/prompts-get for sxl-operator + sxl-generate-design, plus REST status, tools, capabilities, contract-audit, figma-mcp-parity, figma-mcp-skills-parity, performance-profile, runtime-summary, operator-runbook, figma-rest-diagnostics, ultimate-readiness, queue, events, log?source=disk):

sxl-bridge-health --runtime --url http://127.0.0.1:37830

Use --require-plugin when the check must prove an active SXL Studio Remote Connect session:

sxl-bridge-health --runtime --require-plugin --auth-token "$BRIDGE_AUTH_TOKEN"

npm run check includes the local health gate after build. release:check remains the publish dry-run gate and is intentionally separate from the normal local check.

Live workflow smoke

When Figma is open and the SXL Studio plugin has an active Remote Connect session, run the non-destructive workflow smoke:

cd Utils/bridge
npm run workflow:smoke
# installed package alternatives:
sxl-bridge smoke
sxl-bridge-smoke

The workflow is intentionally small but real: GET /api/status → get_plugin_status → find_components → build_mockup { dryRun: true }. It proves that the plugin command path, queue, Remote Connect session, design-system discovery, and Design DSL dry-run are working together.

To write an actual smoke frame into the active Figma file, opt in explicitly:

sxl-bridge-smoke --apply
sxl-bridge-smoke --apply --cleanup

--apply requires writesAllowed=true; in Dev Mode/read-only contexts it fails before touching the canvas. --cleanup is only valid with --apply; it deletes the rootNodeId returned by the smoke frame creation step, so the canary can prove create/delete write access without leaving a frame in the file.

For local agent routing/workflow validation without a running Bridge or Figma session, use:

npm run workflow:agent
# installed package alternative:
sxl-bridge-agent

workflow:agent validates representative RU/EN requests through route_intent, plan_workflow, and preview_workflow. It catches stale routing, missing preflight dependencies, unsafe generated plans, and read-only intents that accidentally plan write tools. readiness prints the Ultimate Bridge requirement audit locally, and health:local includes both the agent workflow gate and readiness gate.

For a broader non-destructive live validation suite, use:

npm run workflow:validate
# installed package alternatives:
sxl-bridge validate
sxl-bridge-live
sxl-bridge-live --suite all --write-canary --cleanup

workflow:validate checks the running Bridge REST + MCP surface plus the connected plugin command path. The default baseline suite covers status, /mcp initialize/session/tools-list/tools-call get_libraries + search_design_system zero-config envelopes, get_operator_runbook, list_tools, validate_screen_spec, preview_export_variables, get_figma_mcp_skills_parity, and plan_workflow for Figma Design library discovery routing, resources-list/resources-read for runtime-summary + operator-runbook + figma-mcp-skills-parity, prompts-list/prompts-get for sxl-operator + sxl-generate-design, ultimate readiness, performance profile, operator runbook, tool catalogue, token/config reads, variable/style reads, component discovery, and a Design DSL dry-run. Readiness/performance endpoints are status-aware: fail fails the suite, while warn is surfaced without changing the non-destructive behavior. --suite all also verifies Code Connect registry/settings/selection status, selection variable definitions, dry-run .figma.ts template generation, database list commands, database payload export + import dry-run, variable/style spec dry-runs, dedupe dry-runs, variable/style coverage summary + paginated detail, variable/style coverage dry-run apply previews, unused variable/style scans, composition list + bulk dry-run + drift audit, component usage summary/detail pagination, component prop usage summary/detail pagination, and Doc Builder build_doc_flow dry-run. --write-canary --cleanup is the explicit write-path proof: it creates a tiny validation frame, verifies the returned rootNodeId, then deletes that same node. It requires an active Remote Connect session and exits non-zero when the plugin is not connected.

MCP configuration (Cursor)

Example .cursor/mcp.json:

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

stdio variant (if preferred):

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

HTTP API examples

Requires the plugin open in Figma, Remote Connect enabled, and Bridge running.

Status

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

Returns ports, mcpStreamableHttp, session, queueLength, currentCommand, queue, runtime, telemetry, and authEnabled. runtime.health is one of ready, busy, degraded, or disconnected; runtime.issues names the actionable condition. telemetry is sanitized and exposes counts/last failure metadata without payload values.

Workspace blobs (Git Sync Local Storage)

Bridge 1.7.0+ persists large workspace payloads on the host disk when the plugin enables Local Storage on a Git Sync connection (token/dataset bodies leave Figma clientStorage; Bridge holds UTF-8 blobs keyed per workspace).

Default root: OS cache directory from env-paths (sxl-studio-bridge) + subdirectory workspace-blobs. Override entirely with SXL_BRIDGE_WORKSPACE_BLOB_ROOT (absolute path).
workspaceId: 64-character lowercase hex (SHA-256 of the plugin workspace key).
key: safe fragment [\w.-]{1,240} (plugin prefixes such as TOKEN_CONTENT_<fileId>, dataset_content_<id>).

Endpoints (same BRIDGE_AUTH_TOKEN / Authorization: Bearer rules as other /api/*; no Remote Connect WebSocket required):

# Read blob (404 if missing)
curl -s 'http://127.0.0.1:37830/api/workspace-blob?workspaceId=<64hex>&key=TOKEN_CONTENT_tf_1'

# Write / replace blob (JSON body; data is a UTF-8 string)
curl -s -X POST http://127.0.0.1:37830/api/workspace-blob \
  -H "Content-Type: application/json" \
  -d '{"workspaceId":"<64hex>","key":"TOKEN_CONTENT_tf_1","data":"{\"$schema\":\"...\"}"}'

# Delete blob
curl -s -X DELETE 'http://127.0.0.1:37830/api/workspace-blob?workspaceId=<64hex>&key=TOKEN_CONTENT_tf_1'

Successful GET returns JSON { "ok": true, "encoding": "utf8", "data": "<string>" }.

Tool catalogue

curl -s 'http://127.0.0.1:37830/api/tools?category=tokens'
curl -s 'http://127.0.0.1:37830/api/tools?devModeReadableOnly=true'

Returns entries { name, category, description, requiresDesignMode, requiresComposition }. MCP clients can call the equivalent list_tools meta-tool.

Current entries also include routing metadata where available: commandType, execution, pluginCommandTypes, aliases, naturalLanguageIntents, dryRunSupported, returnsLargeData, preferredBefore, preferredAfter, and timeoutMs.

Workflow routing

For broad natural-language requests, call route_intent first. For multi-step work, call plan_workflow, then validate the proposed sequence with preview_workflow before executing write tools. The preview checks unknown tools, missing or misordered get_plugin_status, missing or misordered design-system discovery, missing or misordered dry-run gates, and missing/misordered preflight tools declared by preferredAfter.

For token export, this means preview_export_variables should precede export_variables. For Figma Design library discovery/search, use Bridge get_libraries / search_design_system. For official Figma MCP companion scope such as new-file creation, FigJam/Slides, diagrams, or hosted Code Connect repository context, the planner adds an explicit handoff step; avoid Bridge write tools unless the user narrows the task back to SXL/active-file Figma Design work.

Capability matrix

MCP clients should call the get_capability_matrix tool. It returns the catalogue-derived matrix for agent routing and contract audits: execution mode, plugin command mapping, mode requirements, dry-run/large-data flags, and effective Bridge timeout. HTTP clients should use GET /api/capabilities, which is sourced from the same catalogue as GET /api/tools.

curl -s 'http://127.0.0.1:37830/api/capabilities?category=mockup'

Contract audit

MCP clients should call get_contract_audit before release checks or when connecting a new agent/client. It verifies the current Bridge surface: required meta tools, recipe references, schema entrypoints, workflow gates, tool execution mapping, plugin command declarations, Remote Connect whitelist coverage and handler-path coverage when the plugin source is available, and timeouts. HTTP clients can use:

curl -s 'http://127.0.0.1:37830/api/contract-audit'

The response is { ok, status, summary, requiredSurface, findings }; release checks should treat status: "fail" as blocking. The CLI health gate uses the same contract audit locally, so npm run check catches stale catalogue/schema/recipe/Remote Connect whitelist/handler regressions before publish.

Figma MCP parity

Bridge exposes a machine-readable parity map between official Figma MCP tools and SXL Bridge/SXL Studio capabilities:

curl -s 'http://127.0.0.1:37830/api/figma-mcp-parity'

MCP clients can call get_figma_mcp_parity or attach sxl://agent/figma-mcp-parity. The matrix is intentionally explicit about companion requirements: Bridge plugin tools cover enabled-library search and active-file metadata in the open file, Bridge REST tools cover authenticated whoami and known file/team library reads when a Figma REST token is configured, get_libraries / search_design_system provide Figma MCP-compatible Figma Design library discovery/search over active-file and known REST sources, get_design_context covers active-file SXL-native design context, get_metadata covers hosted file/node metadata, get_variable_defs covers selection/local/enabled-library/known-file variable definitions, get_screenshot covers active-file SVG and known-node REST image rendering, Bridge upload_assets covers Figma Design image insertion, get_context_for_code_connect bundles active-file SXL Code Connect context, generate_code_connect_template generates dry-run-first local .figma.ts templates, and get_code_connect_suggestions ranks local source-file candidates before codeconnect_save_binding. Remote-only hosted Figma MCP capabilities such as new-file creation, hosted Code Connect repository context, and FigJam/Slides asset upload cannot be honestly implemented by a local Figma Design plugin Bridge.

Bridge also exposes skill-level parity for the current official Figma MCP skills:

curl -s 'http://127.0.0.1:37830/api/figma-mcp-skills-parity'

MCP clients can call get_figma_mcp_skills_parity or attach sxl://agent/figma-mcp-skills-parity. It maps the current official Figma MCP skills figma-use, figma-use-figjam, figma-use-slides, figma-swiftui, figma-code-connect, figma-create-new-file, figma-generate-diagram, figma-generate-library, and figma-generate-design to SXL recipes/resources/tools. The matrix keeps companion scope and agent-side codebase work explicit instead of pretending every official skill is a single Bridge plugin command.

route_intent and plan_workflow are skill-aware. Current official FigJam, Slides, new-file, and diagram skills route to the official Figma MCP companion. figma-swiftui uses Bridge for active-file design context and Code Connect hints, then agent-side Swift edits. Older client aliases remain supported: figma-implement-design routes to sxl-implement-design, figma-create-design-system-rules routes to sxl-generate-library, and figma-code-connect-components routes to sxl-code-connect.

For Figma Design image insertion, Bridge exposes upload_assets. It accepts PNG, JPG/JPEG, GIF, and WebP URLs or base64 payloads, enforces Figma MCP's 10MB-per-asset limit, supports dryRun, and applies images through the plugin's set_image_fill handler. It fills an existing nodeId when provided; otherwise it creates image rectangles. FigJam/Slides asset upload remains official Figma MCP companion scope.

Performance profile

MCP clients should call get_performance_profile before broad audits, screen generation, bulk export/apply flows, or when optimizing agent behavior. It classifies every catalogued tool as local, standard, summary, paginated-detail, write-preview, or long-running, then exposes target budgets, large-data rules, dry-run-first rules, destructive-write warnings, and recent audit timings.

curl -s 'http://127.0.0.1:37830/api/performance-profile?auditLimit=50'

Resource clients can attach sxl://agent/performance-profile. Treat find_* / large-data tools as paginated detail, use analyze_* / audit_* summaries before details, and call dry-run-capable write tools in preview mode before committing.

Runtime summary

MCP clients should call get_operator_runbook as the start-here workflow chooser, then get_bridge_runtime_summary before heavy workflows. HTTP clients can use:

curl -s 'http://127.0.0.1:37830/api/operator-runbook'
curl -s 'http://127.0.0.1:37830/api/runtime-summary'

The runbook chooses the workflow, tools, dry-run gates, and companion handoff. The runtime summary reports plugin connection, current/queued commands, recent event/audit failures, auth state, MCP URL, and actionable recommendations. It is intentionally compact so agents can decide whether to proceed, wait, inspect logs, or ask the operator to open Remote Connect.

Ultimate readiness audit

MCP clients can call get_ultimate_readiness before release or before claiming Bridge is complete. HTTP clients can use:

curl -s 'http://127.0.0.1:37830/api/ultimate-readiness'

Local operators can run the same audit without a running Bridge server:

npm run readiness
sxl-bridge readiness
sxl-bridge-readiness --json
npm run readiness:runtime
npm run readiness:live

The audit maps the original Ultimate Bridge plan to concrete requirement rows: contract surface, SXL skills, Design DSL, component analytics, database tools, variables/styles, compositions, documentation, Code Connect, production safety, official Figma MCP tool parity, and official Figma MCP skill parity. The contract row includes Remote Connect whitelist and handler-path evidence when the plugin source is available. It deliberately keeps companion/future Figma MCP scope explicit instead of pretending the plugin API can create new files or handle FigJam/Slides. Add --runtime to report running Bridge HTTP/MCP proof next to local readiness; add --require-live when release sign-off must fail unless an active Remote Connect plugin session passes live validation.

Large-data response mode

MCP tools marked returnsLargeData accept Bridge response controls:

bridgeResponseMode: "auto" (default) returns the full payload while it fits the MCP response budget, otherwise returns a compact envelope.
bridgeResponseMode: "summary" always returns { bridgeLargeData, summary, preview } with counts, scalar fields, pagination hints, and a small item preview.
bridgeResponseMode: "full" explicitly returns the full payload. Use it only when the user needs exact data.

Bridge strips these control fields before forwarding the command to the plugin. Raw HTTP /api/command remains an escape hatch for clients that intentionally want the exact plugin result.

Destructive confirmation gate

Bridge blocks destructive plugin commands unless the caller passes confirmDestructive: true in the top-level payload. This applies to delete_*, remove_*, reset_*, git_hard_pull, detach_instance, flatten_nodes, boolean_operation, and export_variables when deleteOrphans or allowDestructiveReorder is enabled. Use preview_export_variables before token export; it reports the exact payload, effective plugin defaults, risk flags, and whether confirmation is required without touching Figma.

curl -s http://127.0.0.1:37830/api/command \
  -H 'Content-Type: application/json' \
  -d '{"commandType":"delete_nodes","payload":{"nodeIds":["1:2"],"confirmDestructive":true}}'

MCP tools expose the same confirmDestructive field where their schema is strict. Bridge strips confirmDestructive and destructiveReason before sending the payload to the plugin, so Remote Connect handlers do not need to accept those fields. Prefer dry-run/preview tools first when they exist.

Audit trail

curl -s 'http://127.0.0.1:37830/api/log?limit=50'
curl -s 'http://127.0.0.1:37830/api/log?source=disk&limit=50'

source=memory (default) returns the in-process ring buffer. source=disk reads persisted JSONL entries from the OS cache directory (env-paths, product id sxl-studio-bridge, subdir audit) unless SXL_BRIDGE_AUDIT_ROOT is set. Entries contain only sanitized command metadata: commandType, status, durationMs, payloadKeys, idempotencyKey, and timestamp fields. Payload values are never stored.

MCP clients can call get_bridge_audit_log with { source: "memory" | "disk", limit }.

Queue snapshot

curl -s 'http://127.0.0.1:37830/api/queue'

Live command queue snapshot: current, queued, and immediate commands with commandId, commandType, status, timings, and payloadKeys. Payload values are never exposed.

Command events

curl -s 'http://127.0.0.1:37830/api/events?limit=100'
curl -s 'http://127.0.0.1:37830/api/events?commandId=<command-id>'

Sanitized lifecycle/progress timeline: queued, started, completed/failed, timeout/cancel events, and plugin progress events when the plugin emits them. Events include ids, status, timings, payloadKeys, and detailKeys; payload/detail values are never exposed.

Read token file (after `list_token_files`)

curl -s -X POST http://127.0.0.1:37830/api/command \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $BRIDGE_AUTH_TOKEN" \
  -H "Idempotency-Key: 01HXYZ1234" \
  -d '{"commandType":"get_token_file_content","payload":{"fileId":"tf_..."}}'

Repeat requests with the same Idempotency-Key (within 10 minutes) return the cached response without touching the plugin — safe for retries.

Save token file (upsert)

curl -s -X POST http://127.0.0.1:37830/api/command \
  -H "Content-Type: application/json" \
  -d '{
    "commandType": "save_token_file",
    "payload": { "name": "buttons", "folder": "components", "content": "{\"$type\":\"composition\"}" }
  }'

If a file with that name+folder exists, it is updated. Otherwise it is created.

Export composition JSON from current selection

curl -s -X POST http://127.0.0.1:37830/api/command \
  -H "Content-Type: application/json" \
  -d '{"commandType":"export_composition_json","payload":{}}'

Optional payload.nodeId selects a specific node instead of the first selected node.

Typed errors

Failures return a structured envelope:

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

Known codes: EDITOR_MODE_READONLY, DESTRUCTIVE_CONFIRMATION_REQUIRED, BRIDGE_TIMEOUT, BRIDGE_CANCELLED, BRIDGE_UNAUTHORIZED, BRIDGE_ERROR. MCP tools decode the envelope before returning to the agent.

MCP tools (summary)

Registered in src/mcp-factory.ts via tools/*.ts:

Diagnostics / meta: get_plugin_status, is_dev_mode, get_selection_summary, get_drift_status, get_operator_runbook, route_intent, plan_workflow, preview_workflow, list_tools, get_capability_matrix, get_contract_audit, get_figma_mcp_parity, get_performance_profile, get_bridge_audit_log, get_ultimate_readiness.
Tokens / workspace: list_token_files, get_token_file_content, save_token_file (upsert), create_token_file, delete_token_file, move_token_file, rename_token_file, get_tokens_config, save_tokens_config, preview_export_variables (read-only export preflight), export_variables, reset_diff*, reapply_token_bindings, cross_file_sync_*, get_applied_tokens.
Composition: export_composition_json, get_codegen, list_compositions, generate_composition, apply_composition, preview_composition, check_composition_linked, inspect_selection.
Variables: get_variables, create_variable_collection, create_variable, bind_variable, rename_variable, delete_variable, rename_variable_collection, delete_variable_collection, add_variable_mode, remove_variable_mode, rename_variable_mode, set_variable_mode_value, set_variable_scopes, set_variable_code_syntax, plus batch ops batch_create_variables / batch_set_variable_values / batch_delete_variables / batch_bind_variables.
Variables orchestration (Phase B, Bridge 1.6.0+): import_variable_spec (idempotent bulk create / update with aliases, dryRun), analyze_variable_order (read-only ordering diff), dedupe_variables (merge duplicates, dry-run by default; canvas write only with apply: true), rebind_variable_aliases (bulk alias rewrite, dryRun), apply_coverage_suggestions (audit suggestions → real bindings, dry-run by default).
Styles: get_local_styles, create_paint_style, create_text_style, create_effect_style, set_text_style, set_effect_style, set_stroke_style, set_fill_style, import_style_by_key.
Styles orchestration (Phase C, Bridge 1.6.0+): import_style_spec (idempotent bulk create / update of Paint / Text / Effect styles, dryRun), dedupe_styles (merge duplicates byName | bySignature, dry-run by default; canvas write only with apply: true), rebind_style_consumers (bulk styleId rewrite on consumer nodes, dryRun), audit_style_drift (READ-ONLY drift between local Paint styles and Variables / expectations[]), apply_style_coverage_suggestions (Phase A find_style_coverage_misses → real setStyleId* writes, dry-run by default).
Mockup-from-DesignSystem / Design DSL (Phase D): inspect_design_system (READ-ONLY aggregate: components/props, variables, styles, token config, composition index), validate_screen_spec, build_screen, update_screen, find_components, build_mockup, apply_mockup_dataset. Prefer inspect_design_system → validate_screen_spec/build_screen dryRun → build_screen/update_screen for full screens; keep build_mockup as the low-level compatible DSL. Payload contract is exposed at sxl://agent/schemas/design-dsl-v1. Replaces hand-rolled use_figma { figma.createInstance(...).setProperties(...) } loops.
Figma REST companion: figma_rest_diagnose, figma_rest_whoami, figma_rest_get_file_metadata, figma_rest_get_file, figma_rest_get_file_nodes, figma_rest_get_images, figma_rest_get_image_fills, figma_rest_get_file_components, figma_rest_get_file_component_sets, figma_rest_get_file_styles, figma_rest_get_team_components, figma_rest_get_team_component_sets, figma_rest_get_team_styles, figma_rest_get_variables_local, figma_rest_get_variables_published, figma_rest_search_design_system. Bridge-local, read-only, no Remote Connect session required; use FIGMA_TOKEN / FIGMA_ACCESS_TOKEN. The Figma MCP-compatible get_libraries / search_design_system tools can orchestrate these REST reads together with active-file plugin sources.
Compositions orchestration (Phase E, Bridge 1.6.0+): bulk_generate_compositions (bulk generate / apply of composition files in one MCP call; filters fileIds | names | prefix; operation: auto | generate | apply; per-item error isolation; dryRun-aware), audit_composition_drift (READ-ONLY drift detector between workspace composition files and tracked Figma components; statuses linked | unlinked | drift | missing; Dev-Mode safe). Replaces hand-rolled for-of loops over generate_composition / apply_composition and per-file check_composition_linked polling.
Data / nodes: database CRUD (list_datasets, get_dataset, save_dataset, delete_dataset, list_assets, get_asset, save_asset, delete_asset, list_mappings, get_mapping, save_mapping, delete_mapping; save/delete support dryRun preview), portable database backup/restore (export_database_payload, import_database_payload; import defaults to dryRun and requires overwrite confirmation for existing IDs), mapping apply/generate preflights (apply_mapping, apply_all_mappings, generate_instances; all support dryRun preview before writing, and apply/count/generate workflows accept explicit targetNodeIds as deterministic selection roots), design-context orchestration (get_design_context), variable/style definition orchestration (get_variable_defs), Figma MCP-compatible library tools (get_libraries, search_design_system), enabled-library search/read tools (search_enabled_library_assets, inspect_enabled_libraries, list_enabled_library_variables), get_metadata, get_screenshot, count_apply_targets, apply_image, upload_assets (dry-run image URL/base64 upload into Figma Design), get_code_connect_suggestions (local binding candidates), plus direct node helpers in data.ts / figma-nodes.ts (set_node_fill_variable, create_rectangle, set_auto_layout, duplicate_subtree, create_component_instance, apply_documentation_payload, extended create_frame / create_text).
Git: git_pull, git_hard_pull, git_push.
Audit analytics: variable/style usage and coverage tools plus component analytics (analyze_component_usage, find_component_usages, analyze_component_prop_usage, find_component_prop_usages).
Audit remediation: coverage audits are read-only; use apply_coverage_suggestions / apply_style_coverage_suggestions in preview mode before committing fixes.
Orchestration: generate_code_from_url, compose_from_url, document_component, index_icons_for_export (read-only icon index: COMPONENT + COMPONENT_SET variants with page/section metadata), build_scenario_from_md, build_doc_flow (node pages or compositionFileId pages rendered through the composition pipeline).

MCP Resources

| URI | Contents | |-----|----------| | sxl://figma/status | Plugin status snapshot | | sxl://figma/selection | Current Figma selection | | sxl://tokens/config | Raw config.json | | sxl://tokens/files | Token file index | | sxl://tokens/files/{fileId} | Raw token file body | | sxl://compositions/index | Composition JSON index | | sxl://agent/operator-runbook | Start-here workflow chooser: preflight, safety rules, common SXL/Figma routes, dry-run gates, and live-readiness checks | | sxl://agent/recipes/index | Intent router (start here) | | sxl://agent/recipes/{sxl-use,sxl-implement-design,sxl-generate-design,sxl-generate-library,sxl-code-connect,sxl-audit,sxl-doc-builder,sxl-data-apply-mapping,sxl-data-apply-all,sxl-data-generate-instances,sxl-database-transfer,figma-mcp-companion,doc-tokens,doc-component,doc-composition,doc-flow,doc-spec-v2,template-discovery,variable-palette,compose-with-variables,scenario-from-markdown,variable-usage,audit-coverage,find-unused,bulk-variables,auto-bind-from-audit,bulk-styles,style-drift,mockup-builder,bulk-compositions,composition-drift} | SXL skills + SXL database/data workflows + official Figma MCP companion routing + Doc Builder + audit + Phase B + Phase C + Phase D + Phase E orchestration recipes | | sxl://agent/figma-mcp-parity | Official Figma MCP tool → SXL Bridge/SXL Studio equivalent / companion / future scope map | | sxl://agent/figma-mcp-skills-parity | Official Figma MCP skill → SXL Bridge recipes/resources/tools / companion / agent-codebase-work map | | sxl://agent/performance-profile | Command budgets, large-data/dry-run policy, destructive-write warnings, and recent audit timings | | sxl://agent/runtime-summary | Plugin connection, queue pressure, recent failures, MCP URL, auth flag, and recommendations | | sxl://agent/ultimate-readiness | Requirement-by-requirement Ultimate Bridge Toolkit readiness audit |

Cursor / Claude can attach these as context without calling tools.

MCP Prompts

Bridge also registers prompt templates for MCP clients that support prompts/list / prompts/get:

sxl-router
sxl-operator
sxl-use
sxl-implement-design
sxl-generate-design
sxl-generate-library
sxl-code-connect
sxl-audit
sxl-doc-builder
figma-mcp-companion

Each prompt returns a concise workflow instruction with the relevant sxl://agent/recipes/* resource, preferred tools, forbidden anti-patterns, dry-run gates, and done criteria. figma-mcp-companion is the explicit handoff prompt for official Figma MCP remote-only scopes such as new-file creation, FigJam/Slides, and diagrams; Figma Design library discovery should use Bridge get_libraries / search_design_system. Use prompts when the MCP client can inject prompt templates directly; use resources when the client prefers attachable context.

Dev Mode support

| Context | Reads | Canvas writes | Token/config/git writes | |---------|-------|---------------|--------------------------| | Figma Design | ✔︎ | ✔︎ | ✔︎ | | Figma Dev Mode (UI, mode: "default") | ✔︎ | ✘ (plugin returns EDITOR_MODE_READONLY) | ✔︎ | | Figma Dev Mode (Inspect → Code sandbox) | read-only codegen callback; Remote Connect unavailable | ✘ | ✘ |

get_codegen (Bridge) and the Dev Mode Inspect → Code panel (plugin) share the exact same routeCodegenGenerate pipeline. Output is byte-identical.

Development

npm run test    # Vitest
npm run build   # tsc → dist/
npm run lint    # tsc --noEmit
npm run check   # lint + build + test
npm run readiness # local Ultimate Bridge requirement audit
npm run readiness:runtime # local readiness + running Bridge HTTP/MCP proof
npm run readiness:live # strict live Figma E2E proof; requires Remote Connect
npm run release:check # check + npm publish --dry-run
npm run release:check:live # check + strict live readiness gate

Publishing to npm

See docs/npm-publish.md. The package ships only dist/ and README.md (files in package.json). Example and monorepo-only scripts live under examples/.

Examples (monorepo only)

See examples/README.md for how to write consumer scripts against POST /api/command without coupling the npm package to your design-system paths.