@atezer/figma-mcp-bridge 1.7.29 → 1.9.0

package/dist/local-plugin-only.js

@@ -17,11 +17,22 @@ import { createChildLogger } from "./core/logger.js";
 import { PluginBridgeServer } from "./core/plugin-bridge-server.js";
 import { PluginBridgeConnector } from "./core/plugin-bridge-connector.js";
 import { parseFigmaUrl } from "./core/figma-url.js";
-import { truncateRestResponse } from "./core/response-guard.js";
+import { truncateRestResponse, truncatePluginResponse } from "./core/response-guard.js";
+import { analyzeCodeForWarnings } from "./core/code-warnings.js";
+import { resolveDevice, DEVICE_PRESETS } from "./core/device-presets.js";
 import { closeAuditLog } from "./core/audit-log.js";
 import { FMCP_VERSION } from "./core/version.js";
 import { ResponseCache } from "./core/response-cache.js";
 const logger = createChildLogger({ component: "plugin-only-mcp" });
+/**
+ * Legacy default flag — when set, restores pre-v1.8.0 default values for
+ * read-only tools (depth=2, verbosity="standard", scale=2, format="PNG").
+ * Allows downstream consumers to opt back into the heavier defaults during
+ * the v1.8.0 → v1.9.0 transition. Will be removed in v1.9.0.
+ *
+ * Set: FMCP_LEGACY_DEFAULTS=1
+ */
+const LEGACY_DEFAULTS = process.env.FMCP_LEGACY_DEFAULTS === "1";
 /** Resolve fileKey from figmaUrl (parse) or explicit fileKey. Returns undefined if neither yields a key. */
 function resolveFileKey(figmaUrl, explicitFileKey) {
     if (explicitFileKey && explicitFileKey.trim())
@@ -98,6 +109,8 @@ function getErrorHint(category) {
         default: return "Hata mesajini kontrol et.";
     }
 }
