figma-claude-connector 1.0.0

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ListToolsRequestSchema, CallToolRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { WSBridge } from './ws-bridge.js';
+import { registerAllTools } from './tools/index.js';
+import { existsSync, mkdirSync, copyFileSync } from 'fs';
+import { resolve, dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+// ── --setup: Copy Figma plugin files to local directory ──
+if (process.argv.includes('--setup')) {
+    const __dirname = dirname(fileURLToPath(import.meta.url));
+    const pluginSrc = resolve(__dirname, '..', 'figma-plugin');
+    const dest = resolve(process.cwd(), 'claude-connector-plugin');
+    if (!existsSync(pluginSrc)) {
+        console.error('Error: Plugin files not found in package.');
+        process.exit(1);
+    }
+    mkdirSync(dest, { recursive: true });
+    for (const file of ['manifest.json', 'ui.html', 'code.js']) {
+        const src = join(pluginSrc, file);
+        if (existsSync(src)) {
+            copyFileSync(src, join(dest, file));
+        }
+    }
+    // Update manifest main path (no dist/ prefix in flat structure)
+    const manifestPath = join(dest, 'manifest.json');
+    const manifestContent = await import('fs').then(fs => fs.readFileSync(manifestPath, 'utf-8').replace('"main": "dist/code.js"', '"main": "code.js"'));
+    await import('fs').then(fs => fs.writeFileSync(manifestPath, manifestContent));
+    console.log(`
+┌─────────────────────────────────────────────┐
+│         Claude Connector - Setup            │
+├─────────────────────────────────────────────┤
+│                                             │
+│  Plugin files copied to:                    │
+│  ${dest}
+│                                             │
+│  Next steps:                                │
+│                                             │
+│  1. Open Figma Desktop                      │
+│  2. Plugins → Development                   │
+│     → Import plugin from manifest...        │
+│  3. Select: ${dest}/manifest.json
+│                                             │
+│  4. Add to .mcp.json:                       │
+│  {                                          │
+│    "mcpServers": {                          │
+│      "figma": {                             │
+│        "command": "npx",                    │
+│        "args": ["figma-claude-connector"]  │
+│      }                                      │
+│    }                                        │
+│  }                                          │
+│                                             │
+│  5. Run plugin in Figma → Done!             │
+│                                             │
+└─────────────────────────────────────────────┘
+`);
+    process.exit(0);
+}
+const bridge = new WSBridge();
+const tools = registerAllTools(bridge);
+const server = new Server({ name: 'figma-mcp-bridge', version: '1.0.0' }, { capabilities: { tools: {} } });
+// List all available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: tools.map(({ name, description, inputSchema }) => ({
+        name,
+        description,
+        inputSchema,
+    })),
+}));
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const tool = tools.find((t) => t.name === name);
+    if (!tool) {
+        return {
+            content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+            isError: true,
+        };
+    }
+    if (!bridge.isConnected) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: 'Figma plugin not connected. Please open the Figma MCP Bridge plugin in Figma Desktop.',
+                }],
+            isError: true,
+        };
+    }
+    try {
+        const result = await tool.handler(args || {});
+        return {
+            content: [{
+                    type: 'text',
+                    text: JSON.stringify(result, null, 2),
+                }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Error: ${err.message}`,
+                }],
+            isError: true,
+        };
+    }
+});
+// Start server
+async function main() {
+    await bridge.start(3055);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error('[MCP] Figma MCP Bridge server started');
+}
+main().catch((err) => {
+    console.error('[MCP] Fatal error:', err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/tools/annotations.d.ts

@@ -0,0 +1,3 @@
+import { ToolDefinition } from '../types.js';
+import { WSBridge } from '../ws-bridge.js';
+export declare function createAnnotationTools(bridge: WSBridge): ToolDefinition[];

package/dist/tools/annotations.js

@@ -0,0 +1,55 @@
+export function createAnnotationTools(bridge) {
+    return [
+        {
+            name: 'figma_add_annotation',
+            description: 'Add a visual annotation (comment bubble) next to a node on the canvas. Supports color presets: amber (default), red (issue), blue (info), green (done), purple (question).',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    nodeId: { type: 'string', description: 'Target node ID to annotate' },
+                    text: { type: 'string', description: 'Comment text' },
+                    author: { type: 'string', description: 'Author name (default: "Claude MCP")' },
+                    color: {
+                        type: 'string',
+                        enum: ['#FBBF24', '#EF4444', '#3B82F6', '#10B981', '#8B5CF6'],
+                        description: 'Color: amber (#FBBF24, default), red (#EF4444, issue), blue (#3B82F6, info), green (#10B981, done), purple (#8B5CF6, question)',
+                    },
+                    position: {
+                        type: 'string',
+                        enum: ['right', 'left', 'top', 'bottom'],
+                        description: 'Position relative to target node (default: "right")',
+                    },
+                    maxWidth: { type: 'number', description: 'Max annotation width (default: 240)' },
+                    timestamp: { type: 'string', description: 'Custom timestamp string (default: auto-generated)' },
+                },
+                required: ['nodeId', 'text'],
+            },
+            handler: async (params) => bridge.sendAction('addAnnotation', params),
+        },
+        {
+            name: 'figma_get_annotations',
+            description: 'Get all annotations attached to a node.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    nodeId: { type: 'string', description: 'Target node ID' },
+                },
+                required: ['nodeId'],
+            },
+            handler: async (params) => bridge.sendAction('getAnnotations', params),
+        },
+        {
+            name: 'figma_delete_annotation',
+            description: 'Delete an annotation by its ID.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    annotationId: { type: 'string', description: 'Annotation node ID to delete' },
+                },
+                required: ['annotationId'],
+            },
+            handler: async (params) => bridge.sendAction('deleteAnnotation', params),
+        },
+    ];
+}
+//# sourceMappingURL=annotations.js.map

package/dist/tools/comments.d.ts

@@ -0,0 +1,3 @@
+import { ToolDefinition } from '../types.js';
+import { WSBridge } from '../ws-bridge.js';
+export declare function createCommentTools(bridge: WSBridge): ToolDefinition[];

package/dist/tools/comments.js

@@ -0,0 +1,187 @@
+/**
+ * Figma REST API를 통한 네이티브 댓글 기능
+ * 환경변수 FIGMA_TOKEN과 FIGMA_FILE_KEY 필요
+ */
+async function figmaApi(method, path, body) {
+    const token = process.env.FIGMA_TOKEN;
+    if (!token)
+        throw new Error('FIGMA_TOKEN 환경변수가 설정되지 않았습니다. Figma Personal Access Token을 설정하세요.');
+    const url = `https://api.figma.com/v1${path}`;
+    const res = await fetch(url, {
+        method,
+        headers: {
+            'X-Figma-Token': token,
+            'Content-Type': 'application/json',
+        },
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    if (!res.ok) {
+        const text = await res.text();
+        throw new Error(`Figma API ${res.status}: ${text}`);
+    }
+    return res.json();
+}
+let cachedFileKey = null;
+async function getFileKey(bridge) {
+    // 1. 환경변수 우선
+    if (process.env.FIGMA_FILE_KEY)
+        return process.env.FIGMA_FILE_KEY;
+    // 2. 캐시
+    if (cachedFileKey)
+        return cachedFileKey;
+    // 3. 플러그인에서 자동 추출
+    try {
+        const info = await bridge.sendAction('getFileInfo', {});
+        if (info.fileKey) {
+            cachedFileKey = info.fileKey;
+            return info.fileKey;
+        }
+    }
+    catch { }
+    throw new Error('File key를 가져올 수 없습니다. 플러그인이 연결되어 있는지 확인하세요.');
+}
+export function createCommentTools(bridge) {
+    return [
+        {
+            name: 'figma_post_comment',
+            description: 'Post a native Figma comment on the file. Shows in the Figma comment panel and sends notifications. Requires FIGMA_TOKEN and FIGMA_FILE_KEY env vars. Optionally pin to a specific node or canvas coordinates.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    message: { type: 'string', description: 'Comment text (supports @mentions with Figma user IDs)' },
+                    nodeId: { type: 'string', description: 'Pin comment to a specific node (optional)' },
+                    x: { type: 'number', description: 'Canvas X coordinate for pinned comment (optional, used with nodeId or standalone)' },
+                    y: { type: 'number', description: 'Canvas Y coordinate for pinned comment (optional)' },
+                },
+                required: ['message'],
+            },
+            handler: async (params) => {
+                const fileKey = await getFileKey(bridge);
+                const body = { message: params.message };
+                if (params.nodeId) {
+                    // 노드에 핀 달기 — 노드 위치 조회
+                    let x = params.x ?? 0;
+                    let y = params.y ?? 0;
+                    if (params.x === undefined && params.y === undefined) {
+                        // 플러그인에서 노드 위치 가져오기
+                        try {
+                            const nodeInfo = await bridge.sendAction('getNodeDetails', { nodeId: params.nodeId });
+                            x = (nodeInfo.x || 0) + (nodeInfo.width || 0) / 2;
+                            y = (nodeInfo.y || 0);
+                        }
+                        catch {
+                            // fallback: 0,0
+                        }
+                    }
+                    body.client_meta = {
+                        node_id: params.nodeId,
+                        node_offset: { x, y },
+                    };
+                }
+                else if (params.x !== undefined && params.y !== undefined) {
+                    body.client_meta = {
+                        x: params.x,
+                        y: params.y,
+                    };
+                }
+                const result = await figmaApi('POST', `/files/${fileKey}/comments`, body);
+                return {
+                    id: result.id,
+                    message: result.message,
+                    user: result.user?.handle,
+                    createdAt: result.created_at,
+                    nodeId: params.nodeId,
+                };
+            },
+        },
+        {
+            name: 'figma_get_comments',
+            description: 'Get all comments on the current Figma file. Requires FIGMA_TOKEN and FIGMA_FILE_KEY env vars.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    asMarkdown: { type: 'boolean', description: 'Format output as readable markdown (default: false)' },
+                },
+            },
+            handler: async (params) => {
+                const fileKey = await getFileKey(bridge);
+                const result = await figmaApi('GET', `/files/${fileKey}/comments`);
+                const comments = (result.comments || []).map((c) => ({
+                    id: c.id,
+                    message: c.message,
+                    user: c.user?.handle,
+                    createdAt: c.created_at,
+                    resolvedAt: c.resolved_at,
+                    nodeId: c.client_meta?.node_id,
+                    orderId: c.order_id,
+                    parentId: c.parent_id,
+                }));
+                if (params.asMarkdown) {
+                    // 스레드 구조로 그룹핑
+                    const roots = comments.filter((c) => !c.parentId);
+                    const replies = comments.filter((c) => c.parentId);
+                    let md = `# Comments (${comments.length})\n\n`;
+                    for (const root of roots) {
+                        const status = root.resolvedAt ? '✅' : '💬';
+                        md += `${status} **${root.user}** — ${root.createdAt}\n`;
+                        md += `> ${root.message}\n`;
+                        if (root.nodeId)
+                            md += `📌 Node: ${root.nodeId}\n`;
+                        const childReplies = replies.filter((r) => r.parentId === root.id);
+                        for (const reply of childReplies) {
+                            md += `  ↳ **${reply.user}**: ${reply.message}\n`;
+                        }
+                        md += '\n';
+                    }
+                    return { markdown: md, count: comments.length };
+                }
+                return { comments, count: comments.length };
+            },
+        },
+        {
+            name: 'figma_reply_comment',
+            description: 'Reply to an existing Figma comment thread. Requires FIGMA_TOKEN and FIGMA_FILE_KEY env vars.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    commentId: { type: 'string', description: 'Parent comment ID to reply to' },
+                    message: { type: 'string', description: 'Reply message' },
+                },
+                required: ['commentId', 'message'],
+            },
+            handler: async (params) => {
+                const fileKey = await getFileKey(bridge);
+                const result = await figmaApi('POST', `/files/${fileKey}/comments`, {
+                    message: params.message,
+                    comment_id: params.commentId,
+                });
+                return {
+                    id: result.id,
+                    message: result.message,
+                    user: result.user?.handle,
+                    parentId: params.commentId,
+                    createdAt: result.created_at,
+                };
+            },
+        },
+        {
+            name: 'figma_resolve_comment',
+            description: 'Resolve (close) a Figma comment. Requires FIGMA_TOKEN and FIGMA_FILE_KEY env vars.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    commentId: { type: 'string', description: 'Comment ID to resolve' },
+                },
+                required: ['commentId'],
+            },
+            handler: async (params) => {
+                const fileKey = await getFileKey(bridge);
+                // Figma REST API doesn't have a direct resolve endpoint — use DELETE to remove
+                // Actually, there's no resolve via REST API; we can delete the comment
+                await figmaApi('DELETE', `/files/${fileKey}/comments/${params.commentId}`);
+                return { deleted: params.commentId };
+            },
+        },
+    ];
+}
+//# sourceMappingURL=comments.js.map

