figma-console-mcp 1.7.0 → 1.9.0

package/README.md

@@ -42,9 +42,9 @@ Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
 | **Edit existing designs** | ✅ | ❌ |
 | **Manage design tokens/variables** | ✅ | ❌ |
 | Desktop Bridge plugin | ✅ | ❌ |
-| **Total tools available** | **72+** | **16** |
+| **Total tools available** | **56+** | **16** |
 
-> **Bottom line:** Remote SSE is **read-only**. If you want AI to actually design in Figma, use NPX Setup.
+> **Bottom line:** Remote SSE is **read-only** with ~34% of the tools. If you want AI to actually design in Figma, use NPX Setup.
 
 ---
 
@@ -52,13 +52,13 @@ Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
 
 **Best for:** Designers who want full AI-assisted design capabilities.
 
-**What you get:** All 72+ tools including design creation, variable management, and component instantiation.
+**What you get:** All 56+ tools including design creation, variable management, and component instantiation.
 
 #### Prerequisites
 
 - [ ] **Node.js 18+** — Check with `node --version` ([Download](https://nodejs.org))
 - [ ] **Figma Desktop** installed (not just the web app)
-- [ ] **Claude Desktop** or another MCP client
+- [ ] **An MCP client** (Claude Code, Cursor, Windsurf, Claude Desktop, etc.)
 
 #### Step 1: Get Your Figma Token
 
@@ -67,9 +67,16 @@ Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
 3. Enter description: `Figma Console MCP`
 4. **Copy the token** — you won't see it again! (starts with `figd_`)
 
-#### Step 2: Configure Claude Desktop
+#### Step 2: Configure Your MCP Client
 
-Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+**Claude Code (CLI):**
+```bash
+claude mcp add figma-console -s user -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN_HERE -- npx -y figma-console-mcp@latest
+```
+
+**Cursor / Windsurf / Claude Desktop:**
+
+Add to your MCP config file:
 
 ```json
 {
@@ -85,32 +92,34 @@ Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) o
 }
 ```
 
-#### Step 3: Start Figma with Debug Mode
+#### Step 3: Connect to Figma Desktop
 
-**Quit Figma completely**, then restart with debug flag:
+**Option A — Desktop Bridge Plugin (Recommended):**
+1. Open Figma Desktop normally (no special flags needed)
+2. Go to **Plugins → Development → Import plugin from manifest...**
+3. Select `figma-desktop-bridge/manifest.json` from the figma-console-mcp directory
+4. Run the plugin in your Figma file — it auto-connects via WebSocket
 
-**macOS:**
-```bash
-open -a "Figma" --args --remote-debugging-port=9222
-```
+> One-time setup. No need to restart Figma with special flags.
 
-**Windows:**
-```
-cmd /c "%LOCALAPPDATA%\Figma\Figma.exe" --remote-debugging-port=9222
-```
+**Option B — CDP Debug Mode (Alternative):**
+
+Quit Figma completely, then restart with:
+- **macOS:** `open -a "Figma" --args --remote-debugging-port=9222`
+- **Windows:** `cmd /c "%LOCALAPPDATA%\Figma\Figma.exe" --remote-debugging-port=9222`
 
 Verify at [http://localhost:9222](http://localhost:9222) — you should see inspectable Figma pages.
 
-#### Step 4: Restart Claude Desktop
+#### Step 4: Restart Your MCP Client
 
-Quit and reopen Claude Desktop. Look for 🔌 icon showing "figma-console: connected".
+Restart your MCP client to load the new configuration.
 
 #### Step 5: Test It!
 
 ```
 Check Figma status
 ```
-→ Should show "✅ Figma Desktop connected"
+→ Should show connection status with active transport (WebSocket or CDP)
 
 ```
 Create a simple frame with a blue background
@@ -125,7 +134,7 @@ Create a simple frame with a blue background
 
 **Best for:** Developers who want to modify source code or contribute to the project.
 
-**What you get:** Same 72+ tools as NPX, plus full source code access.
+**What you get:** Same 56+ tools as NPX, plus full source code access.
 
 #### Quick Setup
 
@@ -137,7 +146,7 @@ npm install
 npm run build:local
 ```
 
-#### Configure Claude Desktop
+#### Configure Your MCP Client
 
 ```json
 {
@@ -153,7 +162,7 @@ npm run build:local
 }
 ```
 
-Then follow [NPX Steps 3-5](#step-3-start-figma-with-debug-mode) above.
+Then follow [NPX Steps 3-5](#step-3-connect-to-figma-desktop) above.
 
 **📖 [Complete Setup Guide](docs/setup.md)**
 
@@ -163,7 +172,7 @@ Then follow [NPX Steps 3-5](#step-3-start-figma-with-debug-mode) above.
 
 **Best for:** Quickly evaluating the tool or read-only design data extraction.
 
-**What you get:** 16 read-only tools — view data, take screenshots, read logs. **Cannot create or modify designs.**
+**What you get:** 21 read-only tools — view data, take screenshots, read logs, design-code parity. **Cannot create or modify designs.**
 
 #### Claude Desktop (UI Method)
 
@@ -212,7 +221,7 @@ Ready for design creation? Follow the [NPX Setup](#-npx-setup-recommended) guide
 | Feature | NPX (Recommended) | Local Git | Remote SSE |
 |---------|-------------------|-----------|------------|
 | **Setup time** | ~10 minutes | ~15 minutes | ~2 minutes |
-| **Total tools** | **72+** | **72+** | **16** (read-only) |
+| **Total tools** | **56+** | **56+** | **21** (read-only) |
 | **Design creation** | ✅ | ✅ | ❌ |
 | **Variable management** | ✅ | ✅ | ❌ |
 | **Component instantiation** | ✅ | ✅ | ❌ |
@@ -224,7 +233,7 @@ Ready for design creation? Follow the [NPX Setup](#-npx-setup-recommended) guide
 | **Automatic updates** | ✅ (`@latest`) | Manual (`git pull`) | ✅ |
 | **Source code access** | ❌ | ✅ | ❌ |
 
-> **Key insight:** Remote SSE is read-only with ~22% of the tools. Use NPX for full capabilities.
+> **Key insight:** Remote SSE is read-only with ~34% of the tools. Use NPX for full capabilities.
 
 **📖 [Complete Feature Comparison](docs/mode-comparison.md)**
 
@@ -385,7 +394,7 @@ Navigate to this file and capture what's on screen
 
 ## 🎨 AI-Assisted Design Creation
 
-> **⚠️ Local Mode Only:** This feature requires the Desktop Bridge plugin and only works with [Local Mode installation](#for-plugin-developers-local-mode). Remote Mode is read-only and cannot create or modify designs.
+> **⚠️ Local Mode Only:** This feature requires the Desktop Bridge plugin and only works with Local Mode installation (NPX or Local Git). Remote Mode is read-only and cannot create or modify designs.
 
 One of the most powerful capabilities of this MCP server is the ability to **design complete UI components and pages directly in Figma through natural language conversation** with any MCP-compatible AI assistant like Claude Desktop or Claude Code.
 
@@ -458,31 +467,51 @@ This ensures designs aren't just technically correct—they *look* right.
 
 ---
 
-## 🎨 Desktop Bridge Plugin (Local Mode Only)
+## 🎨 Desktop Bridge Plugin (Recommended Connection)
 
-The **Figma Desktop Bridge** plugin enables powerful capabilities:
+The **Figma Desktop Bridge** plugin is the recommended way to connect Figma to the MCP server. It communicates via WebSocket — no special Figma launch flags needed, and it persists across Figma restarts.
 
-### Read Operations
-- ✅ Variables without Enterprise API
-- ✅ Reliable component descriptions (bypasses API bugs)
-- ✅ Multi-mode support (Light/Dark/Brand variants)
+### Setup
 
-### Write Operations
-- ✅ **Design Creation** - Create frames, shapes, text, components via `figma_execute`
-- ✅ **Variable Management** - Full CRUD operations on variables and collections
-- ✅ **Mode Management** - Add and rename modes for multi-theme support
+1. Open Figma Desktop (normal launch — no debug flags needed)
+2. Go to **Plugins → Development → Import plugin from manifest...**
+3. Select `figma-desktop-bridge/manifest.json` from the figma-console-mcp directory
+4. Run the plugin in your Figma file — it auto-connects to `ws://localhost:9223`
+5. Ask your AI: "Check Figma status" to verify the connection
 
-**⚠️ Plugin Limitation:** Only works in Local Mode. Remote mode cannot access it.
-
-**Setup:**
-1. Install Local Mode MCP
-2. Download plugin from [Releases](https://github.com/southleft/figma-console-mcp/releases/latest)
-3. Import plugin: Figma Desktop → Plugins → Development → Import plugin from manifest
-4. Run plugin in your Figma file
-5. Ask Claude: "Create a button component" or "Show me the design variables"
+> **One-time import.** Once imported, the plugin stays in your Development plugins list. Just run it whenever you want to use the MCP.
 
 **📖 [Desktop Bridge Documentation](figma-desktop-bridge/README.md)**
 
+### Capabilities
+
+**Read Operations:**
+- Variables without Enterprise API
+- Reliable component descriptions (bypasses API bugs)
+- Multi-mode support (Light/Dark/Brand variants)
+- Real-time selection tracking and document change monitoring
+
+**Write Operations:**
+- **Design Creation** - Create frames, shapes, text, components via `figma_execute`
+- **Variable Management** - Full CRUD operations on variables and collections
+- **Mode Management** - Add and rename modes for multi-theme support
+
+### How the Transport Works
+
+- The MCP server tries **WebSocket first** (port 9223, instant check) via the Desktop Bridge plugin
+- If no WebSocket client is connected, it falls back to **CDP** (port 9222) if available
+- The transport is selected automatically per-command — no configuration needed
+- All 56+ tools work identically through either transport
+
+**CDP as fallback:** If you also launch Figma with `--remote-debugging-port=9222`, CDP serves as a fallback transport. CDP captures all page-level console logs while WebSocket captures plugin-context logs. `figma_navigate` requires CDP for browser-level navigation; in WebSocket mode it returns the connected file info with guidance instead.
+
+**Multiple files:** The WebSocket server supports multiple simultaneous plugin connections — one per open Figma file. Each connection is tracked by file key with independent state (selection, document changes, console logs).
+
+**Environment variables:**
+- `FIGMA_WS_PORT` — Override the server-side WebSocket port (default: 9223). Note: the plugin UI and manifest are hard-coded to port 9223. Using a custom port also requires updating `wsPort` in `ui.html` and `allowedDomains` in `manifest.json`.
+
+**Plugin Limitation:** Only works in Local Mode (NPX or Local Git). Remote SSE mode cannot access it.
+
 ---
 
 ## 🧩 MCP Apps (Experimental)
@@ -581,18 +610,18 @@ The architecture supports adding new apps with minimal boilerplate — each app
 
 ## 🛤️ Roadmap
 
-**Current Status:** v1.2.x (Stable) - Production-ready with comprehensive capabilities
+**Current Status:** v1.9.0 (Stable) - Production-ready with WebSocket Bridge, 56+ tools, Comments API, and MCP Apps
 
-**Coming Soon:**
-- [ ] **Enhanced error messages** - Actionable suggestions for design operations
+**Recent Releases:**
+- [x] **v1.8.0** - WebSocket Bridge transport (CDP-free connectivity), real-time selection/document tracking, `figma_get_selection` + `figma_get_design_changes` tools
+- [x] **v1.7.0** - MCP Apps (Token Browser, Design System Dashboard), batch variable operations, design-code parity tools
+- [x] **v1.5.0** - Node manipulation tools, component property management, component set arrangement
+- [x] **v1.3.0** - Design creation via `figma_execute`, variable CRUD operations
+
+**Coming Next:**
 - [ ] **Component template library** - Common UI pattern generation
-- [ ] **Batch variant operations** - Create multiple variants efficiently
 - [ ] **Visual regression testing** - Screenshot diff capabilities
-
-**Future:**
-- [ ] **Multi-user debugging** - Collaborative debugging sessions
 - [ ] **Design linting** - Automated compliance and accessibility checks
-- [ ] **VS Code extension** - Simplified setup and integration
 - [ ] **AI enhancements** - Intelligent component suggestions and auto-layout optimization
 
 **📖 [Full Roadmap](docs/ROADMAP.md)**

package/dist/cloudflare/core/comment-tools.js

@@ -0,0 +1,292 @@
+/**
+ * Figma Comments MCP Tools
+ * Tools for getting, posting, and deleting comments on Figma files via REST API.
+ * Works in both local and Cloudflare Workers modes — no Plugin API dependency.
+ */
+import { z } from "zod";
+import { extractFileKey } from "./figma-api.js";
+import { createChildLogger } from "./logger.js";
+const logger = createChildLogger({ component: "comment-tools" });
+// ============================================================================
+// Tool Registration
+// ============================================================================
+export function registerCommentTools(server, getFigmaAPI, getCurrentUrl, options) {
+    // -----------------------------------------------------------------------
+    // Tool: figma_get_comments
+    // -----------------------------------------------------------------------
+    server.tool("figma_get_comments", "Get comments on a Figma file. Returns comment threads with author, message, timestamps, and pinned node locations. Use include_resolved to also see resolved comments.", {
+        fileUrl: z
+            .string()
+            .url()
+            .optional()
+            .describe("Figma file URL. Uses current URL if omitted."),
+        as_md: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Return comment message bodies as markdown. Default: false"),
+        include_resolved: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Include resolved (completed) comment threads. Default: false (only active comments)"),
+    }, async ({ fileUrl, as_md = false, include_resolved = false }) => {
+        try {
+            const url = fileUrl || getCurrentUrl();
+            if (!url) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "no_file_url",
+                                message: "No Figma file URL available. Pass the fileUrl parameter, call figma_navigate (CDP mode), or ensure the Desktop Bridge plugin is connected (WebSocket mode).",
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const fileKey = extractFileKey(url);
+            if (!fileKey) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "invalid_url",
+                                message: `Invalid Figma URL: ${url}`,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            logger.info({ fileKey, as_md, include_resolved }, "Fetching comments");
+            const api = await getFigmaAPI();
+            const response = await api.getComments(fileKey, { as_md });
+            const allComments = response.comments || [];
+            // Filter out resolved comments unless explicitly requested
+            const comments = include_resolved
+                ? allComments
+                : allComments.filter((c) => !c.resolved_at);
+            const result = {
+                comments,
+                summary: {
+                    total: allComments.length,
+                    active: allComments.filter((c) => !c.resolved_at).length,
+                    resolved: allComments.filter((c) => c.resolved_at).length,
+                    returned: comments.length,
+                },
+            };
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error({ error }, "Failed to get comments");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "get_comments_failed",
+                            message: `Cannot get comments. ${message}`,
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // -----------------------------------------------------------------------
+    // Tool: figma_post_comment
+    // -----------------------------------------------------------------------
+    server.tool("figma_post_comment", "Post a comment on a Figma file, optionally pinned to a specific design node. Use after figma_check_design_parity to notify designers of drift when code is the canonical source. Supports replies to existing comment threads.", {
+        fileUrl: z
+            .string()
+            .url()
+            .optional()
+            .describe("Figma file URL. Uses current URL if omitted."),
+        message: z
+            .string()
+            .describe("The comment message text. Supports basic formatting."),
+        node_id: z
+            .string()
+            .optional()
+            .describe("Node ID to pin the comment to (e.g., '695:313'). Comment appears on that element in Figma."),
+        x: z
+            .number()
+            .optional()
+            .describe("X coordinate for comment placement (absolute canvas position). Used with node_id."),
+        y: z
+            .number()
+            .optional()
+            .describe("Y coordinate for comment placement (absolute canvas position). Used with node_id."),
+        reply_to_comment_id: z
+            .string()
+            .optional()
+            .describe("ID of an existing comment to reply to. Creates a threaded reply instead of a new top-level comment."),
+    }, async ({ fileUrl, message, node_id, x, y, reply_to_comment_id }) => {
+        try {
+            const url = fileUrl || getCurrentUrl();
+            if (!url) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "no_file_url",
+                                message: "No Figma file URL available. Pass the fileUrl parameter, call figma_navigate (CDP mode), or ensure the Desktop Bridge plugin is connected (WebSocket mode).",
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const fileKey = extractFileKey(url);
+            if (!fileKey) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "invalid_url",
+                                message: `Invalid Figma URL: ${url}`,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            logger.info({ fileKey, node_id, reply_to_comment_id }, "Posting comment");
+            const api = await getFigmaAPI();
+            // Build client_meta for pinning to a node/position
+            // Figma API requires node_offset when node_id is present — default to (0,0) if not specified
+            let clientMeta;
+            if (node_id) {
+                clientMeta = {
+                    node_id,
+                    node_offset: { x: x ?? 0, y: y ?? 0 },
+                };
+            }
+            const result = await api.postComment(fileKey, message, clientMeta, reply_to_comment_id);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            comment: {
+                                id: result.id,
+                                message: result.message,
+                                created_at: result.created_at,
+                                user: result.user,
+                                client_meta: result.client_meta,
+                                order_id: result.order_id,
+                            },
+                        }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message_text = error instanceof Error ? error.message : String(error);
+            logger.error({ error }, "Failed to post comment");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "post_comment_failed",
+                            message: `Cannot post comment. ${message_text}`,
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // -----------------------------------------------------------------------
+    // Tool: figma_delete_comment
+    // -----------------------------------------------------------------------
+    server.tool("figma_delete_comment", "Delete a comment from a Figma file by its comment ID. Use figma_get_comments to find comment IDs first.", {
+        fileUrl: z
+            .string()
+            .url()
+            .optional()
+            .describe("Figma file URL. Uses current URL if omitted."),
+        comment_id: z
+            .string()
+            .describe("The ID of the comment to delete. Get IDs from figma_get_comments."),
+    }, async ({ fileUrl, comment_id }) => {
+        try {
+            const url = fileUrl || getCurrentUrl();
+            if (!url) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "no_file_url",
+                                message: "No Figma file URL available. Pass the fileUrl parameter, call figma_navigate (CDP mode), or ensure the Desktop Bridge plugin is connected (WebSocket mode).",
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const fileKey = extractFileKey(url);
+            if (!fileKey) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "invalid_url",
+                                message: `Invalid Figma URL: ${url}`,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            logger.info({ fileKey, comment_id }, "Deleting comment");
+            const api = await getFigmaAPI();
+            await api.deleteComment(fileKey, comment_id);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            deleted_comment_id: comment_id,
+                        }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error({ error }, "Failed to delete comment");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "delete_comment_failed",
+                            message: `Cannot delete comment. ${message}`,
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/cloudflare/core/design-code-tools.js

@@ -1287,7 +1287,7 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
         try {
             const url = fileUrl || getCurrentUrl();
             if (!url) {
-                throw new Error("No Figma file URL provided. Either pass fileUrl parameter or call figma_navigate first.");
+                throw new Error("No Figma file URL available. Pass the fileUrl parameter, call figma_navigate (CDP mode), or ensure the Desktop Bridge plugin is connected (WebSocket mode).");
             }
             const fileKey = extractFileKey(url);
             if (!fileKey) {
@@ -1474,7 +1474,7 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
         try {
             const url = fileUrl || getCurrentUrl();
             if (!url) {
-                throw new Error("No Figma file URL provided. Either pass fileUrl parameter or call figma_navigate first.");
+                throw new Error("No Figma file URL available. Pass the fileUrl parameter, call figma_navigate (CDP mode), or ensure the Desktop Bridge plugin is connected (WebSocket mode).");
             }
             const fileKey = extractFileKey(url);
             if (!fileKey) {

package/dist/cloudflare/core/figma-api.js

@@ -280,6 +280,40 @@ export class FigmaAPI {
         logger.info({ fileKey, ids, options }, 'Rendering images');
         return this.request(endpoint);
     }
+    /**
+     * GET /v1/files/:file_key/comments
+     * Get comments on a file
+     */
+    async getComments(fileKey, options) {
+        const params = new URLSearchParams();
+        if (options?.as_md)
+            params.set('as_md', 'true');
+        const query = params.toString() ? `?${params.toString()}` : '';
+        return this.request(`/files/${fileKey}/comments${query}`);
+    }
+    /**
+     * POST /v1/files/:file_key/comments
+     * Post a comment on a file
+     */
+    async postComment(fileKey, message, clientMeta, commentId) {
+        return this.request(`/files/${fileKey}/comments`, {
+            method: 'POST',
+            body: JSON.stringify({
+                message,
+                ...(clientMeta && { client_meta: clientMeta }),
+                ...(commentId && { comment_id: commentId }),
+            }),
+        });
+    }
+    /**
+     * DELETE /v1/files/:file_key/comments/:comment_id
+     * Delete a comment on a file
+     */
+    async deleteComment(fileKey, commentId) {
+        return this.request(`/files/${fileKey}/comments/${commentId}`, {
+            method: 'DELETE',
+        });
+    }
     /**
      * Helper: Get all design tokens (variables) with formatted output
      * Both local and published can fail gracefully (e.g., 403 without Enterprise plan)

package/dist/cloudflare/core/figma-connector.js

@@ -0,0 +1,8 @@
+/**
+ * Figma Connector Interface
+ *
+ * Transport abstraction that both CDP (FigmaDesktopConnector) and WebSocket
+ * (WebSocketConnector) implement. Allows getDesktopConnector() to return
+ * whichever transport is available — WebSocket preferred, CDP fallback.
+ */
+export {};