+// analyzeCodeForWarnings + CodeWarning type moved to ./core/code-warnings.ts (v1.8.1)
+// Imported at the top of this file — this comment marks where the helper used to live.
 /** Wrap a tool handler with try-catch to prevent unhandled rejections. */
 function safeToolHandler(handler) {
     return async (params) => {
@@ -136,6 +149,49 @@ export async function main() {
     const cache = new ResponseCache();
     /** Invalidate cache after any mutating operation. */
     function invalidateCache() { cache.invalidate(); }
+    /**
+     * Build a stable cache key from tool name + params. Sort keys for determinism.
+     * fileKey is included to avoid cross-file leakage in multi-file sessions.
+     */
+    function makeCacheKey(toolName, params) {
+        const sortedEntries = Object.entries(params)
+            .filter(([_, v]) => v !== undefined)
+            .sort(([a], [b]) => a.localeCompare(b));
+        return `${toolName}::${JSON.stringify(sortedEntries)}`;
+    }
+    /**
+     * Shared envelope wrapper for plugin tool results. Applies truncatePluginResponse
+     * unless skipGuard is true (for cache hits whose data was already guarded).
+     * When debug=true, the _responseGuard marker is preserved; otherwise stripped.
+     */
+    function toolResult(data, toolName, opts) {
+        let payload;
+        if (data === undefined || data === null) {
+            payload = { success: false, error: "No data from plugin" };
+        }
+        else if (opts?.skipGuard) {
+            payload = data;
+        }
+        else {
+            const result = truncatePluginResponse(data, toolName);
+            payload = result.data;
+            // Strip _responseGuard marker unless debug=true
+            if (!opts?.debug && payload && typeof payload === "object" && payload._responseGuard) {
+                const stripped = { ...payload };
+                delete stripped._responseGuard;
+                payload = stripped;
+            }
+        }
+        const text = typeof payload === "string" ? payload : JSON.stringify(payload);
+        return { content: [{ type: "text", text }] };
+    }
+    /** Helper for error responses with consistent shape. */
+    function errorResult(msg) {
+        return {
+            content: [{ type: "text", text: JSON.stringify({ success: false, error: msg }) }],
+            isError: true,
+        };
+    }
     const server = new McpServer({
         name: "F-MCP ATezer Bridge (Plugin-only)",
         version: FMCP_VERSION,
@@ -162,8 +218,9 @@ export async function main() {
         };
     });
     // ---- figma_get_file_data_plugin (no REST, no token) ----
+    // v1.8.0: Defaults already conservative (depth=1, verbosity="summary"). Cached + truncated.
     server.registerTool("figma_get_file_data", {
-        description: "Get file structure and document tree from the open Figma file. No REST API or token. Use fileKey or figmaUrl to target a specific file when multiple plugins are connected (Figma Desktop, FigJam browser, Figma browser). Pass a Figma/FigJam URL in figmaUrl to route by link.",
+        description: "Get file structure and document tree from the open Figma file. No REST API or token. Use fileKey or figmaUrl to target a specific file when multiple plugins are connected. Defaults to depth=1, verbosity='summary'. Cached 60s per session.",
         inputSchema: {
             figmaUrl: z.string().optional().describe("Figma or FigJam file URL; fileKey is extracted from the link for routing."),
             fileKey: z.string().optional().describe("Target a specific connected file. Use figma_list_connected_files to see available files."),
@@ -174,16 +231,14 @@ export async function main() {
             includeTypography: z.boolean().optional(),
             includeCodeReady: z.boolean().optional(),
             outputHint: z.enum(["react", "tailwind"]).optional(),
+            debug: z.boolean().optional().describe("Bypass cache and include _responseGuard fields."),
         },
         annotations: { readOnlyHint: true },
-    }, async ({ figmaUrl, fileKey, depth, verbosity, includeLayout, includeVisual, includeTypography, includeCodeReady, outputHint }) => {
+    }, async ({ figmaUrl, fileKey, depth, verbosity, includeLayout, includeVisual, includeTypography, includeCodeReady, outputHint, debug }) => {
         try {
             const resolvedKey = resolveFileKey(figmaUrl, fileKey);
             if (figmaUrl && !resolvedKey) {
-                return {
-                    content: [{ type: "text", text: JSON.stringify({ success: false, error: "Invalid Figma/FigJam URL: could not extract file key." }) }],
-                    isError: true,
-                };
+                return errorResult("Invalid Figma/FigJam URL: could not extract file key.");
             }
             const conn = getConnector(bridge, resolvedKey);
             const opts = includeLayout !== undefined ||
@@ -193,13 +248,12 @@ export async function main() {
                 outputHint !== undefined
                 ? { includeLayout, includeVisual, includeTypography, includeCodeReady, outputHint }
                 : undefined;
-            const data = await conn.getDocumentStructure(depth, verbosity, opts);
-            const text = data === undefined || data === null
-                ? JSON.stringify({ success: false, error: "No data from plugin" })
-                : typeof data === "string"
-                    ? data
-                    : JSON.stringify(data);
-            return { content: [{ type: "text", text }] };
+            const cacheK = makeCacheKey("figma_get_file_data", { resolvedKey, depth, verbosity, opts });
+            const cached = debug ? null : cache.get(cacheK, 60_000);
+            const data = cached ?? await conn.getDocumentStructure(depth, verbosity, opts);
+            if (!cached)
+                cache.set(cacheK, data);
+            return toolResult(data, "figma_get_file_data", { skipGuard: !!cached, debug });
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -210,23 +264,26 @@ export async function main() {
         }
     });
     // ---- figma_get_design_context (get_design_context tarzı, token tasarruflu, Figma token yok) ----
+    // v1.8.0: Context-safe defaults — depth=1, verbosity="summary"
+    // Override with FMCP_LEGACY_DEFAULTS=1 env var or pass explicit params.
     server.registerTool("figma_get_design_context", {
-        description: "Design context for a node or whole file: structure + text, layout/visual/typography. Use fileKey or figmaUrl to target a file when multiple plugins are connected. Pass a Figma/FigJam URL in figmaUrl; fileKey and node-id (if present in the link) are extracted automatically.",
+        description: "Design context for a node or whole file: structure + text, layout/visual/typography. Defaults to depth=1, verbosity='summary' for context safety. Pass depth/verbosity explicitly for deeper data. Cached 60s per session.",
         inputSchema: {
             figmaUrl: z.string().optional().describe("Figma or FigJam file URL; fileKey and optional node-id are extracted for routing."),
             fileKey: z.string().optional().describe("Target a specific connected file."),
             nodeId: z.string().optional(),
-            depth: z.number().min(0).max(3).optional().default(2),
-            verbosity: z.enum(["summary", "standard", "full"]).optional().default("standard"),
-            excludeScreenshot: z.boolean().optional(),
+            depth: z.number().min(0).max(3).optional().default(LEGACY_DEFAULTS ? 2 : 1),
+            verbosity: z.enum(["summary", "standard", "full"]).optional().default(LEGACY_DEFAULTS ? "standard" : "summary"),
+            excludeScreenshot: z.boolean().optional().describe("Reserved for future use; plugin currently does not embed screenshots in design_context."),
             includeLayout: z.boolean().optional(),
             includeVisual: z.boolean().optional(),
             includeTypography: z.boolean().optional(),
             includeCodeReady: z.boolean().optional(),
             outputHint: z.enum(["react", "tailwind"]).optional(),
+            debug: z.boolean().optional().describe("Bypass cache and include _responseGuard/_metrics fields."),
         },
         annotations: { readOnlyHint: true },
-    }, async ({ figmaUrl, fileKey, nodeId, depth, verbosity, excludeScreenshot, includeLayout, includeVisual, includeTypography, includeCodeReady, outputHint }) => {
+    }, async ({ figmaUrl, fileKey, nodeId, depth, verbosity, excludeScreenshot, includeLayout, includeVisual, includeTypography, includeCodeReady, outputHint, debug }) => {
         try {
             const { fileKey: resolvedKey, nodeId: resolvedNodeId } = resolveDesignContextParams({ figmaUrl, fileKey, nodeId });
             if (figmaUrl && !resolvedKey) {
@@ -245,15 +302,15 @@ export async function main() {
                 ? { excludeScreenshot, includeLayout, includeVisual, includeTypography, includeCodeReady, outputHint }
                 : undefined;
             const effectiveNodeId = resolvedNodeId ?? nodeId?.trim();
-            const data = effectiveNodeId
+            // Cache lookup (60s TTL) — bypassed when debug=true
+            const cacheK = makeCacheKey("figma_get_design_context", { resolvedKey, effectiveNodeId, depth, verbosity, opts });
+            const cached = debug ? null : cache.get(cacheK, 60_000);
+            const data = cached ?? (effectiveNodeId
                 ? await conn.getNodeContext(effectiveNodeId, depth, verbosity, opts)
-                : await conn.getDocumentStructure(depth, verbosity, opts);
-            const text = data === undefined || data === null
-                ? JSON.stringify({ success: false, error: "No data from plugin" })
-                : typeof data === "string"
-                    ? data
-                    : JSON.stringify(data);
-            return { content: [{ type: "text", text }] };
+                : await conn.getDocumentStructure(depth, verbosity, opts));
+            if (!cached)
+                cache.set(cacheK, data);
+            return toolResult(data, "figma_get_design_context", { skipGuard: !!cached, debug });
         }
         catch (err) {
             const msg = err instanceof Error ? err.message : String(err);
@@ -328,7 +385,11 @@ export async function main() {
     }));
     // ---- figma_execute ----
     server.registerTool("figma_execute", {
-        description: "Run JavaScript in the Figma plugin context. Full Plugin API available. Use fileKey or figmaUrl to target a specific file.",
+        description: "Run JavaScript in the Figma plugin context. Full Plugin API available. Use fileKey or figmaUrl to target a specific file. " +
+            "v1.8.1+: Static analysis detects design-system discipline violations (hardcoded colors, missing token bindings, no-instance usage, hardcoded typography). " +
+            "SEVERE warnings are promoted to the top of the response as _designSystemViolations — Claude must read and self-correct. " +
+            "Also detects gotchas: FILL/ABSOLUTE before appendChild, sync API usage, missing loadFontAsync, sync currentPage assignment. " +
+            "For component instances: use setProperties({...}), NOT findAll(TEXT).",
         inputSchema: {
             figmaUrl: z.string().optional().describe("Figma or FigJam file URL for routing."),
             fileKey: z.string().optional().describe("Target a specific connected file."),
@@ -343,8 +404,26 @@ export async function main() {
                 isError: true,
             };
         }
-        const clampedTimeout = Math.max(3000, Math.min(timeout ?? 15000, 120000));
+        const clampedTimeout = Math.max(3000, Math.min(timeout ?? 15000, 30000));
         invalidateCache();
+        // v1.8.1: Structured warnings with SEVERE vs ADVISORY severity
+        const codeWarnings = analyzeCodeForWarnings(code);
+        const severeWarnings = codeWarnings.filter((w) => w.severity === "SEVERE");
+        const advisoryWarnings = codeWarnings.filter((w) => w.severity === "ADVISORY");
+        // SEVERE warnings go to a prominent field that Claude cannot ignore
+        const dsViolations = severeWarnings.length > 0
+            ? {
+                _designSystemViolations: {
+                    count: severeWarnings.length,
+                    message: "⚠️ DESIGN SYSTEM DISIPLIN IHLALI TESPIT EDILDI — kodu duzelt ve tekrar calistir. Bu ekran kabul edilmez.",
+                    violations: severeWarnings.map((w) => ({ category: w.category, message: w.message })),
+                    action: "Her ihlal icin uygun DS token binding veya component instance kullan. Detay: figma-canvas-ops SKILL Kural 10.",
+                },
+            }
+            : {};
+        const warningsField = advisoryWarnings.length > 0
+            ? { _warnings: advisoryWarnings.map((w) => w.message) }
+            : {};
         const startTime = Date.now();
         try {
             const conn = getConnector(bridge, resolveFileKey(figmaUrl, fileKey));
@@ -362,10 +441,12 @@ export async function main() {
                 catch { /* safe fallback */ }
                 return {
                     content: [{ type: "text", text: JSON.stringify({
+                                ...dsViolations, // v1.8.1: SEVERE warnings FIRST, before anything else
                                 ...result,
                                 errorCategory: category,
                                 _metrics: { durationMs, timeoutMs: clampedTimeout },
                                 hint,
+                                ...warningsField,
                             }) }],
                     isError: true,
                 };
@@ -373,8 +454,15 @@ export async function main() {
             let enriched;
             try {
                 enriched = typeof result === "object" && result !== null
-                    ? { ...result, _metrics: { durationMs, timeoutMs: clampedTimeout } }
-                    : result;
+                    ? {
+                        ...dsViolations, // v1.8.1: SEVERE warnings at top level
+                        ...result,
+                        _metrics: { durationMs, timeoutMs: clampedTimeout },
+                        ...warningsField,
+                    }
+                    : severeWarnings.length > 0 || advisoryWarnings.length > 0
+                        ? { ...dsViolations, result, ...warningsField }
+                        : result;
             }
             catch {
                 enriched = result;
@@ -399,26 +487,122 @@ export async function main() {
                             error: msg,
                             _metrics: { durationMs, timeoutMs: clampedTimeout },
                             hint,
+                            ...warningsField,
                         }) }],
                 isError: true,
             };
         }
     }));
+    // ============================================================================
+    // v1.8.1: HIGH-LEVEL "FAST AND CORRECT" TOOLS
+    // ============================================================================
+    //
+    // These tools sit above figma_execute and provide one-call solutions for
+    // common workflows. Claude should prefer these over hand-written execute
+    // code when possible — they handle token binding, auto-layout preservation,
+    // and DS instance preservation automatically.
+    // ============================================================================
+    // ---- figma_clone_screen_to_device ----
+    // v1.8.2: NARROW USE CASE ONLY — device migration.
+    // For alternatives/variations/new designs, use figma_execute with the
+    // generate-figma-screen SKILL Step 5 "build from scratch" pattern.
+    // Clone will copy benchmark's existing mistakes (hardcoded rectangles,
+    // missing token bindings, non-responsive layouts).
+    server.registerTool("figma_clone_screen_to_device", {
+        description: "⚠️ NARROW USE CASE — Device migration ONLY. Clone a Figma screen to a target device " +
+            "dimension, preserving library instances, bound variables, and auto-layout. " +
+            "USE ONLY WHEN: same design system + same layout structure + only screen size changes. " +
+            "DO NOT USE FOR: creating alternatives, variations, or new designs — these REQUIRE " +
+            "building from scratch with figma_execute following the generate-figma-screen SKILL " +
+            "Step 5 pattern (search_assets → instantiate_component → setBoundVariable → auto-layout FILL). " +
+            "Clone copies benchmark's EXISTING mistakes (hardcoded rectangles, missing token bindings, " +
+            "non-responsive layouts). Benchmark is INSPIRATION, not a copy source for variations. " +
+            "If the user says 'alternatif', 'varyasyon', 'farklı', 'yeni', 'tasarla' — USE figma_execute + Step 5, NOT this tool. " +
+            "Device presets: iPhone 17, iPhone 16 Pro Max, Android Compact, iPad Pro 11, Desktop, " +
+            "and more. Custom: 'WxH' format.",
+        inputSchema: {
+            figmaUrl: z.string().optional().describe("Figma file URL for routing."),
+            fileKey: z.string().optional().describe("Target a specific connected file."),
+            sourceNodeId: z.string().describe("Node ID of the source screen to clone (e.g. '139:3407')"),
+            targetDevice: z.string().describe("Device preset name (e.g. 'iPhone 17', 'Android Compact') or custom 'WxH' (e.g. '1200x800')"),
+            newName: z.string().optional().describe("Name for the cloned screen (default: source name + device suffix)"),
+            targetParentId: z.string().optional().describe("Parent node to place the clone under (default: current page)"),
+            position: z
+                .object({ x: z.number(), y: z.number() })
+                .optional()
+                .describe("Explicit position for the clone (default: auto-placed right of source)"),
+        },
+        annotations: { destructiveHint: true },
+    }, safeToolHandler(async ({ figmaUrl, fileKey, sourceNodeId, targetDevice, newName, targetParentId, position, }) => {
+        // Resolve device name to concrete dimensions
+        const resolved = resolveDevice(targetDevice);
+        if (!resolved) {
+            return errorResult(`Unknown device preset '${targetDevice}'. Supported presets: ${DEVICE_PRESETS.map((p) => p.name).join(", ")}. For custom, use 'WxH' format (e.g. '1200x800').`);
+        }
+        invalidateCache();
+        const conn = getConnector(bridge, resolveFileKey(figmaUrl, fileKey));
+        const result = await conn.cloneScreenToDevice({
+            sourceNodeId,
+            targetWidth: resolved.width,
+            targetHeight: resolved.height,
+            targetDeviceName: resolved.name,
+            newName,
+            targetParentId,
+            position,
+        });
+        return toolResult(result, "figma_clone_screen_to_device");
+    }));
+    // ---- figma_validate_screen ----
+    // Post-creation audit tool. Walks a node tree and scores its DS compliance
+    // across 3 dimensions: instance coverage, token binding coverage, auto-layout
+    // coverage. Returns pass/fail + actionable violations.
+    server.registerTool("figma_validate_screen", {
+        description: "Validate a screen against design-system discipline criteria. Returns a compliance score (0-100) " +
+            "across 3 dimensions: instance coverage (library usage), token binding coverage (bound variables), " +
+            "and auto-layout coverage. Use this AFTER creating a screen to verify DS compliance. " +
+            "If score < minScore, Claude should delete the screen and rebuild it using DS components + token bindings. " +
+            "Read-only — never mutates the file.",
+        inputSchema: {
+            figmaUrl: z.string().optional().describe("Figma file URL for routing."),
+            fileKey: z.string().optional().describe("Target a specific connected file."),
+            nodeId: z.string().describe("Node ID of the screen to validate"),
+            expectedDs: z.string().optional().describe("Expected DS library name (e.g. '❖ SUI') for library match scoring"),
+            minScore: z.number().min(0).max(100).optional().default(80).describe("Minimum acceptable score (0-100). Below this, the screen is considered non-compliant."),
+        },
+        annotations: { readOnlyHint: true },
+    }, safeToolHandler(async ({ figmaUrl, fileKey, nodeId, expectedDs, minScore, }) => {
+        const conn = getConnector(bridge, resolveFileKey(figmaUrl, fileKey));
+        const result = await conn.validateScreen({ nodeId, expectedDs, minScore });
+        return toolResult(result, "figma_validate_screen");
+    }));
     // ---- figma_capture_screenshot ----
+    // v1.8.0: Default JPG@1x (~80% smaller base64 vs PNG@2x). Override via params.
     server.registerTool("figma_capture_screenshot", {
-        description: "Capture screenshot of a node or current view from the plugin. No REST API. Use fileKey or figmaUrl to target a specific file.",
+        description: "Capture screenshot of a node or current view from the plugin. No REST API. Defaults to JPG@1x (q70) for context safety. Use scale/format/jpegQuality to override.",
         inputSchema: {
             figmaUrl: z.string().optional().describe("Figma or FigJam file URL for routing."),
             fileKey: z.string().optional().describe("Target a specific connected file."),
             nodeId: z.string().optional(),
-            format: z.enum(["PNG", "JPG"]).optional().default("PNG"),
-            scale: z.number().optional().default(2),
+            format: z.enum(["PNG", "JPG"]).optional().default(LEGACY_DEFAULTS ? "PNG" : "JPG"),
+            scale: z.number().optional().default(LEGACY_DEFAULTS ? 2 : 1),
+            jpegQuality: z.number().min(30).max(100).optional().default(70).describe("JPEG quality 30-100. Ignored when format=PNG."),
         },
         annotations: { readOnlyHint: true },
-    }, safeToolHandler(async ({ figmaUrl, fileKey, nodeId, format, scale }) => {
+    }, safeToolHandler(async ({ figmaUrl, fileKey, nodeId, format, scale, jpegQuality }) => {
         const conn = getConnector(bridge, resolveFileKey(figmaUrl, fileKey));
-        const result = await conn.captureScreenshot(nodeId ?? null, { format, scale });
-        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        const result = await conn.captureScreenshot(nodeId ?? null, { format, scale, jpegQuality });
+        // v1.9.6 Fix M1 — skipGuard: true → truncatePluginResponse'u bypass et.
+        // Gerekçe: screenshot response {success, image: {base64, ...}} şeklinde.
+        // pruneNodeTree screenshot payload'una (node tree değil) uymadığı için
+        // final fallback truncateResponse({maxStringLength: 200}) devreye girip
+        // base64 string'i 200 karaktere kırpıyordu → Claude Desktop `{}` empty
+        // object görüyordu (FP-1-R-v2 Known Limitation #8 root cause).
+        // skipGuard: true ile payload olduğu gibi JSON.stringify edilir, base64
+        // intact kalır. Claude image render etmez (text content block) ama
+        // base64 string'i görür, kullanabilir, böylece empty object problemi
+        // çözülür. Image content block upgrade'i (MCP image type) Part 5
+        // sonraki adımı — safeToolHandler generic refactor'u gerektirir.
+        return toolResult(result, "figma_capture_screenshot", { skipGuard: true });
     }));
     // ---- figma_set_instance_properties ----
     server.registerTool("figma_set_instance_properties", {
@@ -581,7 +765,9 @@ export async function main() {
     }));
     // ---- Node operations (short list) ----
     server.registerTool("figma_instantiate_component", {
-        description: "Create a component instance. Use componentKey from figma_search_components or nodeId for local components.",
+        description: "Create a component instance. Use componentKey from figma_search_components, figma_search_assets, or REST API. " +
+            "Supports library components (importComponentByKeyAsync) and local components (by nodeId). " +
+            "After creation: use overrides with setProperties({...}) for component properties — do NOT use findAll(TEXT) to modify instance text.",
         inputSchema: {
             componentKey: z.string(),
             options: z
@@ -684,35 +870,37 @@ export async function main() {
         return { content: [{ type: "text", text: JSON.stringify(result) }] };
     }));
     server.registerTool("figma_get_component_image", {
-        description: "Get screenshot of a node (component/frame). Returns base64 image. No REST API.",
+        description: "Get screenshot of a node (component/frame). Returns base64 image. Defaults to JPG@1x q70 (v1.8.0 context-safe).",
         inputSchema: {
             nodeId: z.string(),
-            scale: z.number().min(0.5).max(4).optional().default(2),
-            format: z.enum(["PNG", "JPG"]).optional().default("PNG"),
+            scale: z.number().min(0.5).max(4).optional().default(LEGACY_DEFAULTS ? 2 : 1),
+            format: z.enum(["PNG", "JPG"]).optional().default(LEGACY_DEFAULTS ? "PNG" : "JPG"),
+            jpegQuality: z.number().min(30).max(100).optional().default(70),
         },
         annotations: { readOnlyHint: true },
-    }, safeToolHandler(async ({ nodeId, scale, format }) => {
+    }, safeToolHandler(async ({ nodeId, scale, format, jpegQuality }) => {
         const conn = getConnector(bridge);
-        const result = await conn.captureScreenshot(nodeId, { scale, format });
-        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+        const result = await conn.captureScreenshot(nodeId, { scale, format, jpegQuality });
+        return toolResult(result, "figma_get_component_image");
     }));
     server.registerTool("figma_get_component_for_development", {
-        description: "Get component metadata plus base64 screenshot in one call. For design-to-code workflows.",
+        description: "Get component metadata plus base64 screenshot in one call. For design-to-code workflows. Defaults to JPG@1x q70 (v1.8.0 context-safe).",
         inputSchema: {
             nodeId: z.string(),
-            scale: z.number().min(0.5).max(4).optional().default(2),
-            format: z.enum(["PNG", "JPG"]).optional().default("PNG"),
+            scale: z.number().min(0.5).max(4).optional().default(LEGACY_DEFAULTS ? 2 : 1),
+            format: z.enum(["PNG", "JPG"]).optional().default(LEGACY_DEFAULTS ? "PNG" : "JPG"),
+            jpegQuality: z.number().min(30).max(100).optional().default(70),
         },
         annotations: { readOnlyHint: true },
-    }, safeToolHandler(async ({ nodeId, scale, format }) => {
+    }, safeToolHandler(async ({ nodeId, scale, format, jpegQuality }) => {
         const conn = getConnector(bridge);
         const [component, screenshot] = await Promise.all([
             conn.getComponentFromPluginUI(nodeId),
-            conn.captureScreenshot(nodeId, { scale, format }),
+            conn.captureScreenshot(nodeId, { scale, format, jpegQuality }),
         ]);
         const comp = component?.component ?? component;
         const out = { success: true, component: comp, image: screenshot?.image ?? screenshot?.data };
-        return { content: [{ type: "text", text: JSON.stringify(out) }] };
+        return toolResult(out, "figma_get_component_for_development");
     }));
     // ---- Batch variables & setup_design_tokens & arrange_component_set ----
     server.registerTool("figma_batch_create_variables", {
@@ -989,6 +1177,11 @@ export async function main() {
         const listening = bridge.isListening();
         const currentPort = bridge.getPort();
         const startError = bridge.getStartError();
+        // v1.8.0+: detect plugin/server version mismatch
+        const outdatedPlugins = connectedFiles.filter((f) => f.pluginVersion === null || (f.pluginVersion && f.pluginVersion !== FMCP_VERSION));
+        const versionWarning = outdatedPlugins.length > 0
+            ? `⚠️ Plugin version mismatch detected: ${outdatedPlugins.map(f => `${f.fileName || "?"} (plugin v${f.pluginVersion ?? "<1.8.0"}, server v${FMCP_VERSION})`).join(", ")}. Reinstall the plugin from f-mcp-plugin/ for full v1.8.0 context-safe defaults.`
+            : undefined;
         let msg;
         if (!listening) {
             msg = startError
@@ -997,6 +1190,8 @@ export async function main() {
         }
         else if (connected) {
             msg = `F-MCP ATezer Bridge: ${clientCount} plugin(s) connected on port ${currentPort}. You can use all figma_* tools.`;
+            if (versionWarning)
+                msg += " " + versionWarning;
         }
         else {
             msg = PLUGIN_NOT_CONNECTED;
@@ -1018,30 +1213,57 @@ export async function main() {
                         connectedClients: clientCount,
                         connectedFiles,
                         bridgePort: currentPort,
+                        serverVersion: FMCP_VERSION,
                         ...(autoIncremented && { preferredPort: bridge.getPreferredPort(), autoIncremented }),
                         message: msg,
                         ...(startError && { startError }),
                         ...(portHint && { portHint }),
+                        ...(versionWarning && { versionWarning }),
                     }),
                 }],
         };
     });
     // ---- Node Creation Tools ----
+    // v1.8.0: figma_create_frame now supports auto-layout out of the box.
+    // Default layoutMode="VERTICAL" with sensible padding/gap. Pass layoutMode="NONE"
+    // for a free-form frame (legacy behavior).
     server.registerTool("figma_create_frame", {
-        description: "Create a new frame node on the current page. Returns the created node ID.",
+        description: "Create a new frame node with optional auto-layout. Returns the created node ID. " +
+            "v1.8.0: defaults to layoutMode='VERTICAL' with paddingTop/Bottom=16, paddingLeft/Right=16, itemSpacing=12, " +
+            "primaryAxisSizingMode='AUTO', counterAxisSizingMode='AUTO'. Pass layoutMode='NONE' for legacy free-form frames.",
         inputSchema: {
             name: z.string().optional().default("Frame").describe("Frame name"),
             x: z.number().optional().describe("X position. If omitted, auto-positions to the right of existing content"),
             y: z.number().optional().default(0),
             width: z.number().optional().default(200),
             height: z.number().optional().default(200),
-            fillColor: z.string().optional().describe("Hex color e.g. '#ffffff'"),
+            fillColor: z.string().optional().describe("Hex color e.g. '#ffffff'. DEPRECATED — prefer fillVariableKey for DS token binding (v1.8.1+)."),
             parentId: z.string().optional().describe("Parent node ID (default: current page)"),
+            // Auto-layout parameters (v1.8.0)
+            layoutMode: z.enum(["NONE", "HORIZONTAL", "VERTICAL"]).optional().default("VERTICAL").describe("Auto-layout direction. VERTICAL by default; pass 'NONE' for free-form frames."),
+            paddingTop: z.number().optional().default(16),
+            paddingBottom: z.number().optional().default(16),
+            paddingLeft: z.number().optional().default(16),
+            paddingRight: z.number().optional().default(16),
+            itemSpacing: z.number().optional().default(12).describe("Gap between auto-layout children"),
+            primaryAxisSizingMode: z.enum(["FIXED", "AUTO"]).optional().default("AUTO").describe("AUTO = hug contents, FIXED = use width/height"),
+            counterAxisSizingMode: z.enum(["FIXED", "AUTO"]).optional().default("AUTO"),
+            primaryAxisAlignItems: z.enum(["MIN", "CENTER", "MAX", "SPACE_BETWEEN"]).optional().describe("Main-axis alignment (MIN=top/left, MAX=bottom/right)"),
+            counterAxisAlignItems: z.enum(["MIN", "CENTER", "MAX", "BASELINE"]).optional().describe("Cross-axis alignment"),
+            layoutWrap: z.enum(["NO_WRAP", "WRAP"]).optional().describe("Wrap children when they exceed primary axis"),
+            // v1.8.1+: DS token binding params — PREFER over hardcoded fillColor / padding / radius
+            fillVariableKey: z.string().optional().describe("DS variable key for fill binding (from figma_get_library_variables). Takes precedence over fillColor."),
+            paddingVariableKey: z.string().optional().describe("DS spacing variable key — applies to all 4 paddings via setBoundVariable."),
+            itemSpacingVariableKey: z.string().optional().describe("DS spacing variable key for itemSpacing via setBoundVariable."),
+            cornerRadiusVariableKey: z.string().optional().describe("DS radius variable key for cornerRadius via setBoundVariable."),
+            cornerRadius: z.number().optional().describe("Hardcoded corner radius in px. DEPRECATED — prefer cornerRadiusVariableKey."),
         },
-    }, async ({ name, x, y, width, height, fillColor, parentId }) => {
+    }, async ({ name, x, y, width, height, fillColor, parentId, layoutMode, paddingTop, paddingBottom, paddingLeft, paddingRight, itemSpacing, primaryAxisSizingMode, counterAxisSizingMode, primaryAxisAlignItems, counterAxisAlignItems, layoutWrap, fillVariableKey, paddingVariableKey, itemSpacingVariableKey, cornerRadiusVariableKey, cornerRadius }) => {
         try {
+            invalidateCache();
             const conn = getConnector(bridge);
             const autoPosition = x === undefined && !parentId;
+            const useAutoLayout = layoutMode !== "NONE";
             const code = `
 					${autoPosition ? `
 					let posX = 0;
@@ -1059,9 +1281,64 @@ export async function main() {
 					frame.name = ${JSON.stringify(name)};
 					frame.x = posX; frame.y = ${y};
 					frame.resize(${width}, ${height});
-					${fillColor ? `frame.fills = [{ type: 'SOLID', color: { r: parseInt('${fillColor}'.slice(1,3),16)/255, g: parseInt('${fillColor}'.slice(3,5),16)/255, b: parseInt('${fillColor}'.slice(5,7),16)/255 } }];` : ""}
+					${useAutoLayout ? `
+					frame.layoutMode = ${JSON.stringify(layoutMode)};
+					frame.paddingTop = ${paddingTop};
+					frame.paddingBottom = ${paddingBottom};
+					frame.paddingLeft = ${paddingLeft};
+					frame.paddingRight = ${paddingRight};
+					frame.itemSpacing = ${itemSpacing};
+					frame.primaryAxisSizingMode = ${JSON.stringify(primaryAxisSizingMode)};
+					frame.counterAxisSizingMode = ${JSON.stringify(counterAxisSizingMode)};
+					${primaryAxisAlignItems ? `frame.primaryAxisAlignItems = ${JSON.stringify(primaryAxisAlignItems)};` : ""}
+					${counterAxisAlignItems ? `frame.counterAxisAlignItems = ${JSON.stringify(counterAxisAlignItems)};` : ""}
+					${layoutWrap ? `frame.layoutWrap = ${JSON.stringify(layoutWrap)};` : ""}
+					` : ""}
+					${cornerRadius != null ? `frame.cornerRadius = ${cornerRadius};` : ""}
+					// v1.8.1: DS token binding takes precedence over hardcoded values
+					${fillVariableKey ? `
+					try {
+						const fillVar = await figma.variables.importVariableByKeyAsync(${JSON.stringify(fillVariableKey)});
+						const baseFill = { type: 'SOLID', color: { r: 1, g: 1, b: 1 }, opacity: 1 };
+						const boundFill = figma.variables.setBoundVariableForPaint(baseFill, 'color', fillVar);
+						frame.fills = [boundFill];
+					} catch (fillBindErr) {
+						console.warn('[figma_create_frame] fillVariableKey binding failed:', fillBindErr.message);
+					}
+					` : fillColor ? `frame.fills = [{ type: 'SOLID', color: { r: parseInt('${fillColor}'.slice(1,3),16)/255, g: parseInt('${fillColor}'.slice(3,5),16)/255, b: parseInt('${fillColor}'.slice(5,7),16)/255 } }];` : ""}
+					${paddingVariableKey ? `
+					try {
+						const padVar = await figma.variables.importVariableByKeyAsync(${JSON.stringify(paddingVariableKey)});
+						frame.setBoundVariable('paddingTop', padVar);
+						frame.setBoundVariable('paddingBottom', padVar);
+						frame.setBoundVariable('paddingLeft', padVar);
+						frame.setBoundVariable('paddingRight', padVar);
+					} catch (padBindErr) {
+						console.warn('[figma_create_frame] paddingVariableKey binding failed:', padBindErr.message);
+					}
+					` : ""}
+					${itemSpacingVariableKey ? `
+					try {
+						const gapVar = await figma.variables.importVariableByKeyAsync(${JSON.stringify(itemSpacingVariableKey)});
+						frame.setBoundVariable('itemSpacing', gapVar);
+					} catch (gapBindErr) {
+						console.warn('[figma_create_frame] itemSpacingVariableKey binding failed:', gapBindErr.message);
+					}
+					` : ""}
+					${cornerRadiusVariableKey ? `
+					try {
+						const radVar = await figma.variables.importVariableByKeyAsync(${JSON.stringify(cornerRadiusVariableKey)});
+						frame.setBoundVariable('topLeftRadius', radVar);
+						frame.setBoundVariable('topRightRadius', radVar);
+						frame.setBoundVariable('bottomLeftRadius', radVar);
+						frame.setBoundVariable('bottomRightRadius', radVar);
+					} catch (radBindErr) {
+						console.warn('[figma_create_frame] cornerRadiusVariableKey binding failed:', radBindErr.message);
+					}
+					` : ""}
 					${parentId ? `const parent = await figma.getNodeByIdAsync(${JSON.stringify(parentId)}); if (parent && 'appendChild' in parent) parent.appendChild(frame);` : ""}
-					return { id: frame.id, name: frame.name, width: frame.width, height: frame.height, x: frame.x, y: frame.y };
+					const boundCount = frame.boundVariables ? Object.keys(frame.boundVariables).length : 0;
+					return { id: frame.id, name: frame.name, width: frame.width, height: frame.height, x: frame.x, y: frame.y, layoutMode: frame.layoutMode, boundVariableCount: boundCount };
 				`;
             const result = await conn.executeCodeViaUI(code, 10000);
             return { content: [{ type: "text", text: JSON.stringify({ success: true, ...result }) }] };
@@ -1071,14 +1348,16 @@ export async function main() {
         }
     });
     server.registerTool("figma_create_text", {
-        description: "Create a new text node on the current page. Returns the created node ID.",
+        description: "Create a new text node on the current page. Returns the created node ID. " +
+            "IMPORTANT: fontFamily defaults to 'Inter' — if using a design system (e.g. SUI uses SHBGrotesk), specify the DS font. " +
+            "For DS text with proper token binding, prefer figma_execute with importStyleByKeyAsync + setTextStyleIdAsync instead.",
         inputSchema: {
             text: z.string().describe("Text content"),
             x: z.number().optional().default(0),
             y: z.number().optional().default(0),
             name: z.string().optional().describe("Node name (default: text content)"),
             fontSize: z.number().optional().default(16),
-            fontFamily: z.string().optional().default("Inter"),
+            fontFamily: z.string().optional().default("Inter").describe("Font family — defaults to Inter. Specify DS font if using a design system (e.g. SHBGrotesk for SUI)."),
             fontStyle: z.string().optional().default("Regular"),
             fillColor: z.string().optional().describe("Text color hex e.g. '#000000'"),
             parentId: z.string().optional().describe("Parent node ID"),
@@ -1167,11 +1446,12 @@ export async function main() {
     server.registerTool("figma_export_nodes", {
         description: "Export one or multiple nodes as SVG, PNG, JPG, or PDF. Returns base64-encoded data for each node. " +
             "Supports batch export (up to 50 nodes). No REST API token needed — uses plugin exportAsync. " +
-            "SVG preserves vectors; PNG/JPG are rasterized at configurable scale.",
+            "SVG preserves vectors; PNG/JPG are rasterized at configurable scale. " +
+            "v1.8.0: default scale=1 for context safety (was 2). Override for high-DPI exports.",
         inputSchema: {
             nodeIds: z.array(z.string()).min(1).max(50).describe("Node IDs to export (1-50)"),
             format: z.enum(["PNG", "SVG", "JPG", "PDF"]).optional().default("PNG").describe("Export format"),
-            scale: z.number().min(0.5).max(4).optional().default(2).describe("Scale factor (0.5-4, default 2)"),
+            scale: z.number().min(0.5).max(4).optional().default(LEGACY_DEFAULTS ? 2 : 1).describe("Scale factor (0.5-4, default 1)"),
             svgOutlineText: z.boolean().optional().describe("SVG: render text as outlines (default true)"),
             svgIncludeId: z.boolean().optional().describe("SVG: include node IDs in attributes"),
         },
@@ -1226,36 +1506,175 @@ export async function main() {
     });
     // ---- figma_search_assets (team library search via plugin) ----
     server.registerTool("figma_search_assets", {
-        description: "Search for published team library components and styles available in the current file. " +
-            "Uses Figma's teamLibrary API via plugin. Returns available components from enabled libraries.",
+        description: "Search for design system assets in the current Figma file. Returns: " +
+            "(1) team library VARIABLES via figma.teamLibrary API (all enabled libraries), " +
+            "(2) file-local COMPONENTS / COMPONENT_SETS, and " +
+            "(3) v1.8.0+: REMOTE LIBRARY COMPONENTS discovered by scanning existing INSTANCE nodes (returned as 'libraryComponents'). " +
+            "For library components to appear, at least one DS instance must exist in the file — place one manually first if empty. " +
+            "Pass currentPageOnly=false to scan all pages for instance discovery. " +
+            "Use the returned componentKey with figma_instantiate_component to place new instances. " +
+            "Pass assetTypes to filter: ['variables'], ['components'], or both (default).",
         inputSchema: {
+            figmaUrl: z.string().optional().describe("Figma or FigJam file URL for routing."),
+            fileKey: z.string().optional().describe("Target a specific connected file."),
             query: z.string().optional().describe("Search query to filter by name"),
+            assetTypes: z.array(z.string()).optional().describe("Asset types to search: 'variables', 'components'. Default: both."),
+            limit: z.number().min(1).max(80).optional().describe("Max results per asset type (default 25, max 80)"),
+            currentPageOnly: z.boolean().optional().describe("For components: search current page only (default true)"),
         },
         annotations: { readOnlyHint: true },
-    }, async ({ query }) => {
-        try {
-            const conn = getConnector(bridge);
-            const code = `
-					if (!figma.teamLibrary) return { success: false, error: "teamLibrary API not available" };
-					const availableLibs = await figma.teamLibrary.getAvailableLibraryVariableCollectionsAsync();
-					const availableComps = typeof figma.teamLibrary.getAvailableLibraryComponentsAsync === 'function' ? await figma.teamLibrary.getAvailableLibraryComponentsAsync() : [];
-					return {
-						variableCollections: availableLibs.map(c => ({ name: c.name, key: c.key, libraryName: c.libraryName })),
-						note: "Use figma_search_components for file-local components. Team library component search requires REST API (figma_rest_api)."
-					};
-				`;
-            const result = await conn.executeCodeViaUI(code, 15000);
-            const data = result;
-            if (query && data.variableCollections && Array.isArray(data.variableCollections)) {
-                const q = query.toLowerCase();
-                data.variableCollections = data.variableCollections.filter((c) => (c.name || "").toLowerCase().includes(q) || (c.libraryName || "").toLowerCase().includes(q));
-            }
-            return { content: [{ type: "text", text: JSON.stringify({ success: true, ...data }) }] };
-        }
-        catch (err) {
-            return { content: [{ type: "text", text: JSON.stringify({ success: false, error: err instanceof Error ? err.message : String(err) }) }], isError: true };
-        }
-    });
+    }, safeToolHandler(async ({ figmaUrl, fileKey, query, assetTypes, limit, currentPageOnly }) => {
+        const conn = getConnector(bridge, resolveFileKey(figmaUrl, fileKey));
+        const result = await conn.searchLibraryAssets({
+            query: query || undefined,
+            assetTypes: assetTypes?.length ? assetTypes : undefined,
+            limit: limit ?? undefined,
+            currentPageOnly,
+        });
+        const data = result;
+        return { content: [{ type: "text", text: JSON.stringify({ success: true, ...data }) }] };
+    }));
+    // ---- figma_get_library_variables (team library variable discovery with import keys) ----
+    server.registerTool("figma_get_library_variables", {
+        description: "List variables from team library collections with import keys. " +
+            "Uses figma.teamLibrary API — works in the TARGET file, no need to connect the DS source file. " +
+            "Returns variable name, key (for importVariableByKeyAsync), resolvedType, collection, and library name. " +
+            "Use the returned keys with figma_bind_variable or figma.variables.importVariableByKeyAsync() in figma_execute.",
+        inputSchema: {
+            figmaUrl: z.string().optional().describe("Figma file URL for routing."),
+            fileKey: z.string().optional().describe("Target a specific connected file."),
+            query: z.string().optional().describe("Filter variables by name (case-insensitive contains)"),
+            collectionName: z.string().optional().describe("Filter by collection name (exact match)"),
+            libraryName: z.string().optional().describe("Filter by library name (exact match, e.g. '❖ SUI')"),
+            limit: z.number().min(1).max(500).optional().describe("Max results (default 100)"),
+        },
+        annotations: { readOnlyHint: true },
+    }, safeToolHandler(async ({ figmaUrl, fileKey, query, collectionName, libraryName, limit }) => {
+        const conn = getConnector(bridge, resolveFileKey(figmaUrl, fileKey));
+        const maxResults = limit ?? 100;
+        const q = query ? query.toLowerCase() : "";
+        const code = `
+				if (!figma.teamLibrary) return { success: false, error: "teamLibrary API not available" };
+				var cols = await figma.teamLibrary.getAvailableLibraryVariableCollectionsAsync();
+				var filtered = cols;
+				${collectionName ? `filtered = filtered.filter(function(c) { return c.name === ${JSON.stringify(collectionName)}; });` : ""}
+				${libraryName ? `filtered = filtered.filter(function(c) { return c.libraryName === ${JSON.stringify(libraryName)}; });` : ""}
+				var results = [];
+				for (var ci = 0; ci < filtered.length && results.length < ${maxResults}; ci++) {
+					var col = filtered[ci];
+					var vars = await figma.teamLibrary.getVariablesInLibraryCollectionAsync(col.key);
+					for (var vi = 0; vi < vars.length && results.length < ${maxResults}; vi++) {
+						var v = vars[vi];
+						var nm = (v.name || "").toLowerCase();
+						if (!${JSON.stringify(q)} || nm.indexOf(${JSON.stringify(q)}) >= 0) {
+							results.push({ name: v.name, key: v.key, resolvedType: v.resolvedType, collection: col.name, library: col.libraryName });
+						}
+					}
+				}
+				return { success: true, count: results.length, variables: results };
+			`;
+        const result = await conn.executeCodeViaUI(code, 30000);
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    }));
+    // ---- figma_bind_variable (import variable and bind to node property) ----
+    server.registerTool("figma_bind_variable", {
+        description: "Import a library variable by key and bind it to a node property. " +
+            "For colors: binds to fills or strokes via setBoundVariableForPaint. " +
+            "For spacing/sizing: binds via setBoundVariable (paddingLeft, itemSpacing, cornerRadius, etc.). " +
+            "Get variableKey from figma_get_library_variables. " +
+            "The node's fill/spacing will dynamically update when the DS token changes.",
+        inputSchema: {
+            figmaUrl: z.string().optional().describe("Figma file URL for routing."),
+            fileKey: z.string().optional().describe("Target a specific connected file."),
+            nodeId: z.string().describe("Target node ID"),
+            variableKey: z.string().describe("Variable import key from figma_get_library_variables"),
+            property: z.enum([
+                "fills", "strokes",
+                "paddingLeft", "paddingRight", "paddingTop", "paddingBottom",
+                "itemSpacing", "counterAxisSpacing",
+                "topLeftRadius", "topRightRadius", "bottomLeftRadius", "bottomRightRadius", "cornerRadius",
+                "strokeWeight", "opacity",
+                "width", "height", "minWidth", "minHeight", "maxWidth", "maxHeight",
+            ]).describe("Node property to bind the variable to"),
+            paintIndex: z.number().optional().default(0).describe("For fills/strokes: which paint index (default 0)"),
+        },
+        annotations: { destructiveHint: true },
+    }, safeToolHandler(async ({ figmaUrl, fileKey, nodeId, variableKey, property, paintIndex }) => {
+        invalidateCache();
+        const conn = getConnector(bridge, resolveFileKey(figmaUrl, fileKey));
+        const idx = paintIndex ?? 0;
+        const code = `
+				var variable = await figma.variables.importVariableByKeyAsync(${JSON.stringify(variableKey)});
+				var node = await figma.getNodeByIdAsync(${JSON.stringify(nodeId)});
+				if (!node) throw new Error("Node not found: " + ${JSON.stringify(nodeId)});
+				var prop = ${JSON.stringify(property)};
+				if (prop === "fills" || prop === "strokes") {
+					var paints = [];
+					for (var i = 0; i < node[prop].length; i++) paints.push(node[prop][i]);
+					if (!paints[${idx}]) throw new Error("No paint at index ${idx} on " + prop);
+					var boundPaint = figma.variables.setBoundVariableForPaint(paints[${idx}], "color", variable);
+					paints[${idx}] = boundPaint;
+					node[prop] = paints;
+				} else {
+					node.setBoundVariable(prop, variable);
+				}
+				return { success: true, nodeId: ${JSON.stringify(nodeId)}, property: prop, variableName: variable.name, variableId: variable.id };
+			`;
+        const result = await conn.executeCodeViaUI(code, 10000);
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    }));
+    // ---- figma_import_style (import text/paint/effect style from library) ----
+    server.registerTool("figma_import_style", {
+        description: "Import a text, paint, or effect style from a team library by key, and optionally apply it to a node. " +
+            "IMPORTANT: This API only imports PUBLISHED LIBRARY styles, NOT local file styles. " +
+            "For local styles, use 'node.fillStyleId = style.id' (or textStyleId/effectStyleId) directly via figma_execute. " +
+            "Get library style keys from .claude/libraries/ cache or REST API: figma_rest_api GET /v1/files/{fileKey}/styles. " +
+            "For TEXT styles: applies via setTextStyleIdAsync (includes font, size, weight). " +
+            "For PAINT styles: applies via fillStyleId. For EFFECT styles: applies via effectStyleId.",
+        inputSchema: {
+            figmaUrl: z.string().optional().describe("Figma file URL for routing."),
+            fileKey: z.string().optional().describe("Target a specific connected file."),
+            styleKey: z.string().describe("Library style key (must be from a PUBLISHED team library, not a local style)"),
+            nodeId: z.string().optional().describe("Node ID to apply the style to (optional — omit to just import)"),
+        },
+        annotations: { destructiveHint: true },
+    }, safeToolHandler(async ({ figmaUrl, fileKey, styleKey, nodeId }) => {
+        invalidateCache();
+        const conn = getConnector(bridge, resolveFileKey(figmaUrl, fileKey));
+        const code = `
+				var style;
+				try {
+					style = await figma.importStyleByKeyAsync(${JSON.stringify(styleKey)});
+				} catch (e) {
+					var origMsg = e && e.message ? e.message : String(e);
+					throw new Error(
+						"importStyleByKeyAsync failed for key '" + ${JSON.stringify(styleKey)} + "'. " +
+						"This API only works with PUBLISHED LIBRARY styles. " +
+						"Local file styles cannot be imported this way — use 'node.fillStyleId/textStyleId/effectStyleId = <localStyleId>' directly via figma_execute. " +
+						"To find library style keys, use REST API: GET /v1/files/{fileKey}/styles. " +
+						"Original error: " + origMsg
+					);
+				}
+				var applied = false;
+				${nodeId ? `
+				var node = await figma.getNodeByIdAsync(${JSON.stringify(nodeId)});
+				if (!node) throw new Error("Node not found: " + ${JSON.stringify(nodeId)});
+				if (style.type === "TEXT" && node.type === "TEXT") {
+					await node.setTextStyleIdAsync(style.id);
+					applied = true;
+				} else if (style.type === "PAINT") {
+					node.fillStyleId = style.id;
+					applied = true;
+				} else if (style.type === "EFFECT") {
+					node.effectStyleId = style.id;
+					applied = true;
+				}
+				` : ""}
+				return { success: true, styleId: style.id, styleName: style.name, styleType: style.type, applied: applied };
+			`;
+        const result = await conn.executeCodeViaUI(code, 10000);
+        return { content: [{ type: "text", text: JSON.stringify(result) }] };
+    }));
     // ---- figma_plugin_diagnostics ----
     server.registerTool("figma_plugin_diagnostics", {
         description: "Get diagnostic info about plugin connection health: uptime, connected clients, " +