@mp3wizard/figma-console-mcp 1.32.3 → 1.34.1

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

@@ -7,13 +7,23 @@ const logger = createChildLogger({ component: 'figma-api' });
 const FIGMA_API_BASE = 'https://api.figma.com/v1';
 /**
  * Extract file key from Figma URL
+ * Branch-aware: for branch URLs (/design/KEY/branch/BRANCHKEY/Name) returns the
+ * BRANCH key — the branch is its own file in the REST API, and returning the
+ * main key would silently target the wrong file (comments/diffs/file-data).
  * @example https://www.figma.com/design/abc123/My-File -> abc123
+ * @example https://www.figma.com/design/abc123/branch/xyz789/My-File -> xyz789
  */
 export function extractFileKey(url) {
     try {
         const urlObj = new URL(url);
-        // Match patterns like /design/FILE_KEY or /file/FILE_KEY
-        const match = urlObj.pathname.match(/\/(design|file)\/([a-zA-Z0-9]+)/);
+        // Branch URLs: /design/FILE_KEY/branch/BRANCH_KEY — the branch key is the
+        // effective file key for all REST API calls.
+        const branchMatch = urlObj.pathname.match(/\/(design|file|board|slides)\/[a-zA-Z0-9]+\/branch\/([a-zA-Z0-9]+)/);
+        if (branchMatch) {
+            return branchMatch[2];
+        }
+        // Match patterns like /design/FILE_KEY, /file/FILE_KEY, /board/FILE_KEY (FigJam), /slides/FILE_KEY
+        const match = urlObj.pathname.match(/\/(design|file|board|slides)\/([a-zA-Z0-9]+)/);
         return match ? match[2] : null;
     }
     catch (error) {
@@ -21,6 +31,15 @@ export function extractFileKey(url) {
         return null;
     }
 }
+/**
+ * Normalize a node ID to Figma's canonical colon form.
+ * URLs use dashes ("695-313") but the REST API keys response maps by colon
+ * form ("695:313") — indexing a response with a dashed ID silently returns
+ * undefined, which reads as "node may not exist".
+ */
+export function normalizeNodeId(nodeId) {
+    return nodeId.replace(/-/g, ':');
+}
 /**
  * Extract comprehensive URL info including branch and node IDs
  * Supports both URL formats:
@@ -36,7 +55,7 @@ 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]+)/);
+        const branchPathMatch = urlObj.pathname.match(/\/(design|file|board|slides)\/([a-zA-Z0-9]+)\/branch\/([a-zA-Z0-9]+)/);
         if (branchPathMatch) {
             const fileKey = branchPathMatch[2];
             const branchId = branchPathMatch[3];
@@ -45,7 +64,7 @@ export function extractFigmaUrlInfo(url) {
             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]+)/);
+        const standardMatch = urlObj.pathname.match(/\/(design|file|board|slides)\/([a-zA-Z0-9]+)/);
         if (!standardMatch)
             return null;
         const fileKey = standardMatch[2];
@@ -109,14 +128,54 @@ export class FigmaAPI {
         else {
             headers['X-Figma-Token'] = this.accessToken;
         }
-        const response = await fetch(url, {
-            ...options,
-            headers,
-        });
+        // Up to 3 total attempts on 429 (rate limit), honoring Retry-After when
+        // present (seconds), else exponential backoff (1s, 2s). Delays here run
+        // inside the request promise — callers wrapping with withTimeout() still
+        // get their race-based rejection if the overall wait exceeds their budget.
+        const MAX_ATTEMPTS = 3;
+        let response;
+        for (let attempt = 1;; attempt++) {
+            response = await fetch(url, {
+                ...options,
+                headers,
+            });
+            if (response.status !== 429 || attempt >= MAX_ATTEMPTS) {
+                break;
+            }
+            const retryAfterHeader = response.headers.get('retry-after');
+            const retryAfterSeconds = retryAfterHeader ? Number(retryAfterHeader) : NaN;
+            // Cap Retry-After waits at 30s so a pathological header can't hang callers.
+            const delayMs = Number.isFinite(retryAfterSeconds) && retryAfterSeconds > 0
+                ? Math.min(retryAfterSeconds, 30) * 1000
+                : attempt * 1000; // 1s after attempt 1, 2s after attempt 2
+            logger.warn({ url, attempt, delayMs, retryAfterHeader }, 'Figma API rate limited (429), retrying');
+            await new Promise((resolve) => setTimeout(resolve, delayMs));
+        }
         if (!response.ok) {
             const errorText = await response.text();
             logger.error({ status: response.status, statusText: response.statusText, body: errorText }, 'Figma API request failed');
-            throw new Error(`Figma API error (${response.status}): ${errorText}`);
+            // The `Figma API error (<status>):` prefix is LOAD-BEARING — downstream
+            // tool handlers branch on errorMessage.includes("403") etc. Keep it
+            // verbatim at the start of the message; only APPEND guidance after it.
+            let message = `Figma API error (${response.status}): ${errorText}`;
+            // Token-auth failures (expired/invalid token) get actionable guidance.
+            // Plan-gate 403s (e.g. Variables API on non-Enterprise) do NOT match the
+            // token pattern and must not be flagged as auth errors.
+            const isAuthError = (response.status === 401 || response.status === 403) &&
+                /invalid token|token expired|unauthorized/i.test(errorText);
+            if (isAuthError) {
+                message +=
+                    ' — 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. If Figma Desktop is open with the Desktop Bridge plugin running, most tools work without any REST token.';
+            }
+            else if (response.status === 429) {
+                message += ' Rate limited by Figma — wait a moment and retry.';
+            }
+            const err = new Error(message);
+            err.status = response.status;
+            if (isAuthError) {
+                err.isAuthError = true;
+            }
+            throw err;
         }
         const data = await response.json();
         return data;
@@ -145,43 +204,6 @@ 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
@@ -205,11 +227,17 @@ export class FigmaAPI {
     /**
      * GET /v1/files/:file_key/nodes
      * Get specific nodes by ID
+     *
+     * Node IDs are normalized to Figma's colon form ("695-313" -> "695:313")
+     * before the request, and the response map is aliased back under any
+     * dashed IDs the caller passed — Figma keys the response by colon-format
+     * IDs, so without the alias a dashed lookup silently returns undefined.
      */
     async getNodes(fileKey, nodeIds, options) {
         let endpoint = `/files/${fileKey}/nodes`;
+        const normalizedIds = nodeIds.map((id) => normalizeNodeId(id));
         const params = new URLSearchParams();
-        params.append('ids', nodeIds.join(','));
+        params.append('ids', normalizedIds.join(','));
         if (options?.version)
             params.append('version', options.version);
         if (options?.depth !== undefined)
@@ -219,7 +247,19 @@ export class FigmaAPI {
         if (options?.plugin_data)
             params.append('plugin_data', options.plugin_data);
         endpoint += `?${params.toString()}`;
-        return this.request(endpoint);
+        const response = await this.request(endpoint);
+        // Defensive aliasing: let callers index response.nodes by the ID form
+        // they originally passed (dashed), not just Figma's colon form.
+        if (response?.nodes) {
+            for (let i = 0; i < nodeIds.length; i++) {
+                const original = nodeIds[i];
+                const normalized = normalizedIds[i];
+                if (original !== normalized && response.nodes[normalized] !== undefined && response.nodes[original] === undefined) {
+                    response.nodes[original] = response.nodes[normalized];
+                }
+            }
+        }
+        return response;
     }
     /**
      * GET /v1/files/:file_key/styles
@@ -271,8 +311,12 @@ export class FigmaAPI {
      */
     async getImages(fileKey, nodeIds, options) {
         const params = new URLSearchParams();
-        // Handle single or multiple node IDs
-        const ids = Array.isArray(nodeIds) ? nodeIds.join(',') : nodeIds;
+        // Handle single or multiple node IDs. Normalize to Figma's colon form
+        // ("695-313" -> "695:313") — the response map is keyed by colon IDs, so
+        // a dashed request ID would otherwise never match its own result.
+        const originalIds = Array.isArray(nodeIds) ? nodeIds : [nodeIds];
+        const normalizedIds = originalIds.map((id) => normalizeNodeId(id));
+        const ids = normalizedIds.join(',');
         params.append('ids', ids);
         // Add optional parameters
         if (options?.scale !== undefined)
@@ -291,7 +335,19 @@ export class FigmaAPI {
             params.append('contents_only', options.contents_only.toString());
         const endpoint = `/images/${fileKey}?${params.toString()}`;
         logger.info({ fileKey, ids, options }, 'Rendering images');
-        return this.request(endpoint);
+        const response = await this.request(endpoint);
+        // Defensive aliasing: callers may index the images map by the dashed
+        // ID they passed. Figma keys it by colon-format ID — alias both forms.
+        if (response?.images) {
+            for (let i = 0; i < originalIds.length; i++) {
+                const original = originalIds[i];
+                const normalized = normalizedIds[i];
+                if (original !== normalized && response.images[normalized] !== undefined && response.images[original] === undefined) {
+                    response.images[original] = response.images[normalized];
+                }
+            }
+        }
+        return response;
     }
     /**
      * GET /v1/files/:file_key/comments
@@ -356,15 +412,20 @@ export class FigmaAPI {
         const [localResult, publishedResult] = await Promise.all([
             this.getLocalVariables(fileKey).catch((err) => {
                 const errorMsg = err instanceof Error ? err.message : String(err);
+                logger.warn({ fileKey, error: errorMsg }, 'getLocalVariables failed; returning empty fallback');
                 return { error: errorMsg, variables: {}, variableCollections: {} };
             }),
             this.getPublishedVariables(fileKey).catch((err) => {
                 const errorMsg = err instanceof Error ? err.message : String(err);
+                logger.warn({ fileKey, error: errorMsg }, 'getPublishedVariables failed; returning empty fallback');
                 return { error: errorMsg, variables: {} };
             }),
         ]);
+        // Fallback shape must match the success path (already-unwrapped meta):
+        // { variables, variableCollections } — NOT { meta: {...} } — so consumers
+        // like formatVariables() see a consistent shape either way.
         return {
-            local: 'error' in localResult ? { meta: { variables: {}, variableCollections: {} } } : localResult,
+            local: 'error' in localResult ? { variables: {}, variableCollections: {} } : localResult,
             published: 'error' in publishedResult ? { variables: {} } : publishedResult,
             ...(('error' in localResult) && { localError: localResult.error }),
             ...(('error' in publishedResult) && { publishedError: publishedResult.error }),
@@ -372,10 +433,13 @@ export class FigmaAPI {
     }
     /**
      * Helper: Get component metadata with properties
+     * Normalizes dashed node IDs ("695-313") to colon form ("695:313") so the
+     * response-map lookup matches Figma's colon-keyed response.
      */
     async getComponentData(fileKey, nodeId, depth = 4) {
-        const response = await this.getNodes(fileKey, [nodeId], { depth });
-        return response.nodes?.[nodeId];
+        const normalizedId = normalizeNodeId(nodeId);
+        const response = await this.getNodes(fileKey, [normalizedId], { depth });
+        return response.nodes?.[normalizedId] ?? response.nodes?.[nodeId];
     }
     /**
      * Helper: Search for components by name

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

@@ -147,27 +147,34 @@ function adaptiveResponse(responseData, options) {
             ],
         };
     }
-    // Determine compression level and message
+    // Determine compression level and message. The "AUTO-COMPRESSED" wording is
+    // only truthful when a compressionCallback actually runs — without one the
+    // full payload is returned and the banner must say so instead of claiming
+    // a reduction that never happened.
     let compressionLevel = "info";
     let aiInstruction = "";
     let shouldCompress = false;
+    const canCompress = !!options.compressionCallback;
     if (sizeKB > RESPONSE_SIZE_THRESHOLDS.MAX_SIZE_KB) {
         compressionLevel = "emergency";
         shouldCompress = true;
-        aiInstruction =
-            `⚠️ RESPONSE AUTO-COMPRESSED: The ${options.toolName} response was automatically reduced because the full response would be ${sizeKB.toFixed(0)}KB, which would exhaust Claude Desktop's context window.\n\n`;
+        aiInstruction = canCompress
+            ? `⚠️ RESPONSE AUTO-COMPRESSED: The ${options.toolName} response was automatically reduced because the full response would be ${sizeKB.toFixed(0)}KB, which would exhaust Claude Desktop's context window.\n\n`
+            : `⚠️ LARGE RESPONSE: The ${options.toolName} response is ${sizeKB.toFixed(0)}KB and may exhaust the context window. Retry with filters or pagination to reduce it.\n\n`;
     }
     else if (sizeKB > RESPONSE_SIZE_THRESHOLDS.CRITICAL_SIZE_KB) {
         compressionLevel = "critical";
         shouldCompress = true;
-        aiInstruction =
-            `⚠️ RESPONSE AUTO-COMPRESSED: The ${options.toolName} response was automatically reduced because it would be ${sizeKB.toFixed(0)}KB, risking context window exhaustion.\n\n`;
+        aiInstruction = canCompress
+            ? `⚠️ RESPONSE AUTO-COMPRESSED: The ${options.toolName} response was automatically reduced because it would be ${sizeKB.toFixed(0)}KB, risking context window exhaustion.\n\n`
+            : `⚠️ LARGE RESPONSE: The ${options.toolName} response is ${sizeKB.toFixed(0)}KB, risking context window exhaustion. Retry with filters or pagination to reduce it.\n\n`;
     }
     else if (sizeKB > RESPONSE_SIZE_THRESHOLDS.WARNING_SIZE_KB) {
         compressionLevel = "warning";
         shouldCompress = true;
-        aiInstruction =
-            `ℹ️ RESPONSE OPTIMIZED: The ${options.toolName} response was automatically reduced because it would be ${sizeKB.toFixed(0)}KB.\n\n`;
+        aiInstruction = canCompress
+            ? `ℹ️ RESPONSE OPTIMIZED: The ${options.toolName} response was automatically reduced because it would be ${sizeKB.toFixed(0)}KB.\n\n`
+            : `ℹ️ LARGE RESPONSE: The ${options.toolName} response is ${sizeKB.toFixed(0)}KB. Filters or pagination can reduce it.\n\n`;
     }
     // Map compression level to verbosity level
     const verbosityMap = {
@@ -816,13 +823,17 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
             return adaptiveResponse(finalResponse, {
                 toolName: "figma_get_file_data",
                 compressionCallback: (adjustedLevel) => {
-                    // Re-apply node filtering with lower verbosity
-                    const level = adjustedLevel;
+                    // Re-apply node filtering with lower verbosity. "inventory"
+                    // (the emergency tier) isn't a filterNode level — clamp it to
+                    // "summary", the strongest filter, instead of letting it fall
+                    // through filterNode's default branch which returns the RAW
+                    // node (that ballooned "compressed" responses). Always
+                    // re-filter, even when the caller asked for verbosity='full' —
+                    // an emergency downgrade must never echo the raw document.
+                    const level = (adjustedLevel === "standard" ? "standard" : "summary");
                     const refiltered = {
                         ...finalResponse,
-                        document: verbosity !== "full"
-                            ? filterNode(fileData.document, level)
-                            : fileData.document,
+                        document: filterNode(fileData.document, level),
                         verbosity: level,
                     };
                     return refiltered;
@@ -866,7 +877,7 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
      * removed in the Phase 3 cleanup. Setting parseFromConsole=true now
      * throws an identified error pointing the caller at the bridge.
      */
-    server.tool("figma_get_variables", "Extract design tokens and variables from a Figma file with code export support (CSS, Tailwind, TypeScript, Sass). Use when user asks for: design system tokens, variables, color/spacing values, theme data, or code exports. Handles multi-mode variables (Light/Dark themes). NOT for component metadata (use figma_get_component). Supports filtering by collection/mode/name and verbosity control to prevent token exhaustion. Resolution order: Desktop Bridge plugin (works on any plan) → Variables REST API (Enterprise only) → Styles API as a partial fallback. TIP: For full design system extraction (tokens + components + styles combined), prefer figma_get_design_system_kit instead — it returns everything in one optimized call.", {
+    server.tool("figma_get_variables", "Extract design tokens and variables from a Figma file with code export support (CSS, Tailwind, TypeScript, Sass). Use when user asks for: design system tokens, variables, color/spacing values, theme data, or code exports. Handles multi-mode variables (Light/Dark themes). NOT for component metadata (use figma_get_component). Returns a compact summary by default — pass format='full' for the complete dataset or format='filtered' with collection/namePattern/mode filters for specific variables. Supports verbosity control to prevent token exhaustion. Resolution order: Desktop Bridge plugin (works on any plan) → Variables REST API (Enterprise only) → Styles API as a partial fallback. TIP: For full design system extraction (tokens + components + styles combined), prefer figma_get_design_system_kit instead — it returns everything in one optimized call.", {
         fileUrl: z
             .string()
             .url()
@@ -905,9 +916,9 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
         format: z
             .enum(["summary", "filtered", "full"])
             .optional()
-            .default("full")
             .describe("Response format: 'summary' (~2K tokens with overview and names only), 'filtered' (apply collection/name/mode filters), 'full' (complete dataset from cache or fetch). " +
-            "Summary is recommended for initial exploration. Full format returns all data but may be auto-summarized if >25K tokens. Default: full"),
+            "Default: summary (token-efficient). When format is omitted, filter params (collection/namePattern/mode) auto-select 'filtered', and enrichment/export/resolveAliases/returnAsLinks params auto-select 'full'. " +
+            "Full format returns all data but may be auto-summarized if >25K tokens."),
         collection: z
             .string()
             .optional()
@@ -964,6 +975,28 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
             "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 }) => {
+        // Smart format default (token efficiency): when the caller doesn't pick a
+        // format, use the cheapest one their other parameters allow. Explicit
+        // format callers are unaffected. Only parameters without schema defaults
+        // (or defaulting to false) can signal intent — verbosity, includePublished,
+        // and page/pageSize are always populated by their defaults.
+        if (!format) {
+            if (collection || namePattern || mode) {
+                format = "filtered";
+            }
+            else if (enrich ||
+                include_usage ||
+                include_dependencies ||
+                include_exports ||
+                (export_formats && export_formats.length > 0) ||
+                resolveAliases ||
+                returnAsLinks) {
+                format = "full";
+            }
+            else {
+                format = "summary";
+            }
+        }
         // Extract fileKey and optional branchId outside try block so they're available in catch block
         const url = fileUrl || getCurrentUrl();
         if (!url) {
@@ -1297,6 +1330,53 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
                     let publishedFormatted = includePublished
                         ? formatVariables(published)
                         : null;
+                    // Cache the FULL dataset in the Desktop-connection shape BEFORE
+                    // any format/verbosity/pagination mutation. The cache reader
+                    // expects { variables, variableCollections }; caching the
+                    // stripped, paginated page (the old behavior) poisoned every
+                    // follow-up filtered/summary call for the whole TTL window.
+                    // Variable objects are shallow-copied so downstream verbosity
+                    // stripping can't reach into the cached entries.
+                    if (variablesCache) {
+                        evictOldestCacheEntry(variablesCache);
+                        variablesCache.set(fileKey, {
+                            data: {
+                                fileKey,
+                                source: "rest_api",
+                                timestamp: Date.now(),
+                                variables: (localFormatted.variables || []).map((v) => ({ ...v })),
+                                variableCollections: (localFormatted.collections || []).map((c) => ({ ...c })),
+                            },
+                            timestamp: Date.now(),
+                        });
+                        logger.info({ fileKey, variableCount: localFormatted.variables?.length }, "Cached full REST API variables dataset");
+                    }
+                    // Honor format='summary' on the REST path (historically only the
+                    // cache and Desktop Bridge paths summarized). Runs AFTER the
+                    // cache write so summary calls still populate the full dataset.
+                    if (format === 'summary') {
+                        const summary = generateSummary({
+                            fileKey,
+                            timestamp: Date.now(),
+                            source: 'rest_api',
+                            variables: localFormatted.variables,
+                            variableCollections: localFormatted.collections,
+                        });
+                        logger.info({ fileKey, estimatedTokens: estimateTokens(summary) }, 'Generated summary from REST API data');
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: JSON.stringify({
+                                        fileKey,
+                                        source: "rest_api",
+                                        format: "summary",
+                                        data: summary,
+                                    }),
+                                },
+                            ],
+                        };
+                    }
                     // DEBUG: Check if valuesByMode exists before filtering
                     if (localFormatted.variables[0]) {
                         logger.info({
@@ -1374,31 +1454,8 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
                             publishedFormatted.variables = publishedFormatted.variables.slice(startIdx, endIdx);
                         }
                     }
-                    // Cache the successful REST API response
-                    const dataForCache = {
-                        fileKey,
-                        local: {
-                            summary: localFormatted.summary,
-                            collections: localFormatted.collections,
-                            variables: localFormatted.variables,
-                        },
-                        ...(includePublished &&
-                            publishedFormatted && {
-                            published: {
-                                summary: publishedFormatted.summary,
-                                collections: publishedFormatted.collections,
-                                variables: publishedFormatted.variables,
-                            },
-                        }),
-                        verbosity: verbosity || "standard",
-                        enriched: enrich || false,
-                        timestamp: Date.now(),
-                        source: "rest_api",
-                    };
-                    if (variablesCache) {
-                        variablesCache.set(fileKey, { data: dataForCache, timestamp: Date.now() });
-                        logger.info({ fileKey }, "Cached REST API variables");
-                    }
+                    // (Cache write happens above, pre-mutation — the response below
+                    // is built from the filtered/paginated working copies.)
                     // Apply alias resolution if requested (REST API format has local.variables)
                     if (resolveAliases && localFormatted.variables?.length > 0) {
                         // Build maps from local variables and collections
@@ -1742,6 +1799,46 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
                     if (!localError && local) {
                         let localFormatted = formatVariables(local);
                         let publishedFormatted = includePublished ? formatVariables(published) : null;
+                        // Cache the FULL dataset pre-mutation in the Desktop shape
+                        // (same poisoning fix as the primary REST path above).
+                        if (variablesCache) {
+                            evictOldestCacheEntry(variablesCache);
+                            variablesCache.set(fileKey, {
+                                data: {
+                                    fileKey,
+                                    source: "rest_api",
+                                    timestamp: Date.now(),
+                                    variables: (localFormatted.variables || []).map((v) => ({ ...v })),
+                                    variableCollections: (localFormatted.collections || []).map((c) => ({ ...c })),
+                                },
+                                timestamp: Date.now(),
+                            });
+                        }
+                        // Honor format='summary' on the REST fallback path too
+                        // (after the cache write, so the full dataset is retained).
+                        if (format === 'summary') {
+                            const summary = generateSummary({
+                                fileKey,
+                                timestamp: Date.now(),
+                                source: 'rest_api',
+                                variables: localFormatted.variables,
+                                variableCollections: localFormatted.collections,
+                            });
+                            logger.info({ fileKey, estimatedTokens: estimateTokens(summary) }, 'Generated summary from REST API fallback data');
+                            return {
+                                content: [
+                                    {
+                                        type: "text",
+                                        text: JSON.stringify({
+                                            fileKey,
+                                            source: "rest_api",
+                                            format: "summary",
+                                            data: summary,
+                                        }),
+                                    },
+                                ],
+                            };
+                        }
                         // Apply filters
                         if (format === 'filtered') {
                             const filteredLocal = applyFilters({ variables: localFormatted.variables, variableCollections: localFormatted.collections }, { collection, namePattern, mode }, verbosity || "standard");
@@ -1752,19 +1849,6 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
                             const verbosityFiltered = applyFilters({ variables: localFormatted.variables, variableCollections: localFormatted.collections }, {}, verbosity);
                             localFormatted = { ...localFormatted, collections: verbosityFiltered.variableCollections, variables: verbosityFiltered.variables };
                         }
-                        // Cache
-                        const dataForCache = {
-                            fileKey,
-                            local: { summary: localFormatted.summary, collections: localFormatted.collections, variables: localFormatted.variables },
-                            ...(includePublished && publishedFormatted && { published: { summary: publishedFormatted.summary, collections: publishedFormatted.collections, variables: publishedFormatted.variables } }),
-                            verbosity: verbosity || "standard",
-                            enriched: enrich || false,
-                            timestamp: Date.now(),
-                            source: "rest_api",
-                        };
-                        if (variablesCache) {
-                            variablesCache.set(fileKey, { data: dataForCache, timestamp: Date.now() });
-                        }
                         // Apply alias resolution
                         if (resolveAliases && localFormatted.variables?.length > 0) {
                             const allVariablesMap = new Map();
@@ -1825,6 +1909,27 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
         catch (error) {
             logger.error({ error }, "Failed to get variables");
             const errorMessage = error instanceof Error ? error.message : String(error);
+            // A 403 here has two very different causes: an expired/invalid token
+            // (isAuthError, set centrally by FigmaAPI.request) or the Variables
+            // API's Enterprise plan gate. Only the latter should be diagnosed as
+            // "requires Enterprise" — telling a user with a dead token to buy
+            // Enterprise is actively wrong.
+            const isTokenError = error?.isAuthError === true;
+            if (isTokenError) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: errorMessage,
+                                message: "Failed to retrieve Figma variables — REST token is expired or invalid",
+                                hint: "Generate a new personal access token at figma.com → Settings → Security → Personal access tokens and update FIGMA_ACCESS_TOKEN. Or open the Desktop Bridge plugin in Figma Desktop — variables work on any plan without a REST token.",
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
             // FIXED: Jump directly to Styles API (fast) instead of full file data (slow)
             if (errorMessage.includes("403")) {
                 try {
@@ -1879,11 +1984,12 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
                                         "The file structure may not contain extractable styles",
                                         "There may be a network or authentication issue"
                                     ],
-                                    suggestion: "Please ensure the file is accessible and try again, or check if your token has the necessary permissions.",
+                                    suggestion: "Please ensure the file is accessible and try again, or check if your token has the necessary permissions. With the Desktop Bridge plugin open in Figma Desktop, variables work on any plan without a REST token.",
                                     technical: styleError instanceof Error ? styleError.message : String(styleError)
                                 }),
                             },
                         ],
+                        isError: true,
                     };
                 }
             }
@@ -1896,8 +2002,8 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
                             error: errorMessage,
                             message: "Failed to retrieve Figma variables",
                             hint: errorMessage.includes("403")
-                                ? "Variables API requires Enterprise plan. Set useConsoleFallback=true for alternative method."
-                                : "Make sure FIGMA_ACCESS_TOKEN is configured and has appropriate permissions",
+                                ? "The Variables REST API requires an Enterprise plan. Open the Desktop Bridge plugin in Figma Desktop instead — variables work on any plan through the bridge."
+                                : "Make sure FIGMA_ACCESS_TOKEN is configured and has appropriate permissions, or open the Desktop Bridge plugin in Figma Desktop",
                         }),
                     },
                 ],
