@seed-design/mcp 0.0.2

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@seed-design/mcp",
+  "version": "0.0.2",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/daangn/seed-design.git",
+    "directory": "packages/mcp"
+  },
+  "author": "Asher <asher@daangn.com>",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "bin",
+    "src"
+  ],
+  "bin": "./bin/index.mjs",
+  "scripts": {
+    "clean": "rm -rf lib",
+    "build": "bunchee",
+    "lint:publish": "bun publint"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.7.0",
+    "@seed-design/figma": "0.0.2",
+    "express": "^4.21.2",
+    "yargs": "^17.7.2"
+  },
+  "devDependencies": {
+    "@types/yargs": "^17.0.33",
+    "typescript": "^5.4.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/bin/index.ts

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+import { startServer } from "../index";
+import { ConsoleLogger } from "../logger";
+
+/**
+ * Main CLI entry point
+ */
+async function main(): Promise<void> {
+  try {
+    // Set environment to indicate CLI mode
+    process.env["NODE_ENV"] = "cli";
+
+    // Start server
+    await startServer();
+  } catch (error) {
+    handleStartupError(error);
+    process.exit(1);
+  }
+}
+
+/**
+ * Handles and logs startup errors
+ */
+function handleStartupError(error: unknown): void {
+  if (error instanceof Error) {
+    ConsoleLogger.error("Failed to start server:", error.message);
+  } else {
+    ConsoleLogger.error("Failed to start server with unknown error:", error);
+  }
+}
+
+// Run the application
+main().catch(handleStartupError);

package/src/config.ts

@@ -0,0 +1,166 @@
+import yargs from "yargs";
+import { hideBin } from "yargs/helpers";
+import type { Logger } from "./logger";
+import { NoOpLogger } from "./logger";
+
+/**
+ * Configuration for the Figma MCP Server
+ */
+export interface ServerConfig {
+  figmaApiKey: string;
+  port: number;
+  configSources: {
+    figmaApiKey: ConfigSource;
+    port: ConfigSource;
+  };
+}
+
+/**
+ * Source of configuration value
+ */
+type ConfigSource = "cli" | "env" | "default";
+
+/**
+ * Command line arguments
+ */
+interface CliArgs {
+  "figma-api-key"?: string;
+  port?: number;
+}
+
+/**
+ * Configuration manager for the Figma MCP Server
+ */
+export class ConfigManager {
+  private readonly isStdioMode: boolean;
+  private readonly logger: Logger;
+
+  /**
+   * Creates a new ConfigManager instance
+   */
+  constructor(options: { isStdioMode: boolean; logger?: Logger }) {
+    this.isStdioMode = options.isStdioMode;
+    this.logger = options.logger || NoOpLogger;
+  }
+
+  /**
+   * Gets the server configuration from command line arguments and environment variables
+   */
+  getServerConfig(): ServerConfig {
+    // Parse command line arguments
+    const argv = this.parseCommandLineArgs();
+
+    // Initialize config with default values
+    const config: ServerConfig = {
+      figmaApiKey: "",
+      port: 3333,
+      configSources: {
+        figmaApiKey: "env",
+        port: "default",
+      },
+    };
+
+    // Handle FIGMA_API_KEY
+    this.configureFigmaApiKey(config, argv);
+
+    // Handle PORT
+    this.configurePort(config, argv);
+
+    // Validate configuration
+    this.validateConfig(config);
+
+    // Log configuration sources
+    this.logConfig(config);
+
+    return config;
+  }
+
+  /**
+   * Parses command line arguments
+   */
+  private parseCommandLineArgs(): CliArgs {
+    return yargs(hideBin(process.argv))
+      .options({
+        "figma-api-key": {
+          type: "string",
+          description: "Figma API key",
+        },
+        port: {
+          type: "number",
+          description: "Port to run the server on",
+        },
+      })
+      .help()
+      .parseSync() as CliArgs;
+  }
+
+  /**
+   * Configures the Figma API key
+   */
+  private configureFigmaApiKey(config: ServerConfig, argv: CliArgs): void {
+    if (argv["figma-api-key"]) {
+      config.figmaApiKey = argv["figma-api-key"];
+      config.configSources.figmaApiKey = "cli";
+    } else if (process.env["FIGMA_API_KEY"]) {
+      config.figmaApiKey = process.env["FIGMA_API_KEY"];
+      config.configSources.figmaApiKey = "env";
+    }
+  }
+
+  /**
+   * Configures the server port
+   */
+  private configurePort(config: ServerConfig, argv: CliArgs): void {
+    if (argv.port) {
+      config.port = argv.port;
+      config.configSources.port = "cli";
+    } else if (process.env["PORT"]) {
+      config.port = Number.parseInt(process.env["PORT"], 10);
+      config.configSources.port = "env";
+    }
+  }
+
+  /**
+   * Validates the configuration
+   */
+  private validateConfig(config: ServerConfig): void {
+    if (!config.figmaApiKey) {
+      this.logger.error(
+        "FIGMA_API_KEY is required (via CLI argument --figma-api-key or .env file)",
+      );
+      process.exit(1);
+    }
+  }
+
+  /**
+   * Logs the configuration
+   */
+  private logConfig(config: ServerConfig): void {
+    if (this.isStdioMode) {
+      return;
+    }
+
+    this.logger.log("\nConfiguration:");
+    this.logger.log(
+      `- FIGMA_API_KEY: ${this.maskApiKey(config.figmaApiKey)} (source: ${config.configSources.figmaApiKey})`,
+    );
+    this.logger.log(`- PORT: ${config.port} (source: ${config.configSources.port})`);
+    this.logger.log(""); // Empty line for better readability
+  }
+
+  /**
+   * Masks an API key for secure logging
+   */
+  private maskApiKey(key: string): string {
+    if (key.length <= 4) return "****";
+    return `****${key.slice(-4)}`;
+  }
+}
+
+/**
+ * Gets the server configuration
+ */
+export function getServerConfig(isStdioMode: boolean): ServerConfig {
+  const configManager = new ConfigManager({ isStdioMode });
+  return configManager.getServerConfig();
+}

package/src/figma.ts

@@ -0,0 +1,211 @@
+import type { GetFileNodesResponse, GetImagesResponse } from "@figma/rest-api-spec";
+import fs from "fs";
+import { generateCode, createRestNormalizer } from "@seed-design/figma";
+import type { Logger } from "./logger";
+import { NoOpLogger } from "./logger";
+
+export interface FigmaError {
+  status: number;
+  err: string;
+}
+
+export interface FetchImageParams {
+  /**
+   * The Node in Figma that will either be rendered or have its background image downloaded
+   */
+  nodeId: string;
+  /**
+   * The file mimetype for the image
+   */
+  fileType: "png" | "svg";
+  /**
+   * The filename to save the image as
+   */
+  name: string;
+}
+
+export interface FigmaImage {
+  nodeId: string;
+  name: string;
+  blob: Buffer;
+  fileType: "png" | "svg";
+}
+
+export interface SimplifiedDesign {
+  name: string;
+  lastModified: string;
+  code: string;
+}
+
+interface FigmaServiceOptions {
+  apiKey: string;
+  baseUrl?: string;
+  logger?: Logger;
+}
+
+export class FigmaService {
+  private readonly apiKey: string;
+  private readonly baseUrl: string;
+  private readonly logger: Logger;
+
+  constructor(options: FigmaServiceOptions) {
+    this.apiKey = options.apiKey;
+    this.baseUrl = options.baseUrl || "https://api.figma.com/v1";
+    this.logger = options.logger || NoOpLogger;
+  }
+
+  private async request<T>(endpoint: string): Promise<T> {
+    try {
+      this.logger.log(`Calling ${this.baseUrl}${endpoint}`);
+      const response = await fetch(`${this.baseUrl}${endpoint}`, {
+        headers: {
+          "X-Figma-Token": this.apiKey,
+        },
+      });
+
+      if (!response.ok) {
+        const errorData = (await response.json().catch(() => ({}))) as { err?: string };
+        throw {
+          status: response.status,
+          err: errorData.err || "Unknown error",
+        } as FigmaError;
+      }
+
+      return response.json() as Promise<T>;
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new Error(`Failed to make request to Figma API: ${error.message}`);
+      }
+      throw error;
+    }
+  }
+
+  async getImages(fileKey: string, nodes: FetchImageParams[]): Promise<FigmaImage[]> {
+    const pngNodes = nodes.filter(({ fileType }) => fileType === "png");
+    const svgNodes = nodes.filter(({ fileType }) => fileType === "svg");
+
+    const imagesMap = await this.fetchImageUrls(fileKey, pngNodes, svgNodes);
+
+    const images = await this.fetchImage(nodes, imagesMap);
+
+    return images;
+  }
+
+  private async fetchImageUrls(
+    fileKey: string,
+    pngNodes: FetchImageParams[],
+    svgNodes: FetchImageParams[],
+  ): Promise<Record<string, string>> {
+    const pngIds = pngNodes.map(({ nodeId }) => nodeId);
+    const pngFiles =
+      pngIds.length > 0
+        ? this.request<GetImagesResponse>(
+            `/images/${fileKey}?ids=${pngIds.join(",")}&scale=2&format=png`,
+          ).then(({ images = {} }) => images)
+        : ({} as GetImagesResponse["images"]);
+
+    const svgIds = svgNodes.map(({ nodeId }) => nodeId);
+    const svgFiles =
+      svgIds.length > 0
+        ? this.request<GetImagesResponse>(
+            `/images/${fileKey}?ids=${svgIds.join(",")}&format=svg`,
+          ).then(({ images = {} }) => images)
+        : ({} as GetImagesResponse["images"]);
+
+    const [pngImages, svgImages] = await Promise.all([pngFiles, svgFiles]);
+    const combinedImages: Record<string, string> = {};
+
+    Object.entries({ ...pngImages, ...svgImages }).forEach(([key, value]) => {
+      if (value !== null) {
+        combinedImages[key] = value;
+      }
+    });
+
+    return combinedImages;
+  }
+
+  private async fetchImage(
+    nodes: FetchImageParams[],
+    imagesMap: Record<string, string>,
+  ): Promise<FigmaImage[]> {
+    const fetchPromises = nodes
+      .map(({ nodeId, name, fileType }) => {
+        const imageUrl = imagesMap[nodeId];
+        if (imageUrl) {
+          return fetch(imageUrl)
+            .then((response) => response.arrayBuffer())
+            .then((arrayBuffer) => Buffer.from(arrayBuffer))
+            .then((buffer) => {
+              return {
+                nodeId,
+                name,
+                blob: buffer,
+                fileType,
+              };
+            })
+            .catch((error) => {
+              this.logger.error(`Failed to fetch image for ${nodeId}:`, error);
+              return undefined;
+            });
+        }
+        return undefined;
+      })
+      .filter((x): x is Promise<FigmaImage> => x !== undefined);
+
+    return Promise.all(fetchPromises);
+  }
+
+  async getGeneratedCode(
+    fileKey: string,
+    nodeId: string,
+    depth?: number,
+  ): Promise<SimplifiedDesign> {
+    const endpoint = `/files/${fileKey}/nodes?ids=${nodeId}${depth ? `&depth=${depth}` : ""}`;
+    const response = await this.request<GetFileNodesResponse>(endpoint);
+
+    this.writeDebugLogs("figma-raw.json", response);
+
+    const node = Object.values(response.nodes)[0]!;
+
+    const normalizer = createRestNormalizer({
+      styles: node.styles,
+      components: node.components,
+      componentSets: node.componentSets,
+    });
+
+    const normalizedNode = normalizer(node.document);
+    const code = await generateCode(normalizedNode);
+
+    const result = {
+      name: node.document.name,
+      lastModified: response.lastModified,
+      code,
+    };
+
+    this.writeDebugLogs("figma-result.json", result);
+    return result;
+  }
+
+  private writeDebugLogs(name: string, value: any): void {
+    try {
+      if (process.env["NODE_ENV"] !== "development") return;
+
+      const logsDir = "logs";
+
+      try {
+        fs.accessSync(process.cwd(), fs.constants.W_OK);
+      } catch (error) {
+        this.logger.error("Failed to write logs:", error);
+        return;
+      }
+
+      if (!fs.existsSync(logsDir)) {
+        fs.mkdirSync(logsDir);
+      }
+
+      fs.writeFileSync(`${logsDir}/${name}`, JSON.stringify(value, null, 2));
+    } catch (error) {
+      this.logger.error("Failed to write logs:", error);
+    }
+  }
+}

