@mp3wizard/figma-console-mcp 1.14.0

package/dist/cloudflare/core/logger.js

@@ -0,0 +1,53 @@
+/**
+ * Logging infrastructure using pino
+ */
+import pino from 'pino';
+/**
+ * Create logger instance
+ * Note: In Cloudflare Workers, console methods are automatically captured
+ */
+export function createLogger(level = 'info') {
+    // Check if running in Cloudflare Workers environment
+    const isWorkers = typeof globalThis.caches !== 'undefined';
+    if (isWorkers) {
+        // Cloudflare Workers: use simple console-based logging
+        return pino({
+            level: process.env.LOG_LEVEL || level,
+            browser: {
+                asObject: true,
+            },
+        });
+    }
+    // Node.js environment: detect MCP stdio mode
+    // When stdout is not a TTY, we're likely in MCP stdio mode
+    const isMCPStdio = !process.stdout.isTTY;
+    // MCP stdio mode: NO pretty printing, stderr only
+    if (isMCPStdio) {
+        return pino({ level: process.env.LOG_LEVEL || level }, pino.destination({ dest: 2, sync: false }));
+    }
+    // Development/terminal mode: use pretty printing
+    return pino({
+        level: process.env.LOG_LEVEL || level,
+        transport: process.env.NODE_ENV !== 'production'
+            ? {
+                target: 'pino-pretty',
+                options: {
+                    colorize: true,
+                    translateTime: 'HH:MM:ss',
+                    ignore: 'pid,hostname',
+                    destination: 2, // Explicit stderr for transport
+                },
+            }
+            : undefined,
+    });
+}
+/**
+ * Default logger instance
+ */
+export const logger = createLogger();
+/**
+ * Create child logger with additional context
+ */
+export function createChildLogger(bindings) {
+    return logger.child(bindings);
+}

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

@@ -0,0 +1,282 @@
+/**
+ * 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.
+ *
+ * Zombie process detection:
+ *   Active servers refresh their port file every 30s (heartbeat).
+ *   On startup, cleanupStalePortFiles() detects zombies via:
+ *     1. Dead PID — process no longer exists (existing behavior)
+ *     2. Stale heartbeat — lastSeen older than 5 minutes (process frozen/hung)
+ *     3. Age ceiling — startedAt older than 4 hours with no heartbeat (pre-v1.12 compat)
+ *   Zombie processes are terminated with SIGTERM to free their ports.
+ *
+ * Data flow:
+ *   Server binds port → writes /tmp/figma-console-mcp-{port}.json
+ *   Server heartbeat → refreshes lastSeen every 30s
+ *   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();
+/** Maximum age before a port file without heartbeat is considered stale (4 hours) */
+export const MAX_PORT_FILE_AGE_MS = 4 * 60 * 60 * 1000;
+/** Maximum time since last heartbeat before a process is considered stale (5 minutes) */
+export const HEARTBEAT_STALE_MS = 5 * 60 * 1000;
+/** Interval between heartbeat refreshes (30 seconds) */
+export const HEARTBEAT_INTERVAL_MS = 30 * 1000;
+/**
+ * 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 and lastSeen for heartbeat tracking.
+ */
+export function advertisePort(port, host = 'localhost') {
+    const now = new Date().toISOString();
+    const data = {
+        port,
+        pid: process.pid,
+        host,
+        startedAt: now,
+        lastSeen: now,
+    };
+    const filePath = getPortFilePath(port);
+    try {
+        writeFileSync(filePath, JSON.stringify(data, null, 2), { mode: 0o600 });
+        logger.info({ port, filePath }, 'Port advertised');
+    }
+    catch (error) {
+        logger.warn({ port, filePath, error }, 'Failed to write port advertisement file');
+    }
+}
+/**
+ * Refresh the lastSeen timestamp in a port advertisement file.
+ * Called periodically as a heartbeat to prove this server is still active.
+ * Non-fatal — heartbeat failures are silently ignored.
+ */
+export function refreshPortAdvertisement(port) {
+    const filePath = getPortFilePath(port);
+    try {
+        if (!existsSync(filePath))
+            return;
+        const raw = readFileSync(filePath, 'utf-8');
+        const data = JSON.parse(raw);
+        // Only refresh our own port file
+        if (data.pid !== process.pid)
+            return;
+        data.lastSeen = new Date().toISOString();
+        writeFileSync(filePath, JSON.stringify(data, null, 2), { mode: 0o600 });
+    }
+    catch {
+        // Best-effort — heartbeat failures are non-fatal
+    }
+}
+/**
+ * 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;
+    }
+}
+/**
+ * Determine if a port file represents a zombie/stale MCP instance.
+ *
+ * Detection layers:
+ *   1. If lastSeen exists (v1.12+): stale if older than HEARTBEAT_STALE_MS (5 min)
+ *   2. If lastSeen is missing (pre-v1.12): stale if startedAt older than MAX_PORT_FILE_AGE_MS (4h)
+ *
+ * Assumes the owning process IS alive (PID check should happen before calling this).
+ */
+export function isStaleInstance(data) {
+    const now = Date.now();
+    // If heartbeat exists, use it — active servers refresh every 30s
+    if (data.lastSeen) {
+        const lastSeenAge = now - new Date(data.lastSeen).getTime();
+        return lastSeenAge > HEARTBEAT_STALE_MS;
+    }
+    // No heartbeat (pre-v1.12 instance) — fall back to startup age
+    const startedAge = now - new Date(data.startedAt).getTime();
+    return startedAge > MAX_PORT_FILE_AGE_MS;
+}
+/**
+ * Attempt to terminate a process by PID.
+ * Uses SIGTERM for graceful shutdown. On Windows, this calls TerminateProcess
+ * which is immediate and cannot be caught.
+ *
+ * @returns true if the signal was sent successfully, false if the process was already gone
+ */
+function terminateProcess(pid) {
+    try {
+        process.kill(pid, 'SIGTERM');
+        return true;
+    }
+    catch {
+        return false; // Process may have already exited
+    }
+}
+/**
+ * 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 stale port files and terminate zombie MCP processes.
+ *
+ * Runs at startup before port binding. Detects stale instances via:
+ *   1. Dead PID — process no longer exists → delete file
+ *   2. Zombie process — alive but stale (no heartbeat or expired heartbeat)
+ *      → send SIGTERM to free the port, then delete file
+ *   3. Corrupt file — invalid JSON → delete file
+ */
+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)) {
+                        // Dead PID — just clean up the file
+                        unlinkSync(filePath);
+                        cleaned++;
+                        logger.debug({ port: data.port, pid: data.pid }, 'Cleaned up stale port file (dead process)');
+                    }
+                    else if (data.pid !== process.pid && isStaleInstance(data)) {
+                        // Live PID but stale — zombie process, terminate it to free the port
+                        logger.info({ port: data.port, pid: data.pid, startedAt: data.startedAt, lastSeen: data.lastSeen }, 'Detected zombie MCP process — sending SIGTERM to free port');
+                        terminateProcess(data.pid);
+                        try {
+                            unlinkSync(filePath);
+                        }
+                        catch { /* best-effort */ }
+                        cleaned++;
+                    }
+                }
+                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/snippet-injector.js

