@seed-design/mcp 0.0.0-alpha-20260324091316

package/bin/index.mjs

@@ -0,0 +1,1295 @@
+#!/usr/bin/env node
+import { cac } from 'cac';
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import fs from 'node:fs';
+import path from 'node:path';
+import { Api } from 'figma-api';
+import { v4 } from 'uuid';
+import WebSocket$1 from 'ws';
+import { createRestNormalizer, figma, react, getFigmaColorVariableNames } from '@seed-design/figma';
+import { z } from 'zod';
+
+var version = "1.3.8";
+
+/**
+ * Custom logging module that writes to stderr instead of stdout
+ * to avoid being captured in MCP protocol communication
+ */ const logger = {
+    /**
+   * Log an informational message
+   */ info: (message)=>process.stderr.write(`[INFO] ${message}\n`),
+    /**
+   * Log a debug message
+   */ debug: (message)=>process.stderr.write(`[DEBUG] ${message}\n`),
+    /**
+   * Log a warning message
+   */ warn: (message)=>process.stderr.write(`[WARN] ${message}\n`),
+    /**
+   * Log an error message
+   */ error: (message)=>process.stderr.write(`[ERROR] ${message}\n`),
+    /**
+   * Log a general message
+   */ log: (message)=>process.stderr.write(`[LOG] ${message}\n`)
+};
+/**
+ * Format an error for logging
+ */ function formatError(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+
+// Config loader
+async function loadConfig(configPath) {
+    try {
+        const resolvedPath = path.resolve(process.cwd(), configPath);
+        if (!fs.existsSync(resolvedPath)) {
+            logger.error(`Config file not found: ${resolvedPath}`);
+            return null;
+        }
+        // Handle different file types
+        if (resolvedPath.endsWith(".json")) {
+            const content = fs.readFileSync(resolvedPath, "utf-8");
+            return JSON.parse(content);
+        }
+        if (resolvedPath.endsWith(".js") || resolvedPath.endsWith(".mjs") || resolvedPath.endsWith(".ts") || resolvedPath.endsWith(".mts")) {
+            // For JS/MJS/TS/MTS files, we can dynamically import with Bun
+            // Bun has built-in TypeScript support without requiring transpilation
+            const config = await import(resolvedPath);
+            return config.default || config;
+        }
+        logger.error(`Unsupported config file format: ${resolvedPath}`);
+        return null;
+    } catch (error) {
+        logger.error(`Failed to load config file: ${error instanceof Error ? error.message : String(error)}`);
+        return null;
+    }
+}
+
+function createFigmaRestClient(personalAccessToken) {
+    const api = new Api({
+        personalAccessToken
+    });
+    return {
+        async getFileNodes (fileKey, nodeIds) {
+            const response = await api.getFileNodes({
+                file_key: fileKey
+            }, {
+                ids: nodeIds.join(",")
+            });
+            return response;
+        }
+    };
+}
+/**
+ * https://www.figma.com/:file_type/:file_key/:file_name?node-id=:id
+ *
+ * file_type:
+ *  - design
+ *  - file (legacy)
+ *
+ * Note: While node-id is separated by hyphens ('-') in the URL,
+ * it must be converted to colons (':') when making API calls.
+ * e.g. URL "node-id=794-1987" → API "794:1987"
+ */ function parseFigmaUrl(url) {
+    const __url = (()=>{
+        try {
+            return new URL(url);
+        } catch  {
+            throw new Error(`Invalid URL format: ${url}`);
+        }
+    })();
+    const pathMatch = __url.pathname.match(/^\/(design|file)\/([A-Za-z0-9]+)/);
+    const rawNodeId = __url.searchParams.get("node-id");
+    if (!pathMatch) throw new Error("Invalid Figma URL: Expected format https://www.figma.com/design/{fileKey}/... or /file/{fileKey}/...");
+    if (!rawNodeId) throw new Error("Invalid Figma URL: Missing node-id query parameter");
+    return {
+        fileKey: pathMatch[2],
+        nodeId: rawNodeId.replace(/-/g, ":")
+    };
+}
+
+function createFigmaWebSocketClient(serverUrl) {
+    const WS_URL = serverUrl === "localhost" ? `ws://${serverUrl}` : `wss://${serverUrl}`;
+    // Track which channel each client is in
+    let currentChannel = null;
+    // WebSocket connection and request tracking
+    let ws = null;
+    const pendingRequests = new Map();
+    // Update the connectToFigma function
+    function connectToFigma(port = 3055) {
+        // If already connected, do nothing
+        if (ws && ws.readyState === WebSocket$1.OPEN) {
+            logger.info("Already connected to Figma");
+            return;
+        }
+        const wsUrl = serverUrl === "localhost" ? `${WS_URL}:${port}` : WS_URL;
+        logger.info(`Connecting to Figma socket server at ${wsUrl}...`);
+        ws = new WebSocket$1(wsUrl);
+        ws.on("open", ()=>{
+            logger.info("Connected to Figma socket server");
+            // Reset channel on new connection
+            joinChannel("local-default");
+        });
+        ws.on("message", (data)=>{
+            try {
+                const json = JSON.parse(data);
+                // Handle progress updates
+                if (json.type === "progress_update") {
+                    const progressData = json.message.data;
+                    const requestId = json.id || "";
+                    if (requestId && pendingRequests.has(requestId)) {
+                        const request = pendingRequests.get(requestId);
+                        // Update last activity timestamp
+                        request.lastActivity = Date.now();
+                        // Reset the timeout to prevent timeouts during long-running operations
+                        clearTimeout(request.timeout);
+                        // Create a new timeout
+                        request.timeout = setTimeout(()=>{
+                            if (pendingRequests.has(requestId)) {
+                                logger.error(`Request ${requestId} timed out after extended period of inactivity`);
+                                pendingRequests.delete(requestId);
+                                request.reject(new Error("Request to Figma timed out"));
+                            }
+                        }, 60000); // 60 second timeout for inactivity
+                        // Log progress
+                        logger.info(`Progress update for ${progressData.commandType}: ${progressData.progress}% - ${progressData.message}`);
+                        // For completed updates, we could resolve the request early if desired
+                        if (progressData.status === "completed" && progressData.progress === 100) {
+                            // Optionally resolve early with partial data
+                            // request.resolve(progressData.payload);
+                            // pendingRequests.delete(requestId);
+                            // Instead, just log the completion, wait for final result from Figma
+                            logger.info(`Operation ${progressData.commandType} completed, waiting for final result`);
+                        }
+                    }
+                    return;
+                }
+                // Handle regular responses
+                const myResponse = json.message;
+                logger.debug(`Received message: ${JSON.stringify(myResponse)}`);
+                logger.log("myResponse" + JSON.stringify(myResponse));
+                // Handle response to a request
+                if (myResponse.id && pendingRequests.has(myResponse.id) && (myResponse.result || myResponse.error)) {
+                    const request = pendingRequests.get(myResponse.id);
+                    clearTimeout(request.timeout);
+                    if (myResponse.error) {
+                        logger.error(`Error from Figma: ${myResponse.error}`);
+                        request.reject(new Error(myResponse.error));
+                    } else {
+                        if (myResponse.result) {
+                            request.resolve(myResponse.result);
+                        }
+                    }
+                    pendingRequests.delete(myResponse.id);
+                } else {
+                    // Handle broadcast messages or events not associated with a request ID
+                    logger.info(`Received broadcast message: ${JSON.stringify(myResponse)}`);
+                }
+            } catch (error) {
+                logger.error(`Error parsing message: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        });
+        ws.on("error", (error)=>{
+            logger.error(`Socket error: ${error}`);
+        });
+        ws.on("close", ()=>{
+            logger.info("Disconnected from Figma socket server");
+            ws = null;
+            // Reject all pending requests
+            for (const [id, request] of pendingRequests.entries()){
+                clearTimeout(request.timeout);
+                request.reject(new Error("Connection closed"));
+                pendingRequests.delete(id);
+            }
+            // Attempt to reconnect
+            logger.info("Attempting to reconnect in 2 seconds...");
+            setTimeout(()=>connectToFigma(port), 2000);
+        });
+    }
+    // Function to join a channel
+    async function joinChannel(channelName) {
+        if (!ws || ws.readyState !== WebSocket$1.OPEN) {
+            throw new Error("Not connected to Figma");
+        }
+        try {
+            await sendCommandToFigma("join", {
+                channel: channelName
+            });
+            currentChannel = channelName;
+            logger.info(`Joined channel: ${channelName}`);
+        } catch (error) {
+            logger.error(`Failed to join channel: ${error instanceof Error ? error.message : String(error)}`);
+            throw error;
+        }
+    }
+    // Function to send commands to Figma
+    function sendCommandToFigma(command, params = {}, timeoutMs = 30000) {
+        return new Promise((resolve, reject)=>{
+            // If not connected, try to connect first
+            if (!ws || ws.readyState !== WebSocket$1.OPEN) {
+                connectToFigma();
+                reject(new Error("Not connected to Figma. Attempting to connect..."));
+                return;
+            }
+            // Check if we need a channel for this command
+            const requiresChannel = command !== "join";
+            if (requiresChannel && !currentChannel) {
+                reject(new Error("Must join a channel before sending commands"));
+                return;
+            }
+            const id = v4();
+            const request = {
+                id,
+                type: command === "join" ? "join" : "message",
+                ...command === "join" ? {
+                    channel: params.channel
+                } : {
+                    channel: currentChannel
+                },
+                message: {
+                    id,
+                    command,
+                    params: {
+                        ...params,
+                        commandId: id
+                    }
+                }
+            };
+            // Set timeout for request
+            const timeout = setTimeout(()=>{
+                if (pendingRequests.has(id)) {
+                    pendingRequests.delete(id);
+                    logger.error(`Request ${id} to Figma timed out after ${timeoutMs / 1000} seconds`);
+                    reject(new Error("Request to Figma timed out"));
+                }
+            }, timeoutMs);
+            // Store the promise callbacks to resolve/reject later
+            pendingRequests.set(id, {
+                resolve,
+                reject,
+                timeout,
+                lastActivity: Date.now()
+            });
+            // Send the request
+            logger.info(`Sending command to Figma: ${command}`);
+            logger.debug(`Request details: ${JSON.stringify(request)}`);
+            ws.send(JSON.stringify(request));
+        });
+    }
+    return {
+        connectToFigma,
+        joinChannel,
+        sendCommandToFigma
+    };
+}
+
+/**
+ * Format an object response
+ */ function formatObjectResponse(result) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result)
+            }
+        ]
+    };
+}
+/**
+ * Format a text response
+ */ function formatTextResponse(text) {
+    return {
+        content: [
+            {
+                type: "text",
+                text
+            }
+        ]
+    };
+}
+/**
+ * Format an image response
+ */ function formatImageResponse(imageData, mimeType = "image/png") {
+    return {
+        content: [
+            {
+                type: "image",
+                data: imageData,
+                mimeType
+            }
+        ]
+    };
+}
+/**
+ * Format an error response
+ */ function formatErrorResponse(toolName, error) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: `Error in ${toolName}: ${formatError(error)}`
+            }
+        ]
+    };
+}
+
+function createToolContext(figmaClient, restClient, config, mode) {
+    return {
+        sendCommandToFigma: figmaClient?.sendCommandToFigma ?? null,
+        restClient,
+        mode,
+        extend: config?.extend
+    };
+}
+function resolveRestClient(personalAccessToken, context) {
+    if (context.mode === "websocket") {
+        return null;
+    }
+    if (personalAccessToken) {
+        return createFigmaRestClient(personalAccessToken);
+    }
+    return context.restClient;
+}
+async function fetchNodeData(params, context) {
+    const { fileKey, nodeId, personalAccessToken } = params;
+    const restClient = resolveRestClient(personalAccessToken, context);
+    const { sendCommandToFigma } = context;
+    if (restClient && fileKey) {
+        const response = await restClient.getFileNodes(fileKey, [
+            nodeId
+        ]);
+        const nodeData = response.nodes[nodeId];
+        if (!nodeData) throw new Error(`Node ${nodeId} not found in file ${fileKey}`);
+        return nodeData;
+    }
+    if (sendCommandToFigma) {
+        return await sendCommandToFigma("get_node_info", {
+            nodeId
+        });
+    }
+    throw new Error("No connection available. Provide figmaUrl/fileKey with personalAccessToken or FIGMA_PERSONAL_ACCESS_TOKEN, or use WebSocket mode with Figma Plugin.");
+}
+async function fetchMultipleNodesData(params, context) {
+    const { fileKey, nodeIds, personalAccessToken } = params;
+    const restClient = resolveRestClient(personalAccessToken, context);
+    const { sendCommandToFigma } = context;
+    if (restClient && fileKey) {
+        const response = await restClient.getFileNodes(fileKey, nodeIds);
+        return response.nodes;
+    }
+    if (sendCommandToFigma) {
+        const results = {};
+        await Promise.all(nodeIds.map(async (nodeId)=>{
+            const data = await sendCommandToFigma("get_node_info", {
+                nodeId
+            });
+            results[nodeId] = data;
+        }));
+        return results;
+    }
+    throw new Error("No connection available. Provide figmaUrl/fileKey with personalAccessToken or FIGMA_PERSONAL_ACCESS_TOKEN, or use WebSocket mode with Figma Plugin.");
+}
+function requireWebSocket(context) {
+    if (!context.sendCommandToFigma) throw new Error("WebSocket not available. This tool requires Figma Plugin connection.");
+}
+
+const singleNodeBaseSchema = z.object({
+    figmaUrl: z.url().optional().describe("Figma node URL. Extracts fileKey and nodeId automatically when provided."),
+    fileKey: z.string().optional().describe("Figma file key. Use with nodeId when not using figmaUrl."),
+    nodeId: z.string().optional().describe("Node ID (e.g., '0:1')."),
+    personalAccessToken: z.string().optional().describe("Figma PAT. Falls back to FIGMA_PERSONAL_ACCESS_TOKEN env when not provided.")
+});
+const multiNodeBaseSchema = z.object({
+    fileKey: z.string().optional().describe("Figma file key. Required when WebSocket connection is not available."),
+    nodeIds: z.array(z.string()).describe("Array of node IDs (e.g., ['0:1', '0:2'])"),
+    personalAccessToken: z.string().optional().describe("Figma PAT. Falls back to FIGMA_PERSONAL_ACCESS_TOKEN env when not provided to be used when WebSocket connection is not available.")
+});
+function getSingleNodeParamsSchema(mode) {
+    switch(mode){
+        case "websocket":
+            return singleNodeBaseSchema.pick({
+                nodeId: true
+            }).required();
+        default:
+            return singleNodeBaseSchema;
+    }
+}
+function getMultiNodeParamsSchema(mode) {
+    switch(mode){
+        case "websocket":
+            return multiNodeBaseSchema.pick({
+                nodeIds: true
+            });
+        case "rest":
+            return multiNodeBaseSchema.required({
+                fileKey: true
+            });
+        default:
+            return multiNodeBaseSchema;
+    }
+}
+function resolveSingleNodeParams(params) {
+    if (params.figmaUrl) {
+        const parsed = parseFigmaUrl(params.figmaUrl);
+        return {
+            fileKey: parsed.fileKey,
+            nodeId: parsed.nodeId,
+            personalAccessToken: params.personalAccessToken
+        };
+    }
+    if (!params.nodeId) {
+        throw new Error("Either figmaUrl or nodeId must be provided. Use figmaUrl for automatic parsing, or provide fileKey + nodeId directly.");
+    }
+    return {
+        fileKey: params.fileKey,
+        nodeId: params.nodeId,
+        personalAccessToken: params.personalAccessToken
+    };
+}
+function getSingleNodeDescription(baseDescription, mode) {
+    switch(mode){
+        case "rest":
+            return `${baseDescription} Provide either: (1) figmaUrl (e.g., https://www.figma.com/design/ABC/Name?node-id=0-1), or (2) fileKey + nodeId.`;
+        case "websocket":
+            return `${baseDescription} Provide nodeId. Requires WebSocket connection with Figma Plugin.`;
+        case "all":
+            return `${baseDescription} Provide either: (1) figmaUrl (e.g., https://www.figma.com/design/ABC/Name?node-id=0-1), (2) fileKey + nodeId, or (3) nodeId only for WebSocket mode.`;
+    }
+}
+function getMultiNodeDescription(baseDescription, mode) {
+    switch(mode){
+        case "rest":
+            return `${baseDescription} Provide fileKey + nodeIds.`;
+        case "websocket":
+            return `${baseDescription} Provide nodeIds. Requires WebSocket connection with Figma Plugin.`;
+        case "all":
+            return `${baseDescription} Provide either: (1) fileKey + nodeIds for REST API, or (2) nodeIds only for WebSocket mode. If you have multiple URLs, call get_node_info for each URL instead.`;
+    }
+}
+function registerTools(server, figmaClient, restClient, config, mode) {
+    const context = createToolContext(figmaClient, restClient, config, mode);
+    const singleNodeParamsSchema = getSingleNodeParamsSchema(mode);
+    const multiNodeParamsSchema = getMultiNodeParamsSchema(mode);
+    const shouldRegisterWebSocketOnlyTools = mode === "websocket" || mode === "all";
+    // REST API + WebSocket Tools (hybrid)
+    // These tools support both REST API and WebSocket modes
+    // Component Info Tool (REST API + WebSocket)
+    server.registerTool("get_component_info", {
+        description: getSingleNodeDescription("Get detailed information about a specific component node in Figma.", mode),
+        inputSchema: singleNodeParamsSchema
+    }, async (params)=>{
+        try {
+            const { fileKey, nodeId, personalAccessToken } = resolveSingleNodeParams(params);
+            const result = await fetchNodeData({
+                fileKey,
+                nodeId,
+                personalAccessToken
+            }, context);
+            const node = result.document;
+            if (node.type !== "COMPONENT" && node.type !== "COMPONENT_SET") {
+                return formatErrorResponse("get_component_info", new Error(`Node with ID ${nodeId} is not a component node`));
+            }
+            const key = result.componentSets[nodeId]?.key ?? result.components[nodeId]?.key;
+            if (!key) {
+                return formatErrorResponse("get_component_info", new Error(`${nodeId} is not present in exported component data`));
+            }
+            return formatObjectResponse({
+                name: node.name,
+                key,
+                componentPropertyDefinitions: node.componentPropertyDefinitions
+            });
+        } catch (error) {
+            return formatErrorResponse("get_component_info", error);
+        }
+    });
+    // Node Info Tool (REST API + WebSocket)
+    server.registerTool("get_node_info", {
+        description: getSingleNodeDescription("Get detailed information about a specific node in Figma.", mode),
+        inputSchema: singleNodeParamsSchema
+    }, async (params)=>{
+        try {
+            const { fileKey, nodeId, personalAccessToken } = resolveSingleNodeParams(params);
+            const result = await fetchNodeData({
+                fileKey,
+                nodeId,
+                personalAccessToken
+            }, context);
+            const normalizer = createRestNormalizer(result);
+            const node = normalizer(result.document);
+            const noInferPipeline = figma.createPipeline({
+                shouldInferAutoLayout: false,
+                shouldInferVariableName: false
+            });
+            const inferPipeline = figma.createPipeline({
+                shouldInferAutoLayout: true,
+                shouldInferVariableName: true
+            });
+            const original = noInferPipeline.generateCode(node, {
+                shouldPrintSource: true
+            })?.jsx ?? "Failed to generate summarized node info";
+            const inferred = inferPipeline.generateCode(node, {
+                shouldPrintSource: true
+            })?.jsx ?? "Failed to generate summarized node info";
+            return formatObjectResponse({
+                original: {
+                    data: original,
+                    description: "Original Figma node info"
+                },
+                inferred: {
+                    data: inferred,
+                    description: "AutoLayout Inferred Figma node info"
+                }
+            });
+        } catch (error) {
+            return formatTextResponse(`Error in get_node_info: ${formatError(error)}\n\n⚠️ Please make sure you have the latest version of the Figma library.`);
+        }
+    });
+    // Nodes Info Tool (REST API + WebSocket)
+    server.registerTool("get_nodes_info", {
+        description: getMultiNodeDescription("Get detailed information about multiple nodes in Figma.", mode),
+        inputSchema: multiNodeParamsSchema
+    }, async ({ fileKey, nodeIds, personalAccessToken })=>{
+        try {
+            if (nodeIds.length === 0) {
+                return formatErrorResponse("get_nodes_info", new Error("No node IDs provided"));
+            }
+            const nodesData = await fetchMultipleNodesData({
+                fileKey,
+                nodeIds,
+                personalAccessToken
+            }, context);
+            const results = nodeIds.map((nodeId)=>{
+                const nodeData = nodesData[nodeId];
+                if (!nodeData) {
+                    return {
+                        nodeId,
+                        error: `Node ${nodeId} not found`
+                    };
+                }
+                const normalizer = createRestNormalizer(nodeData);
+                const node = normalizer(nodeData.document);
+                const noInferPipeline = figma.createPipeline({
+                    shouldInferAutoLayout: false,
+                    shouldInferVariableName: false
+                });
+                const inferPipeline = figma.createPipeline({
+                    shouldInferAutoLayout: true,
+                    shouldInferVariableName: true
+                });
+                const original = noInferPipeline.generateCode(node, {
+                    shouldPrintSource: true
+                })?.jsx ?? "Failed to generate summarized node info";
+                const inferred = inferPipeline.generateCode(node, {
+                    shouldPrintSource: true
+                })?.jsx ?? "Failed to generate summarized node info";
+                return {
+                    nodeId,
+                    original: {
+                        data: original,
+                        description: "Original Figma node info"
+                    },
+                    inferred: {
+                        data: inferred,
+                        description: "AutoLayout Inferred Figma node info"
+                    }
+                };
+            });
+            return formatObjectResponse(results);
+        } catch (error) {
+            return formatTextResponse(`Error in get_nodes_info: ${formatError(error)}\n\n⚠️ Please make sure you have the latest version of the Figma library.`);
+        }
+    });
+    // Get Node React Code Tool (REST API + WebSocket)
+    server.registerTool("get_node_react_code", {
+        description: getSingleNodeDescription("Get the React code for a specific node in Figma.", mode),
+        inputSchema: singleNodeParamsSchema
+    }, async (params)=>{
+        try {
+            const { fileKey, nodeId, personalAccessToken } = resolveSingleNodeParams(params);
+            const result = await fetchNodeData({
+                fileKey,
+                nodeId,
+                personalAccessToken
+            }, context);
+            const normalizer = createRestNormalizer(result);
+            const pipeline = react.createPipeline({
+                shouldInferAutoLayout: true,
+                shouldInferVariableName: true,
+                extend: context.extend
+            });
+            const generated = pipeline.generateCode(normalizer(result.document), {
+                shouldPrintSource: false
+            });
+            if (!generated) {
+                return formatTextResponse("Failed to generate code\n\n⚠️ Please make sure you have the latest version of the Figma library.");
+            }
+            return formatTextResponse(`${generated.imports}\n\n${generated.jsx}`);
+        } catch (error) {
+            return formatTextResponse(`Error in get_node_react_code: ${formatError(error)}\n\n⚠️ Please make sure you have the latest version of the Figma library.`);
+        }
+    });
+    // Find Layers Tool (REST API + WebSocket)
+    server.registerTool("find_nodes", {
+        description: getSingleNodeDescription("Find layers by name within a Figma node's subtree. Returns a flat array of matching nodes with their IDs.", mode),
+        inputSchema: singleNodeParamsSchema.extend({
+            name: z.string().describe("Regex pattern to match layer names (e.g., 'Usage', 'Do$').")
+        })
+    }, async (params)=>{
+        try {
+            const { fileKey, nodeId, personalAccessToken } = resolveSingleNodeParams(params);
+            const result = await fetchNodeData({
+                fileKey,
+                nodeId,
+                personalAccessToken
+            }, context);
+            const normalizer = createRestNormalizer(result);
+            const node = normalizer(result.document);
+            let pattern;
+            try {
+                pattern = new RegExp(params.name);
+            } catch  {
+                return formatErrorResponse("find_nodes", new Error(`Invalid regex pattern: ${params.name}`));
+            }
+            const matches = collectMatchingNodes(node, pattern);
+            return formatObjectResponse(matches);
+        } catch (error) {
+            return formatErrorResponse("find_nodes", error);
+        }
+    });
+    // Utility Tools (No Figma connection required)
+    // Retrieve Color Variable Names Tool
+    server.registerTool("retrieve_color_variable_names", {
+        description: "Retrieve available SEED Design color variable names by scope. No Figma connection required.",
+        inputSchema: z.object({
+            scope: z.enum([
+                "fg",
+                "bg",
+                "stroke",
+                "palette"
+            ]).array().describe("The scope of the color variable names to retrieve")
+        })
+    }, async ({ scope })=>{
+        try {
+            const result = getFigmaColorVariableNames(scope);
+            return formatObjectResponse(result);
+        } catch (error) {
+            return formatErrorResponse("retrieve_color_variable_names", error);
+        }
+    });
+    if (shouldRegisterWebSocketOnlyTools) {
+        // WebSocket Only Tools
+        server.registerTool("join_channel", {
+            description: "Join a specific channel to communicate with Figma (WebSocket mode only)",
+            inputSchema: z.object({
+                channel: z.string().describe("The name of the channel to join").default("")
+            })
+        }, async ({ channel })=>{
+            try {
+                if (!figmaClient) return formatErrorResponse("join_channel", new Error("WebSocket not available. This tool requires Figma Plugin connection."));
+                if (!channel) // If no channel provided, ask the user for input
+                return {
+                    ...formatTextResponse("Please provide a channel name to join:"),
+                    followUp: {
+                        tool: "join_channel",
+                        description: "Join the specified channel"
+                    }
+                };
+                await figmaClient.joinChannel(channel);
+                return formatTextResponse(`Successfully joined channel: ${channel}`);
+            } catch (error) {
+                return formatErrorResponse("join_channel", error);
+            }
+        });
+        // Document Info Tool
+        server.registerTool("get_document_info", {
+            description: "Get detailed information about the current Figma document (WebSocket mode only)"
+        }, async ()=>{
+            try {
+                requireWebSocket(context);
+                const result = await context.sendCommandToFigma("get_document_info");
+                return formatObjectResponse(result);
+            } catch (error) {
+                return formatErrorResponse("get_document_info", error);
+            }
+        });
+        // Selection Tool
+        server.registerTool("get_selection", {
+            description: "Get information about the current selection in Figma (WebSocket mode only)"
+        }, async ()=>{
+            try {
+                requireWebSocket(context);
+                const result = await context.sendCommandToFigma("get_selection");
+                return formatObjectResponse(result);
+            } catch (error) {
+                return formatErrorResponse("get_selection", error);
+            }
+        });
+        // Annotation Tool
+        server.registerTool("add_annotations", {
+            description: "Add annotations to multiple nodes in Figma (WebSocket mode only)",
+            inputSchema: z.object({
+                annotations: z.array(z.object({
+                    nodeId: z.string().describe("The ID of the node to add an annotation to"),
+                    labelMarkdown: z.string().describe("The markdown label for the annotation, do not escape newlines")
+                }))
+            })
+        }, async ({ annotations })=>{
+            try {
+                requireWebSocket(context);
+                await context.sendCommandToFigma("add_annotations", {
+                    annotations
+                });
+                return formatTextResponse(`Annotations added to nodes ${annotations.map((annotation)=>annotation.nodeId).join(", ")}`);
+            } catch (error) {
+                return formatErrorResponse("add_annotations", error);
+            }
+        });
+        // Get Annotations Tool
+        server.registerTool("get_annotations", {
+            description: "Get annotations for a specific node in Figma (WebSocket mode only)",
+            inputSchema: z.object({
+                nodeId: z.string().describe("The ID of the node to get annotations for")
+            })
+        }, async ({ nodeId })=>{
+            try {
+                requireWebSocket(context);
+                const result = await context.sendCommandToFigma("get_annotations", {
+                    nodeId
+                });
+                return formatObjectResponse(result);
+            } catch (error) {
+                return formatErrorResponse("get_annotations", error);
+            }
+        });
+        // Export Node as Image Tool
+        server.registerTool("export_node_as_image", {
+            description: "Export a node as an image from Figma (WebSocket mode only)",
+            inputSchema: z.object({
+                nodeId: z.string().describe("The ID of the node to export"),
+                format: z.enum([
+                    "PNG",
+                    "JPG",
+                    "SVG",
+                    "PDF"
+                ]).optional().describe("Export format"),
+                scale: z.number().positive().optional().describe("Export scale")
+            })
+        }, async ({ nodeId, format, scale })=>{
+            try {
+                requireWebSocket(context);
+                const result = await context.sendCommandToFigma("export_node_as_image", {
+                    nodeId,
+                    format: format || "PNG",
+                    scale: scale || 1
+                });
+                const typedResult = result;
+                return formatImageResponse(typedResult.base64, typedResult.mimeType || "image/png");
+            } catch (error) {
+                return formatErrorResponse("export_node_as_image", error);
+            }
+        });
+    }
+}
+function collectMatchingNodes(node, pattern) {
+    const results = [];
+    if ("name" in node && pattern.test(node.name)) {
+        results.push({
+            id: node.id,
+            name: node.name,
+            type: node.type
+        });
+    }
+    if ("children" in node && node.children) {
+        for (const child of node.children){
+            results.push(...collectMatchingNodes(child, pattern));
+        }
+    }
+    return results;
+}
+// editing tools require WebSocket client
+function registerEditingTools(server, figmaClient) {
+    const { sendCommandToFigma } = figmaClient;
+    // Clone Node Tool
+    server.registerTool("clone_node", {
+        description: "Clone an existing node in Figma (WebSocket mode only)",
+        inputSchema: z.object({
+            nodeId: z.string().describe("The ID of the node to clone"),
+            x: z.number().optional().describe("New X position for the clone"),
+            y: z.number().optional().describe("New Y position for the clone")
+        })
+    }, async ({ nodeId, x, y })=>{
+        try {
+            const result = await sendCommandToFigma("clone_node", {
+                nodeId,
+                x,
+                y
+            });
+            const typedResult = result;
+            return formatTextResponse(`Cloned node with new ID: ${typedResult.id}${x !== undefined && y !== undefined ? ` at position (${x}, ${y})` : ""}`);
+        } catch (error) {
+            return formatErrorResponse("clone_node", error);
+        }
+    });
+    server.registerTool("set_fill_color", {
+        description: "Set the fill color of a node (WebSocket mode only)",
+        inputSchema: z.object({
+            nodeId: z.string().describe("The ID of the node to set the fill color of"),
+            colorToken: z.string().describe("The color token to set the fill color to. Format: `{category}/{name}`. Example: `bg/brand`")
+        })
+    }, async ({ nodeId, colorToken })=>{
+        try {
+            await sendCommandToFigma("set_fill_color", {
+                nodeId,
+                colorToken
+            });
+            return formatTextResponse(`Fill color set to ${colorToken}`);
+        } catch (error) {
+            return formatErrorResponse("set_fill_color", error);
+        }
+    });
+    server.registerTool("set_stroke_color", {
+        description: "Set the stroke color of a node (WebSocket mode only)",
+        inputSchema: z.object({
+            nodeId: z.string().describe("The ID of the node to set the stroke color of"),
+            colorToken: z.string().describe("The color token to set the stroke color to. Format: `{category}/{name}`. Example: `stroke/neutral`")
+        })
+    }, async ({ nodeId, colorToken })=>{
+        try {
+            await sendCommandToFigma("set_stroke_color", {
+                nodeId,
+                colorToken
+            });
+            return formatTextResponse(`Stroke color set to ${colorToken}`);
+        } catch (error) {
+            return formatErrorResponse("set_stroke_color", error);
+        }
+    });
+    server.registerTool("set_auto_layout", {
+        description: "Set the auto layout of a node (WebSocket mode only)",
+        inputSchema: z.object({
+            nodeId: z.string().describe("The ID of the node to set the auto layout of"),
+            layoutMode: z.enum([
+                "HORIZONTAL",
+                "VERTICAL"
+            ]).optional().describe("The layout mode to set"),
+            layoutWrap: z.enum([
+                "NO_WRAP",
+                "WRAP"
+            ]).optional().describe("The layout wrap to set"),
+            primaryAxisAlignItems: z.enum([
+                "MIN",
+                "MAX",
+                "CENTER",
+                "SPACE_BETWEEN"
+            ]).optional().describe("The primary axis align items to set"),
+            counterAxisAlignItems: z.enum([
+                "MIN",
+                "MAX",
+                "CENTER",
+                "BASELINE"
+            ]).optional().describe("The counter axis align items to set"),
+            itemSpacing: z.number().optional().describe("The item spacing to set"),
+            horizontalPadding: z.number().optional().describe("The horizontal padding to set"),
+            verticalPadding: z.number().optional().describe("The vertical padding to set"),
+            paddingLeft: z.number().optional().describe("The padding left to set (when left != right)"),
+            paddingRight: z.number().optional().describe("The padding right to set (when left != right)"),
+            paddingTop: z.number().optional().describe("The padding top to set (when top != bottom)"),
+            paddingBottom: z.number().optional().describe("The padding bottom to set (when top != bottom)")
+        })
+    }, async ({ nodeId, layoutMode, layoutWrap, primaryAxisAlignItems, counterAxisAlignItems, itemSpacing, horizontalPadding, verticalPadding, paddingLeft, paddingRight, paddingTop, paddingBottom })=>{
+        try {
+            await sendCommandToFigma("set_auto_layout", {
+                nodeId,
+                layoutMode,
+                layoutWrap,
+                primaryAxisAlignItems,
+                counterAxisAlignItems,
+                itemSpacing,
+                horizontalPadding,
+                verticalPadding,
+                paddingLeft,
+                paddingRight,
+                paddingTop,
+                paddingBottom
+            });
+            return formatTextResponse(`Layout set to ${layoutMode}`);
+        } catch (error) {
+            return formatErrorResponse("set_auto_layout", error);
+        }
+    });
+    server.registerTool("set_size", {
+        description: "Set the size of a node (WebSocket mode only)",
+        inputSchema: z.object({
+            nodeId: z.string().describe("The ID of the node to set the size of"),
+            layoutSizingHorizontal: z.enum([
+                "HUG",
+                "FILL"
+            ]).optional().describe("The horizontal layout sizing to set (exclusive with width)"),
+            layoutSizingVertical: z.enum([
+                "HUG",
+                "FILL"
+            ]).optional().describe("The vertical layout sizing to set (exclusive with height)"),
+            width: z.number().optional().describe("The width to set (raw value)"),
+            height: z.number().optional().describe("The height to set (raw value)")
+        })
+    }, async ({ nodeId, layoutSizingHorizontal, layoutSizingVertical, width, height })=>{
+        try {
+            await sendCommandToFigma("set_size", {
+                nodeId,
+                layoutSizingHorizontal,
+                layoutSizingVertical,
+                width,
+                height
+            });
+            return formatTextResponse(`Size set to ${width ?? layoutSizingHorizontal}x${height ?? layoutSizingVertical}`);
+        } catch (error) {
+            return formatErrorResponse("set_size", error);
+        }
+    });
+}
+
+function registerPrompts(server) {
+    server.prompt("react_implementation_strategy", "Best practices for implementing React components", (_extra)=>{
+        return {
+            messages: [
+                {
+                    role: "assistant",
+                    content: {
+                        type: "text",
+                        text: `When implementing React components, follow these best practices:
+  
+  1. Start with selection:
+     - First use get_selection() to understand the current selection
+     - If no selection ask user to select single node
+  
+  2. Get React code of the selected node:
+     - Use get_node_react_code() to get the React code of the selected node
+     - If no selection ask user to select single node
+  `
+                    }
+                }
+            ],
+            description: "Best practices for implementing React components"
+        };
+    });
+    server.prompt("read_design_strategy", "Best practices for reading Figma designs", (_extra)=>{
+        return {
+            messages: [
+                {
+                    role: "assistant",
+                    content: {
+                        type: "text",
+                        text: `When reading Figma designs, follow these best practices:
+  
+  1. Start with selection:
+     - First use get_selection() to understand the current selection
+     - If no selection ask user to select single or multiple nodes
+  
+  2. Get node infos of the selected nodes:
+     - Use get_nodes_info() to get the information of the selected nodes
+     - If no selection ask user to select single or multiple nodes
+  `
+                    }
+                }
+            ],
+            description: "Best practices for reading Figma designs"
+        };
+    });
+}
+
+const channels = new Map();
+function sendJson(ws, data) {
+    ws.send(JSON.stringify(data));
+}
+function broadcastToChannel(channelName, message, excludeWs) {
+    const clients = channels.get(channelName);
+    if (!clients) return;
+    for (const client of clients){
+        if (client !== excludeWs && client.readyState === WebSocket.OPEN) {
+            sendJson(client, message);
+        }
+    }
+}
+function handleJoin(ws, data) {
+    const { channel: channelName, id } = data;
+    if (!channelName || typeof channelName !== "string") {
+        sendJson(ws, {
+            type: "error",
+            message: "Channel name is required"
+        });
+        return;
+    }
+    if (!channels.has(channelName)) {
+        channels.set(channelName, new Set());
+    }
+    const channelClients = channels.get(channelName);
+    if (!channelClients) {
+        sendJson(ws, {
+            type: "error",
+            message: "Failed to join channel"
+        });
+        return;
+    }
+    channelClients.add(ws);
+    // Notify client they joined successfully
+    sendJson(ws, {
+        type: "system",
+        message: `Joined channel: ${channelName}`,
+        channel: channelName
+    });
+    // Send connection confirmation
+    console.log("Sending message to client:", id);
+    sendJson(ws, {
+        type: "system",
+        message: {
+            id,
+            result: `Connected to channel: ${channelName}`
+        },
+        channel: channelName
+    });
+    // Notify other clients in channel
+    broadcastToChannel(channelName, {
+        type: "system",
+        message: "A new user has joined the channel",
+        channel: channelName
+    }, ws);
+}
+function handleMessage(ws, data) {
+    const { channel: channelName, message } = data;
+    if (!channelName || typeof channelName !== "string") {
+        sendJson(ws, {
+            type: "error",
+            message: "Channel name is required"
+        });
+        return;
+    }
+    const channelClients = channels.get(channelName);
+    if (!channelClients?.has(ws)) {
+        sendJson(ws, {
+            type: "error",
+            message: "You must join the channel first"
+        });
+        return;
+    }
+    // Broadcast to all clients in the channel
+    for (const client of channelClients){
+        if (client.readyState === WebSocket.OPEN) {
+            console.log("Broadcasting message to client:", message);
+            sendJson(client, {
+                type: "broadcast",
+                message,
+                sender: client === ws ? "You" : "User",
+                channel: channelName
+            });
+        }
+    }
+}
+// WebSocket Event Handlers
+function handleConnection(ws) {
+    console.log("New client connected");
+    sendJson(ws, {
+        type: "system",
+        message: "Please join a channel to start chatting"
+    });
+}
+function handleWebSocketMessage(ws, rawMessage) {
+    try {
+        console.log("Received message from client:", rawMessage);
+        const data = JSON.parse(rawMessage);
+        switch(data.type){
+            case "join":
+                handleJoin(ws, data);
+                break;
+            case "message":
+                handleMessage(ws, data);
+                break;
+            default:
+                console.warn(`Unknown message type: ${data.type}`);
+        }
+    } catch (err) {
+        console.error("Error handling message:", err);
+    }
+}
+function handleClose(ws) {
+    console.log("Client disconnected");
+    for (const [channelName, clients] of channels){
+        if (clients.has(ws)) {
+            clients.delete(ws);
+            broadcastToChannel(channelName, {
+                type: "system",
+                message: "A user has left the channel",
+                channel: channelName
+            });
+        }
+    }
+}
+// Server
+async function startWebSocketServer(port) {
+    const server = Bun.serve({
+        port,
+        // uncomment this to allow connections in windows wsl
+        // hostname: "0.0.0.0",
+        fetch (req, server) {
+            // Handle CORS preflight
+            if (req.method === "OPTIONS") {
+                return new Response(null, {
+                    headers: {
+                        "Access-Control-Allow-Origin": "*",
+                        "Access-Control-Allow-Methods": "GET, POST, OPTIONS",
+                        "Access-Control-Allow-Headers": "Content-Type, Authorization"
+                    }
+                });
+            }
+            // Handle WebSocket upgrade
+            if (server.upgrade(req, {
+                headers: {
+                    "Access-Control-Allow-Origin": "*"
+                },
+                data: {}
+            })) {
+                return;
+            }
+            // Return response for non-WebSocket requests
+            return new Response("WebSocket server running", {
+                headers: {
+                    "Access-Control-Allow-Origin": "*"
+                }
+            });
+        },
+        websocket: {
+            open: handleConnection,
+            message: handleWebSocketMessage,
+            close: handleClose
+        }
+    });
+    console.log(`WebSocket server running on port ${server.port}`);
+    return server;
+}
+
+// Helper Functions
+function getFigmaAccessToken() {
+    return process.env["FIGMA_PERSONAL_ACCESS_TOKEN"]?.trim();
+}
+function createFigmaClient(serverUrl, mode) {
+    const pat = getFigmaAccessToken();
+    const resolvedUrl = serverUrl ?? "localhost";
+    switch(mode){
+        case "rest":
+            {
+                if (!pat) {
+                    logger.warn("REST mode requires FIGMA_PERSONAL_ACCESS_TOKEN. Running without Figma client.");
+                } else {
+                    logger.info("REST mode enabled. Using REST API only.");
+                }
+                return null;
+            }
+        case "websocket":
+            {
+                logger.info(`WebSocket mode enabled. Client connecting to: ${resolvedUrl}`);
+                return createFigmaWebSocketClient(resolvedUrl);
+            }
+        case "all":
+            {
+                if (pat) {
+                    logger.info("FIGMA_PERSONAL_ACCESS_TOKEN found. REST API enabled for figmaUrl/fileKey requests.");
+                }
+                logger.info(`WebSocket client connecting to: ${resolvedUrl}`);
+                return createFigmaWebSocketClient(resolvedUrl);
+            }
+    }
+}
+function createRestClient(mode) {
+    if (mode === "websocket") {
+        return null;
+    }
+    const pat = getFigmaAccessToken();
+    if (!pat) {
+        if (mode === "rest") {
+            logger.warn("REST mode requires FIGMA_PERSONAL_ACCESS_TOKEN. REST API will not be available.");
+        }
+        return null;
+    }
+    logger.info("Initializing REST API client with PAT from environment");
+    return createFigmaRestClient(pat);
+}
+async function loadMcpConfig(configPath) {
+    if (!configPath) return null;
+    const config = await loadConfig(configPath);
+    if (!config) return null;
+    logger.info(`Loaded configuration from: ${configPath}`);
+    if (config.extend?.componentHandlers?.length) {
+        logger.info(`Found ${config.extend.componentHandlers.length} custom component handlers`);
+    }
+    return config;
+}
+function connectFigmaClient(figmaClient) {
+    if (!figmaClient) return;
+    try {
+        figmaClient.connectToFigma();
+    } catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        logger.warn(`Could not connect to Figma initially: ${message}`);
+        if (getFigmaAccessToken()) {
+            logger.info("REST API fallback available via FIGMA_PERSONAL_ACCESS_TOKEN");
+        } else {
+            logger.warn("Will try to connect when the first command is sent");
+        }
+    }
+}
+async function startMcpServer(options = {}) {
+    const { serverUrl, experimental, configPath, mode = "all" } = options;
+    const config = await loadMcpConfig(configPath);
+    const figmaClient = createFigmaClient(serverUrl, mode);
+    const restClient = createRestClient(mode);
+    const server = new McpServer({
+        name: "SEED Design MCP",
+        version
+    });
+    registerTools(server, figmaClient, restClient, config, mode);
+    registerPrompts(server);
+    if (experimental) {
+        if (mode === "rest") {
+            logger.warn("Experimental editing tools not available in REST mode. Skipping.");
+        } else if (figmaClient) {
+            registerEditingTools(server, figmaClient);
+        } else {
+            logger.warn("Experimental editing tools require WebSocket connection. Skipping.");
+        }
+    }
+    connectFigmaClient(figmaClient);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info(`FigmaMCP server running on stdio (mode: ${mode})`);
+}
+// CLI
+const cli = cac("@seed-design/mcp");
+cli.command("", "Start the MCP server").option("--server <server>", "WebSocket server URL. If not provided and FIGMA_PERSONAL_ACCESS_TOKEN is set, REST API mode will be used.").option("--experimental", "Enable experimental features", {
+    default: false
+}).option("--config <config>", "Path to configuration file (.js, .mjs, .ts, .mts)").option("--mode <mode>", "Tool registration mode: 'rest' (REST API tools only), 'websocket' (WebSocket tools only), or 'all' (default)").action(async (options)=>{
+    const mode = options.mode;
+    if (mode && ![
+        "rest",
+        "websocket",
+        "all"
+    ].includes(mode)) {
+        console.error(`Invalid mode: ${mode}. Use 'rest', 'websocket', or 'all'.`);
+        process.exit(1);
+    }
+    await startMcpServer({
+        serverUrl: options.server,
+        experimental: options.experimental,
+        configPath: options.config,
+        mode
+    });
+});
+cli.command("socket", "Start the WebSocket server").option("--port <port>", "Port number", {
+    default: 3055
+}).action(async (options)=>{
+    await startWebSocketServer(options.port);
+});
+cli.help();
+cli.version(version);
+cli.parse();