@seed-design/mcp 0.0.0-alpha-20260324091316

package/src/bin/index.ts

@@ -0,0 +1,197 @@
+#!/usr/bin/env node
+
+import { cac } from "cac";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { version } from "../../package.json" with { type: "json" };
+import { logger } from "../logger";
+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 { startWebSocketServer } from "./websocket-server";
+
+// Helper Functions
+
+function getFigmaAccessToken(): string | undefined {
+  return process.env["FIGMA_PERSONAL_ACCESS_TOKEN"]?.trim();
+}
+
+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.");
+      }
+
+      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: 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 server = new McpServer({
+    name: "SEED Design MCP",
+    version,
+  });
+
+  registerTools(server, figmaClient, restClient, config, mode);
+  registerPrompts(server);
+
+  if (experimental) {
+    if (mode === "rest") {
+      logger.warn("Experimental editing tools not available in REST mode. Skipping.");
+    } else if (figmaClient) {
+      registerEditingTools(server, figmaClient);
+    } else {
+      logger.warn("Experimental editing tools require WebSocket connection. Skipping.");
+    }
+  }
+
+  connectFigmaClient(figmaClient);
+
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+
+  logger.info(`FigmaMCP server running on stdio (mode: ${mode})`);
+}
+
+// CLI
+
+const cli = cac("@seed-design/mcp");
+
+cli
+  .command("", "Start the MCP server")
+  .option(
+    "--server <server>",
+    "WebSocket server URL. If not provided and FIGMA_PERSONAL_ACCESS_TOKEN is set, REST API mode will be used.",
+  )
+  .option("--experimental", "Enable experimental features", { default: false })
+  .option("--config <config>", "Path to configuration file (.js, .mjs, .ts, .mts)")
+  .option(
+    "--mode <mode>",
+    "Tool registration mode: 'rest' (REST API tools only), 'websocket' (WebSocket tools only), or 'all' (default)",
+  )
+  .action(async (options) => {
+    const mode = options.mode 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
+  .command("socket", "Start the WebSocket server")
+  .option("--port <port>", "Port number", { default: 3055 })
+  .action(async (options) => {
+    await startWebSocketServer(options.port);
+  });
+
+cli.help();
+cli.version(version);
+cli.parse();

package/src/bin/websocket-server.ts

@@ -0,0 +1,193 @@
+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
+  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/config.ts

@@ -0,0 +1,47 @@
+import type { CreatePipelineConfig } from "@seed-design/figma/codegen/targets/react";
+import fs from "node:fs";
+import path from "node:path";
+import { logger } from "./logger";
+
+// Define config type
+export interface McpConfig {
+  extend?: CreatePipelineConfig["extend"];
+}
+
+// Config loader
+export async function loadConfig(configPath: string) {
+  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;
+  }
+}

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";

package/src/logger.ts

@@ -0,0 +1,41 @@
+/**
+ * Custom logging module that writes to stderr instead of stdout
+ * to avoid being captured in MCP protocol communication
+ */
+
+export const logger = {
+  /**
+   * Log an informational message
+   */
+  info: (message: string) => process.stderr.write(`[INFO] ${message}\n`),
+
+  /**
+   * Log a debug message
+   */
+  debug: (message: string) => process.stderr.write(`[DEBUG] ${message}\n`),
+
+  /**
+   * Log a warning message
+   */
+  warn: (message: string) => process.stderr.write(`[WARN] ${message}\n`),
+
+  /**
+   * Log an error message
+   */
+  error: (message: string) => process.stderr.write(`[ERROR] ${message}\n`),
+
+  /**
+   * Log a general message
+   */
+  log: (message: string) => process.stderr.write(`[LOG] ${message}\n`),
+};
+
+/**
+ * Format an error for logging
+ */
+export function formatError(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message;
+  }
+  return String(error);
+}

package/src/prompts.ts

@@ -0,0 +1,55 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+
+export function registerPrompts(server: McpServer): void {
+  server.prompt(
+    "react_implementation_strategy",
+    "Best practices for implementing React components",
+    (_extra) => {
+      return {
+        messages: [
+          {
+            role: "assistant",
+            content: {
+              type: "text",
+              text: `When implementing React components, follow these best practices:
+  
+  1. Start with selection:
+     - First use get_selection() to understand the current selection
+     - If no selection ask user to select single node
+  
+  2. Get React code of the selected node:
+     - Use get_node_react_code() to get the React code of the selected node
+     - If no selection ask user to select single node
+  `,
+            },
+          },
+        ],
+        description: "Best practices for implementing React components",
+      };
+    },
+  );
+
+  server.prompt("read_design_strategy", "Best practices for reading Figma designs", (_extra) => {
+    return {
+      messages: [
+        {
+          role: "assistant",
+          content: {
+            type: "text",
+            text: `When reading Figma designs, follow these best practices:
+  
+  1. Start with selection:
+     - First use get_selection() to understand the current selection
+     - If no selection ask user to select single or multiple nodes
+  
+  2. Get node infos of the selected nodes:
+     - Use get_nodes_info() to get the information of the selected nodes
+     - If no selection ask user to select single or multiple nodes
+  `,
+          },
+        },
+      ],
+      description: "Best practices for reading Figma designs",
+    };
+  });
+}

package/src/responses.ts

@@ -0,0 +1,77 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { formatError } from "./logger";
+
+/**
+ * Format an object response
+ */
+export function formatObjectResponse(result: unknown): CallToolResult {
+  return {
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(result),
+      },
+    ],
+  };
+}
+
+/**
+ * Format a text response
+ */
+export function formatTextResponse(text: string): CallToolResult {
+  return {
+    content: [
+      {
+        type: "text",
+        text,
+      },
+    ],
+  };
+}
+
+/**
+ * Format an image response
+ */
+export function formatImageResponse(imageData: string, mimeType = "image/png"): CallToolResult {
+  return {
+    content: [
+      {
+        type: "image",
+        data: imageData,
+        mimeType,
+      },
+    ],
+  };
+}
+
+/**
+ * Format an error response
+ */
+export function formatErrorResponse(toolName: string, error: unknown): CallToolResult {
+  return {
+    content: [
+      {
+        type: "text",
+        text: `Error in ${toolName}: ${formatError(error)}`,
+      },
+    ],
+  };
+}
+
+/**
+ * Format a progress response with initial message
+ */
+export function formatProgressResponse(initialMessage: string, result: unknown): CallToolResult {
+  return {
+    content: [
+      {
+        type: "text",
+        text: initialMessage,
+      },
+      {
+        type: "text",
+        text: typeof result === "string" ? result : JSON.stringify(result),
+      },
+    ],
+  };
+}