figma-console-mcp 1.19.0 → 1.19.2

package/README.md

@@ -51,9 +51,9 @@ Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
 | Real-time monitoring (console, selection) | ✅ | ❌ | ❌ |
 | Desktop Bridge plugin | ✅ | ✅ | ❌ |
 | Requires Node.js | Yes | **No** | No |
-| **Total tools available** | **89+** | **43** | **22** |
+| **Total tools available** | **90+** | **43** | **22** |
 
-> **Bottom line:** Remote SSE is **read-only** with ~38% of the tools. **Cloud Mode** unlocks write access from web AI clients without Node.js. NPX/Local Git gives the full 89+ tools with real-time monitoring.
+> **Bottom line:** Remote SSE is **read-only** with ~38% of the tools. **Cloud Mode** unlocks write access from web AI clients without Node.js. NPX/Local Git gives the full 90+ tools with real-time monitoring.
 
 ---
 
@@ -61,7 +61,7 @@ Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
 
 **Best for:** Designers who want full AI-assisted design capabilities.
 
-**What you get:** All 89+ tools including design creation, variable management, and component instantiation.
+**What you get:** All 90+ tools including design creation, variable management, and component instantiation.
 
 #### Prerequisites
 
@@ -123,7 +123,7 @@ If you're not sure where to put the JSON configuration above, here's where each
 #### Step 3: Connect to Figma Desktop
 
 **Desktop Bridge Plugin:**
-1. Open Figma Desktop normally (no special flags needed)
+1. Open Figma Desktop normally (no special flags needed) and open a file
 2. Go to **Plugins → Development → Import plugin from manifest...**
 3. Select `~/.figma-console-mcp/plugin/manifest.json` (stable path, auto-created by the MCP server)
 4. Run the plugin in your Figma file — the bootloader finds the MCP server and loads the latest UI automatically
@@ -156,7 +156,7 @@ Create a simple frame with a blue background
 
 **Best for:** Developers who want to modify source code or contribute to the project.
 
-**What you get:** Same 89+ tools as NPX, plus full source code access.
+**What you get:** Same 90+ tools as NPX, plus full source code access.
 
 #### Quick Setup
 
@@ -302,7 +302,7 @@ AI Client → Cloud MCP Server → Durable Object Relay → Desktop Bridge Plugi
 | Feature | NPX (Recommended) | Cloud Mode | Local Git | Remote SSE |
 |---------|-------------------|------------|-----------|------------|
 | **Setup time** | ~10 minutes | ~5 minutes | ~15 minutes | ~2 minutes |
-| **Total tools** | **89+** | **43** | **89+** | **22** (read-only) |
+| **Total tools** | **90+** | **43** | **90+** | **22** (read-only) |
 | **Design creation** | ✅ | ✅ | ✅ | ❌ |
 | **Variable management** | ✅ | ✅ | ✅ | ❌ |
 | **Component instantiation** | ✅ | ✅ | ✅ | ❌ |
@@ -317,7 +317,7 @@ AI Client → Cloud MCP Server → Durable Object Relay → Desktop Bridge Plugi
 | **Automatic updates** | ✅ (`@latest`) | ✅ | Manual (`git pull`) | ✅ |
 | **Source code access** | ❌ | ❌ | ✅ | ❌ |
 
-> **Key insight:** Remote SSE is read-only. Cloud Mode adds write access for web AI clients without Node.js. NPX/Local Git give the full 89+ tools.
+> **Key insight:** Remote SSE is read-only. Cloud Mode adds write access for web AI clients without Node.js. NPX/Local Git give the full 90+ tools.
 
 **📖 [Complete Feature Comparison](docs/mode-comparison.md)**
 
@@ -649,7 +649,7 @@ The **Figma Desktop Bridge** plugin is the recommended way to connect Figma to t
 - The MCP server communicates via **WebSocket** through the Desktop Bridge plugin
 - The server tries port 9223 first, then automatically falls back through ports 9224–9232 if needed
 - The plugin scans all ports in the range and connects to every active server it finds
-- All 89+ tools work through the WebSocket transport
+- All 90+ tools work through the WebSocket transport
 
 **Multiple files:** The WebSocket server supports multiple simultaneous plugin connections — one per open Figma file. Each connection is tracked by file key with independent state (selection, document changes, console logs).
 
@@ -786,7 +786,7 @@ The architecture supports adding new apps with minimal boilerplate — each app
 
 ## 🛤️ Roadmap
 
