figma-prototype-mcp 0.30.1 → 0.30.3

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")*
@@ -180,6 +186,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,13 +1,54 @@
 #!/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";
+
+// src/server/messages.ts
+var COMMUNITY_URL = "https://www.figma.com/community/plugin/1647184714488719280";
+var PLUGIN_NOT_CONNECTED = [
+  `Figma plugin not connected. The MCP server is running, but no Figma plugin has connected yet.`,
+  `To connect: in Figma, open your file \u2192 Plugins \u2192 run "Prototype MCP".`,
+  `If you haven't installed it, get it from Figma Community:`,
+  COMMUNITY_URL,
+  `The plugin auto-connects to ws://localhost:3000/ws \u2014 once it shows "Connected", retry your request.`,
+  ``,
+  `Figma \uD50C\uB7EC\uADF8\uC778\uC774 \uC5F0\uACB0\uB418\uC9C0 \uC54A\uC558\uC2B5\uB2C8\uB2E4. MCP \uC11C\uBC84\uB294 \uC2E4\uD589 \uC911\uC774\uC9C0\uB9CC \uD50C\uB7EC\uADF8\uC778\uC774 \uC544\uC9C1 \uC5F0\uACB0\uB418\uC9C0 \uC54A\uC558\uC5B4\uC694.`,
+  `\uC5F0\uACB0 \uBC29\uBC95: Figma\uC5D0\uC11C \uD30C\uC77C\uC744 \uC5F4\uACE0 \u2192 Plugins \u2192 "Prototype MCP" \uC2E4\uD589.`,
+  `\uC124\uCE58 \uC804\uC774\uB77C\uBA74 Figma Community\uC5D0\uC11C \uBC1B\uC73C\uC138\uC694:`,
+  COMMUNITY_URL,
+  `\uD50C\uB7EC\uADF8\uC778\uC740 ws://localhost:3000/ws\uC5D0 \uC790\uB3D9 \uC5F0\uACB0\uB429\uB2C8\uB2E4 \u2014 "Connected"\uAC00 \uB728\uBA74 \uB2E4\uC2DC \uC2DC\uB3C4\uD558\uC138\uC694.`
+].join("\n");
+var PLUGIN_DISCONNECTED = [
+  `The Figma plugin disconnected before the command finished. This usually means the Figma tab/file or the plugin window was closed.`,
+  `Reopen "Prototype MCP" in Figma \u2014 it auto-reconnects \u2014 then retry.`,
+  ``,
+  `\uBA85\uB839\uC774 \uB05D\uB098\uAE30 \uC804\uC5D0 Figma \uD50C\uB7EC\uADF8\uC778 \uC5F0\uACB0\uC774 \uB04A\uACBC\uC2B5\uB2C8\uB2E4. \uBCF4\uD1B5 Figma \uD0ED/\uD30C\uC77C\uC774\uB098 \uD50C\uB7EC\uADF8\uC778 \uCC3D\uC744 \uB2EB\uC558\uC744 \uB54C \uBC1C\uC0DD\uD574\uC694.`,
+  `Figma\uC5D0\uC11C "Prototype MCP"\uB97C \uB2E4\uC2DC \uC2E4\uD589\uD558\uBA74 \uC790\uB3D9 \uC7AC\uC5F0\uACB0\uB429\uB2C8\uB2E4 \u2014 \uADF8 \uD6C4 \uB2E4\uC2DC \uC2DC\uB3C4\uD558\uC138\uC694.`
+].join("\n");
+var PLUGIN_CONNECTION_REPLACED = [
+  `Your plugin connection was replaced by a newer one. Only one Figma plugin can be active at a time (newest wins) \u2014 this usually means the plugin connected from a second Figma tab or file.`,
+  `Use the most recently opened "Prototype MCP" plugin, then retry.`,
+  ``,
+  `\uD50C\uB7EC\uADF8\uC778 \uC5F0\uACB0\uC774 \uB354 \uC0C8\uB85C\uC6B4 \uC5F0\uACB0\uB85C \uAD50\uCCB4\uB418\uC5C8\uC2B5\uB2C8\uB2E4. \uD55C \uBC88\uC5D0 \uD558\uB098\uC758 Figma \uD50C\uB7EC\uADF8\uC778\uB9CC \uD65C\uC131\uD654\uB429\uB2C8\uB2E4(\uCD5C\uC2E0 \uC6B0\uC120) \u2014 \uBCF4\uD1B5 \uB450 \uBC88\uC9F8 Figma \uD0ED\uC774\uB098 \uD30C\uC77C\uC5D0\uC11C \uD50C\uB7EC\uADF8\uC778\uC774 \uC5F0\uACB0\uB410\uC744 \uB54C \uBC1C\uC0DD\uD574\uC694.`,
+  `\uAC00\uC7A5 \uCD5C\uADFC\uC5D0 \uC5F0 "Prototype MCP" \uD50C\uB7EC\uADF8\uC778\uC744 \uC0AC\uC6A9\uD55C \uB4A4 \uC7AC\uC2DC\uB3C4\uD558\uC138\uC694.`
+].join("\n");
+var pluginCommandTimeout = (command, ms) => [
+  `The Figma plugin is connected but didn't respond within ${ms}ms (command: ${command}).`,
+  `Figma may be busy, or the plugin may be stuck. Try closing and relaunching "Prototype MCP" in Figma, then retry.`,
+  ``,
+  `Figma \uD50C\uB7EC\uADF8\uC778\uC774 \uC5F0\uACB0\uB3FC \uC788\uC9C0\uB9CC ${ms}ms \uC548\uC5D0 \uC751\uB2F5\uD558\uC9C0 \uC54A\uC558\uC2B5\uB2C8\uB2E4 (\uBA85\uB839: ${command}).`,
+  `Figma\uAC00 \uBC14\uC058\uAC70\uB098 \uD50C\uB7EC\uADF8\uC778\uC774 \uBA48\uCDC4\uC744 \uC218 \uC788\uC5B4\uC694. Figma\uC5D0\uC11C "Prototype MCP"\uB97C \uB2EB\uC558\uB2E4\uAC00 \uB2E4\uC2DC \uC2E4\uD589\uD55C \uB4A4 \uC7AC\uC2DC\uB3C4\uD558\uC138\uC694.`
+].join("\n");
+
+// src/server/sessions.ts
 var PluginSession = class {
   active = null;
   pending = /* @__PURE__ */ new Map();
@@ -31,7 +72,7 @@ var PluginSession = class {
         this.active.close();
       } catch {
       }
-      this.failAllPending(new Error("Plugin connection replaced by newer connection"));
+      this.failAllPending(new Error(PLUGIN_CONNECTION_REPLACED));
     }
     this.active = ws;
     try {
@@ -43,7 +84,7 @@ var PluginSession = class {
   clearActive(ws) {
     if (this.active === ws) {
       this.active = null;
-      this.failAllPending(new Error("Plugin disconnected"));
+      this.failAllPending(new Error(PLUGIN_DISCONNECTED));
     }
   }
   handleResponse(msg) {
@@ -58,14 +99,14 @@ var PluginSession = class {
     if (!this.isConnected()) {
       await this.waitForConnection(this.connectWaitMs);
       if (!this.isConnected()) {
-        throw new Error("\uD53C\uADF8\uB9C8 \uD50C\uB7EC\uADF8\uC778 \uC5F0\uACB0\uC744 \uD655\uC778\uD574\uC8FC\uC138\uC694");
+        throw new Error(PLUGIN_NOT_CONNECTED);
       }
     }
     const id = randomUUID();
     return new Promise((resolve, reject) => {
       const timer = setTimeout(() => {
         this.pending.delete(id);
-        reject(new Error(`Command ${command} timed out after ${this.commandTimeoutMs}ms`));
+        reject(new Error(pluginCommandTimeout(command, this.commandTimeoutMs)));
       }, this.commandTimeoutMs);
       this.pending.set(id, { resolve, reject, timer });
       try {
@@ -107,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 {
@@ -117,7 +158,7 @@ function attachPluginWebSocket(httpServer2, session2) {
     }
   });
   wss.on("connection", (ws) => {
-    session2.setActive(ws);
+    session.setActive(ws);
     ws.on("message", (raw) => {
       let msg;
       try {
@@ -126,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 {
@@ -795,59 +882,13 @@ 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;
-  }
-  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
 async function recordedHandler(store, tool, parsedInput, send) {
   const result = await send();
   store.record(tool, parsedInput, summarizeResult(result));
   return result;
 }
-function makeTools(historyStore2) {
+function makeTools(historyStore) {
   return [
     {
       name: "get_canvas_overview",
@@ -901,13 +942,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))
         );
       }
     },
@@ -915,13 +956,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))
         );
       }
     },
@@ -929,13 +970,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))
         );
       }
     },
@@ -943,13 +984,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))
         );
       }
     },
@@ -957,13 +998,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))
         );
       }
     },
@@ -971,13 +1012,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))
         );
       }
     },
@@ -985,13 +1026,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))
         );
       }
     },
@@ -999,13 +1040,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))
         );
       }
     },
@@ -1013,13 +1054,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))
         );
       }
     },
@@ -1029,13 +1070,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,
@@ -1053,19 +1094,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;
 }
 
@@ -1109,47 +1150,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.1",
+  "version": "0.30.3",
   "description": "MCP server for creating Figma prototype interactions via natural language",
   "license": "MIT",
   "author": "smooeach",