@mp3wizard/figma-console-mcp 1.32.2 → 1.34.1

package/dist/local.js

@@ -36,7 +36,7 @@ import { registerWriteTools } from "./core/write-tools.js";
 import { registerTokensTools } from "./core/tokens-tools.js";
 import { wrapServerForIdentity } from "./core/identity.js";
 import { PACKAGE_ROOT } from "./core/resolve-package-root.js";
-import { FigmaWebSocketServer } from "./core/websocket-server.js";
+import { FigmaWebSocketServer, getBundledPluginVersion } from "./core/websocket-server.js";
 import { WebSocketConnector } from "./core/websocket-connector.js";
 import { DEFAULT_WS_PORT, getPortRange, advertisePort, unadvertisePort, registerPortCleanup, startPeriodicReaper, discoverActiveInstances, cleanupStalePortFiles, cleanupOrphanedProcesses, evictOldestInstance, refreshPortAdvertisement, HEARTBEAT_INTERVAL_MS, } from "./core/port-discovery.js";
 import { registerTokenBrowserApp } from "./apps/token-browser/server.js";
@@ -97,7 +97,6 @@ class LocalFigmaConsoleMCP {
     }
     constructor() {
         this.figmaAPI = null;
-        this.desktopConnector = null;
         this.wsServer = null;
         this.wsStartupError = null;
         /** The port the WebSocket server actually bound to (may differ from preferred if fallback occurred) */
@@ -211,9 +210,8 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
             try {
                 const wsConnector = new WebSocketConnector(this.wsServer);
                 await wsConnector.initialize();
-                this.desktopConnector = wsConnector;
                 logger.debug("Desktop connector initialized via WebSocket bridge");
-                return this.desktopConnector;
+                return wsConnector;
             }
             catch (wsError) {
                 const errorMsg = wsError instanceof Error ? wsError.message : String(wsError);
@@ -448,9 +446,11 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
                 };
             }
         });
-        // Tool 2: Take Screenshot (using Figma REST API)
+        // Tool 2: Take Screenshot (Desktop Bridge first, REST API fallback)
+        // Bridge-first: the plugin's exportAsync works on any Figma plan with no REST
+        // token, and reflects the current runtime state (no cloud-sync lag).
         // Note: For screenshots of specific components, use figma_get_component_image instead
