figma-code-agent-mcp 1.0.0

package/dist/tools/updateNode.js

@@ -0,0 +1,163 @@
+import { figmaWebSocket } from '../websocket.js';
+export const updateNodeSchema = {
+    name: 'update_node',
+    description: 'Update properties of an existing node in Figma. To copy image fills between nodes, use copyFillsFrom with the source node ID.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            nodeId: {
+                type: 'string',
+                description: 'ID of the node to update',
+            },
+            properties: {
+                type: 'object',
+                description: 'Properties to update on the node',
+                properties: {
+                    name: {
+                        type: 'string',
+                        description: 'New name for the node',
+                    },
+                    x: {
+                        type: 'number',
+                        description: 'New X position',
+                    },
+                    y: {
+                        type: 'number',
+                        description: 'New Y position',
+                    },
+                    width: {
+                        type: 'number',
+                        description: 'New width (only for resizable nodes)',
+                    },
+                    height: {
+                        type: 'number',
+                        description: 'New height (only for resizable nodes)',
+                    },
+                    fillColor: {
+                        type: 'object',
+                        description: 'New fill color (RGB values from 0-1)',
+                        properties: {
+                            r: { type: 'number', minimum: 0, maximum: 1 },
+                            g: { type: 'number', minimum: 0, maximum: 1 },
+                            b: { type: 'number', minimum: 0, maximum: 1 },
+                            a: { type: 'number', minimum: 0, maximum: 1, default: 1 },
+                        },
+                        required: ['r', 'g', 'b'],
+                    },
+                    opacity: {
+                        type: 'number',
+                        description: 'Node opacity (0-1)',
+                        minimum: 0,
+                        maximum: 1,
+                    },
+                    visible: {
+                        type: 'boolean',
+                        description: 'Whether the node is visible',
+                    },
+                    locked: {
+                        type: 'boolean',
+                        description: 'Whether the node is locked',
+                    },
+                    text: {
+                        type: 'string',
+                        description: 'New text content (only for text nodes)',
+                    },
+                    fontSize: {
+                        type: 'number',
+                        description: 'New font size (only for text nodes)',
+                    },
+                    fontWeight: {
+                        type: 'string',
+                        description: 'Font weight for text nodes (e.g., "Regular", "Bold", "Medium")',
+                    },
+                    cornerRadius: {
+                        type: 'number',
+                        description: 'Corner radius for frames and rectangles',
+                    },
+                    strokeColor: {
+                        type: 'object',
+                        description: 'Stroke/border color (RGB values from 0-1)',
+                        properties: {
+                            r: { type: 'number', minimum: 0, maximum: 1 },
+                            g: { type: 'number', minimum: 0, maximum: 1 },
+                            b: { type: 'number', minimum: 0, maximum: 1 },
+                            a: { type: 'number', minimum: 0, maximum: 1, default: 1 },
+                        },
+                        required: ['r', 'g', 'b'],
+                    },
+                    strokeWeight: {
+                        type: 'number',
+                        description: 'Stroke/border width in pixels',
+                    },
+                    copyFillsFrom: {
+                        type: 'string',
+                        description: 'Node ID to copy fills from (including image fills). This copies the entire fills array from the source node.',
+                    },
+                    copyStrokesFrom: {
+                        type: 'string',
+                        description: 'Node ID to copy strokes from. This copies the entire strokes array from the source node.',
+                    },
+                    layoutMode: {
+                        type: 'string',
+                        enum: ['NONE', 'HORIZONTAL', 'VERTICAL'],
+                        description: 'Auto-layout direction. HORIZONTAL = row, VERTICAL = column, NONE = disable auto-layout',
+                    },
+                    primaryAxisSizingMode: {
+                        type: 'string',
+                        enum: ['FIXED', 'AUTO'],
+                        description: 'How the frame sizes itself along the primary axis (FIXED = fixed size, AUTO = hug contents)',
+                    },
+                    counterAxisSizingMode: {
+                        type: 'string',
+                        enum: ['FIXED', 'AUTO'],
+                        description: 'How the frame sizes itself along the counter axis',
+                    },
+                    primaryAxisAlignItems: {
+                        type: 'string',
+                        enum: ['MIN', 'CENTER', 'MAX', 'SPACE_BETWEEN'],
+                        description: 'Alignment of children along primary axis',
+                    },
+                    counterAxisAlignItems: {
+                        type: 'string',
+                        enum: ['MIN', 'CENTER', 'MAX', 'BASELINE'],
+                        description: 'Alignment of children along counter axis',
+                    },
+                    itemSpacing: {
+                        type: 'number',
+                        description: 'Gap between children in pixels (for auto-layout frames)',
+                    },
+                    paddingTop: {
+                        type: 'number',
+                        description: 'Top padding in pixels (for auto-layout frames)',
+                    },
+                    paddingBottom: {
+                        type: 'number',
+                        description: 'Bottom padding in pixels (for auto-layout frames)',
+                    },
+                    paddingLeft: {
+                        type: 'number',
+                        description: 'Left padding in pixels (for auto-layout frames)',
+                    },
+                    paddingRight: {
+                        type: 'number',
+                        description: 'Right padding in pixels (for auto-layout frames)',
+                    },
+                    layoutWrap: {
+                        type: 'string',
+                        enum: ['NO_WRAP', 'WRAP'],
+                        description: 'Whether children wrap to new lines (for auto-layout frames)',
+                    },
+                },
+            },
+            returnScreenshot: {
+                type: 'boolean',
+                description: 'If true, returns a screenshot of the updated node for visual verification',
+                default: false,
+            },
+        },
+        required: ['nodeId', 'properties'],
+    },
+};
+export async function updateNode(params) {
+    return figmaWebSocket.sendCommand('updateNode', params);
+}

