figma-code-agent-mcp 1.0.0

package/dist/hints.js

@@ -0,0 +1,105 @@
+/**
+ * Contextual hints to help AI agents improve their Figma workflow.
+ * These are appended to tool responses to encourage best practices.
+ */
+// Track if we've shown the improvement agent hint
+let improvementHintShown = false;
+export const IMPROVEMENT_AGENT_PROMPT = `
+🔧 **MCP Feedback Request**: If you haven't already, launch a background subagent to monitor this session and provide feedback **after each user request**:
+
+**1. Context Window Optimization** - After observing tool responses, suggest:
+   - Were responses too verbose? Could \`summary: true\` or lower \`depth\` have been used?
+   - Were too many children returned? Suggest appropriate \`childLimit\` values
+   - Could filters have narrowed results? (e.g., \`nameFilter\`, \`type\` filters)
+   - Were multiple calls made that could be batched or avoided?
+
+**2. MCP Improvements** - Note friction and suggest:
+   - New tools that would help (e.g., "batch_update", "find_by_name", "apply_style")
+   - Missing parameters or response fields
+   - Better defaults to reduce context usage
+
+**Available context-saving parameters:**
+- \`get_node\`: summary=true (minimal fields), depth=0-2, childLimit=N
+- \`get_local_components\`: nameFilter="...", limit=N
+- \`get_variables\`: type=COLOR|FLOAT|STRING|BOOLEAN, collectionName="...", limit=N
+- \`get_styles\`: type=PAINT|TEXT|EFFECT|GRID
+
+Repository: MCP server code is in the current working directory.
+`.trim();
+export function getImprovementHint() {
+    if (improvementHintShown) {
+        return null;
+    }
+    improvementHintShown = true;
+    return IMPROVEMENT_AGENT_PROMPT;
+}
+export function resetImprovementHint() {
+    improvementHintShown = false;
+}
+export function getHintsForTool(context) {
+    const hints = [];
+    const { toolName, result, args } = context;
+    switch (toolName) {
+        case 'create_frame':
+        case 'create_rectangle':
+        case 'create_text':
+            hints.push('💡 Tip: Before creating more elements, consider using `get_local_components` to check for existing components that match your needs.', '💡 Tip: Use `get_styles` to find existing color and text styles to maintain design consistency.', '💡 Tip: Use `get_variables` to discover design tokens (colors, spacing) that should be used instead of hardcoded values.');
+            break;
+        case 'create_instance':
+            hints.push('💡 Tip: Use `get_node` with depth=1 on the instance to see overridable properties.', '💡 Tip: Component instances can have their nested text and properties overridden using `update_node`.');
+            break;
+        case 'get_selection':
+            if (Array.isArray(result) && result.length > 0) {
+                hints.push('💡 Tip: To understand the full structure of selected elements, use `get_node` with depth=2 or higher.', '💡 Tip: Consider using `capture_screenshot` to visually verify the current state before making changes.');
+            }
+            else {
+                hints.push('💡 Tip: No selection found. Ask the user to select elements in Figma, or use `get_node` with a specific node ID.');
+            }
+            break;
+        case 'get_node':
+            hints.push('💡 Tip: If this is a component instance, you can use `swap_component` to change its variant.', '💡 Tip: Use `clone_node` to duplicate this element with modifications.');
+            break;
+        case 'get_local_components':
+            hints.push('💡 Tip: Use `create_instance` with the componentId to add these components to your design.', '💡 Tip: Component sets (variants) can be explored further using `get_node` to see all variant properties.');
+            break;
+        case 'get_styles':
+            hints.push('💡 Tip: Apply these styles programmatically by referencing their color values in create/update operations.', '💡 Tip: Consider documenting which styles are being used for consistency.');
+            break;
+        case 'get_variables':
+            hints.push('💡 Tip: Variables are the foundation of a design system. Use these values instead of hardcoded colors/numbers.', '💡 Tip: Variable collections often represent different themes or modes (light/dark).');
+            break;
+        case 'capture_screenshot':
+            hints.push('💡 Tip: Screenshots are useful for verifying visual changes. Consider capturing before and after states.', '💡 Tip: Share screenshots with the user to confirm the design matches expectations.');
+            break;
+        case 'update_node':
+        case 'move_node':
+        case 'delete_node':
+            hints.push('💡 Tip: Use `capture_screenshot` to verify the visual result of your changes.', '💡 Tip: Consider using `get_node` to confirm the update was applied correctly.');
+            break;
+    }
+    return hints;
+}
+// Set to true to enable contextual hints in responses
+const HINTS_ENABLED = false;
+export function formatResponseWithHints(result, toolName, args) {
+    const resultJson = JSON.stringify(result, null, 2);
+    if (!HINTS_ENABLED) {
+        return resultJson;
+    }
+    const sections = [resultJson];
+    // Add improvement agent hint on first tool call
+    const improvementHint = getImprovementHint();
+    if (improvementHint) {
+        sections.push(improvementHint);
+    }
+    // Add contextual tool hints
+    const hints = getHintsForTool({ toolName, result, args });
+    if (hints.length > 0) {
+        // Select 1-2 random hints to avoid overwhelming the response
+        const selectedHints = hints
+            .sort(() => Math.random() - 0.5)
+            .slice(0, 2);
+        sections.push(selectedHints.join('\n'));
+    }
+    return sections.join('\n\n---\n');
+}