package/dist/tools/components.d.ts

@@ -0,0 +1,3 @@
+import { ToolDefinition } from '../types.js';
+import { WSBridge } from '../ws-bridge.js';
+export declare function createComponentTools(bridge: WSBridge): ToolDefinition[];

package/dist/tools/components.js

@@ -0,0 +1,124 @@
+export function createComponentTools(bridge) {
+    return [
+        {
+            name: 'figma_create_button',
+            description: 'Create a button component with Auto Layout. Supports primary, secondary, and outline variants.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    label: { type: 'string', description: 'Button text (default: "Button")' },
+                    variant: { type: 'string', enum: ['primary', 'secondary', 'outline'], description: 'Button style variant (default: "primary")' },
+                    width: { type: 'number', description: 'Width (default: auto)' },
+                    height: { type: 'number', description: 'Height (default: 40)' },
+                    cornerRadius: { type: 'number', description: 'Corner radius (default: 8)' },
+                    x: { type: 'number', description: 'X position' },
+                    y: { type: 'number', description: 'Y position' },
+                    parentId: { type: 'string', description: 'Parent node ID' },
+                },
+            },
+            handler: async (params) => bridge.sendAction('createButton', params),
+        },
+        {
+            name: 'figma_create_card',
+            description: 'Create a card layout with optional header, content, and footer sections using Auto Layout.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: 'Card name' },
+                    header: { type: 'string', description: 'Header text' },
+                    content: { type: 'string', description: 'Content/body text' },
+                    footer: { type: 'string', description: 'Footer text' },
+                    width: { type: 'number', description: 'Width (default: 320)' },
+                    fill: { type: 'string', description: 'Background color (default: "#FFFFFF")' },
+                    cornerRadius: { type: 'number', description: 'Corner radius (default: 12)' },
+                    x: { type: 'number', description: 'X position' },
+                    y: { type: 'number', description: 'Y position' },
+                    parentId: { type: 'string', description: 'Parent node ID' },
+                },
+            },
+            handler: async (params) => bridge.sendAction('createCard', params),
+        },
+        {
+            name: 'figma_create_input',
+            description: 'Create an input field component with optional label.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: 'Input name' },
+                    placeholder: { type: 'string', description: 'Placeholder text (default: "Placeholder")' },
+                    label: { type: 'string', description: 'Label text above the input' },
+                    width: { type: 'number', description: 'Width (default: 240)' },
+                    height: { type: 'number', description: 'Height (default: 40)' },
+                    x: { type: 'number', description: 'X position' },
+                    y: { type: 'number', description: 'Y position' },
+                    parentId: { type: 'string', description: 'Parent node ID' },
+                },
+            },
+            handler: async (params) => bridge.sendAction('createInput', params),
+        },
+        {
+            name: 'figma_create_component',
+            description: 'Create a new Component node, or convert an existing frame to a Component. Components are reusable and support properties.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: 'Component name' },
+                    fromNodeId: { type: 'string', description: 'Convert existing frame to component (optional)' },
+                    width: { type: 'number', description: 'Width (when creating new)' },
+                    height: { type: 'number', description: 'Height (when creating new)' },
+                    fill: { type: 'string', description: 'Background color hex' },
+                    cornerRadius: { type: 'number', description: 'Corner radius' },
+                    x: { type: 'number', description: 'X position' },
+                    y: { type: 'number', description: 'Y position' },
+                    parentId: { type: 'string', description: 'Parent node ID' },
+                },
+            },
+            handler: async (params) => bridge.sendAction('createComponentFromFrame', params),
+        },
+        {
+            name: 'figma_add_component_property',
+            description: 'Add a property to a Component node. Supports TEXT, BOOLEAN, VARIANT, and INSTANCE_SWAP types.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    nodeId: { type: 'string', description: 'Component node ID' },
+                    propertyName: { type: 'string', description: 'Property name (e.g., "Label", "Disabled", "Style")' },
+                    propertyType: { type: 'string', enum: ['TEXT', 'BOOLEAN', 'VARIANT', 'INSTANCE_SWAP'], description: 'Property type' },
+                    defaultValue: { type: ['string', 'boolean'], description: 'Default value for the property' },
+                },
+                required: ['nodeId', 'propertyName', 'propertyType'],
+            },
+            handler: async (params) => bridge.sendAction('addComponentProperty', params),
+        },
+        {
+            name: 'figma_create_variants',
+            description: 'Combine multiple Component nodes into a single Variant Set (Component Set).',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    name: { type: 'string', description: 'Variant set name' },
+                    nodeIds: { type: 'array', items: { type: 'string' }, description: 'Array of Component node IDs to combine' },
+                },
+                required: ['nodeIds'],
+            },
+            handler: async (params) => bridge.sendAction('createComponentVariants', params),
+        },
+        {
+            name: 'figma_create_instance',
+            description: 'Create an instance of a Component. Optionally override component properties.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    componentId: { type: 'string', description: 'Source Component node ID' },
+                    properties: { type: 'object', description: 'Property overrides (key-value pairs)' },
+                    x: { type: 'number', description: 'X position' },
+                    y: { type: 'number', description: 'Y position' },
+                    parentId: { type: 'string', description: 'Parent node ID' },
+                },
+                required: ['componentId'],
+            },
+            handler: async (params) => bridge.sendAction('createInstance', params),
+        },
+    ];
+}
+//# sourceMappingURL=components.js.map