package/src/index.ts

@@ -0,0 +1,36 @@
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { FigmaMcpServer } from "./server";
+import { getServerConfig } from "./config";
+import { ConsoleLogger } from "./logger";
+
+/**
+ * Determines if the server should run in stdio mode
+ */
+function isRunningInStdioMode(): boolean {
+  return process.env["NODE_ENV"] === "cli" || process.argv.includes("--stdio");
+}
+
+/**
+ * Starts the Figma MCP server
+ */
+export async function startServer(): Promise<void> {
+  // Determine server mode (stdio or HTTP)
+  const stdioMode = isRunningInStdioMode();
+
+  // Get configuration
+  const config = getServerConfig(stdioMode);
+
+  // Create server instance
+  const server = new FigmaMcpServer(config.figmaApiKey);
+
+  // Start in appropriate mode
+  if (stdioMode) {
+    // Connect to stdio transport for CLI mode
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+  } else {
+    // Start HTTP server for web mode
+    ConsoleLogger.log(`Initializing Figma MCP Server in HTTP mode on port ${config.port}...`);
+    await server.startHttpServer(config.port);
+  }
+}

package/src/logger.ts

@@ -0,0 +1,43 @@
+/**
+ * Centralized logger module for the Figma MCP Server
+ */
+export interface Logger {
+  log(...args: any[]): void;
+  error(...args: any[]): void;
+}
+
+/**
+ * Default logger implementation that does nothing
+ */
+export const NoOpLogger: Logger = {
+  log: () => {},
+  error: () => {},
+};
+
+/**
+ * Logger that writes to the console
+ */
+export const ConsoleLogger: Logger = {
+  log: console.log,
+  error: console.error,
+};
+
+/**
+ * Creates a logger that sends messages to an MCP server
+ */
+export function createMcpLogger(sendLoggingMessage: (message: any) => void): Logger {
+  return {
+    log: (...args: any[]) => {
+      sendLoggingMessage({
+        level: "info",
+        data: args,
+      });
+    },
+    error: (...args: any[]) => {
+      sendLoggingMessage({
+        level: "error",
+        data: args,
+      });
+    },
+  };
+}

package/src/save-image.ts

@@ -0,0 +1,16 @@
+import fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+
+const defaultDownloadsPath = path.join(os.homedir(), "Downloads");
+
+export function saveImage(image: Buffer, name: string, type: "png" | "svg") {
+  if (!fs.existsSync(defaultDownloadsPath)) {
+    fs.mkdirSync(defaultDownloadsPath, { recursive: true });
+  }
+
+  const filePath = path.join(defaultDownloadsPath, `${name}.${type}`);
+  fs.writeFileSync(filePath, image);
+
+  return filePath;
+}