@seed-design/mcp 1.2.1 → 1.3.1

package/bin/index.mjs

@@ -2,12 +2,15 @@
 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';
-import fs from 'node:fs';
-import path from 'node:path';
+
+var version = "1.3.1";
 
 /**
  * Custom logging module that writes to stderr instead of stdout
@@ -38,6 +41,76 @@ import path from 'node:path';
     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
@@ -263,85 +336,158 @@ function createFigmaWebSocketClient(serverUrl) {
     };
 }
 
-function registerTools(server, figmaClient, config = {}) {
-    const { joinChannel, sendCommandToFigma } = figmaClient;
-    const { extend } = config ?? {};
-    // join_channel tool
-    server.tool("join_channel", "Join a specific channel to communicate with Figma", {
-        channel: z.string().describe("The name of the channel to join").default("")
-    }, async ({ channel })=>{
-        try {
-            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 joinChannel(channel);
-            return formatTextResponse(`Successfully joined channel: ${channel}`);
-        } catch (error) {
-            return formatErrorResponse("join_channel", error);
-        }
-    });
-    // Document Info Tool
-    server.tool("get_document_info", "Get detailed information about the current Figma document", {}, async ()=>{
-        try {
-            const result = await sendCommandToFigma("get_document_info");
-            return formatObjectResponse(result);
-        } catch (error) {
-            return formatErrorResponse("get_document_info", error);
-        }
-    });
-    // Selection Tool
-    server.tool("get_selection", "Get information about the current selection in Figma", {}, async ()=>{
-        try {
-            const result = await sendCommandToFigma("get_selection");
-            return formatObjectResponse(result);
-        } catch (error) {
-            return formatErrorResponse("get_selection", error);
-        }
-    });
-    // Annotation Tool
-    server.tool("add_annotations", "Add annotations to multiple nodes in Figma", {
-        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 {
-            await 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.tool("get_annotations", "Get annotations for a specific node in Figma", {
-        nodeId: z.string().describe("The ID of the node to get annotations for")
-    }, async ({ nodeId })=>{
-        try {
-            const result = await sendCommandToFigma("get_annotations", {
+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
             });
-            return formatObjectResponse(result);
-        } catch (error) {
-            return formatErrorResponse("get_annotations", error);
-        }
-    });
-    // Component Info Tool
-    server.tool("get_component_info", "Get detailed information about a specific component node in Figma", {
-        nodeId: z.string().describe("The ID of the component node to get information about")
-    }, async ({ nodeId })=>{
-        try {
-            const result = 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`));
@@ -356,17 +502,21 @@ function registerTools(server, figmaClient, config = {}) {
                 componentPropertyDefinitions: node.componentPropertyDefinitions
             });
         } catch (error) {
-            return formatErrorResponse("get_node_info", error);
+            return formatErrorResponse("get_component_info", error);
         }
     });
-    // Node Info Tool
-    server.tool("get_node_info", "Get detailed information about a specific node in Figma", {
-        nodeId: z.string().describe("The ID of the node to get information about")
-    }, async ({ nodeId })=>{
+    // 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 result = await sendCommandToFigma("get_node_info", {
-                nodeId
-            });
+            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({
@@ -390,24 +540,37 @@ function registerTools(server, figmaClient, config = {}) {
                 },
                 inferred: {
                     data: inferred,
-                    description: "AutoLayout Inferred Figma node info (fix suggestions)"
+                    description: "AutoLayout Inferred Figma node info"
                 }
             });
         } catch (error) {
-            return formatTextResponse(`Error in get_node_info: ${formatError(error)}\n\n⚠️ Figma 라이브러리가 최신 버전인지 확인해주세요.`);
+            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
-    server.tool("get_nodes_info", "Get detailed information about multiple nodes in Figma", {
-        nodeIds: z.array(z.string()).describe("Array of node IDs to get information about")
-    }, async ({ nodeIds })=>{
+    // 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 {
-            const results = await Promise.all(nodeIds.map(async (nodeId)=>{
-                const result = await sendCommandToFigma("get_node_info", {
-                    nodeId
-                });
-                const normalizer = createRestNormalizer(result);
-                const node = normalizer(result.document);
+            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
@@ -430,70 +593,56 @@ function registerTools(server, figmaClient, config = {}) {
                     },
                     inferred: {
                         data: inferred,
-                        description: "AutoLayout Inferred Figma node info (fix suggestions)"
+                        description: "AutoLayout Inferred Figma node info"
                     }
                 };
-            }));
+            });
             return formatObjectResponse(results);
         } catch (error) {
-            return formatTextResponse(`Error in get_nodes_info: ${formatError(error)}\n\n⚠️ Figma 라이브러리가 최신 버전인지 확인해주세요.`);
+            return formatTextResponse(`Error in get_nodes_info: ${formatError(error)}\n\n⚠️ Please make sure you have the latest version of the Figma library.`);
         }
     });
-    server.tool("get_node_react_code", "Get the React code for a specific node in Figma", {
-        nodeId: z.string().describe("The ID of the node to get code for")
-    }, async ({ nodeId })=>{
+    // 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 result = await sendCommandToFigma("get_node_info", {
-                nodeId
-            });
+            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
+                extend: context.extend
             });
             const generated = pipeline.generateCode(normalizer(result.document), {
                 shouldPrintSource: false
             });
             if (!generated) {
-                return formatTextResponse("Failed to generate code\n\n⚠️ Figma 라이브러리가 최신 버전인지 확인해주세요.");
+                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⚠️ Figma 라이브러리가 최신 버전인지 확인해주세요.`);
-        }
-    });
-    // Export Node as Image Tool
-    server.tool("export_node_as_image", "Export a node as an image from Figma", {
-        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 {
-            const result = await 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);
+            return formatTextResponse(`Error in get_node_react_code: ${formatError(error)}\n\n⚠️ Please make sure you have the latest version of the Figma library.`);
         }
     });
+    // Utility Tools (No Figma connection required)
     // Retrieve Color Variable Names Tool
-    server.tool("retrieve_color_variable_names", "Retrieve available color variable names in scope", {
-        scope: z.enum([
-            "fg",
-            "bg",
-            "stroke",
-            "palette"
-        ]).array().describe("The scope of the color variable names to retrieve")
+    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);
@@ -502,14 +651,131 @@ function registerTools(server, figmaClient, config = {}) {
             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);
+            }
+        });
+    }
 }
+// editing tools require WebSocket client
 function registerEditingTools(server, figmaClient) {
     const { sendCommandToFigma } = figmaClient;
     // Clone Node Tool
-    server.tool("clone_node", "Clone an existing node in Figma", {
-        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")
+    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", {
@@ -523,9 +789,12 @@ function registerEditingTools(server, figmaClient) {
             return formatErrorResponse("clone_node", error);
         }
     });
-    server.tool("set_fill_color", "Set the fill color of a node", {
-        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`")
+    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", {
@@ -537,9 +806,12 @@ function registerEditingTools(server, figmaClient) {
             return formatErrorResponse("set_fill_color", error);
         }
     });
-    server.tool("set_stroke_color", "Set the stroke color of a node", {
-        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`")
+    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", {
@@ -551,35 +823,38 @@ function registerEditingTools(server, figmaClient) {
             return formatErrorResponse("set_stroke_color", error);
         }
     });
-    server.tool("set_auto_layout", "Set the auto layout of a node", {
-        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)")
+    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", {
@@ -601,18 +876,21 @@ function registerEditingTools(server, figmaClient) {
             return formatErrorResponse("set_auto_layout", error);
         }
     });
-    server.tool("set_size", "Set the size of a node", {
-        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)")
+    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", {
@@ -678,63 +956,135 @@ function registerPrompts(server) {
     });
 }
 
-var version = "1.2.1";
-
-// 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);
+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);
         }
-        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;
+    }
+}
+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 with ID if provided
+    if (id) {
+        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
+            });
         }
-        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;
     }
 }
-
-// Initialize CLI
-const cli = cac("@seed-design/mcp");
-// Store WebSocket clients by channel
-const channels = new Map();
-function handleWebSocketConnection(ws) {
+// WebSocket Event Handlers
+function handleConnection(ws) {
     console.log("New client connected");
-    ws.send(JSON.stringify({
+    sendJson(ws, {
         type: "system",
         message: "Please join a channel to start chatting"
-    }));
-    ws.close = ()=>{
-        console.log("Client disconnected");
-        channels.forEach((clients, channelName)=>{
-            if (clients.has(ws)) {
-                clients.delete(ws);
-                clients.forEach((client)=>{
-                    if (client.readyState === WebSocket.OPEN) {
-                        client.send(JSON.stringify({
-                            type: "system",
-                            message: "A user has left the channel",
-                            channel: channelName
-                        }));
-                    }
-                });
-            }
-        });
-    };
+    });
+}
+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,
@@ -752,12 +1102,14 @@ async function startWebSocketServer(port) {
                 });
             }
             // Handle WebSocket upgrade
-            const success = server.upgrade(req, {
+            if (server.upgrade(req, {
                 headers: {
                     "Access-Control-Allow-Origin": "*"
-                }
-            });
-            if (success) return;
+                },
+                data: {}
+            })) {
+                return;
+            }
             // Return response for non-WebSocket requests
             return new Response("WebSocket server running", {
                 headers: {
@@ -766,143 +1118,130 @@ async function startWebSocketServer(port) {
             });
         },
         websocket: {
-            open: handleWebSocketConnection,
-            message (ws, message) {
-                try {
-                    console.log("Received message from client:", message);
-                    const data = JSON.parse(message);
-                    if (data.type === "join") {
-                        const channelName = data.channel;
-                        if (!channelName || typeof channelName !== "string") {
-                            ws.send(JSON.stringify({
-                                type: "error",
-                                message: "Channel name is required"
-                            }));
-                            return;
-                        }
-                        // Create channel if it doesn't exist
-                        if (!channels.has(channelName)) {
-                            channels.set(channelName, new Set());
-                        }
-                        // Add client to channel
-                        const channelClients = channels.get(channelName);
-                        channelClients.add(ws);
-                        // Notify client they joined successfully
-                        ws.send(JSON.stringify({
-                            type: "system",
-                            message: `Joined channel: ${channelName}`,
-                            channel: channelName
-                        }));
-                        console.log("Sending message to client:", data.id);
-                        ws.send(JSON.stringify({
-                            type: "system",
-                            message: {
-                                id: data.id,
-                                result: "Connected to channel: " + channelName
-                            },
-                            channel: channelName
-                        }));
-                        // Notify other clients in channel
-                        channelClients.forEach((client)=>{
-                            if (client !== ws && client.readyState === WebSocket.OPEN) {
-                                client.send(JSON.stringify({
-                                    type: "system",
-                                    message: "A new user has joined the channel",
-                                    channel: channelName
-                                }));
-                            }
-                        });
-                        return;
-                    }
-                    // Handle regular messages
-                    if (data.type === "message") {
-                        const channelName = data.channel;
-                        if (!channelName || typeof channelName !== "string") {
-                            ws.send(JSON.stringify({
-                                type: "error",
-                                message: "Channel name is required"
-                            }));
-                            return;
-                        }
-                        const channelClients = channels.get(channelName);
-                        if (!channelClients || !channelClients.has(ws)) {
-                            ws.send(JSON.stringify({
-                                type: "error",
-                                message: "You must join the channel first"
-                            }));
-                            return;
-                        }
-                        // Broadcast to all clients in the channel
-                        channelClients.forEach((client)=>{
-                            if (client.readyState === WebSocket.OPEN) {
-                                console.log("Broadcasting message to client:", data.message);
-                                client.send(JSON.stringify({
-                                    type: "broadcast",
-                                    message: data.message,
-                                    sender: client === ws ? "You" : "User",
-                                    channel: channelName
-                                }));
-                            }
-                        });
-                    }
-                } catch (err) {
-                    console.error("Error handling message:", err);
-                }
-            },
-            close (ws) {
-                // Remove client from their channel
-                channels.forEach((clients)=>{
-                    clients.delete(ws);
-                });
-            }
+            open: handleConnection,
+            message: handleWebSocketMessage,
+            close: handleClose
         }
     });
     console.log(`WebSocket server running on port ${server.port}`);
     return server;
 }
-async function startMcpServer(serverUrl, experimental, configPath) {
-    // Load config if provided
-    let configData = null;
-    if (configPath) {
-        configData = await loadConfig(configPath);
-        if (configData) {
-            logger.info(`Loaded configuration from: ${configPath}`);
-            // Log component transformers if present
-            if (configData.extend?.componentHandlers) {
-                const handlers = configData.extend.componentHandlers;
-                if (handlers.length > 0) {
-                    logger.info(`Found ${handlers.length} custom component handlers`);
+
+// 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`);
     }
-    const figmaClient = createFigmaWebSocketClient(serverUrl);
+    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, configData);
-    if (experimental) {
-        registerEditingTools(server, figmaClient);
-    }
+    registerTools(server, figmaClient, restClient, config, mode);
     registerPrompts(server);
-    try {
-        figmaClient.connectToFigma();
-    } catch (error) {
-        logger.warn(`Could not connect to Figma initially: ${error instanceof Error ? error.message : String(error)}`);
-        logger.warn("Will try to connect when the first command is sent");
+    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");
+    logger.info(`FigmaMCP server running on stdio (mode: ${mode})`);
 }
-// Define CLI commands
-cli.command("", "Start the MCP server").option("--server <server>", "Server URL", {
-    default: "localhost"
-}).option("--experimental", "Enable experimental features", {
+// 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)").action(async (options)=>{
-    await startMcpServer(options.server, options.experimental, options.config);
+}).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
@@ -911,5 +1250,4 @@ cli.command("socket", "Start the WebSocket server").option("--port <port>", "Por
 });
 cli.help();
 cli.version(version);
-// Parse CLI args
 cli.parse();