@seed-design/mcp 1.2.1 → 1.3.1

package/src/bin/index.ts

@@ -3,244 +3,186 @@
 import { cac } from "cac";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { version } from "../../package.json" with { type: "json" };
 import { logger } from "../logger";
-import { createFigmaWebSocketClient } from "../websocket";
+import { loadConfig, type McpConfig } from "../config";
+import { createFigmaRestClient, type FigmaRestClient } from "../figma-rest-client";
+import { createFigmaWebSocketClient, type FigmaWebSocketClient } from "../websocket";
 import { registerEditingTools, registerTools } from "../tools";
+import type { ToolMode } from "../tools-helpers";
 import { registerPrompts } from "../prompts";
-import { version } from "../../package.json" with { type: "json" };
-import type { ServerWebSocket } from "bun";
-import { loadConfig, type McpConfig } from "../config";
+import { startWebSocketServer } from "./websocket-server";
 
-// Initialize CLI
-const cli = cac("@seed-design/mcp");
+// Helper Functions
 
-// Store WebSocket clients by channel
-const channels = new Map<string, Set<ServerWebSocket<any>>>();
-
-function handleWebSocketConnection(ws: ServerWebSocket<any>) {
-  console.log("New client connected");
-
-  ws.send(
-    JSON.stringify({
-      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 getFigmaAccessToken(): string | undefined {
+  return process.env["FIGMA_PERSONAL_ACCESS_TOKEN"]?.trim();
 }
 
-async function startWebSocketServer(port: number) {
-  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",
-          },
-        });
+function createFigmaClient(
+  serverUrl: string | undefined,
+  mode: ToolMode,
+): FigmaWebSocketClient | null {
+  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.");
       }
 
-      // Handle WebSocket upgrade
-      const success = server.upgrade(req, {
-        headers: {
-          "Access-Control-Allow-Origin": "*",
-        },
-      });
-
-      if (success) return;
-
-      // Return response for non-WebSocket requests
-      return new Response("WebSocket server running", {
-        headers: {
-          "Access-Control-Allow-Origin": "*",
-        },
-      });
-    },
-    websocket: {
-      open: handleWebSocketConnection,
-      message(ws, message) {
-        try {
-          console.log("Received message from client:", message);
-          const data = JSON.parse(message as string);
-
-          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);
-        });
-      },
-    },
-  });
+      return null;
+    }
 
-  console.log(`WebSocket server running on port ${server.port}`);
-  return server;
-}
+    case "websocket": {
+      logger.info(`WebSocket mode enabled. Client connecting to: ${resolvedUrl}`);
+
+      return createFigmaWebSocketClient(resolvedUrl);
+    }
 
-async function startMcpServer(serverUrl: string, experimental: boolean, configPath?: string) {
-  // Load config if provided
-  let configData: McpConfig | null = 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`);
-        }
+    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: ToolMode): FigmaRestClient | null {
+  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?: string): Promise<McpConfig | null> {
+  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: FigmaWebSocketClient | null): void {
+  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");
+    }
+  }
+}
+
+// MCP Server
+
+interface McpServerOptions {
+  serverUrl?: string;
+  experimental?: boolean;
+  configPath?: string;
+  mode?: ToolMode;
+}
+
+async function startMcpServer(options: McpServerOptions = {}): Promise<void> {
+  const { serverUrl, experimental, configPath, mode = "all" } = options;
+
+  const config = await loadMcpConfig(configPath);
+  const figmaClient = createFigmaClient(serverUrl, mode);
+  const restClient = createRestClient(mode);
 
-  const figmaClient = createFigmaWebSocketClient(serverUrl);
   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
+
+const cli = cac("@seed-design/mcp");
+
 cli
   .command("", "Start the MCP server")
-  .option("--server <server>", "Server URL", { default: "localhost" })
+  .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) => {
-    await startMcpServer(options.server, options.experimental, options.config);
+    const mode = options.mode as ToolMode | undefined;
+    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
@@ -252,6 +194,4 @@ cli
 
 cli.help();
 cli.version(version);
-
-// Parse CLI args
 cli.parse();

package/src/bin/websocket-server.ts

@@ -0,0 +1,196 @@
+import type { ServerWebSocket } from "bun";
+
+interface JoinMessage {
+  type: "join";
+  channel: string;
+  id?: string;
+}
+
+interface ChatMessage {
+  type: "message";
+  channel: string;
+  message: unknown;
+}
+
+type WebSocketMessage = JoinMessage | ChatMessage;
+
+const channels = new Map<string, Set<ServerWebSocket<unknown>>>();
+
+function sendJson(ws: ServerWebSocket<unknown>, data: object): void {
+  ws.send(JSON.stringify(data));
+}
+
+function broadcastToChannel(
+  channelName: string,
+  message: object,
+  excludeWs?: ServerWebSocket<unknown>,
+): void {
+  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: ServerWebSocket<unknown>, data: JoinMessage): void {
+  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: ServerWebSocket<unknown>, data: ChatMessage): void {
+  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: ServerWebSocket<unknown>): void {
+  console.log("New client connected");
+  sendJson(ws, { type: "system", message: "Please join a channel to start chatting" });
+}
+
+function handleWebSocketMessage(ws: ServerWebSocket<unknown>, rawMessage: string | Buffer): void {
+  try {
+    console.log("Received message from client:", rawMessage);
+    const data = JSON.parse(rawMessage as string) as WebSocketMessage;
+
+    switch (data.type) {
+      case "join":
+        handleJoin(ws, data);
+        break;
+      case "message":
+        handleMessage(ws, data);
+        break;
+      default:
+        console.warn(`Unknown message type: ${(data as { type: string }).type}`);
+    }
+  } catch (err) {
+    console.error("Error handling message:", err);
+  }
+}
+
+function handleClose(ws: ServerWebSocket<unknown>): void {
+  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
+
+export async function startWebSocketServer(port: number) {
+  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;
+}

package/src/figma-rest-client.ts

@@ -0,0 +1,55 @@
+import { Api as FigmaApi } from "figma-api";
+import type { GetFileNodesResponse } from "@figma/rest-api-spec";
+
+export interface FigmaRestClient {
+  getFileNodes(fileKey: string, nodeIds: string[]): Promise<GetFileNodesResponse>;
+}
+
+export function createFigmaRestClient(personalAccessToken: string): FigmaRestClient {
+  const api = new FigmaApi({ personalAccessToken });
+
+  return {
+    async getFileNodes(fileKey: string, nodeIds: string[]): Promise<GetFileNodesResponse> {
+      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"
+ */
+export function parseFigmaUrl(url: string): { fileKey: string; nodeId: string } {
+  const __url: 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, ":"),
+  };
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export { registerTools } from "./tools";
+export { createFigmaRestClient, parseFigmaUrl } from "./figma-rest-client";
+export type { FigmaRestClient } from "./figma-rest-client";
+export type { ToolMode } from "./tools-helpers";