@seed-design/mcp 1.2.1 → 1.3.1

package/dist/index.js

@@ -0,0 +1,537 @@
+import { createRestNormalizer, figma, react, getFigmaColorVariableNames } from '@seed-design/figma';
+import { z } from 'zod';
+import { Api } from 'figma-api';
+
+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, ":")
+    };
+}
+
+/**
+ * Format an error for logging
+ */ function formatError(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+
+/**
+ * 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.`);
+        }
+    });
+    // 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);
+            }
+        });
+    }
+}
+
+export { createFigmaRestClient, parseFigmaUrl, registerTools };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seed-design/mcp",
-  "version": "1.2.1",
+  "version": "1.3.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/daangn/seed-design.git",
@@ -12,26 +12,34 @@
   "sideEffects": false,
   "files": [
     "bin",
+    "dist",
     "src",
     "package.json"
   ],
   "bin": "./bin/index.mjs",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
   "scripts": {
-    "clean": "rm -rf lib",
+    "clean": "rm -rf dist bin",
     "build": "bunchee",
     "lint:publish": "bun publint"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.10.2",
+    "@modelcontextprotocol/sdk": "^1.25.3",
     "@seed-design/figma": "1.2.1",
     "cac": "^6.7.14",
+    "figma-api": "^2.1.0-beta",
     "uuid": "^13.0.0",
     "ws": "^8.18.1",
     "yargs": "^18.0.0",
-    "zod": "^3.24.3"
+    "zod": "4.3.5"
   },
   "devDependencies": {
-    "@types/bun": "^1.2.10",
+    "@figma/rest-api-spec": "^0.36.0",
     "@types/ws": "^8.18.1",
     "@types/yargs": "^17.0.33",
     "typescript": "^5.9.2"