figma-prototype-mcp 0.30.2 → 0.31.0

package/README.md

@@ -27,6 +27,12 @@ npx figma-prototype-mcp
 { "mcpServers": { "figma-prototype": { "url": "http://localhost:3000/sse" } } }
 ```
 
+**Claude Desktop** has no native SSE support, so point it at the server over stdio — it launches the server for you (no separate `npx figma-prototype-mcp` needed):
+```json
+{ "mcpServers": { "figma-prototype": { "command": "npx", "args": ["-y", "figma-prototype-mcp", "--stdio"] } } }
+```
+In `--stdio` mode the client starts the server and talks to it over stdio; the server still hosts the Figma plugin WebSocket on `ws://localhost:3000/ws`. Don't also run a separate SSE server (`npx figma-prototype-mcp`) on the same port — pick one. (Claude Code can use either the SSE `url` above or this stdio command.)
+
 **4. Wire it by talking.** In a file with ≥2 frames, ask Claude:
 > "Home의 버튼을 누르면 Detail 화면으로 가게 해줘"
 > *(or "when the button on Home is clicked, navigate to Detail")*
@@ -166,9 +172,14 @@ To bypass the preset system (e.g. for `MOVE_IN`/`PUSH`/`SLIDE_*` directional tra
 | `create_reactions` | **Write**: batch create prototype reactions. Each connection's `action` picks between Navigate To (action.type=navigate, targetFrameId), Scroll To (scroll, targetNodeId), Open Overlay (overlay, targetFrameId), Close Overlay (close, no destination), Back (back, no destination), Open URL (url, url, openInNewTab?), Swap Overlay (swap_overlay, targetFrameId), and Change To (change_to, targetVariantId — switch a component instance to a sibling variant). Triggers: string shortcuts `ON_CLICK` (default) / `ON_HOVER` / `ON_PRESS` / `AFTER_TIMEOUT` (with top-level `afterTimeoutSeconds`); object form additionally supports `{type:"ON_DRAG"}`, `{type:"MOUSE_UP"\|"MOUSE_DOWN", delay?}`, `{type:"MOUSE_ENTER"\|"MOUSE_LEAVE", delay?, deprecatedVersion?}`, `{type:"ON_KEY_DOWN", device, keyCodes}`, `{type:"ON_MEDIA_HIT", mediaHitTime}`, `{type:"ON_MEDIA_END"}`, and a self-contained `{type:"AFTER_TIMEOUT", timeout}`. Transitions: string shortcuts `INSTANT` / `DISSOLVE` / `SMART_ANIMATE`, simple object form (DISSOLVE/SMART_ANIMATE/SCROLL_ANIMATE + duration + easing), and directional form (`MOVE_IN`/`MOVE_OUT`/`PUSH`/`SLIDE_IN`/`SLIDE_OUT` × `direction` LEFT/RIGHT/TOP/BOTTOM × optional `matchLayers`). NODE actions (navigate / scroll / overlay / swap_overlay) also accept optional `resetScrollPosition?: boolean` — `false` to keep the destination frame's previous scroll position, `true` to reset to top. Omit to use Figma's runtime default. Each succeeds or fails independently; scroll targets without a scrollable ancestor return a `warning`. A `conditional` action wraps an IF/ELSE: `{ type: "conditional", condition, then: [action, ...], else?: [action, ...] }` where `condition` is a single comparison `{ variable, operator: "==" \| "!=" \| "<" \| "<=" \| ">" \| ">=", value }` or a one-level compound `{ all: [comparison, ...] }` (AND) / `{ any: [comparison, ...] }` (OR) over ≥2 comparisons. The `variable` is the name of a local Figma variable (BOOLEAN/FLOAT/STRING); plugin resolves to id. Nested conditionals are rejected. Branches use any of the 7 non-conditional action types. Variable mutations: `set_variable` action assigns a literal (`{ type: "set_variable", variable, value }`; value is boolean/number/string matching the variable's resolvedType; valid both at top-level and inside conditional then/else); `toggle_variable` action flips a BOOLEAN variable (`{ type: "toggle_variable", variable }`; top-level only — desugars to CONDITIONAL+2 SET_VARIABLE; nested-rejected to preserve the no-nesting rule). Both reference local Figma variables by name. `list_reactions` round-trips toggle_variable via pattern detection on the stored CONDITIONAL. COLOR variables accept hex string values (`"#RRGGBB"` or `"#RRGGBBAA"` — case insensitive); the plugin validates format and parses to Figma's RGB(A) shape internally. `list_reactions` echoes COLOR `value` back as a hex string. Conditional comparison against COLOR variables is rejected (use BOOLEAN/FLOAT/STRING for conditions). |
 | `list_reactions` | Inspect existing reactions on a node |
 | `get_prototype_flow` | **Read** the whole prototype interaction graph of a page in one call: frames (with `isStartFrame`) + every wired interaction (`frameId`, `sourceNodeId`, `trigger`, decoded `action` — same shape as `list_reactions`). Page-scoped (optional `pageId`); `limit` caps results. Use to see what is already wired before adding more. |
