figma-prototype-mcp 0.30.3 → 0.31.0

package/README.md

@@ -172,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 |

package/dist/server/index.js

@@ -265,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(),
@@ -882,6 +886,102 @@ function compileProtoConditional(input) {
   return { connections, replaceExisting: input.replaceExisting };
 }
 
+// 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 };
+  }
+  return { raw: c };
+}
+function mapAction(a, source, unsupported) {
+  if (!a || typeof a !== "object") {
+    unsupported.push({ source, reason: "non-object action", raw: a });
+    return null;
+  }
+  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;
+  }
+}
+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);
+  }
+  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 });
+  }
+  return {
+    schemaVersion: "1.0",
+    page: flow.page ?? { id: "", name: "" },
+    screens: screensOut,
+    requestedScreens: screens,
+    missingScreens,
+    unsupported,
+    truncated: Boolean(flow.truncated)
+  };
+}
+
 // src/server/tools.ts
 async function recordedHandler(store, tool, parsedInput, send) {
   const result = await send();
@@ -902,6 +1002,17 @@ function makeTools(historyStore) {
       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.",

package/package.json

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