-        this.server.tool("figma_take_screenshot", `Export an image of the current Figma page or specific node via REST API. Returns an image URL (valid 30 days). Use for visual validation after design changes — check alignment, spacing, proportions. Pass nodeId to target specific elements. For components, prefer figma_get_component_image.`, {
+        this.server.tool("figma_take_screenshot", `Export an image of the current Figma page or specific node. Uses the Desktop Bridge plugin (exportAsync) when connected — works on any plan, no REST token needed, reflects current runtime state. Falls back to the Figma REST API when the bridge is unavailable or for PDF format. Use for visual validation after design changes — check alignment, spacing, proportions. Pass nodeId to target specific elements. For components, prefer figma_get_component_image.`, {
             nodeId: z
                 .string()
                 .optional()
@@ -468,6 +468,73 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
                 .default("png")
                 .describe("Image format (default: png)"),
         }, async ({ nodeId, scale, format }) => {
+            // Callers routinely paste URL-format ids (123-456); both the Plugin
+            // API and REST response maps use colon format (123:456).
+            nodeId = nodeId?.replace(/-/g, ":");
+            // Bridge-first: exportAsync via the Desktop Bridge works on any plan
+            // (no REST token) and reflects the current runtime state. PDF is the
+            // only format exportAsync can't produce, so it goes straight to REST.
+            if (format !== "pdf" && this.wsServer?.isClientConnected()) {
+                try {
+                    const connector = await this.getDesktopConnector();
+                    // Resolve the target node the same way the REST path does;
+                    // empty string means the plugin captures the current page.
+                    let bridgeNodeId = nodeId || "";
+                    if (!bridgeNodeId) {
+                        const currentUrl = this.getCurrentFileUrl();
+                        const nodeIdParam = currentUrl
+                            ? new URL(currentUrl).searchParams.get("node-id")
+                            : null;
+                        if (nodeIdParam) {
+                            bridgeNodeId = nodeIdParam.replace(/-/g, ":");
+                        }
+                    }
+                    const bridgeFormat = format === "jpg" ? "JPG" : format === "svg" ? "SVG" : "PNG";
+                    // exportAsync scale floor is 0.5 (REST allows 0.01)
+                    const bridgeScale = Math.min(Math.max(scale, 0.5), 4);
+                    logger.info({ nodeId: bridgeNodeId, format: bridgeFormat, scale: bridgeScale }, "Capturing screenshot via Desktop Bridge (bridge-first)");
+                    let result = await connector.captureScreenshot(bridgeNodeId, {
+                        format: bridgeFormat,
+                        scale: bridgeScale,
+                    });
+                    if (result &&
+                        typeof result.success === "undefined" &&
+                        result.image) {
+                        result = { success: true, image: result };
+                    }
+                    if (!result?.success || !result.image?.base64) {
+                        throw new Error(result?.error || "Bridge screenshot returned no image");
+                    }
+                    const bridgeMimeType = bridgeFormat === "JPG"
+                        ? "image/jpeg"
+                        : bridgeFormat === "SVG"
+                            ? "image/svg+xml"
+                            : "image/png";
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    nodeId: result.image.node?.id || bridgeNodeId || null,
+                                    scale: result.image.scale,
+                                    format,
+                                    byteLength: result.image.byteLength,
+                                    source: "desktop_bridge",
+                                    note: "Screenshot captured via the Desktop Bridge plugin (current runtime state, no REST token required). The image is included below for visual analysis.",
+                                }),
+                            },
+                            {
+                                type: "image",
+                                data: result.image.base64,
+                                mimeType: bridgeMimeType,
+                            },
+                        ],
+                    };
+                }
+                catch (bridgeError) {
+                    logger.warn({ error: bridgeError }, "Desktop Bridge screenshot failed, falling back to REST API");
+                }
+            }
             try {
                 const api = await this.getFigmaAPI();
                 // Get current URL to extract file key and node ID if not provided
@@ -544,6 +611,12 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
             catch (error) {
                 logger.error({ error }, "Failed to capture screenshot");
                 const errorMessage = error instanceof Error ? error.message : String(error);
+                // FigmaAPI.request() tags real token failures with isAuthError —
+                // a bare "403" substring also matches node IDs like "403:12"
+                // and permission-denied responses, which are not token problems.
+                const isAuthError = error?.isAuthError === true ||
+                    errorMessage.toLowerCase().includes("token expired") ||
+                    errorMessage.toLowerCase().includes("invalid token");
                 return {
                     content: [
                         {
@@ -551,7 +624,9 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
                             text: JSON.stringify({
                                 error: errorMessage,
                                 message: "Failed to capture screenshot via Figma API",
-                                hint: "Make sure you've called figma_navigate to open a file, or provide a valid nodeId parameter",
+                                hint: isAuthError
+                                    ? "Your FIGMA_ACCESS_TOKEN is expired or invalid. Generate a new personal access token at figma.com → Settings → Security → Personal access tokens, then update FIGMA_ACCESS_TOKEN in your MCP config. Alternatively, open the Desktop Bridge plugin in Figma Desktop — screenshots work through the bridge without any REST token."
+                                    : "Make sure you've called figma_navigate to open a file, or provide a valid nodeId parameter. Tip: with the Desktop Bridge plugin open, screenshots don't need a REST token at all.",
                             }),
                         },
                     ],
@@ -952,6 +1027,11 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
                                     websocket: {
                                         available: wsConnected,
                                         serverRunning: this.wsServer?.isStarted() ?? false,
+                                        // Version of the plugin files this server ships — what a
+                                        // manifest re-import installs. pluginUpdateAvailable on
+                                        // connected files compares against THIS, not the server
+                                        // version (which can be newer on server-only releases).
+                                        bundledPluginVersion: getBundledPluginVersion(),
                                         port: this.wsActualPort ? String(this.wsActualPort) : null,
                                         preferredPort: String(this.wsPreferredPort),
                                         portFallbackUsed: this.wsActualPort !== null && this.wsActualPort !== this.wsPreferredPort,
@@ -981,6 +1061,8 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
                                             fileKey: wsFileInfo.fileKey,
                                             currentPage: wsFileInfo.currentPage,
                                             connectedAt: new Date(wsFileInfo.connectedAt).toISOString(),
+                                            pluginVersion: wsFileInfo.pluginVersion ?? undefined,
+                                            pluginUpdateAvailable: wsFileInfo.pluginUpdateAvailable || undefined,
                                         } : undefined,
                                         connectedFiles: (() => {
                                             const files = this.wsServer?.getConnectedFiles();
@@ -993,6 +1075,8 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
                                                 editorType: f.editorType || 'figma',
                                                 isActive: f.isActive,
                                                 connectedAt: new Date(f.connectedAt).toISOString(),
+                                                pluginVersion: f.pluginVersion ?? undefined,
+                                                pluginUpdateAvailable: f.pluginUpdateAvailable || undefined,
                                             }));
                                         })(),
                                         currentSelection: (() => {
@@ -1073,46 +1157,60 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
         // Tool: Force reconnect to Figma Desktop
         this.server.tool("figma_reconnect", "Force a complete reconnection to Figma Desktop. Use when connection seems stale or after switching files.", {}, async () => {
             try {
-                // Clear cached desktop connector to force fresh detection
-                this.desktopConnector = null;
-                let transport = "none";
-                let currentUrl = null;
-                let fileName = null;
                 // figma_reconnect is informational in WebSocket-only mode — the
-                // plugin handles its own reconnect logic. We just report whether
-                // the bridge is currently connected.
-                if (this.wsServer?.isClientConnected()) {
-                    transport = "websocket";
-                }
-                if (transport === "none") {
+                // plugin handles its own reconnect logic. A TCP-open socket is not
+                // proof of health (the plugin sandbox can be dead while ui.html
+                // still pongs), so a live roundtrip through the sandbox is the
+                // success criterion here.
+                if (!this.wsServer?.isClientConnected()) {
                     throw new Error("Cannot connect to Figma Desktop.\n\n" +
                         "Open the Desktop Bridge plugin in Figma (Plugins → Development → Figma Desktop Bridge).");
                 }
-                // Try to get the file name via whichever transport connected
-                try {
-                    const connector = await this.getDesktopConnector();
-                    const fileInfo = await connector.executeCodeViaUI("return { fileName: figma.root.name, fileKey: figma.fileKey }", 5000);
-                    if (fileInfo.success && fileInfo.result) {
-                        fileName = fileInfo.result.fileName;
+                const connector = await this.getDesktopConnector();
+                const probe = async () => connector.executeCodeViaUI("return { fileName: figma.root.name, fileKey: figma.fileKey }", 5000);
+                let fileInfo = await probe().catch(() => ({ success: false, result: null }));
+                let selfHealed = false;
+                if (!fileInfo.success) {
+                    // Sandbox-dead / wedged-relay state: attempt self-healing by
+                    // reloading the plugin iframe (RELOAD_UI re-runs figma.showUI,
+                    // which triggers a fresh port scan and reconnection). This only
+                    // works when the message relay is still partially functional —
+                    // if code.js itself is dead, the command times out and we fall
+                    // through to the honest error below.
+                    try {
+                        logger.info("Reconnect probe failed — attempting RELOAD_UI self-heal");
+                        await this.wsServer.sendCommand("RELOAD_UI", {}, 5000);
+                        // Give the fresh iframe time to rescan and re-identify
+                        await new Promise((resolve) => setTimeout(resolve, 4000));
+                        fileInfo = await probe().catch(() => ({ success: false, result: null }));
+                        selfHealed = fileInfo.success;
+                    }
+                    catch {
+                        // RELOAD_UI itself failed — the sandbox is truly unreachable
                     }
                 }
-                catch {
-                    // Non-critical - just for context
+                if (!fileInfo.success) {
+                    const probeErr = new Error("Desktop Bridge socket is open but the plugin is not responding to commands " +
+                        "(automatic plugin reload was attempted and did not help). " +
+                        "Close and reopen the Figma Console MCP plugin in Figma Desktop (Plugins → Development → Figma Console MCP).");
+                    probeErr.connectionError = this.buildConnectionError(probeErr);
+                    throw probeErr;
                 }
+                const fileName = fileInfo.result?.fileName || null;
                 return {
                     content: [
                         {
                             type: "text",
                             text: JSON.stringify({
-                                status: "reconnected",
-                                transport,
-                                currentUrl,
-                                fileName: fileName ||
-                                    "(unknown - Desktop Bridge may need to be restarted)",
+                                status: "connected",
+                                transport: "websocket",
+                                probeVerified: true,
+                                selfHealed: selfHealed || undefined,
+                                fileName,
                                 timestamp: Date.now(),
-                                message: fileName
-                                    ? `Successfully reconnected via ${transport.toUpperCase()}. Now connected to: "${fileName}"`
-                                    : `Successfully reconnected to Figma Desktop via ${transport.toUpperCase()}.`,
+                                message: selfHealed
+                                    ? `Plugin was unresponsive; automatically reloaded it and verified the connection. Connected to: "${fileName || "(unnamed file)"}"`
+                                    : `Connection verified via live roundtrip. Connected to: "${fileName || "(unnamed file)"}"`,
                             }),
                         },
                     ],
@@ -1375,8 +1473,11 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
             const { DesignSystemManifestCache, createEmptyManifest, figmaColorToHex, } = await import("./core/design-system-manifest.js");
             const cache = DesignSystemManifestCache.getInstance();
             const currentUrl = this.getCurrentFileUrl();
-            const fileKeyMatch = currentUrl?.match(/\/(file|design)\/([a-zA-Z0-9]+)/);
-            const fileKey = fileKeyMatch ? fileKeyMatch[2] : "unknown";
+            // extractFileKey is branch-aware: on /design/KEY/branch/BRANCH_KEY/…
+            // URLs the branch key is the effective file key — an ad-hoc regex
+            // here returned the main key and cached the wrong manifest for
+            // branch files.
+            const fileKey = (currentUrl ? extractFileKey(currentUrl) : null) ?? "unknown";
             // Check cache first
             let cacheEntry = cache.get(fileKey);
             if (cacheEntry) {
@@ -1431,7 +1532,10 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
                 logger.warn({ error }, "Could not fetch variables during auto-load");
             }
             // Get components
+            // Maps are keyed by component key (unique) rather than name — same-named
+            // components on different pages would silently overwrite each other.
             let rawComponents;
+            let componentsFetchError = null;
             try {
                 const componentsResult = await connector.getLocalComponents();
                 if (componentsResult.success && componentsResult.data) {
@@ -1440,7 +1544,7 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
                         componentSets: componentsResult.data.componentSets || [],
                     };
                     for (const comp of rawComponents.components) {
-                        manifest.components[comp.name] = {
+                        manifest.components[comp.key || comp.nodeId] = {
                             key: comp.key,
                             nodeId: comp.nodeId,
                             name: comp.name,
@@ -1449,7 +1553,7 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
                         };
                     }
                     for (const compSet of rawComponents.componentSets) {
-                        manifest.componentSets[compSet.name] = {
+                        manifest.componentSets[compSet.key || compSet.nodeId] = {
                             key: compSet.key,
                             nodeId: compSet.nodeId,
                             name: compSet.name,
@@ -1466,8 +1570,14 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
                         };
                     }
                 }
+                else {
+                    componentsFetchError =
+                        componentsResult?.error || "getLocalComponents returned no data";
+                }
             }
             catch (error) {
+                componentsFetchError =
+                    error instanceof Error ? error.message : String(error);
                 logger.warn({ error }, "Could not fetch components during auto-load");
             }
             // Update summary
@@ -1484,10 +1594,29 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
                 typographyScale: [],
                 componentCategories: [],
             };
-            // Cache the result
-            cache.set(fileKey, manifest, rawComponents);
-            cacheEntry = cache.get(fileKey);
-            return { cacheEntry, fileKey, wasLoaded: true };
+            // Cache the result — but never cache a manifest built from a FAILED
+            // components fetch: serving an empty manifest as "cached" for the full
+            // TTL is exactly the "search returns 0 components" poisoning bug.
+            if (!componentsFetchError) {
+                cache.set(fileKey, manifest, rawComponents);
+                cacheEntry = cache.get(fileKey);
+            }
+            else {
+                cacheEntry = {
+                    manifest,
+                    timestamp: Date.now(),
+                    fileKey,
+                    rawComponents,
+                };
+            }
+            return {
+                cacheEntry,
+                fileKey,
+                wasLoaded: true,
+                warning: componentsFetchError
+                    ? `Components fetch failed (${componentsFetchError}) — results may be incomplete and were NOT cached; retry after checking the Desktop Bridge plugin.`
+                    : undefined,
+            };
         };
         // ============================================================================
         // READ-SIDE LIBRARY / DESIGN-SYSTEM TOOLS
@@ -1505,7 +1634,7 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
                 const { DesignSystemManifestCache, createEmptyManifest, figmaColorToHex, getCategories, getTokenSummary, } = await import("./core/design-system-manifest.js");
                 const cache = DesignSystemManifestCache.getInstance();
                 const currentUrl = this.getCurrentFileUrl();
-                const fileKeyMatch = currentUrl?.match(/\/(file|design)\/([a-zA-Z0-9]+)/);
+                const fileKeyMatch = currentUrl?.match(/\/(file|design|board|slides)\/([a-zA-Z0-9]+)/);
                 const fileKey = fileKeyMatch ? fileKeyMatch[2] : "unknown";
                 // Check cache first
                 let cacheEntry = cache.get(fileKey);
@@ -1582,7 +1711,10 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
                     logger.warn({ error }, "Could not fetch variables");
                 }
                 // Get components (can be slow for large files)
+                // Keyed by component key (unique) — name keys drop same-named
+                // components on other pages.
                 let rawComponents;
+                let componentsFetchError = null;
                 try {
                     const componentsResult = await connector.getLocalComponents();
                     if (componentsResult.success && componentsResult.data) {
@@ -1591,7 +1723,7 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
                             componentSets: componentsResult.data.componentSets || [],
                         };
                         for (const comp of rawComponents.components) {
-                            manifest.components[comp.name] = {
+                            manifest.components[comp.key || comp.nodeId] = {
                                 key: comp.key,
                                 nodeId: comp.nodeId,
                                 name: comp.name,
@@ -1600,7 +1732,7 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
                             };
                         }
                         for (const compSet of rawComponents.componentSets) {
-                            manifest.componentSets[compSet.name] = {
+                            manifest.componentSets[compSet.key || compSet.nodeId] = {
                                 key: compSet.key,
                                 nodeId: compSet.nodeId,
                                 name: compSet.name,
@@ -1617,8 +1749,14 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
                             };
                         }
                     }
+                    else {
+                        componentsFetchError =
+                            componentsResult?.error || "getLocalComponents returned no data";
+                    }
                 }
                 catch (error) {
+                    componentsFetchError =
+                        error instanceof Error ? error.message : String(error);
                     logger.warn({ error }, "Could not fetch components");
                 }
                 // Update summary
@@ -1635,8 +1773,11 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
                     typographyScale: [],
                     componentCategories: [],
                 };
-                // Cache the result
-                cache.set(fileKey, manifest, rawComponents);
+                // Cache the result — never cache a manifest built from a failed
+                // components fetch (would serve empty results for the full TTL).
+                if (!componentsFetchError) {
+                    cache.set(fileKey, manifest, rawComponents);
+                }
                 const categories = getCategories(manifest);
                 const tokenSummary = getTokenSummary(manifest);
                 return {
@@ -1654,6 +1795,11 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
                                     componentSets: manifest.summary.totalComponentSets,
                                     tokens: manifest.summary.totalTokens,
                                 },
+                                warnings: componentsFetchError
+                                    ? [
+                                        `Components fetch failed (${componentsFetchError}) — component data is incomplete and was NOT cached. Check the Desktop Bridge plugin and retry.`,
+                                    ]
+                                    : undefined,
                                 hint: "Use figma_search_components to find specific components by name or category.",
                             }),
                         },
@@ -1800,7 +1946,18 @@ Without libraryFileKey/libraryFileUrl, searches the currently open file (local c
                     const effectiveLimit = Math.min(limit || 10, 25);
                     const effectiveOffset = offset || 0;
                     const total = results.length;
-                    const paginatedResults = results.slice(effectiveOffset, effectiveOffset + effectiveLimit);
+                    const paginatedResults = results
+                        .slice(effectiveOffset, effectiveOffset + effectiveLimit)
+                        // Search hits only need a teaser — some design systems carry
+                        // multi-KB doc blocks per component, which multiplies across
+                        // a result page. figma_get_component_details returns full text.
+                        .map((item) => item.description && item.description.length > 200
+                        ? {
+                            ...item,
+                            description: `${item.description.slice(0, 200)}…`,
+                            descriptionTruncated: true,
+                        }
+                        : item);
                     return {
                         content: [
                             {
@@ -1827,7 +1984,7 @@ Without libraryFileKey/libraryFileUrl, searches the currently open file (local c
                 // LOCAL SEARCH PATH: Use cached design system manifest (existing behavior)
                 const { searchComponents } = await import("./core/design-system-manifest.js");
                 // Auto-load design system cache if needed (no error returned to user)
-                const { cacheEntry } = await ensureDesignSystemCache();
+                const { cacheEntry, warning: cacheWarning } = await ensureDesignSystemCache();
                 if (!cacheEntry) {
                     return {
                         content: [
@@ -1858,6 +2015,7 @@ Without libraryFileKey/libraryFileUrl, searches the currently open file (local c
                                 query: query || "(all)",
                                 category: category || "(all)",
                                 results: results.results,
+                                warnings: cacheWarning ? [cacheWarning] : undefined,
                                 pagination: {
                                     offset: offset || 0,
                                     limit: effectiveLimit,
@@ -1930,10 +2088,12 @@ Without libraryFileKey/libraryFileUrl, searches the currently open file (local c
                 // Search for the component
                 let component = null;
                 let isComponentSet = false;
-                // Check component sets first (they have variants)
-                for (const [name, compSet] of Object.entries(cacheEntry.manifest.componentSets)) {
+                // Check component sets first (they have variants).
+                // Maps are keyed by component key; match names via the entry's
+                // own name field, not the map key.
+                for (const compSet of Object.values(cacheEntry.manifest.componentSets)) {
                     if ((componentKey && compSet.key === componentKey) ||
-                        (componentName && name === componentName)) {
+                        (componentName && compSet.name === componentName)) {
                         component = compSet;
                         isComponentSet = true;
                         break;
@@ -1941,9 +2101,9 @@ Without libraryFileKey/libraryFileUrl, searches the currently open file (local c
                 }
                 // Check standalone components
                 if (!component) {
-                    for (const [name, comp] of Object.entries(cacheEntry.manifest.components)) {
+                    for (const comp of Object.values(cacheEntry.manifest.components)) {
                         if ((componentKey && comp.key === componentKey) ||
-                            (componentName && name === componentName)) {
+                            (componentName && comp.name === componentName)) {
                             component = comp;
                             break;
                         }
@@ -2363,8 +2523,9 @@ Without libraryFileKey/libraryFileUrl, searches the currently open file (local c
         registerWriteTools(this.server, () => this.getDesktopConnector());
         // Register token sync tools — figma_export_tokens and figma_import_tokens.
         // Replace Style Dictionary and Tokens Studio's export pipeline for the
-        // popular styling methods (DTCG canonical, plus CSS/Tailwind/SCSS/etc.
-        // as Phase 2+ extensions to a single internal token model).
+        // popular styling methods (DTCG canonical — legacy + 2025.10 dialects —
+        // plus CSS/Tailwind/SCSS/TS/JSON/Style Dictionary/Tokens Studio, all
+        // derived from a single internal token model).
         registerTokensTools(this.server, () => this.getDesktopConnector());
         // Register Figma API tools (Tools 8-11)
         registerFigmaAPITools(this.server, () => this.getFigmaAPI(), () => this.getCurrentFileUrl(), this.variablesCache, // Pass cache for efficient variable queries
@@ -2414,6 +2575,7 @@ Without libraryFileKey/libraryFileUrl, searches the currently open file (local c
                     return "0.0.0";
                 }
             },
+            getBundledPluginVersion,
             getPluginState: () => {
                 if (!this.wsServer)
                     return null;
@@ -2427,6 +2589,8 @@ Without libraryFileKey/libraryFileUrl, searches the currently open file (local c
                     editorType: fileInfo?.editorType,
                     port: this.wsActualPort ?? undefined,
                     portFallbackFrom: this.wsPreferredPort,
+                    pluginVersion: fileInfo?.pluginVersion,
+                    pluginUpdateAvailable: fileInfo?.pluginUpdateAvailable,
                 };
             },
             getTokenState: () => {
@@ -2765,13 +2929,17 @@ Without libraryFileKey/libraryFileUrl, searches the currently open file (local c
             const wsHost = process.env.FIGMA_WS_HOST || 'localhost';
             this.wsPreferredPort = parseInt(process.env.FIGMA_WS_PORT || String(DEFAULT_WS_PORT), 10);
             // Clean up stale/orphaned MCP server instances before trying to bind.
-            // Phase 1: Remove stale port files and terminate zombie processes that have port files
+            // Step 1: Remove stale port files and terminate zombie processes that have port files
             cleanupStalePortFiles();
-            // Phase 2: Deep scan for orphaned processes holding ports WITHOUT port files
+            // Step 2: Deep scan for orphaned processes holding ports WITHOUT port files
             // (e.g., old instances from before port file tracking, or files already cleaned up)
             cleanupOrphanedProcesses(this.wsPreferredPort);
             const portsToTry = getPortRange(this.wsPreferredPort);
             let boundPort = null;
+            // Distinguish "every port was in use" from "bind failed for another
+            // reason" — eviction must only fire for genuine port exhaustion, and
+            // figma_get_status must report the real error code.
+            let lastNonPortError = null;
             for (const port of portsToTry) {
                 try {
                     this.wsServer = new FigmaWebSocketServer({ port, host: wsHost });
@@ -2806,12 +2974,18 @@ Without libraryFileKey/libraryFileUrl, searches the currently open file (local c
                     }
                     // Non-port-conflict error — don't try more ports
                     logger.warn({ error: errorMsg, port }, "Failed to start WebSocket bridge server");
+                    lastNonPortError = {
+                        code: errorCode || "UNKNOWN",
+                        message: errorMsg,
+                    };
                     this.wsServer = null;
                     break;
                 }
             }
-            // Phase 3: If all ports exhausted, try evicting the oldest instance and retry ONCE
-            if (!boundPort && evictOldestInstance(this.wsPreferredPort)) {
+            // Phase 3: If all ports exhausted, try evicting the oldest instance and
+            // retry ONCE. Only for genuine EADDRINUSE exhaustion — killing a healthy
+            // sibling can't fix an EACCES/EADDRNOTAVAIL bind failure.
+            if (!boundPort && !lastNonPortError && evictOldestInstance(this.wsPreferredPort)) {
                 for (const port of portsToTry) {
                     try {
                         this.wsServer = new FigmaWebSocketServer({ port, host: wsHost });
@@ -2840,11 +3014,15 @@ Without libraryFileKey/libraryFileUrl, searches the currently open file (local c
             }
             if (!boundPort) {
                 this.wsStartupError = {
-                    code: "EADDRINUSE",
+                    code: lastNonPortError?.code ?? "EADDRINUSE",
                     port: this.wsPreferredPort,
                 };
                 const rangeEnd = this.wsPreferredPort + portsToTry.length - 1;
-                logger.warn({ portRange: `${this.wsPreferredPort}-${rangeEnd}` }, "All WebSocket ports in range are in use — running without WebSocket transport");
+                logger.warn(lastNonPortError
+                    ? { error: lastNonPortError }
+                    : { portRange: `${this.wsPreferredPort}-${rangeEnd}` }, lastNonPortError
+                    ? "WebSocket bridge failed to start (non-port error) — running without WebSocket transport"
+                    : "All WebSocket ports in range are in use — running without WebSocket transport");
             }
             if (this.wsServer) {
                 // Log when plugin files connect/disconnect (with file identity)
@@ -2859,6 +3037,11 @@ Without libraryFileKey/libraryFileUrl, searches the currently open file (local c
                     logger.info({ fileKey: data.fileKey, fileName: data.fileName }, "Desktop Bridge plugin disconnected from WebSocket");
                     if (data.fileKey) {
                         this.variablesCache.delete(data.fileKey);
+                        // design-system-tools.ts stores token data under a prefixed key
+                        this.variablesCache.delete(`vars:${data.fileKey}`);
+                        void import("./core/design-system-manifest.js").then(({ DesignSystemManifestCache }) => {
+                            DesignSystemManifestCache.getInstance().invalidate(data.fileKey);
+                        }).catch(() => { });
                     }
                 });
                 // Invalidate variable cache when document changes are reported.
@@ -2868,8 +3051,15 @@ Without libraryFileKey/libraryFileUrl, searches the currently open file (local c
                 this.wsServer.on("documentChange", (data) => {
                     if (data.hasStyleChanges || data.hasNodeChanges) {
                         if (data.fileKey) {
-                            // Per-file cache invalidation — only clear the affected file's cache
+                            // Per-file cache invalidation — only clear the affected file's cache.
+                            // Also clear the design-system-tools token entry (prefixed key)
+                            // and the component manifest, so searches see new components
+                            // and the design-system kit sees edited variables.
                             this.variablesCache.delete(data.fileKey);
+                            this.variablesCache.delete(`vars:${data.fileKey}`);
+                            void import("./core/design-system-manifest.js").then(({ DesignSystemManifestCache }) => {
+                                DesignSystemManifestCache.getInstance().invalidate(data.fileKey);
+                            }).catch(() => { });
                             logger.debug({ fileKey: data.fileKey, changeCount: data.changeCount, hasStyleChanges: data.hasStyleChanges, hasNodeChanges: data.hasNodeChanges }, "Variable cache invalidated due to document changes");
                         }
                         else {