@atezer/figma-mcp-bridge 1.7.30 → 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,42 +109,8 @@ function getErrorHint(category) {
         default: return "Hata mesajini kontrol et.";
     }
 }
-/** Analyze figma_execute code for common mistakes. Returns advisory warnings (never blocks execution). */
-function analyzeCodeForWarnings(code) {
-    const warnings = [];
-    // 1. FILL before appendChild — must set FILL *after* node is in auto-layout parent
-    if (/layoutSizing(?:Horizontal|Vertical)\s*=\s*['"]FILL['"]/i.test(code)) {
-        const fillIdx = code.search(/layoutSizing(?:Horizontal|Vertical)\s*=\s*['"]FILL['"]/i);
-        const appendIdx = code.indexOf("appendChild");
-        if (appendIdx === -1 || fillIdx < appendIdx) {
-            warnings.push("layoutSizingHorizontal/Vertical = 'FILL' appendChild'dan ONCE ayarlanmis. " +
-                "Oncesinde hata verir. FILL'i appendChild SONRASINA tasi.");
-        }
-    }
-    // 2. Sync API usage — should use Async versions
-    const syncApis = [
-        { sync: "getLocalPaintStyles(", async: "getLocalPaintStylesAsync(" },
-        { sync: "getLocalTextStyles(", async: "getLocalTextStylesAsync(" },
-        { sync: "getLocalEffectStyles(", async: "getLocalEffectStylesAsync(" },
-        { sync: "getLocalGridStyles(", async: "getLocalGridStylesAsync(" },
-    ];
-    for (const api of syncApis) {
-        if (code.includes(api.sync) && !code.includes(api.async)) {
-            warnings.push(`Sync API '${api.sync.slice(0, -1)}' tespit edildi. 'await ${api.async.slice(0, -1)}' kullanin — dynamic-page modunda sync API'ler calismaz.`);
-        }
-    }
-    // 3. Font not loaded before text modification
-    if ((/\.characters\s*=/.test(code) || code.includes(".insertCharacters") || code.includes(".deleteCharacters")) &&
-        !code.includes("loadFontAsync")) {
-        warnings.push("Text icerik degisikligi (characters) tespit edildi, ancak loadFontAsync cagrisi yok. " +
-            "Metin degistirmeden once 'await figma.loadFontAsync(node.fontName)' ekleyin.");
-    }
-    // 4. Sync page assignment — does not work
-    if (/figma\.currentPage\s*=/.test(code) && !code.includes("setCurrentPageAsync")) {
-        warnings.push("'figma.currentPage = ...' calismaz. 'await figma.setCurrentPageAsync(page)' kullanin.");
-    }
-    return warnings;
-}
+// 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) => {
@@ -172,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,
@@ -198,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."),
@@ -210,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 ||
@@ -229,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);
@@ -246,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) {
@@ -281,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);
@@ -365,11 +386,9 @@ 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. " +
-            "Common mistakes are detected and returned as _warnings: " +
-            "(1) layoutSizingHorizontal/Vertical='FILL' must be set AFTER appendChild, " +
-            "(2) use getLocalPaintStylesAsync not getLocalPaintStyles, " +
-            "(3) call loadFontAsync before .characters=, " +
-            "(4) use setCurrentPageAsync not figma.currentPage=. " +
+            "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."),
@@ -385,11 +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();
-        // Run static analysis BEFORE execution so warnings are available in ALL response paths
+        // v1.8.1: Structured warnings with SEVERE vs ADVISORY severity
         const codeWarnings = analyzeCodeForWarnings(code);
-        const warningsField = codeWarnings.length > 0 ? { _warnings: codeWarnings } : {};
+        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));
@@ -407,6 +441,7 @@ 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 },
@@ -419,8 +454,15 @@ export async function main() {
             let enriched;
             try {
                 enriched = typeof result === "object" && result !== null
-                    ? { ...result, _metrics: { durationMs, timeoutMs: clampedTimeout }, ...warningsField }
-                    : 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;
@@ -451,21 +493,116 @@ export async function main() {
             };
         }
     }));
+    // ============================================================================
+    // 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", {
@@ -733,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", {
@@ -1038,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
@@ -1046,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;
@@ -1067,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;
@@ -1108,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 }) }] };
@@ -1218,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"),
         },
@@ -1277,9 +1506,13 @@ export async function main() {
     });
     // ---- figma_search_assets (team library search via plugin) ----
     server.registerTool("figma_search_assets", {
-        description: "Search for team library variable collections (with import keys) and file-local components/component sets. " +
-            "Variables come from enabled team libraries via figma.teamLibrary API. " +
-            "Components are file-local only — for remote library component discovery, use figma_rest_api GET /v1/files/{fileKey}/components. " +
+        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."),