package/dist/types.d.ts

@@ -0,0 +1,101 @@
+export interface WebSocketMessage {
+    id: string;
+    command: string;
+    params: Record<string, unknown>;
+}
+export interface WebSocketResponse {
+    id: string;
+    success: boolean;
+    result?: unknown;
+    error?: string;
+}
+export interface PendingRequest {
+    resolve: (value: unknown) => void;
+    reject: (reason: Error) => void;
+    timeout: NodeJS.Timeout;
+}
+export interface FigmaNode {
+    id: string;
+    name: string;
+    type: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    children?: FigmaNode[];
+}
+export interface CreateFrameParams {
+    name: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    parentId?: string;
+}
+export interface CreateRectangleParams {
+    name?: string;
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    fillColor?: {
+        r: number;
+        g: number;
+        b: number;
+        a?: number;
+    };
+    parentId?: string;
+}
+export interface CreateTextParams {
+    text: string;
+    name?: string;
+    x?: number;
+    y?: number;
+    fontSize?: number;
+    fontFamily?: string;
+    fillColor?: {
+        r: number;
+        g: number;
+        b: number;
+        a?: number;
+    };
+    parentId?: string;
+}
+export interface CreateInstanceParams {
+    componentKey: string;
+    x?: number;
+    y?: number;
+    parentId?: string;
+}
+export interface UpdateNodeParams {
+    nodeId: string;
+    properties: {
+        name?: string;
+        x?: number;
+        y?: number;
+        width?: number;
+        height?: number;
+        fillColor?: {
+            r: number;
+            g: number;
+            b: number;
+            a?: number;
+        };
+        opacity?: number;
+        visible?: boolean;
+        locked?: boolean;
+        text?: string;
+        fontSize?: number;
+    };
+}
+export interface DeleteNodeParams {
+    nodeId: string;
+}
+export interface GetNodeParams {
+    nodeId: string;
+}
+export interface CaptureScreenshotParams {
+    nodeId: string;
+    scale?: number;
+    format?: 'PNG' | 'JPG' | 'SVG' | 'PDF';
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/websocket.d.ts

@@ -0,0 +1,30 @@
+export interface ClientInfo {
+    name: string;
+    version?: string;
+    projectPath?: string;
+}
+declare class FigmaWebSocketClient {
+    private ws;
+    private pendingRequests;
+    private isInitialized;
+    private mcpClientInfo;
+    private pluginEditorType;
+    private pluginConnected;
+    private sessionId;
+    private reconnectTimer;
+    initialize(): Promise<void>;
+    private readAuthToken;
+    private launchHub;
+    private tryConnect;
+    private setupListeners;
+    private scheduleReconnect;
+    private handleResponse;
+    sendCommand(command: string, params?: Record<string, unknown>): Promise<unknown>;
+    isConnected(): boolean;
+    getEditorType(): string | null;
+    setClientInfo(info: ClientInfo): void;
+    private sendClientInfo;
+    close(): void;
+}
+export declare const figmaWebSocket: FigmaWebSocketClient;
+export {};

package/dist/websocket.js

@@ -0,0 +1,282 @@
+import WebSocket from 'ws';
+import { v4 as uuidv4 } from 'uuid';
+import { spawn } from 'child_process';
+import { fileURLToPath } from 'url';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+const PORT = Number(process.env.FIGMA_HUB_PORT) || 3001;
+const COMMAND_TIMEOUT = 30000; // 30 seconds
+const HUB_CONNECT_TIMEOUT = 5000; // 5 seconds to wait for hub startup
+const MAX_PENDING = 100;
+class FigmaWebSocketClient {
+    ws = null;
+    pendingRequests = new Map();
+    isInitialized = false;
+    mcpClientInfo = null;
+    pluginEditorType = null;
+    pluginConnected = false;
+    sessionId = uuidv4();
+    reconnectTimer = null;
+    async initialize() {
+        if (this.isInitialized)
+            return;
+        this.isInitialized = true;
+        // Try connecting to an existing hub first
+        const connected = await this.tryConnect();
+        if (connected)
+            return;
+        // No hub running — launch one
+        await this.launchHub();
+        // Now connect to it
+        const retryConnected = await this.tryConnect();
+        if (!retryConnected) {
+            console.error('[WebSocket] Failed to connect to hub after launching it');
+        }
+    }
+    readAuthToken() {
+        try {
+            const tokenPath = path.join(os.homedir(), '.figma-mcp-hub-token');
+            return fs.readFileSync(tokenPath, 'utf-8').trim();
+        }
+        catch {
+            return null;
+        }
+    }
+    async launchHub() {
+        const lockPath = path.join(os.homedir(), '.figma-mcp-hub.lock');
+        // Check if another process is already launching the hub
+        try {
+            const lockContent = fs.readFileSync(lockPath, 'utf-8').trim();
+            const lockTime = parseInt(lockContent, 10);
+            // If lock is less than 10 seconds old, skip spawning
+            if (Date.now() - lockTime < 10000) {
+                console.error('[WebSocket] Hub launch already in progress, waiting...');
+                await new Promise(resolve => setTimeout(resolve, 2000));
+                return;
+            }
+        }
+        catch {
+            // No lock file, proceed
+        }
+        // Write lock file
+        try {
+            fs.writeFileSync(lockPath, String(Date.now()), { mode: 0o600 });
+        }
+        catch {
+            // If we can't write lock, proceed anyway
+        }
+        const __filename = fileURLToPath(import.meta.url);
+        const __dirname = path.dirname(__filename);
+        const hubPath = path.join(__dirname, 'hub.js');
+        console.error('[WebSocket] Launching hub...');
+        const child = spawn(process.execPath, [hubPath], {
+            detached: true,
+            stdio: 'ignore',
+            env: { ...process.env, FIGMA_HUB_PORT: String(PORT) },
+        });
+        child.unref();
+        // Wait for hub to be ready
+        await new Promise((resolve) => {
+            const start = Date.now();
+            const check = () => {
+                const probe = new WebSocket(`ws://localhost:${PORT}`);
+                probe.on('open', () => {
+                    probe.close();
+                    resolve();
+                });
+                probe.on('error', () => {
+                    if (Date.now() - start > HUB_CONNECT_TIMEOUT) {
+                        resolve(); // give up waiting, tryConnect will fail
+                    }
+                    else {
+                        setTimeout(check, 200);
+                    }
+                });
+            };
+            check();
+        });
+        // Clean up lock after hub is ready
+        try {
+            fs.unlinkSync(lockPath);
+        }
+        catch { }
+    }
+    tryConnect() {
+        return new Promise((resolve) => {
+            try {
+                const ws = new WebSocket(`ws://localhost:${PORT}`);
+                const timeout = setTimeout(() => {
+                    ws.close();
+                    resolve(false);
+                }, 3000);
+                ws.on('open', () => {
+                    clearTimeout(timeout);
+                    this.ws = ws;
+                    this.setupListeners();
+                    // Register as MCP server
+                    const token = this.readAuthToken();
+                    ws.send(JSON.stringify({
+                        type: 'register',
+                        role: 'mcp-server',
+                        sessionId: this.sessionId,
+                        token,
+                    }));
+                    // Send client info if already available
+                    if (this.mcpClientInfo) {
+                        this.sendClientInfo();
+                    }
+                    console.error(`[WebSocket] Connected to hub (session: ${this.sessionId.slice(0, 8)})`);
+                    resolve(true);
+                });
+                ws.on('error', () => {
+                    clearTimeout(timeout);
+                    resolve(false);
+                });
+            }
+            catch {
+                resolve(false);
+            }
+        });
+    }
+    setupListeners() {
+        if (!this.ws)
+            return;
+        this.ws.on('message', (data) => {
+            try {
+                const parsed = JSON.parse(data.toString());
+                // Hub status update
+                if (parsed.type === 'hub-status') {
+                    this.pluginConnected = parsed.pluginConnected ?? false;
+                    this.pluginEditorType = parsed.editorType ?? null;
+                    console.error(`[WebSocket] Plugin connected: ${this.pluginConnected}`);
+                    return;
+                }
+                // Plugin disconnected notification
+                if (parsed.type === 'plugin-disconnected') {
+                    this.pluginConnected = false;
+                    this.pluginEditorType = null;
+                    console.error('[WebSocket] Figma plugin disconnected');
+                    // Reject all pending requests
+                    for (const [id, request] of this.pendingRequests) {
+                        clearTimeout(request.timeout);
+                        request.reject(new Error('Figma plugin disconnected'));
+                        this.pendingRequests.delete(id);
+                    }
+                    return;
+                }
+                // Plugin connected notification
+                if (parsed.type === 'plugin-connected') {
+                    this.pluginConnected = true;
+                    this.pluginEditorType = parsed.editorType ?? null;
+                    console.error('[WebSocket] Figma plugin connected');
+                    return;
+                }
+                // Command response
+                this.handleResponse(parsed);
+            }
+            catch (error) {
+                console.error('[WebSocket] Failed to parse message:', error);
+            }
+        });
+        this.ws.on('close', () => {
+            console.error('[WebSocket] Disconnected from hub');
+            this.ws = null;
+            this.pluginConnected = false;
+            // Reject pending requests
+            for (const [id, request] of this.pendingRequests) {
+                clearTimeout(request.timeout);
+                request.reject(new Error('Disconnected from hub'));
+                this.pendingRequests.delete(id);
+            }
+            // Try to reconnect
+            this.scheduleReconnect();
+        });
+        this.ws.on('error', (error) => {
+            console.error('[WebSocket] Error:', error.message);
+        });
+    }
+    scheduleReconnect() {
+        if (this.reconnectTimer)
+            return;
+        this.reconnectTimer = setTimeout(async () => {
+            this.reconnectTimer = null;
+            const connected = await this.tryConnect();
+            if (!connected) {
+                // Hub might have died — try launching a new one
+                await this.launchHub();
+                await this.tryConnect();
+            }
+        }, 2000);
+    }
+    handleResponse(response) {
+        const pending = this.pendingRequests.get(response.id);
+        if (!pending) {
+            // Not for us — ignore (another MCP server's response)
+            return;
+        }
+        clearTimeout(pending.timeout);
+        this.pendingRequests.delete(response.id);
+        if (response.success) {
+            pending.resolve(response.result);
+        }
+        else {
+            pending.reject(new Error(response.error || 'Unknown error'));
+        }
+    }
+    async sendCommand(command, params = {}) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error('Not connected to hub. Please ensure the MCP server is running.');
+        }
+        if (!this.pluginConnected) {
+            throw new Error('Figma plugin is not connected. Please open the Figma plugin first.');
+        }
+        if (this.pendingRequests.size >= MAX_PENDING) {
+            throw new Error('Too many pending requests. Please wait for some to complete.');
+        }
+        const id = uuidv4();
+        const message = { id, command, params };
+        return new Promise((resolve, reject) => {
+            const timeout = setTimeout(() => {
+                this.pendingRequests.delete(id);
+                reject(new Error(`Command '${command}' timed out after ${COMMAND_TIMEOUT / 1000} seconds`));
+            }, COMMAND_TIMEOUT);
+            this.pendingRequests.set(id, { resolve, reject, timeout });
+            this.ws.send(JSON.stringify(message));
+        });
+    }
+    isConnected() {
+        return this.pluginConnected;
+    }
+    getEditorType() {
+        return this.pluginEditorType;
+    }
+    setClientInfo(info) {
+        this.mcpClientInfo = info;
+        if (this.ws && this.ws.readyState === WebSocket.OPEN) {
+            this.sendClientInfo();
+        }
+    }
+    sendClientInfo() {
+        if (!this.ws || !this.mcpClientInfo)
+            return;
+        this.ws.send(JSON.stringify({
+            type: 'clientInfo',
+            clientInfo: this.mcpClientInfo,
+        }));
+        console.error(`[WebSocket] Sent client info: ${this.mcpClientInfo.name}`);
+    }
+    close() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+        if (this.ws) {
+            this.ws.close();
+            this.ws = null;
+        }
+        this.isInitialized = false;
+    }
+}
+// Singleton instance
+export const figmaWebSocket = new FigmaWebSocketClient();

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "figma-code-agent-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for Figma integration via WebSocket bridge",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "figma-code-agent": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc --watch"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "ws": "^8.16.0",
+    "uuid": "^9.0.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "@types/ws": "^8.5.10",
+    "@types/uuid": "^9.0.7",
+    "typescript": "^5.3.0"
+  }
+}