figma-console-mcp 1.9.1 → 1.10.1

package/README.md

@@ -7,6 +7,8 @@
 
 > **Your design system as an API.** Model Context Protocol server that bridges design and development—giving AI assistants complete access to Figma for **extraction**, **creation**, and **debugging**.
 
+> **🆕 v1.10.0 — Multi-Instance Support:** Run Figma Console MCP in multiple Claude Desktop tabs, CLI terminals, or projects simultaneously. No more port conflicts. [See what's new →](#-multi-instance-support-v1100)
+
 ## What is this?
 
 Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
@@ -71,12 +73,12 @@ Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
 
 **Claude Code (CLI):**
 ```bash
-claude mcp add figma-console -s user -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN_HERE -- npx -y figma-console-mcp@latest
+claude mcp add figma-console -s user -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN_HERE -e ENABLE_MCP_APPS=true -- npx -y figma-console-mcp@latest
 ```
 
 **Cursor / Windsurf / Claude Desktop:**
 
-Add to your MCP config file:
+Add to your MCP config file (see [Where to find your config file](#-where-to-find-your-config-file) below):
 
 ```json
 {
@@ -85,13 +87,31 @@ Add to your MCP config file:
       "command": "npx",
       "args": ["-y", "figma-console-mcp@latest"],
       "env": {
-        "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE"
+        "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE",
+        "ENABLE_MCP_APPS": "true"
       }
     }
   }
 }
 ```
 
+#### 📂 Where to Find Your Config File
+
+If you're not sure where to put the JSON configuration above, here's where each app stores its MCP config:
+
+| App | macOS | Windows |
+|-----|-------|---------|
+| **Claude Desktop** | `~/Library/Application Support/Claude/claude_desktop_config.json` | `%APPDATA%\Claude\claude_desktop_config.json` |
+| **Claude Code (CLI)** | `~/.claude.json` | `%USERPROFILE%\.claude.json` |
+| **Cursor** | `~/.cursor/mcp.json` | `%USERPROFILE%\.cursor\mcp.json` |
+| **Windsurf** | `~/.codeium/windsurf/mcp_config.json` | `%USERPROFILE%\.codeium\windsurf\mcp_config.json` |
+
+> **Tip for designers:** The `~` symbol means your **home folder**. On macOS, that's `/Users/YourName/`. On Windows, it's `C:\Users\YourName\`. You can open these files in any text editor — even TextEdit or Notepad.
+>
+> **Can't find the file?** If it doesn't exist yet, create it. The app will pick it up on its next restart. Make sure the entire file is valid JSON (watch for missing commas or brackets).
+>
+> **Claude Code users:** You can skip manual editing entirely. Just run the `claude mcp add` command above and it handles everything for you.
+
 #### Step 3: Connect to Figma Desktop
 
 **Option A — Desktop Bridge Plugin (Recommended):**
@@ -148,6 +168,8 @@ npm run build:local
 
 #### Configure Your MCP Client
 
+Add to your config file (see [Where to find your config file](#-where-to-find-your-config-file)):
+
 ```json
 {
   "mcpServers": {
@@ -155,7 +177,8 @@ npm run build:local
       "command": "node",
       "args": ["/absolute/path/to/figma-console-mcp/dist/local.js"],
       "env": {
-        "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE"
+        "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE",
+        "ENABLE_MCP_APPS": "true"
       }
     }
   }
@@ -476,7 +499,7 @@ The **Figma Desktop Bridge** plugin is the recommended way to connect Figma to t
 1. Open Figma Desktop (normal launch — no debug flags needed)
 2. Go to **Plugins → Development → Import plugin from manifest...**
 3. Select `figma-desktop-bridge/manifest.json` from the figma-console-mcp directory
-4. Run the plugin in your Figma file — it auto-connects to `ws://localhost:9223`
+4. Run the plugin in your Figma file — it auto-connects via WebSocket (scans ports 9223–9232)
 5. Ask your AI: "Check Figma status" to verify the connection
 
 > **One-time import.** Once imported, the plugin stays in your Development plugins list. Just run it whenever you want to use the MCP.
@@ -508,13 +531,47 @@ The **Figma Desktop Bridge** plugin is the recommended way to connect Figma to t
 **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).
 
 **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`.
+- `FIGMA_WS_PORT` — Override the preferred WebSocket port (default: 9223). The server will fall back through a 10-port range starting from this value if the preferred port is occupied.
 - `FIGMA_WS_HOST` — Override the WebSocket server bind address (default: `localhost`). Set to `0.0.0.0` when running inside Docker so the host machine can reach the MCP server.
 
 **Plugin Limitation:** Only works in Local Mode (NPX or Local Git). Remote SSE mode cannot access it.
 
 ---
 
+## 🔀 Multi-Instance Support (v1.10.0)
+
+Figma Console MCP now supports **multiple simultaneous instances** — perfect for designers and developers who work across multiple projects or use Claude Desktop's Chat and Code tabs at the same time.
+
+### The Problem (Before v1.10.0)
+
+When two processes tried to start the MCP server (e.g., Claude Desktop's Chat tab and Code tab), the second one would crash with `EADDRINUSE` because both competed for port 9223.
+
+### How It Works Now
+
+- The server tries port **9223** first (the default)
+- If that port is already taken, it automatically tries **9224**, then **9225**, and so on up to **9232**
+- The Desktop Bridge plugin in Figma connects to **all** active servers simultaneously
+- Every server instance receives real-time events (selection changes, document changes, console logs)
+- `figma_get_status` shows which port you're on and lists other active instances
+
+### What This Means for You
+
+| Scenario | Before v1.10.0 | Now |
+|----------|----------------|-----|
+| Two Claude Desktop tabs (Chat + Code) | Second tab crashes | Both work independently |
+| Multiple CLI terminals on different projects | Only one can run | All run simultaneously |
+| Claude Desktop + Claude Code CLI | Port conflict | Both coexist |
+
+### Do I Need to Do Anything?
+
+**If you're running a single instance:** Nothing changes. You'll still use port 9223 as before.
+
+**If you want multi-instance:** Re-import the Desktop Bridge plugin in Figma (Plugins → Development → Import plugin from manifest). This updates the plugin to scan all ports and connect to every active server.
+
+> **Note:** The server-side update happens automatically when you update the npm package. Only the plugin needs a one-time re-import to enable multi-connection support.
+
+---
+
 ## 🧩 MCP Apps (Experimental)
 
 Figma Console MCP includes support for **MCP Apps** — rich interactive UI experiences that render directly inside any MCP client that supports the [MCP Apps protocol extension](https://github.com/anthropics/anthropic-cookbook/tree/main/misc/model_context_protocol/ext-apps). Built with the official [`@modelcontextprotocol/ext-apps`](https://www.npmjs.com/package/@modelcontextprotocol/ext-apps) SDK.
@@ -550,20 +607,12 @@ A Lighthouse-style health scorecard that audits your design system across six ca
 
 **Enabling MCP Apps:**
 
-MCP Apps are gated behind an environment variable. Add to your MCP config:
+MCP Apps are enabled by default in the setup configurations above (via `"ENABLE_MCP_APPS": "true"`). If you set up before v1.10.0 and don't have this in your config, add it to your `env` section:
 
 ```json
-{
-  "mcpServers": {
-    "figma-console-local": {
-      "command": "node",
-      "args": ["/path/to/figma-console-mcp/dist/local.js"],
-      "env": {
-        "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE",
-        "ENABLE_MCP_APPS": "true"
-      }
-    }
-  }
+"env": {
+  "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE",
+  "ENABLE_MCP_APPS": "true"
 }
 ```
 
@@ -611,9 +660,11 @@ The architecture supports adding new apps with minimal boilerplate — each app
 
 ## 🛤️ Roadmap
 
-**Current Status:** v1.9.0 (Stable) - Production-ready with WebSocket Bridge, 56+ tools, Comments API, and MCP Apps
+**Current Status:** v1.10.0 (Stable) - Production-ready with multi-instance support, WebSocket Bridge, 56+ tools, Comments API, and MCP Apps
 
 **Recent Releases:**
+- [x] **v1.10.0** - Multi-instance support (dynamic port fallback 9223–9232, multi-connection plugin, instance discovery)
+- [x] **v1.9.0** - Figma Comments tools, improved port conflict detection
 - [x] **v1.8.0** - WebSocket Bridge transport (CDP-free connectivity), real-time selection/document tracking, `figma_get_selection` + `figma_get_design_changes` tools
 - [x] **v1.7.0** - MCP Apps (Token Browser, Design System Dashboard), batch variable operations, design-code parity tools
 - [x] **v1.5.0** - Node manipulation tools, component property management, component set arrangement

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

@@ -0,0 +1,191 @@
+/**
+ * Port Discovery Module
+ *
+ * Handles dynamic WebSocket port assignment with range-based fallback.
+ * When the preferred port (default 9223) is taken by another MCP server instance
+ * (e.g., Claude Desktop Chat tab vs Code tab), the server automatically tries
+ * the next port in a fixed range (9223-9232).
+ *
+ * Port advertisement files are written to /tmp so the Figma plugin can discover
+ * which port to connect to. Each instance writes its own file with PID for
+ * stale-file detection.
+ *
+ * Data flow:
+ *   Server binds port → writes /tmp/figma-console-mcp-{port}.json
+ *   Plugin scans ports 9223-9232 → connects to first responding server
+ *   External tools read port files for discovery
+ */
+import { writeFileSync, readFileSync, unlinkSync, existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { createChildLogger } from './logger.js';
+const logger = createChildLogger({ component: 'port-discovery' });
+/** Default preferred WebSocket port */
+export const DEFAULT_WS_PORT = 9223;
+/** Number of ports in the fallback range (9223-9232 = 10 ports) */
+export const PORT_RANGE_SIZE = 10;
+/** Prefix for port advertisement files in /tmp */
+const PORT_FILE_PREFIX = 'figma-console-mcp-';
+/** Directory for port advertisement files */
+const PORT_FILE_DIR = tmpdir();
+/**
+ * Try to bind a WebSocket server to ports in a range, starting from the preferred port.
+ * Returns the first port that binds successfully.
+ *
+ * @param preferredPort - The port to try first (default 9223)
+ * @param host - The host to bind to (default 'localhost')
+ * @returns The actual port that was bound
+ * @throws If all ports in the range are exhausted
+ */
+export function getPortRange(preferredPort = DEFAULT_WS_PORT) {
+    const ports = [];
+    for (let i = 0; i < PORT_RANGE_SIZE; i++) {
+        ports.push(preferredPort + i);
+    }
+    return ports;
+}
+/**
+ * Get the file path for a port advertisement file.
+ */
+export function getPortFilePath(port) {
+    return join(PORT_FILE_DIR, `${PORT_FILE_PREFIX}${port}.json`);
+}
+/**
+ * Write a port advertisement file so clients can discover this server instance.
+ * Includes PID for stale-file detection.
+ */
+export function advertisePort(port, host = 'localhost') {
+    const data = {
+        port,
+        pid: process.pid,
+        host,
+        startedAt: new Date().toISOString(),
+    };
+    const filePath = getPortFilePath(port);
+    try {
+        writeFileSync(filePath, JSON.stringify(data, null, 2));
+        logger.info({ port, filePath }, 'Port advertised');
+    }
+    catch (error) {
+        logger.warn({ port, filePath, error }, 'Failed to write port advertisement file');
+    }
+}
+/**
+ * Remove the port advertisement file for this instance.
+ * Call on clean shutdown.
+ */
+export function unadvertisePort(port) {
+    const filePath = getPortFilePath(port);
+    try {
+        if (existsSync(filePath)) {
+            unlinkSync(filePath);
+            logger.debug({ port, filePath }, 'Port advertisement removed');
+        }
+    }
+    catch {
+        // Best-effort cleanup — file may already be gone
+    }
+}
+/**
+ * Check if a PID is still alive.
+ */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0); // Signal 0 = existence check, doesn't actually kill
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read and validate a port advertisement file.
+ * Returns null if the file doesn't exist, is invalid, or the owning process is dead.
+ */
+export function readPortFile(port) {
+    const filePath = getPortFilePath(port);
+    if (!existsSync(filePath))
+        return null;
+    try {
+        const raw = readFileSync(filePath, 'utf-8');
+        const data = JSON.parse(raw);
+        // Validate the owning process is still alive
+        if (!isProcessAlive(data.pid)) {
+            logger.debug({ port, pid: data.pid }, 'Stale port file detected (process dead), cleaning up');
+            try {
+                unlinkSync(filePath);
+            }
+            catch { /* best-effort */ }
+            return null;
+        }
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Discover all active Figma Console MCP server instances by scanning port files.
+ * Validates each file's PID to filter out stale entries.
+ */
+export function discoverActiveInstances(preferredPort = DEFAULT_WS_PORT) {
+    const instances = [];
+    for (const port of getPortRange(preferredPort)) {
+        const data = readPortFile(port);
+        if (data) {
+            instances.push(data);
+        }
+    }
+    return instances;
+}
+/**
+ * Clean up all stale port files (dead PIDs).
+ * Useful for maintenance and debugging.
+ */
+export function cleanupStalePortFiles() {
+    let cleaned = 0;
+    try {
+        const files = readdirSync(PORT_FILE_DIR);
+        for (const file of files) {
+            if (file.startsWith(PORT_FILE_PREFIX) && file.endsWith('.json')) {
+                const filePath = join(PORT_FILE_DIR, file);
+                try {
+                    const raw = readFileSync(filePath, 'utf-8');
+                    const data = JSON.parse(raw);
+                    if (!isProcessAlive(data.pid)) {
+                        unlinkSync(filePath);
+                        cleaned++;
+                        logger.debug({ port: data.port, pid: data.pid }, 'Cleaned up stale port file');
+                    }
+                }
+                catch {
+                    // Corrupt file — remove it
+                    try {
+                        unlinkSync(filePath);
+                        cleaned++;
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+        }
+    }
+    catch {
+        // Can't read /tmp — unusual but not fatal
+    }
+    return cleaned;
+}
+/**
+ * Register process exit handlers to clean up port advertisement file.
+ * Should be called once after the port is successfully bound.
+ */
+export function registerPortCleanup(port) {
+    const cleanup = () => unadvertisePort(port);
+    process.on('exit', cleanup);
+    // Re-register SIGINT/SIGTERM to ensure cleanup runs before the
+    // existing handlers in local.ts main() call process.exit()
+    const originalSigintListeners = process.listeners('SIGINT');
+    const originalSigtermListeners = process.listeners('SIGTERM');
+    // Prepend our cleanup — it runs first, then existing handlers take over
+    process.prependListener('SIGINT', cleanup);
+    process.prependListener('SIGTERM', cleanup);
+}

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

@@ -398,6 +398,19 @@ export class FigmaWebSocketServer extends EventEmitter {
     isStarted() {
         return this._isStarted;
     }
+    /**
+     * Get the bound address info (port, host, family).
+     * Only available after the server has started listening.
+     * Returns the actual port — critical when using port 0 for OS-assigned ports.
+     */
+    address() {
+        if (!this.wss)
+            return null;
+        const addr = this.wss.address();
+        if (typeof addr === 'string')
+            return null; // Unix socket path, not applicable
+        return addr;
+    }
     // ============================================================================
     // Active file getters (backward compatible — return active file's state)
     // ============================================================================

package/dist/core/port-discovery.d.ts

@@ -0,0 +1,72 @@
+/**
+ * Port Discovery Module
+ *
+ * Handles dynamic WebSocket port assignment with range-based fallback.
+ * When the preferred port (default 9223) is taken by another MCP server instance
+ * (e.g., Claude Desktop Chat tab vs Code tab), the server automatically tries
+ * the next port in a fixed range (9223-9232).
+ *
+ * Port advertisement files are written to /tmp so the Figma plugin can discover
+ * which port to connect to. Each instance writes its own file with PID for
+ * stale-file detection.
+ *
+ * Data flow:
+ *   Server binds port → writes /tmp/figma-console-mcp-{port}.json
+ *   Plugin scans ports 9223-9232 → connects to first responding server
+ *   External tools read port files for discovery
+ */
+/** Default preferred WebSocket port */
+export declare const DEFAULT_WS_PORT = 9223;
+/** Number of ports in the fallback range (9223-9232 = 10 ports) */
+export declare const PORT_RANGE_SIZE = 10;
+export interface PortFileData {
+    port: number;
+    pid: number;
+    host: string;
+    startedAt: string;
+}
+/**
+ * Try to bind a WebSocket server to ports in a range, starting from the preferred port.
+ * Returns the first port that binds successfully.
+ *
+ * @param preferredPort - The port to try first (default 9223)
+ * @param host - The host to bind to (default 'localhost')
+ * @returns The actual port that was bound
+ * @throws If all ports in the range are exhausted
+ */
+export declare function getPortRange(preferredPort?: number): number[];
+/**
+ * Get the file path for a port advertisement file.
+ */
+export declare function getPortFilePath(port: number): string;
+/**
+ * Write a port advertisement file so clients can discover this server instance.
+ * Includes PID for stale-file detection.
+ */
+export declare function advertisePort(port: number, host?: string): void;
+/**
+ * Remove the port advertisement file for this instance.
+ * Call on clean shutdown.
+ */
+export declare function unadvertisePort(port: number): void;
+/**
+ * Read and validate a port advertisement file.
+ * Returns null if the file doesn't exist, is invalid, or the owning process is dead.
+ */
+export declare function readPortFile(port: number): PortFileData | null;
+/**
+ * Discover all active Figma Console MCP server instances by scanning port files.
+ * Validates each file's PID to filter out stale entries.
+ */
+export declare function discoverActiveInstances(preferredPort?: number): PortFileData[];
+/**
+ * Clean up all stale port files (dead PIDs).
+ * Useful for maintenance and debugging.
+ */
+export declare function cleanupStalePortFiles(): number;
+/**
+ * Register process exit handlers to clean up port advertisement file.
+ * Should be called once after the port is successfully bound.
+ */
+export declare function registerPortCleanup(port: number): void;
+//# sourceMappingURL=port-discovery.d.ts.map

package/dist/core/port-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port-discovery.d.ts","sourceRoot":"","sources":["../../src/core/port-discovery.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AASH,uCAAuC;AACvC,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC,mEAAmE;AACnE,eAAO,MAAM,eAAe,KAAK,CAAC;AAQlC,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,aAAa,GAAE,MAAwB,GAAG,MAAM,EAAE,CAM9E;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,MAAoB,GAAG,IAAI,CAe5E;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAUlD;AAcD;;;GAGG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI,CAoB9D;AAED;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,aAAa,GAAE,MAAwB,GAAG,YAAY,EAAE,CAW/F;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,MAAM,CA2B9C;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAatD"}

package/dist/core/port-discovery.js

@@ -0,0 +1,192 @@
+/**
+ * Port Discovery Module
+ *
+ * Handles dynamic WebSocket port assignment with range-based fallback.
+ * When the preferred port (default 9223) is taken by another MCP server instance
+ * (e.g., Claude Desktop Chat tab vs Code tab), the server automatically tries
+ * the next port in a fixed range (9223-9232).
+ *
+ * Port advertisement files are written to /tmp so the Figma plugin can discover
+ * which port to connect to. Each instance writes its own file with PID for
+ * stale-file detection.
+ *
+ * Data flow:
+ *   Server binds port → writes /tmp/figma-console-mcp-{port}.json
+ *   Plugin scans ports 9223-9232 → connects to first responding server
+ *   External tools read port files for discovery
+ */
+import { writeFileSync, readFileSync, unlinkSync, existsSync, readdirSync } from 'fs';
+import { join } from 'path';
+import { tmpdir } from 'os';
+import { createChildLogger } from './logger.js';
+const logger = createChildLogger({ component: 'port-discovery' });
+/** Default preferred WebSocket port */
+export const DEFAULT_WS_PORT = 9223;
+/** Number of ports in the fallback range (9223-9232 = 10 ports) */
+export const PORT_RANGE_SIZE = 10;
+/** Prefix for port advertisement files in /tmp */
+const PORT_FILE_PREFIX = 'figma-console-mcp-';
+/** Directory for port advertisement files */
+const PORT_FILE_DIR = tmpdir();
+/**
+ * Try to bind a WebSocket server to ports in a range, starting from the preferred port.
+ * Returns the first port that binds successfully.
+ *
+ * @param preferredPort - The port to try first (default 9223)
+ * @param host - The host to bind to (default 'localhost')
+ * @returns The actual port that was bound
+ * @throws If all ports in the range are exhausted
+ */
+export function getPortRange(preferredPort = DEFAULT_WS_PORT) {
+    const ports = [];
+    for (let i = 0; i < PORT_RANGE_SIZE; i++) {
+        ports.push(preferredPort + i);
+    }
+    return ports;
+}
+/**
+ * Get the file path for a port advertisement file.
+ */
+export function getPortFilePath(port) {
+    return join(PORT_FILE_DIR, `${PORT_FILE_PREFIX}${port}.json`);
+}
+/**
+ * Write a port advertisement file so clients can discover this server instance.
+ * Includes PID for stale-file detection.
+ */
+export function advertisePort(port, host = 'localhost') {
+    const data = {
+        port,
+        pid: process.pid,
+        host,
+        startedAt: new Date().toISOString(),
+    };
+    const filePath = getPortFilePath(port);
+    try {
+        writeFileSync(filePath, JSON.stringify(data, null, 2));
+        logger.info({ port, filePath }, 'Port advertised');
+    }
+    catch (error) {
+        logger.warn({ port, filePath, error }, 'Failed to write port advertisement file');
+    }
+}
+/**
+ * Remove the port advertisement file for this instance.
+ * Call on clean shutdown.
+ */
+export function unadvertisePort(port) {
+    const filePath = getPortFilePath(port);
+    try {
+        if (existsSync(filePath)) {
+            unlinkSync(filePath);
+            logger.debug({ port, filePath }, 'Port advertisement removed');
+        }
+    }
+    catch {
+        // Best-effort cleanup — file may already be gone
+    }
+}
+/**
+ * Check if a PID is still alive.
+ */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0); // Signal 0 = existence check, doesn't actually kill
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read and validate a port advertisement file.
+ * Returns null if the file doesn't exist, is invalid, or the owning process is dead.
+ */
+export function readPortFile(port) {
+    const filePath = getPortFilePath(port);
+    if (!existsSync(filePath))
+        return null;
+    try {
+        const raw = readFileSync(filePath, 'utf-8');
+        const data = JSON.parse(raw);
+        // Validate the owning process is still alive
+        if (!isProcessAlive(data.pid)) {
+            logger.debug({ port, pid: data.pid }, 'Stale port file detected (process dead), cleaning up');
+            try {
+                unlinkSync(filePath);
+            }
+            catch { /* best-effort */ }
+            return null;
+        }
+        return data;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Discover all active Figma Console MCP server instances by scanning port files.
+ * Validates each file's PID to filter out stale entries.
+ */
+export function discoverActiveInstances(preferredPort = DEFAULT_WS_PORT) {
+    const instances = [];
+    for (const port of getPortRange(preferredPort)) {
+        const data = readPortFile(port);
+        if (data) {
+            instances.push(data);
+        }
+    }
+    return instances;
+}
+/**
+ * Clean up all stale port files (dead PIDs).
+ * Useful for maintenance and debugging.
+ */
+export function cleanupStalePortFiles() {
+    let cleaned = 0;
+    try {
+        const files = readdirSync(PORT_FILE_DIR);
+        for (const file of files) {
+            if (file.startsWith(PORT_FILE_PREFIX) && file.endsWith('.json')) {
+                const filePath = join(PORT_FILE_DIR, file);
+                try {
+                    const raw = readFileSync(filePath, 'utf-8');
+                    const data = JSON.parse(raw);
+                    if (!isProcessAlive(data.pid)) {
+                        unlinkSync(filePath);
+                        cleaned++;
+                        logger.debug({ port: data.port, pid: data.pid }, 'Cleaned up stale port file');
+                    }
+                }
+                catch {
+                    // Corrupt file — remove it
+                    try {
+                        unlinkSync(filePath);
+                        cleaned++;
+                    }
+                    catch { /* ignore */ }
+                }
+            }
+        }
+    }
+    catch {
+        // Can't read /tmp — unusual but not fatal
+    }
+    return cleaned;
+}
+/**
+ * Register process exit handlers to clean up port advertisement file.
+ * Should be called once after the port is successfully bound.
+ */
+export function registerPortCleanup(port) {
+    const cleanup = () => unadvertisePort(port);
+    process.on('exit', cleanup);
+    // Re-register SIGINT/SIGTERM to ensure cleanup runs before the
+    // existing handlers in local.ts main() call process.exit()
+    const originalSigintListeners = process.listeners('SIGINT');
+    const originalSigtermListeners = process.listeners('SIGTERM');
+    // Prepend our cleanup — it runs first, then existing handlers take over
+    process.prependListener('SIGINT', cleanup);
+    process.prependListener('SIGTERM', cleanup);
+}
+//# sourceMappingURL=port-discovery.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"port-discovery.js","sourceRoot":"","sources":["../../src/core/port-discovery.ts"],"names":[],"mappings":"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"}

package/dist/core/websocket-server.d.ts

@@ -108,6 +108,12 @@ export declare class FigmaWebSocketServer extends EventEmitter {
      * Whether the server has been started
      */
     isStarted(): boolean;
+    /**
+     * Get the bound address info (port, host, family).
+     * Only available after the server has started listening.
+     * Returns the actual port — critical when using port 0 for OS-assigned ports.
+     */
+    address(): import('net').AddressInfo | null;
     /**
      * Get info about the currently active Figma file.
      * Returns null if no file is active or connected.