figma-code-agent-mcp 1.0.0

package/dist/sandbox.js

@@ -0,0 +1,154 @@
+/**
+ * Code execution sandbox using Node.js vm module.
+ * Provides a figma.* API that delegates to figmaWebSocket.sendCommand().
+ */
+import vm from 'node:vm';
+import { figmaWebSocket } from './websocket.js';
+const globalSetTimeout = setTimeout;
+const MAX_LOG_CHARS = 10000;
+const DEFAULT_TIMEOUT_MS = 60000;
+/**
+ * Build the figma.* API object that wraps WebSocket commands.
+ * Each method strips returnScreenshot before sending.
+ */
+function buildFigmaApi() {
+    const makeCommand = (command, hasParams = true) => {
+        return async (params) => {
+            const cleanParams = { ...(hasParams ? params || {} : {}) };
+            delete cleanParams.returnScreenshot;
+            return figmaWebSocket.sendCommand(command, cleanParams);
+        };
+    };
+    return {
+        // Create
+        create: makeCommand('create'),
+        createFrame: makeCommand('createFrame'),
+        createRectangle: makeCommand('createRectangle'),
+        createText: makeCommand('createText'),
+        createEllipse: makeCommand('createEllipse'),
+        createLine: makeCommand('createLine'),
+        createInstance: makeCommand('createInstance'),
+        cloneNode: makeCommand('cloneNode'),
+        // Read
+        getNode: makeCommand('getNode'),
+        getSelection: makeCommand('getSelection', false),
+        getCurrentPage: makeCommand('getCurrentPage'),
+        getStyles: makeCommand('getStyles'),
+        getLocalComponents: makeCommand('getLocalComponents'),
+        getVariables: makeCommand('getVariables'),
+        searchNodes: makeCommand('searchNodes'),
+        captureScreenshot: makeCommand('captureScreenshot'),
+        // Update
+        updateNode: makeCommand('updateNode'),
+        moveNode: makeCommand('moveNode'),
+        swapComponent: makeCommand('swapComponent'),
+        // Delete
+        deleteNode: makeCommand('deleteNode'),
+        // Tokens
+        createToken: makeCommand('createToken'),
+        bindToken: makeCommand('bindToken'),
+        // Components
+        toComponent: makeCommand('toComponent'),
+        createVariants: makeCommand('createVariants'),
+        addComponentProperty: makeCommand('addComponentProperty'),
+        setInstanceOverride: makeCommand('setInstanceOverride'),
+        // Accessibility
+        checkAccessibility: makeCommand('checkAccessibility'),
+        // FigJam-specific create methods
+        createSection: makeCommand('createSection'),
+        createSticky: makeCommand('createSticky'),
+        createShape: makeCommand('createShapeWithText'),
+        createConnector: makeCommand('createConnector'),
+        // Meta
+        getEditorType: makeCommand('getEditorType', false),
+    };
+}
+/**
+ * Format sandbox errors with contextual hints.
+ */
+export function formatSandboxError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    const stack = error instanceof Error ? error.stack || '' : '';
+    // Clean stack trace: remove node:vm internals and strip file paths
+    const cleanStack = stack
+        .split('\n')
+        .filter((line) => !line.includes('node:vm') && !line.includes('node:internal'))
+        .map((line) => line.replace(/\(\/[^)]+\)/g, '(<sandbox>)').replace(/at \/[^\s]+/g, 'at <sandbox>'))
+        .slice(0, 5)
+        .join('\n');
+    let hint = '';
+    if (message.includes('is not a function')) {
+        hint = '\nHint: Method not found. Use the search_tools tool to discover available figma.* methods.';
+    }
+    else if (message.includes('not connected') || message.includes('plugin')) {
+        hint = '\nHint: The Figma plugin is not connected. Please open the Figma desktop app and run the MCP plugin.';
+    }
+    else if (message.includes('timed out') || message.includes('Script execution timed out')) {
+        hint = '\nHint: Operation timed out. Try breaking into smaller operations or reducing the scope.';
+    }
+    else if (message.includes('Node not found') || message.includes('not found')) {
+        hint = '\nHint: Node not found. Use figma.getSelection() or figma.searchNodes() to find valid node IDs.';
+    }
+    return `${message}${cleanStack ? '\n' + cleanStack : ''}${hint}`;
+}
+/**
+ * Create a VM sandbox and run user code with the figma.* API.
+ */
+export async function createAndRunSandbox(code, timeoutMs = DEFAULT_TIMEOUT_MS) {
+    const startTime = Date.now();
+    const logs = [];
+    let totalLogChars = 0;
+    const appendLog = (level, args) => {
+        if (totalLogChars >= MAX_LOG_CHARS)
+            return;
+        const msg = `[${level}] ${args.map((a) => (typeof a === 'object' ? JSON.stringify(a) : String(a))).join(' ')}`;
+        const truncated = msg.slice(0, MAX_LOG_CHARS - totalLogChars);
+        logs.push(truncated);
+        totalLogChars += truncated.length;
+    };
+    const frozenConsole = Object.freeze({
+        log: (...args) => appendLog('log', args),
+        warn: (...args) => appendLog('warn', args),
+        error: (...args) => appendLog('error', args),
+    });
+    const figmaApi = Object.freeze(buildFigmaApi());
+    const contextObject = {
+        figma: figmaApi,
+        console: frozenConsole,
+        JSON: Object.freeze({ parse: JSON.parse, stringify: JSON.stringify }),
+        Math: Object.freeze(Object.create(Math)),
+        parseInt,
+        parseFloat,
+        sleep: Object.freeze((ms) => new Promise(resolve => globalSetTimeout(resolve, Math.min(ms, 5000)))),
+    };
+    const context = vm.createContext(contextObject);
+    // Wrap code in async IIFE so top-level await works
+    const wrappedCode = `(async () => { ${code} })()`;
+    try {
+        const script = new vm.Script(wrappedCode, {
+            filename: 'execute.js',
+        });
+        // Run in context — timeout covers synchronous execution
+        const promise = script.runInContext(context, {
+            timeout: timeoutMs,
+        });
+        // Race against timeout for async operations
+        const result = await Promise.race([
+            promise,
+            new Promise((_, reject) => globalSetTimeout(() => reject(new Error('Script execution timed out')), timeoutMs)),
+        ]);
+        return {
+            result: result === undefined ? null : result,
+            logs,
+            duration: Date.now() - startTime,
+        };
+    }
+    catch (error) {
+        return {
+            result: null,
+            logs,
+            error: formatSandboxError(error),
+            duration: Date.now() - startTime,
+        };
+    }
+}

package/dist/toolRegistry.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Registry of all figma.* methods available in the execute sandbox.
+ * Powers the search_tools tool for progressive API discovery.
+ */
+export interface ToolEntry {
+    name: string;
+    category: 'create' | 'read' | 'update' | 'delete' | 'tokens' | 'components' | 'accessibility' | 'figjam';
+    description: string;
+    parameters: Record<string, {
+        type: string;
+        description: string;
+        required?: boolean;
+        default?: unknown;
+    }>;
+    returns: string;
+    example: string;
+}
+export type DetailLevel = 'name' | 'description' | 'full';
+export declare function searchRegistry(query: string, category?: 'create' | 'read' | 'update' | 'delete' | 'tokens' | 'components' | 'accessibility' | 'figjam', detailLevel?: DetailLevel): unknown[];