@mp3wizard/figma-console-mcp 1.15.3 → 1.15.4

package/README.md

@@ -758,28 +758,6 @@ The architecture supports adding new apps with minimal boilerplate — each app
 
 ---
 
-## 🔒 Security
-
-This repository has undergone **two security reviews** — most recently on 2026-03-18 (v1.14.0).
-
-### What Was Reviewed
-
-- Authentication & token handling
-- Input validation and sanitization
-- Rate limiting and abuse prevention
-- Error message exposure
-- Dependency vulnerabilities
-- Secrets management
-
-### Review Outcome
-
-All identified security findings have been addressed and patched in this fork. No sensitive credentials are exposed, and error messages have been sanitized to prevent information leakage.
-
-📄 **Latest report:** [SECURITY-REVIEW-2026-03-18.md](Security%20review%20report/SECURITY-REVIEW-2026-03-18.md)
-📄 **Previous report:** [SECURITY-REVIEW-2026-03-16.md](Security%20review%20report/SECURITY-REVIEW-2026-03-16.md)
-
----
-
 ## 💻 Development
 
 ```bash

package/dist/cloudflare/core/cloud-websocket-relay.js

@@ -164,7 +164,6 @@ export class PluginRelayDO extends DurableObject {
         }
         const body = await request.json();
         const { method, params = {}, timeoutMs = 15000 } = body;
-        const safeTimeout = Math.min(Math.max(timeoutMs, 1000), 60000); // clamp 1s–60s
         const id = `relay_${++this.requestIdCounter}_${Date.now()}`;
         // Send command to plugin
         try {
@@ -178,9 +177,9 @@ export class PluginRelayDO extends DurableObject {
             const timeoutId = setTimeout(() => {
                 if (this.pendingRequests.has(id)) {
                     this.pendingRequests.delete(id);
-                    resolve(new Response(JSON.stringify({ error: `Command ${method} timed out after ${safeTimeout}ms` }), { status: 504, headers: { 'Content-Type': 'application/json' } }));
+                    resolve(new Response(JSON.stringify({ error: `Command ${method} timed out after ${timeoutMs}ms` }), { status: 504, headers: { 'Content-Type': 'application/json' } }));
                 }
-            }, safeTimeout);
+            }, timeoutMs);
             this.pendingRequests.set(id, { resolve, reject: () => { }, timeoutId });
         });
     }

package/dist/cloudflare/core/config.js

@@ -30,7 +30,7 @@ const DEFAULT_CONFIG = {
         args: [
             '--disable-blink-features=AutomationControlled',
             '--disable-dev-shm-usage',
-            // '--no-sandbox' removed from defaults; enable via config file if required by your environment
+            '--no-sandbox', // Note: Only use in trusted environments
         ],
     },
     console: {

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

@@ -94,12 +94,16 @@ export class FigmaAPI {
         // OAuth tokens start with 'figu_' and require Authorization: Bearer header
         // Personal Access Tokens use X-Figma-Token header
         const isOAuthToken = this.accessToken.startsWith('figu_');
-        logger.debug({
+        // Debug logging to verify token is being used
+        const tokenPreview = this.accessToken ? `${this.accessToken.substring(0, 10)}...` : 'NO TOKEN';
+        logger.info({
             url,
+            tokenPreview,
             hasToken: !!this.accessToken,
+            tokenLength: this.accessToken?.length,
             isOAuthToken,
             authMethod: isOAuthToken ? 'Bearer' : 'X-Figma-Token'
-        }, 'Making Figma API request');
+        }, 'Making Figma API request with token');
         const headers = {
             'Content-Type': 'application/json',
             ...(options.headers || {}),

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

@@ -429,8 +429,7 @@ export class FigmaDesktopConnector {
         } catch (error) {
           return {
             success: false,
-            error: error.message,
-            stack: error.stack
+            error: error.message
           };
         }
       })()

package/dist/cloudflare/core/port-discovery.js

@@ -80,7 +80,7 @@ export function advertisePort(port, host = 'localhost') {
     };
     const filePath = getPortFilePath(port);
     try {
-        writeFileSync(filePath, JSON.stringify(data, null, 2), { mode: 0o600 });
+        writeFileSync(filePath, JSON.stringify(data, null, 2));
         logger.info({ port, filePath }, 'Port advertised');
     }
     catch (error) {
@@ -103,7 +103,7 @@ export function refreshPortAdvertisement(port) {
         if (data.pid !== process.pid)
             return;
         data.lastSeen = new Date().toISOString();
-        writeFileSync(filePath, JSON.stringify(data, null, 2), { mode: 0o600 });
+        writeFileSync(filePath, JSON.stringify(data, null, 2));
     }
     catch {
         // Best-effort — heartbeat failures are non-fatal
@@ -265,6 +265,77 @@ export function cleanupStalePortFiles() {
     }
     return cleaned;
 }
+/**
+ * Deep scan for orphaned MCP server processes that hold ports but have no port files.
+ * These are processes left behind by Claude Desktop when tabs close without proper cleanup.
+ *
+ * Uses lsof (macOS/Linux) to find PIDs listening on each port in the range,
+ * then verifies they're figma-console-mcp before terminating.
+ *
+ * Call AFTER cleanupStalePortFiles() — that handles the port-file-based cleanup first,
+ * then this catches any remaining ghosts.
+ */
+export function cleanupOrphanedProcesses(preferredPort = DEFAULT_WS_PORT) {
+    // Only supported on macOS/Linux (lsof)
+    if (process.platform === 'win32')
+        return 0;
+    let cleaned = 0;
+    const myPid = process.pid;
+    const ports = getPortRange(preferredPort);
+    // Collect PIDs that have valid port files (known-good servers)
+    const knownPids = new Set();
+    for (const port of ports) {
+        const data = readPortFile(port);
+        if (data)
+            knownPids.add(data.pid);
+    }
+    knownPids.add(myPid); // Never kill ourselves
+    for (const port of ports) {
+        try {
+            // Find PIDs listening on this port via lsof
+            const { execSync } = require('child_process');
+            const output = execSync(`lsof -i :${port} -sTCP:LISTEN -t 2>/dev/null`, {
+                encoding: 'utf-8',
+                timeout: 3000,
+            }).trim();
+            if (!output)
+                continue;
+            const pids = output.split('\n').map(Number).filter(Boolean);
+            for (const pid of pids) {
+                if (knownPids.has(pid))
+                    continue; // Skip known-good servers
+                // Verify this is actually a figma-console-mcp process before killing
+                try {
+                    const cmdline = execSync(`ps -p ${pid} -o command= 2>/dev/null`, {
+                        encoding: 'utf-8',
+                        timeout: 2000,
+                    }).trim();
+                    if (cmdline.includes('figma-console-mcp') || cmdline.includes('figma_console_mcp') || cmdline.includes('local.js')) {
+                        logger.info({ port, pid, command: cmdline.substring(0, 120) }, 'Terminating orphaned MCP server (no port file, holding port)');
+                        terminateProcess(pid);
+                        cleaned++;
+                    }
+                }
+                catch {
+                    // Can't read process info — skip to be safe
+                }
+            }
+        }
+        catch {
+            // lsof failed for this port — skip
+        }
+    }
+    if (cleaned > 0) {
+        // Give terminated processes a moment to release their ports
+        try {
+            const { execSync } = require('child_process');
+            execSync('sleep 0.5', { timeout: 2000 });
+        }
+        catch { /* non-critical */ }
+        logger.info({ cleaned }, `Cleaned up ${cleaned} orphaned MCP server process(es)`);
+    }
+    return cleaned;
+}
 /**
  * Register process exit handlers to clean up port advertisement file.
  * Should be called once after the port is successfully bound.

package/dist/cloudflare/core/websocket-server.js

@@ -14,7 +14,8 @@
  */
 import { WebSocketServer as WSServer, WebSocket } from 'ws';
 import { EventEmitter } from 'events';
-import { readFileSync } from 'fs';
+import { createServer as createHttpServer } from 'http';
+import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import { createChildLogger } from './logger.js';
 // Read version from package.json
@@ -27,11 +28,37 @@ try {
 catch {
     // Non-critical — version will show as 0.0.0
 }
+/**
+ * Load the full plugin UI HTML content that gets served to the bootloader.
+ * Falls back to a minimal error page if the file isn't found.
+ */
+function loadPluginUIContent() {
+    const candidates = [
+        // ESM runtime: dist/core/ → ../../figma-desktop-bridge/
+        typeof __dirname !== 'undefined'
+            ? join(__dirname, '..', '..', 'figma-desktop-bridge', 'ui-full.html')
+            : join(process.cwd(), 'figma-desktop-bridge', 'ui-full.html'),
+        // Direct from project root
+        join(process.cwd(), 'figma-desktop-bridge', 'ui-full.html'),
+    ];
+    for (const path of candidates) {
+        try {
+            if (existsSync(path)) {
+                return readFileSync(path, 'utf-8');
+            }
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return '<html><body><p>Plugin UI not found. Please reinstall figma-console-mcp.</p></body></html>';
+}
 const logger = createChildLogger({ component: 'websocket-server' });
 export class FigmaWebSocketServer extends EventEmitter {
     constructor(options) {
         super();
         this.wss = null;
+        this.httpServer = null;
         /** Named clients indexed by fileKey — each represents a connected Figma file */
         this.clients = new Map();
         /** Clients awaiting FILE_INFO identification, mapped to their pending timeout */
@@ -44,21 +71,75 @@ export class FigmaWebSocketServer extends EventEmitter {
         this._startedAt = Date.now();
         this.consoleBufferSize = 1000;
         this.documentChangeBufferSize = 200;
+        /** Cached plugin UI HTML content — loaded once and served to bootloader requests */
+        this._pluginUIContent = null;
         this.options = options;
         this._startedAt = Date.now();
     }
     /**
-     * Start the WebSocket server
+     * Handle HTTP requests on the same port as WebSocket.
+     * Serves plugin UI content for the bootloader and health checks.
+     */
+    handleHttpRequest(req, res) {
+        // CORS headers for Figma plugin iframe (sandboxed, origin: null)
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        const url = req.url || '/';
+        // Plugin UI endpoint — bootloader redirects here
+        if (url === '/plugin/ui' || url === '/plugin/ui/') {
+            if (!this._pluginUIContent) {
+                this._pluginUIContent = loadPluginUIContent();
+            }
+            res.writeHead(200, {
+                'Content-Type': 'text/html; charset=utf-8',
+                'Cache-Control': 'no-cache, no-store, must-revalidate',
+            });
+            res.end(this._pluginUIContent);
+            return;
+        }
+        // Health/version endpoint
+        if (url === '/health' || url === '/') {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                status: 'ok',
+                version: SERVER_VERSION,
+                clients: this.clients.size,
+                uptime: Math.floor((Date.now() - this._startedAt) / 1000),
+            }));
+            return;
+        }
+        // 404 for anything else
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        res.end('Not Found');
+    }
+    /**
+     * Start the HTTP + WebSocket server.
+     * HTTP serves the plugin UI content; WebSocket handles plugin communication.
      */
     async start() {
         if (this._isStarted)
             return;
         return new Promise((resolve, reject) => {
+            let rejected = false;
+            const rejectOnce = (error) => {
+                if (!rejected) {
+                    rejected = true;
+                    reject(error);
+                }
+            };
             try {
+                // Create HTTP server first — handles plugin UI requests
+                this.httpServer = createHttpServer((req, res) => this.handleHttpRequest(req, res));
+                // Attach WebSocket server to the HTTP server (shares the same port)
                 this.wss = new WSServer({
-                    port: this.options.port,
-                    host: this.options.host || 'localhost',
-                    maxPayload: 25 * 1024 * 1024, // 25MB — sufficient for screenshots; set FIGMA_WS_MAX_PAYLOAD_MB env var to override
+                    server: this.httpServer,
+                    maxPayload: 100 * 1024 * 1024, // 100MB — screenshots and large component data can be big
                     verifyClient: (info, callback) => {
                         // Mitigate Cross-Site WebSocket Hijacking (CSWSH):
                         // Reject connections from unexpected browser origins.
@@ -76,18 +157,38 @@ export class FigmaWebSocketServer extends EventEmitter {
                         }
                     },
                 });
-                this.wss.on('listening', () => {
-                    this._isStarted = true;
-                    logger.info({ port: this.options.port, host: this.options.host || 'localhost' }, 'WebSocket bridge server started');
-                    resolve();
-                });
-                this.wss.on('error', (error) => {
+                // Error handler for startup failures (EADDRINUSE, etc.)
+                // Must be on BOTH httpServer and wss — the WSS re-emits HTTP server errors
+                // and throws if no listener is attached.
+                const onStartupError = (error) => {
                     if (!this._isStarted) {
-                        reject(error);
+                        try {
+                            if (this.wss) {
+                                this.wss.close();
+                                this.wss = null;
+                            }
+                        }
+                        catch { /* ignore */ }
+                        try {
+                            if (this.httpServer) {
+                                this.httpServer.close();
+                                this.httpServer = null;
+                            }
+                        }
+                        catch { /* ignore */ }
+                        rejectOnce(error);
                     }
                     else {
-                        logger.error({ error }, 'WebSocket server error');
+                        logger.error({ error }, 'HTTP/WebSocket server error');
                     }
+                };
+                this.httpServer.on('error', onStartupError);
+                this.wss.on('error', onStartupError);
+                // Start listening on the HTTP server (which also handles WS upgrades)
+                this.httpServer.listen(this.options.port, this.options.host || 'localhost', () => {
+                    this._isStarted = true;
+                    logger.info({ port: this.options.port, host: this.options.host || 'localhost' }, 'WebSocket bridge server started (with HTTP plugin UI endpoint)');
+                    resolve();
                 });
                 this.wss.on('connection', (ws) => {
                     // Add to pending until FILE_INFO identifies the file
@@ -146,7 +247,7 @@ export class FigmaWebSocketServer extends EventEmitter {
                 });
             }
             catch (error) {
-                reject(error);
+                rejectOnce(error);
             }
         });
     }
@@ -177,6 +278,22 @@ export class FigmaWebSocketServer extends EventEmitter {
             }
             return;
         }
+        // Bootloader request: send the full plugin UI HTML
+        if (message.type === 'GET_PLUGIN_UI') {
+            if (!this._pluginUIContent) {
+                this._pluginUIContent = loadPluginUIContent();
+            }
+            try {
+                ws.send(JSON.stringify({
+                    type: 'PLUGIN_UI_CONTENT',
+                    html: this._pluginUIContent,
+                }));
+            }
+            catch {
+                // Non-critical — bootloader will show error
+            }
+            return;
+        }
         // Unsolicited data from plugin (FILE_INFO, events, forwarded data)
         if (message.type) {
             // FILE_INFO promotes pending clients to named clients
@@ -434,11 +551,19 @@ export class FigmaWebSocketServer extends EventEmitter {
      * Returns the actual port — critical when using port 0 for OS-assigned ports.
      */
     address() {
+        // Use the HTTP server's address (which is the actual listening socket)
+        if (this.httpServer) {
+            const addr = this.httpServer.address();
+            if (typeof addr === 'string' || !addr)
+                return null;
+            return addr;
+        }
+        // Fallback for backward compat
         if (!this.wss)
             return null;
         const addr = this.wss.address();
         if (typeof addr === 'string')
-            return null; // Unix socket path, not applicable
+            return null;
         return addr;
     }
     // ============================================================================
@@ -632,15 +757,20 @@ export class FigmaWebSocketServer extends EventEmitter {
         }
         this.clients.clear();
         this._activeFileKey = null;
+        // Close WS server first (handles WebSocket connections)
         if (this.wss) {
-            return new Promise((resolve) => {
-                this.wss.close(() => {
-                    this._isStarted = false;
-                    logger.info('WebSocket bridge server stopped');
-                    resolve();
-                });
+            await new Promise((resolve) => {
+                this.wss.close(() => resolve());
+            });
+        }
+        // Then close HTTP server (releases the port)
+        if (this.httpServer) {
+            await new Promise((resolve) => {
+                this.httpServer.close(() => resolve());
             });
+            this.httpServer = null;
         }
         this._isStarted = false;
+        logger.info('WebSocket bridge server stopped');
     }
 }

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

@@ -17,7 +17,15 @@ export function registerWriteTools(server, getDesktopConnector) {
 
 **VALIDATION:** After creating/modifying visuals: screenshot with figma_capture_screenshot, check alignment/spacing/proportions, iterate up to 3x.
 
-**PLACEMENT:** Always create components inside a Section or Frame, never on blank canvas. Use parent.insertChild(0, bg) for z-ordering backgrounds behind content.`, {
+**PLACEMENT:** Always create components inside a Section or Frame, never on blank canvas. Use parent.insertChild(0, bg) for z-ordering backgrounds behind content.
+
+**HOUSEKEEPING (MANDATORY):**
+Before creating: screenshot the target page to see existing content and find clear space.
+When creating: place inside a named Section, positioned BELOW or AWAY from existing content. Never overlap.
+After creating: screenshot to verify clean placement and no overlaps.
+On failure/retry: DELETE any partial artifacts (empty frames, orphaned layers, blank pages) before retrying. Use node.remove() to clean up.
+Pages: NEVER create a new page if one with that name already exists — use the existing one. If you created a blank page during a failed attempt, delete it.
+Layers: If your code creates helper frames, placeholder nodes, or intermediate layers that aren't part of the final result, remove them.`, {
         code: z
             .string()
             .describe("JavaScript code to execute. Has access to the 'figma' global object. " +
@@ -1476,7 +1484,7 @@ After instantiating components, use figma_take_screenshot to verify the result l
         }
     });
     // Tool: Create Child Node
-    server.tool("figma_create_child", "Create a new child node inside a parent container. Useful for adding shapes, text, or frames to existing structures.", {
+    server.tool("figma_create_child", "Create a new child node inside a parent container. Always place inside an existing Section or Frame — never on a bare page. If no suitable parent exists, create a Section first. Clean up any empty or orphaned nodes if the operation fails.", {
         parentId: z.string().describe("The parent node ID"),
         nodeType: z
             .enum(["RECTANGLE", "ELLIPSE", "FRAME", "TEXT", "LINE"])