@sangheepark/figma-ds-mcp 0.1.0

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+/**
+ * Code-to-Figma MCP Server
+ *
+ * Bridges Claude Code (via MCP/stdio) to the Figma Bridge Plugin (via WebSocket).
+ * Provides tools for creating Figma components from JSON specs.
+ */
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { FigmaBridge } from './ws-bridge.js';
+import { registerUtilityTools } from './tools/utility-tools.js';
+import { registerSpecTools } from './tools/spec-tools.js';
+import { registerModeTools } from './tools/mode-tools.js';
+import { registerVariableTools } from './tools/variable-tools.js';
+import { registerStyleTools } from './tools/style-tools.js';
+import { registerDataTools } from './tools/data-tools.js';
+// Create the WebSocket bridge to Figma
+const bridge = new FigmaBridge();
+// Create MCP server
+const server = new McpServer({
+    name: 'code-to-figma',
+    version: '0.1.0',
+});
+// Register all tools
+registerUtilityTools(server, bridge);
+registerSpecTools(server, bridge);
+registerModeTools(server, bridge);
+registerVariableTools(server, bridge);
+registerStyleTools(server, bridge);
+registerDataTools(server, bridge);
+// Connect to Claude Code via stdio
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('[MCP] Code-to-Figma MCP server started (stdio + WebSocket on port 3055)');
+}
+main().catch((error) => {
+    console.error('[MCP] Fatal error:', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/tools/data-tools.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { FigmaBridge } from '../ws-bridge.js';
+export declare function registerDataTools(server: McpServer, bridge: FigmaBridge): void;

package/dist/tools/data-tools.js

@@ -0,0 +1,107 @@
+/**
+ * Data management tools: fetch_component_sets, export_style_guide, export_icons
+ * Phase 4 — Design system data update automation
+ */
+import { z } from 'zod';
+export function registerDataTools(server, bridge) {
+    // fetch_component_sets — Fetch component sets from Figma REST API (server-side, no bridge)
+    server.tool('fetch_component_sets', 'Fetch component sets from a Figma library file via REST API. Requires a Figma Personal Access Token (PAT) and file key. Returns component set names, keys, and node IDs.', {
+        fileKey: z.string().describe('Figma file key (from URL: figma.com/design/{fileKey}/...)'),
+        token: z.string().describe('Figma Personal Access Token (PAT)'),
+    }, async ({ fileKey, token }) => {
+        try {
+            const url = `https://api.figma.com/v1/files/${fileKey}/component_sets`;
+            const response = await fetch(url, {
+                headers: { 'X-Figma-Token': token },
+            });
+            if (!response.ok) {
+                const errorText = await response.text();
+                throw new Error(`Figma API error (${response.status}): ${errorText}`);
+            }
+            const data = await response.json();
+            const componentSets = data.meta?.component_sets || [];
+            // Return summary + full data
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            message: `Fetched ${componentSets.length} component sets from file ${fileKey}`,
+                            count: componentSets.length,
+                            data: { meta: { component_sets: componentSets } },
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: msg }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+    });
+    // export_style_guide — Export styles, variables, and components from the current Figma file
+    server.tool('export_style_guide', 'Export the style guide (variables, styles, components) from the currently open Figma file. Returns both JSON (for import/preset) and Markdown (for AI context). Requires the Bridge plugin to be connected.', {}, async () => {
+        try {
+            const result = await bridge.send('bridge-export-style-guide', {});
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            message: `Exported style guide: ${result.variableCount} variables, ${result.styleCount} styles, ${result.componentCount} components, ${result.libraryComponentCount} library components`,
+                            variableCount: result.variableCount,
+                            styleCount: result.styleCount,
+                            componentCount: result.componentCount,
+                            libraryComponentCount: result.libraryComponentCount,
+                            json: result.json,
+                            markdown: result.markdown,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: msg }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+    });
+    // export_icons — Extract icon component keys from the current Figma page
+    server.tool('export_icons', 'Extract icon component names and published keys from instances on the current Figma page. Returns an array of { name, key } objects. Requires the Bridge plugin to be connected and the icon page to be open.', {}, async () => {
+        try {
+            const result = await bridge.send('bridge-export-icons', {});
+            const icons = (result.icons || []);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            message: `Exported ${icons.length} icon keys from current page`,
+                            count: icons.length,
+                            icons,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: msg }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=data-tools.js.map

package/dist/tools/mode-tools.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { FigmaBridge } from '../ws-bridge.js';
+export declare function registerModeTools(server: McpServer, bridge: FigmaBridge): void;

package/dist/tools/mode-tools.js

@@ -0,0 +1,153 @@
+/**
+ * Mode tools: set_style_mode, load_preset, get_presets
+ */
+import { z } from 'zod';
+export function registerModeTools(server, bridge) {
+    // set_style_mode — Set the style resolution mode for subsequent operations
+    server.tool('set_style_mode', `Set the style resolution mode for subsequent create operations.
+- "hardcode": Use raw color/size values directly
+- "variable": Bind to Figma variable tokens using {varName} syntax
+- "library": Use library style references with @StyleName syntax and {varName} for variables
+
+After setting "library" mode, you should also call load_preset to load a library preset.`, {
+        mode: z.enum(['hardcode', 'variable', 'library']).describe('Style resolution mode'),
+    }, async ({ mode }) => {
+        try {
+            const result = await bridge.send('bridge-set-style-mode', { mode });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            mode,
+                            message: result.message || `Style mode set to "${mode}"`,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: msg }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+    });
+    // load_preset — Load a library preset (required for library mode)
+    server.tool('load_preset', `Load a library preset by ID. Use get_presets first to see available presets.
+Loading a preset provides variable names, style names, and library component keys for use in specs.`, {
+        presetId: z.string().describe('Preset ID from get_presets list'),
+    }, async ({ presetId }) => {
+        try {
+            const result = await bridge.send('bridge-load-preset', { presetId });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            presetId: result.presetId,
+                            libraryName: result.libraryName,
+                            varCount: result.varCount,
+                            styleCount: result.styleCount,
+                            componentCount: result.componentCount,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: msg }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+    });
+    // get_presets — List available library presets
+    server.tool('get_presets', 'List all available library presets bundled in the plugin. Returns preset IDs, names, and descriptions.', {}, async () => {
+        try {
+            const result = await bridge.send('bridge-get-presets', {});
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            presets: result.presets || [],
+                            activePresetIds: result.activePresetIds || [],
+                            primaryPresetId: result.primaryPresetId || null,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: msg }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+    });
+    // create_instance — Create a library/local component instance
+    server.tool('create_instance', `Create an instance of a library or local component in Figma.
+
+For library components, provide library-key (from preset data).
+For local components, provide component name.
+
+Supports:
+- variant selection: "Size=SM, Style=Primary"
+- property overrides: { "Label": "Custom Text", "showIcon": true }
+- text variable binding: { "Title": "i18n/greeting" }
+- nested overrides: [{ name: "Icon", variant: "Type=Arrow" }]`, {
+        parentId: z.string().optional().describe('Parent nodeId to add instance to (optional — if omitted, placed on canvas)'),
+        component: z.string().optional().describe('Local component name (for local instances)'),
+        'library-key': z.string().optional().describe('Library component key (from preset data)'),
+        variant: z.string().optional().describe('Variant selection string, e.g. "Size=SM, Style=Primary"'),
+        overrides: z.record(z.union([z.string(), z.boolean()])).optional()
+            .describe('Property overrides: { "Label": "Custom", "showIcon": true }'),
+        'text-variables': z.record(z.string()).optional()
+            .describe('Text variable bindings: { "Title": "i18n/greeting" }'),
+        'nested-overrides': z.array(z.object({
+            name: z.string(),
+            index: z.number().optional(),
+            variant: z.string().optional(),
+            overrides: z.record(z.union([z.string(), z.boolean()])).optional(),
+            'text-variables': z.record(z.string()).optional(),
+        })).optional()
+            .describe('Override child instances within the parent instance'),
+        layout: z.record(z.unknown()).optional().describe('Optional layout overrides'),
+        style: z.record(z.unknown()).optional().describe('Optional style overrides'),
+    }, async (params) => {
+        try {
+            const result = await bridge.send('bridge-create-instance', params);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            nodeId: result.nodeId,
+                            name: result.name,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: msg }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=mode-tools.js.map

package/dist/tools/spec-tools.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { FigmaBridge } from '../ws-bridge.js';
+export declare function registerSpecTools(server: McpServer, bridge: FigmaBridge): void;

package/dist/tools/spec-tools.js

@@ -0,0 +1,189 @@
+/**
+ * Spec tools: create_from_spec, create_node, add_child, modify_node
+ */
+import { z } from 'zod';
+// Reusable schema fragments
+const layoutSchema = z.object({
+    direction: z.enum(['row', 'column']).optional(),
+    gap: z.string().optional(),
+    padding: z.string().optional(),
+    'align-items': z.enum(['start', 'flex-start', 'center', 'end', 'flex-end', 'stretch', 'baseline']).optional(),
+    'justify-content': z.enum(['start', 'flex-start', 'center', 'end', 'flex-end', 'space-between']).optional(),
+    width: z.string().optional(),
+    height: z.string().optional(),
+    positioning: z.enum(['auto', 'absolute']).optional(),
+    x: z.string().optional(),
+    y: z.string().optional(),
+    wrap: z.boolean().optional(),
+    'wrap-gap': z.string().optional(),
+    'z-order': z.enum(['first-on-top', 'last-on-top']).optional(),
+    'clip-content': z.boolean().optional(),
+    rotation: z.number().optional(),
+    'min-width': z.string().optional(),
+    'max-width': z.string().optional(),
+    'min-height': z.string().optional(),
+    'max-height': z.string().optional(),
+}).passthrough().optional().describe('Layout properties (CSS flexbox terms)');
+const styleSchema = z.object({
+    background: z.string().optional(),
+    'border-radius': z.string().optional(),
+    border: z.string().optional(),
+    'border-top': z.string().optional(),
+    'border-bottom': z.string().optional(),
+    'border-left': z.string().optional(),
+    'border-right': z.string().optional(),
+    opacity: z.number().optional(),
+    'font-family': z.string().optional(),
+    'font-size': z.string().optional(),
+    'font-weight': z.string().optional(),
+    color: z.string().optional(),
+    'text-align': z.enum(['left', 'center', 'right', 'justify']).optional(),
+    'line-height': z.string().optional(),
+    'letter-spacing': z.string().optional(),
+    'text-style': z.string().optional(),
+    'effect-style': z.string().optional(),
+}).passthrough().optional().describe('Style properties (CSS terms). Use {varName} for variable tokens, @StyleName for library styles.');
+export function registerSpecTools(server, bridge) {
+    // create_from_spec — Full spec in one shot (JSON, not YAML)
+    server.tool('create_from_spec', `Create a Figma component/frame/component-set from a complete JSON spec. This is the primary tool for creating Figma components.
+
+The spec follows the same structure as the YAML format but in JSON:
+- name (required): Component name
+- type: "frame" | "component" | "component-set"
+- layout: { direction, gap, padding, align-items, justify-content, width, height, ... }
+- style: { background, border-radius, color, font-size, ... }
+- children: Array of child node specs
+- variants: Array of variant specs (for component-set)
+- properties: Component property definitions
+
+Style values can use:
+- {variableName} for variable token binding
+- @StyleName for library style references
+
+If a component with the same name already exists, it will be updated in-place.`, {
+        spec: z.record(z.unknown()).describe('The complete RootSpec object (name, type, layout, style, children, variants, properties)'),
+        styleMode: z.enum(['hardcode', 'variable', 'library']).optional()
+            .describe('Style resolution mode. If omitted, uses the session style mode set by set_style_mode.'),
+    }, async ({ spec, styleMode }) => {
+        try {
+            const result = await bridge.send('bridge-create-from-spec', { spec, styleMode });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            message: result.message || 'Created successfully',
+                            nodeId: result.nodeId,
+                            name: result.name,
+                            warnings: result.warnings,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: msg }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+    });
+    // create_node — Create a single empty node (for incremental building)
+    server.tool('create_node', `Create a single Figma node (frame or component) without children. Returns nodeId for use with add_child.
+Use this for incremental/step-by-step component building.`, {
+        type: z.enum(['frame', 'component']).describe('Node type'),
+        name: z.string().describe('Node name'),
+        layout: layoutSchema,
+        style: styleSchema,
+    }, async ({ type, name, layout, style }) => {
+        try {
+            const result = await bridge.send('bridge-create-node', { type, name, layout, style });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            nodeId: result.nodeId,
+                            name: result.name,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: msg }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+    });
+    // add_child — Add a child node to an existing parent
+    server.tool('add_child', `Add a child node to an existing parent frame/component. The child spec follows the ChildNodeSpec format:
+- type: "frame" | "text" | "rectangle" | "instance" | "vector"
+- name, content (text), layout, style, children, etc.
+- For instances: component, library-key, variant, overrides, text-variables, nested-overrides`, {
+        parentId: z.string().describe('The nodeId of the parent frame/component'),
+        child: z.record(z.unknown()).describe('ChildNodeSpec object: { type, name, content, layout, style, children, ... }'),
+    }, async ({ parentId, child }) => {
+        try {
+            const result = await bridge.send('bridge-add-child', { parentId, child });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            nodeId: result.nodeId,
+                            name: result.name,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: msg }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+    });
+    // modify_node — Modify an existing node's layout/style
+    server.tool('modify_node', 'Modify the layout and/or style of an existing Figma node by its nodeId.', {
+        nodeId: z.string().describe('The nodeId of the node to modify'),
+        layout: layoutSchema,
+        style: styleSchema,
+    }, async ({ nodeId, layout, style }) => {
+        try {
+            const result = await bridge.send('bridge-modify-node', { nodeId, layout, style });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            nodeId: result.nodeId,
+                            message: result.message || 'Node modified',
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: msg }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=spec-tools.js.map

package/dist/tools/style-tools.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { FigmaBridge } from '../ws-bridge.js';
+export declare function registerStyleTools(server: McpServer, bridge: FigmaBridge): void;

package/dist/tools/style-tools.js

@@ -0,0 +1,122 @@
+/**
+ * Style tools: create_text_styles, create_effect_styles
+ */
+import { z } from 'zod';
+export function registerStyleTools(server, bridge) {
+    // create_text_styles — Create Text Styles
+    server.tool('create_text_styles', `Create Figma Text Styles.
+
+Example:
+{
+  "name": "Typography",
+  "font-family": "Inter",
+  "styles": [
+    { "name": "Heading/H1", "font-size": "48px", "font-weight": 700, "line-height": "120%" },
+    { "name": "Body/MD", "font-size": "16px", "font-weight": 400, "line-height": "150%" }
+  ]
+}`, {
+        name: z.string().describe('Style group name'),
+        'font-family': z.string().optional().describe('Default font family for all styles'),
+        styles: z.array(z.object({
+            name: z.string(),
+            'font-family': z.string().optional(),
+            'font-size': z.string().describe('e.g. "16px"'),
+            'font-weight': z.number().optional(),
+            'line-height': z.string().optional().describe('e.g. "150%", "24px", "auto"'),
+            'letter-spacing': z.string().optional(),
+            'text-decoration': z.enum(['none', 'underline', 'strikethrough']).optional(),
+            'text-case': z.enum(['original', 'uppercase', 'lowercase', 'capitalize']).optional(),
+            description: z.string().optional(),
+        })).describe('Text style definitions'),
+    }, async (params) => {
+        try {
+            const spec = {
+                type: 'text-styles',
+                ...params,
+            };
+            const result = await bridge.send('bridge-create-text-styles', { spec });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            styleCount: result.styleCount,
+                            createdCount: result.createdCount,
+                            updatedCount: result.updatedCount,
+                            message: result.message,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: msg }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+    });
+    // create_effect_styles — Create Effect Styles
+    server.tool('create_effect_styles', `Create Figma Effect Styles (shadows, blurs).
+
+Example:
+{
+  "name": "Effects",
+  "styles": [
+    {
+      "name": "Shadow/MD",
+      "effects": [
+        { "type": "drop-shadow", "x": 0, "y": 4, "blur": 6, "spread": -1, "color": "rgba(0,0,0,0.1)" }
+      ]
+    }
+  ]
+}`, {
+        name: z.string().describe('Style group name'),
+        styles: z.array(z.object({
+            name: z.string(),
+            effects: z.array(z.object({
+                type: z.enum(['drop-shadow', 'inner-shadow', 'layer-blur', 'background-blur']),
+                x: z.number().optional(),
+                y: z.number().optional(),
+                blur: z.number(),
+                spread: z.number().optional(),
+                color: z.string().optional(),
+            })).describe('Effect definitions'),
+            description: z.string().optional(),
+        })).describe('Effect style definitions'),
+    }, async (params) => {
+        try {
+            const spec = {
+                type: 'effect-styles',
+                ...params,
+            };
+            const result = await bridge.send('bridge-create-effect-styles', { spec });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            styleCount: result.styleCount,
+                            createdCount: result.createdCount,
+                            updatedCount: result.updatedCount,
+                            message: result.message,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: msg }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=style-tools.js.map

package/dist/tools/utility-tools.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { FigmaBridge } from '../ws-bridge.js';
+export declare function registerUtilityTools(server: McpServer, bridge: FigmaBridge): void;

package/dist/tools/utility-tools.js

@@ -0,0 +1,92 @@
+/**
+ * Utility tools: get_status, validate_spec, generate_from_yaml
+ */
+import { z } from 'zod';
+export function registerUtilityTools(server, bridge) {
+    // get_status — Check connection status
+    server.tool('get_status', 'Check if the Figma Bridge plugin is connected and ready', {}, async () => {
+        const connected = bridge.isConnected();
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify({
+                        connected,
+                        message: connected
+                            ? 'Figma Bridge plugin is connected and ready.'
+                            : 'Figma Bridge plugin is NOT connected. Please open the "Code to Figma Bridge" plugin in Figma.',
+                    }, null, 2),
+                }],
+        };
+    });
+    // validate_spec — Validate a JSON spec without creating anything
+    server.tool('validate_spec', 'Validate a component/variable/style spec (JSON) without creating anything in Figma. Returns validation errors if any.', {
+        spec: z.record(z.unknown()).describe('The spec object to validate (same format as create_from_spec)'),
+    }, async ({ spec }) => {
+        // We convert the spec to YAML-like format and send it to the plugin's validate handler
+        // Actually, we send it as a bridge-validate-spec message that the plugin will handle
+        try {
+            const result = await bridge.send('bridge-validate-spec', { spec });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            valid: true,
+                            specType: result.specType || 'node',
+                            message: result.message || 'Spec is valid',
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            valid: false,
+                            error: msg,
+                        }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+    });
+    // generate_from_yaml — Legacy YAML passthrough for compatibility
+    server.tool('generate_from_yaml', 'Generate Figma components from YAML text (legacy passthrough). Prefer using create_from_spec with JSON instead.', {
+        yaml: z.string().describe('YAML spec text'),
+        styleMode: z.enum(['hardcode', 'variable', 'library']).optional().default('hardcode')
+            .describe('Style resolution mode: hardcode (raw values), variable (token binding), library (library style refs)'),
+        dryRun: z.boolean().optional().default(false)
+            .describe('If true, preview what would be created without actually creating'),
+    }, async ({ yaml, styleMode, dryRun }) => {
+        try {
+            const result = await bridge.send('generate', {
+                yaml,
+                styleMode,
+                collectionId: styleMode === 'variable' ? 'all' : null,
+                dryRun,
+            });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            message: result.message || 'Generated successfully',
+                            data: result,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: msg }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=utility-tools.js.map

package/dist/tools/variable-tools.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { FigmaBridge } from '../ws-bridge.js';
+export declare function registerVariableTools(server: McpServer, bridge: FigmaBridge): void;

package/dist/tools/variable-tools.js

@@ -0,0 +1,109 @@
+/**
+ * Variable tools: create_variables, create_i18n_variables
+ */
+import { z } from 'zod';
+export function registerVariableTools(server, bridge) {
+    // create_variables — Create a Variable Collection
+    server.tool('create_variables', `Create a Figma Variable Collection with multi-mode support.
+
+Example:
+{
+  "name": "Colors",
+  "modes": ["Light", "Dark"],
+  "variables": [
+    { "name": "brand/primary", "type": "COLOR", "values": { "Light": "#3B82F6", "Dark": "#60A5FA" } },
+    { "name": "spacing/md", "type": "FLOAT", "values": { "Light": "16", "Dark": "16" } }
+  ]
+}`, {
+        name: z.string().describe('Collection name'),
+        modes: z.array(z.string()).min(1).describe('Mode names, e.g. ["Light", "Dark"]'),
+        description: z.string().optional(),
+        variables: z.array(z.object({
+            name: z.string(),
+            type: z.enum(['COLOR', 'FLOAT', 'STRING', 'BOOLEAN']),
+            values: z.record(z.string()).describe('Mode name → value mapping'),
+            description: z.string().optional(),
+            scopes: z.array(z.string()).optional(),
+        })).describe('Variable definitions'),
+    }, async (params) => {
+        try {
+            const spec = {
+                type: 'variable-collection',
+                ...params,
+            };
+            const result = await bridge.send('bridge-create-variables', { spec });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            collectionName: result.collectionName,
+                            variableCount: result.variableCount,
+                            modeCount: result.modeCount,
+                            message: result.message,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: msg }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+    });
+    // create_i18n_variables — Create/update i18n STRING variables
+    server.tool('create_i18n_variables', `Create or update i18n STRING variables in a Figma Variable Collection.
+
+Example:
+{
+  "collection": "Translations",
+  "modes": { "Eng": "en", "Kor": "ko" },
+  "data": {
+    "greeting": { "en": "Hello", "ko": "안녕하세요" },
+    "farewell": { "en": "Goodbye", "ko": "안녕히 가세요" }
+  }
+}`, {
+        collection: z.string().describe('Variable Collection name'),
+        modes: z.record(z.string()).describe('Figma mode name → input key mapping, e.g. { "Eng": "en", "Kor": "ko" }'),
+        'skip-same-value': z.boolean().optional().default(true)
+            .describe('Skip variables where all mode values are identical'),
+        delete: z.array(z.string()).optional()
+            .describe('Variable names to delete from collection'),
+        data: z.record(z.record(z.string()))
+            .describe('Variable data: { variableName: { modeKey: value } }'),
+    }, async (params) => {
+        try {
+            const spec = {
+                type: 'i18n',
+                ...params,
+            };
+            const result = await bridge.send('bridge-create-i18n-variables', { spec });
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            success: true,
+                            message: result.message,
+                            data: result,
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            const msg = error instanceof Error ? error.message : 'Unknown error';
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({ success: false, error: msg }, null, 2),
+                    }],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=variable-tools.js.map

package/dist/ws-bridge.d.ts

@@ -0,0 +1,22 @@
+export declare class FigmaBridge {
+    private wss;
+    private client;
+    private pendingRequests;
+    private requestCounter;
+    constructor();
+    /**
+     * Check if Figma plugin is connected
+     */
+    isConnected(): boolean;
+    /**
+     * Send a message to the Figma plugin and wait for a response.
+     * Returns the response data or throws on timeout/error.
+     */
+    send(type: string, payload?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * Shut down the WebSocket server
+     */
+    close(): void;
+    private handleMessage;
+    private nextRequestId;
+}

package/dist/ws-bridge.js

@@ -0,0 +1,110 @@
+/**
+ * WebSocket Bridge — manages connection to Figma Bridge Plugin.
+ * Provides request/response correlation via requestId.
+ */
+import { WebSocketServer, WebSocket } from 'ws';
+const WS_PORT = 3055;
+const REQUEST_TIMEOUT = 180_000; // 180 seconds (font/library loading can be very slow)
+export class FigmaBridge {
+    wss;
+    client = null;
+    pendingRequests = new Map();
+    requestCounter = 0;
+    constructor() {
+        this.wss = new WebSocketServer({ port: WS_PORT });
+        this.wss.on('connection', (ws) => {
+            console.error(`[Bridge] Figma plugin connected`);
+            this.client = ws;
+            ws.on('message', (data) => {
+                try {
+                    const msg = JSON.parse(data.toString());
+                    this.handleMessage(msg);
+                }
+                catch (e) {
+                    console.error('[Bridge] Failed to parse message:', e);
+                }
+            });
+            ws.on('close', () => {
+                console.error('[Bridge] Figma plugin disconnected');
+                if (this.client === ws) {
+                    this.client = null;
+                }
+                // Reject all pending requests
+                for (const [id, pending] of this.pendingRequests) {
+                    clearTimeout(pending.timer);
+                    pending.reject(new Error('Figma plugin disconnected'));
+                    this.pendingRequests.delete(id);
+                }
+            });
+            ws.on('error', (err) => {
+                console.error('[Bridge] WebSocket error:', err.message);
+            });
+        });
+        this.wss.on('error', (err) => {
+            console.error('[Bridge] WebSocket server error:', err.message);
+        });
+        console.error(`[Bridge] WebSocket server listening on port ${WS_PORT}`);
+    }
+    /**
+     * Check if Figma plugin is connected
+     */
+    isConnected() {
+        return this.client !== null && this.client.readyState === WebSocket.OPEN;
+    }
+    /**
+     * Send a message to the Figma plugin and wait for a response.
+     * Returns the response data or throws on timeout/error.
+     */
+    async send(type, payload = {}) {
+        if (!this.isConnected()) {
+            throw new Error('Figma Bridge plugin is not connected. Please open the "Code to Figma Bridge" plugin in Figma.');
+        }
+        const requestId = this.nextRequestId();
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingRequests.delete(requestId);
+                reject(new Error(`Request timed out after ${REQUEST_TIMEOUT / 1000}s (type: ${type})`));
+            }, REQUEST_TIMEOUT);
+            this.pendingRequests.set(requestId, { resolve, reject, timer });
+            const message = JSON.stringify({
+                requestId,
+                type,
+                params: payload,
+            });
+            this.client.send(message);
+        });
+    }
+    /**
+     * Shut down the WebSocket server
+     */
+    close() {
+        this.wss.close();
+    }
+    handleMessage(msg) {
+        // Handshake
+        if (msg.type === 'handshake') {
+            return;
+        }
+        // Bridge response — correlate with pending request
+        if (msg.type === 'bridge-response' && typeof msg.requestId === 'string') {
+            const pending = this.pendingRequests.get(msg.requestId);
+            if (pending) {
+                clearTimeout(pending.timer);
+                this.pendingRequests.delete(msg.requestId);
+                if (msg.success) {
+                    pending.resolve(msg.data || msg);
+                }
+                else {
+                    pending.reject(new Error(msg.error || 'Unknown error from Figma'));
+                }
+            }
+            return;
+        }
+        // Unknown message
+        console.error('[Bridge] Unhandled message type:', msg.type);
+    }
+    nextRequestId() {
+        return `req_${++this.requestCounter}_${Date.now()}`;
+    }
+}
+//# sourceMappingURL=ws-bridge.js.map

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@sangheepark/figma-ds-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for Code to Figma Bridge — bridges Claude Code to Figma plugin via WebSocket",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "figma-ds-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "!dist/bundle.js"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsc && node dist/index.js"
+  },
+  "keywords": [
+    "mcp",
+    "figma",
+    "model-context-protocol",
+    "code-to-figma"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/sagheepark/code-to-figma"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "ws": "^8.16.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/ws": "^8.5.10",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.3.0"
+  }
+}