figma-console-mcp 1.15.3 → 1.15.5

package/dist/cloudflare/core/port-discovery.js

@@ -265,6 +265,77 @@ export function cleanupStalePortFiles() {
     }
     return cleaned;
 }
+/**
+ * Deep scan for orphaned MCP server processes that hold ports but have no port files.
+ * These are processes left behind by Claude Desktop when tabs close without proper cleanup.
+ *
+ * Uses lsof (macOS/Linux) to find PIDs listening on each port in the range,
+ * then verifies they're figma-console-mcp before terminating.
+ *
+ * Call AFTER cleanupStalePortFiles() — that handles the port-file-based cleanup first,
+ * then this catches any remaining ghosts.
+ */
+export function cleanupOrphanedProcesses(preferredPort = DEFAULT_WS_PORT) {
+    // Only supported on macOS/Linux (lsof)
+    if (process.platform === 'win32')
+        return 0;
+    let cleaned = 0;
+    const myPid = process.pid;
+    const ports = getPortRange(preferredPort);
+    // Collect PIDs that have valid port files (known-good servers)
+    const knownPids = new Set();
+    for (const port of ports) {
+        const data = readPortFile(port);
+        if (data)
+            knownPids.add(data.pid);
+    }
+    knownPids.add(myPid); // Never kill ourselves
+    for (const port of ports) {
+        try {
+            // Find PIDs listening on this port via lsof
+            const { execSync } = require('child_process');
+            const output = execSync(`lsof -i :${port} -sTCP:LISTEN -t 2>/dev/null`, {
+                encoding: 'utf-8',
+                timeout: 3000,
+            }).trim();
+            if (!output)
+                continue;
+            const pids = output.split('\n').map(Number).filter(Boolean);
+            for (const pid of pids) {
+                if (knownPids.has(pid))
+                    continue; // Skip known-good servers
+                // Verify this is actually a figma-console-mcp process before killing
+                try {
+                    const cmdline = execSync(`ps -p ${pid} -o command= 2>/dev/null`, {
+                        encoding: 'utf-8',
+                        timeout: 2000,
+                    }).trim();
+                    if (cmdline.includes('figma-console-mcp') || cmdline.includes('figma_console_mcp') || cmdline.includes('local.js')) {
+                        logger.info({ port, pid, command: cmdline.substring(0, 120) }, 'Terminating orphaned MCP server (no port file, holding port)');
+                        terminateProcess(pid);
+                        cleaned++;
+                    }
+                }
+                catch {
+                    // Can't read process info — skip to be safe
+                }
+            }
+        }
+        catch {
+            // lsof failed for this port — skip
+        }
+    }
+    if (cleaned > 0) {
+        // Give terminated processes a moment to release their ports
+        try {
+            const { execSync } = require('child_process');
+            execSync('sleep 0.5', { timeout: 2000 });
+        }
+        catch { /* non-critical */ }
+        logger.info({ cleaned }, `Cleaned up ${cleaned} orphaned MCP server process(es)`);
+    }
+    return cleaned;
+}
 /**
  * Register process exit handlers to clean up port advertisement file.
  * Should be called once after the port is successfully bound.

package/dist/cloudflare/core/websocket-server.js

@@ -14,7 +14,8 @@
  */
 import { WebSocketServer as WSServer, WebSocket } from 'ws';
 import { EventEmitter } from 'events';
-import { readFileSync } from 'fs';
+import { createServer as createHttpServer } from 'http';
+import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import { createChildLogger } from './logger.js';
 // Read version from package.json
