figma-console-mcp 1.2.5 → 1.3.0

package/README.md

@@ -1,9 +1,11 @@
 # Figma Console MCP Server
 
 [![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io/)
+[![npm](https://img.shields.io/npm/v/figma-console-mcp)](https://www.npmjs.com/package/figma-console-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Documentation](https://img.shields.io/badge/docs-docs.figma--console--mcp.southleft.com-0D9488)](https://docs.figma-console-mcp.southleft.com)
 
-> **Model Context Protocol server** that provides AI assistants with **real-time console access, visual debugging, design system extraction, and design creation** for Figma.
+> **Your design system as an API.** Model Context Protocol server that bridges design and development—giving AI assistants complete access to Figma for **extraction**, **creation**, and **debugging**.
 
 ## What is this?
 
@@ -593,7 +595,8 @@ MIT - See [LICENSE](LICENSE) file for details.
 
 ## 🔗 Links
 
-- 📖 [Full Documentation](docs/)
+- 📚 **[Documentation Site](https://docs.figma-console-mcp.southleft.com)** — Complete guides, tutorials, and API reference
+- 📖 [Local Docs](docs/) — Documentation source files
 - 🐛 [Report Issues](https://github.com/southleft/figma-console-mcp/issues)
 - 💬 [Discussions](https://github.com/southleft/figma-console-mcp/discussions)
 - 🌐 [Model Context Protocol](https://modelcontextprotocol.io/)

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

@@ -21,6 +21,62 @@ export function extractFileKey(url) {
         return null;
     }
 }
+/**
+ * Extract comprehensive URL info including branch and node IDs
+ * Supports both URL formats:
+ * - Path-based: /design/{fileKey}/branch/{branchKey}/{fileName}
+ * - Query-based: /design/{fileKey}/{fileName}?branch-id={branchId}
+ *
+ * @example https://www.figma.com/design/abc123/branch/xyz789/My-File?node-id=1-2
+ *   -> { fileKey: 'abc123', branchId: 'xyz789', nodeId: '1:2' }
+ * @example https://www.figma.com/design/abc123/My-File?branch-id=xyz789&node-id=1-2
+ *   -> { fileKey: 'abc123', branchId: 'xyz789', nodeId: '1:2' }
+ */
+export function extractFigmaUrlInfo(url) {
+    try {
+        const urlObj = new URL(url);
+        // First try: Path-based branch format /design/{fileKey}/branch/{branchKey}/{fileName}
+        const branchPathMatch = urlObj.pathname.match(/\/(design|file)\/([a-zA-Z0-9]+)\/branch\/([a-zA-Z0-9]+)/);
+        if (branchPathMatch) {
+            const fileKey = branchPathMatch[2];
+            const branchId = branchPathMatch[3];
+            const nodeIdParam = urlObj.searchParams.get('node-id');
+            const nodeId = nodeIdParam ? nodeIdParam.replace(/-/g, ':') : undefined;
+            return { fileKey, branchId, nodeId };
+        }
+        // Second try: Standard format /design/{fileKey}/{fileName} with optional ?branch-id=
+        const standardMatch = urlObj.pathname.match(/\/(design|file)\/([a-zA-Z0-9]+)/);
+        if (!standardMatch)
+            return null;
+        const fileKey = standardMatch[2];
+        const branchId = urlObj.searchParams.get('branch-id') || undefined;
+        const nodeIdParam = urlObj.searchParams.get('node-id');
+        // Convert node-id from URL format (1-2) to Figma format (1:2)
+        const nodeId = nodeIdParam ? nodeIdParam.replace(/-/g, ':') : undefined;
+        return { fileKey, branchId, nodeId };
+    }
+    catch (error) {
+        logger.error({ error, url }, 'Failed to extract Figma URL info');
+        return null;
+    }
+}
+/**
+ * Wrap a promise with a timeout
+ * @param promise The promise to wrap
+ * @param ms Timeout in milliseconds
+ * @param label Label for error message
+ * @returns Promise that rejects if timeout exceeded
+ */
+export function withTimeout(promise, ms, label) {
+    const timeoutPromise = new Promise((_, reject) => {
+        const timeoutId = setTimeout(() => {
+            reject(new Error(`${label} timed out after ${ms}ms`));
+        }, ms);
+        // Ensure timeout is cleared if promise resolves first
+        promise.finally(() => clearTimeout(timeoutId));
+    });
+    return Promise.race([promise, timeoutPromise]);
+}
 /**
  * Figma API Client
  * Makes authenticated requests to Figma REST API
@@ -95,6 +151,43 @@ export class FigmaAPI {
         }
         return this.request(endpoint);
     }
+    /**
+     * Resolve a branch key from a branch ID
+     * If branchId is provided, fetches branch data and returns the branch's unique key
+     * Otherwise returns the main file key unchanged
+     * @param fileKey The main file key from the URL
+     * @param branchId Optional branch ID from URL query param (branch-id)
+     * @returns The effective file key to use for API calls (branch key if on branch, otherwise fileKey)
+     */
+    async getBranchKey(fileKey, branchId) {
+        if (!branchId) {
+            return fileKey;
+        }
+        try {
+            logger.info({ fileKey, branchId }, 'Resolving branch key');
+            const fileData = await this.getFile(fileKey, { branch_data: true });
+            const branches = fileData.branches || [];
+            // Try to find branch by key (branchId might already be the key)
+            // or by matching other identifiers
+            const branch = branches.find((b) => b.key === branchId || b.name === branchId);
+            if (branch?.key) {
+                logger.info({ fileKey, branchId, branchKey: branch.key, branchName: branch.name }, 'Resolved branch key');
+                return branch.key;
+            }
+            // If branchId looks like a file key (alphanumeric), it might already be the branch key
+            // In this case, return it directly as it may be usable
+            if (/^[a-zA-Z0-9]+$/.test(branchId)) {
+                logger.info({ fileKey, branchId }, 'Branch ID appears to be a key, using directly');
+                return branchId;
+            }
+            logger.warn({ fileKey, branchId, availableBranches: branches.map((b) => ({ key: b.key, name: b.name })) }, 'Branch not found in file, using main file key');
+            return fileKey;
+        }
+        catch (error) {
+            logger.error({ error, fileKey, branchId }, 'Failed to resolve branch key, using main file key');
+            return fileKey;
+        }
+    }
     /**
      * GET /v1/files/:file_key/variables/local
      * Get local variables (design tokens) from a file

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

@@ -101,6 +101,11 @@ export class FigmaDesktopConnector {
             // Try to find plugin UI iframe with variables data
             for (const frame of frames) {
                 try {
+                    // Check if frame is still attached before accessing it
+                    if (frame.isDetached()) {
+                        logger.debug('Skipping detached frame');
+                        continue;
+                    }
                     const frameUrl = frame.url();
                     await this.page.evaluate((url) => {
                         console.log(`[DESKTOP_CONNECTOR] Checking frame: ${url}`);
@@ -128,10 +133,31 @@ export class FigmaDesktopConnector {
                     }
                 }
                 catch (frameError) {
-                    await this.page.evaluate((url, err) => {
-                        console.log(`[DESKTOP_CONNECTOR] Frame ${url} check failed: ${err}`);
-                    }, frame.url(), frameError instanceof Error ? frameError.message : String(frameError));
-                    logger.debug({ error: frameError, frameUrl: frame.url() }, 'Frame check failed, trying next');
+                    const errorMsg = frameError instanceof Error ? frameError.message : String(frameError);
+                    const isDetachedError = errorMsg.includes('detached') || errorMsg.includes('Execution context was destroyed');
+                    // Safely get frame URL (may fail if frame is detached)
+                    let safeFrameUrl = 'unknown';
+                    try {
+                        safeFrameUrl = frame.url();
+                    }
+                    catch {
+                        safeFrameUrl = '(detached)';
+                    }
+                    if (isDetachedError) {
+                        logger.debug({ frameUrl: safeFrameUrl }, 'Frame was detached during variables check, trying next');
+                    }
+                    else {
+                        // Only log to browser console if we can (page may still be accessible)
+                        try {
+                            await this.page.evaluate((url, err) => {
+                                console.log(`[DESKTOP_CONNECTOR] Frame ${url} check failed: ${err}`);
+                            }, safeFrameUrl, errorMsg);
+                        }
+                        catch {
+                            // Page also unavailable, just log locally
+                        }
+                        logger.debug({ error: frameError, frameUrl: safeFrameUrl }, 'Frame check failed, trying next');
+                    }
                     continue;
                 }
             }
@@ -167,6 +193,11 @@ export class FigmaDesktopConnector {
             // Try to find plugin UI iframe with requestComponentData function
             for (const frame of frames) {
                 try {
+                    // Check if frame is still attached before accessing it
+                    if (frame.isDetached()) {
+                        logger.debug('Skipping detached frame');
+                        continue;
+                    }
                     const frameUrl = frame.url();
                     await this.page.evaluate((url) => {
                         console.log(`[DESKTOP_CONNECTOR] Checking frame: ${url}`);
@@ -196,10 +227,31 @@ export class FigmaDesktopConnector {
                     }
                 }
                 catch (frameError) {
-                    await this.page.evaluate((url, err) => {
-                        console.log(`[DESKTOP_CONNECTOR] Frame ${url} check failed: ${err}`);
-                    }, frame.url(), frameError instanceof Error ? frameError.message : String(frameError));
-                    logger.debug({ error: frameError, frameUrl: frame.url() }, 'Frame check failed, trying next');
+                    const errorMsg = frameError instanceof Error ? frameError.message : String(frameError);
+                    const isDetachedError = errorMsg.includes('detached') || errorMsg.includes('Execution context was destroyed');
+                    // Safely get frame URL (may fail if frame is detached)
+                    let safeFrameUrl = 'unknown';
+                    try {
+                        safeFrameUrl = frame.url();
+                    }
+                    catch {
+                        safeFrameUrl = '(detached)';
+                    }
+                    if (isDetachedError) {
+                        logger.debug({ frameUrl: safeFrameUrl }, 'Frame was detached during component check, trying next');
+                    }
+                    else {
+                        // Only log to browser console if we can (page may still be accessible)
+                        try {
+                            await this.page.evaluate((url, err) => {
+                                console.log(`[DESKTOP_CONNECTOR] Frame ${url} check failed: ${err}`);
+                            }, safeFrameUrl, errorMsg);
+                        }
+                        catch {
+                            // Page also unavailable, just log locally
+                        }
+                        logger.debug({ error: frameError, frameUrl: safeFrameUrl }, 'Frame check failed, trying next');
+                    }
                     continue;
                 }
             }

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

@@ -3,7 +3,7 @@
  * MCP tool definitions for Figma REST API data extraction
  */
 import { z } from "zod";
-import { extractFileKey, formatVariables, formatComponentData } from "./figma-api.js";
+import { extractFileKey, extractFigmaUrlInfo, formatVariables, formatComponentData, withTimeout } from "./figma-api.js";
 import { createChildLogger } from "./logger.js";
 import { EnrichmentService } from "./enrichment/index.js";
 import { SnippetInjector } from "./snippet-injector.js";
@@ -886,7 +886,7 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             "instead of just alias references. Useful for getting color hex values without manual resolution. " +
             "Default: false."),
     }, async ({ fileUrl, includePublished, verbosity, enrich, include_usage, include_dependencies, include_exports, export_formats, format, collection, namePattern, mode, returnAsLinks, refreshCache, useConsoleFallback, parseFromConsole, page, pageSize, resolveAliases }) => {
-        // Extract fileKey outside try block so it's available in catch block
+        // Extract fileKey and optional branchId outside try block so they're available in catch block
         const url = fileUrl || getCurrentUrl();
         if (!url) {
             return {
@@ -902,8 +902,9 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
                 isError: true,
             };
         }
-        const fileKey = extractFileKey(url);
-        if (!fileKey) {
+        // Use extractFigmaUrlInfo to get fileKey, branchId, and nodeId
+        const urlInfo = extractFigmaUrlInfo(url);
+        if (!urlInfo) {
             return {
                 content: [
                     {
@@ -917,6 +918,14 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
                 isError: true,
             };
         }
+        // For branch URLs, the branchId IS the file key to use for API calls
+        // Figma branch URLs contain the branch key directly in the path
+        const fileKey = urlInfo.branchId || urlInfo.fileKey;
+        const mainFileKey = urlInfo.fileKey;
+        const branchId = urlInfo.branchId;
+        if (branchId) {
+            logger.info({ mainFileKey, branchId, effectiveFileKey: fileKey }, 'Branch URL detected, using branch key for API calls');
+        }
         try {
             // =====================================================================
             // CACHE-FIRST LOGIC: Check if we have cached data before fetching
@@ -1197,7 +1206,8 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
                 try {
                     logger.info({ fileKey, includePublished, verbosity, enrich }, "Fetching variables via REST API (priority: token detected)");
                     const api = await getFigmaAPI();
-                    const { local, published } = await api.getAllVariables(fileKey);
+                    // Wrap API call with timeout to prevent indefinite hangs (30s timeout)
+                    const { local, published } = await withTimeout(api.getAllVariables(fileKey), 30000, 'Figma Variables API');
                     let localFormatted = formatVariables(local);
                     let publishedFormatted = includePublished
                         ? formatVariables(published)
@@ -1411,7 +1421,22 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
                 }
                 catch (restError) {
                     const errorMessage = restError instanceof Error ? restError.message : String(restError);
-                    logger.warn({ error: errorMessage }, "REST API failed, will try Desktop Bridge fallback");
+                    // Detect specific error types for better logging and handling
+                    const isTimeout = errorMessage.includes('timed out');
+                    const isRateLimit = errorMessage.includes('429') || errorMessage.toLowerCase().includes('rate limit');
+                    const isAuthError = errorMessage.includes('403') || errorMessage.includes('401');
+                    if (isTimeout) {
+                        logger.warn({ error: errorMessage, fileKey }, "REST API timed out after 30s, falling back to Desktop Bridge");
+                    }
+                    else if (isRateLimit) {
+                        logger.warn({ error: errorMessage, fileKey }, "REST API rate limited (429), falling back to Desktop Bridge");
+                    }
+                    else if (isAuthError) {
+                        logger.warn({ error: errorMessage, fileKey }, "REST API auth error, check FIGMA_ACCESS_TOKEN validity");
+                    }
+                    else {
+                        logger.warn({ error: errorMessage, fileKey }, "REST API failed, will try Desktop Bridge fallback");
+                    }
                     // Don't throw - fall through to Desktop Bridge
                 }
             }