figma-prototype-mcp 0.30.0 → 0.30.2

package/README.md

@@ -6,6 +6,33 @@ Why this exists: the official Figma MCP doesn't expose a write API for prototype
 
 > 🎨 Designers: see the plain-language **[prototype-wiring cheat-sheet](docs/prototype-wiring-for-designers.md)** ("say this → get that").
 
+## Quick start
+
+You connect three local pieces: a **server**, the **Figma plugin**, and your **AI client**. ~3 minutes.
+
+**Prerequisites:** [Node 18+](https://nodejs.org) · the Figma **desktop app** · an MCP client ([Claude Desktop](https://claude.ai/download) or Claude Code).
+
+**1. Start the server** (terminal — leave it running):
+```bash
+npx figma-prototype-mcp
+# → [server] listening on http://localhost:3000
+```
+
+**2. Install & run the plugin:**
+- Install from Figma Community: **[Prototype MCP — wire prototypes with LLM](https://www.figma.com/community/plugin/1647184714488719280/prototype-mcp-wire-prototypes-with-llm)**
+- Open a Figma **design file** → run the plugin (Plugins → Prototype MCP) → it should show **Connected** (needs step 1 running).
+
+**3. Point your AI client at the server** — add this to your MCP client config, then restart it:
+```json
+{ "mcpServers": { "figma-prototype": { "url": "http://localhost:3000/sse" } } }
+```
+
+**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")*
+
+The interaction appears in Figma's **Prototype** tab. That's the loop — describe it, it's wired. (Stuck? see [Troubleshooting](#troubleshooting).)
+
 ## Architecture
 
 ```
@@ -50,9 +77,8 @@ Requires **Node ≥ 18**.
 
 **2. Figma plugin**:
 
-- Open Figma desktop app.
-- Plugins → Development → Import plugin from manifest...
-- Choose `dist/figma-plugin/manifest.json`.
+- **Easiest — install from Figma Community:** [Prototype MCP — wire prototypes with LLM](https://www.figma.com/community/plugin/1647184714488719280/prototype-mcp-wire-prototypes-with-llm) → **Open in…** / **Run**.
+- **Or load locally (for development):** Figma desktop → Plugins → Development → Import plugin from manifest… → choose `dist/figma-plugin/manifest.json` (after `npm run build`).
 - Run the plugin. It auto-connects to `ws://localhost:3000/ws` (single-active session — only one plugin at a time, latest connection wins). Click **Connect** if it doesn't auto-connect on launch.
 
 **3. MCP client** (Claude Desktop or Claude Code):

package/dist/figma-plugin/code.js

@@ -498,7 +498,7 @@
       return { type: "set_variable", variable: varName != null ? varName : `<id:${action.variableId}>`, value };
     }
     const destId = action.destinationId;
-    const destName = destId ? resolvers.nodeName(destId) : void 0;
+    const destName = destId ? await resolvers.nodeName(destId) : void 0;
     return {
       type: (_c = action.type) != null ? _c : "UNKNOWN",
       navigation: action.navigation,
@@ -623,14 +623,14 @@
       return figma.currentPage;
     }
     await figma.loadAllPagesAsync();
-    const page = figma.getNodeById(pageId);
+    const page = await figma.getNodeByIdAsync(pageId);
     if (!page || page.type !== "PAGE") throw new Error(`Page not found: ${pageId}`);
     return page;
   }
   async function buildNonConditionalAction(action, trigger, afterTimeoutSeconds, transition, sourceNode, degradeTo) {
     var _a;
     if (action.type === "navigate") {
-      const target = figma.getNodeById(action.targetFrameId);
+      const target = await figma.getNodeByIdAsync(action.targetFrameId);
       if (!target) throw new Error(`Target frame not found: ${action.targetFrameId}`);
       if (target.type !== "FRAME") {
         throw new Error(`Target must be a frame: ${action.targetFrameId} (got ${target.type})`);
@@ -651,7 +651,7 @@
       return { built: reaction.actions[0], warning };
     }
     if (action.type === "scroll") {
-      const target = figma.getNodeById(action.targetNodeId);
+      const target = await figma.getNodeByIdAsync(action.targetNodeId);
       if (!target) throw new Error(`Scroll target node not found: ${action.targetNodeId}`);
       const scrollable = findScrollableAncestor(target);
       let warning;
@@ -668,7 +668,7 @@
       return { built: reaction.actions[0], warning };
     }
     if (action.type === "overlay") {
-      const target = figma.getNodeById(action.targetFrameId);
+      const target = await figma.getNodeByIdAsync(action.targetFrameId);
       if (!target) throw new Error(`Overlay target frame not found: ${action.targetFrameId}`);
       if (target.type !== "FRAME") {
         throw new Error(`Overlay target must be a frame: ${action.targetFrameId} (got ${target.type})`);
@@ -710,7 +710,7 @@
       return { built, warning };
     }
     if (action.type === "swap_overlay") {
-      const target = figma.getNodeById(action.targetFrameId);
+      const target = await figma.getNodeByIdAsync(action.targetFrameId);
       if (!target) throw new Error(`Swap overlay target frame not found: ${action.targetFrameId}`);
       if (target.type !== "FRAME") {
         throw new Error(`Swap overlay target must be a frame: ${action.targetFrameId} (got ${target.type})`);
@@ -725,7 +725,7 @@
       return { built: reaction.actions[0] };
     }
     if (action.type === "change_to") {
-      const target = figma.getNodeById(action.targetVariantId);
+      const target = await figma.getNodeByIdAsync(action.targetVariantId);
       if (!target) throw new Error(`Change-to target not found: ${action.targetVariantId}`);
       if (target.type !== "COMPONENT") {
         throw new Error(`Change-to target must be a component variant: ${action.targetVariantId} (got ${target.type})`);
@@ -993,7 +993,7 @@
     let warningCount = 0;
     for (const conn of params.connections) {
       try {
-        const source = figma.getNodeById(conn.sourceNodeId);
+        const source = await figma.getNodeByIdAsync(conn.sourceNodeId);
         if (!source) throw new Error(`Source node not found: ${conn.sourceNodeId}`);
         if (!("setReactionsAsync" in source) || typeof source.setReactionsAsync !== "function") {
           throw new Error(`Node cannot have reactions: ${source.name} (type: ${source.type})`);
@@ -1115,15 +1115,15 @@
         return void 0;
       }
     },
-    nodeName: (id) => {
+    nodeName: async (id) => {
       var _a, _b;
-      return (_b = (_a = figma.getNodeById(id)) == null ? void 0 : _a.name) != null ? _b : void 0;
+      return (_b = (_a = await figma.getNodeByIdAsync(id)) == null ? void 0 : _a.name) != null ? _b : void 0;
     }
   };
   async function handleListReactions(params) {
     var _a;
     await figma.loadAllPagesAsync();
-    const node = figma.getNodeById(params.nodeId);
+    const node = await figma.getNodeByIdAsync(params.nodeId);
     if (!node) throw new Error(`Node not found: ${params.nodeId}`);
     if (!("reactions" in node)) throw new Error(`Node has no reactions field: ${node.name}`);
     const reactions = (_a = node.reactions) != null ? _a : [];
@@ -1147,7 +1147,7 @@
     const results = [];
     for (const nodeId of params.nodeIds) {
       try {
-        const node = figma.getNodeById(nodeId);
+        const node = await figma.getNodeByIdAsync(nodeId);
         if (!node) throw new Error(`Node not found: ${nodeId}`);
         if (!("setReactionsAsync" in node)) throw new Error(`Node cannot have reactions: ${node.name}`);
         const existing = (_a = node.reactions) != null ? _a : [];
@@ -1178,7 +1178,7 @@
     for (const { frameId, direction, fixedChildren } of params.frames) {
       const applied = [];
       try {
-        const node = figma.getNodeById(frameId);
+        const node = await figma.getNodeByIdAsync(frameId);
         if (!node) throw new Error(`Frame not found: ${frameId}`);
         if (node.type !== "FRAME") {
           throw new Error(`Node is not a FRAME: ${node.name} (type: ${node.type})`);

package/dist/figma-plugin/manifest.json

@@ -1,13 +1,14 @@
 {
   "name": "Figma Prototype MCP",
-  "id": "figma-prototype-mcp-local",
+  "id": "1647184714488719280",
   "api": "1.0.0",
   "main": "code.js",
   "ui": "ui.html",
   "editorType": ["figma"],
+  "documentAccess": "dynamic-page",
   "permissions": ["teamlibrary"],
   "networkAccess": {
     "allowedDomains": ["ws://localhost:3000"],
-    "reasoning": "Local WebSocket bridge to the figma-prototype-mcp unified server (Phase A v1.19+)"
+    "reasoning": "Connects only to a local companion server (ws://localhost:3000) that the user runs themselves; no external network access. The server bridges this plugin to an MCP client. https://github.com/smooeach/figma-prototype-mcp"
   }
 }

package/dist/server/index.js

@@ -8,6 +8,45 @@ import { fileURLToPath } from "url";
 
 // 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 +70,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 +82,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 +97,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 {

package/package.json

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