package/dist/tools/export.d.ts

@@ -0,0 +1,3 @@
+import { ToolDefinition } from '../types.js';
+import { WSBridge } from '../ws-bridge.js';
+export declare function createExportTools(bridge: WSBridge): ToolDefinition[];

package/dist/tools/export.js

@@ -0,0 +1,19 @@
+export function createExportTools(bridge) {
+    return [
+        {
+            name: 'figma_export_image',
+            description: 'Export a node as PNG, SVG, or PDF. Returns base64-encoded data.',
+            inputSchema: {
+                type: 'object',
+                properties: {
+                    nodeId: { type: 'string', description: 'Node ID to export' },
+                    format: { type: 'string', enum: ['PNG', 'SVG', 'PDF'], description: 'Export format (default: "PNG")' },
+                    scale: { type: 'number', description: 'Scale factor for PNG (default: 2)' },
+                },
+                required: ['nodeId'],
+            },
+            handler: async (params) => bridge.sendAction('exportNode', params),
+        },
+    ];
+}
+//# sourceMappingURL=export.js.map

package/dist/tools/index.d.ts

@@ -0,0 +1,3 @@
+import { ToolDefinition } from '../types.js';
+import { WSBridge } from '../ws-bridge.js';
+export declare function registerAllTools(bridge: WSBridge): ToolDefinition[];

package/dist/tools/index.js

@@ -0,0 +1,25 @@
+import { createNodeTools } from './nodes.js';
+import { createComponentTools } from './components.js';
+import { createLayoutTools } from './layout.js';
+import { createStyleTools } from './styles.js';
+import { createTextTools } from './text.js';
+import { createQueryTools } from './query.js';
+import { createExportTools } from './export.js';
+import { createMetadataTools } from './metadata.js';
+import { createAnnotationTools } from './annotations.js';
+import { createCommentTools } from './comments.js';
+export function registerAllTools(bridge) {
+    return [
+        ...createNodeTools(bridge),
+        ...createComponentTools(bridge),
+        ...createLayoutTools(bridge),
+        ...createStyleTools(bridge),
+        ...createTextTools(bridge),
+        ...createQueryTools(bridge),
+        ...createExportTools(bridge),
+        ...createMetadataTools(bridge),
+        ...createAnnotationTools(bridge),
+        ...createCommentTools(bridge),
+    ];
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/layout.d.ts

@@ -0,0 +1,3 @@
+import { ToolDefinition } from '../types.js';
+import { WSBridge } from '../ws-bridge.js';
+export declare function createLayoutTools(bridge: WSBridge): ToolDefinition[];