figma-rust-mcp 3.0.0 → 3.0.2

package/README.md

@@ -147,7 +147,7 @@ Add to your `~/.gemini/config/mcp_config.json` or project `.agents/mcp_config.js
 
 ## 🛠️ MCP Tools Reference
 
-`figma-mcp` provides **14 first-class MCP tools**:
+`figma-mcp` provides **15 first-class MCP tools**:
 
 ### 1. `figma_status`
 Checks live bridge connection status, connected Figma tabs/files, in-memory index health, queue length, and latency statistics.
@@ -230,6 +230,17 @@ Scans your local codebase directories (`src/components`, `components/ui`) to dis
 - **`projectDir`**: Base directory of your project (default: current directory `"."`).
 - **`nodeId`**: Optional Figma node ID to check specific match against local components.
 
+### 15. `figma_prepare_design`
+**All-In-One Multimodal Grounding Pack for AI**: The ultimate single-call tool for code generation that eliminates missing UI elements and icon guesswork.
+- Simultaneously extracts **100% of visible text elements** (greeting, badges, timestamps, labels).
+- Automatically **exports all SVG vector icons** into your local project directory (`iconDir`) and provides exact TypeScript import statements.
+- Captures high-res **visual canvas screenshots** saved locally for immediate multimodal LLM inspection.
+- Discovers existing components in your codebase for direct reuse.
+- Generates an actionable **Implementation Checklist** ensuring complete design fidelity in 1 single shot.
+- **`nodeId`**: Target Figma screen/frame ID.
+- **`iconDir`**: Target directory for SVG icons (e.g. `src/assets/icons` or `assets/images`).
+- **`projectDir`**: Base directory for component discovery.
+
 ---
 
 ## 💻 Development & Testing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-rust-mcp",
-  "version": "3.0.0",
+  "version": "3.0.2",
   "description": "Claude Code to Figma — Bidirectional MCP bridge. AI draws UI on Figma canvas, reads designs back. Works with Claude, Cursor, VS Code, Windsurf, Antigravity. No API key needed.",
   "mcpName": "io.github.BuiHung1612/figma-mcp",
   "type": "module",

package/plugin/code.js

@@ -1,7 +1,7 @@
 // figma-mcp — Figma Plugin main thread v1.2.1
 // Handles both WRITE (draw UI) and READ (extract design) operations.
 // AUTO-GENERATED by scripts/build-plugin.js — edit plugin-src/*.js instead
-// Generated: 2026-08-27T08:12:15.747Z
+// Generated: 2026-08-29T05:29:59.260Z
 
 // ── plugin-src/utils.js ──
 // ─── UTILS ────────────────────────────────────────────────────────────────────
@@ -113,6 +113,109 @@ function solidStroke(hex, strokeOpacity) {
   return [stroke];
 }
 
+// ── Variable & Token Deep Resolver ───────────────────────────────────────────
+var variableCache = new Map();
+
+async function getVariableSafeAsync(id) {
+  if (!id) return null;
+  if (variableCache.has(id)) return variableCache.get(id);
+  try {
+    if (figma.variables && typeof figma.variables.getVariableByIdAsync === "function") {
+      var v = await figma.variables.getVariableByIdAsync(id);
+      if (v) variableCache.set(id, v);
+      return v;
+    }
+  } catch(e) {}
+  return null;
+}
+
+// Recursively resolves a variable (and its VARIABLE_ALIAS chains) to concrete primitive value & hex
+async function resolveVariableValueAsync(variableOrId, contextNodeOrModeMap, depth, visited) {
+  if (!variableOrId) return null;
+  depth = depth || 0;
+  visited = visited || {};
+  if (depth > 6) return null;
+
+  var variable = null;
+  if (typeof variableOrId === "string") {
+    if (visited[variableOrId]) return null;
+    visited[variableOrId] = true;
+    variable = await getVariableSafeAsync(variableOrId);
+  } else {
+    variable = variableOrId;
+    if (variable && variable.id) {
+      if (visited[variable.id]) return null;
+      visited[variable.id] = true;
+    }
+  }
+
+  if (!variable || !variable.valuesByMode) return null;
+
+  // Determine active mode
+  var modeId = null;
+  var colId = variable.variableCollectionId;
+  if (contextNodeOrModeMap) {
+    if (typeof contextNodeOrModeMap === "object" && contextNodeOrModeMap.resolvedVariableModes) {
+      modeId = contextNodeOrModeMap.resolvedVariableModes[colId];
+    } else if (typeof contextNodeOrModeMap === "object" && contextNodeOrModeMap[colId]) {
+      modeId = contextNodeOrModeMap[colId];
+    } else if (typeof contextNodeOrModeMap === "string") {
+      modeId = contextNodeOrModeMap;
+    }
+  }
+  var availableModes = Object.keys(variable.valuesByMode);
+  if (!modeId || variable.valuesByMode[modeId] === undefined) {
+    modeId = availableModes.length > 0 ? availableModes[0] : null;
+  }
+  if (!modeId) return null;
+
+  var rawVal = variable.valuesByMode[modeId];
+  if (rawVal === undefined || rawVal === null) return null;
+
+  // If alias, follow recursively down to primitive token
+  if (typeof rawVal === "object" && rawVal.type === "VARIABLE_ALIAS" && rawVal.id) {
+    var targetResult = await resolveVariableValueAsync(rawVal.id, contextNodeOrModeMap, depth + 1, visited);
+    return {
+      type: "ALIAS",
+      name: variable.name,
+      variableId: variable.id,
+      resolvedType: variable.resolvedType,
+      targetId: rawVal.id,
+      targetName: targetResult ? (targetResult.primitiveName || targetResult.name) : null,
+      primitiveName: targetResult ? (targetResult.primitiveName || targetResult.name) : variable.name,
+      resolvedValue: targetResult ? targetResult.resolvedValue : null,
+      hex: targetResult ? targetResult.hex : null,
+      raw: rawVal,
+    };
+  }
+
+  // If RGBA color
+  if (typeof rawVal === "object" && "r" in rawVal && "g" in rawVal && "b" in rawVal) {
+    var hex = rgbToHex(rawVal);
+    var alpha = rawVal.a !== undefined ? Math.round(rawVal.a * 100) / 100 : 1;
+    return {
+      type: "COLOR",
+      name: variable.name,
+      variableId: variable.id,
+      resolvedType: "COLOR",
+      resolvedValue: hex,
+      hex: hex,
+      alpha: alpha,
+      primitiveName: variable.name,
+    };
+  }
+
+  // Primitive value
+  return {
+    type: variable.resolvedType || typeof rawVal,
+    name: variable.name,
+    variableId: variable.id,
+    resolvedType: variable.resolvedType || typeof rawVal,
+    resolvedValue: rawVal,
+    primitiveName: variable.name,
+  };
+}
+
 // Paint/effect helpers (buildFillArray, buildGradientPaint, buildEffect,
 // applyEffects, applyCornerRadii) live in paint-and-effects.js.
 
@@ -1245,7 +1348,7 @@ const handlers = {};
 
 handlers.status = async () => ({
   connected:   true,
-  version:     "3.0.0",
+  version:     "3.0.2",
   fileName:    figma.root.name,
   currentPage: figma.currentPage.name,
   pageCount:   figma.root.children.length,
@@ -3198,6 +3301,26 @@ handlers.get_node_detail = async function(params) {
         } else if (f.type === "IMAGE") {
           fd.scaleMode = f.scaleMode || "FILL";
         }
+
+        // Link bound variable token if present
+        try {
+          if (node.boundVariables && node.boundVariables.fills) {
+            var fBindings = Array.isArray(node.boundVariables.fills) ? node.boundVariables.fills : [node.boundVariables.fills];
+            if (fBindings[fi] && fBindings[fi].id) {
+              var boundVar = await resolveVariableValueAsync(fBindings[fi].id, node, 0);
+              if (boundVar) {
+                fd.boundToken = {
+                  id: fBindings[fi].id,
+                  name: boundVar.name,
+                  primitive: boundVar.primitiveName,
+                  resolvedHex: boundVar.hex || boundVar.resolvedValue,
+                };
+                if (boundVar.hex) fd.color = boundVar.hex;
+              }
+            }
+          }
+        } catch(e3) {}
+
         detail.fills.push(fd);
       }
     }
@@ -3207,14 +3330,46 @@ handlers.get_node_detail = async function(params) {
   try {
     if (node.strokes && node.strokes.length) {
       var dStrokes = node.strokes;
+      var strokeBindings = (node.boundVariables && node.boundVariables.strokes) ? (Array.isArray(node.boundVariables.strokes) ? node.boundVariables.strokes : [node.boundVariables.strokes]) : [];
+
       if (dStrokes.length === 1 && dStrokes[0].type === "SOLID") {
         detail.stroke = rgbToHex(dStrokes[0].color);
+        try {
+          if (strokeBindings[0] && strokeBindings[0].id) {
+            var boundStrokeVar = await resolveVariableValueAsync(strokeBindings[0].id, node, 0);
+            if (boundStrokeVar) {
+              detail.strokeBoundToken = {
+                id: strokeBindings[0].id,
+                name: boundStrokeVar.name,
+                primitive: boundStrokeVar.primitiveName,
+                resolvedHex: boundStrokeVar.hex || boundStrokeVar.resolvedValue,
+              };
+              if (boundStrokeVar.hex) detail.stroke = boundStrokeVar.hex;
+            }
+          }
+        } catch(e4) {}
       } else {
-        detail.strokes = dStrokes.map(function(s) {
+        detail.strokes = [];
+        for (var si = 0; si < dStrokes.length; si++) {
+          var s = dStrokes[si];
           var sd = { type: s.type };
           if (s.type === "SOLID") sd.color = rgbToHex(s.color);
-          return sd;
-        });
+          try {
+            if (strokeBindings[si] && strokeBindings[si].id) {
+              var bsv = await resolveVariableValueAsync(strokeBindings[si].id, node, 0);
+              if (bsv) {
+                sd.boundToken = {
+                  id: strokeBindings[si].id,
+                  name: bsv.name,
+                  primitive: bsv.primitiveName,
+                  resolvedHex: bsv.hex || bsv.resolvedValue,
+                };
+                if (bsv.hex) sd.color = bsv.hex;
+              }
+            }
+          } catch(e5) {}
+          detail.strokes.push(sd);
+        }
       }
       detail.strokeWeight = node.strokeWeight;
       detail.strokeAlign = node.strokeAlign;
@@ -3302,7 +3457,7 @@ handlers.get_node_detail = async function(params) {
     try { detail.textAlign = node.textAlignHorizontal ? node.textAlignHorizontal.toLowerCase() : null; } catch(e) {}
   }
 
-  // P1: Resolve bound variables → name + resolvedType + value (not just IDs)
+  // P1: Resolve bound variables → name + resolvedType + value (deep recursive resolution)
   try {
     if (node.boundVariables) {
       var bv = {};
@@ -3318,16 +3473,18 @@ handlers.get_node_detail = async function(params) {
           if (!alias || !alias.id) continue;
           var entry = { id: alias.id };
           try {
-            var variable = await figma.variables.getVariableByIdAsync(alias.id);
+            var variable = await getVariableSafeAsync(alias.id);
             if (variable) {
               entry.name = variable.name;
               entry.resolvedType = variable.resolvedType;
-              // Get first mode value as preview
-              var modeIds = Object.keys(variable.valuesByMode);
-              if (modeIds.length > 0) {
-                var val = variable.valuesByMode[modeIds[0]];
-                if (val && typeof val === "object" && "r" in val) entry.value = rgbToHex(val);
-                else entry.value = val;
+              var resolvedToken = await resolveVariableValueAsync(variable, node, 0);
+              if (resolvedToken) {
+                entry.value = resolvedToken.resolvedValue !== undefined ? resolvedToken.resolvedValue : (resolvedToken.hex || resolvedToken.value);
+                if (resolvedToken.type === "ALIAS") {
+                  entry.aliasTarget = resolvedToken.targetName;
+                  entry.primitiveName = resolvedToken.primitiveName;
+                  entry.resolvedValue = resolvedToken.resolvedValue;
+                }
               }
             }
           } catch(e2) {}
@@ -3694,6 +3851,12 @@ handlers.get_design_context = async function(params) {
   };
 };
 
+// Aliases for developer convenience & MCP tool naming compatibility
+handlers.inspect_node = handlers.get_design_context;
+handlers.inspect = handlers.get_design_context;
+handlers.get_node_info = handlers.get_node_detail;
+handlers.node_detail = handlers.get_node_detail;
+
 // get_component_map — list every component instance in a frame with variant properties
 // Use this to map Figma components to their code equivalents
 handlers.get_component_map = async function(params) {
@@ -3944,22 +4107,37 @@ handlers.get_variables = async function() {
       }
     } catch(e) { /* fall back to per-id lookups */ }
 
+    var resolvedTokensMap = {};
+
     for (var ci = 0; ci < localCollections.length; ci++) {
       var col = localCollections[ci];
       var variables = [];
       for (var vi = 0; vi < col.variableIds.length; vi++) {
         var vid = col.variableIds[vi];
-        var v = bulkLoaded ? varsById[vid] : await figma.variables.getVariableByIdAsync(vid);
+        var v = bulkLoaded ? varsById[vid] : await getVariableSafeAsync(vid);
         if (!v) continue;
         var values = {};
         for (var modeId in v.valuesByMode) {
           if (Object.prototype.hasOwnProperty.call(v.valuesByMode, modeId)) {
             var val = v.valuesByMode[modeId];
-            // Convert color values to hex
             if (val && typeof val === "object" && "r" in val && "g" in val && "b" in val) {
-              values[modeId] = rgbToHex(val);
+              var hexVal = rgbToHex(val);
+              values[modeId] = hexVal;
+              resolvedTokensMap[v.name] = hexVal;
+            } else if (val && typeof val === "object" && val.type === "VARIABLE_ALIAS" && val.id) {
+              var resolvedAlias = await resolveVariableValueAsync(val.id, modeId, 1);
+              var finalHexOrVal = resolvedAlias ? (resolvedAlias.resolvedValue || resolvedAlias.hex || resolvedAlias.value) : null;
+              values[modeId] = {
+                type: "VARIABLE_ALIAS",
+                aliasId: val.id,
+                aliasName: resolvedAlias ? resolvedAlias.name : null,
+                primitiveName: resolvedAlias ? resolvedAlias.primitiveName : null,
+                resolvedValue: finalHexOrVal,
+              };
+              if (finalHexOrVal) resolvedTokensMap[v.name] = finalHexOrVal;
             } else {
               values[modeId] = val;
+              if (val !== undefined && val !== null) resolvedTokensMap[v.name] = val;
             }
           }
         }
@@ -3984,9 +4162,12 @@ handlers.get_variables = async function() {
   } catch(e) {
     return { error: "Variables API not available: " + e.message, collections: [] };
   }
-  return { collections: collections };
+  return { collections: collections, resolvedTokens: resolvedTokensMap };
 };
 
+handlers.get_tokens = handlers.get_variable_tokens;
+handlers.tokens = handlers.get_variable_tokens;
+
 // ─── EXPORT ASSETS (Batch Icon & Image Extractor) ────────────────────────────
 handlers.export_assets = async function(params) {
   var id = params ? (params.id || params.nodeId) : null;