@mp3wizard/figma-console-mcp 1.14.0

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

@@ -0,0 +1,199 @@
+/**
+ * Cloud WebSocket Relay — Durable Object
+ *
+ * Bridges the Figma Desktop Bridge plugin to the cloud MCP server.
+ * The plugin connects via WebSocket (hibernation-aware); the MCP DO
+ * sends commands via fetch() RPC and receives responses.
+ *
+ * IMPORTANT: Uses hibernation-safe patterns throughout:
+ *   - WebSocket retrieved via this.ctx.getWebSockets() (not class property)
+ *   - File info persisted in DO storage (not in-memory)
+ *   - Pending requests kept in-memory (safe: fetch keeps DO alive)
+ *
+ * Routes:
+ *   /ws/connect   — WebSocket upgrade from plugin (paired via code)
+ *   /relay/command — RPC from MCP DO → plugin (holds response open)
+ *   /relay/status  — Connection & file info query
+ */
+import { DurableObject } from 'cloudflare:workers';
+/**
+ * Generate a 6-character alphanumeric pairing code (uppercase).
+ */
+export function generatePairingCode() {
+    const chars = 'ABCDEFGHJKLMNPQRSTUVWXYZ23456789'; // No 0/O/1/I confusion
+    let code = '';
+    const arr = new Uint8Array(6);
+    crypto.getRandomValues(arr);
+    for (let i = 0; i < 6; i++) {
+        code += chars[arr[i] % chars.length];
+    }
+    return code;
+}
+export class PluginRelayDO extends DurableObject {
+    constructor() {
+        super(...arguments);
+        this.pendingRequests = new Map();
+        this.requestIdCounter = 0;
+    }
+    // ======================================================================
+    // Hibernation-safe WebSocket retrieval
+    // ======================================================================
+    /**
+     * Get the active plugin WebSocket. Uses ctx.getWebSockets() which
+     * survives DO hibernation (unlike a class property reference).
+     */
+    getPluginWs() {
+        const sockets = this.ctx.getWebSockets('plugin');
+        return sockets.length > 0 ? sockets[0] : null;
+    }
+    /**
+     * Incoming fetch handler — dispatches to routes.
+     */
+    async fetch(request) {
+        const url = new URL(request.url);
+        if (url.pathname === '/ws/connect') {
+            return this.handlePluginConnect(request);
+        }
+        if (url.pathname === '/relay/command') {
+            return this.handleRelayCommand(request);
+        }
+        if (url.pathname === '/relay/status') {
+            return this.handleRelayStatus();
+        }
+        return new Response('Not found', { status: 404 });
+    }
+    // ==========================================================================
+    // WebSocket — plugin connects here
+    // ==========================================================================
+    handlePluginConnect(request) {
+        const upgradeHeader = request.headers.get('Upgrade');
+        if (!upgradeHeader || upgradeHeader.toLowerCase() !== 'websocket') {
+            return new Response('Expected WebSocket upgrade', { status: 426 });
+        }
+        // Close any existing plugin connection (e.g., re-pairing)
+        const existing = this.getPluginWs();
+        if (existing) {
+            try {
+                existing.close(1000, 'Replaced by new connection');
+            }
+            catch { /* ignore */ }
+        }
+        const pair = new WebSocketPair();
+        const [client, server] = Object.values(pair);
+        // Accept with 'plugin' tag — this.ctx.getWebSockets('plugin') retrieves
+        // the socket even after the DO wakes from hibernation.
+        this.ctx.acceptWebSocket(server, ['plugin']);
+        return new Response(null, { status: 101, webSocket: client });
+    }
+    /**
+     * Hibernation callback — incoming message from plugin WebSocket.
+     */
+    async webSocketMessage(ws, message) {
+        if (typeof message !== 'string')
+            return;
+        try {
+            const data = JSON.parse(message);
+            // FILE_INFO identification from plugin — persist to DO storage
+            if (data.type === 'FILE_INFO' && data.data) {
+                const fileInfo = {
+                    fileName: data.data.fileName,
+                    fileKey: data.data.fileKey || null,
+                    currentPage: data.data.currentPage,
+                    currentPageId: data.data.currentPageId || null,
+                    connectedAt: Date.now(),
+                };
+                await this.ctx.storage.put('fileInfo', fileInfo);
+                return;
+            }
+            // Event broadcasts from plugin (PAGE_CHANGE, etc.)
+            if (data.type === 'PAGE_CHANGE' && data.data) {
+                const fileInfo = await this.ctx.storage.get('fileInfo');
+                if (fileInfo) {
+                    fileInfo.currentPage = data.data.pageName;
+                    fileInfo.currentPageId = data.data.pageId || null;
+                    await this.ctx.storage.put('fileInfo', fileInfo);
+                }
+                return;
+            }
+            // Response to a relayed command
+            if (data.id && this.pendingRequests.has(data.id)) {
+                const pending = this.pendingRequests.get(data.id);
+                clearTimeout(pending.timeoutId);
+                this.pendingRequests.delete(data.id);
+                const body = JSON.stringify(data.error
+                    ? { error: data.error }
+                    : { result: data.result });
+                pending.resolve(new Response(body, {
+                    headers: { 'Content-Type': 'application/json' },
+                }));
+            }
+        }
+        catch {
+            // Malformed message — ignore
+        }
+    }
+    /**
+     * Hibernation callback — WebSocket closed.
+     */
+    webSocketClose(ws, code, reason, wasClean) {
+        this.handleDisconnect();
+    }
+    /**
+     * Hibernation callback — WebSocket error.
+     */
+    webSocketError(ws, error) {
+        this.handleDisconnect();
+    }
+    handleDisconnect() {
+        // Clear persisted file info
+        this.ctx.storage.delete('fileInfo');
+        // Reject all in-flight commands
+        for (const [id, pending] of this.pendingRequests) {
+            clearTimeout(pending.timeoutId);
+            pending.resolve(new Response(JSON.stringify({ error: 'Plugin disconnected' }), { status: 502, headers: { 'Content-Type': 'application/json' } }));
+        }
+        this.pendingRequests.clear();
+    }
+    // ==========================================================================
+    // Relay — MCP DO sends commands here
+    // ==========================================================================
+    async handleRelayCommand(request) {
+        const pluginWs = this.getPluginWs();
+        if (!pluginWs) {
+            return new Response(JSON.stringify({ error: 'No plugin connected. User must pair the Desktop Bridge plugin first.' }), { status: 502, headers: { 'Content-Type': 'application/json' } });
+        }
+        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 {
+            pluginWs.send(JSON.stringify({ id, method, params }));
+        }
+        catch {
+            return new Response(JSON.stringify({ error: 'Failed to send command to plugin — connection may be stale' }), { status: 502, headers: { 'Content-Type': 'application/json' } });
+        }
+        // Wait for plugin response (the DO stays alive because fetch is active)
+        return new Promise((resolve) => {
+            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' } }));
+                }
+            }, safeTimeout);
+            this.pendingRequests.set(id, { resolve, reject: () => { }, timeoutId });
+        });
+    }
+    // ==========================================================================
+    // Status
+    // ==========================================================================
+    async handleRelayStatus() {
+        const pluginWs = this.getPluginWs();
+        const fileInfo = await this.ctx.storage.get('fileInfo');
+        return new Response(JSON.stringify({
+            connected: pluginWs !== null,
+            fileInfo: fileInfo || null,
+            pendingCommands: this.pendingRequests.size,
+        }), { headers: { 'Content-Type': 'application/json' } });
+    }
+}

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

