@mp3wizard/figma-console-mcp 1.14.0 → 1.15.2

package/dist/local.js

@@ -16,8 +16,9 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
 import { fileURLToPath } from "url";
-import { dirname, resolve } from "path";
-import { realpathSync, existsSync, readFileSync } from "fs";
+import { dirname, resolve, join } from "path";
+import { realpathSync, existsSync, readFileSync, mkdirSync, copyFileSync, writeFileSync } from "fs";
+import { homedir } from "os";
 import { LocalBrowserManager } from "./browser/local.js";
 import { ConsoleMonitor } from "./core/console-monitor.js";
 import { getConfig } from "./core/config.js";
@@ -30,10 +31,40 @@ import { registerDesignSystemTools } from "./core/design-system-tools.js";
 import { FigmaDesktopConnector } from "./core/figma-desktop-connector.js";
 import { FigmaWebSocketServer } from "./core/websocket-server.js";
 import { WebSocketConnector } from "./core/websocket-connector.js";
-import { DEFAULT_WS_PORT, getPortRange, advertisePort, unadvertisePort, registerPortCleanup, discoverActiveInstances, cleanupStalePortFiles, refreshPortAdvertisement, HEARTBEAT_INTERVAL_MS, } from "./core/port-discovery.js";
+import { DEFAULT_WS_PORT, getPortRange, advertisePort, unadvertisePort, registerPortCleanup, discoverActiveInstances, cleanupStalePortFiles, cleanupOrphanedProcesses, refreshPortAdvertisement, HEARTBEAT_INTERVAL_MS, } from "./core/port-discovery.js";
 import { registerTokenBrowserApp } from "./apps/token-browser/server.js";
 import { registerDesignSystemDashboardApp } from "./apps/design-system-dashboard/server.js";
 const logger = createChildLogger({ component: "local-server" });
