@mp3wizard/figma-console-mcp 1.25.1 → 1.27.2

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

@@ -7,8 +7,8 @@ import * as fs from "fs";
 import * as path from "path";
 import { extractFileKey, extractFigmaUrlInfo, formatVariables, formatComponentData, withTimeout } from "./figma-api.js";
 import { createChildLogger } from "./logger.js";
+import { identifiedError, withIdentity } from "./identity.js";
 import { EnrichmentService } from "./enrichment/index.js";
-import { SnippetInjector } from "./snippet-injector.js";
 import { extractNodeSpec, validateReconstructionSpec, listVariants } from "./figma-reconstruction-spec.js";
 const logger = createChildLogger({ component: "figma-tools" });
 // Initialize enrichment service
@@ -81,8 +81,6 @@ function scanCodebaseComponents(componentsDir) {
     }
     return registry;
 }
-// Initialize snippet injector
-const snippetInjector = new SnippetInjector();
 // ============================================================================
 // Cache Management & Data Processing Helpers
 // ============================================================================
@@ -132,14 +130,19 @@ function calculateSizeKB(data) {
  * @returns Response content array with optional AI instruction
  */
 function adaptiveResponse(responseData, options) {
-    const sizeKB = calculateSizeKB(responseData);
+    // Tag every response with our MCP identity so LLMs can attribute it
+    // unambiguously when other Figma-related MCPs are also connected.
+    const tagged = responseData && typeof responseData === "object" && !Array.isArray(responseData)
+        ? withIdentity(responseData)
+        : { _mcp: "figma-console-mcp", data: responseData };
+    const sizeKB = calculateSizeKB(tagged);
     // No compression needed
     if (sizeKB <= RESPONSE_SIZE_THRESHOLDS.IDEAL_SIZE_KB) {
         return {
             content: [
                 {
                     type: "text",
-                    text: JSON.stringify(responseData),
+                    text: JSON.stringify(tagged),
                 },
             ],
         };
@@ -200,11 +203,14 @@ function adaptiveResponse(responseData, options) {
             });
         }
     }
-    // Build response content
+    // Build response content (tagged with identity so cross-MCP attribution is clear)
+    const taggedFinal = finalData && typeof finalData === "object" && !Array.isArray(finalData)
+        ? withIdentity(finalData)
+        : { _mcp: "figma-console-mcp", data: finalData };
     const content = [
         {
             type: "text",
-            text: JSON.stringify(finalData),
+            text: JSON.stringify(taggedFinal),
         },
     ];
     // Add AI instruction as separate content block if needed
@@ -647,8 +653,21 @@ function resolveVariableAliases(variables, allVariablesMap, collectionsMap) {
 /**
  * Register Figma API tools with the MCP server
  */
-export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getConsoleMonitor, getBrowserManager, ensureInitialized, variablesCache, options, getDesktopConnector) {
+export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variablesCache, options, getDesktopConnector) {
     const isRemoteMode = options?.isRemoteMode ?? false;
+    /**
+     * Build a designer-readable REST-auth error tagged with our MCP identity.
+     * Shows only the remediation path that applies to the caller's mode — local
+     * users never see OAuth instructions, cloud users never see env-var
+     * instructions. Identity prefix lets LLMs disambiguate this error from
+     * errors thrown by other Figma-related MCP servers running in parallel.
+     */
+    function restAuthError(context, originalError, extra) {
+        const remediation = isRemoteMode
+            ? "Re-authenticate via the OAuth flow in your MCP client, or pass a Figma personal access token (figd_...) as a Bearer token."
+            : "Set FIGMA_ACCESS_TOKEN in your MCP client config to a Figma personal access token. Generate one at https://www.figma.com/developers/api#access-tokens.";
+        return identifiedError(`${context}\nError: ${originalError}\n\nTo fix: ${remediation}${extra ? `\n\n${extra}` : ""}`);
+    }
     // Tool 8: Get File Data (General Purpose)
     // NOTE: For specific use cases, consider using specialized tools:
     // - figma_get_component_for_development: For UI component implementation
@@ -688,13 +707,7 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             }
             catch (apiError) {
                 const errorMessage = apiError instanceof Error ? apiError.message : String(apiError);
-                throw new Error(`Cannot retrieve file data. REST API authentication required.\n` +
-                    `Error: ${errorMessage}\n\n` +
-                    `To fix:\n` +
-                    `1. Local mode: Set FIGMA_ACCESS_TOKEN environment variable\n` +
-                    `2. Cloud mode: Authenticate via OAuth\n\n` +
-                    `Note: figma_get_file_data requires REST API access. ` +
-                    `For component-specific data, use figma_get_component which has Desktop Bridge fallback.`);
+                throw restAuthError("Cannot retrieve file data. REST API authentication required.", errorMessage, "Note: figma_get_file_data requires REST API access. For component-specific data, use figma_get_component which has Desktop Bridge fallback.");
             }
             // Use provided URL or current URL from browser
             const url = fileUrl || getCurrentUrl();
