@mp3wizard/figma-console-mcp 1.15.4 → 1.19.0

package/dist/local.js

@@ -27,13 +27,17 @@ import { FigmaAPI, extractFileKey, extractFigmaUrlInfo, formatVariables, } from
 import { registerFigmaAPITools } from "./core/figma-tools.js";
 import { registerDesignCodeTools } from "./core/design-code-tools.js";
 import { registerCommentTools } from "./core/comment-tools.js";
+import { registerAnnotationTools } from "./core/annotation-tools.js";
+import { registerDeepComponentTools } from "./core/deep-component-tools.js";
 import { registerDesignSystemTools } from "./core/design-system-tools.js";
 import { FigmaDesktopConnector } from "./core/figma-desktop-connector.js";
 import { FigmaWebSocketServer } from "./core/websocket-server.js";
 import { WebSocketConnector } from "./core/websocket-connector.js";
-import { DEFAULT_WS_PORT, getPortRange, advertisePort, unadvertisePort, registerPortCleanup, discoverActiveInstances, cleanupStalePortFiles, cleanupOrphanedProcesses, refreshPortAdvertisement, HEARTBEAT_INTERVAL_MS, } from "./core/port-discovery.js";
+import { DEFAULT_WS_PORT, getPortRange, advertisePort, unadvertisePort, registerPortCleanup, discoverActiveInstances, cleanupStalePortFiles, cleanupOrphanedProcesses, evictOldestInstance, refreshPortAdvertisement, HEARTBEAT_INTERVAL_MS, } from "./core/port-discovery.js";
 import { registerTokenBrowserApp } from "./apps/token-browser/server.js";
 import { registerDesignSystemDashboardApp } from "./apps/design-system-dashboard/server.js";
+import { registerFigJamTools } from "./core/figjam-tools.js";
+import { registerSlidesTools } from "./core/slides-tools.js";
 const logger = createChildLogger({ component: "local-server" });
 /**
  * Copy plugin files to a stable directory (~/.figma-console-mcp/plugin/).
@@ -1052,6 +1056,7 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
                                 currentFileName: currentFileName ||
                                     "(unable to retrieve - Desktop Bridge may need to be opened)",
                                 currentFileKey: currentFileKey || undefined,
+                                editorType: this.wsServer?.getEditorType() || "figma",
                                 monitoredPageUrl: currentUrl,
                                 monitorWorkerCount: monitorStatus?.workerCount ?? 0,
                                 transport: {
@@ -1097,6 +1102,7 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
                                                 fileName: f.fileName,
                                                 fileKey: f.fileKey,
                                                 currentPage: f.currentPage,
+                                                editorType: f.editorType || 'figma',
                                                 isActive: f.isActive,
                                                 connectedAt: new Date(f.connectedAt).toISOString(),
                                             }));
@@ -1122,7 +1128,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 +1144,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.`
@@ -1316,6 +1322,7 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
 									if ('opacity' in node) info.opacity = node.opacity;
 									if ('cornerRadius' in node) info.cornerRadius = node.cornerRadius;
 									if ('componentProperties' in node) info.componentProperties = node.componentProperties;
+									if ('annotations' in node && node.annotations && node.annotations.length > 0) info.annotations = node.annotations;
 									results.push(info);
 								}
 								return results;`, 10000);
@@ -3115,6 +3122,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.
 
@@ -3203,8 +3215,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
@@ -3274,13 +3290,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: [] } };
                     }),
                 ]);
@@ -3376,9 +3398,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,
@@ -3392,11 +3418,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.",
                                 },
                             }),
                         },
@@ -4657,6 +4689,14 @@ return {
         registerCommentTools(this.server, () => this.getFigmaAPI(), () => this.getCurrentFileUrl());
         // Register Design System Kit tool
         registerDesignSystemTools(this.server, () => this.getFigmaAPI(), () => this.getCurrentFileUrl(), this.variablesCache);
+        // Register Annotation tools (read/write design annotations via Desktop Bridge)
+        registerAnnotationTools(this.server, () => this.getDesktopConnector());
+        // Register Deep Component tools (full Plugin API tree extraction for code generation)
+        registerDeepComponentTools(this.server, () => this.getDesktopConnector());
+        // Register FigJam-specific tools (sticky notes, connectors, tables, etc.)
+        registerFigJamTools(this.server, () => this.getDesktopConnector());
+        // Register Figma Slides tools (slide management, transitions, content)
+        registerSlidesTools(this.server, () => this.getDesktopConnector());
         // MCP Apps - gated behind ENABLE_MCP_APPS env var
         if (process.env.ENABLE_MCP_APPS === "true") {
             registerTokenBrowserApp(this.server, async (fileUrl) => {
@@ -5025,6 +5065,34 @@ return {
                     break;
                 }
             }
+            // Phase 3: If all ports exhausted, try evicting the oldest instance and retry ONCE
+            if (!boundPort && evictOldestInstance(this.wsPreferredPort)) {
+                for (const port of portsToTry) {
+                    try {
+                        this.wsServer = new FigmaWebSocketServer({ port, host: wsHost });
+                        await this.wsServer.start();
+                        const addr = this.wsServer.address();
+                        boundPort = addr?.port ?? port;
+                        this.wsActualPort = boundPort;
+                        logger.info({ wsPort: boundPort, eviction: true }, "WebSocket bridge server started after evicting stale instance");
+                        advertisePort(boundPort, wsHost);
+                        registerPortCleanup(boundPort);
+                        const heartbeatPort = boundPort;
+                        this.wsHeartbeatTimer = setInterval(() => refreshPortAdvertisement(heartbeatPort), HEARTBEAT_INTERVAL_MS);
+                        this.wsHeartbeatTimer.unref();
+                        break;
+                    }
+                    catch (wsError) {
+                        const errorCode = wsError instanceof Error ? wsError.code : undefined;
+                        if (errorCode === "EADDRINUSE") {
+                            this.wsServer = null;
+                            continue;
+                        }
+                        this.wsServer = null;
+                        break;
+                    }
+                }
+            }
             if (!boundPort) {
                 this.wsStartupError = {
                     code: "EADDRINUSE",