@@ -0,0 +1,292 @@
+/**
+ * Figma Comments MCP Tools
+ * Tools for getting, posting, and deleting comments on Figma files via REST API.
+ * Works in both local and Cloudflare Workers modes — no Plugin API dependency.
+ */
+import { z } from "zod";
+import { extractFileKey } from "./figma-api.js";
+import { createChildLogger } from "./logger.js";
+const logger = createChildLogger({ component: "comment-tools" });
+// ============================================================================
+// Tool Registration
+// ============================================================================
+export function registerCommentTools(server, getFigmaAPI, getCurrentUrl, options) {
+    // -----------------------------------------------------------------------
+    // Tool: figma_get_comments
+    // -----------------------------------------------------------------------
+    server.tool("figma_get_comments", "Get comments on a Figma file. Returns comment threads with author, message, timestamps, and pinned node locations. Use include_resolved to also see resolved comments.", {
+        fileUrl: z
+            .string()
+            .url()
+            .optional()
+            .describe("Figma file URL. Uses current URL if omitted."),
+        as_md: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Return comment message bodies as markdown. Default: false"),
+        include_resolved: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Include resolved (completed) comment threads. Default: false (only active comments)"),
+    }, async ({ fileUrl, as_md = false, include_resolved = false }) => {
+        try {
+            const url = fileUrl || getCurrentUrl();
+            if (!url) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "no_file_url",
+                                message: "No Figma file URL available. Pass the fileUrl parameter or ensure the Desktop Bridge plugin is open in Figma.",
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const fileKey = extractFileKey(url);
+            if (!fileKey) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "invalid_url",
+                                message: `Invalid Figma URL: ${url}`,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            logger.info({ fileKey, as_md, include_resolved }, "Fetching comments");
+            const api = await getFigmaAPI();
+            const response = await api.getComments(fileKey, { as_md });
+            const allComments = response.comments || [];
+            // Filter out resolved comments unless explicitly requested
+            const comments = include_resolved
+                ? allComments
+                : allComments.filter((c) => !c.resolved_at);
+            const result = {
+                comments,
+                summary: {
+                    total: allComments.length,
+                    active: allComments.filter((c) => !c.resolved_at).length,
+                    resolved: allComments.filter((c) => c.resolved_at).length,
+                    returned: comments.length,
+                },
+            };
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error({ error }, "Failed to get comments");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "get_comments_failed",
+                            message: `Cannot get comments. ${message}`,
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // -----------------------------------------------------------------------
+    // Tool: figma_post_comment
+    // -----------------------------------------------------------------------
+    server.tool("figma_post_comment", "Post a comment on a Figma file, optionally pinned to a specific design node. Use after figma_check_design_parity to notify designers of drift when code is the canonical source. Supports replies to existing comment threads. Limitation: @mentions are a Figma UI-only feature — including '@name' in the message renders as plain text, not a clickable mention tag, and does not trigger Figma notifications.", {
+        fileUrl: z
+            .string()
+            .url()
+            .optional()
+            .describe("Figma file URL. Uses current URL if omitted."),
+        message: z
+            .string()
+            .describe("The comment message text. Supports basic formatting."),
+        node_id: z
+            .string()
+            .optional()
+            .describe("Node ID to pin the comment to (e.g., '695:313'). Comment appears on that element in Figma."),
+        x: z
+            .number()
+            .optional()
+            .describe("X coordinate for comment placement (absolute canvas position). Used with node_id."),
+        y: z
+            .number()
+            .optional()
+            .describe("Y coordinate for comment placement (absolute canvas position). Used with node_id."),
+        reply_to_comment_id: z
+            .string()
+            .optional()
+            .describe("ID of an existing comment to reply to. Creates a threaded reply instead of a new top-level comment."),
+    }, async ({ fileUrl, message, node_id, x, y, reply_to_comment_id }) => {
+        try {
+            const url = fileUrl || getCurrentUrl();
+            if (!url) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "no_file_url",
+                                message: "No Figma file URL available. Pass the fileUrl parameter or ensure the Desktop Bridge plugin is open in Figma.",
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const fileKey = extractFileKey(url);
+            if (!fileKey) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "invalid_url",
+                                message: `Invalid Figma URL: ${url}`,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            logger.info({ fileKey, node_id, reply_to_comment_id }, "Posting comment");
+            const api = await getFigmaAPI();
+            // Build client_meta for pinning to a node/position
+            // Figma API requires node_offset when node_id is present — default to (0,0) if not specified
+            let clientMeta;
+            if (node_id) {
+                clientMeta = {
+                    node_id,
+                    node_offset: { x: x ?? 0, y: y ?? 0 },
+                };
+            }
+            const result = await api.postComment(fileKey, message, clientMeta, reply_to_comment_id);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            comment: {
+                                id: result.id,
+                                message: result.message,
+                                created_at: result.created_at,
+                                user: result.user,
+                                client_meta: result.client_meta,
+                                order_id: result.order_id,
+                            },
+                        }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message_text = error instanceof Error ? error.message : String(error);
+            logger.error({ error }, "Failed to post comment");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "post_comment_failed",
+                            message: `Cannot post comment. ${message_text}`,
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // -----------------------------------------------------------------------
+    // Tool: figma_delete_comment
+    // -----------------------------------------------------------------------
+    server.tool("figma_delete_comment", "Delete a comment from a Figma file by its comment ID. Use figma_get_comments to find comment IDs first.", {
+        fileUrl: z
+            .string()
+            .url()
+            .optional()
+            .describe("Figma file URL. Uses current URL if omitted."),
+        comment_id: z
+            .string()
+            .describe("The ID of the comment to delete. Get IDs from figma_get_comments."),
+    }, async ({ fileUrl, comment_id }) => {
+        try {
+            const url = fileUrl || getCurrentUrl();
+            if (!url) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "no_file_url",
+                                message: "No Figma file URL available. Pass the fileUrl parameter or ensure the Desktop Bridge plugin is open in Figma.",
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const fileKey = extractFileKey(url);
+            if (!fileKey) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "invalid_url",
+                                message: `Invalid Figma URL: ${url}`,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            logger.info({ fileKey, comment_id }, "Deleting comment");
+            const api = await getFigmaAPI();
+            await api.deleteComment(fileKey, comment_id);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            deleted_comment_id: comment_id,
+                        }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error({ error }, "Failed to delete comment");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "delete_comment_failed",
+                            message: `Cannot delete comment. ${message}`,
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/cloudflare/core/config.js

@@ -0,0 +1,161 @@
+/**
+ * Configuration management for Figma Console MCP server
+ */
+import { readFileSync, existsSync } from 'fs';
+import { homedir } from 'os';
+import { join } from 'path';
+/**
+ * Auto-detect server mode based on environment
+ */
+function detectMode() {
+    // If running in Workers environment, return cloudflare
+    if (typeof globalThis !== 'undefined' && 'caches' in globalThis) {
+        return 'cloudflare';
+    }
+    // Explicit env var override
+    const modeEnv = process.env.FIGMA_MCP_MODE?.toLowerCase();
+    if (modeEnv === 'local' || modeEnv === 'cloudflare') {
+        return modeEnv;
+    }
+    // Default to local for Node.js environments
+    return 'local';
+}
+/**
+ * Default configuration values
+ */
+const DEFAULT_CONFIG = {
+    mode: detectMode(),
+    browser: {
+        headless: false,
+        args: [
+            '--disable-blink-features=AutomationControlled',
+            '--disable-dev-shm-usage',
+            // '--no-sandbox' removed from defaults; enable via config file if required by your environment
+        ],
+    },
+    console: {
+        bufferSize: 1000,
+        filterLevels: ['log', 'info', 'warn', 'error', 'debug'],
+        truncation: {
+            maxStringLength: 500,
+            maxArrayLength: 10,
+            maxObjectDepth: 3,
+            removeDuplicates: true,
+        },
+    },
+    screenshots: {
+        defaultFormat: 'png',
+        quality: 90,
+        storePath: join(process.env.TMPDIR || '/tmp', 'figma-console-mcp', 'screenshots'),
+    },
+    local: {
+        debugHost: process.env.FIGMA_DEBUG_HOST || 'localhost',
+        debugPort: parseInt(process.env.FIGMA_DEBUG_PORT || '9222', 10),
+    },
+};
+/**
+ * Possible config file locations (checked in order)
+ */
+const CONFIG_PATHS = [
+    // Environment variable override
+    process.env.FIGMA_CONSOLE_CONFIG,
+    // Project-local config
+    join(process.cwd(), '.figma-console-mcp.json'),
+    join(process.cwd(), 'figma-console-mcp.json'),
+    // User home config
+    join(homedir(), '.config', 'figma-console-mcp', 'config.json'),
+    join(homedir(), '.figma-console-mcp.json'),
+].filter((path) => path !== undefined);
+/**
+ * Load configuration from file or use defaults
+ */
+export function loadConfig() {
+    // Try to load from config file
+    for (const configPath of CONFIG_PATHS) {
+        if (existsSync(configPath)) {
+            try {
+                const fileContent = readFileSync(configPath, 'utf-8');
+                const userConfig = JSON.parse(fileContent);
+                // Deep merge with defaults
+                const config = mergeConfig(DEFAULT_CONFIG, userConfig);
+                return config;
+            }
+            catch (error) {
+                console.error(`Failed to load config from ${configPath}:`, error);
+                // Continue to next config path
+            }
+        }
+    }
+    // No config file found, use defaults
+    return DEFAULT_CONFIG;
+}
+/**
+ * Deep merge two configuration objects
+ */
+function mergeConfig(defaults, overrides) {
+    return {
+        mode: overrides.mode || defaults.mode,
+        browser: {
+            ...defaults.browser,
+            ...(overrides.browser || {}),
+        },
+        console: {
+            ...defaults.console,
+            ...(overrides.console || {}),
+            truncation: {
+                ...defaults.console.truncation,
+                ...(overrides.console?.truncation || {}),
+            },
+        },
+        screenshots: {
+            ...defaults.screenshots,
+            ...(overrides.screenshots || {}),
+        },
+        local: {
+            ...defaults.local,
+            ...(overrides.local || {}),
+        },
+    };
+}
+/**
+ * Validate configuration
+ */
+export function validateConfig(config) {
+    // Validate browser config
+    if (!Array.isArray(config.browser.args)) {
+        throw new Error('browser.args must be an array');
+    }
+    // Validate console config
+    if (config.console.bufferSize <= 0) {
+        throw new Error('console.bufferSize must be positive');
+    }
+    if (!Array.isArray(config.console.filterLevels)) {
+        throw new Error('console.filterLevels must be an array');
+    }
+    // Validate truncation config
+    const { truncation } = config.console;
+    if (truncation.maxStringLength <= 0) {
+        throw new Error('console.truncation.maxStringLength must be positive');
+    }
+    if (truncation.maxArrayLength <= 0) {
+        throw new Error('console.truncation.maxArrayLength must be positive');
+    }
+    if (truncation.maxObjectDepth <= 0) {
+        throw new Error('console.truncation.maxObjectDepth must be positive');
+    }
+    // Validate screenshot config
+    if (!['png', 'jpeg'].includes(config.screenshots.defaultFormat)) {
+        throw new Error('screenshots.defaultFormat must be "png" or "jpeg"');
+    }
+    if (config.screenshots.quality < 0 || config.screenshots.quality > 100) {
+        throw new Error('screenshots.quality must be between 0 and 100');
+    }
+}
+/**
+ * Get configuration with validation
+ */
+export function getConfig() {
+    const config = loadConfig();
+    validateConfig(config);
+    return config;
+}