@@ -843,18 +856,17 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
     /**
      * Tool 9: Get Variables (Design Tokens)
      *
-     * WORKFLOW:
-     * - Primary: Attempts to fetch variables via Figma REST API (requires Enterprise plan)
-     * - Fallback: On 403 error, provides console-based extraction snippet
-     *
-     * TWO-CALL PATTERN (when API unavailable):
-     * 1. First call: Returns snippet + instructions (useConsoleFallback: true, default)
-     * 2. User runs snippet in Figma plugin console
-     * 3. Second call: Parses captured data (parseFromConsole: true)
+     * RESOLUTION ORDER (in order, first success wins):
+     *   1. Cache hit (if fresh and refreshCache=false)
+     *   2. Desktop Bridge plugin via WebSocket — works on any Figma plan
+     *   3. REST API — requires Enterprise plan (returns 403 otherwise)
+     *   4. Styles API — partial fallback for non-Enterprise (styles, not variables)
      *
-     * IMPORTANT: Snippet requires Figma Plugin API context, not browser DevTools console.
+     * The legacy `parseFromConsole` two-call console-snippet workflow was
+     * 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. Enterprise plan required for Variables API; automatically falls back to Styles API or console-based extraction if unavailable. 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). 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.", {
         fileUrl: z
             .string()
             .url()
@@ -912,7 +924,7 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             .boolean()
             .optional()
             .default(false)
-            .describe("Return variables as resource_link references instead of full data. Drastically reduces payload size (100+ variables = ~20KB vs >1MB). Use with figma_get_variable_by_id to fetch specific variables. Recommended for large variable sets. Default: false"),
+            .describe("Return variables as resource_link references instead of full data. Drastically reduces payload size (100+ variables = ~20KB vs >1MB). Recommended for large variable sets — combine with format='filtered' + namePattern/collection/mode to fetch only the variables you need. Default: false"),
         refreshCache: z
             .boolean()
             .optional()
@@ -922,20 +934,12 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             .boolean()
             .optional()
             .default(true)
-            .describe("Enable automatic fallback to console-based extraction when REST API returns 403 (Figma Enterprise plan required). " +
-            "When enabled, provides a JavaScript snippet that users run in Figma's plugin console. " +
-            "This is STEP 1 of a two-call workflow. After receiving the snippet, instruct the user to run it, then call this tool again with parseFromConsole=true. " +
-            "Default: true. Set to false only to disable the fallback entirely."),
+            .describe("DEPRECATED — has no effect. The console-snippet workflow was removed in the Phase 3 CDP cleanup; the Desktop Bridge plugin now handles all non-REST variable extraction automatically. Kept for parameter compatibility only — safe to ignore."),
         parseFromConsole: z
             .boolean()
             .optional()
             .default(false)
-            .describe("Parse variables from console logs after user has executed the snippet. " +
-            "This is STEP 2 of the two-call workflow. Set to true ONLY after: " +
-            "(1) you received a console snippet from the first call, " +
-            "(2) instructed the user to run it in Figma's PLUGIN console (Plugins → Development → Open Console or existing plugin), " +
-            "(3) user confirmed they ran the snippet and saw '✅ Variables data captured!' message. " +
-            "Default: false. Never set to true on the first call."),
+            .describe("DEPRECATED — setting this to true now raises an explicit error. The Puppeteer-based console parser no longer exists. Open the Figma Console MCP Desktop Bridge plugin in Figma Desktop and call figma_get_variables() without parseFromConsole; the plugin returns full variable data through the WebSocket bridge."),
         page: z
             .number()
             .int()
@@ -1271,13 +1275,7 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             // Check if REST API token is available
             const hasToken = !!process.env.FIGMA_ACCESS_TOKEN;
             let restApiSucceeded = false;
-            // Detect Desktop Bridge availability early (needed for priority decision)
-            if (ensureInitialized && !getDesktopConnector && !parseFromConsole) {
-                logger.info("Calling ensureInitialized to initialize browser manager (legacy path)");
-                await ensureInitialized();
-            }
-            const browserManager = getBrowserManager?.();
-            const hasDesktopConnection = !!getDesktopConnector || !!browserManager;
+            const hasDesktopConnection = !!getDesktopConnector;
             // PRIORITY LOGIC:
             // 1. If Desktop Bridge connected → Try Desktop Bridge FIRST (instant, all plans, full Plugin API data)
             // 2. If no Desktop Bridge OR it fails → Try REST API as fallback (Enterprise users)
@@ -1434,7 +1432,7 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
                         const content = [
                             {
                                 type: "text",
-                                text: `Variables for file ${fileKey} (${localFormatted.variables.length} variables). Use figma_get_variable_by_id to fetch specific variables:\n\n`,
+                                text: `Variables for file ${fileKey} (${localFormatted.variables.length} variables). Call figma_get_variables again with format='filtered' and a namePattern/collection/mode filter to fetch specific variables:\n\n`,
                             },
                         ];
                         for (const variable of localFormatted.variables) {
@@ -1529,21 +1527,11 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             }
             // PRIMARY: Try Desktop Bridge (instant, all plans, full Plugin API data including aliases)
             // Also used as fallback when REST API fails (403, timeout, rate limit)
-            if (hasDesktopConnection && !parseFromConsole && !restApiSucceeded) {
+            if (hasDesktopConnection && !parseFromConsole && !restApiSucceeded && getDesktopConnector) {
                 try {
                     logger.info({ fileKey }, "Attempting to get variables via Desktop connection");
-                    let connector;
-                    if (getDesktopConnector) {
-                        connector = await getDesktopConnector();
-                    }
-                    else {
-                        // Fallback: direct connector (legacy path)
-                        const { FigmaDesktopConnector } = await import('./figma-desktop-connector.js');
-                        const page = await browserManager.getPage();
-                        connector = new FigmaDesktopConnector(page);
-                        await connector.initialize();
-                    }
-                    logger.info({ transport: connector.getTransportType?.() || 'unknown' }, "Desktop connector ready");
+                    const connector = await getDesktopConnector();
+                    logger.info({ transport: connector.getTransportType?.() || 'websocket' }, "Desktop connector ready");
                     // When refreshCache is requested, bypass the plugin UI's stale snapshot
                     // and fetch live data directly from the Figma Plugin API
                     const desktopResult = refreshCache
@@ -1551,7 +1539,7 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
                         : await connector.getVariablesFromPluginUI(fileKey);
                     // EXECUTE_CODE responses come back wrapped one level deeper:
                     // `{ success: true, result: { success: true, variables, ... } }`
-                    // because handleResult in ui-full.html nests the script return value
+                    // because handleResult in ui.html nests the script return value
                     // under `result`. The plugin-UI cache path (GET_VARIABLES_DATA) does
                     // not nest. Unwrap when we detect the EXECUTE_CODE shape so both
                     // paths produce a uniform { success, variables, ... } below. See #68.
@@ -1742,21 +1730,6 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
                         message: errorMessage,
                         stack: errorStack
                     }, "Desktop connection failed, falling back to other methods");
-                    // Try to log to browser console if we have access to page
-                    try {
-                        if (browserManager) {
-                            const page = await browserManager.getPage();
-                            await page.evaluate((msg, stack) => {
-                                console.error('[FIGMA_TOOLS] ❌ Desktop connection failed:', msg);
-                                if (stack) {
-                                    console.error('[FIGMA_TOOLS] Stack trace:', stack);
-                                }
-                            }, errorMessage, errorStack);
-                        }
-                    }
-                    catch (logError) {
-                        // Ignore logging errors
-                    }
                     // Continue to try REST API fallback
                 }
             }
@@ -1827,53 +1800,18 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
                     logger.warn({ error: msg, fileKey }, "REST API fallback failed");
                 }
             }
-            // LAST RESORT: Parse from console logs if requested
+            // LAST RESORT: parseFromConsole was a Puppeteer-era workflow that read
+            // the magic-string output of a console snippet from the browser's
+            // console buffer. After the Phase 3 CDP cleanup there is no longer a
+            // Puppeteer-attached console for the snippet's output to land in, so
+            // the flag has become a no-op. Tell the caller what to do instead.
             if (parseFromConsole) {
-                const consoleMonitor = getConsoleMonitor?.();
-                if (!consoleMonitor) {
-                    throw new Error("Console monitoring not available. Make sure browser is connected to Figma.");
-                }
-                logger.info({ fileKey }, "Parsing variables from console logs");
-                // Get recent logs
-                const logs = consoleMonitor.getLogs({ count: 100, level: "log" });
-                const varLog = snippetInjector.findVariablesLog(logs);
-                if (!varLog) {
-                    throw new Error("No variables found in console logs.\n\n" +
-                        "Did you run the snippet in Figma's plugin console? Here's the correct workflow:\n\n" +
-                        "1. Call figma_get_variables() without parameters (you may have already done this)\n" +
-                        "2. Copy the provided snippet\n" +
-                        "3. Open Figma Desktop → Plugins → Development → Open Console\n" +
-                        "4. Paste and run the snippet in the PLUGIN console (not browser DevTools)\n" +
-                        "5. Wait for '✅ Variables data captured!' confirmation\n" +
-                        "6. Then call figma_get_variables({ parseFromConsole: true })\n\n" +
-                        "Note: The browser console won't work - you need a plugin console for the figma.variables API.");
-                }
-                // Parse variables from log
-                const parsedData = snippetInjector.parseVariablesFromLog(varLog);
-                if (!parsedData) {
-                    throw new Error("Failed to parse variables from console log");
-                }
-                return {
-                    content: [
-                        {
-                            type: "text",
-                            text: JSON.stringify({
-                                fileKey,
-                                source: "console_capture",
-                                local: {
-                                    summary: {
-                                        total_variables: parsedData.variables.length,
-                                        total_collections: parsedData.variableCollections.length,
-                                    },
-                                    collections: parsedData.variableCollections,
-                                    variables: parsedData.variables,
-                                },
-                                timestamp: parsedData.timestamp,
-                                enriched: false,
-                            }),
-                        },
-                    ],
-                };
+                throw identifiedError("parseFromConsole is no longer supported.\n\n" +
+                    "The console-snippet workflow it relied on required a Puppeteer browser " +
+                    "connection to Figma Desktop, which was removed in Phase 3 of the cleanup. " +
+                    "To extract variables, open the Figma Console MCP Desktop Bridge plugin in " +
+                    "Figma Desktop and call figma_get_variables() without parseFromConsole — " +
+                    "the plugin returns full variable data through the WebSocket bridge.");
             }
             // No more fallback options available
             throw new Error(`Cannot retrieve variables. All methods failed.\n\n` +
@@ -1882,8 +1820,7 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
                 `✗ Desktop Bridge (failed or not available)\n` +
                 `\nTo fix:\n` +
                 `1. If you have FIGMA_ACCESS_TOKEN: Check your token permissions\n` +
-                `2. Install and run the Figma Desktop Bridge plugin\n` +
-                `3. Alternative: Use parseFromConsole=true with console snippet workflow`);
+                `2. Install and run the Figma Desktop Bridge plugin and re-run this tool`);
         }
         catch (error) {
             logger.error({ error }, "Failed to get variables");
@@ -1898,11 +1835,7 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
                     }
                     catch (apiError) {
                         const errorMessage = apiError instanceof Error ? apiError.message : String(apiError);
-                        throw new Error(`Cannot retrieve variables or styles. REST API authentication required for both.\n` +
-                            `Error: ${errorMessage}\n\n` +
-                            `To fix:\n` +
-                            `1. Local mode: Set FIGMA_ACCESS_TOKEN environment variable\n` +
-                            `2. Cloud mode: Authenticate via OAuth`);
+                        throw restAuthError("Cannot retrieve variables or styles. REST API authentication required for both.", errorMessage);
                     }
                     // Use the Styles API directly - much faster than getFile!
                     const stylesData = await api.getStyles(fileKey);
@@ -2006,26 +1939,10 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             }
             logger.info({ fileKey, nodeId, format, enrich }, "Fetching component data");
             // PRIORITY 1: Try Desktop Bridge plugin UI first (has reliable description field!)
-            if (getDesktopConnector || (getBrowserManager && ensureInitialized)) {
+            if (getDesktopConnector) {
                 try {
                     logger.info({ nodeId }, "Attempting to get component via Desktop Bridge plugin UI");
-                    let connector;
-                    if (getDesktopConnector) {
-                        connector = await getDesktopConnector();
-                    }
-                    else {
-                        // Fallback: direct connector (legacy path)
-                        if (ensureInitialized)
-                            await ensureInitialized();
-                        const browserManager = getBrowserManager?.();
-                        if (!browserManager) {
-                            throw new Error("Browser manager not available after initialization");
-                        }
-                        const { FigmaDesktopConnector } = await import('./figma-desktop-connector.js');
-                        const page = await browserManager.getPage();
-                        connector = new FigmaDesktopConnector(page);
-                        await connector.initialize();
-                    }
+                    const connector = await getDesktopConnector();
                     const desktopResult = await connector.getComponentFromPluginUI(nodeId);
                     if (desktopResult.success && desktopResult.component) {
                         logger.info({
@@ -2132,13 +2049,10 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             }
             catch (apiError) {
                 const errorMessage = apiError instanceof Error ? apiError.message : String(apiError);
-                throw new Error(`Cannot retrieve component data. Both Desktop Bridge and REST API are unavailable.\n` +
-                    `Desktop Bridge: ${getDesktopConnector || (getBrowserManager && ensureInitialized) ? 'Failed (see logs above)' : 'Not available (local mode only)'}\n` +
-                    `REST API: ${errorMessage}\n\n` +
-                    `To fix:\n` +
-                    `1. Local mode: Set FIGMA_ACCESS_TOKEN environment variable, OR ensure Figma Desktop Bridge plugin is running\n` +
-                    `2. Cloud mode: Authenticate via OAuth\n` +
-                    `3. Ensure the Desktop Bridge plugin is running in Figma Desktop`);
+                const dbStatus = getDesktopConnector
+                    ? "Failed (see logs above)"
+                    : "Not available";
+                throw restAuthError("Cannot retrieve component data. Both Desktop Bridge and REST API are unavailable.", `Desktop Bridge: ${dbStatus}; REST API: ${errorMessage}`, "Alternatively: open the Figma Desktop Bridge plugin in Figma Desktop to enable the plugin-based fallback.");
             }
             const componentData = await api.getComponentData(fileKey, nodeId);
             if (!componentData) {
@@ -2267,11 +2181,7 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             }
             catch (apiError) {
                 const errorMessage = apiError instanceof Error ? apiError.message : String(apiError);
-                throw new Error(`Cannot retrieve styles. REST API authentication required.\n` +
-                    `Error: ${errorMessage}\n\n` +
-                    `To fix:\n` +
-                    `1. Local mode: Set FIGMA_ACCESS_TOKEN environment variable\n` +
-                    `2. Cloud mode: Authenticate via OAuth`);
+                throw restAuthError("Cannot retrieve styles. REST API authentication required.", errorMessage);
             }
             const url = fileUrl || getCurrentUrl();
             if (!url) {
@@ -2406,13 +2316,7 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             }
             catch (apiError) {
                 const errorMessage = apiError instanceof Error ? apiError.message : String(apiError);
-                throw new Error(`Cannot render component image. REST API authentication required.\n` +
-                    `Error: ${errorMessage}\n\n` +
-                    `To fix:\n` +
-                    `1. Local mode: Set FIGMA_ACCESS_TOKEN environment variable\n` +
-                    `2. Cloud mode: Authenticate via OAuth\n\n` +
-                    `Note: For component screenshots, figma_capture_screenshot may work as an alternative ` +
-                    `if the Desktop Bridge plugin is connected.`);
+                throw restAuthError("Cannot render component image. REST API authentication required.", errorMessage, "Note: For component screenshots, figma_capture_screenshot may work as an alternative if the Desktop Bridge plugin is connected.");
             }
             const url = fileUrl || getCurrentUrl();
             if (!url) {
@@ -2525,13 +2429,7 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             }
             catch (apiError) {
                 const errorMessage = apiError instanceof Error ? apiError.message : String(apiError);
-                throw new Error(`Cannot retrieve component for development. REST API authentication required.\n` +
-                    `Error: ${errorMessage}\n\n` +
-                    `To fix:\n` +
-                    `1. Local mode: Set FIGMA_ACCESS_TOKEN environment variable\n` +
-                    `2. Cloud mode: Authenticate via OAuth\n\n` +
-                    `Note: For component metadata, figma_get_component has Desktop Bridge fallback ` +
-                    `that works without token (requires the Desktop Bridge plugin to be connected).`);
+                throw restAuthError("Cannot retrieve component for development. REST API authentication required.", errorMessage, "Note: For component metadata, figma_get_component has a Desktop Bridge fallback that works without a token (requires the Desktop Bridge plugin to be connected).");
             }
             const url = fileUrl || getCurrentUrl();
             if (!url) {
@@ -2971,11 +2869,7 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             }
             catch (apiError) {
                 const errorMessage = apiError instanceof Error ? apiError.message : String(apiError);
-                throw new Error(`Cannot retrieve file data for plugin development. REST API authentication required.\n` +
-                    `Error: ${errorMessage}\n\n` +
-                    `To fix:\n` +
-                    `1. Local mode: Set FIGMA_ACCESS_TOKEN environment variable\n` +
-                    `2. Cloud mode: Authenticate via OAuth`);
+                throw restAuthError("Cannot retrieve file data for plugin development. REST API authentication required.", errorMessage);
             }
             const url = fileUrl || getCurrentUrl();
             if (!url) {
@@ -3166,33 +3060,6 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
                     result = { success: true, image: result };
                 }
             }
-            // Legacy CDP fallback (only when no connector factory is available)
-            if (!result && !getDesktopConnector) {
-                const browserManager = getBrowserManager?.();
-                if (!browserManager) {
-                    throw new Error("Desktop Bridge not available. To capture screenshots:\n" +
-                        "1. Open your Figma file in Figma Desktop\n" +
-                        "2. Install and run the 'Figma Console MCP' plugin\n" +
-                        "3. Ensure the plugin shows 'MCP ready' status");
-                }
-                if (ensureInitialized) {
-                    await ensureInitialized();
-                }
-                const page = await browserManager.getPage();
-                const frames = page.frames();
-                for (const frame of frames) {
-                    try {
-                        const hasFunction = await frame.evaluate('typeof window.captureScreenshot === "function"');
-                        if (hasFunction) {
-                            result = await frame.evaluate(`window.captureScreenshot(${JSON.stringify(nodeId || '')}, ${JSON.stringify({ format, scale })})`);
-                            break;
-                        }
-                    }
-                    catch {
-                        continue;
-                    }
-                }
-            }
             if (!result) {
                 throw new Error("Desktop Bridge plugin not found. Ensure the 'Figma Console MCP' plugin is running in Figma Desktop.");
             }
@@ -3271,33 +3138,6 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
                 logger.info({ transport: connector.getTransportType?.() || 'unknown' }, "Instance properties via connector");
                 result = await connector.setInstanceProperties(nodeId, properties);
             }
-            // Legacy CDP fallback (only when no connector factory is available)
-            if (!result && !getDesktopConnector) {
-                const browserManager = getBrowserManager?.();
-                if (!browserManager) {
-                    throw new Error("Desktop Bridge not available. To set instance properties:\n" +
-                        "1. Open your Figma file in Figma Desktop\n" +
-                        "2. Install and run the 'Figma Console MCP' plugin\n" +
-                        "3. Ensure the plugin shows 'MCP ready' status");
-                }
-                if (ensureInitialized) {
-                    await ensureInitialized();
-                }
-                const page = await browserManager.getPage();
-                const frames = page.frames();
-                for (const frame of frames) {
-                    try {
-                        const hasFunction = await frame.evaluate('typeof window.setInstanceProperties === "function"');
-                        if (hasFunction) {
-                            result = await frame.evaluate(`window.setInstanceProperties(${JSON.stringify(nodeId)}, ${JSON.stringify(properties)})`);
-                            break;
-                        }
-                    }
-                    catch {
-                        continue;
-                    }
-                }
-            }
             if (!result) {
                 throw new Error("Desktop Bridge plugin not found. Ensure the 'Figma Console MCP' plugin is running in Figma Desktop.");
             }

package/dist/cloudflare/core/identity.js

@@ -0,0 +1,96 @@
+/**
+ * Server identity helpers.
+ *
+ * When a user has multiple Figma-related MCP servers configured at once
+ * (e.g. figma-console-mcp alongside Figma's native codegen MCP), an LLM can
+ * conflate errors from one server with the troubleshooting copy of another —
+ * producing remediation advice that points at the wrong tool. Tagging our
+ * responses with an explicit `[figma-console-mcp]` prefix and an `_mcp`
+ * field makes attribution unambiguous.
+ */
+export const MCP_NAME = "figma-console-mcp";
+export const ERROR_PREFIX = `[${MCP_NAME}]`;
+/**
+ * Prefix a thrown-error message with our MCP identity so cross-tool errors
+ * can't be mistakenly attributed to this server.
+ */
+export function identifiedError(message) {
+    return new Error(`${ERROR_PREFIX} ${message}`);
+}
+/**
+ * Tag a response payload with our MCP identity at the top level.
+ * The `_mcp` field is read by LLMs alongside the rest of the response and
+ * gives them a reliable signal for "which server produced this output".
+ */
+export function withIdentity(data) {
+    return { _mcp: MCP_NAME, ...data };
+}
+/**
+ * Tag every text/JSON content block in a tool response with our MCP identity.
+ * Idempotent — already-tagged content (from adaptiveResponse or explicit
+ * withIdentity calls) is left alone. Non-JSON text content is left alone.
+ */
+function tagToolResponse(result) {
+    if (!result ||
+        typeof result !== "object" ||
+        !("content" in result) ||
+        !Array.isArray(result.content)) {
+        return result;
+    }
+    const r = result;
+    const newContent = r.content.map((item) => {
+        if (item.type !== "text" || typeof item.text !== "string")
+            return item;
+        try {
+            const parsed = JSON.parse(item.text);
+            if (parsed &&
+                typeof parsed === "object" &&
+                !Array.isArray(parsed) &&
+                !("_mcp" in parsed)) {
+                return { ...item, text: JSON.stringify({ _mcp: MCP_NAME, ...parsed }) };
+            }
+        }
+        catch {
+            // Not JSON — leave the text untouched (e.g. AI instruction blocks
+            // emitted by adaptiveResponse, or plain-text error messages).
+        }
+        return item;
+    });
+    return { ...r, content: newContent };
+}
+/**
+ * Monkey-patch an MCP server instance so every tool registered on it gets
+ * identity tagging applied to its responses and an identity prefix on any
+ * Error it throws — without modifying the ~97 individual tool handlers.
+ *
+ * Call this once, immediately after constructing the McpServer, BEFORE any
+ * tool registration calls run. The wrap is idempotent at the response level
+ * (tools that already tag themselves via withIdentity or adaptiveResponse
+ * won't get double-tagged).
+ *
+ * Adds attribution coverage to every response path uniformly — see
+ * project_lauren_cross_mcp_confusion for why this matters.
+ */
+export function wrapServerForIdentity(server) {
+    const target = server;
+    const originalTool = target.tool.bind(target);
+    target.tool = function (...args) {
+        if (args.length === 0 || typeof args[args.length - 1] !== "function") {
+            return originalTool(...args);
+        }
+        const handler = args[args.length - 1];
+        const wrappedHandler = async (...handlerArgs) => {
+            try {
+                const result = await handler(...handlerArgs);
+                return tagToolResponse(result);
+            }
+            catch (err) {
+                if (err instanceof Error && !err.message.startsWith(ERROR_PREFIX)) {
+                    err.message = `${ERROR_PREFIX} ${err.message}`;
+                }
+                throw err;
+            }
+        };
+        return originalTool(...args.slice(0, -1), wrappedHandler);
+    };
+}