@@ -27,11 +28,37 @@ try {
 catch {
     // Non-critical — version will show as 0.0.0
 }
+/**
+ * Load the full plugin UI HTML content that gets served to the bootloader.
+ * Falls back to a minimal error page if the file isn't found.
+ */
+function loadPluginUIContent() {
+    const candidates = [
+        // ESM runtime: dist/core/ → ../../figma-desktop-bridge/
+        typeof __dirname !== 'undefined'
+            ? join(__dirname, '..', '..', 'figma-desktop-bridge', 'ui-full.html')
+            : join(process.cwd(), 'figma-desktop-bridge', 'ui-full.html'),
+        // Direct from project root
+        join(process.cwd(), 'figma-desktop-bridge', 'ui-full.html'),
+    ];
+    for (const path of candidates) {
+        try {
+            if (existsSync(path)) {
+                return readFileSync(path, 'utf-8');
+            }
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return '<html><body><p>Plugin UI not found. Please reinstall figma-console-mcp.</p></body></html>';
+}
 const logger = createChildLogger({ component: 'websocket-server' });
 export class FigmaWebSocketServer extends EventEmitter {
     constructor(options) {
         super();
         this.wss = null;
+        this.httpServer = null;
         /** Named clients indexed by fileKey — each represents a connected Figma file */
         this.clients = new Map();
         /** Clients awaiting FILE_INFO identification, mapped to their pending timeout */
@@ -44,20 +71,74 @@ export class FigmaWebSocketServer extends EventEmitter {
         this._startedAt = Date.now();
         this.consoleBufferSize = 1000;
         this.documentChangeBufferSize = 200;
+        /** Cached plugin UI HTML content — loaded once and served to bootloader requests */
+        this._pluginUIContent = null;
         this.options = options;
         this._startedAt = Date.now();
     }
     /**
-     * Start the WebSocket server
+     * Handle HTTP requests on the same port as WebSocket.
+     * Serves plugin UI content for the bootloader and health checks.
+     */
+    handleHttpRequest(req, res) {
+        // CORS headers for Figma plugin iframe (sandboxed, origin: null)
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        const url = req.url || '/';
+        // Plugin UI endpoint — bootloader redirects here
+        if (url === '/plugin/ui' || url === '/plugin/ui/') {
+            if (!this._pluginUIContent) {
+                this._pluginUIContent = loadPluginUIContent();
+            }
+            res.writeHead(200, {
+                'Content-Type': 'text/html; charset=utf-8',
+                'Cache-Control': 'no-cache, no-store, must-revalidate',
+            });
+            res.end(this._pluginUIContent);
+            return;
+        }
+        // Health/version endpoint
+        if (url === '/health' || url === '/') {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                status: 'ok',
+                version: SERVER_VERSION,
+                clients: this.clients.size,
+                uptime: Math.floor((Date.now() - this._startedAt) / 1000),
+            }));
+            return;
+        }
+        // 404 for anything else
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        res.end('Not Found');
+    }
+    /**
+     * Start the HTTP + WebSocket server.
+     * HTTP serves the plugin UI content; WebSocket handles plugin communication.
      */
     async start() {
         if (this._isStarted)
             return;
         return new Promise((resolve, reject) => {
+            let rejected = false;
+            const rejectOnce = (error) => {
+                if (!rejected) {
+                    rejected = true;
+                    reject(error);
+                }
+            };
             try {
+                // Create HTTP server first — handles plugin UI requests
+                this.httpServer = createHttpServer((req, res) => this.handleHttpRequest(req, res));
+                // Attach WebSocket server to the HTTP server (shares the same port)
                 this.wss = new WSServer({
-                    port: this.options.port,
-                    host: this.options.host || 'localhost',
+                    server: this.httpServer,
                     maxPayload: 100 * 1024 * 1024, // 100MB — screenshots and large component data can be big
                     verifyClient: (info, callback) => {
                         // Mitigate Cross-Site WebSocket Hijacking (CSWSH):
@@ -76,18 +157,38 @@ export class FigmaWebSocketServer extends EventEmitter {
                         }
                     },
                 });
-                this.wss.on('listening', () => {
-                    this._isStarted = true;
-                    logger.info({ port: this.options.port, host: this.options.host || 'localhost' }, 'WebSocket bridge server started');
-                    resolve();
-                });
-                this.wss.on('error', (error) => {
+                // Error handler for startup failures (EADDRINUSE, etc.)
+                // Must be on BOTH httpServer and wss — the WSS re-emits HTTP server errors
+                // and throws if no listener is attached.
+                const onStartupError = (error) => {
                     if (!this._isStarted) {
-                        reject(error);
+                        try {
+                            if (this.wss) {
+                                this.wss.close();
+                                this.wss = null;
+                            }
+                        }
+                        catch { /* ignore */ }
+                        try {
+                            if (this.httpServer) {
+                                this.httpServer.close();
+                                this.httpServer = null;
+                            }
+                        }
+                        catch { /* ignore */ }
+                        rejectOnce(error);
                     }
                     else {
-                        logger.error({ error }, 'WebSocket server error');
+                        logger.error({ error }, 'HTTP/WebSocket server error');
                     }
+                };
+                this.httpServer.on('error', onStartupError);
+                this.wss.on('error', onStartupError);
+                // Start listening on the HTTP server (which also handles WS upgrades)
+                this.httpServer.listen(this.options.port, this.options.host || 'localhost', () => {
+                    this._isStarted = true;
+                    logger.info({ port: this.options.port, host: this.options.host || 'localhost' }, 'WebSocket bridge server started (with HTTP plugin UI endpoint)');
+                    resolve();
                 });
                 this.wss.on('connection', (ws) => {
                     // Add to pending until FILE_INFO identifies the file
@@ -146,7 +247,7 @@ export class FigmaWebSocketServer extends EventEmitter {
                 });
             }
             catch (error) {
-                reject(error);
+                rejectOnce(error);
             }
         });
     }
@@ -177,6 +278,22 @@ export class FigmaWebSocketServer extends EventEmitter {
             }
             return;
         }
+        // Bootloader request: send the full plugin UI HTML
+        if (message.type === 'GET_PLUGIN_UI') {
+            if (!this._pluginUIContent) {
+                this._pluginUIContent = loadPluginUIContent();
+            }
+            try {
+                ws.send(JSON.stringify({
+                    type: 'PLUGIN_UI_CONTENT',
+                    html: this._pluginUIContent,
+                }));
+            }
+            catch {
+                // Non-critical — bootloader will show error
+            }
+            return;
+        }
         // Unsolicited data from plugin (FILE_INFO, events, forwarded data)
         if (message.type) {
             // FILE_INFO promotes pending clients to named clients
@@ -434,11 +551,19 @@ export class FigmaWebSocketServer extends EventEmitter {
      * Returns the actual port — critical when using port 0 for OS-assigned ports.
      */
     address() {
+        // Use the HTTP server's address (which is the actual listening socket)
+        if (this.httpServer) {
+            const addr = this.httpServer.address();
+            if (typeof addr === 'string' || !addr)
+                return null;
+            return addr;
+        }
+        // Fallback for backward compat
         if (!this.wss)
             return null;
         const addr = this.wss.address();
         if (typeof addr === 'string')
-            return null; // Unix socket path, not applicable
+            return null;
         return addr;
     }
     // ============================================================================
@@ -632,15 +757,20 @@ export class FigmaWebSocketServer extends EventEmitter {
         }
         this.clients.clear();
         this._activeFileKey = null;
+        // Close WS server first (handles WebSocket connections)
         if (this.wss) {
-            return new Promise((resolve) => {
-                this.wss.close(() => {
-                    this._isStarted = false;
-                    logger.info('WebSocket bridge server stopped');
-                    resolve();
-                });
+            await new Promise((resolve) => {
+                this.wss.close(() => resolve());
+            });
+        }
+        // Then close HTTP server (releases the port)
+        if (this.httpServer) {
+            await new Promise((resolve) => {
+                this.httpServer.close(() => resolve());
             });
+            this.httpServer = null;
         }
         this._isStarted = false;
+        logger.info('WebSocket bridge server stopped');
     }
 }

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

@@ -17,7 +17,15 @@ export function registerWriteTools(server, getDesktopConnector) {
 
 **VALIDATION:** After creating/modifying visuals: screenshot with figma_capture_screenshot, check alignment/spacing/proportions, iterate up to 3x.
 
-**PLACEMENT:** Always create components inside a Section or Frame, never on blank canvas. Use parent.insertChild(0, bg) for z-ordering backgrounds behind content.`, {
+**PLACEMENT:** Always create components inside a Section or Frame, never on blank canvas. Use parent.insertChild(0, bg) for z-ordering backgrounds behind content.
+
+**HOUSEKEEPING (MANDATORY):**
+Before creating: screenshot the target page to see existing content and find clear space.
+When creating: place inside a named Section, positioned BELOW or AWAY from existing content. Never overlap.
+After creating: screenshot to verify clean placement and no overlaps.
+On failure/retry: DELETE any partial artifacts (empty frames, orphaned layers, blank pages) before retrying. Use node.remove() to clean up.
+Pages: NEVER create a new page if one with that name already exists — use the existing one. If you created a blank page during a failed attempt, delete it.
+Layers: If your code creates helper frames, placeholder nodes, or intermediate layers that aren't part of the final result, remove them.`, {
         code: z
             .string()
             .describe("JavaScript code to execute. Has access to the 'figma' global object. " +
@@ -1476,7 +1484,7 @@ After instantiating components, use figma_take_screenshot to verify the result l
         }
     });
     // Tool: Create Child Node
-    server.tool("figma_create_child", "Create a new child node inside a parent container. Useful for adding shapes, text, or frames to existing structures.", {
+    server.tool("figma_create_child", "Create a new child node inside a parent container. Always place inside an existing Section or Frame — never on a bare page. If no suitable parent exists, create a Section first. Clean up any empty or orphaned nodes if the operation fails.", {
         parentId: z.string().describe("The parent node ID"),
         nodeType: z
             .enum(["RECTANGLE", "ELLIPSE", "FRAME", "TEXT", "LINE"])

package/dist/cloudflare/index.js

@@ -38,7 +38,7 @@ export class FigmaConsoleMCPv3 extends McpAgent {
         super(...arguments);
         this.server = new McpServer({
             name: "Figma Console MCP",
-            version: "1.13.0",
+            version: "1.15.5",
         });
         this.browserManager = null;
         this.consoleMonitor = null;
@@ -950,7 +950,7 @@ export default {
             });
             const statelessServer = new McpServer({
                 name: "Figma Console MCP",
-                version: "1.13.0",
+                version: "1.15.5",
             });
             // ================================================================
             // Cloud Write Relay — Pairing Tool (stateless /mcp path)
@@ -1579,7 +1579,7 @@ export default {
             return new Response(JSON.stringify({
                 status: "healthy",
                 service: "Figma Console MCP",
-                version: "1.13.0",
+                version: "1.15.5",
                 endpoints: {
                     mcp: ["/sse", "/mcp"],
                     oauth_mcp_spec: ["/.well-known/oauth-authorization-server", "/authorize", "/token", "/oauth/register"],
@@ -1625,13 +1625,13 @@ export default {
 	<meta name="viewport" content="width=device-width, initial-scale=1.0">
 	<title>Figma Console MCP - The Most Comprehensive MCP Server for Figma</title>
 	<link rel="icon" type="image/svg+xml" href="https://docs.figma-console-mcp.southleft.com/favicon.svg">
-	<meta name="description" content="Turn your Figma design system into a living API. 59+ tools give AI assistants deep access to design tokens, component specs, variables, and programmatic design creation.">
+	<meta name="description" content="Turn your Figma design system into a living API. 63+ tools give AI assistants deep access to design tokens, component specs, variables, and programmatic design creation.">
 
 	<!-- Open Graph -->
 	<meta property="og:type" content="website">
 	<meta property="og:url" content="https://figma-console-mcp.southleft.com">
 	<meta property="og:title" content="Figma Console MCP - Turn Your Design System Into a Living API">
-	<meta property="og:description" content="The most comprehensive MCP server for Figma. 59+ tools give AI assistants deep access to design tokens, components, variables, and programmatic design creation.">
+	<meta property="og:description" content="The most comprehensive MCP server for Figma. 63+ tools give AI assistants deep access to design tokens, components, variables, and programmatic design creation.">
 	<meta property="og:image" content="https://docs.figma-console-mcp.southleft.com/images/og-image.jpg">
 	<meta property="og:image:width" content="1200">
 	<meta property="og:image:height" content="630">
@@ -1639,7 +1639,7 @@ export default {
 	<!-- Twitter -->
 	<meta name="twitter:card" content="summary_large_image">
 	<meta name="twitter:title" content="Figma Console MCP - Turn Your Design System Into a Living API">
-	<meta name="twitter:description" content="The most comprehensive MCP server for Figma. 59+ tools give AI assistants deep access to design tokens, components, variables, and programmatic design creation.">
+	<meta name="twitter:description" content="The most comprehensive MCP server for Figma. 63+ tools give AI assistants deep access to design tokens, components, variables, and programmatic design creation.">
 	<meta name="twitter:image" content="https://docs.figma-console-mcp.southleft.com/images/og-image.jpg">
 
 	<meta name="theme-color" content="#0D9488">

package/dist/local.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../src/local.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;GAYG;AAiFH;;;GAGG;AACH,cAAM,oBAAoB;IACzB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,cAAc,CAAoC;IAC1D,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,gBAAgB,CAAgC;IACxD,OAAO,CAAC,QAAQ,CAAqC;IACrD,OAAO,CAAC,cAAc,CAA+C;IACrE,uGAAuG;IACvG,OAAO,CAAC,YAAY,CAAuB;IAC3C,6DAA6D;IAC7D,OAAO,CAAC,eAAe,CAA2B;IAClD,8EAA8E;IAC9E,OAAO,CAAC,gBAAgB,CAA+C;IACvE,OAAO,CAAC,MAAM,CAAe;IAI7B,OAAO,CAAC,cAAc,CAMR;;IA2Ed;;OAEG;YACW,WAAW;IA0BzB;;;OAGG;YACW,mBAAmB;IA6CjC;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAiBzB;;OAEG;YACW,iBAAiB;IAqB/B,wDAAwD;IACxD,OAAO,CAAC,gBAAgB,CAAuB;IAE/C;;;OAGG;IACH,OAAO,CAAC,aAAa;IAgBrB;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAuB1B;;OAEG;YACW,iBAAiB;IA+I/B;;OAEG;IACH,OAAO,CAAC,aAAa;IA09KrB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAgK5B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAgC/B;AA4ED,OAAO,EAAE,oBAAoB,EAAE,CAAC"}
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../src/local.ts"],"names":[],"mappings":";AAEA;;;;;;;;;;;;GAYG;AAiFH;;;GAGG;AACH,cAAM,oBAAoB;IACzB,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,cAAc,CAAoC;IAC1D,OAAO,CAAC,cAAc,CAA+B;IACrD,OAAO,CAAC,QAAQ,CAAyB;IACzC,OAAO,CAAC,gBAAgB,CAAgC;IACxD,OAAO,CAAC,QAAQ,CAAqC;IACrD,OAAO,CAAC,cAAc,CAA+C;IACrE,uGAAuG;IACvG,OAAO,CAAC,YAAY,CAAuB;IAC3C,6DAA6D;IAC7D,OAAO,CAAC,eAAe,CAA2B;IAClD,8EAA8E;IAC9E,OAAO,CAAC,gBAAgB,CAA+C;IACvE,OAAO,CAAC,MAAM,CAAe;IAI7B,OAAO,CAAC,cAAc,CAMR;;IA2Ed;;OAEG;YACW,WAAW;IA0BzB;;;OAGG;YACW,mBAAmB;IA6CjC;;;;OAIG;IACH,OAAO,CAAC,iBAAiB;IAiBzB;;OAEG;YACW,iBAAiB;IAqB/B,wDAAwD;IACxD,OAAO,CAAC,gBAAgB,CAAuB;IAE/C;;;OAGG;IACH,OAAO,CAAC,aAAa;IAgBrB;;;;OAIG;IACH,OAAO,CAAC,kBAAkB;IAuB1B;;OAEG;YACW,iBAAiB;IA+I/B;;OAEG;IACH,OAAO,CAAC,aAAa;IAk/KrB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAgK5B;;OAEG;IACG,QAAQ,IAAI,OAAO,CAAC,IAAI,CAAC;CAgC/B;AA4ED,OAAO,EAAE,oBAAoB,EAAE,CAAC"}

package/dist/local.js

@@ -1122,7 +1122,7 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
                                         : this.wsStartupError?.code === "EADDRINUSE"
                                             ? `❌ All WebSocket ports ${this.wsPreferredPort}-${this.wsPreferredPort + 9} are in use`
                                             : this.wsActualPort !== null && this.wsActualPort !== this.wsPreferredPort
-                                                ? `❌ WebSocket server running on port ${this.wsActualPort} (fallback) but no plugin connected. Re-import the Desktop Bridge plugin in Figma to enable multi-port scanning.`
+                                                ? `❌ WebSocket server running on port ${this.wsActualPort} (fallback) but no plugin connected. Restart the Desktop Bridge plugin in Figma to reconnect.`
                                                 : "❌ No connection to Figma Desktop",
                                     setupInstructions: !setupValid
                                         ? this.wsStartupError?.code === "EADDRINUSE"
@@ -1138,7 +1138,7 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
                                         ? this.wsStartupError?.code === "EADDRINUSE"
                                             ? `All WebSocket ports in range ${this.wsPreferredPort}-${this.wsPreferredPort + 9} are in use — most likely multiple Claude Desktop tabs or terminal sessions are running the Figma Console MCP server. Ask the user to close some sessions and restart.`
                                             : this.wsActualPort !== null && this.wsActualPort !== this.wsPreferredPort
-                                                ? `Server is running on fallback port ${this.wsActualPort} (port ${this.wsPreferredPort} was taken by another instance). The Desktop Bridge plugin is not connected — most likely because the plugin has old code that only scans port ${this.wsPreferredPort}. TELL THE USER: Re-import the Desktop Bridge plugin in Figma (Plugins → Development → Import plugin from manifest) to update it with multi-port scanning support. This is a one-time step.${this.getPluginPath() ? ' The manifest file is at: ' + this.getPluginPath() : ''}`
+                                                ? `Server is running on fallback port ${this.wsActualPort} (port ${this.wsPreferredPort} was taken by another instance). The Desktop Bridge plugin is not connected. TELL THE USER: Close and reopen the Desktop Bridge plugin in Figma to reconnect. The plugin's bootloader will automatically scan all ports in the range.`
                                                 : `No connection to Figma Desktop. Open the Desktop Bridge plugin in Figma to connect.${this.getPluginPath() ? ' Plugin manifest: ' + this.getPluginPath() : ''}`
                                         : activeTransport === "websocket"
                                             ? `Connected via WebSocket Bridge to "${currentFileName || "unknown file"}" on port ${this.wsActualPort}. All design tools and console monitoring tools are available. Console logs are captured from the plugin sandbox (code.js). IMPORTANT: Always verify the file name before destructive operations when multiple files have the plugin open.`
@@ -3114,6 +3114,11 @@ Without libraryFileKey/libraryFileUrl, searches the currently open file (local c
 **For local components:** Pass BOTH componentKey AND nodeId together. Most local/unpublished components require nodeId.
 **For library components:** Pass just the componentKey from figma_get_library_components or figma_search_components (with libraryFileKey). The component will be imported from the published library automatically.
 
+**CRITICAL: Use VARIANT keys, not COMPONENT_SET keys!**
+When importing from a published library, use the key of a specific variant (type: "COMPONENT"), NOT the parent component set key (type: "COMPONENT_SET"). Component set keys will fail with importComponentByKeyAsync. In figma_get_library_components results, look inside the "variants" array for individual variant keys.
+
+**Font loading:** Library components may use fonts not loaded in the current file. If instantiation fails with a font error, load the required fonts first via figma_execute before retrying (e.g., \`await figma.loadFontAsync({ family: "Geist", style: "Regular" })\`).
+
 **IMPORTANT: Always re-search before instantiating!**
 NodeIds are session-specific and may be stale from previous conversations. ALWAYS search for components at the start of each design session to get current, valid identifiers.
 
@@ -3202,8 +3207,12 @@ After instantiating components, use figma_take_screenshot to verify the result l
 
 **WORKFLOW:**
 1. Call this tool with the library file's URL or file key
-2. Browse the returned components (with keys, names, variants)
-3. Use figma_instantiate_component with the componentKey to place them in the current file
+2. Browse the returned components — results include COMPONENT_SET (with variants array) and standalone COMPONENT types
+3. Use figma_instantiate_component with a VARIANT key (from the variants array inside a COMPONENT_SET result, NOT the component set key itself)
+
+**SEARCH NOTE:** The query filter matches both component names AND descriptions. If you get unexpected results (e.g., "Accordion" when searching "Button"), verify the result name matches what you need — it may have matched on a description mention.
+
+**MULTI-FILE TIP:** If you need to find a specific component and REST API search returns too many results, you can switch to the library file via figma_navigate, use figma_execute to find the exact component and its variant key, then switch back.
 
 **NOTE:** Requires FIGMA_ACCESS_TOKEN to be set (uses the Figma REST API to read the library file).`, {
             libraryFileUrl: z
@@ -3272,13 +3281,19 @@ After instantiating components, use figma_take_screenshot to verify the result l
                 // Use REST API to get published components from the library file
                 const api = await this.getFigmaAPI();
                 // Fetch both components and component sets in parallel
+                // Surface errors instead of swallowing them — token/scope issues need to be visible
+                const apiErrors = [];
                 const [componentsResponse, componentSetsResponse] = await Promise.all([
                     api.getComponents(fileKey).catch((err) => {
+                        const msg = err.message || String(err);
                         logger.warn({ error: err }, "Failed to fetch components from library");
+                        apiErrors.push(`Components API: ${msg}`);
                         return { meta: { components: [] } };
                     }),
                     api.getComponentSets(fileKey).catch((err) => {
+                        const msg = err.message || String(err);
                         logger.warn({ error: err }, "Failed to fetch component sets from library");
+                        apiErrors.push(`Component Sets API: ${msg}`);
                         return { meta: { component_sets: [] } };
                     }),
                 ]);
@@ -3374,9 +3389,13 @@ After instantiating components, use figma_take_screenshot to verify the result l
                         {
                             type: "text",
                             text: JSON.stringify({
-                                success: true,
+                                success: apiErrors.length === 0,
                                 libraryFileKey: fileKey,
                                 query: query || "(all)",
+                                ...(apiErrors.length > 0 && {
+                                    apiErrors,
+                                    hint: "REST API errors occurred. Check that FIGMA_ACCESS_TOKEN is valid and has file_content:read scope. If the token is correct, the library components may not be published to a team library.",
+                                }),
                                 summary: {
                                     totalComponentSets: componentSets.length,
                                     totalStandaloneComponents: standaloneComponents.length,
@@ -3390,11 +3409,17 @@ After instantiating components, use figma_take_screenshot to verify the result l
                                     hasMore,
                                 },
                                 usage: {
-                                    instantiate: `To use a component: call figma_instantiate_component with the componentKey from results above.`,
-                                    example: paginatedResults[0]
-                                        ? `figma_instantiate_component({ componentKey: "${paginatedResults[0].key}" })`
-                                        : undefined,
-                                    note: "Components will be imported from the published library into the current file automatically.",
+                                    instantiate: `To use a component: call figma_instantiate_component with a VARIANT key (not the component set key). For COMPONENT_SET results, pick a variant from the "variants" array.`,
+                                    example: (() => {
+                                        const first = paginatedResults[0];
+                                        if (!first)
+                                            return undefined;
+                                        if (first.type === "COMPONENT_SET" && first.variants?.length > 0) {
+                                            return `figma_instantiate_component({ componentKey: "${first.variants[0].key}" }) — using first variant of "${first.name}"`;
+                                        }
+                                        return `figma_instantiate_component({ componentKey: "${first.key}" })`;
+                                    })(),
+                                    note: "IMPORTANT: Use variant keys (type COMPONENT), not component set keys (type COMPONENT_SET). Component set keys will fail. Also pre-load any custom fonts the component uses via figma_execute before instantiating.",
                                 },
                             }),
                         },