-**Current Status:** v1.17.0 (Stable) - Production-ready with FigJam + Slides support, Cloud Write Relay, Design System Kit, WebSocket-only connectivity, smart multi-file tracking, 89+ tools, Comments API, and MCP Apps
+**Current Status:** v1.17.0 (Stable) - Production-ready with FigJam + Slides support, Cloud Write Relay, Design System Kit, WebSocket-only connectivity, smart multi-file tracking, 90+ tools, Comments API, and MCP Apps
 
 **Recent Releases:**
 - [x] **v1.17.0** - Figma Slides Support: 15 new tools for managing presentations — slides, transitions, content, reordering, and navigation. Inspired by Toni Haidamous (PR #11).

package/dist/cloudflare/core/cloud-websocket-connector.js

@@ -142,6 +142,12 @@ export class CloudWebSocketConnector {
     async getAnnotationCategories() {
         return this.sendCommand('GET_ANNOTATION_CATEGORIES', {}, 5000);
     }
+    async deepGetComponent(nodeId, depth) {
+        return this.sendCommand('DEEP_GET_COMPONENT', { nodeId, depth: depth || 10 }, 30000);
+    }
+    async analyzeComponentSet(nodeId) {
+        return this.sendCommand('ANALYZE_COMPONENT_SET', { nodeId }, 30000);
+    }
     async addComponentProperty(nodeId, propertyName, type, defaultValue, options) {
         const params = { nodeId, propertyName, propertyType: type, defaultValue };
         if (options?.preferredValues)

package/dist/cloudflare/core/deep-component-tools.js

@@ -0,0 +1,128 @@
+/**
+ * Deep Component Extraction MCP Tool
+ *
+ * Provides unlimited-depth component tree extraction via the Desktop Bridge
+ * Plugin API. Returns full visual properties, resolved design token names,
+ * instance references (mainComponent), prototype reactions, and annotations
+ * at every level of the tree.
+ *
+ * This complements figma_get_component_for_development (REST API, depth 4)
+ * with deeper, richer data when the Desktop Bridge plugin is connected.
+ */
+import { z } from "zod";
+import { createChildLogger } from "./logger.js";
+const logger = createChildLogger({ component: "deep-component-tools" });
+export function registerDeepComponentTools(server, getDesktopConnector) {
+    server.tool("figma_get_component_for_development_deep", "Get a deeply nested component tree with full visual properties, resolved design token names, instance references, prototype interactions, and annotations at every level. Uses the Desktop Bridge Plugin API for unlimited depth traversal — essential for complex components like data tables, nested menus, date pickers, and compound form fields where the standard depth-4 REST API tool misses deeper structure. Returns boundVariables resolved to actual token names (not just IDs), mainComponent references for INSTANCE nodes, and reactions for interaction states. Requires Desktop Bridge plugin. For simpler components (depth ≤ 4), use figma_get_component_for_development instead.", {
+        nodeId: z
+            .string()
+            .describe("Component node ID to extract (e.g., '695:313')"),
+        depth: z.preprocess((v) => (typeof v === "string" ? Number(v) : v), z.number().optional().default(10)).describe("Maximum tree depth to traverse (default: 10, max: 20). Use higher values for deeply nested components."),
+    }, async ({ nodeId, depth = 10 }) => {
+        try {
+            const clampedDepth = Math.min(Math.max(depth, 1), 20);
+            logger.info({ nodeId, depth: clampedDepth }, "Deep component extraction");
+            const connector = await getDesktopConnector();
+            const result = await connector.deepGetComponent(nodeId, clampedDepth);
+            if (!result || (result.success === false)) {
+                throw new Error(result?.error || "Failed to extract component");
+            }
+            const data = result.data || result;
+            // Measure response size and warn if large
+            const responseJson = JSON.stringify(data);
+            const sizeKB = Math.round(responseJson.length / 1024);
+            const response = {
+                nodeId,
+                component: data,
+                metadata: {
+                    purpose: "deep_component_development",
+                    treeDepth: clampedDepth,
+                    responseSizeKB: sizeKB,
+                    variablesResolved: data._variableMapSize || 0,
+                    note: [
+                        `Deep component tree extracted via Plugin API (depth ${clampedDepth}).`,
+                        "boundVariables are resolved to token names, collections, and codeSyntax.",
+                        "INSTANCE nodes include mainComponent references (key, name, component set).",
+                        "Use this data to generate production-quality, token-aware, accessible code.",
+                        sizeKB > 200 ? "Response is large — consider targeting a specific child node for deeper analysis." : null,
+                    ].filter(Boolean).join(" "),
+                },
+            };
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(response),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error({ error }, "Deep component extraction failed");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "deep_component_failed",
+                            message: `Cannot extract deep component. ${message}`,
+                            hint: "This tool requires the Desktop Bridge plugin to be running in Figma. For REST API fallback (depth 4), use figma_get_component_for_development.",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // -----------------------------------------------------------------------
+    // Tool: figma_analyze_component_set
+    // -----------------------------------------------------------------------
+    server.tool("figma_analyze_component_set", "Analyze a Figma COMPONENT_SET to extract variant state machine and cross-variant diffs for code generation. Returns: (1) variant axes (size, state) with all values, (2) CSS pseudo-class mappings for interaction states (hover→:hover, focus→:focus-visible, disabled→:disabled, error→[aria-invalid]), (3) visual diff from default state per variant (only changed properties — fill token, stroke token, stroke weight, text color, opacity, effects, visibility), (4) component property definitions mapped to code props (BOOLEAN→boolean, TEXT→string, INSTANCE_SWAP→slot/ReactNode). Use this on the parent COMPONENT_SET node, not individual variants. Requires Desktop Bridge plugin.", {
+        nodeId: z
+            .string()
+            .describe("COMPONENT_SET node ID (the parent of all variants, e.g., '214:274')"),
+    }, async ({ nodeId }) => {
+        try {
+            logger.info({ nodeId }, "Analyzing component set");
+            const connector = await getDesktopConnector();
+            const result = await connector.analyzeComponentSet(nodeId);
+            if (!result || (result.success === false)) {
+                throw new Error(result?.error || "Failed to analyze component set");
+            }
+            const data = result.data || result;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            nodeId,
+                            analysis: data,
+                            metadata: {
+                                purpose: "variant_state_machine",
+                                note: "Use cssMapping to implement interaction states as CSS pseudo-classes/attributes. diffFromDefault shows only what changes per variant — apply as style overrides. componentProps maps to your component's TypeScript interface.",
+                            },
+                        }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error({ error }, "Component set analysis failed");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "analyze_component_set_failed",
+                            message: `Cannot analyze component set. ${message}`,
+                            hint: "This tool requires the Desktop Bridge plugin and a COMPONENT_SET node ID (not an individual variant). Use figma_search_components to find component sets.",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/cloudflare/core/design-code-tools.js

@@ -2127,7 +2127,7 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
             logger.info({ fileKey, nodeId, canonicalSource, enrich }, "Starting design-code parity check");
             const api = await getFigmaAPI();
             // Fetch component node
-            const nodesResponse = await api.getNodes(fileKey, [nodeId], { depth: 2 });
+            const nodesResponse = await api.getNodes(fileKey, [nodeId], { depth: 4 });
             const nodeData = nodesResponse?.nodes?.[nodeId];
             if (!nodeData?.document) {
                 throw new Error(`Node ${nodeId} not found in file ${fileKey}`);

package/dist/cloudflare/core/enrichment/enrichment-service.js

@@ -152,20 +152,116 @@ export class EnrichmentService {
                 }
                 enriched.styles_used = stylesUsed;
             }
-            // Extract variables used
-            if (component.boundVariables) {
-                const varsUsed = [];
-                // This would need actual variable resolution
-                enriched.variables_used = varsUsed;
-            }
-            // Detect hardcoded values (simplified for now)
-            // TODO: Implement full hardcoded value detection
-            enriched.hardcoded_values = [];
+            // Extract variables used and detect hardcoded values by walking the node tree
+            const varsUsed = [];
+            const hardcodedValues = [];
+            const variables = this.extractVariablesMap(data);
+            // Walk node tree to find boundVariables and hardcoded values
+            const walkForTokens = (node, path = "") => {
+                if (!node)
+                    return;
+                const nodePath = path ? `${path} > ${node.name || node.id}` : (node.name || node.id);
+                const bv = node.boundVariables || {};
+                // Check fills
+                if (node.fills && Array.isArray(node.fills)) {
+                    for (let i = 0; i < node.fills.length; i++) {
+                        const fill = node.fills[i];
+                        if (fill.type === "SOLID" && fill.visible !== false) {
+                            const fillBv = bv.fills;
+                            if (fillBv && (Array.isArray(fillBv) ? fillBv[i] : fillBv)) {
+                                const varRef = Array.isArray(fillBv) ? fillBv[i] : fillBv;
+                                if (varRef?.id) {
+                                    const varInfo = variables.get(varRef.id);
+                                    varsUsed.push({
+                                        variableId: varRef.id,
+                                        variableName: varInfo?.name || varRef.id,
+                                        property: "fill",
+                                        nodePath,
+                                    });
+                                }
+                            }
+                            else {
+                                // Hardcoded fill
+                                const c = fill.color;
+                                if (c) {
+                                    hardcodedValues.push({
+                                        property: "fill",
+                                        value: `rgb(${Math.round(c.r * 255)}, ${Math.round(c.g * 255)}, ${Math.round(c.b * 255)})`,
+                                        nodePath,
+                                    });
+                                }
+                            }
+                        }
+                    }
+                }
+                // Check strokes
+                if (node.strokes && Array.isArray(node.strokes)) {
+                    for (let i = 0; i < node.strokes.length; i++) {
+                        const stroke = node.strokes[i];
+                        if (stroke.type === "SOLID" && stroke.visible !== false) {
+                            const strokeBv = bv.strokes;
+                            if (strokeBv && (Array.isArray(strokeBv) ? strokeBv[i] : strokeBv)) {
+                                const varRef = Array.isArray(strokeBv) ? strokeBv[i] : strokeBv;
+                                if (varRef?.id) {
+                                    const varInfo = variables.get(varRef.id);
+                                    varsUsed.push({
+                                        variableId: varRef.id,
+                                        variableName: varInfo?.name || varRef.id,
+                                        property: "stroke",
+                                        nodePath,
+                                    });
+                                }
+                            }
+                            else {
+                                const c = stroke.color;
+                                if (c) {
+                                    hardcodedValues.push({
+                                        property: "stroke",
+                                        value: `rgb(${Math.round(c.r * 255)}, ${Math.round(c.g * 255)}, ${Math.round(c.b * 255)})`,
+                                        nodePath,
+                                    });
+                                }
+                            }
+                        }
+                    }
+                }
+                // Check spacing/sizing tokens
+                const spacingProps = ["itemSpacing", "paddingLeft", "paddingRight", "paddingTop", "paddingBottom", "cornerRadius"];
+                for (const prop of spacingProps) {
+                    if (node[prop] !== undefined && node[prop] !== 0) {
+                        if (bv[prop]?.id) {
+                            const varInfo = variables.get(bv[prop].id);
+                            varsUsed.push({
+                                variableId: bv[prop].id,
+                                variableName: varInfo?.name || bv[prop].id,
+                                property: prop,
+                                nodePath,
+                            });
+                        }
+                        else {
+                            hardcodedValues.push({
+                                property: prop,
+                                value: node[prop],
+                                nodePath,
+                            });
+                        }
+                    }
+                }
+                // Recurse into children
+                if (node.children && Array.isArray(node.children)) {
+                    for (const child of node.children) {
+                        walkForTokens(child, nodePath);
+                    }
+                }
+            };
+            walkForTokens(component);
+            enriched.variables_used = varsUsed;
+            enriched.hardcoded_values = hardcodedValues;
             // Calculate token coverage
-            const totalProps = (enriched.styles_used?.length || 0) + (enriched.variables_used?.length || 0) + (enriched.hardcoded_values?.length || 0);
-            const tokenProps = (enriched.styles_used?.length || 0) + (enriched.variables_used?.length || 0);
+            const totalProps = varsUsed.length + (enriched.styles_used?.length || 0) + hardcodedValues.length;
+            const tokenProps = varsUsed.length + (enriched.styles_used?.length || 0);
             enriched.token_coverage =
-                totalProps > 0 ? Math.round((tokenProps / totalProps) * 100) : 0;
+                totalProps > 0 ? Math.round((tokenProps / totalProps) * 100) : 100;
             this.logger.info({ componentId: component.id, coverage: enriched.token_coverage }, "Component enrichment complete");
             return enriched;
         }

package/dist/cloudflare/core/figma-api.js

@@ -341,8 +341,8 @@ export class FigmaAPI {
     /**
      * Helper: Get component metadata with properties
      */
-    async getComponentData(fileKey, nodeId) {
-        const response = await this.getNodes(fileKey, [nodeId], { depth: 2 });
+    async getComponentData(fileKey, nodeId, depth = 4) {
+        const response = await this.getNodes(fileKey, [nodeId], { depth });
         return response.nodes?.[nodeId];
     }
     /**

package/dist/cloudflare/core/figma-desktop-connector.js

@@ -937,6 +937,38 @@ export class FigmaDesktopConnector {
             throw error;
         }
     }
+    /**
+     * Analyze a component set — variant state machine + cross-variant diff
+     */
+    async analyzeComponentSet(nodeId) {
+        logger.info({ nodeId }, 'Analyzing component set via plugin UI');
+        const frame = await this.findPluginUIFrame();
+        try {
+            const result = await frame.evaluate(`window.analyzeComponentSet(${JSON.stringify(nodeId)})`);
+            logger.info({ success: result?.success }, 'Component set analysis complete');
+            return result;
+        }
+        catch (error) {
+            logger.error({ error, nodeId }, 'Component set analysis failed');
+            throw error;
+        }
+    }
+    /**
+     * Deep component extraction via plugin UI
+     */
+    async deepGetComponent(nodeId, depth) {
+        logger.info({ nodeId, depth }, 'Deep component fetch via plugin UI');
+        const frame = await this.findPluginUIFrame();
+        try {
+            const result = await frame.evaluate(`window.deepGetComponent(${JSON.stringify(nodeId)}, ${JSON.stringify(depth || 10)})`);
+            logger.info({ success: result?.success }, 'Deep component data retrieved');
+            return result;
+        }
+        catch (error) {
+            logger.error({ error, nodeId }, 'Deep component fetch failed');
+            throw error;
+        }
+    }
     /**
      * Add a component property
      */