figma-console-mcp 1.7.0 → 1.8.0

package/README.md

@@ -42,7 +42,7 @@ Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
 | **Edit existing designs** | ✅ | ❌ |
 | **Manage design tokens/variables** | ✅ | ❌ |
 | Desktop Bridge plugin | ✅ | ❌ |
-| **Total tools available** | **72+** | **16** |
+| **Total tools available** | **53+** | **16** |
 
 > **Bottom line:** Remote SSE is **read-only**. If you want AI to actually design in Figma, use NPX Setup.
 
@@ -52,7 +52,7 @@ Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
 
 **Best for:** Designers who want full AI-assisted design capabilities.
 
-**What you get:** All 72+ tools including design creation, variable management, and component instantiation.
+**What you get:** All 53+ tools including design creation, variable management, and component instantiation.
 
 #### Prerequisites
 
@@ -125,7 +125,7 @@ Create a simple frame with a blue background
 
 **Best for:** Developers who want to modify source code or contribute to the project.
 
-**What you get:** Same 72+ tools as NPX, plus full source code access.
+**What you get:** Same 53+ tools as NPX, plus full source code access.
 
 #### Quick Setup
 
@@ -212,7 +212,7 @@ Ready for design creation? Follow the [NPX Setup](#-npx-setup-recommended) guide
 | Feature | NPX (Recommended) | Local Git | Remote SSE |
 |---------|-------------------|-----------|------------|
 | **Setup time** | ~10 minutes | ~15 minutes | ~2 minutes |
-| **Total tools** | **72+** | **72+** | **16** (read-only) |
+| **Total tools** | **53+** | **53+** | **16** (read-only) |
 | **Design creation** | ✅ | ✅ | ❌ |
 | **Variable management** | ✅ | ✅ | ❌ |
 | **Component instantiation** | ✅ | ✅ | ❌ |
@@ -224,7 +224,7 @@ Ready for design creation? Follow the [NPX Setup](#-npx-setup-recommended) guide
 | **Automatic updates** | ✅ (`@latest`) | Manual (`git pull`) | ✅ |
 | **Source code access** | ❌ | ✅ | ❌ |
 
-> **Key insight:** Remote SSE is read-only with ~22% of the tools. Use NPX for full capabilities.
+> **Key insight:** Remote SSE is read-only with ~30% of the tools. Use NPX for full capabilities.
 
 **📖 [Complete Feature Comparison](docs/mode-comparison.md)**
 
@@ -483,6 +483,34 @@ The **Figma Desktop Bridge** plugin enables powerful capabilities:
 
 **📖 [Desktop Bridge Documentation](figma-desktop-bridge/README.md)**
 
+### 🔌 WebSocket Bridge
+
+Figma Desktop is transitioning away from Chrome DevTools Protocol (CDP) support. The MCP server includes a **WebSocket bridge** that provides seamless connectivity regardless of which transport is available.
+
+**How it works:**
+- The server tries **WebSocket first** (port 9223, instant check) via the Desktop Bridge plugin
+- If no WebSocket client is connected, it falls back to **CDP** (port 9222)
+- The transport is selected automatically per-command — no configuration needed
+- All 53+ tools work identically through either transport
+
+**Setup:**
+1. Install the Desktop Bridge plugin in Figma (Plugins > Development > Import from manifest)
+2. Open the plugin in your Figma file — it connects to ws://localhost:9223 automatically
+3. The MCP server detects the connection and routes commands through WebSocket
+
+**If you also have CDP available** (Figma launched with `--remote-debugging-port=9222`), CDP serves as a fallback. Console tools work with both transports — CDP captures all page-level logs while WebSocket captures plugin-context logs. `figma_navigate` requires CDP for browser-level navigation; in WebSocket mode it returns the connected file info with guidance instead.
+
+**Multiple files:** The WebSocket server supports multiple simultaneous plugin connections — one per open Figma file. Each connection is tracked by file key with independent state (selection, document changes, console logs). The MCP server routes commands to the appropriate file based on active context. If a plugin instance is replaced (e.g., plugin reloaded in the same file), the displaced client stops reconnecting automatically.
+
+**Environment variables:**
+- `FIGMA_WS_PORT` — Override the server-side WebSocket port (default: 9223). Note: the plugin UI and manifest are hard-coded to port 9223. Using a custom port also requires updating `wsPort` in `ui.html` and `allowedDomains` in `manifest.json`.
+
+**Checking transport status:**
+```
+Ask Claude: "Check Figma status"
+```
+The response will show which transport is active (CDP or WebSocket).
+
 ---
 
 ## 🧩 MCP Apps (Experimental)

package/dist/cloudflare/core/design-code-tools.js

@@ -1287,7 +1287,7 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
         try {
             const url = fileUrl || getCurrentUrl();
             if (!url) {
-                throw new Error("No Figma file URL provided. Either pass fileUrl parameter or call figma_navigate first.");
+                throw new Error("No Figma file URL available. Pass the fileUrl parameter, call figma_navigate (CDP mode), or ensure the Desktop Bridge plugin is connected (WebSocket mode).");
             }
             const fileKey = extractFileKey(url);
             if (!fileKey) {
@@ -1474,7 +1474,7 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
         try {
             const url = fileUrl || getCurrentUrl();
             if (!url) {
-                throw new Error("No Figma file URL provided. Either pass fileUrl parameter or call figma_navigate first.");
+                throw new Error("No Figma file URL available. Pass the fileUrl parameter, call figma_navigate (CDP mode), or ensure the Desktop Bridge plugin is connected (WebSocket mode).");
             }
             const fileKey = extractFileKey(url);
             if (!fileKey) {

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

@@ -0,0 +1,8 @@
+/**
+ * Figma Connector Interface
+ *
+ * Transport abstraction that both CDP (FigmaDesktopConnector) and WebSocket
+ * (WebSocketConnector) implement. Allows getDesktopConnector() to return
+ * whichever transport is available — WebSocket preferred, CDP fallback.
+ */
+export {};

package/dist/cloudflare/core/figma-desktop-connector.js

@@ -45,6 +45,9 @@ export class FigmaDesktopConnector {
     async initialize() {
         logger.info('Figma Desktop connector initialized (using Puppeteer Worker API)');
     }
+    getTransportType() {
+        return 'cdp';
+    }
     /**
      * Execute code in Figma's plugin context where the figma API is available
      * Uses Puppeteer's direct worker access instead of CDP context enumeration
@@ -707,7 +710,18 @@ export class FigmaDesktopConnector {
         logger.info({ variableId, newName }, 'Renaming variable via plugin UI');
         const frame = await this.findPluginUIFrame();
         try {
-            const result = await frame.evaluate(`window.renameVariable(${JSON.stringify(variableId)}, ${JSON.stringify(newName)})`);
+            // Look up old name from cached variables data, then rename — single CDP roundtrip
+            const result = await frame.evaluate(`(async () => {
+          var oldName;
+          var vars = window.__figmaVariablesData;
+          if (vars && vars.variables) {
+            var v = vars.variables.find(function(v) { return v.id === ${JSON.stringify(variableId)}; });
+            if (v) oldName = v.name;
+          }
+          var result = await window.renameVariable(${JSON.stringify(variableId)}, ${JSON.stringify(newName)});
+          if (oldName) result.oldName = oldName;
+          return result;
+        })()`);
             logger.info({ success: result.success, oldName: result.oldName, newName: result.variable?.name }, 'Variable renamed');
             await this.logToFigmaConsole((oldN, newN) => {
                 console.log(`[DESKTOP_CONNECTOR] ✅ Variable renamed from "${oldN}" to "${newN}"`);
@@ -773,7 +787,25 @@ export class FigmaDesktopConnector {
         logger.info({ collectionId, modeId, newName }, 'Renaming mode via plugin UI');
         const frame = await this.findPluginUIFrame();
         try {
-            const result = await frame.evaluate(`window.renameMode(${JSON.stringify(collectionId)}, ${JSON.stringify(modeId)}, ${JSON.stringify(newName)})`);
+            // Look up old mode name from cached variables data, then rename — single CDP roundtrip
+            const result = await frame.evaluate(`(async () => {
+          var oldName;
+          var vars = window.__figmaVariablesData;
+          var colls = vars && (vars.variableCollections || vars.collections);
+          if (colls) {
+            for (var i = 0; i < colls.length; i++) {
+              var c = colls[i];
+              if (c.id === ${JSON.stringify(collectionId)}) {
+                var mode = c.modes.find(function(m) { return m.modeId === ${JSON.stringify(modeId)}; });
+                if (mode) oldName = mode.name;
+                break;
+              }
+            }
+          }
+          var result = await window.renameMode(${JSON.stringify(collectionId)}, ${JSON.stringify(modeId)}, ${JSON.stringify(newName)});
+          if (oldName) result.oldName = oldName;
+          return result;
+        })()`);
             logger.info({ success: result.success, oldName: result.oldName, newName }, 'Mode renamed');
             await this.logToFigmaConsole((oldN, newN) => {
                 console.log(`[DESKTOP_CONNECTOR] ✅ Mode renamed from "${oldN}" to "${newN}"`);
@@ -1080,5 +1112,40 @@ export class FigmaDesktopConnector {
             throw error;
         }
     }
+    // ============================================================================
+    // SCREENSHOT & INSTANCE PROPERTIES (via plugin UI)
+    // ============================================================================
+    /**
+     * Capture screenshot via plugin's exportAsync
+     */
+    async captureScreenshot(nodeId, options) {
+        logger.info({ nodeId, options }, 'Capturing screenshot via plugin UI');
+        const frame = await this.findPluginUIFrame();
+        try {
+            const result = await frame.evaluate(`window.captureScreenshot(${JSON.stringify(nodeId)}, ${JSON.stringify(options || {})})`);
+            logger.info({ success: result.success }, 'Screenshot captured');
+            return result;
+        }
+        catch (error) {
+            logger.error({ error, nodeId }, 'Capture screenshot failed');
+            throw error;
+        }
+    }
+    /**
+     * Set component instance properties
+     */
+    async setInstanceProperties(nodeId, properties) {
+        logger.info({ nodeId, properties: Object.keys(properties || {}) }, 'Setting instance properties via plugin UI');
+        const frame = await this.findPluginUIFrame();
+        try {
+            const result = await frame.evaluate(`window.setInstanceProperties(${JSON.stringify(nodeId)}, ${JSON.stringify(properties)})`);
+            logger.info({ success: result.success }, 'Instance properties set');
+            return result;
+        }
+        catch (error) {
+            logger.error({ error, nodeId }, 'Set instance properties failed');
+            throw error;
+        }
+    }
 }
 FigmaDesktopConnector.DEBUG = process.env.DEBUG === '1' || process.env.DEBUG === 'true';

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

@@ -574,7 +574,7 @@ function resolveVariableAliases(variables, allVariablesMap, collectionsMap) {
 /**
  * Register Figma API tools with the MCP server
  */
-export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getConsoleMonitor, getBrowserManager, ensureInitialized, variablesCache, options) {
+export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getConsoleMonitor, getBrowserManager, ensureInitialized, variablesCache, options, getDesktopConnector) {
     const isRemoteMode = options?.isRemoteMode ?? false;
     // Tool 8: Get File Data (General Purpose)
     // NOTE: For specific use cases, consider using specialized tools:
@@ -585,7 +585,7 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             .string()
             .url()
             .optional()
-            .describe("Figma file URL (e.g., https://figma.com/design/abc123). REQUIRED unless figma_navigate was already called. If not provided, ask the user to share their Figma file URL (they can copy it from Figma Desktop via right-click → 'Copy link')."),
+            .describe("Figma file URL (e.g., https://figma.com/design/abc123). Auto-detected from CDP browser or WebSocket Desktop Bridge connection. Only required if neither is connected."),
         depth: z
             .number()
             .min(0)
@@ -626,7 +626,7 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             // Use provided URL or current URL from browser
             const url = fileUrl || getCurrentUrl();
             if (!url) {
-                throw new Error("No Figma file URL provided. Either pass fileUrl parameter or call figma_navigate first.");
+                throw new Error("No Figma file URL available. Pass the fileUrl parameter, call figma_navigate (CDP mode), or ensure the Desktop Bridge plugin is connected (WebSocket mode).");
             }
             const fileKey = extractFileKey(url);
             if (!fileKey) {
@@ -786,7 +786,7 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             .string()
             .url()
             .optional()
-            .describe("Figma file URL (e.g., https://figma.com/design/abc123). REQUIRED unless figma_navigate was already called. If not provided, ask the user to share their Figma file URL (they can copy it from Figma Desktop via right-click → 'Copy link')."),
+            .describe("Figma file URL (e.g., https://figma.com/design/abc123). Auto-detected from CDP browser or WebSocket Desktop Bridge connection. Only required if neither is connected."),
         includePublished: z
             .boolean()
             .optional()
@@ -895,8 +895,8 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
                     {
                         type: "text",
                         text: JSON.stringify({
-                            error: "No Figma file URL provided",
-                            message: "Either pass fileUrl parameter or call figma_navigate first."
+                            error: "No Figma file URL available",
+                            message: "Pass the fileUrl parameter, call figma_navigate (CDP mode), or ensure the Desktop Bridge plugin is connected (WebSocket mode)."
                         }),
                     },
                 ],
@@ -1447,16 +1447,17 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
                 }
             }
             // FALLBACK: Try Desktop connection (when no token available OR as secondary fallback)
-            // Ensure browser manager is initialized
-            if (ensureInitialized && !parseFromConsole && (!hasToken || !restApiSucceeded)) {
-                logger.info("Calling ensureInitialized to initialize browser manager");
+            // Only call ensureInitialized for CDP path — skip when transport-agnostic connector exists
+            if (ensureInitialized && !getDesktopConnector && !parseFromConsole && (!hasToken || !restApiSucceeded)) {
+                logger.info("Calling ensureInitialized to initialize browser manager (CDP path)");
                 await ensureInitialized();
             }
             const browserManager = getBrowserManager?.();
-            logger.info({ hasBrowserManager: !!browserManager, parseFromConsole, hasToken, restApiSucceeded }, "Desktop connection check");
+            const hasDesktopConnection = !!getDesktopConnector || !!browserManager;
+            logger.info({ hasBrowserManager: !!browserManager, hasDesktopConnector: !!getDesktopConnector, parseFromConsole, hasToken, restApiSucceeded }, "Desktop connection check");
             // Debug: Log why Desktop connection might be skipped
-            if (!browserManager) {
-                logger.error("Desktop connection skipped: browserManager is not available");
+            if (!hasDesktopConnection) {
+                logger.error("Desktop connection skipped: neither connector nor browserManager available");
             }
             else if (parseFromConsole) {
                 logger.info("Desktop connection skipped: parseFromConsole is true");
@@ -1464,26 +1465,21 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             else if (restApiSucceeded) {
                 logger.info("Desktop connection skipped: REST API already succeeded");
             }
-            if (browserManager && !parseFromConsole && (!hasToken || !restApiSucceeded)) {
+            if (hasDesktopConnection && !parseFromConsole && (!hasToken || !restApiSucceeded)) {
                 try {
                     logger.info({ fileKey }, "Attempting to get variables via Desktop connection");
-                    // Import and use the Desktop connector
-                    const { FigmaDesktopConnector } = await import('./figma-desktop-connector.js');
-                    const page = await browserManager.getPage();
-                    logger.info("Got page from browser manager");
-                    // Log to browser console for MCP capture
-                    await page.evaluate(() => {
-                        console.log('[FIGMA_TOOLS] 🚀 Got page from browser manager, creating Desktop connector...');
-                    });
-                    const connector = new FigmaDesktopConnector(page);
-                    await page.evaluate(() => {
-                        console.log('[FIGMA_TOOLS] ✅ Desktop connector created, initializing...');
-                    });
-                    await connector.initialize();
-                    logger.info("Desktop connector initialized, calling getVariablesFromPluginUI...");
-                    await page.evaluate(() => {
-                        console.log('[FIGMA_TOOLS] ✅ Desktop connector initialized, calling getVariablesFromPluginUI...');
-                    });
+                    let connector;
+                    if (getDesktopConnector) {
+                        connector = await getDesktopConnector();
+                    }
+                    else {
+                        // Fallback: direct CDP connector (legacy path)
+                        const { FigmaDesktopConnector } = await import('./figma-desktop-connector.js');
+                        const page = await browserManager.getPage();
+                        connector = new FigmaDesktopConnector(page);
+                        await connector.initialize();
+                    }
+                    logger.info({ transport: connector.getTransportType?.() || 'unknown' }, "Desktop connector ready");
                     const desktopResult = await connector.getVariablesFromPluginUI(fileKey);
                     if (desktopResult.success && desktopResult.variables) {
                         logger.info({
@@ -1841,7 +1837,7 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             .string()
             .url()
             .optional()
-            .describe("Figma file URL (e.g., https://figma.com/design/abc123). REQUIRED unless figma_navigate was already called. If not provided, ask the user to share their Figma file URL (they can copy it from Figma Desktop via right-click → 'Copy link')."),
+            .describe("Figma file URL (e.g., https://figma.com/design/abc123). Auto-detected from CDP browser or WebSocket Desktop Bridge connection. Only required if neither is connected."),
         nodeId: z
             .string()
             .describe("Component node ID (e.g., '123:456')"),
@@ -1858,7 +1854,7 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
         try {
             const url = fileUrl || getCurrentUrl();
             if (!url) {
-                throw new Error("No Figma file URL provided. Either pass fileUrl parameter or call figma_navigate first.");
+                throw new Error("No Figma file URL available. Pass the fileUrl parameter, call figma_navigate (CDP mode), or ensure the Desktop Bridge plugin is connected (WebSocket mode).");
             }
             const fileKey = extractFileKey(url);
             if (!fileKey) {
@@ -1866,18 +1862,26 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             }
             logger.info({ fileKey, nodeId, format, enrich }, "Fetching component data");
             // PRIORITY 1: Try Desktop Bridge plugin UI first (has reliable description field!)
-            if (getBrowserManager && ensureInitialized) {
+            if (getDesktopConnector || (getBrowserManager && ensureInitialized)) {
                 try {
                     logger.info({ nodeId }, "Attempting to get component via Desktop Bridge plugin UI");
-                    await ensureInitialized();
-                    const browserManager = getBrowserManager();
-                    if (!browserManager) {
-                        throw new Error("Browser manager not available after initialization");
+                    let connector;
+                    if (getDesktopConnector) {
+                        connector = await getDesktopConnector();
+                    }
+                    else {
+                        // Fallback: direct CDP connector (legacy path)
+                        if (ensureInitialized)
+                            await ensureInitialized();
+                        const browserManager = getBrowserManager?.();
+                        if (!browserManager) {
+                            throw new Error("Browser manager not available after initialization");
+                        }
+                        const { FigmaDesktopConnector } = await import('./figma-desktop-connector.js');
+                        const page = await browserManager.getPage();
+                        connector = new FigmaDesktopConnector(page);
+                        await connector.initialize();
                     }
-                    const { FigmaDesktopConnector } = await import('./figma-desktop-connector.js');
-                    const page = await browserManager.getPage();
-                    const connector = new FigmaDesktopConnector(page);
-                    await connector.initialize();
                     const desktopResult = await connector.getComponentFromPluginUI(nodeId);
                     if (desktopResult.success && desktopResult.component) {
                         logger.info({
@@ -1969,7 +1973,7 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             catch (apiError) {
                 const errorMessage = apiError instanceof Error ? apiError.message : String(apiError);
                 throw new Error(`Cannot retrieve component data. Both Desktop Bridge and REST API are unavailable.\n` +
-                    `Desktop Bridge: ${getBrowserManager && ensureInitialized ? 'Failed (see logs above)' : 'Not available (local mode only)'}\n` +
+                    `Desktop Bridge: ${getDesktopConnector || (getBrowserManager && ensureInitialized) ? 'Failed (see logs above)' : 'Not available (local mode only)'}\n` +
                     `REST API: ${errorMessage}\n\n` +
                     `To fix:\n` +
                     `1. Local mode: Set FIGMA_ACCESS_TOKEN environment variable, OR ensure Figma Desktop Bridge plugin is running\n` +
@@ -2073,7 +2077,7 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             .string()
             .url()
             .optional()
-            .describe("Figma file URL (e.g., https://figma.com/design/abc123). REQUIRED unless figma_navigate was already called. If not provided, ask the user to share their Figma file URL (they can copy it from Figma Desktop via right-click → 'Copy link')."),
+            .describe("Figma file URL (e.g., https://figma.com/design/abc123). Auto-detected from CDP browser or WebSocket Desktop Bridge connection. Only required if neither is connected."),
         verbosity: z
             .enum(["summary", "standard", "full"])
             .optional()
@@ -2111,7 +2115,7 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             }
             const url = fileUrl || getCurrentUrl();
             if (!url) {
-                throw new Error("No Figma file URL provided. Either pass fileUrl parameter or call figma_navigate first.");
+                throw new Error("No Figma file URL available. Pass the fileUrl parameter, call figma_navigate (CDP mode), or ensure the Desktop Bridge plugin is connected (WebSocket mode).");
             }
             const fileKey = extractFileKey(url);
             if (!fileKey) {
@@ -2218,7 +2222,7 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             .string()
             .url()
             .optional()
-            .describe("Figma file URL (e.g., https://figma.com/design/abc123). REQUIRED unless figma_navigate was already called. If not provided, ask the user to share their Figma file URL (they can copy it from Figma Desktop via right-click → 'Copy link')."),
+            .describe("Figma file URL (e.g., https://figma.com/design/abc123). Auto-detected from CDP browser or WebSocket Desktop Bridge connection. Only required if neither is connected."),
         nodeId: z
             .string()
             .describe("Component node ID to render as image (e.g., '695:313')"),
@@ -2252,7 +2256,7 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             }
             const url = fileUrl || getCurrentUrl();
             if (!url) {
-                throw new Error("No Figma file URL provided. Either pass fileUrl parameter or call figma_navigate first.");
+                throw new Error("No Figma file URL available. Pass the fileUrl parameter, call figma_navigate (CDP mode), or ensure the Desktop Bridge plugin is connected (WebSocket mode).");
             }
             const fileKey = extractFileKey(url);
             if (!fileKey) {
@@ -2260,8 +2264,8 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             }
             logger.info({ fileKey, nodeId, scale, format }, "Rendering component image");
             // First, fetch the node to check if it's a COMPONENT_SET
-            const fileData = await api.getFile(fileKey, { ids: [nodeId] });
-            const node = fileData.nodes[nodeId]?.document;
+            const fileData = await api.getNodes(fileKey, [nodeId]);
+            const node = fileData.nodes?.[nodeId]?.document;
             if (!node) {
                 throw new Error(`Node ${nodeId} not found in file ${fileKey}. Please verify the node ID is correct.`);
             }
@@ -2367,7 +2371,7 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             }
             const url = fileUrl || getCurrentUrl();
             if (!url) {
-                throw new Error("No Figma file URL provided. Either pass fileUrl parameter or call figma_navigate first.");
+                throw new Error("No Figma file URL available. Pass the fileUrl parameter, call figma_navigate (CDP mode), or ensure the Desktop Bridge plugin is connected (WebSocket mode).");
             }
             const fileKey = extractFileKey(url);
             if (!fileKey) {
@@ -2577,7 +2581,7 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             }
             const url = fileUrl || getCurrentUrl();
             if (!url) {
-                throw new Error("No Figma file URL provided. Either pass fileUrl parameter or call figma_navigate first.");
+                throw new Error("No Figma file URL available. Pass the fileUrl parameter, call figma_navigate (CDP mode), or ensure the Desktop Bridge plugin is connected (WebSocket mode).");
             }
             const fileKey = extractFileKey(url);
             if (!fileKey) {
@@ -2752,33 +2756,43 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             .describe("Scale factor (default: 2 for 2x resolution)"),
     }, async ({ nodeId, format, scale }) => {
         try {
-            // Check for Desktop Bridge connection
-            const browserManager = getBrowserManager?.();
-            if (!browserManager) {
-                throw new Error("Desktop Bridge not available. To capture screenshots:\n" +
-                    "1. Open your Figma file in Figma Desktop\n" +
-                    "2. Install and run the 'Figma Console MCP' plugin\n" +
-                    "3. Ensure the plugin shows 'MCP ready' status");
-            }
-            // Ensure browser is initialized
-            if (ensureInitialized) {
-                await ensureInitialized();
-            }
-            const page = await browserManager.getPage();
             logger.info({ nodeId, format, scale }, "Capturing screenshot via Desktop Bridge");
-            // Find the plugin UI frame and call the captureScreenshot function
-            const frames = page.frames();
             let result = null;
-            for (const frame of frames) {
-                try {
-                    const hasFunction = await frame.evaluate('typeof window.captureScreenshot === "function"');
-                    if (hasFunction) {
-                        result = await frame.evaluate(`window.captureScreenshot(${JSON.stringify(nodeId)}, ${JSON.stringify({ format, scale })})`);
-                        break;
-                    }
+            // Use the connector abstraction (supports both CDP and WebSocket)
+            if (getDesktopConnector) {
+                const connector = await getDesktopConnector();
+                logger.info({ transport: connector.getTransportType?.() || 'unknown' }, "Screenshot via connector");
+                result = await connector.captureScreenshot(nodeId || '', { format, scale });
+                // Wrap in expected format only if connector returns raw data without a success flag
+                if (result && typeof result.success === 'undefined' && result.image) {
+                    result = { success: true, image: result };
+                }
+            }
+            // Legacy CDP fallback (only when no connector factory is available)
+            if (!result && !getDesktopConnector) {
+                const browserManager = getBrowserManager?.();
+                if (!browserManager) {
+                    throw new Error("Desktop Bridge not available. To capture screenshots:\n" +
+                        "1. Open your Figma file in Figma Desktop\n" +
+                        "2. Install and run the 'Figma Console MCP' plugin\n" +
+                        "3. Ensure the plugin shows 'MCP ready' status");
                 }
-                catch {
-                    continue;
+                if (ensureInitialized) {
+                    await ensureInitialized();
+                }
+                const page = await browserManager.getPage();
+                const frames = page.frames();
+                for (const frame of frames) {
+                    try {
+                        const hasFunction = await frame.evaluate('typeof window.captureScreenshot === "function"');
+                        if (hasFunction) {
+                            result = await frame.evaluate(`window.captureScreenshot(${JSON.stringify(nodeId || '')}, ${JSON.stringify({ format, scale })})`);
+                            break;
+                        }
+                    }
+                    catch {
+                        continue;
+                    }
                 }
             }
             if (!result) {
@@ -2850,33 +2864,39 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, getCon
             "The tool automatically handles the #nodeId suffix for TEXT/BOOLEAN/INSTANCE_SWAP properties."),
     }, async ({ nodeId, properties }) => {
         try {
-            // Check for Desktop Bridge connection
-            const browserManager = getBrowserManager?.();
-            if (!browserManager) {
-                throw new Error("Desktop Bridge not available. To set instance properties:\n" +
-                    "1. Open your Figma file in Figma Desktop\n" +
-                    "2. Install and run the 'Figma Console MCP' plugin\n" +
-                    "3. Ensure the plugin shows 'MCP ready' status");
-            }
-            // Ensure browser is initialized
-            if (ensureInitialized) {
-                await ensureInitialized();
-            }
-            const page = await browserManager.getPage();
             logger.info({ nodeId, properties: Object.keys(properties) }, "Setting instance properties via Desktop Bridge");
-            // Find the plugin UI frame and call the setInstanceProperties function
-            const frames = page.frames();
             let result = null;
-            for (const frame of frames) {
-                try {
-                    const hasFunction = await frame.evaluate('typeof window.setInstanceProperties === "function"');
-                    if (hasFunction) {
-                        result = await frame.evaluate(`window.setInstanceProperties(${JSON.stringify(nodeId)}, ${JSON.stringify(properties)})`);
-                        break;
-                    }
+            // Use the connector abstraction (supports both CDP and WebSocket)
+            if (getDesktopConnector) {
+                const connector = await getDesktopConnector();
+                logger.info({ transport: connector.getTransportType?.() || 'unknown' }, "Instance properties via connector");
+                result = await connector.setInstanceProperties(nodeId, properties);
+            }
+            // Legacy CDP fallback (only when no connector factory is available)
+            if (!result && !getDesktopConnector) {
+                const browserManager = getBrowserManager?.();
+                if (!browserManager) {
+                    throw new Error("Desktop Bridge not available. To set instance properties:\n" +
+                        "1. Open your Figma file in Figma Desktop\n" +
+                        "2. Install and run the 'Figma Console MCP' plugin\n" +
+                        "3. Ensure the plugin shows 'MCP ready' status");
+                }
+                if (ensureInitialized) {
+                    await ensureInitialized();
                 }
-                catch {
-                    continue;
+                const page = await browserManager.getPage();
+                const frames = page.frames();
+                for (const frame of frames) {
+                    try {
+                        const hasFunction = await frame.evaluate('typeof window.setInstanceProperties === "function"');
+                        if (hasFunction) {
+                            result = await frame.evaluate(`window.setInstanceProperties(${JSON.stringify(nodeId)}, ${JSON.stringify(properties)})`);
+                            break;
+                        }
+                    }
+                    catch {
+                        continue;
+                    }
                 }
             }
             if (!result) {