+/**
+ * Copy plugin files to a stable directory (~/.figma-console-mcp/plugin/).
+ * This gives users a permanent, predictable path to import from instead of
+ * the volatile npx cache path that changes between updates.
+ *
+ * Returns the stable manifest path, or null if copy failed.
+ */
+function setupStablePluginDir(sourcePluginDir) {
+    try {
+        const stableDir = join(homedir(), ".figma-console-mcp", "plugin");
+        mkdirSync(stableDir, { recursive: true });
+        const filesToCopy = ["manifest.json", "code.js", "ui.html", "ui-full.html"];
+        for (const file of filesToCopy) {
+            const src = join(sourcePluginDir, file);
+            const dest = join(stableDir, file);
+            if (existsSync(src)) {
+                copyFileSync(src, dest);
+            }
+        }
+        // Write a version marker so we can detect stale copies
+        const pkg = JSON.parse(readFileSync(join(sourcePluginDir, "..", "package.json"), "utf-8"));
+        writeFileSync(join(stableDir, ".version"), pkg.version, "utf-8");
+        logger.info({ stableDir }, "Plugin files copied to stable directory");
+        return join(stableDir, "manifest.json");
+    }
+    catch (error) {
+        logger.warn({ error }, "Could not set up stable plugin directory (non-critical)");
+        return null;
+    }
+}
 /**
  * Local MCP Server
  * Connects to Figma Desktop and provides identical tools to Cloudflare mode
@@ -56,6 +87,8 @@ class LocalFigmaConsoleMCP {
         // In-memory cache for variables data to avoid MCP token limits
         // Maps fileKey -> {data, timestamp}
         this.variablesCache = new Map();
+        /** Stable plugin directory path (set during startup) */
+        this.stablePluginPath = null;
         this.server = new McpServer({
             name: "Figma Console MCP (Local)",
             version: "0.1.0",
@@ -226,9 +259,13 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
     }
     /**
      * Resolve the path to the Desktop Bridge plugin manifest.
-     * Works for both NPX installs (buried in npm cache) and local git clones.
+     * Prefers the stable directory (~/.figma-console-mcp/plugin/) over the npx cache path.
      */
     getPluginPath() {
+        // Prefer stable path — consistent across npx updates
+        if (this.stablePluginPath && existsSync(this.stablePluginPath)) {
+            return this.stablePluginPath;
+        }
         try {
             const thisFile = fileURLToPath(import.meta.url);
             // From dist/local.js → go up to package root, then into figma-desktop-bridge
@@ -1466,7 +1503,15 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
 
 **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. " +
@@ -1483,23 +1528,73 @@ If Design Systems Assistant MCP is not available, install it from: https://githu
                 try {
                     const connector = await this.getDesktopConnector();
                     const result = await connector.executeCodeViaUI(code, Math.min(timeout, 30000));
+                    // Post-execution audit: detect common housekeeping issues
+                    // Runs automatically when the code creates pages, components, or frames
+                    const createsContent = /createPage|createComponent|createFrame|createSection|createRectangle|createEllipse/.test(code);
+                    let housekeepingWarnings = [];
+                    if (createsContent && result.success) {
+                        try {
+                            const auditResult = await connector.executeCodeViaUI(`
+									var warnings = [];
+									var pages = figma.root.children;
+									// Check for duplicate page names
+									var pageNames = {};
+									for (var i = 0; i < pages.length; i++) {
+										var name = pages[i].name;
+										if (pageNames[name]) pageNames[name]++;
+										else pageNames[name] = 1;
+									}
+									for (var name in pageNames) {
+										if (pageNames[name] > 1) warnings.push('DUPLICATE_PAGE: ' + pageNames[name] + ' pages named "' + name + '" — delete the empty duplicate');
+									}
+									// Check for empty pages (likely from failed attempts)
+									for (var i = 0; i < pages.length; i++) {
+										if (pages[i].children.length === 0 && pages[i].name !== '---') {
+											warnings.push('EMPTY_PAGE: "' + pages[i].name + '" has no content — delete if unintended');
+										}
+									}
+									// Check for nodes placed directly on page (not in section/frame)
+									var currentPage = figma.currentPage;
+									var floatingNodes = 0;
+									for (var i = 0; i < currentPage.children.length; i++) {
+										var child = currentPage.children[i];
+										if (child.type === 'COMPONENT' || child.type === 'FRAME' || child.type === 'RECTANGLE') {
+											if (currentPage.children.length > 1 && child.type !== 'SECTION') floatingNodes++;
+										}
+									}
+									if (floatingNodes > 3) warnings.push('FLOATING_NODES: ' + floatingNodes + ' nodes placed directly on the page canvas — consider grouping inside a Section');
+									return warnings;
+								`, 5000);
+                            if (auditResult.success && Array.isArray(auditResult.result) && auditResult.result.length > 0) {
+                                housekeepingWarnings = auditResult.result;
+                            }
+                        }
+                        catch {
+                            // Audit is best-effort — don't fail the main operation
+                        }
+                    }
+                    const response = {
+                        success: result.success,
+                        result: result.result,
+                        error: result.error,
+                        resultAnalysis: result.resultAnalysis,
+                        fileContext: result.fileContext,
+                        timestamp: Date.now(),
+                        ...(attempt > 0
+                            ? { reconnected: true, attempts: attempt + 1 }
+                            : {}),
+                    };
+                    if (housekeepingWarnings.length > 0) {
+                        response.housekeeping = {
+                            warnings: housekeepingWarnings,
+                            ai_instruction: "CLEANUP REQUIRED: The warnings above indicate housekeeping issues from your recent operation. Fix these NOW before proceeding — delete empty/duplicate pages, remove orphaned nodes, and move floating content into Sections.",
+                        };
+                    }
                     return {
                         content: [
                             {
                                 type: "text",
-                                text: JSON.stringify({
-                                    success: result.success,
-                                    result: result.result,
-                                    error: result.error,
-                                    // Include resultAnalysis for silent failure detection
-                                    resultAnalysis: result.resultAnalysis,
-                                    // Include file context so users know which file was queried
-                                    fileContext: result.fileContext,
-                                    timestamp: Date.now(),
-                                    ...(attempt > 0
-                                        ? { reconnected: true, attempts: attempt + 1 }
-                                        : {}),
-                                }),
+                                text: JSON.stringify(response),
                             },
                         ],
                     };
@@ -3934,7 +4029,7 @@ After instantiating components, use figma_take_screenshot to verify the result l
             }
         });
         // Tool: Create Child Node
-        this.server.tool("figma_create_child", "Create a new child node inside a parent container. Useful for adding shapes, text, or frames to existing structures.", {
+        this.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"])
@@ -4858,13 +4953,30 @@ return {
     async start() {
         try {
             logger.info({ config: this.config }, "Starting Figma Console MCP (Local Mode)");
+            // Copy plugin files to stable directory (~/.figma-console-mcp/plugin/)
+            // so users have a permanent import path that survives npx cache changes.
+            try {
+                const thisFile = fileURLToPath(import.meta.url);
+                const packageRoot = dirname(dirname(thisFile));
+                const sourcePluginDir = resolve(packageRoot, "figma-desktop-bridge");
+                if (existsSync(sourcePluginDir)) {
+                    this.stablePluginPath = setupStablePluginDir(sourcePluginDir);
+                }
+            }
+            catch {
+                // Non-critical — stable dir is a convenience feature
+            }
             // Start WebSocket bridge server with port range fallback.
             // If the preferred port is taken (e.g., Claude Desktop Chat tab already bound it),
             // try subsequent ports in the range (9223-9232) so multiple instances can coexist.
             const wsHost = process.env.FIGMA_WS_HOST || 'localhost';
             this.wsPreferredPort = parseInt(process.env.FIGMA_WS_PORT || String(DEFAULT_WS_PORT), 10);
-            // Clean up any stale port files from crashed instances before trying to bind
+            // Clean up stale/orphaned MCP server instances before trying to bind.
+            // Phase 1: Remove stale port files and terminate zombie processes that have port files
             cleanupStalePortFiles();
+            // Phase 2: Deep scan for orphaned processes holding ports WITHOUT port files
+            // (e.g., old instances from before port file tracking, or files already cleaned up)
+            cleanupOrphanedProcesses(this.wsPreferredPort);
             const portsToTry = getPortRange(this.wsPreferredPort);
             let boundPort = null;
             for (const port of portsToTry) {
@@ -5017,10 +5129,23 @@ async function main() {
 const currentFile = fileURLToPath(import.meta.url);
 const entryFile = process.argv[1] ? realpathSync(resolve(process.argv[1])) : "";
 if (currentFile === entryFile) {
-    // Handle --print-path: print the Desktop Bridge manifest path and exit
+    // Handle --print-path: print the Desktop Bridge manifest path and exit.
+    // Copies plugin files to the stable directory and prints that path so users
+    // import the bootloader version (which auto-updates on every launch).
     if (process.argv.includes("--print-path")) {
         const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
-        const manifestPath = resolve(packageRoot, "figma-desktop-bridge", "manifest.json");
+        const sourceDir = resolve(packageRoot, "figma-desktop-bridge");
+        // Ensure stable directory exists with latest files
+        const stablePath = setupStablePluginDir(sourceDir);
+        if (stablePath && existsSync(stablePath)) {
+            console.log(stablePath);
+            console.error("\nImport this manifest in Figma once — the bootloader will\n" +
+                "automatically load the latest UI from the MCP server.\n" +
+                "You won't need to re-import when the server updates.");
+            process.exit(0);
+        }
+        // Fallback to npm package path if stable dir setup failed
+        const manifestPath = resolve(sourceDir, "manifest.json");
         if (existsSync(manifestPath)) {
             console.log(manifestPath);
             process.exit(0);