figma-console-mcp 0.1.0

package/dist/core/figma-tools.js

@@ -0,0 +1,2300 @@
+/**
+ * Figma API MCP Tools
+ * MCP tool definitions for Figma REST API data extraction
+ */
+import { z } from "zod";
+import { extractFileKey, formatVariables, formatComponentData } from "./figma-api.js";
+import { createChildLogger } from "./logger.js";
+import { EnrichmentService } from "./enrichment/index.js";
+import { SnippetInjector } from "./snippet-injector.js";
+const logger = createChildLogger({ component: "figma-tools" });
+// Initialize enrichment service
+const enrichmentService = new EnrichmentService(logger);
+// Initialize snippet injector
+const snippetInjector = new SnippetInjector();
+// ============================================================================
+// Cache Management & Data Processing Helpers
+// ============================================================================
+/**
+ * Cache configuration
+ */
+const CACHE_TTL_MS = 5 * 60 * 1000; // 5 minutes
+const MAX_CACHE_ENTRIES = 10; // LRU eviction
+/**
+ * Check if cache entry is still valid based on TTL
+ */
+function isCacheValid(timestamp, ttlMs = CACHE_TTL_MS) {
+    return Date.now() - timestamp < ttlMs;
+}
+/**
+ * Rough token estimation for response size checking
+ * Approximation: 1 token ≈ 4 characters for JSON
+ */
+function estimateTokens(data) {
+    const jsonString = JSON.stringify(data);
+    return Math.ceil(jsonString.length / 4);
+}
+/**
+ * Response size thresholds for adaptive verbosity
+ * Based on typical Claude Desktop context window limits
+ */
+const RESPONSE_SIZE_THRESHOLDS = {
+    // Conservative thresholds to leave room for conversation context
+    IDEAL_SIZE_KB: 100, // Target size for optimal performance
+    WARNING_SIZE_KB: 200, // Start considering compression
+    CRITICAL_SIZE_KB: 500, // Must compress to avoid context exhaustion
+    MAX_SIZE_KB: 1000, // Absolute maximum before emergency compression
+};
+/**
+ * Calculate JSON string size in KB
+ */
+function calculateSizeKB(data) {
+    const jsonString = JSON.stringify(data);
+    return jsonString.length / 1024;
+}
+/**
+ * Generic adaptive response wrapper - automatically compresses responses that exceed size thresholds
+ * Can be used by any tool to prevent context window exhaustion
+ *
+ * @param responseData - The response data to potentially compress
+ * @param options - Configuration options for compression behavior
+ * @returns Response content array with optional AI instruction
+ */
+function adaptiveResponse(responseData, options) {
+    const sizeKB = calculateSizeKB(responseData);
+    // No compression needed
+    if (sizeKB <= RESPONSE_SIZE_THRESHOLDS.IDEAL_SIZE_KB) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify(responseData),
+                },
+            ],
+        };
+    }
+    // Determine compression level and message
+    let compressionLevel = "info";
+    let aiInstruction = "";
+    let shouldCompress = false;
+    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`;
+    }
+    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`;
+    }
+    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`;
+    }
+    // Map compression level to verbosity level
+    const verbosityMap = {
+        "info": "standard",
+        "warning": "summary",
+        "critical": "summary",
+        "emergency": "inventory"
+    };
+    // If compression needed, apply callback to reduce data
+    let finalData = responseData;
+    if (shouldCompress && options.compressionCallback) {
+        const targetVerbosity = verbosityMap[compressionLevel] || "summary";
+        finalData = options.compressionCallback(targetVerbosity);
+        // Add compression metadata
+        finalData.compression = {
+            originalSizeKB: Math.round(sizeKB),
+            finalSizeKB: Math.round(calculateSizeKB(finalData)),
+            compressionLevel,
+        };
+        logger.info({
+            tool: options.toolName,
+            originalSizeKB: sizeKB.toFixed(2),
+            finalSizeKB: calculateSizeKB(finalData).toFixed(2),
+            compressionLevel,
+        }, "Response compressed to prevent context exhaustion");
+    }
+    // Build AI instruction with suggested actions
+    if (shouldCompress) {
+        if (options.suggestedActions && options.suggestedActions.length > 0) {
+            aiInstruction += `To get more detail:\n`;
+            options.suggestedActions.forEach(action => {
+                aiInstruction += `• ${action}\n`;
+            });
+        }
+    }
+    // Build response content
+    const content = [
+        {
+            type: "text",
+            text: JSON.stringify(finalData),
+        },
+    ];
+    // Add AI instruction as separate content block if needed
+    if (aiInstruction) {
+        content.unshift({
+            type: "text",
+            text: aiInstruction.trim(),
+        });
+    }
+    return { content };
+}
+/**
+ * Adaptive verbosity system - automatically downgrades verbosity based on response size
+ * Returns adjusted verbosity level and compression info for AI instructions
+ *
+ * @deprecated Use adaptiveResponse instead for more flexible compression
+ */
+function adaptiveVerbosity(data, requestedVerbosity) {
+    const sizeKB = calculateSizeKB(data);
+    // No adjustment needed - response is within ideal size
+    if (sizeKB <= RESPONSE_SIZE_THRESHOLDS.IDEAL_SIZE_KB) {
+        return {
+            adjustedVerbosity: requestedVerbosity,
+            sizeKB,
+            wasCompressed: false,
+        };
+    }
+    // Determine appropriate verbosity based on size
+    let adjustedVerbosity = requestedVerbosity;
+    let compressionReason = "";
+    let aiInstruction = "";
+    if (sizeKB > RESPONSE_SIZE_THRESHOLDS.MAX_SIZE_KB) {
+        // Emergency: Force inventory mode
+        adjustedVerbosity = "inventory";
+        compressionReason = `Response size (${sizeKB.toFixed(0)}KB) exceeds maximum threshold (${RESPONSE_SIZE_THRESHOLDS.MAX_SIZE_KB}KB)`;
+        aiInstruction =
+            `⚠️ RESPONSE AUTO-COMPRESSED: The response was automatically reduced to 'inventory' verbosity (names/IDs only) because the full response would be ${sizeKB.toFixed(0)}KB, which would exhaust Claude Desktop's context window.\n\n` +
+                `To get more detail:\n` +
+                `• Use format='filtered' with collection/namePattern/mode filters to narrow the scope\n` +
+                `• Use pagination (page=1, pageSize=20) to retrieve data in smaller chunks\n` +
+                `• Use returnAsLinks=true to get resource_link references instead of full data\n\n` +
+                `Current response contains variable/collection names and IDs only.`;
+    }
+    else if (sizeKB > RESPONSE_SIZE_THRESHOLDS.CRITICAL_SIZE_KB) {
+        // Critical: Downgrade to summary if higher was requested
+        if (requestedVerbosity === "full" || requestedVerbosity === "standard") {
+            adjustedVerbosity = "summary";
+            compressionReason = `Response size (${sizeKB.toFixed(0)}KB) exceeds critical threshold (${RESPONSE_SIZE_THRESHOLDS.CRITICAL_SIZE_KB}KB)`;
+            aiInstruction =
+                `⚠️ RESPONSE AUTO-COMPRESSED: The response was automatically reduced to 'summary' verbosity because the ${requestedVerbosity} response would be ${sizeKB.toFixed(0)}KB, risking context window exhaustion.\n\n` +
+                    `To get more detail, use filtering options:\n` +
+                    `• format='filtered' with collection='CollectionName' to focus on specific collections\n` +
+                    `• namePattern='color' to filter by variable name\n` +
+                    `• mode='Light' to filter by mode\n` +
+                    `• pagination with smaller pageSize values\n\n` +
+                    `Current response includes variable names, types, and mode information.`;
+        }
+    }
+    else if (sizeKB > RESPONSE_SIZE_THRESHOLDS.WARNING_SIZE_KB) {
+        // Warning: Downgrade full to standard
+        if (requestedVerbosity === "full") {
+            adjustedVerbosity = "standard";
+            compressionReason = `Response size (${sizeKB.toFixed(0)}KB) exceeds warning threshold (${RESPONSE_SIZE_THRESHOLDS.WARNING_SIZE_KB}KB)`;
+            aiInstruction =
+                `ℹ️ RESPONSE OPTIMIZED: The response was automatically reduced to 'standard' verbosity because the full response would be ${sizeKB.toFixed(0)}KB.\n\n` +
+                    `This response includes essential variable properties. For specific details, use filtering:\n` +
+                    `• format='filtered' with collection/namePattern/mode filters\n` +
+                    `• Request verbosity='full' with specific filters to get complete data for a subset`;
+        }
+    }
+    const wasCompressed = adjustedVerbosity !== requestedVerbosity;
+    if (wasCompressed) {
+        logger.info({
+            originalVerbosity: requestedVerbosity,
+            adjustedVerbosity,
+            sizeKB: sizeKB.toFixed(2),
+            threshold: compressionReason,
+        }, "Adaptive compression applied");
+    }
+    return {
+        adjustedVerbosity,
+        sizeKB,
+        wasCompressed,
+        compressionReason: wasCompressed ? compressionReason : undefined,
+        aiInstruction: wasCompressed ? aiInstruction : undefined,
+    };
+}
+/**
+ * Generate compact summary of variables data (~2K tokens)
+ * Returns high-level overview with counts and names
+ */
+function generateSummary(data) {
+    const summary = {
+        fileKey: data.fileKey,
+        timestamp: data.timestamp,
+        source: data.source || 'cache',
+        overview: {
+            total_variables: data.variables?.length || 0,
+            total_collections: data.variableCollections?.length || 0,
+        },
+        collections: data.variableCollections?.map((c) => ({
+            id: c.id,
+            name: c.name,
+            modes: c.modes?.map((m) => ({ id: m.modeId, name: m.name })),
+            variable_count: c.variableIds?.length || 0,
+        })) || [],
+        variables_by_type: {},
+        variable_names: [],
+    };
+    // Count variables by type
+    const typeCount = {};
+    const names = [];
+    data.variables?.forEach((v) => {
+        typeCount[v.resolvedType] = (typeCount[v.resolvedType] || 0) + 1;
+        names.push(v.name);
+    });
+    summary.variables_by_type = typeCount;
+    summary.variable_names = names;
+    return summary;
+}
+/**
+ * Apply filters to variables data
+ */
+function applyFilters(data, filters, verbosity = "standard") {
+    let filteredVariables = [...(data.variables || [])];
+    let filteredCollections = [...(data.variableCollections || [])];
+    // Filter by collection name or ID
+    if (filters.collection) {
+        const collectionFilter = filters.collection.toLowerCase();
+        filteredCollections = filteredCollections.filter((c) => c.name?.toLowerCase().includes(collectionFilter) ||
+            c.id === filters.collection);
+        const collectionIds = new Set(filteredCollections.map((c) => c.id));
+        filteredVariables = filteredVariables.filter((v) => collectionIds.has(v.variableCollectionId));
+    }
+    // Filter by variable name pattern (regex or substring)
+    if (filters.namePattern) {
+        try {
+            const regex = new RegExp(filters.namePattern, 'i');
+            filteredVariables = filteredVariables.filter((v) => regex.test(v.name));
+        }
+        catch (e) {
+            // If regex fails, fall back to substring match
+            const pattern = filters.namePattern.toLowerCase();
+            filteredVariables = filteredVariables.filter((v) => v.name?.toLowerCase().includes(pattern));
+        }
+    }
+    // Find target mode ID if mode filter specified (needed for both filtering and transformation)
+    let targetModeId = null;
+    let targetModeName = null;
+    if (filters.mode) {
+        const modeFilter = filters.mode.toLowerCase();
+        // Try direct mode ID match first
+        if (data.variableCollections || filteredCollections.length > 0) {
+            for (const collection of filteredCollections) {
+                if (collection.modes) {
+                    const mode = collection.modes.find((m) => m.modeId === filters.mode ||
+                        m.name?.toLowerCase().includes(modeFilter));
+                    if (mode) {
+                        targetModeId = mode.modeId;
+                        targetModeName = mode.name;
+                        break;
+                    }
+                }
+            }
+        }
+    }
+    // Filter by mode name or ID
+    if (filters.mode) {
+        filteredVariables = filteredVariables.filter((v) => {
+            // Check if variable has values for the specified mode
+            if (v.valuesByMode) {
+                // Try to match by mode ID directly
+                if (v.valuesByMode[filters.mode]) {
+                    return true;
+                }
+                // Try using resolved targetModeId
+                if (targetModeId && v.valuesByMode[targetModeId]) {
+                    return true;
+                }
+                // Try to match by mode name through collections
+                const collection = filteredCollections.find((c) => c.id === v.variableCollectionId);
+                if (collection?.modes) {
+                    const mode = collection.modes.find((m) => m.name?.toLowerCase().includes(filters.mode.toLowerCase()) || m.modeId === filters.mode);
+                    return mode && v.valuesByMode[mode.modeId];
+                }
+            }
+            return false;
+        });
+    }
+    // Transform valuesByMode based on verbosity level
+    // This is critical for reducing response size with multi-mode variables
+    if (verbosity !== "full") {
+        filteredVariables = filteredVariables.map((v) => {
+            const variable = { ...v };
+            // Use original collections array for lookup, not filtered, since we need mode metadata
+            // Handle both variableCollections and collections property names
+            const collections = data.variableCollections || data.collections || [];
+            const collection = collections.find((c) => c.id === v.variableCollectionId);
+            if (verbosity === "inventory") {
+                // Inventory: Remove valuesByMode entirely, add mode count
+                delete variable.valuesByMode;
+                if (collection?.modes) {
+                    variable.modeCount = collection.modes.length;
+                }
+            }
+            else if (verbosity === "summary") {
+                // Summary: Replace valuesByMode with mode names array
+                if (variable.valuesByMode && collection?.modes) {
+                    variable.modeNames = collection.modes.map((m) => m.name);
+                    variable.modeCount = collection.modes.length;
+                }
+                delete variable.valuesByMode;
+            }
+            else if (verbosity === "standard") {
+                // Standard: If mode parameter specified, filter to that mode only
+                if (targetModeId && variable.valuesByMode) {
+                    const singleModeValue = variable.valuesByMode[targetModeId];
+                    variable.valuesByMode = { [targetModeId]: singleModeValue };
+                    variable.selectedMode = {
+                        modeId: targetModeId,
+                        modeName: targetModeName,
+                    };
+                }
+                // If no mode specified, keep all valuesByMode but add metadata for context
+                else if (variable.valuesByMode && collection?.modes) {
+                    variable.modeMetadata = collection.modes.map((m) => ({
+                        modeId: m.modeId,
+                        modeName: m.name,
+                    }));
+                }
+            }
+            return variable;
+        });
+        // Apply field-level filtering based on verbosity
+        if (verbosity === "inventory") {
+            filteredVariables = filteredVariables.map((v) => ({
+                id: v.id,
+                name: v.name,
+                resolvedType: v.resolvedType,
+                variableCollectionId: v.variableCollectionId,
+                ...(v.modeCount && { modeCount: v.modeCount }),
+            }));
+        }
+        else if (verbosity === "summary") {
+            filteredVariables = filteredVariables.map((v) => ({
+                id: v.id,
+                name: v.name,
+                resolvedType: v.resolvedType,
+                variableCollectionId: v.variableCollectionId,
+                ...(v.modeNames && { modeNames: v.modeNames }),
+                ...(v.modeCount && { modeCount: v.modeCount }),
+            }));
+        }
+        else if (verbosity === "standard") {
+            filteredVariables = filteredVariables.map((v) => ({
+                id: v.id,
+                name: v.name,
+                resolvedType: v.resolvedType,
+                valuesByMode: v.valuesByMode,
+                description: v.description,
+                variableCollectionId: v.variableCollectionId,
+                ...(v.scopes && { scopes: v.scopes }),
+                ...(v.selectedMode && { selectedMode: v.selectedMode }),
+                ...(v.modeMetadata && { modeMetadata: v.modeMetadata }),
+            }));
+        }
+        // For "full" verbosity, return all fields (no filtering)
+    }
+    // IMPORTANT: Only return filtered data, not the entire original data object
+    // The ...data spread was including massive metadata that bloated responses
+    return {
+        variables: filteredVariables,
+        variableCollections: filteredCollections,
+    };
+}
+/**
+ * Apply pagination to variables
+ */
+function paginateVariables(data, page = 1, pageSize = 50) {
+    const variables = data.variables || [];
+    const totalVariables = variables.length;
+    const totalPages = Math.ceil(totalVariables / pageSize);
+    // Validate page number
+    const currentPage = Math.max(1, Math.min(page, totalPages || 1));
+    // Calculate pagination
+    const startIndex = (currentPage - 1) * pageSize;
+    const endIndex = startIndex + pageSize;
+    const paginatedVariables = variables.slice(startIndex, endIndex);
+    return {
+        data: {
+            ...data,
+            variables: paginatedVariables,
+        },
+        pagination: {
+            currentPage,
+            pageSize,
+            totalVariables,
+            totalPages,
+            hasNextPage: currentPage < totalPages,
+            hasPrevPage: currentPage > 1,
+        },
+    };
+}
+/**
+ * Manage LRU cache eviction
+ */
+function evictOldestCacheEntry(cache) {
+    if (cache.size >= MAX_CACHE_ENTRIES) {
+        // Find oldest entry
+        let oldestKey = null;
+        let oldestTime = Infinity;
+        for (const [key, entry] of cache.entries()) {
+            if (entry.timestamp < oldestTime) {
+                oldestTime = entry.timestamp;
+                oldestKey = key;
+            }
+        }
+        if (oldestKey) {
+            cache.delete(oldestKey);
+            logger.info({ evictedKey: oldestKey }, 'Evicted oldest cache entry (LRU)');
+        }
+    }
+}
+/**
+ * Register Figma API tools with the MCP server
+ */
+export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getConsoleMonitor, getBrowserManager, ensureInitialized, variablesCache) {
+    // 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
+    // - figma_get_file_for_plugin: For plugin development
+    server.tool("figma_get_file_data", "Get full file structure and document tree. WARNING: Can consume large amounts of tokens. NOT recommended for component descriptions (use figma_get_component instead). Best for understanding file structure or finding component nodeIds. Start with verbosity='summary' and depth=1 for initial exploration.", {
+        fileUrl: z
+            .string()
+            .url()
+            .optional()
+            .describe("Figma file URL (e.g., https://figma.com/design/abc123). REQUIRED unless figma_navigate was already called. If not provided, ask the user to share their Figma file URL (they can copy it from Figma Desktop via right-click → 'Copy link')."),
+        depth: z
+            .number()
+            .min(0)
+            .max(3)
+            .optional()
+            .default(1)
+            .describe("How many levels of children to include (default: 1, max: 3). Start with 1 to prevent context exhaustion. Use 0 for full tree only when absolutely necessary."),
+        verbosity: z
+            .enum(["summary", "standard", "full"])
+            .optional()
+            .default("summary")
+            .describe("Controls payload size: 'summary' (IDs/names/types only, ~90% smaller - RECOMMENDED), 'standard' (essential properties, ~50% smaller), 'full' (everything). Default: summary for token efficiency."),
+        nodeIds: z
+            .array(z.string())
+            .optional()
+            .describe("Specific node IDs to retrieve (optional)"),
+        enrich: z
+            .boolean()
+            .optional()
+            .describe("Set to true when user asks for: file statistics, health metrics, design system audit, or quality analysis. Adds statistics, health scores, and audit summaries. Default: false"),
+    }, async ({ fileUrl, depth, nodeIds, enrich, verbosity }) => {
+        try {
+            const api = await getFigmaAPI();
+            // Use provided URL or current URL from browser
+            const url = fileUrl || getCurrentUrl();
+            if (!url) {
+                throw new Error("No Figma file URL provided. Either pass fileUrl parameter or call figma_navigate first.");
+            }
+            const fileKey = extractFileKey(url);
+            if (!fileKey) {
+                throw new Error(`Invalid Figma URL: ${url}`);
+            }
+            logger.info({ fileKey, depth, nodeIds, enrich, verbosity }, "Fetching file data");
+            const fileData = await api.getFile(fileKey, {
+                depth,
+                ids: nodeIds,
+            });
+            // Apply verbosity filtering to reduce payload size
+            const filterNode = (node, level) => {
+                if (!node)
+                    return node;
+                if (level === "summary") {
+                    // Summary: Only IDs, names, types (~90% reduction)
+                    return {
+                        id: node.id,
+                        name: node.name,
+                        type: node.type,
+                        ...(node.children && {
+                            children: node.children.map((child) => filterNode(child, level))
+                        }),
+                    };
+                }
+                if (level === "standard") {
+                    // Standard: Essential properties for plugin development (~50% reduction)
+                    const filtered = {
+                        id: node.id,
+                        name: node.name,
+                        type: node.type,
+                        visible: node.visible,
+                        locked: node.locked,
+                    };
+                    // Include bounds for layout calculations
+                    if (node.absoluteBoundingBox)
+                        filtered.absoluteBoundingBox = node.absoluteBoundingBox;
+                    if (node.size)
+                        filtered.size = node.size;
+                    // Include component/instance info for plugin work
+                    if (node.componentId)
+                        filtered.componentId = node.componentId;
+                    if (node.componentPropertyReferences)
+                        filtered.componentPropertyReferences = node.componentPropertyReferences;
+                    // Include basic styling (but not full details)
+                    if (node.fills && node.fills.length > 0) {
+                        filtered.fills = node.fills.map((fill) => ({
+                            type: fill.type,
+                            visible: fill.visible,
+                            ...(fill.color && { color: fill.color }),
+                        }));
+                    }
+                    // Include plugin data if present
+                    if (node.pluginData)
+                        filtered.pluginData = node.pluginData;
+                    if (node.sharedPluginData)
+                        filtered.sharedPluginData = node.sharedPluginData;
+                    // Recursively filter children
+                    if (node.children) {
+                        filtered.children = node.children.map((child) => filterNode(child, level));
+                    }
+                    return filtered;
+                }
+                // Full: Return everything
+                return node;
+            };
+            const filteredDocument = verbosity !== "full"
+                ? filterNode(fileData.document, verbosity || "standard")
+                : fileData.document;
+            let response = {
+                fileKey,
+                name: fileData.name,
+                lastModified: fileData.lastModified,
+                version: fileData.version,
+                document: filteredDocument,
+                components: fileData.components
+                    ? Object.keys(fileData.components).length
+                    : 0,
+                styles: fileData.styles
+                    ? Object.keys(fileData.styles).length
+                    : 0,
+                verbosity: verbosity || "standard",
+                ...(nodeIds && {
+                    requestedNodes: nodeIds,
+                    nodes: fileData.nodes,
+                }),
+            };
+            // Apply enrichment if requested
+            if (enrich) {
+                const enrichmentOptions = {
+                    enrich: true,
+                    include_usage: true,
+                };
+                response = await enrichmentService.enrichFileData({ ...response, ...fileData }, enrichmentOptions);
+            }
+            const finalResponse = {
+                ...response,
+                enriched: enrich || false,
+            };
+            // Use adaptive response to prevent context exhaustion
+            return adaptiveResponse(finalResponse, {
+                toolName: "figma_get_file_data",
+                compressionCallback: (adjustedLevel) => {
+                    // Re-apply node filtering with lower verbosity
+                    const level = adjustedLevel;
+                    const refiltered = {
+                        ...finalResponse,
+                        document: verbosity !== "full"
+                            ? filterNode(fileData.document, level)
+                            : fileData.document,
+                        verbosity: level,
+                    };
+                    return refiltered;
+                },
+                suggestedActions: [
+                    "Use verbosity='summary' with depth=1 for initial exploration",
+                    "Use verbosity='standard' for essential properties",
+                    "Request specific nodeIds to narrow the scope",
+                    "Reduce depth parameter (max 3, recommend 1-2)",
+                ],
+            });
+        }
+        catch (error) {
+            logger.error({ error }, "Failed to get file data");
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: errorMessage,
+                            message: "Failed to retrieve Figma file data",
+                            hint: "Make sure FIGMA_ACCESS_TOKEN is configured and the file is accessible",
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    /**
+     * 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)
+     *
+     * IMPORTANT: Snippet requires Figma Plugin API context, not browser DevTools console.
+     */
+    server.tool("figma_get_variables", {
+        fileUrl: z
+            .string()
+            .url()
+            .optional()
+            .describe("Figma file URL (e.g., https://figma.com/design/abc123). REQUIRED unless figma_navigate was already called. If not provided, ask the user to share their Figma file URL (they can copy it from Figma Desktop via right-click → 'Copy link')."),
+        includePublished: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Include published variables from libraries"),
+        verbosity: z
+            .enum(["inventory", "summary", "standard", "full"])
+            .optional()
+            .default("standard")
+            .describe("Controls payload size: 'inventory' (names/IDs only, ~95% smaller, use with filtered), 'summary' (names/values only, ~80% smaller), 'standard' (essential properties, ~45% smaller), 'full' (everything). Default: standard"),
+        enrich: z
+            .boolean()
+            .optional()
+            .describe("Set to true when user asks for: CSS/Sass/Tailwind exports, code examples, design tokens, usage information, dependencies, or any export format. Adds resolved values, dependency graphs, and usage analysis. Default: false"),
+        include_usage: z
+            .boolean()
+            .optional()
+            .describe("Include usage in styles and components (requires enrich=true)"),
+        include_dependencies: z
+            .boolean()
+            .optional()
+            .describe("Include variable dependency graph (requires enrich=true)"),
+        include_exports: z
+            .boolean()
+            .optional()
+            .describe("Include export format examples (requires enrich=true)"),
+        export_formats: z
+            .array(z.enum(["css", "sass", "tailwind", "typescript", "json"]))
+            .optional()
+            .describe("Which code formats to generate examples for. Use when user mentions specific formats like 'CSS', 'Tailwind', 'SCSS', 'TypeScript', etc. Automatically enables enrichment."),
+        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"),
+        collection: z
+            .string()
+            .optional()
+            .describe("Filter variables by collection name or ID. Case-insensitive substring match. Only applies when format='filtered'. Example: 'Primitives' or 'VariableCollectionId:123'"),
+        namePattern: z
+            .string()
+            .optional()
+            .describe("Filter variables by name using regex pattern or substring. Case-insensitive. Only applies when format='filtered'. Example: 'color/brand' or '^typography'"),
+        mode: z
+            .string()
+            .optional()
+            .describe("Filter variables by mode name or ID. Only returns variables that have values for this mode. Only applies when format='filtered'. Example: 'Light' or 'Dark'"),
+        returnAsLinks: z
+            .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"),
+        refreshCache: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Force refresh cache by fetching fresh data from Figma. Use when data may have changed since last fetch. Default: false (use cached data if available and fresh)"),
+        useConsoleFallback: z
+            .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."),
+        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."),
+        page: z
+            .number()
+            .int()
+            .min(1)
+            .optional()
+            .default(1)
+            .describe("Page number for paginated results (1-based). Use when response is too large (>1MB). Each page returns up to 50 variables."),
+        pageSize: z
+            .number()
+            .int()
+            .min(1)
+            .max(100)
+            .optional()
+            .default(50)
+            .describe("Number of variables per page (1-100). Default: 50. Smaller values reduce response size."),
+    }, async ({ fileUrl, includePublished, verbosity, enrich, include_usage, include_dependencies, include_exports, export_formats, format, collection, namePattern, mode, returnAsLinks, refreshCache, useConsoleFallback, parseFromConsole, page, pageSize }) => {
+        // Extract fileKey outside try block so it's available in catch block
+        const url = fileUrl || getCurrentUrl();
+        if (!url) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "No Figma file URL provided",
+                            message: "Either pass fileUrl parameter or call figma_navigate first."
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        const fileKey = extractFileKey(url);
+        if (!fileKey) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: `Invalid Figma URL: ${url}`,
+                            message: "Could not extract file key from URL"
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+        try {
+            // =====================================================================
+            // CACHE-FIRST LOGIC: Check if we have cached data before fetching
+            // =====================================================================
+            let cachedData = null;
+            let shouldFetch = true;
+            if (variablesCache && !parseFromConsole) {
+                const cacheEntry = variablesCache.get(fileKey);
+                if (cacheEntry) {
+                    const isValid = isCacheValid(cacheEntry.timestamp);
+                    if (isValid && !refreshCache) {
+                        // Cache hit! Use cached data
+                        cachedData = cacheEntry.data;
+                        shouldFetch = false;
+                        logger.info({
+                            fileKey,
+                            cacheAge: Date.now() - cacheEntry.timestamp,
+                            variableCount: cachedData.variables?.length,
+                        }, 'Using cached variables data');
+                    }
+                    else if (!isValid) {
+                        logger.info({ fileKey, cacheAge: Date.now() - cacheEntry.timestamp }, 'Cache expired, will refresh');
+                    }
+                    else if (refreshCache) {
+                        logger.info({ fileKey }, 'Refresh cache requested, will fetch fresh data');
+                    }
+                }
+                else {
+                    logger.info({ fileKey }, 'No cache entry found, will fetch data');
+                }
+            }
+            // If we have cached data, skip fetching and jump to formatting
+            if (cachedData && !shouldFetch) {
+                // Apply format logic based on user request
+                let responseData = cachedData;
+                let paginationInfo = null;
+                if (format === 'summary') {
+                    // Return compact summary
+                    responseData = generateSummary(cachedData);
+                    logger.info({ fileKey, estimatedTokens: estimateTokens(responseData) }, 'Generated summary from cache');
+                }
+                else if (format === 'filtered') {
+                    // Apply filters with verbosity-aware valuesByMode transformation
+                    responseData = applyFilters(cachedData, {
+                        collection,
+                        namePattern,
+                        mode,
+                    }, verbosity || 'standard');
+                    // ALWAYS apply pagination for filtered results to prevent 1MB limit
+                    // Default to page 1, pageSize 50 if not specified
+                    const paginated = paginateVariables(responseData, page || 1, pageSize || 50);
+                    responseData = paginated.data;
+                    paginationInfo = paginated.pagination;
+                    // Apply verbosity filtering to minimize payload size
+                    // For filtered results, default to "inventory" for maximum size reduction
+                    const effectiveVerbosity = verbosity || "inventory";
+                    // CRITICAL FIX: Only include collections referenced by paginated variables
+                    const referencedCollectionIds = new Set(responseData.variables.map((v) => v.variableCollectionId));
+                    responseData.variableCollections = responseData.variableCollections.filter((c) => referencedCollectionIds.has(c.id));
+                    // Filter variables to minimal needed fields
+                    responseData.variables = responseData.variables.map((v) => {
+                        if (effectiveVerbosity === "inventory") {
+                            // Ultra-minimal: just names and IDs for inventory purposes
+                            // If mode filter is specified, include only that mode's value
+                            const result = {
+                                id: v.id,
+                                name: v.name,
+                                collectionId: v.variableCollectionId,
+                            };
+                            // If mode filter specified, include just that single mode's value
+                            if (mode && v.valuesByMode) {
+                                // Find the mode ID from the collection
+                                const collection = responseData.variableCollections.find((c) => c.id === v.variableCollectionId);
+                                if (collection?.modes) {
+                                    const modeObj = collection.modes.find((m) => m.name?.toLowerCase().includes(mode.toLowerCase()) || m.modeId === mode);
+                                    if (modeObj && v.valuesByMode[modeObj.modeId]) {
+                                        result.value = v.valuesByMode[modeObj.modeId];
+                                        result.mode = modeObj.name;
+                                    }
+                                }
+                            }
+                            return result;
+                        }
+                        if (effectiveVerbosity === "summary") {
+                            return {
+                                id: v.id,
+                                name: v.name,
+                                resolvedType: v.resolvedType,
+                                valuesByMode: v.valuesByMode,
+                                variableCollectionId: v.variableCollectionId,
+                                // Include modeNames and modeCount added by applyFilters
+                                ...(v.modeNames && { modeNames: v.modeNames }),
+                                ...(v.modeCount && { modeCount: v.modeCount }),
+                            };
+                        }
+                        if (effectiveVerbosity === "standard") {
+                            return {
+                                id: v.id,
+                                name: v.name,
+                                resolvedType: v.resolvedType,
+                                valuesByMode: v.valuesByMode,
+                                description: v.description,
+                                variableCollectionId: v.variableCollectionId,
+                            };
+                        }
+                        return v; // full
+                    });
+                    // Filter collections to remove massive variableIds arrays
+                    responseData.variableCollections = responseData.variableCollections.map((c) => {
+                        if (effectiveVerbosity === "inventory") {
+                            // Ultra-minimal: just ID and name, mode names only (no full mode objects)
+                            return {
+                                id: c.id,
+                                name: c.name,
+                                modeNames: c.modes?.map((m) => m.name) || [],
+                            };
+                        }
+                        if (effectiveVerbosity === "summary") {
+                            return {
+                                id: c.id,
+                                name: c.name,
+                                modes: c.modes, // Keep modes for user to understand mode structure
+                            };
+                        }
+                        if (effectiveVerbosity === "standard") {
+                            return {
+                                id: c.id,
+                                name: c.name,
+                                modes: c.modes,
+                                defaultModeId: c.defaultModeId,
+                            };
+                        }
+                        // For full, remove variableIds array to reduce size
+                        const { variableIds, ...rest } = c;
+                        return rest;
+                    });
+                    logger.info({
+                        fileKey,
+                        originalCount: cachedData.variables?.length,
+                        filteredCount: paginationInfo.totalVariables,
+                        returnedCount: responseData.variables?.length,
+                        page: paginationInfo.currentPage,
+                        totalPages: paginationInfo.totalPages,
+                        verbosity: effectiveVerbosity,
+                    }, 'Applied filters, pagination, and verbosity filtering to cached data');
+                }
+                else {
+                    // format === 'full'
+                    // Check if we need to auto-summarize
+                    const estimatedTokens = estimateTokens(responseData);
+                    if (estimatedTokens > 25000) {
+                        logger.warn({ fileKey, estimatedTokens }, 'Full data exceeds MCP token limit (25K), auto-summarizing. Use format=summary or format=filtered to get specific data.');
+                        const summary = generateSummary(responseData);
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: JSON.stringify({
+                                        fileKey,
+                                        source: 'cache_auto_summarized',
+                                        warning: 'Full dataset exceeds MCP token limit (25,000 tokens)',
+                                        suggestion: 'Use format="summary" for overview or format="filtered" with collection/namePattern/mode filters to get specific variables',
+                                        estimatedTokens,
+                                        summary,
+                                    }, null, 2),
+                                },
+                            ],
+                        };
+                    }
+                }
+                // Return cached/processed data
+                // If returnAsLinks=true, return resource_link references instead of full data
+                if (returnAsLinks) {
+                    const summary = {
+                        fileKey,
+                        source: 'cache',
+                        totalVariables: responseData.variables?.length || 0,
+                        totalCollections: responseData.variableCollections?.length || 0,
+                        ...(paginationInfo && { pagination: paginationInfo }),
+                    };
+                    // Build resource_link content for each variable
+                    const content = [
+                        {
+                            type: "text",
+                            text: JSON.stringify(summary),
+                        },
+                    ];
+                    // Add resource_link for each variable (minimal overhead ~150 bytes each)
+                    responseData.variables?.forEach((v) => {
+                        content.push({
+                            type: "resource_link",
+                            uri: `figma://variable/${v.id}`,
+                            name: v.name || v.id,
+                            description: `${v.resolvedType || 'VARIABLE'} from ${fileKey}`,
+                        });
+                    });
+                    logger.info({
+                        fileKey,
+                        format: 'resource_links',
+                        variableCount: responseData.variables?.length || 0,
+                        linkCount: content.length - 1, // -1 for summary text
+                        estimatedSizeKB: (content.length * 150) / 1024,
+                    }, `Returning variables as resource_links`);
+                    return { content };
+                }
+                // Default: return full data
+                const responsePayload = {
+                    fileKey,
+                    source: 'cache',
+                    format: format || 'full',
+                    timestamp: cachedData.timestamp,
+                    data: responseData,
+                    ...(paginationInfo && { pagination: paginationInfo }),
+                };
+                // Remove pretty printing to reduce payload size by 30-40%
+                const responseText = JSON.stringify(responsePayload);
+                const responseSizeBytes = Buffer.byteLength(responseText, 'utf8');
+                const responseSizeMB = (responseSizeBytes / (1024 * 1024)).toFixed(2);
+                logger.info({
+                    fileKey,
+                    format: format || 'full',
+                    verbosity: verbosity || 'standard',
+                    variableCount: responseData.variables?.length || 0,
+                    collectionCount: responseData.variableCollections?.length || 0,
+                    responseSizeBytes,
+                    responseSizeMB: `${responseSizeMB} MB`,
+                    isUnder1MB: responseSizeBytes < 1024 * 1024,
+                }, `Response size check: ${responseSizeMB} MB`);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: responseText,
+                        },
+                    ],
+                };
+            }
+            // =====================================================================
+            // FETCH LOGIC: No cache or cache invalid/refresh requested
+            // =====================================================================
+            // BEST: Try Desktop connection first (like official Figma MCP does)
+            // Ensure browser manager is initialized
+            if (ensureInitialized && !parseFromConsole) {
+                logger.info("Calling ensureInitialized to initialize browser manager");
+                await ensureInitialized();
+            }
+            const browserManager = getBrowserManager?.();
+            logger.info({ hasBrowserManager: !!browserManager, parseFromConsole }, "Desktop connection check");
+            // Debug: Log why Desktop connection might be skipped
+            if (!browserManager) {
+                logger.error("Desktop connection skipped: browserManager is not available");
+            }
+            else if (parseFromConsole) {
+                logger.info("Desktop connection skipped: parseFromConsole is true");
+            }
+            if (browserManager && !parseFromConsole) {
+                try {
+                    logger.info({ fileKey }, "Attempting to get variables via Desktop connection");
+                    // Import and use the Desktop connector
+                    const { FigmaDesktopConnector } = await import('./figma-desktop-connector.js');
+                    const page = await browserManager.getPage();
+                    logger.info("Got page from browser manager");
+                    // Log to browser console for MCP capture
+                    await page.evaluate(() => {
+                        console.log('[FIGMA_TOOLS] 🚀 Got page from browser manager, creating Desktop connector...');
+                    });
+                    const connector = new FigmaDesktopConnector(page);
+                    await page.evaluate(() => {
+                        console.log('[FIGMA_TOOLS] ✅ Desktop connector created, initializing...');
+                    });
+                    await connector.initialize();
+                    logger.info("Desktop connector initialized, calling getVariablesFromPluginUI...");
+                    await page.evaluate(() => {
+                        console.log('[FIGMA_TOOLS] ✅ Desktop connector initialized, calling getVariablesFromPluginUI...');
+                    });
+                    const desktopResult = await connector.getVariablesFromPluginUI(fileKey);
+                    if (desktopResult.success && desktopResult.variables) {
+                        logger.info({
+                            variableCount: desktopResult.variables.length,
+                            collectionCount: desktopResult.variableCollections?.length
+                        }, "Successfully retrieved variables via Desktop connection!");
+                        // Prepare data for caching (using the raw data, not enriched)
+                        const dataForCache = {
+                            fileKey,
+                            source: "desktop_connection",
+                            timestamp: desktopResult.timestamp || Date.now(),
+                            variables: desktopResult.variables,
+                            variableCollections: desktopResult.variableCollections,
+                        };
+                        // Store in cache with LRU eviction
+                        if (variablesCache) {
+                            evictOldestCacheEntry(variablesCache);
+                            variablesCache.set(fileKey, {
+                                data: dataForCache,
+                                timestamp: Date.now(),
+                            });
+                            logger.info({ fileKey, cacheSize: variablesCache.size }, 'Stored variables in cache');
+                        }
+                        // Apply format logic
+                        let responseData = dataForCache;
+                        if (format === 'summary') {
+                            responseData = generateSummary(dataForCache);
+                            logger.info({ fileKey, estimatedTokens: estimateTokens(responseData) }, 'Generated summary from fetched data');
+                        }
+                        else if (format === 'filtered') {
+                            // Apply filters with verbosity-aware valuesByMode transformation
+                            responseData = applyFilters(dataForCache, {
+                                collection,
+                                namePattern,
+                                mode,
+                            }, verbosity || 'standard');
+                            logger.info({
+                                fileKey,
+                                originalCount: dataForCache.variables?.length,
+                                filteredCount: responseData.variables?.length,
+                            }, 'Applied filters to fetched data');
+                            // Apply pagination (CRITICAL - was missing!)
+                            let paginationInfo = null;
+                            const paginated = paginateVariables(responseData, page || 1, pageSize || 50);
+                            responseData = paginated.data;
+                            paginationInfo = paginated.pagination;
+                            // Apply verbosity filtering (CRITICAL - was missing!)
+                            const effectiveVerbosity = verbosity || "inventory";
+                            // Only include collections referenced by paginated variables
+                            const referencedCollectionIds = new Set(responseData.variables.map((v) => v.variableCollectionId));
+                            responseData.variableCollections = responseData.variableCollections.filter((c) => referencedCollectionIds.has(c.id));
+                            // Filter variables by verbosity
+                            responseData.variables = responseData.variables.map((v) => {
+                                if (effectiveVerbosity === "inventory") {
+                                    return {
+                                        id: v.id,
+                                        name: v.name,
+                                        collectionId: v.variableCollectionId,
+                                    };
+                                }
+                                if (effectiveVerbosity === "summary") {
+                                    return {
+                                        id: v.id,
+                                        name: v.name,
+                                        resolvedType: v.resolvedType,
+                                        valuesByMode: v.valuesByMode,
+                                        variableCollectionId: v.variableCollectionId,
+                                    };
+                                }
+                                return v; // standard/full
+                            });
+                            // Filter collections by verbosity
+                            responseData.variableCollections = responseData.variableCollections.map((c) => {
+                                if (effectiveVerbosity === "inventory") {
+                                    return {
+                                        id: c.id,
+                                        name: c.name,
+                                        modeNames: c.modes?.map((m) => m.name) || [],
+                                    };
+                                }
+                                if (effectiveVerbosity === "summary") {
+                                    return {
+                                        id: c.id,
+                                        name: c.name,
+                                        modes: c.modes,
+                                    };
+                                }
+                                return c; // standard/full
+                            });
+                        }
+                        else {
+                            // format === 'full'
+                            // Check if we need to auto-summarize
+                            const estimatedTokens = estimateTokens(responseData);
+                            if (estimatedTokens > 25000) {
+                                logger.warn({ fileKey, estimatedTokens }, 'Full data exceeds MCP token limit (25K), auto-summarizing. Use format=summary or format=filtered to get specific data.');
+                                const summary = generateSummary(responseData);
+                                return {
+                                    content: [
+                                        {
+                                            type: "text",
+                                            text: JSON.stringify({
+                                                fileKey,
+                                                source: 'desktop_connection_auto_summarized',
+                                                warning: 'Full dataset exceeds MCP token limit (25,000 tokens)',
+                                                suggestion: 'Use format="summary" for overview or format="filtered" with collection/namePattern/mode filters to get specific variables',
+                                                estimatedTokens,
+                                                summary,
+                                            }),
+                                        },
+                                    ],
+                                };
+                            }
+                        }
+                        // If returnAsLinks=true, return resource_link references
+                        if (returnAsLinks) {
+                            const summary = {
+                                fileKey,
+                                source: 'desktop_connection',
+                                totalVariables: responseData.variables?.length || 0,
+                                totalCollections: responseData.variableCollections?.length || 0,
+                            };
+                            const content = [
+                                {
+                                    type: "text",
+                                    text: JSON.stringify(summary),
+                                },
+                            ];
+                            // Add resource_link for each variable
+                            responseData.variables?.forEach((v) => {
+                                content.push({
+                                    type: "resource_link",
+                                    uri: `figma://variable/${v.id}`,
+                                    name: v.name || v.id,
+                                    description: `${v.resolvedType || 'VARIABLE'} from ${fileKey}`,
+                                });
+                            });
+                            logger.info({
+                                fileKey,
+                                format: 'resource_links',
+                                variableCount: responseData.variables?.length || 0,
+                                linkCount: content.length - 1,
+                            }, `Returning Desktop variables as resource_links`);
+                            return { content };
+                        }
+                        // Default: return full data (removed pretty printing)
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: JSON.stringify({
+                                        fileKey,
+                                        source: "desktop_connection",
+                                        format: format || 'full',
+                                        timestamp: dataForCache.timestamp,
+                                        data: responseData,
+                                        cached: true,
+                                    }),
+                                },
+                            ],
+                        };
+                    }
+                }
+                catch (desktopError) {
+                    const errorMessage = desktopError instanceof Error ? desktopError.message : String(desktopError);
+                    const errorStack = desktopError instanceof Error ? desktopError.stack : undefined;
+                    logger.error({
+                        error: desktopError,
+                        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 other methods
+                }
+            }
+            // FALLBACK: Parse from console logs if requested
+            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,
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            // Try REST API
+            logger.info({ fileKey, includePublished, verbosity, enrich }, "Fetching variables via REST API");
+            const api = await getFigmaAPI();
+            const { local, published } = await api.getAllVariables(fileKey);
+            let localFormatted = formatVariables(local);
+            let publishedFormatted = includePublished
+                ? formatVariables(published)
+                : null;
+            // DEBUG: Check if valuesByMode exists before filtering
+            if (localFormatted.variables[0]) {
+                logger.info({
+                    hasValuesByMode: !!localFormatted.variables[0].valuesByMode,
+                    variableKeys: Object.keys(localFormatted.variables[0]),
+                    collectionCount: localFormatted.collections?.length,
+                }, 'Variable structure before filtering');
+            }
+            // Apply collection/name/mode filtering if format is 'filtered'
+            if (format === 'filtered') {
+                // Create properly structured data for applyFilters
+                const dataToFilter = {
+                    variables: localFormatted.variables,
+                    variableCollections: localFormatted.collections,
+                };
+                // Apply filters with verbosity-aware valuesByMode transformation
+                const filtered = applyFilters(dataToFilter, {
+                    collection,
+                    namePattern,
+                    mode,
+                }, verbosity || 'standard');
+                localFormatted.variables = filtered.variables;
+                localFormatted.collections = filtered.variableCollections;
+                // DEBUG: Check if transformation was applied
+                if (localFormatted.variables[0]) {
+                    logger.info({
+                        hasValuesByMode: !!localFormatted.variables[0].valuesByMode,
+                        hasModeNames: !!localFormatted.variables[0].modeNames,
+                        variableKeys: Object.keys(localFormatted.variables[0]),
+                    }, 'Variable structure after applyFilters');
+                }
+                // Skip inline verbosity filtering - already handled by applyFilters
+            }
+            // Apply verbosity filtering for non-filtered formats
+            const filterVariable = (variable, level) => {
+                if (!variable)
+                    return variable;
+                if (level === "summary") {
+                    // Summary: Only id, name, value (~80% reduction)
+                    return {
+                        id: variable.id,
+                        name: variable.name,
+                        resolvedType: variable.resolvedType,
+                        valuesByMode: variable.valuesByMode,
+                        // Include modeNames and modeCount added by applyFilters
+                        ...(variable.modeNames && { modeNames: variable.modeNames }),
+                        ...(variable.modeCount && { modeCount: variable.modeCount }),
+                    };
+                }
+                if (level === "standard") {
+                    // Standard: Essential properties (~45% reduction)
+                    return {
+                        id: variable.id,
+                        name: variable.name,
+                        resolvedType: variable.resolvedType,
+                        valuesByMode: variable.valuesByMode,
+                        description: variable.description,
+                        variableCollectionId: variable.variableCollectionId,
+                        ...(variable.scopes && { scopes: variable.scopes }),
+                    };
+                }
+                // Full: Return everything
+                return variable;
+            };
+            const filterCollection = (collection, level) => {
+                if (!collection)
+                    return collection;
+                if (level === "summary") {
+                    return {
+                        id: collection.id,
+                        name: collection.name,
+                    };
+                }
+                if (level === "standard") {
+                    return {
+                        id: collection.id,
+                        name: collection.name,
+                        modes: collection.modes,
+                        defaultModeId: collection.defaultModeId,
+                    };
+                }
+                return collection;
+            };
+            // Apply inline verbosity filtering only for non-filtered formats
+            // (filtered format already handled by applyFilters above)
+            if (verbosity !== "full" && format !== 'filtered') {
+                const level = verbosity || "standard";
+                localFormatted.variables = localFormatted.variables.map((v) => filterVariable(v, level));
+                localFormatted.collections = localFormatted.collections.map((c) => filterCollection(c, level));
+                if (publishedFormatted) {
+                    publishedFormatted.variables = publishedFormatted.variables.map((v) => filterVariable(v, level));
+                    publishedFormatted.collections = publishedFormatted.collections.map((c) => filterCollection(c, level));
+                }
+            }
+            // Apply enrichment if requested
+            if (enrich) {
+                const enrichmentOptions = {
+                    enrich: true,
+                    include_usage: include_usage !== false,
+                    include_dependencies: include_dependencies !== false,
+                    include_exports: include_exports !== false,
+                    export_formats: export_formats || ["css", "sass", "tailwind", "typescript", "json"],
+                };
+                // Enrich local variables
+                const enrichedLocal = await enrichmentService.enrichVariables(localFormatted.variables, fileKey, enrichmentOptions);
+                localFormatted = { ...localFormatted, variables: enrichedLocal };
+                // Enrich published variables if included
+                if (publishedFormatted) {
+                    const enrichedPublished = await enrichmentService.enrichVariables(publishedFormatted.variables, fileKey, enrichmentOptions);
+                    publishedFormatted = { ...publishedFormatted, variables: enrichedPublished };
+                }
+            }
+            // Apply pagination for filtered format
+            let paginationInfo = null;
+            if (format === 'filtered') {
+                const paginated = paginateVariables({ variables: localFormatted.variables, variableCollections: localFormatted.collections }, page || 1, pageSize || 50);
+                localFormatted.variables = paginated.data.variables;
+                localFormatted.collections = paginated.data.variableCollections;
+                paginationInfo = paginated.pagination;
+                // For inventory/summary modes, strip variableIds from collections to reduce payload
+                if (verbosity === 'inventory' || verbosity === 'summary') {
+                    localFormatted.collections = localFormatted.collections.map((c) => ({
+                        id: c.id,
+                        name: c.name,
+                        key: c.key,
+                        modes: c.modes,
+                        // Omit variableIds array which can be huge
+                    }));
+                }
+            }
+            // If returnAsLinks=true, return resource_link references
+            if (returnAsLinks) {
+                const summary = {
+                    fileKey,
+                    source: 'rest_api',
+                    totalVariables: localFormatted.variables.length,
+                    totalCollections: localFormatted.collections.length,
+                    ...(paginationInfo && { pagination: paginationInfo }),
+                };
+                const content = [
+                    {
+                        type: "text",
+                        text: JSON.stringify(summary),
+                    },
+                ];
+                // Add resource_link for each variable
+                localFormatted.variables.forEach((v) => {
+                    content.push({
+                        type: "resource_link",
+                        uri: `figma://variable/${v.id}`,
+                        name: v.name || v.id,
+                        description: `${v.resolvedType || 'VARIABLE'} from ${fileKey}`,
+                    });
+                });
+                logger.info({
+                    fileKey,
+                    format: 'resource_links',
+                    variableCount: localFormatted.variables.length,
+                    linkCount: content.length - 1,
+                }, `Returning REST API variables as resource_links`);
+                return { content };
+            }
+            // Build initial response data
+            const responseData = {
+                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,
+                ...(paginationInfo && { pagination: paginationInfo }),
+            };
+            // Use adaptive response to prevent context exhaustion
+            return adaptiveResponse(responseData, {
+                toolName: "figma_get_variables",
+                compressionCallback: (adjustedLevel) => {
+                    // Re-apply filters with adjusted verbosity
+                    const level = adjustedLevel;
+                    const refiltered = applyFilters({
+                        variables: localFormatted.variables,
+                        variableCollections: localFormatted.collections,
+                    }, { collection, namePattern, mode }, level);
+                    return {
+                        ...responseData,
+                        local: {
+                            ...responseData.local,
+                            variables: refiltered.variables,
+                            collections: refiltered.variableCollections,
+                        },
+                        verbosity: level,
+                    };
+                },
+                suggestedActions: [
+                    "Use verbosity='inventory' or 'summary' for large variable sets",
+                    "Apply filters: collection, namePattern, or mode parameters",
+                    "Use pagination with pageSize parameter (default 50, max 100)",
+                    "Use returnAsLinks=true to get resource_link references instead of full data",
+                ],
+            });
+        }
+        catch (error) {
+            logger.error({ error }, "Failed to get variables");
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            // FIXED: Jump directly to Styles API (fast) instead of full file data (slow)
+            if (errorMessage.includes("403")) {
+                try {
+                    logger.info({ fileKey }, "Variables API requires Enterprise, falling back to Styles API");
+                    const api = await getFigmaAPI();
+                    // Use the Styles API directly - much faster than getFile!
+                    const stylesData = await api.getStyles(fileKey);
+                    // Format the styles data similar to variables
+                    const formattedStyles = {
+                        summary: {
+                            total_styles: stylesData.meta?.styles?.length || 0,
+                            message: "Variables API requires Enterprise. Here are your design styles instead.",
+                            note: "These are Figma Styles (not Variables). Styles are the traditional way to store design tokens in Figma."
+                        },
+                        styles: stylesData.meta?.styles || []
+                    };
+                    logger.info({ styleCount: formattedStyles.summary.total_styles }, "Successfully retrieved styles as fallback!");
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    fileKey,
+                                    source: "styles_api",
+                                    message: "Variables API requires an Enterprise plan. Retrieved your design system styles instead.",
+                                    data: formattedStyles,
+                                    fallback_method: true,
+                                }, null, 2),
+                            },
+                        ],
+                    };
+                }
+                catch (styleError) {
+                    logger.warn({ error: styleError }, "Style extraction failed");
+                    // Return a simple error message without the console snippet
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    error: "Unable to extract variables or styles from this file",
+                                    message: "The Variables API requires an Enterprise plan, and the automatic style extraction encountered an error.",
+                                    possibleReasons: [
+                                        "The file may be private or require additional permissions",
+                                        "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.",
+                                    technical: styleError instanceof Error ? styleError.message : String(styleError)
+                                }, null, 2),
+                            },
+                        ],
+                    };
+                }
+            }
+            // Standard error response
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            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",
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Tool 10: Get Component Data
+    server.tool("figma_get_component", "Get component metadata including reliable description fields. IMPORTANT: For local/unpublished components, ensure the Figma Desktop Bridge plugin is running (Right-click in Figma → Plugins → Development → Figma Desktop Bridge) to get complete description data. Without the plugin, descriptions may be missing due to REST API limitations.", {
+        fileUrl: z
+            .string()
+            .url()
+            .optional()
+            .describe("Figma file URL (e.g., https://figma.com/design/abc123). REQUIRED unless figma_navigate was already called. If not provided, ask the user to share their Figma file URL (they can copy it from Figma Desktop via right-click → 'Copy link')."),
+        nodeId: z
+            .string()
+            .describe("Component node ID (e.g., '123:456')"),
+        enrich: z
+            .boolean()
+            .optional()
+            .describe("Set to true when user asks for: design token coverage, hardcoded value analysis, or component quality metrics. Adds token coverage analysis and hardcoded value detection. Default: false"),
+    }, async ({ fileUrl, nodeId, enrich }) => {
+        try {
+            const api = await getFigmaAPI();
+            const url = fileUrl || getCurrentUrl();
+            if (!url) {
+                throw new Error("No Figma file URL provided. Either pass fileUrl parameter or call figma_navigate first.");
+            }
+            const fileKey = extractFileKey(url);
+            if (!fileKey) {
+                throw new Error(`Invalid Figma URL: ${url}`);
+            }
+            logger.info({ fileKey, nodeId, enrich }, "Fetching component data");
+            // PRIORITY 1: Try Desktop Bridge plugin UI first (has reliable description field!)
+            if (getBrowserManager && ensureInitialized) {
+                try {
+                    logger.info({ nodeId }, "Attempting to get component via Desktop Bridge plugin UI");
+                    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();
+                    const connector = new FigmaDesktopConnector(page);
+                    await connector.initialize();
+                    const desktopResult = await connector.getComponentFromPluginUI(nodeId);
+                    if (desktopResult.success && desktopResult.component) {
+                        logger.info({
+                            componentName: desktopResult.component.name,
+                            hasDescription: !!desktopResult.component.description,
+                            hasDescriptionMarkdown: !!desktopResult.component.descriptionMarkdown
+                        }, "Successfully retrieved component via Desktop Bridge plugin UI!");
+                        let formatted = desktopResult.component;
+                        // Apply enrichment if requested
+                        if (enrich) {
+                            const enrichmentOptions = {
+                                enrich: true,
+                                include_usage: true,
+                            };
+                            formatted = await enrichmentService.enrichComponent(formatted, fileKey, enrichmentOptions);
+                        }
+                        return {
+                            content: [
+                                {
+                                    type: "text",
+                                    text: JSON.stringify({
+                                        fileKey,
+                                        nodeId,
+                                        component: formatted,
+                                        source: "desktop_bridge_plugin",
+                                        enriched: enrich || false,
+                                        note: "Retrieved via Desktop Bridge plugin - description fields are reliable and current"
+                                    }, null, 2),
+                                },
+                            ],
+                        };
+                    }
+                }
+                catch (desktopError) {
+                    logger.warn({ error: desktopError, nodeId }, "Desktop Bridge plugin failed, falling back to REST API");
+                }
+            }
+            // FALLBACK: Use REST API (may have missing/outdated description)
+            logger.info({ nodeId }, "Using REST API fallback");
+            const componentData = await api.getComponentData(fileKey, nodeId);
+            if (!componentData) {
+                throw new Error(`Component not found: ${nodeId}`);
+            }
+            let formatted = formatComponentData(componentData.document);
+            // Apply enrichment if requested
+            if (enrich) {
+                const enrichmentOptions = {
+                    enrich: true,
+                    include_usage: true,
+                };
+                formatted = await enrichmentService.enrichComponent(formatted, fileKey, enrichmentOptions);
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            fileKey,
+                            nodeId,
+                            component: formatted,
+                            source: "rest_api",
+                            enriched: enrich || false,
+                            warning: "Retrieved via REST API - description field may be missing due to known Figma API bug",
+                            action_required: formatted.description || formatted.descriptionMarkdown ? null : "To get reliable component descriptions, run the Desktop Bridge plugin in Figma Desktop: Right-click → Plugins → Development → Figma Desktop Bridge, then try again."
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error({ error }, "Failed to get component");
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: errorMessage,
+                            message: "Failed to retrieve component data",
+                            hint: "Make sure the node ID is correct and the file is accessible",
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Tool 11: Get Styles
+    server.tool("figma_get_styles", {
+        fileUrl: z
+            .string()
+            .url()
+            .optional()
+            .describe("Figma file URL (e.g., https://figma.com/design/abc123). REQUIRED unless figma_navigate was already called. If not provided, ask the user to share their Figma file URL (they can copy it from Figma Desktop via right-click → 'Copy link')."),
+        verbosity: z
+            .enum(["summary", "standard", "full"])
+            .optional()
+            .default("standard")
+            .describe("Controls payload size: 'summary' (names/types only, ~85% smaller), 'standard' (essential properties, ~40% smaller), 'full' (everything). Default: standard"),
+        enrich: z
+            .boolean()
+            .optional()
+            .describe("Set to true when user asks for: CSS/Sass/Tailwind code, export formats, usage information, code examples, or design system exports. Adds resolved values, usage analysis, and export format examples. Default: false for backward compatibility"),
+        include_usage: z
+            .boolean()
+            .optional()
+            .describe("Include component usage information (requires enrich=true)"),
+        include_exports: z
+            .boolean()
+            .optional()
+            .describe("Include export format examples (requires enrich=true)"),
+        export_formats: z
+            .array(z.enum(["css", "sass", "tailwind", "typescript", "json"]))
+            .optional()
+            .describe("Which code formats to generate examples for. Use when user mentions specific formats like 'CSS', 'Tailwind', 'SCSS', 'TypeScript', etc. Automatically enables enrichment. Default: all formats"),
+    }, async ({ fileUrl, verbosity, enrich, include_usage, include_exports, export_formats }) => {
+        try {
+            const api = await getFigmaAPI();
+            const url = fileUrl || getCurrentUrl();
+            if (!url) {
+                throw new Error("No Figma file URL provided. Either pass fileUrl parameter or call figma_navigate first.");
+            }
+            const fileKey = extractFileKey(url);
+            if (!fileKey) {
+                throw new Error(`Invalid Figma URL: ${url}`);
+            }
+            logger.info({ fileKey, verbosity, enrich }, "Fetching styles");
+            const stylesData = await api.getStyles(fileKey);
+            let styles = stylesData.meta?.styles || [];
+            // Apply verbosity filtering
+            const filterStyle = (style, level) => {
+                if (!style)
+                    return style;
+                if (level === "summary") {
+                    // Summary: Only key, name, type (~85% reduction)
+                    return {
+                        key: style.key,
+                        name: style.name,
+                        style_type: style.style_type,
+                    };
+                }
+                if (level === "standard") {
+                    // Standard: Essential properties (~40% reduction)
+                    return {
+                        key: style.key,
+                        name: style.name,
+                        description: style.description,
+                        style_type: style.style_type,
+                        ...(style.remote && { remote: style.remote }),
+                    };
+                }
+                // Full: Return everything
+                return style;
+            };
+            if (verbosity !== "full") {
+                styles = styles.map((style) => filterStyle(style, verbosity || "standard"));
+            }
+            // Apply enrichment if requested
+            if (enrich) {
+                const enrichmentOptions = {
+                    enrich: true,
+                    include_usage: include_usage !== false,
+                    include_exports: include_exports !== false,
+                    export_formats: export_formats || [
+                        "css",
+                        "sass",
+                        "tailwind",
+                        "typescript",
+                        "json",
+                    ],
+                };
+                styles = await enrichmentService.enrichStyles(styles, fileKey, enrichmentOptions);
+            }
+            const finalResponse = {
+                fileKey,
+                styles,
+                totalStyles: styles.length,
+                verbosity: verbosity || "standard",
+                enriched: enrich || false,
+            };
+            // Use adaptive response to prevent context exhaustion
+            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;
+                    return {
+                        ...finalResponse,
+                        styles: refilteredStyles,
+                        verbosity: level,
+                    };
+                },
+                suggestedActions: [
+                    "Use verbosity='summary' for style names and types only",
+                    "Use verbosity='standard' for essential style properties",
+                    "Filter to specific style types if needed",
+                ],
+            });
+        }
+        catch (error) {
+            logger.error({ error }, "Failed to get styles");
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: errorMessage,
+                            message: "Failed to retrieve styles",
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Tool 12: Get Component Image (Visual Reference)
+    server.tool("figma_get_component_image", {
+        fileUrl: z
+            .string()
+            .url()
+            .optional()
+            .describe("Figma file URL (e.g., https://figma.com/design/abc123). REQUIRED unless figma_navigate was already called. If not provided, ask the user to share their Figma file URL (they can copy it from Figma Desktop via right-click → 'Copy link')."),
+        nodeId: z
+            .string()
+            .describe("Component node ID to render as image (e.g., '695:313')"),
+        scale: z
+            .number()
+            .min(0.01)
+            .max(4)
+            .optional()
+            .default(2)
+            .describe("Image scale factor (0.01-4, default: 2 for high quality)"),
+        format: z
+            .enum(["png", "jpg", "svg", "pdf"])
+            .optional()
+            .default("png")
+            .describe("Image format (default: png)"),
+    }, async ({ fileUrl, nodeId, scale, format }) => {
+        try {
+            const api = await getFigmaAPI();
+            const url = fileUrl || getCurrentUrl();
+            if (!url) {
+                throw new Error("No Figma file URL provided. Either pass fileUrl parameter or call figma_navigate first.");
+            }
+            const fileKey = extractFileKey(url);
+            if (!fileKey) {
+                throw new Error(`Invalid Figma URL: ${url}`);
+            }
+            logger.info({ fileKey, nodeId, scale, format }, "Rendering component image");
+            // Call the new getImages method
+            const result = await api.getImages(fileKey, nodeId, {
+                scale,
+                format,
+                contents_only: true,
+            });
+            const imageUrl = result.images[nodeId];
+            if (!imageUrl) {
+                throw new Error(`Failed to render image for node ${nodeId}. The node may not exist or may not be renderable.`);
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            fileKey,
+                            nodeId,
+                            imageUrl,
+                            scale,
+                            format,
+                            expiresIn: "30 days",
+                            note: "Use this image as visual reference for component development. Image URLs expire after 30 days.",
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error({ error }, "Failed to render component image");
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: errorMessage,
+                            message: "Failed to render component image",
+                            hint: "Make sure the node ID is correct and the component is renderable",
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Tool 13: Get Component for Development (UI Implementation)
+    server.tool("figma_get_component_for_development", {
+        fileUrl: z
+            .string()
+            .url()
+            .optional()
+            .describe("Figma file URL (e.g., https://figma.com/design/abc123). REQUIRED unless figma_navigate was already called."),
+        nodeId: z
+            .string()
+            .describe("Component node ID to get data for (e.g., '695:313')"),
+        includeImage: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("Include rendered image for visual reference (default: true)"),
+    }, async ({ fileUrl, nodeId, includeImage }) => {
+        try {
+            const api = await getFigmaAPI();
+            const url = fileUrl || getCurrentUrl();
+            if (!url) {
+                throw new Error("No Figma file URL provided. Either pass fileUrl parameter or call figma_navigate first.");
+            }
+            const fileKey = extractFileKey(url);
+            if (!fileKey) {
+                throw new Error(`Invalid Figma URL: ${url}`);
+            }
+            logger.info({ fileKey, nodeId, includeImage }, "Fetching component for development");
+            // Get node data with depth for children
+            const nodeData = await api.getNodes(fileKey, [nodeId], { depth: 2 });
+            const node = nodeData.nodes?.[nodeId]?.document;
+            if (!node) {
+                throw new Error(`Component not found: ${nodeId}`);
+            }
+            // Filter to visual/layout properties only
+            const filterForDevelopment = (n) => {
+                if (!n)
+                    return n;
+                const result = {
+                    id: n.id,
+                    name: n.name,
+                    type: n.type,
+                    description: n.description,
+                    descriptionMarkdown: n.descriptionMarkdown,
+                };
+                // Layout & positioning
+                if (n.absoluteBoundingBox)
+                    result.absoluteBoundingBox = n.absoluteBoundingBox;
+                if (n.relativeTransform)
+                    result.relativeTransform = n.relativeTransform;
+                if (n.size)
+                    result.size = n.size;
+                if (n.constraints)
+                    result.constraints = n.constraints;
+                if (n.layoutAlign)
+                    result.layoutAlign = n.layoutAlign;
+                if (n.layoutGrow)
+                    result.layoutGrow = n.layoutGrow;
+                if (n.layoutPositioning)
+                    result.layoutPositioning = n.layoutPositioning;
+                // Auto-layout
+                if (n.layoutMode)
+                    result.layoutMode = n.layoutMode;
+                if (n.primaryAxisSizingMode)
+                    result.primaryAxisSizingMode = n.primaryAxisSizingMode;
+                if (n.counterAxisSizingMode)
+                    result.counterAxisSizingMode = n.counterAxisSizingMode;
+                if (n.primaryAxisAlignItems)
+                    result.primaryAxisAlignItems = n.primaryAxisAlignItems;
+                if (n.counterAxisAlignItems)
+                    result.counterAxisAlignItems = n.counterAxisAlignItems;
+                if (n.paddingLeft !== undefined)
+                    result.paddingLeft = n.paddingLeft;
+                if (n.paddingRight !== undefined)
+                    result.paddingRight = n.paddingRight;
+                if (n.paddingTop !== undefined)
+                    result.paddingTop = n.paddingTop;
+                if (n.paddingBottom !== undefined)
+                    result.paddingBottom = n.paddingBottom;
+                if (n.itemSpacing !== undefined)
+                    result.itemSpacing = n.itemSpacing;
+                if (n.itemReverseZIndex)
+                    result.itemReverseZIndex = n.itemReverseZIndex;
+                if (n.strokesIncludedInLayout)
+                    result.strokesIncludedInLayout = n.strokesIncludedInLayout;
+                // Visual properties
+                if (n.fills)
+                    result.fills = n.fills;
+                if (n.strokes)
+                    result.strokes = n.strokes;
+                if (n.strokeWeight !== undefined)
+                    result.strokeWeight = n.strokeWeight;
+                if (n.strokeAlign)
+                    result.strokeAlign = n.strokeAlign;
+                if (n.strokeCap)
+                    result.strokeCap = n.strokeCap;
+                if (n.strokeJoin)
+                    result.strokeJoin = n.strokeJoin;
+                if (n.dashPattern)
+                    result.dashPattern = n.dashPattern;
+                if (n.cornerRadius !== undefined)
+                    result.cornerRadius = n.cornerRadius;
+                if (n.rectangleCornerRadii)
+                    result.rectangleCornerRadii = n.rectangleCornerRadii;
+                if (n.effects)
+                    result.effects = n.effects;
+                if (n.opacity !== undefined)
+                    result.opacity = n.opacity;
+                if (n.blendMode)
+                    result.blendMode = n.blendMode;
+                if (n.isMask)
+                    result.isMask = n.isMask;
+                if (n.clipsContent)
+                    result.clipsContent = n.clipsContent;
+                // Typography
+                if (n.characters)
+                    result.characters = n.characters;
+                if (n.style)
+                    result.style = n.style;
+                if (n.characterStyleOverrides)
+                    result.characterStyleOverrides = n.characterStyleOverrides;
+                if (n.styleOverrideTable)
+                    result.styleOverrideTable = n.styleOverrideTable;
+                // Component properties & variants
+                if (n.componentProperties)
+                    result.componentProperties = n.componentProperties;
+                if (n.componentPropertyDefinitions)
+                    result.componentPropertyDefinitions = n.componentPropertyDefinitions;
+                if (n.variantProperties)
+                    result.variantProperties = n.variantProperties;
+                if (n.componentId)
+                    result.componentId = n.componentId;
+                // State
+                if (n.visible !== undefined)
+                    result.visible = n.visible;
+                if (n.locked)
+                    result.locked = n.locked;
+                // Recursively process children
+                if (n.children) {
+                    result.children = n.children.map((child) => filterForDevelopment(child));
+                }
+                return result;
+            };
+            const componentData = filterForDevelopment(node);
+            // Get image if requested
+            let imageUrl = null;
+            if (includeImage) {
+                try {
+                    const imageResult = await api.getImages(fileKey, nodeId, {
+                        scale: 2,
+                        format: "png",
+                        contents_only: true,
+                    });
+                    imageUrl = imageResult.images[nodeId];
+                }
+                catch (error) {
+                    logger.warn({ error }, "Failed to render component image, continuing without it");
+                }
+            }
+            // Build response with component data and image URL
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            fileKey,
+                            nodeId,
+                            imageUrl,
+                            component: componentData,
+                            metadata: {
+                                purpose: "component_development",
+                                note: imageUrl
+                                    ? "Image URL provided above (valid for 30 days). Full component data optimized for UI implementation."
+                                    : "Full component data optimized for UI implementation.",
+                            },
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error({ error }, "Failed to get component for development");
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: errorMessage,
+                            message: "Failed to retrieve component development data",
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Tool 14: Get File for Plugin Development
+    server.tool("figma_get_file_for_plugin", {
+        fileUrl: z
+            .string()
+            .url()
+            .optional()
+            .describe("Figma file URL (e.g., https://figma.com/design/abc123). REQUIRED unless figma_navigate was already called."),
+        depth: z
+            .number()
+            .min(0)
+            .max(5)
+            .optional()
+            .default(2)
+            .describe("How many levels of children to include (default: 2, max: 5). Higher depths are safe here due to filtering."),
+        nodeIds: z
+            .array(z.string())
+            .optional()
+            .describe("Specific node IDs to retrieve (optional)"),
+    }, async ({ fileUrl, depth, nodeIds }) => {
+        try {
+            const api = await getFigmaAPI();
+            const url = fileUrl || getCurrentUrl();
+            if (!url) {
+                throw new Error("No Figma file URL provided. Either pass fileUrl parameter or call figma_navigate first.");
+            }
+            const fileKey = extractFileKey(url);
+            if (!fileKey) {
+                throw new Error(`Invalid Figma URL: ${url}`);
+            }
+            logger.info({ fileKey, depth, nodeIds }, "Fetching file data for plugin development");
+            const fileData = await api.getFile(fileKey, {
+                depth,
+                ids: nodeIds,
+            });
+            // Filter to plugin-relevant properties only
+            const filterForPlugin = (node) => {
+                if (!node)
+                    return node;
+                const result = {
+                    id: node.id,
+                    name: node.name,
+                    type: node.type,
+                    description: node.description,
+                    descriptionMarkdown: node.descriptionMarkdown,
+                };
+                // Navigation & structure
+                if (node.visible !== undefined)
+                    result.visible = node.visible;
+                if (node.locked)
+                    result.locked = node.locked;
+                if (node.removed)
+                    result.removed = node.removed;
+                // Lightweight bounds (just position/size)
+                if (node.absoluteBoundingBox) {
+                    result.bounds = {
+                        x: node.absoluteBoundingBox.x,
+                        y: node.absoluteBoundingBox.y,
+                        width: node.absoluteBoundingBox.width,
+                        height: node.absoluteBoundingBox.height,
+                    };
+                }
+                // Plugin data (CRITICAL for plugins)
+                if (node.pluginData)
+                    result.pluginData = node.pluginData;
+                if (node.sharedPluginData)
+                    result.sharedPluginData = node.sharedPluginData;
+                // Component relationships (important for plugins)
+                if (node.componentId)
+                    result.componentId = node.componentId;
+                if (node.mainComponent)
+                    result.mainComponent = node.mainComponent;
+                if (node.componentPropertyReferences)
+                    result.componentPropertyReferences = node.componentPropertyReferences;
+                if (node.instanceOf)
+                    result.instanceOf = node.instanceOf;
+                if (node.exposedInstances)
+                    result.exposedInstances = node.exposedInstances;
+                // Component properties (for manipulation)
+                if (node.componentProperties)
+                    result.componentProperties = node.componentProperties;
+                // Characters for text nodes (plugins often need this)
+                if (node.characters !== undefined)
+                    result.characters = node.characters;
+                // Recursively process children
+                if (node.children) {
+                    result.children = node.children.map((child) => filterForPlugin(child));
+                }
+                return result;
+            };
+            const filteredDocument = filterForPlugin(fileData.document);
+            const finalResponse = {
+                fileKey,
+                name: fileData.name,
+                lastModified: fileData.lastModified,
+                version: fileData.version,
+                document: filteredDocument,
+                components: fileData.components
+                    ? Object.keys(fileData.components).length
+                    : 0,
+                styles: fileData.styles
+                    ? Object.keys(fileData.styles).length
+                    : 0,
+                ...(nodeIds && {
+                    requestedNodes: nodeIds,
+                    nodes: fileData.nodes,
+                }),
+                metadata: {
+                    purpose: "plugin_development",
+                    note: "Optimized for plugin development. Contains IDs, structure, plugin data, and component relationships.",
+                },
+            };
+            // Use adaptive response to prevent context exhaustion
+            return adaptiveResponse(finalResponse, {
+                toolName: "figma_get_file_for_plugin",
+                compressionCallback: (adjustedLevel) => {
+                    // For plugin format, we can't reduce much without breaking functionality
+                    // But we can strip some less critical metadata
+                    const compressNode = (node) => {
+                        const result = {
+                            id: node.id,
+                            name: node.name,
+                            type: node.type,
+                        };
+                        // Keep only essential properties based on compression level
+                        if (adjustedLevel !== "inventory") {
+                            if (node.visible !== undefined)
+                                result.visible = node.visible;
+                            if (node.locked !== undefined)
+                                result.locked = node.locked;
+                            if (node.absoluteBoundingBox)
+                                result.absoluteBoundingBox = node.absoluteBoundingBox;
+                            if (node.pluginData)
+                                result.pluginData = node.pluginData;
+                            if (node.sharedPluginData)
+                                result.sharedPluginData = node.sharedPluginData;
+                            if (node.componentId)
+                                result.componentId = node.componentId;
+                        }
+                        if (node.children) {
+                            result.children = node.children.map(compressNode);
+                        }
+                        return result;
+                    };
+                    return {
+                        ...finalResponse,
+                        document: compressNode(filteredDocument),
+                        metadata: {
+                            ...finalResponse.metadata,
+                            compressionApplied: adjustedLevel,
+                        },
+                    };
+                },
+                suggestedActions: [
+                    "Reduce depth parameter (recommend 1-2)",
+                    "Request specific nodeIds to narrow the scope",
+                    "Filter to specific component types if possible",
+                ],
+            });
+        }
+        catch (error) {
+            logger.error({ error }, "Failed to get file for plugin");
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: errorMessage,
+                            message: "Failed to retrieve file data for plugin development",
+                        }, null, 2),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=figma-tools.js.map