@@ -0,0 +1,96 @@
+/**
+ * Snippet Injector
+ * Generates and manages console-based data extraction snippets for Figma
+ */
+import { createChildLogger } from './logger.js';
+const logger = createChildLogger({ component: 'snippet-injector' });
+export class SnippetInjector {
+    /**
+     * Generate variables extraction snippet for Figma console
+     */
+    generateVariablesSnippet() {
+        return `
+(async () => {
+  try {
+    const vars = await figma.variables.getLocalVariablesAsync();
+    const collections = await figma.variables.getLocalVariableCollectionsAsync();
+
+    const payload = {
+      timestamp: Date.now(),
+      variables: vars.map(v => ({
+        id: v.id,
+        name: v.name,
+        key: v.key,
+        resolvedType: v.resolvedType,
+        valuesByMode: v.valuesByMode,
+        variableCollectionId: v.variableCollectionId,
+        scopes: v.scopes,
+        description: v.description,
+        hiddenFromPublishing: v.hiddenFromPublishing
+      })),
+      variableCollections: collections.map(c => ({
+        id: c.id,
+        name: c.name,
+        key: c.key,
+        modes: c.modes.map(m => ({ modeId: m.modeId, name: m.name })),
+        defaultModeId: c.defaultModeId,
+        variableIds: c.variableIds
+      }))
+    };
+
+    console.log('[MCP_VARIABLES]', JSON.stringify(payload), '[MCP_VARIABLES_END]');
+    console.log('✅ Variables data captured! Run figma_get_variables({ parseFromConsole: true }) in Claude to retrieve.');
+
+  } catch (error) {
+    console.error('[MCP_VARIABLES_ERROR]', error.message);
+    console.log('❌ Make sure you\\'re running this in a Figma file with variables.');
+  }
+})();
+		`.trim();
+    }
+    /**
+     * Parse variables from console log entry
+     */
+    parseVariablesFromLog(logEntry) {
+        try {
+            // Check for marker
+            if (!logEntry.message.includes('[MCP_VARIABLES]')) {
+                return null;
+            }
+            // Extract JSON from args
+            // The snippet logs: console.log('[MCP_VARIABLES]', JSON.stringify(payload), '[MCP_VARIABLES_END]')
+            // So args[0] is the marker, args[1] is the JSON string
+            const jsonStr = logEntry.args[1] || logEntry.args[0];
+            if (!jsonStr) {
+                throw new Error('No data found in console log');
+            }
+            const data = typeof jsonStr === 'string' ? JSON.parse(jsonStr) : jsonStr;
+            logger.info({
+                variableCount: data.variables?.length || 0,
+                collectionCount: data.variableCollections?.length || 0,
+            }, 'Successfully parsed variables from console log');
+            return {
+                variables: data.variables || [],
+                variableCollections: data.variableCollections || [],
+                timestamp: data.timestamp || Date.now(),
+            };
+        }
+        catch (error) {
+            logger.error({ error }, 'Failed to parse variables from console log');
+            throw new Error(`Failed to parse variables from console log: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Find the most recent variables log entry
+     */
+    findVariablesLog(logs) {
+        // Search in reverse (most recent first)
+        for (let i = logs.length - 1; i >= 0; i--) {
+            const log = logs[i];
+            if (log.message.includes('[MCP_VARIABLES]')) {
+                return log;
+            }
+        }
+        return null;
+    }
+}

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

@@ -0,0 +1,4 @@
+/**
+ * TypeScript types for Design-Code Parity Checker & Documentation Generator
+ */
+export {};

package/dist/cloudflare/core/types/enriched.js

@@ -0,0 +1,5 @@
+/**
+ * TypeScript types for enriched Figma data responses
+ * Phase 5: Enriched Data Extraction & Design System Auditing
+ */
+export {};

package/dist/cloudflare/core/types/index.js

@@ -0,0 +1,4 @@
+/**
+ * Type definitions for Figma Console MCP
+ */
+export {};