+| `export_interactions` | Export the wired interactions of designated **completed screens** as a canonical, framework-agnostic **JSON spec** for developer handoff. Input `{ screens: string[] (frame node IDs), pageId? }`. Each interaction is a typed action (navigate / scrollTo / openOverlay / swapOverlay / closeOverlay / back / openUrl / setVariable / toggleVariable / changeVariant / conditional); unmappable actions are flagged in `unsupported[]`, unknown screen IDs in `missingScreens[]`. Read-only — developers (or Claude) derive framework code from the JSON. |
 | `clear_reactions` | Remove reactions from one or more nodes |
 | `set_frame_scroll` | **Write**: configure scroll-related properties on one or more FRAME nodes. Each entry accepts optional `direction` (`NONE` / `HORIZONTAL` / `VERTICAL` / `BOTH`) and/or optional `fixedChildren` (number of top-most children to fix when scrolling — Figma's sticky-header model fixes the first N children in z-order; layer panel order matters). At least one of `direction` or `fixedChildren` must be provided per entry. Each frame succeeds or fails independently; response includes `applied` array naming which fields were set. |
 
+### Developer handoff: export interactions as JSON
+
+`export_interactions` turns the prototype interactions you wired into a **language-neutral JSON spec** — a faithful map of "what each control does" (trigger → actions) for the screens you designate as done. It is intentionally framework-agnostic: it describes the behavior (navigate, set variable, conditional, …) using Figma's own vocabulary, and a developer (or Claude, on request) generates React/Vue/state-machine code from it. It does NOT emit framework code or visual UI — pair it with Figma Dev Mode / Code Connect for the UI.
+
 ## Troubleshooting
 
 | Symptom | Cause / fix |
@@ -180,6 +191,7 @@ To bypass the preset system (e.g. for `MOVE_IN`/`PUSH`/`SLIDE_*` directional tra
 | A tool call hangs, then the client falls back to another tool | A **second MCP client** connected and evicted the first (single-active, newest-wins). Keep one client per server; reconnect the one you want to use. A stdio↔SSE bridge (e.g. supergateway) may not surface the eviction — the server logs `a second MCP client connected — evicted the prior SSE connection`. |
 | `get_canvas_overview` shows `frames: []` but the page clearly has frames | `get_canvas_overview` lists only **top-level** frames, so frames nested inside a **Section** don't appear. `get_prototype_flow` lists frames recursively (Sections included) and is the better read for a populated page; pass `pageId` if you're not on the intended page. |
 | Cryptic crash on startup (syntax / module errors) | Check your Node version — this needs **Node ≥ 18** (`node -v`). |
+| Client shows a zod `invalid_union` error mentioning `error.code` expected number, or `ECONNREFUSED ...:3000`, at startup | Your `:3000` server isn't running. For **Claude Desktop**, use the `--stdio` command config (it launches the server for you). For **Claude Code** over SSE, start `npx figma-prototype-mcp` first. (A stdio↔SSE bridge like supergateway reports a missing server as this malformed frame.) |
 
 ## Known limitations
 

package/dist/server/index.js

@@ -1,10 +1,12 @@
 #!/usr/bin/env node
 
-// src/server/index.ts
-import express from "express";
-import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+// src/server/run.ts
+import http from "http";
 import { readFileSync } from "fs";
 import { fileURLToPath } from "url";
+import express from "express";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 
 // src/server/sessions.ts
 import { randomUUID } from "crypto";
@@ -146,9 +148,9 @@ var PluginSession = class {
 // src/server/plugin-ws.ts
 import { WebSocketServer } from "ws";
 var PLUGIN_PATH = "/ws";
-function attachPluginWebSocket(httpServer2, session2) {
+function attachPluginWebSocket(httpServer, session) {
   const wss = new WebSocketServer({ noServer: true });
-  httpServer2.on("upgrade", (req, socket, head) => {
+  httpServer.on("upgrade", (req, socket, head) => {
     if (req.url === PLUGIN_PATH) {
       wss.handleUpgrade(req, socket, head, (ws) => wss.emit("connection", ws, req));
     } else {
@@ -156,7 +158,7 @@ function attachPluginWebSocket(httpServer2, session2) {
     }
   });
   wss.on("connection", (ws) => {
-    session2.setActive(ws);
+    session.setActive(ws);
     ws.on("message", (raw) => {
       let msg;
       try {
@@ -165,15 +167,61 @@ function attachPluginWebSocket(httpServer2, session2) {
         return;
       }
       if (typeof msg === "object" && msg !== null && msg.type === "response") {
-        session2.handleResponse(msg);
+        session.handleResponse(msg);
       }
     });
-    ws.on("close", () => session2.clearActive(ws));
-    ws.on("error", () => session2.clearActive(ws));
+    ws.on("close", () => session.clearActive(ws));
+    ws.on("error", () => session.clearActive(ws));
   });
   return wss;
 }
 
+// src/server/history.ts
+import { randomUUID as randomUUID2 } from "crypto";
+var HistoryStore = class {
+  buffer = [];
+  capacity;
+  constructor(capacity = 10) {
+    this.capacity = capacity;
+  }
+  record(tool, input, result) {
+    if (result.successCount === 0) return null;
+    const entry = {
+      historyId: randomUUID2(),
+      timestamp: Date.now(),
+      tool,
+      input,
+      result
+    };
+    this.buffer.push(entry);
+    if (this.buffer.length > this.capacity) this.buffer.shift();
+    return entry;
+  }
+  /**
+   * Return up to `count` most-recent entries in oldest-to-newest order
+   * (so `arr.at(-1)` is the most recent). Empty array if count < 1.
+   * Clamped to `buffer.length` when count exceeds it.
+   */
+  getLast(count = 1) {
+    if (count < 1) return [];
+    return this.buffer.slice(-Math.min(count, this.buffer.length));
+  }
+  size() {
+    return this.buffer.length;
+  }
+};
+function summarizeResult(raw) {
+  if (typeof raw !== "object" || raw === null) {
+    return { successCount: 0, errorCount: 0, warningCount: 0 };
+  }
+  const r = raw;
+  return {
+    successCount: typeof r.successCount === "number" ? r.successCount : 0,
+    errorCount: typeof r.errorCount === "number" ? r.errorCount : 0,
+    warningCount: typeof r.warningCount === "number" ? r.warningCount : 0
+  };
+}
+
 // src/server/tools.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import {
@@ -217,8 +265,12 @@ var GetCanvasOverviewInput = z.object({
 });
 var GetPrototypeFlowInput = z.object({
   pageId: z.string().optional(),
-  limit: z.number().int().positive().max(2e3).default(500)
+  limit: z.number().int().positive().max(5e3).default(500)
 });
+var ExportInteractionsInput = z.object({
+  screens: z.array(z.string()).min(1),
+  pageId: z.string().optional()
+}).strict();
 var FindNodesInput = z.object({
   query: z.string().min(1),
   nodeTypes: z.array(z.string()).optional(),
@@ -834,49 +886,99 @@ function compileProtoConditional(input) {
   return { connections, replaceExisting: input.replaceExisting };
 }
 
-// src/server/history.ts
-import { randomUUID as randomUUID2 } from "crypto";
-var HistoryStore = class {
-  buffer = [];
-  capacity;
-  constructor(capacity = 10) {
-    this.capacity = capacity;
+// src/server/interaction-spec.ts
+function mapCondition(c) {
+  if (c && typeof c === "object") {
+    if (Array.isArray(c.all)) return { all: c.all.map(mapCondition) };
+    if (Array.isArray(c.any)) return { any: c.any.map(mapCondition) };
+    if ("variable" in c && "operator" in c) {
+      return { variable: c.variable, operator: c.operator, value: c.value };
+    }
+    if ("raw" in c) return { raw: c.raw };
   }
-  record(tool, input, result) {
-    if (result.successCount === 0) return null;
-    const entry = {
-      historyId: randomUUID2(),
-      timestamp: Date.now(),
-      tool,
-      input,
-      result
-    };
-    this.buffer.push(entry);
-    if (this.buffer.length > this.capacity) this.buffer.shift();
-    return entry;
+  return { raw: c };
+}
+function mapAction(a, source, unsupported) {
+  if (!a || typeof a !== "object") {
+    unsupported.push({ source, reason: "non-object action", raw: a });
+    return null;
   }
-  /**
-   * Return up to `count` most-recent entries in oldest-to-newest order
-   * (so `arr.at(-1)` is the most recent). Empty array if count < 1.
-   * Clamped to `buffer.length` when count exceeds it.
-   */
-  getLast(count = 1) {
-    if (count < 1) return [];
-    return this.buffer.slice(-Math.min(count, this.buffer.length));
+  switch (a.type) {
+    case "BACK":
+      return { type: "back" };
+    case "CLOSE":
+      return { type: "closeOverlay" };
+    case "URL":
+      return { type: "openUrl", url: a.url, openInNewTab: a.openInNewTab };
+    case "set_variable":
+      return { type: "setVariable", variable: a.variable, value: a.value };
+    case "toggle_variable":
+      return { type: "toggleVariable", variable: a.variable };
+    case "NODE": {
+      const to = { id: a.destinationId ?? null, name: a.destinationName ?? null };
+      switch (a.navigation) {
+        case "NAVIGATE":
+          return { type: "navigate", to, transition: a.transition };
+        case "SCROLL_TO":
+          return { type: "scrollTo", to, transition: a.transition };
+        case "OVERLAY":
+          return { type: "openOverlay", to, transition: a.transition };
+        case "SWAP":
+          return { type: "swapOverlay", to, transition: a.transition };
+        case "CHANGE_TO":
+          return { type: "changeVariant", to };
+        default:
+          unsupported.push({ source, reason: `unknown navigation: ${String(a.navigation)}`, raw: a });
+          return null;
+      }
+    }
+    case "CONDITIONAL": {
+      if (a.condition === void 0 || a.then === void 0) {
+        unsupported.push({ source, reason: "non-standard conditional", raw: a });
+        return null;
+      }
+      const then = (Array.isArray(a.then) ? a.then : []).map((x) => mapAction(x, source, unsupported)).filter((x) => x !== null);
+      const elseActions = a.else !== void 0 ? (Array.isArray(a.else) ? a.else : []).map((x) => mapAction(x, source, unsupported)).filter((x) => x !== null) : void 0;
+      return { type: "conditional", if: mapCondition(a.condition), then, else: elseActions };
+    }
+    default:
+      unsupported.push({ source, reason: `unknown action type: ${String(a.type)}`, raw: a });
+      return null;
   }
-  size() {
-    return this.buffer.length;
+}
+function buildInteractionSpec(flow, screens) {
+  const frameById = new Map((flow.frames ?? []).map((f) => [f.id, f]));
+  const byFrame = /* @__PURE__ */ new Map();
+  for (const it of flow.interactions ?? []) {
+    if (it.frameId == null) continue;
+    const arr = byFrame.get(it.frameId) ?? [];
+    arr.push(it);
+    byFrame.set(it.frameId, arr);
   }
-};
-function summarizeResult(raw) {
-  if (typeof raw !== "object" || raw === null) {
-    return { successCount: 0, errorCount: 0, warningCount: 0 };
+  const unsupported = [];
+  const screensOut = [];
+  const missingScreens = [];
+  for (const id of screens) {
+    const frame = frameById.get(id);
+    if (!frame) {
+      missingScreens.push(id);
+      continue;
+    }
+    const interactions = (byFrame.get(id) ?? []).map((it) => {
+      const source = { id: it.sourceNodeId, name: it.sourceNodeName ?? null };
+      const mapped = mapAction(it.action, source, unsupported);
+      return { source, trigger: it.trigger, actions: mapped ? [mapped] : [] };
+    });
+    screensOut.push({ id, name: frame.name ?? null, interactions });
   }
-  const r = raw;
   return {
-    successCount: typeof r.successCount === "number" ? r.successCount : 0,
-    errorCount: typeof r.errorCount === "number" ? r.errorCount : 0,
-    warningCount: typeof r.warningCount === "number" ? r.warningCount : 0
+    schemaVersion: "1.0",
+    page: flow.page ?? { id: "", name: "" },
+    screens: screensOut,
+    requestedScreens: screens,
+    missingScreens,
+    unsupported,
+    truncated: Boolean(flow.truncated)
   };
 }
 
@@ -886,7 +988,7 @@ async function recordedHandler(store, tool, parsedInput, send) {
   store.record(tool, parsedInput, summarizeResult(result));
   return result;
 }
-function makeTools(historyStore2) {
+function makeTools(historyStore) {
   return [
     {
       name: "get_canvas_overview",
@@ -900,6 +1002,17 @@ function makeTools(historyStore2) {
       schema: GetPrototypeFlowInput,
       command: "GET_PROTOTYPE_FLOW"
     },
+    {
+      name: "export_interactions",
+      description: "\uC774 \uB3C4\uAD6C\uB294 \uC624\uC9C1 \uD53C\uADF8\uB9C8\uC758 \uD504\uB85C\uD1A0\uD0C0\uC785 \uC778\uD130\uB799\uC158/\uC560\uB2C8\uBA54\uC774\uC158 \uC0DD\uC131\xB7\uC218\uC815 \uBAA9\uC801\uC73C\uB85C\uB9CC \uC0AC\uC6A9\uD569\uB2C8\uB2E4. Export the wired prototype interactions of the given completed screens as a canonical, framework-agnostic JSON spec for developer handoff. Input `{ screens: string[] (frame node IDs), pageId? }`. Returns `{ schemaVersion, page, screens:[{id,name,interactions:[{source,trigger,actions}]}], requestedScreens, missingScreens, unsupported, truncated }`. Each action is a typed entry (navigate / scrollTo / openOverlay / swapOverlay / closeOverlay / back / openUrl / setVariable / toggleVariable / changeVariant / conditional). This is a READ/handoff tool \u2014 developers (or you) derive framework code (React, etc.) from the JSON; it does NOT generate framework or UI code.",
+      schema: ExportInteractionsInput,
+      handler: async (input, session) => {
+        const { screens, pageId } = input;
+        const params = pageId ? { pageId, limit: 5e3 } : { limit: 5e3 };
+        const flow = await session.sendCommand("GET_PROTOTYPE_FLOW", params);
+        return buildInteractionSpec(flow, screens);
+      }
+    },
     {
       name: "find_nodes",
       description: "Search nodes on the current page (or document) by name substring, with optional type filter.",
@@ -940,13 +1053,13 @@ function makeTools(historyStore2) {
       name: "proto_wire",
       description: "\uC774 \uB3C4\uAD6C\uB294 \uC624\uC9C1 \uD53C\uADF8\uB9C8\uC758 \uD504\uB85C\uD1A0\uD0C0\uC785 \uC778\uD130\uB799\uC158/\uC560\uB2C8\uBA54\uC774\uC158 \uC0DD\uC131\xB7\uC218\uC815 \uBAA9\uC801\uC73C\uB85C\uB9CC \uC0AC\uC6A9\uD569\uB2C8\uB2E4. Wire one or more source nodes to destination frames with Navigate To. `from`/`to` are node IDs (e.g. \"1404:1947\"), NOT frame names \u2014 resolve names to IDs with find_nodes or get_canvas_overview first. Use when the WHOLE screen changes to the destination. For a modal/popup/dialog/toast/sheet that appears ON TOP of the current screen ('\uB5A0/\uD31D\uC5C5/\uBAA8\uB2EC'), use proto_overlay (open) instead. Accepts a `motion` preset name (e.g. \"M3_EMPHASIZED\") or a full TransitionInput. Defaults: trigger=ON_CLICK, motion=M3_EMPHASIZED (a SMART_ANIMATE preset). SMART_ANIMATE only morphs layers shared by name between the two frames; when they share none it auto-degrades to the connection's `degradeTo` (DISSOLVE by default). For a spatial 'slides/pushes in' feel between distinct screens, pass a directional TransitionInput (PUSH/MOVE_IN/MOVE_OUT) as `motion`. Compiles to create_reactions internally.",
       schema: ProtoWireInput,
-      handler: async (input, session2) => {
+      handler: async (input, session) => {
         const parsedInput = input;
         return recordedHandler(
-          historyStore2,
+          historyStore,
           "proto_wire",
           parsedInput,
-          () => session2.sendCommand("CREATE_REACTIONS", compileProtoWire(parsedInput))
+          () => session.sendCommand("CREATE_REACTIONS", compileProtoWire(parsedInput))
         );
       }
     },
@@ -954,13 +1067,13 @@ function makeTools(historyStore2) {
       name: "proto_change_to",
       description: "\uC774 \uB3C4\uAD6C\uB294 \uC624\uC9C1 \uD53C\uADF8\uB9C8\uC758 \uD504\uB85C\uD1A0\uD0C0\uC785 \uC778\uD130\uB799\uC158/\uC560\uB2C8\uBA54\uC774\uC158 \uC0DD\uC131\xB7\uC218\uC815 \uBAA9\uC801\uC73C\uB85C\uB9CC \uC0AC\uC6A9\uD569\uB2C8\uB2E4. Switch a component INSTANCE to a sibling VARIANT on interaction (Figma's 'Change to'). This is a ONE-SHOT switch to a SPECIFIC target variant (\u2192 selected, \u2192 highlight, \u2192 on), NOT an alternating flip \u2014 for tabs, segmented controls, and 'set this to its <state> state' changes driven by variants of one component. KO cues: '\uC120\uD0DD \uC0C1\uD0DC\uB85C', 'highlight \uC0C1\uD0DC\uB85C \uBC14\uAFD4', 'variant \uBC14\uAFD4', '~\uC0C1\uD0DC\uB85C \uBC14\uAFD4'. `from` = a component instance node ID (or a node inside one); `to` = the target variant node ID (a COMPONENT inside the same component set, and NOT the instance's current variant) \u2014 both are node IDs, NOT names; resolve names via find_nodes first. Boundaries: a whole-screen change \u2192 proto_wire; a data value \u2192 proto_set_variable; an on/off that flips BACK on every tap ('\uCF1C\uACE0 \uB044\uAE30', a repeating toggle) must be driven by a BOOLEAN variable \u2192 use proto_toggle_variable (a single change_to only goes one direction, it cannot alternate). Defaults: trigger=ON_CLICK, motion=M3_EMPHASIZED (SMART_ANIMATE morph between variants). Compiles to create_reactions internally.",
       schema: ProtoChangeToInput,
-      handler: async (input, session2) => {
+      handler: async (input, session) => {
         const parsedInput = input;
         return recordedHandler(
-          historyStore2,
+          historyStore,
           "proto_change_to",
           parsedInput,
-          () => session2.sendCommand("CREATE_REACTIONS", compileProtoChangeTo(parsedInput))
+          () => session.sendCommand("CREATE_REACTIONS", compileProtoChangeTo(parsedInput))
         );
       }
     },
@@ -968,13 +1081,13 @@ function makeTools(historyStore2) {
       name: "proto_overlay",
       description: `\uC774 \uB3C4\uAD6C\uB294 \uC624\uC9C1 \uD53C\uADF8\uB9C8\uC758 \uD504\uB85C\uD1A0\uD0C0\uC785 \uC778\uD130\uB799\uC158/\uC560\uB2C8\uBA54\uC774\uC158 \uC0DD\uC131\xB7\uC218\uC815 \uBAA9\uC801\uC73C\uB85C\uB9CC \uC0AC\uC6A9\uD569\uB2C8\uB2E4. Create overlay reactions in batch. Each entry has mode = "open" | "swap" | "close". open/swap require an \`overlay\` frameId; close has none. 'open' = content floating above the current screen (modal/popup/dialog/toast/bottom-sheet); for a full screen change use proto_wire. 'close' = dismiss an open overlay, revealing the screen underneath it. If the user says 'go back / \uB3CC\uC544\uAC00 / \uB4A4\uB85C' while on an overlay, that is AMBIGUOUS between close (reveal the underlying screen) and proto_back (history pop) \u2014 ask the user which they mean rather than guessing. Defaults: trigger=ON_CLICK, motion=M3_EMPHASIZED. Compiles to create_reactions internally. Note: Figma's runtime rejects SMART_ANIMATE on overlay/swap/close navigation, so any SMART_ANIMATE-based motion (including all M3/HIG presets) is silently rewritten to DISSOLVE while preserving duration + easing.`,
       schema: ProtoOverlayInput,
-      handler: async (input, session2) => {
+      handler: async (input, session) => {
         const parsedInput = input;
         return recordedHandler(
-          historyStore2,
+          historyStore,
           "proto_overlay",
           parsedInput,
-          () => session2.sendCommand("CREATE_REACTIONS", compileProtoOverlay(parsedInput))
+          () => session.sendCommand("CREATE_REACTIONS", compileProtoOverlay(parsedInput))
         );
       }
     },
@@ -982,13 +1095,13 @@ function makeTools(historyStore2) {
       name: "proto_scroll",
       description: "\uC774 \uB3C4\uAD6C\uB294 \uC624\uC9C1 \uD53C\uADF8\uB9C8\uC758 \uD504\uB85C\uD1A0\uD0C0\uC785 \uC778\uD130\uB799\uC158/\uC560\uB2C8\uBA54\uC774\uC158 \uC0DD\uC131\xB7\uC218\uC815 \uBAA9\uC801\uC73C\uB85C\uB9CC \uC0AC\uC6A9\uD569\uB2C8\uB2E4. Wire source nodes to scroll targets \u2014 Figma's SCROLL_TO action: clicking the source jumps the prototype view to a target NODE inside the same scrollable frame (the target frame must have overflowDirection set, e.g. via set_frame_scroll). NOT for the general 'scroll feel' between pages ('\uC2A4\uD06C\uB864 \uB290\uB08C\uC73C\uB85C \uD654\uBA74\uC774 \uBD80\uB4DC\uB7FD\uAC8C \uB118\uC5B4\uAC00\uAC8C') \u2014 for that effect, use a directional transition (PUSH or SLIDE_*) via proto_wire instead. Defaults: trigger=ON_CLICK, motion=M3_EMPHASIZED. Compiles to create_reactions internally.",
       schema: ProtoScrollInput,
-      handler: async (input, session2) => {
+      handler: async (input, session) => {
         const parsedInput = input;
         return recordedHandler(
-          historyStore2,
+          historyStore,
           "proto_scroll",
           parsedInput,
-          () => session2.sendCommand("CREATE_REACTIONS", compileProtoScroll(parsedInput))
+          () => session.sendCommand("CREATE_REACTIONS", compileProtoScroll(parsedInput))
         );
       }
     },
@@ -996,13 +1109,13 @@ function makeTools(historyStore2) {
       name: "proto_back",
       description: "\uC774 \uB3C4\uAD6C\uB294 \uC624\uC9C1 \uD53C\uADF8\uB9C8\uC758 \uD504\uB85C\uD1A0\uD0C0\uC785 \uC778\uD130\uB799\uC158/\uC560\uB2C8\uBA54\uC774\uC158 \uC0DD\uC131\xB7\uC218\uC815 \uBAA9\uC801\uC73C\uB85C\uB9CC \uC0AC\uC6A9\uD569\uB2C8\uB2E4. Wire source nodes to the Back navigation action (pops the prototype history stack \u2014 no destination). Use for 'go back / \uB4A4\uB85C' = return to whatever screen the user came from (dynamic, no fixed destination). To navigate to a SPECIFIC previous frame, use proto_wire instead. Choosing the source node: for an abstract request ('\uB4A4\uB85C\uAC00\uAE30 \uB2EC\uC544\uC918/add back to each screen') FIRST look for a visible back affordance in each frame \u2014 a small top-left icon, or a node whose name contains back/arrow/chevron/prev, or a '<'/'\u2039' glyph \u2014 and wire THAT with ON_CLICK. Only use a frame-level ON_DRAG swipe-back when the request names a gesture ('\uC2A4\uC640\uC774\uD504/\uBC00\uC5B4\uC11C \uB4A4\uB85C'). If the intent is abstract AND no back-affordance node exists, ASK the user ('\uBC31\uBC84\uD2BC\uC774 \uC548 \uBCF4\uC774\uB294\uB370 \uC2A4\uC640\uC774\uD504 \uC81C\uC2A4\uCC98\uB85C \uD560\uAE4C\uC694?') rather than silently wiring a swipe \u2014 do not create a node (this tool only wires). \u26A0\uFE0F If the source is on an OVERLAY (popup/modal/dialog/sheet shown on top of another screen), 'go back / \uB3CC\uC544\uAC00 / \uB4A4\uB85C' is AMBIGUOUS \u2014 it may mean dismiss the overlay to reveal the screen underneath (= proto_overlay close) or pop the navigation history (= Back, which on an overlay often lands on an unexpected earlier frame). Ask the user which they mean before wiring. Defaults: trigger=ON_CLICK, motion=M3_EMPHASIZED. Compiles to create_reactions internally.",
       schema: ProtoBackInput,
-      handler: async (input, session2) => {
+      handler: async (input, session) => {
         const parsedInput = input;
         return recordedHandler(
-          historyStore2,
+          historyStore,
           "proto_back",
           parsedInput,
-          () => session2.sendCommand("CREATE_REACTIONS", compileProtoBack(parsedInput))
+          () => session.sendCommand("CREATE_REACTIONS", compileProtoBack(parsedInput))
         );
       }
     },
@@ -1010,13 +1123,13 @@ function makeTools(historyStore2) {
       name: "proto_url",
       description: "\uC774 \uB3C4\uAD6C\uB294 \uC624\uC9C1 \uD53C\uADF8\uB9C8\uC758 \uD504\uB85C\uD1A0\uD0C0\uC785 \uC778\uD130\uB799\uC158/\uC560\uB2C8\uBA54\uC774\uC158 \uC0DD\uC131\xB7\uC218\uC815 \uBAA9\uC801\uC73C\uB85C\uB9CC \uC0AC\uC6A9\uD569\uB2C8\uB2E4. Wire source nodes to the Open URL action. Input `{ urls: [{ from, url, openInNewTab? }] }`. Defaults: trigger=ON_CLICK, openInNewTab=false. No `motion` field \u2014 URL is a terminal event and the underlying reaction's transition defaults to INSTANT. Compiles to create_reactions internally.",
       schema: ProtoUrlInput,
-      handler: async (input, session2) => {
+      handler: async (input, session) => {
         const parsedInput = input;
         return recordedHandler(
-          historyStore2,
+          historyStore,
           "proto_url",
           parsedInput,
-          () => session2.sendCommand("CREATE_REACTIONS", compileProtoUrl(parsedInput))
+          () => session.sendCommand("CREATE_REACTIONS", compileProtoUrl(parsedInput))
         );
       }
     },
@@ -1024,13 +1137,13 @@ function makeTools(historyStore2) {
       name: "proto_set_variable",
       description: '\uC774 \uB3C4\uAD6C\uB294 \uC624\uC9C1 \uD53C\uADF8\uB9C8\uC758 \uD504\uB85C\uD1A0\uD0C0\uC785 \uC778\uD130\uB799\uC158/\uC560\uB2C8\uBA54\uC774\uC158 \uC0DD\uC131\xB7\uC218\uC815 \uBAA9\uC801\uC73C\uB85C\uB9CC \uC0AC\uC6A9\uD569\uB2C8\uB2E4. Wire source nodes to the Set Variable action \u2014 clicking the source assigns a literal value to a Figma variable (resolved by NAME \u2014 local or library/remote; library variables are auto-imported on use). Input `{ sets: [{ from, variable, value }] }`. `value` is boolean / number / string and must match the variable\'s resolvedType; for COLOR variables, pass `value` as a hex string ("#RRGGBB" or "#RRGGBBAA"). To flip a BOOLEAN without naming the target value (\'\uD1A0\uAE00/\uCF1C\uACE0 \uB044\uAE30\'), use proto_toggle_variable \u2014 this tool assigns a SPECIFIC value. Defaults: trigger=ON_CLICK. No `motion` field \u2014 variable changes are instant (transition defaults to INSTANT). Compiles to create_reactions internally.',
       schema: ProtoSetVariableInput,
-      handler: async (input, session2) => {
+      handler: async (input, session) => {
         const parsedInput = input;
         return recordedHandler(
-          historyStore2,
+          historyStore,
           "proto_set_variable",
           parsedInput,
-          () => session2.sendCommand("CREATE_REACTIONS", compileProtoSetVariable(parsedInput))
+          () => session.sendCommand("CREATE_REACTIONS", compileProtoSetVariable(parsedInput))
         );
       }
     },
@@ -1038,13 +1151,13 @@ function makeTools(historyStore2) {
       name: "proto_toggle_variable",
       description: "\uC774 \uB3C4\uAD6C\uB294 \uC624\uC9C1 \uD53C\uADF8\uB9C8\uC758 \uD504\uB85C\uD1A0\uD0C0\uC785 \uC778\uD130\uB799\uC158/\uC560\uB2C8\uBA54\uC774\uC158 \uC0DD\uC131\xB7\uC218\uC815 \uBAA9\uC801\uC73C\uB85C\uB9CC \uC0AC\uC6A9\uD569\uB2C8\uB2E4. Wire source nodes to the Toggle Variable action \u2014 clicking the source flips a BOOLEAN variable (resolved by NAME \u2014 local or library/remote, auto-imported on use). Input `{ toggles: [{ from, variable }] }`. The variable's resolvedType MUST be BOOLEAN (plugin rejects otherwise). Use to flip/switch a boolean ('\uD1A0\uAE00', '\uCF1C\uACE0 \uB044\uAE30') with no named target value; to assign a specific value (true/false/number/string/color) use proto_set_variable instead. This is the right tool for a REPEATING on/off that flips back on every tap. If the on/off is a VISUAL component built from variants and NOT backed by a boolean variable, a one-directional switch to a specific state is proto_change_to instead; toggle_variable requires a BOOLEAN variable to flip. Defaults: trigger=ON_CLICK. No `motion` field \u2014 variable changes are instant. Compiles to create_reactions internally (desugars to CONDITIONAL + 2 SET_VARIABLE under the hood; list_reactions round-trips to toggle_variable shape).",
       schema: ProtoToggleVariableInput,
-      handler: async (input, session2) => {
+      handler: async (input, session) => {
         const parsedInput = input;
         return recordedHandler(
-          historyStore2,
+          historyStore,
           "proto_toggle_variable",
           parsedInput,
-          () => session2.sendCommand("CREATE_REACTIONS", compileProtoToggleVariable(parsedInput))
+          () => session.sendCommand("CREATE_REACTIONS", compileProtoToggleVariable(parsedInput))
         );
       }
     },
@@ -1052,13 +1165,13 @@ function makeTools(historyStore2) {
       name: "proto_conditional",
       description: "\uC774 \uB3C4\uAD6C\uB294 \uC624\uC9C1 \uD53C\uADF8\uB9C8\uC758 \uD504\uB85C\uD1A0\uD0C0\uC785 \uC778\uD130\uB799\uC158/\uC560\uB2C8\uBA54\uC774\uC158 \uC0DD\uC131\xB7\uC218\uC815 \uBAA9\uC801\uC73C\uB85C\uB9CC \uC0AC\uC6A9\uD569\uB2C8\uB2E4. Wire a conditional reaction (if/then/else) on a source node based on a variable comparison. Use for '~\uBA74 ~\uD558\uACE0 \uC544\uB2C8\uBA74 ~' / '\uC870\uAC74\uC5D0 \uB530\uB77C' branching interactions. The variable is referenced by NAME; the plugin resolves it at runtime \u2014 local variables match directly, library/remote variables are auto-imported on use. Use list_variables to find exact names. Input `{ conditions: [{ from, if, then, else? }] }`. `if` is a single comparison `{ variable, operator?, value }`, OR a one-level compound: `{ all: [<comparison>, \u2026] }` (AND \u2014 \uBAA8\uB450 \uCC38\uC77C \uB54C; cues: '\uADF8\uB9AC\uACE0 / \uC774\uACE0 / \uB458 \uB2E4 / \uBAA8\uB450') or `{ any: [<comparison>, \u2026] }` (OR \u2014 \uD558\uB098\uB77C\uB3C4 \uCC38\uC77C \uB54C; cues: '\uB610\uB294 / \uAC70\uB098 / \uD558\uB098\uB77C\uB3C4'). Each array needs \u22652 comparisons; `all` and `any` cannot be mixed or nested (one level only) \u2014 for multi-way branching use separate reactions (Figma has no else-if). `if.operator` defaults to \"==\" if omitted (most common case); other operators: !=, <, <=, >, >=. `then` / `else` each take exactly ONE branch action (single sugar entry). Branch sugar keys: `navigate` / `scroll` / `overlay` / `swap` / `close` / `back` / `url` / `set`. `toggle_variable` is not available inside conditional (toggle itself desugars to CONDITIONAL \u2014 nesting is meaningless). For multi-action branches, use low-level `create_reactions` (escape hatch). Overlay/swap branches: if either branch is `{ overlay }` or `{ swap }`, SMART_ANIMATE auto-rewrites to DISSOLVE (Figma's overlay transition constraint); the motion intent (duration/easing) is preserved. Variable type must match `if.value` (BOOLEAN/FLOAT/STRING); COLOR variables are NOT comparable. `trigger` / `motion` apply at the conditional level (shared across branches); branch sugars do NOT accept them.",
       schema: ProtoConditionalInput,
-      handler: async (input, session2) => {
+      handler: async (input, session) => {
         const parsedInput = input;
         return recordedHandler(
-          historyStore2,
+          historyStore,
           "proto_conditional",
           parsedInput,
-          () => session2.sendCommand("CREATE_REACTIONS", compileProtoConditional(parsedInput))
+          () => session.sendCommand("CREATE_REACTIONS", compileProtoConditional(parsedInput))
         );
       }
     },
@@ -1068,13 +1181,13 @@ function makeTools(historyStore2) {
       schema: ProtoGetLastHistoryInput,
       handler: async (input) => {
         const { count } = input;
-        return { entries: historyStore2.getLast(count) };
+        return { entries: historyStore.getLast(count) };
       }
     }
   ];
 }
-function registerToolHandlers(mcp, session2, historyStore2) {
-  const TOOLS = makeTools(historyStore2);
+function registerToolHandlers(mcp, session, historyStore) {
+  const TOOLS = makeTools(historyStore);
   mcp.setRequestHandler(ListToolsRequestSchema, async () => ({
     tools: TOOLS.map((t) => ({
       name: t.name,
@@ -1092,19 +1205,19 @@ function registerToolHandlers(mcp, session2, historyStore2) {
       return { isError: true, content: [{ type: "text", text: `Invalid input: ${parsed.error.message}` }] };
     }
     try {
-      const result = tool.handler !== void 0 ? await tool.handler(parsed.data, session2) : await session2.sendCommand(tool.command, parsed.data);
+      const result = tool.handler !== void 0 ? await tool.handler(parsed.data, session) : await session.sendCommand(tool.command, parsed.data);
       return { content: [{ type: "text", text: JSON.stringify(result, null, 2) }] };
     } catch (err) {
       return { isError: true, content: [{ type: "text", text: err.message }] };
     }
   });
 }
-function createMcpServer(session2, historyStore2, version) {
+function createMcpServer(session, historyStore, version) {
   const server = new Server(
     { name: "figma-prototype-mcp", version },
     { capabilities: { tools: {} } }
   );
-  registerToolHandlers(server, session2, historyStore2);
+  registerToolHandlers(server, session, historyStore);
   return server;
 }
 
@@ -1148,47 +1261,107 @@ var SseSession = class {
   }
 };
 
-// src/server/index.ts
-var pkg = JSON.parse(
-  readFileSync(new URL("../../package.json", import.meta.url), "utf8")
-);
-var PORT = Number(process.env.PORT ?? 3e3);
-var session = new PluginSession();
-var historyStore = new HistoryStore();
-var sse = new SseSession();
-var app = express();
-app.get("/sse", async (_req, res) => {
-  const server = createMcpServer(session, historyStore, pkg.version);
-  const transport = new SSEServerTransport("/messages", res);
-  res.on("close", () => sse.clear(transport));
-  await server.connect(transport);
-  const evicted = sse.activate(server, transport);
-  if (evicted) {
-    console.warn(
-      "[server] a second MCP client connected \u2014 evicted the prior SSE connection (newest-wins). The displaced client's next call fails fast with HTTP 400 and it should reconnect; keep a single MCP client per server (a supergateway bridge may hang instead of surfacing the eviction)."
-    );
-  }
-});
-app.post("/messages", express.json(), async (req, res) => {
-  const t = sse.get(String(req.query.sessionId ?? ""));
-  if (!t) {
-    res.status(400).send("unknown session");
-    return;
+// src/server/run.ts
+function parseArgs(argv) {
+  return { mode: argv.includes("--stdio") ? "stdio" : "sse" };
+}
+function createDeps() {
+  const pkg = JSON.parse(
+    readFileSync(new URL("../../package.json", import.meta.url), "utf8")
+  );
+  return {
+    session: new PluginSession(),
+    historyStore: new HistoryStore(),
+    version: pkg.version
+  };
+}
+function listenWithWs(httpServer, port, session) {
+  attachPluginWebSocket(httpServer, session);
+  return new Promise((resolve) => {
+    httpServer.on("error", (err) => {
+      if (err.code === "EADDRINUSE") {
+        console.error(
+          `[server] port ${port} is already in use \u2014 another figma-prototype-mcp server may be running. Stop it, or set PORT to a free port (and update the plugin manifest if you change it).`
+        );
+      } else {
+        console.error("[server] http server error:", err);
+      }
+      process.exit(1);
+    });
+    httpServer.listen(port, () => {
+      resolve();
+    });
+  });
+}
+function logStartup(port, mode2) {
+  if (mode2 === "sse") {
+    console.error(`[server] listening on http://localhost:${port}`);
+    console.error(`[server]   MCP SSE endpoint: GET /sse`);
+  } else {
+    console.error(`[server] stdio MCP mode (MCP over stdio; stdout is the JSON-RPC channel)`);
   }
-  await t.handlePostMessage(req, res, req.body);
-});
-var httpServer = app.listen(PORT, () => {
-  console.log(`[server] listening on http://localhost:${PORT}`);
-  console.log(`[server]   MCP SSE endpoint: GET /sse`);
-  console.log(`[server]   Plugin WebSocket:  ws://localhost:${PORT}/ws`);
-  console.log(
+  console.error(`[server]   Plugin WebSocket:  ws://localhost:${port}/ws`);
+  console.error(
     `[server]   Figma plugin manifest: ${fileURLToPath(new URL("../figma-plugin/manifest.json", import.meta.url))}`
   );
-});
-attachPluginWebSocket(httpServer, session);
+}
+async function runSse(deps2, port = Number(process.env.PORT ?? 3e3)) {
+  const sse = new SseSession();
+  const app = express();
+  app.get("/sse", async (_req, res) => {
+    const server = createMcpServer(deps2.session, deps2.historyStore, deps2.version);
+    const transport = new SSEServerTransport("/messages", res);
+    res.on("close", () => sse.clear(transport));
+    await server.connect(transport);
+    const evicted = sse.activate(server, transport);
+    if (evicted) {
+      console.error(
+        "[server] a second MCP client connected \u2014 evicted the prior SSE connection (newest-wins). The displaced client's next call fails fast with HTTP 400 and it should reconnect; keep a single MCP client per server (a supergateway bridge may hang instead of surfacing the eviction)."
+      );
+    }
+  });
+  app.post("/messages", express.json(), async (req, res) => {
+    const t = sse.get(String(req.query.sessionId ?? ""));
+    if (!t) {
+      res.status(400).send("unknown session");
+      return;
+    }
+    await t.handlePostMessage(req, res, req.body);
+  });
+  const httpServer = http.createServer(app);
+  await listenWithWs(httpServer, port, deps2.session);
+  logStartup(port, "sse");
+  return httpServer;
+}
+async function runStdio(deps2, port = Number(process.env.PORT ?? 3e3), transport = new StdioServerTransport()) {
+  const httpServer = http.createServer();
+  await listenWithWs(httpServer, port, deps2.session);
+  const mcpServer = createMcpServer(deps2.session, deps2.historyStore, deps2.version);
+  mcpServer.onclose = () => {
+    try {
+      httpServer.close();
+    } catch {
+    }
+  };
+  await mcpServer.connect(transport).catch((err) => {
+    httpServer.close();
+    throw err;
+  });
+  logStartup(port, "stdio");
+  return { httpServer, mcpServer };
+}
+
+// src/server/index.ts
 process.on("unhandledRejection", (err) => {
   console.error("[server] unhandledRejection:", err);
 });
 process.on("uncaughtException", (err) => {
   console.error("[server] uncaughtException:", err);
 });
+var { mode } = parseArgs(process.argv.slice(2));
+var deps = createDeps();
+if (mode === "stdio") {
+  void runStdio(deps);
+} else {
+  void runSse(deps);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-prototype-mcp",
-  "version": "0.30.2",
+  "version": "0.31.0",
   "description": "MCP server for creating Figma prototype interactions via natural language",
   "license": "MIT",
   "author": "smooeach",