package/dist/hub.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * Standalone WebSocket hub that routes messages between multiple MCP server
+ * instances and the Figma plugin.  Auto-exits after an idle timeout when all
+ * clients have disconnected.
+ *
+ * Launched automatically by the first MCP server that starts.
+ */
+export {};

package/dist/hub.js

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+/**
+ * Standalone WebSocket hub that routes messages between multiple MCP server
+ * instances and the Figma plugin.  Auto-exits after an idle timeout when all
+ * clients have disconnected.
+ *
+ * Launched automatically by the first MCP server that starts.
+ */
+import { WebSocketServer, WebSocket } from 'ws';
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+// ---------- port validation ----------
+const port = parseInt(process.env.FIGMA_HUB_PORT || '3001', 10);
+if (isNaN(port) || port < 1 || port > 65535) {
+    console.error('[Hub] Invalid port number');
+    process.exit(1);
+}
+const PORT = port;
+// ---------- auth token ----------
+const AUTH_TOKEN = crypto.randomBytes(32).toString('hex');
+const TOKEN_PATH = path.join(os.homedir(), '.figma-mcp-hub-token');
+fs.writeFileSync(TOKEN_PATH, AUTH_TOKEN, { mode: 0o600 });
+function cleanup() {
+    try {
+        fs.unlinkSync(TOKEN_PATH);
+    }
+    catch { }
+}
+process.on('exit', cleanup);
+const IDLE_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes
+// ---------- state ----------
+let figmaPlugin = null;
+let pluginEditorType = null;
+const mcpClients = new Map();
+let idleTimer = null;
+// ---------- rate limiting ----------
+const messageTimestamps = new WeakMap();
+const RATE_LIMIT_WINDOW = 10000; // 10 seconds
+const RATE_LIMIT_MAX = 100;
+function checkRateLimit(ws) {
+    const now = Date.now();
+    let timestamps = messageTimestamps.get(ws);
+    if (!timestamps) {
+        timestamps = [];
+        messageTimestamps.set(ws, timestamps);
+    }
+    // Remove old entries outside window
+    while (timestamps.length > 0 && timestamps[0] <= now - RATE_LIMIT_WINDOW) {
+        timestamps.shift();
+    }
+    if (timestamps.length >= RATE_LIMIT_MAX) {
+        return false; // rate limited
+    }
+    timestamps.push(now);
+    return true;
+}
+// ---------- idle management ----------
+function resetIdleTimer() {
+    if (idleTimer)
+        clearTimeout(idleTimer);
+    idleTimer = null;
+}
+function startIdleTimerIfEmpty() {
+    if (mcpClients.size === 0 && !figmaPlugin) {
+        idleTimer = setTimeout(() => {
+            console.error('[Hub] No clients for 5 minutes — shutting down.');
+            process.exit(0);
+        }, IDLE_TIMEOUT_MS);
+    }
+}
+// ---------- helpers ----------
+function broadcastSessionList() {
+    if (!figmaPlugin || figmaPlugin.readyState !== WebSocket.OPEN)
+        return;
+    const sessions = Array.from(mcpClients.values()).map((c) => ({
+        sessionId: c.sessionId,
+        clientInfo: c.clientInfo,
+    }));
+    figmaPlugin.send(JSON.stringify({ type: 'sessions', sessions }));
+}
+// ---------- server ----------
+const wss = new WebSocketServer({ port: PORT, host: '127.0.0.1', maxPayload: 512 * 1024 });
+wss.on('listening', () => {
+    console.error(`[Hub] Listening on port ${PORT}`);
+});
+wss.on('connection', (ws) => {
+    // Every new connection must send a `register` message first.
+    let registered = false;
+    const registrationTimeout = setTimeout(() => {
+        if (!registered) {
+            console.error('[Hub] Connection did not register in time — closing');
+            ws.close(4000, 'Registration timeout');
+        }
+    }, 5000);
+    ws.on('message', (raw) => {
+        if (!checkRateLimit(ws)) {
+            ws.send(JSON.stringify({ error: 'Rate limit exceeded. Max 100 messages per 10 seconds.' }));
+            return;
+        }
+        let msg;
+        try {
+            msg = JSON.parse(raw.toString());
+        }
+        catch {
+            return;
+        }
+        // ── registration ──
+        if (!registered && msg.type === 'register') {
+            registered = true;
+            clearTimeout(registrationTimeout);
+            resetIdleTimer();
+            if (msg.role === 'figma-plugin') {
+                figmaPlugin = ws;
+                console.error('[Hub] Figma plugin connected');
+                if (msg.editorType) {
+                    pluginEditorType = msg.editorType;
+                }
+                // Send stored client infos so the plugin sees all agents
+                broadcastSessionList();
+                return;
+            }
+            if (msg.role === 'mcp-server') {
+                if (msg.token !== AUTH_TOKEN) {
+                    console.error('[Hub] MCP server rejected: invalid token');
+                    ws.close(4001, 'Invalid authentication token');
+                    return;
+                }
+                const sessionId = msg.sessionId;
+                mcpClients.set(sessionId, { ws, sessionId, clientInfo: null });
+                console.error(`[Hub] MCP server registered: ${sessionId}`);
+                // Tell MCP server whether plugin is connected
+                ws.send(JSON.stringify({
+                    type: 'hub-status',
+                    pluginConnected: figmaPlugin !== null && figmaPlugin.readyState === WebSocket.OPEN,
+                    editorType: pluginEditorType,
+                }));
+                broadcastSessionList();
+                return;
+            }
+            console.error('[Hub] Unknown role:', msg.role);
+            return;
+        }
+        if (!registered)
+            return; // ignore messages before registration
+        // ── messages FROM mcp-server ──
+        // Find which MCP client sent this
+        const sender = Array.from(mcpClients.values()).find((c) => c.ws === ws);
+        if (sender) {
+            // clientInfo update
+            if (msg.type === 'clientInfo') {
+                sender.clientInfo = msg.clientInfo;
+                console.error(`[Hub] Client info from ${sender.sessionId}: ${sender.clientInfo?.name}`);
+                broadcastSessionList();
+                return;
+            }
+            // command → forward to plugin with sessionId tag
+            if (msg.command) {
+                if (!figmaPlugin || figmaPlugin.readyState !== WebSocket.OPEN) {
+                    // Send error response back
+                    ws.send(JSON.stringify({
+                        id: msg.id,
+                        success: false,
+                        error: 'Figma plugin is not connected. Please open the Figma plugin first.',
+                    }));
+                    return;
+                }
+                figmaPlugin.send(JSON.stringify({
+                    ...msg,
+                    sessionId: sender.sessionId,
+                }));
+                return;
+            }
+            return;
+        }
+        // ── messages FROM figma-plugin ──
+        if (ws === figmaPlugin) {
+            // editorType update
+            if (msg.type === 'editorType') {
+                pluginEditorType = msg.editorType;
+                console.error(`[Hub] Editor type: ${pluginEditorType}`);
+                return;
+            }
+            // response → route back to correct MCP server by sessionId
+            if (msg.id && msg.sessionId) {
+                const target = mcpClients.get(msg.sessionId);
+                if (target && target.ws.readyState === WebSocket.OPEN) {
+                    // Strip sessionId before forwarding to MCP server
+                    const { sessionId: _sid, ...response } = msg;
+                    target.ws.send(JSON.stringify(response));
+                }
+                else {
+                    console.error(`[Hub] No MCP client for session: ${msg.sessionId}`);
+                }
+                return;
+            }
+            // response without sessionId (legacy) — try to match by request ID
+            if (msg.id) {
+                // Broadcast to all MCP clients; only the one with the matching pending
+                // request will use it (safe because IDs are UUIDs).
+                for (const client of mcpClients.values()) {
+                    if (client.ws.readyState === WebSocket.OPEN) {
+                        client.ws.send(JSON.stringify(msg));
+                    }
+                }
+            }
+        }
+    });
+    ws.on('close', () => {
+        clearTimeout(registrationTimeout);
+        if (ws === figmaPlugin) {
+            figmaPlugin = null;
+            pluginEditorType = null;
+            console.error('[Hub] Figma plugin disconnected');
+            // Notify all MCP servers
+            for (const client of mcpClients.values()) {
+                if (client.ws.readyState === WebSocket.OPEN) {
+                    client.ws.send(JSON.stringify({ type: 'plugin-disconnected' }));
+                }
+            }
+        }
+        else {
+            // An MCP server disconnected
+            for (const [sid, client] of mcpClients) {
+                if (client.ws === ws) {
+                    mcpClients.delete(sid);
+                    console.error(`[Hub] MCP server disconnected: ${sid}`);
+                    broadcastSessionList();
+                    break;
+                }
+            }
+        }
+        startIdleTimerIfEmpty();
+    });
+    ws.on('error', (err) => {
+        console.error('[Hub] Socket error:', err.message);
+    });
+});
+wss.on('error', (error) => {
+    if (error.code === 'EADDRINUSE') {
+        // Another hub is already running — just exit silently.
+        console.error(`[Hub] Port ${PORT} already in use — another hub is running.`);
+        process.exit(0);
+    }
+    console.error('[Hub] Server error:', error);
+});
+// Start idle timer immediately (will be cleared once first client connects)
+startIdleTimerIfEmpty();
+// Graceful shutdown
+process.on('SIGTERM', () => { cleanup(); process.exit(0); });
+process.on('SIGINT', () => { cleanup(); process.exit(0); });

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { figmaWebSocket } from './websocket.js';
+import { assetServer } from './assetServer.js';
+// Direct tools (only those with special MCP response handling)
+import { captureScreenshotSchema, captureScreenshot } from './tools/captureScreenshot.js';
+import { getDesignContextSchema, getDesignContext } from './tools/getDesignContext.js';
+// New tools
+import { executeSchema } from './tools/execute.js';
+import { searchToolsSchema } from './tools/searchTools.js';
+import { createAndRunSandbox } from './sandbox.js';
+import { searchRegistry } from './toolRegistry.js';
+const server = new Server({
+    name: 'figma-code-agent',
+    version: '1.0.0',
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Send client info to Figma plugin when MCP client is initialized
+server.oninitialized = () => {
+    const clientVersion = server.getClientVersion();
+    // Include project path so plugin UI shows which session is connected
+    const cwd = process.cwd();
+    const projectName = cwd.split('/').pop() || cwd;
+    figmaWebSocket.setClientInfo({
+        name: clientVersion?.name || 'MCP Client',
+        version: clientVersion?.version,
+        projectPath: projectName,
+    });
+};
+// List available tools (4 total)
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            executeSchema,
+            searchToolsSchema,
+            captureScreenshotSchema,
+            getDesignContextSchema,
+        ],
+    };
+});
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+    try {
+        let result;
+        switch (name) {
+            case 'execute': {
+                const code = args.code;
+                if (!code) {
+                    throw new Error('Missing required parameter: code');
+                }
+                const sandboxResult = await createAndRunSandbox(code);
+                const parts = [];
+                if (sandboxResult.error) {
+                    parts.push(`Error: ${sandboxResult.error}`);
+                }
+                else {
+                    parts.push(JSON.stringify(sandboxResult.result, null, 2));
+                }
+                if (sandboxResult.logs.length > 0) {
+                    parts.push(`\n--- Console Output ---\n${sandboxResult.logs.join('\n')}`);
+                }
+                parts.push(`\n(executed in ${sandboxResult.duration}ms)`);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: parts.join('\n'),
+                        },
+                    ],
+                    isError: !!sandboxResult.error,
+                };
+            }
+            case 'search_tools': {
+                const query = args.query;
+                if (!query) {
+                    throw new Error('Missing required parameter: query');
+                }
+                const category = args.category;
+                const detailLevel = args.detail_level || 'description';
+                result = searchRegistry(query, category, detailLevel);
+                break;
+            }
+            case 'capture_screenshot': {
+                const screenshotResult = await captureScreenshot(args);
+                const format = (args.format || 'PNG').toUpperCase();
+                const mimeType = format === 'JPG' ? 'image/jpeg' :
+                    format === 'SVG' ? 'image/svg+xml' :
+                        format === 'PDF' ? 'application/pdf' : 'image/png';
+                return {
+                    content: [
+                        {
+                            type: 'image',
+                            data: screenshotResult.data,
+                            mimeType,
+                        },
+                    ],
+                };
+            }
+            case 'get_design_context':
+                result = await getDesignContext(args);
+                break;
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: `Error: ${errorMessage}`,
+                },
+            ],
+            isError: true,
+        };
+    }
+});
+async function main() {
+    // Connect to WebSocket hub (launches hub if needed)
+    await figmaWebSocket.initialize();
+    // Initialize asset server for serving exported images
+    assetServer.initialize();
+    // Connect MCP server via stdio
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('Figma MCP Server running on stdio');
+}
+main().catch((error) => {
+    console.error('Fatal error:', error);
+    process.exit(1);
+});

package/dist/sandbox.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Code execution sandbox using Node.js vm module.
+ * Provides a figma.* API that delegates to figmaWebSocket.sendCommand().
+ */
+export interface SandboxResult {
+    result: unknown;
+    logs: string[];
+    error?: string;
+    duration: number;
+}
+/**
+ * Format sandbox errors with contextual hints.
+ */
+export declare function formatSandboxError(error: unknown): string;
+/**
+ * Create a VM sandbox and run user code with the figma.* API.
+ */
+export declare function createAndRunSandbox(code: string, timeoutMs?: number): Promise<SandboxResult>;