@@ -2251,14 +2357,15 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
             return adaptiveResponse(finalResponse, {
                 toolName: "figma_get_styles",
                 compressionCallback: (adjustedLevel) => {
-                    // Re-apply style filtering with lower verbosity
-                    const level = adjustedLevel;
-                    const refilteredStyles = verbosity !== "full"
-                        ? styles.map((style) => filterStyle(style, level))
-                        : styles;
+                    // Re-apply style filtering with lower verbosity. Clamp the
+                    // emergency "inventory" tier to "summary" (filterStyle has no
+                    // inventory branch) and always re-filter — even for
+                    // verbosity='full' callers — so compression can never echo
+                    // the unfiltered payload.
+                    const level = (adjustedLevel === "standard" ? "standard" : "summary");
                     return {
                         ...finalResponse,
-                        styles: refilteredStyles,
+                        styles: styles.map((style) => filterStyle(style, level)),
                         verbosity: level,
                     };
                 },
@@ -2310,6 +2417,9 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
             .describe("Image format (default: png)"),
     }, async ({ fileUrl, nodeId, scale, format }) => {
         try {
+            // Accept URL-format ids (123-456); the REST response maps key by
+            // colon format (123:456).
+            nodeId = nodeId.replace(/-/g, ":");
             let api;
             try {
                 api = await getFigmaAPI();
@@ -3151,8 +3261,14 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
                         text: JSON.stringify({
                             success: true,
                             instance: result.instance,
+                            // Plugin-side warnings (e.g. property names that didn't
+                            // match anything) — without these a partial apply looks
+                            // like a full success.
+                            warnings: result.warnings?.length ? result.warnings : undefined,
                             metadata: {
-                                note: "Instance properties updated successfully. Use figma_capture_screenshot to verify visual changes.",
+                                note: result.warnings?.length
+                                    ? "Some properties were applied, but see warnings — not every requested property matched. Use figma_capture_screenshot to verify visual changes."
+                                    : "Instance properties updated successfully. Use figma_capture_screenshot to verify visual changes.",
                             },
                         }),
                     },