@mp3wizard/figma-console-mcp 1.15.4 → 1.19.0

package/README.md

@@ -1,14 +1,17 @@
 # Figma Console MCP Server
 
 [![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io/)
-[![npm](https://img.shields.io/npm/v/figma-console-mcp)](https://www.npmjs.com/package/figma-console-mcp)
+[![npm](https://img.shields.io/npm/v/@mp3wizard/figma-console-mcp)](https://www.npmjs.com/package/@mp3wizard/figma-console-mcp)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Security Reviewed](https://img.shields.io/badge/Security-Reviewed-brightgreen)](Security%20review%20report/)
 [![Documentation](https://img.shields.io/badge/docs-docs.figma--console--mcp.southleft.com-0D9488)](https://docs.figma-console-mcp.southleft.com)
 [![Sponsor](https://img.shields.io/badge/Sponsor-southleft-ea4aaa?logo=github-sponsors&logoColor=white)](https://github.com/sponsors/southleft)
 
 > **Your design system as an API.** Model Context Protocol server that bridges design and development—giving AI assistants complete access to Figma for **extraction**, **creation**, and **debugging**.
 
-> **🆕 Import Once, Update Never — Plugin Bootloader Architecture:** The Desktop Bridge plugin now dynamically loads its UI from the MCP server on every launch. Import the manifest once from `~/.figma-console-mcp/plugin/manifest.json` and you're done forever — server updates, new tools, and bug fixes are delivered automatically. Plus: orphaned process cleanup, cross-file library components, and built-in housekeeping. [See changelog →](CHANGELOG.md)
+> **🔒 Security Reviewed Fork:** This fork (`@mp3wizard/figma-console-mcp`) has passed a full security review following OWASP Top 10 and CWE standards, including automated scanning (Semgrep, Trivy, TruffleHog) and manual vulnerability analysis. Review reports are available in the [`Security review report/`](Security%20review%20report/) folder.
+
+> **🆕 High-Fidelity Design-to-Code:** Deep component trees (depth 4), resolved design tokens, interaction state machines with CSS mappings, and codebase-aware component scanning. AI gets everything a senior engineer needs — tokens, sizing, states, annotations, and a cross-reference of what already exists in your codebase. [See what's new →](docs/figma-mcp-vs-figma-console-mcp.md)
 
 ## What is this?
 
@@ -20,6 +23,7 @@ Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
 - **✏️ Design creation** - Create UI components, frames, and layouts directly in Figma
 - **🔧 Variable management** - Create, update, rename, and delete design tokens
 - **⚡ Real-time monitoring** - Watch logs as plugins execute
+- **📌 FigJam boards** - Create stickies, flowcharts, tables, and code blocks on collaborative boards
 - **☁️ Cloud Write Relay** - Web AI clients (Claude.ai, v0, Replit) can design in Figma via cloud pairing
 - **🔄 Four ways to connect** - Remote SSE, Cloud Mode, NPX, or Local Git
 
@@ -46,12 +50,13 @@ Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
 | **Create components & frames** | ✅ | ✅ | ❌ |
 | **Edit existing designs** | ✅ | ✅ | ❌ |
 | **Manage design tokens/variables** | ✅ | ✅ | ❌ |
+| **FigJam boards (stickies, flowcharts)** | ✅ | ✅ | ❌ |
 | Real-time monitoring (console, selection) | ✅ | ❌ | ❌ |
 | Desktop Bridge plugin | ✅ | ✅ | ❌ |
 | Requires Node.js | Yes | **No** | No |
-| **Total tools available** | **63+** | **43** | **22** |
+| **Total tools available** | **89+** | **43** | **22** |
 
-> **Bottom line:** Remote SSE is **read-only** with ~38% of the tools. **Cloud Mode** unlocks write access from web AI clients without Node.js. NPX/Local Git gives the full 63+ tools with real-time monitoring.
+> **Bottom line:** Remote SSE is **read-only** with ~38% of the tools. **Cloud Mode** unlocks write access from web AI clients without Node.js. NPX/Local Git gives the full 89+ tools with real-time monitoring.
 
 ---
 
@@ -59,7 +64,7 @@ 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 63+ tools including design creation, variable management, and component instantiation.
+**What you get:** All 89+ tools including design creation, variable management, and component instantiation.
 
 #### Prerequisites
 
@@ -72,13 +77,14 @@ Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
 1. Go to [Manage personal access tokens](https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens) in Figma Help
 2. Follow the steps to **create a new personal access token**
 3. Enter description: `Figma Console MCP`
-4. **Copy the token** — you won't see it again! (starts with `figd_`)
+4. Set scopes: **File content** (Read), **Variables** (Read), **Comments** (Read and write)
+5. **Copy the token** — you won't see it again! (starts with `figd_`)
 
 #### Step 2: Configure Your MCP Client
 
 **Claude Code (CLI):**
 ```bash
-claude mcp add figma-console -s user -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN_HERE -e ENABLE_MCP_APPS=true -- npx -y figma-console-mcp@latest
+claude mcp add figma-console -s user -e FIGMA_ACCESS_TOKEN=figd_YOUR_TOKEN_HERE -e ENABLE_MCP_APPS=true -- npx -y @mp3wizard/figma-console-mcp@latest
 ```
 
 **Cursor / Windsurf / Claude Desktop:**
@@ -90,7 +96,7 @@ Add to your MCP config file (see [Where to find your config file](#-where-to-fin
   "mcpServers": {
     "figma-console": {
       "command": "npx",
-      "args": ["-y", "figma-console-mcp@latest"],
+      "args": ["-y", "@mp3wizard/figma-console-mcp@latest"],
       "env": {
         "FIGMA_ACCESS_TOKEN": "figd_YOUR_TOKEN_HERE",
         "ENABLE_MCP_APPS": "true"
@@ -127,7 +133,7 @@ If you're not sure where to put the JSON configuration above, here's where each
 
 > One-time setup. The plugin uses a bootloader that dynamically loads fresh code from the MCP server — no need to re-import when the server updates.
 
-> **Upgrading from v1.14 or earlier?** Your existing plugin still works, but to get the bootloader benefits (no more re-importing), do one final re-import from `~/.figma-console-mcp/plugin/manifest.json`. The path is created automatically when the MCP server starts. Run `npx figma-console-mcp@latest --print-path` to see it. After this one-time upgrade, you're done forever.
+> **Upgrading from v1.14 or earlier?** Your existing plugin still works, but to get the bootloader benefits (no more re-importing), do one final re-import from `~/.figma-console-mcp/plugin/manifest.json`. The path is created automatically when the MCP server starts. Run `npx @mp3wizard/figma-console-mcp@latest --print-path` to see it. After this one-time upgrade, you're done forever.
 
 #### Step 4: Restart Your MCP Client
 
@@ -153,7 +159,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 63+ tools as NPX, plus full source code access.
+**What you get:** Same 89+ tools as NPX, plus full source code access.
 
 #### Quick Setup
 
@@ -242,7 +248,7 @@ Ready for design creation? Follow the [NPX Setup](#-npx-setup-recommended) guide
 
 **Best for:** Using Claude.ai, v0, Replit, or Lovable to create and modify Figma designs — no Node.js required.
 
-**What you get:** 52 tools including full write access — design creation, variable management, component instantiation, and all REST API tools. Only real-time monitoring (console logs, selection tracking, document changes) requires Local Mode.
+**What you get:** 79 tools including full write access — design creation, variable management, component instantiation, and all REST API tools. Only real-time monitoring (console logs, selection tracking, document changes) requires Local Mode.
 
 #### Prerequisites
 
@@ -299,10 +305,11 @@ AI Client → Cloud MCP Server → Durable Object Relay → Desktop Bridge Plugi
 | Feature | NPX (Recommended) | Cloud Mode | Local Git | Remote SSE |
 |---------|-------------------|------------|-----------|------------|
 | **Setup time** | ~10 minutes | ~5 minutes | ~15 minutes | ~2 minutes |
-| **Total tools** | **63+** | **43** | **63+** | **22** (read-only) |
+| **Total tools** | **89+** | **43** | **89+** | **22** (read-only) |
 | **Design creation** | ✅ | ✅ | ✅ | ❌ |
 | **Variable management** | ✅ | ✅ | ✅ | ❌ |
 | **Component instantiation** | ✅ | ✅ | ✅ | ❌ |
+| **FigJam boards** | ✅ | ✅ | ✅ | ❌ |
 | **Real-time monitoring** | ✅ | ❌ | ✅ | ❌ |
 | **Desktop Bridge plugin** | ✅ | ✅ | ✅ | ❌ |
 | **Variables (no Enterprise)** | ✅ | ✅ | ✅ | ❌ |
@@ -313,7 +320,7 @@ AI Client → Cloud MCP Server → Durable Object Relay → Desktop Bridge Plugi
 | **Automatic updates** | ✅ (`@latest`) | ✅ | Manual (`git pull`) | ✅ |
 | **Source code access** | ❌ | ❌ | ✅ | ❌ |
 
-> **Key insight:** Remote SSE is read-only. Cloud Mode adds write access for web AI clients without Node.js. NPX/Local Git give the full 63+ tools.
+> **Key insight:** Remote SSE is read-only. Cloud Mode adds write access for web AI clients without Node.js. NPX/Local Git give the full 89+ tools.
 
 **📖 [Complete Feature Comparison](docs/mode-comparison.md)**
 
@@ -359,7 +366,7 @@ When you first use design system tools:
 ### Local Mode - Personal Access Token (Manual)
 
 1. Visit https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens
-2. Generate token
+2. Generate token with scopes: **File content** (Read), **Variables** (Read), **Comments** (Read and write)
 3. Add to MCP config as `FIGMA_ACCESS_TOKEN` environment variable
 
 ---
@@ -426,6 +433,34 @@ When you first use design system tools:
 - `figma_batch_update_variables` - Update up to 100 variable values in one call
 - `figma_setup_design_tokens` - Create complete token system (collection + modes + variables) atomically
 
+### 📌 FigJam Board Tools (Local Mode + Cloud Mode)
+- `figjam_create_sticky` - Create a sticky note with color options
+- `figjam_create_stickies` - Batch create up to 200 stickies
+- `figjam_create_connector` - Connect nodes with labeled connector lines
+- `figjam_create_shape_with_text` - Create flowchart shapes (diamond, ellipse, etc.)
+- `figjam_create_table` - Create tables with cell data
+- `figjam_create_code_block` - Add code snippets with syntax highlighting
+- `figjam_auto_arrange` - Arrange nodes in grid, horizontal, or vertical layouts
+- `figjam_get_board_contents` - Read all content from a FigJam board
+- `figjam_get_connections` - Read the connection graph (flowcharts, relationships)
+
+### 🎞️ Slides Presentation Tools (Local Mode + Cloud Mode)
+- `figma_list_slides` - List all slides with IDs, positions, and skip status
+- `figma_get_slide_content` - Get the full content tree of a slide
+- `figma_get_slide_grid` - Get the 2D grid layout of the presentation
+- `figma_get_slide_transition` - Read transition settings for a slide
+- `figma_get_focused_slide` - Get the currently focused slide
+- `figma_create_slide` - Create a new blank slide
+- `figma_delete_slide` - Delete a slide from the presentation
+- `figma_duplicate_slide` - Clone an existing slide
+- `figma_reorder_slides` - Reorder slides via new 2D grid layout
+- `figma_set_slide_transition` - Set transition effects (22 styles, 8 curves)
+- `figma_skip_slide` - Toggle whether a slide is skipped in presentation mode
+- `figma_add_text_to_slide` - Add text to a specific slide
+- `figma_add_shape_to_slide` - Add rectangle or ellipse shapes with color
+- `figma_set_slides_view_mode` - Toggle grid vs. single-slide view
+- `figma_focus_slide` - Navigate to a specific slide
+
 **📖 [Detailed Tool Documentation](docs/TOOLS.md)**
 
 ---
@@ -479,6 +514,25 @@ Check design parity for the Card component before sign-off
 Generate component documentation for the Dialog from our design system
 ```
 
+### FigJam Boards
+```
+Create a retrospective board with "Went Well", "To Improve", and "Action Items" columns
+Build a user flow diagram for the checkout process with decision points
+Read this brainstorming board and summarize the key themes
+Generate an affinity map from these meeting notes
+Create a comparison table of our three platform options
+```
+
+### Slides Presentations
+```
+List all slides and tell me which ones are skipped
+Add a new slide with the title "Thank You" in 72px text
+Set a DISSOLVE transition on the first slide with 0.5 second duration
+Duplicate slide 5 for an A/B comparison
+Skip slides 8 and 9 — they're not ready for the client presentation
+Reorder my slides so the conclusion comes before Q&A
+```
+
 ### Visual Debugging
 ```
 Take a screenshot of the current Figma canvas
@@ -598,7 +652,7 @@ The **Figma Desktop Bridge** plugin is the recommended way to connect Figma to t
 - The MCP server communicates via **WebSocket** through the Desktop Bridge plugin
 - The server tries port 9223 first, then automatically falls back through ports 9224–9232 if needed
 - The plugin scans all ports in the range and connects to every active server it finds
-- All 63+ tools work through the WebSocket transport
+- All 89+ tools work through the WebSocket transport
 
 **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).
 
@@ -716,11 +770,12 @@ The architecture supports adding new apps with minimal boilerplate — each app
 
 ## 🤝 vs. Figma Official MCP
 
-**Figma Console MCP (This Project)** - Debugging & data extraction
+**Figma Console MCP (This Project)** - Debugging, data extraction, and design creation
 - ✅ Real-time console logs from Figma plugins
 - ✅ Screenshot capture and visual debugging
 - ✅ Error stack traces and runtime monitoring
 - ✅ Raw design data extraction (JSON)
+- ✅ FigJam board creation and reading (stickies, flowcharts, tables)
 - ✅ Works remotely or locally
 
 **Figma Official Dev Mode MCP** - Code generation
@@ -734,9 +789,11 @@ The architecture supports adding new apps with minimal boilerplate — each app
 
 ## 🛤️ Roadmap
 
-**Current Status:** v1.12.0 (Stable) - Production-ready with Cloud Write Relay, Design System Kit, WebSocket-only connectivity, smart multi-file tracking, 63+ tools, Comments API, and MCP Apps
+**Current Status:** v1.17.0 (Stable) - Production-ready with FigJam + Slides support, Cloud Write Relay, Design System Kit, WebSocket-only connectivity, smart multi-file tracking, 89+ tools, Comments API, and MCP Apps
 
 **Recent Releases:**
+- [x] **v1.17.0** - Figma Slides Support: 15 new tools for managing presentations — slides, transitions, content, reordering, and navigation. Inspired by Toni Haidamous (PR #11).
+- [x] **v1.16.0** - FigJam Support: 9 new tools for creating and reading FigJam boards — stickies, flowcharts, tables, code blocks, and connection graphs. Community-contributed by klgral and lukemoderwell.
 - [x] **v1.12.0** - Cloud Write Relay: web AI clients (Claude.ai, v0, Replit, Lovable) can create and modify Figma designs via cloud relay pairing — no Node.js required
 - [x] **v1.11.2** - Screenshot fix: `figma_take_screenshot` works without explicit `nodeId` in WebSocket mode
 - [x] **v1.11.1** - Doc generator fixes: clean markdown tables, Storybook links, property metadata filtering

package/dist/cloudflare/index.js

@@ -38,7 +38,7 @@ export class FigmaConsoleMCPv3 extends McpAgent {
         super(...arguments);
         this.server = new McpServer({
             name: "Figma Console MCP",
-            version: "1.15.0",
+            version: "1.15.5",
         });
         this.browserManager = null;
         this.consoleMonitor = null;
@@ -950,7 +950,7 @@ export default {
             });
             const statelessServer = new McpServer({
                 name: "Figma Console MCP",
-                version: "1.15.0",
+                version: "1.15.5",
             });
             // ================================================================
             // Cloud Write Relay — Pairing Tool (stateless /mcp path)
@@ -1579,7 +1579,7 @@ export default {
             return new Response(JSON.stringify({
                 status: "healthy",
                 service: "Figma Console MCP",
-                version: "1.15.0",
+                version: "1.15.5",
                 endpoints: {
                     mcp: ["/sse", "/mcp"],
                     oauth_mcp_spec: ["/.well-known/oauth-authorization-server", "/authorize", "/token", "/oauth/register"],

package/dist/core/annotation-tools.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Figma Annotations MCP Tools
+ * Tools for reading, writing, and managing design annotations on Figma nodes.
+ * Annotations are a Plugin API feature — requires Desktop Bridge plugin connection.
+ *
+ * Annotations are distinct from comments: they are node-level design specs that
+ * can pin specific properties (fills, width, typography, etc.) and support
+ * markdown-formatted labels. Designers use them to communicate animation timings,
+ * accessibility requirements, interaction specs, and other implementation details
+ * that don't fit in the description field.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerAnnotationTools(server: McpServer, getDesktopConnector: () => Promise<any>): void;
+//# sourceMappingURL=annotation-tools.d.ts.map

package/dist/core/annotation-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotation-tools.d.ts","sourceRoot":"","sources":["../../src/core/annotation-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA4EzE,wBAAgB,uBAAuB,CACtC,MAAM,EAAE,SAAS,EACjB,mBAAmB,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,GACrC,IAAI,CA0LN"}

package/dist/core/annotation-tools.js

@@ -0,0 +1,231 @@
+/**
+ * Figma Annotations MCP Tools
+ * Tools for reading, writing, and managing design annotations on Figma nodes.
+ * Annotations are a Plugin API feature — requires Desktop Bridge plugin connection.
+ *
+ * Annotations are distinct from comments: they are node-level design specs that
+ * can pin specific properties (fills, width, typography, etc.) and support
+ * markdown-formatted labels. Designers use them to communicate animation timings,
+ * accessibility requirements, interaction specs, and other implementation details
+ * that don't fit in the description field.
+ */
+import { z } from "zod";
+import { createChildLogger } from "./logger.js";
+const logger = createChildLogger({ component: "annotation-tools" });
+// Valid AnnotationPropertyType values from the Figma Plugin API
+// Sourced from @figma/plugin-typings — keep in sync with AnnotationPropertyType union
+// Reference: https://developers.figma.com/docs/plugins/api/AnnotationProperty
+const ANNOTATION_PROPERTY_TYPES = [
+    "width",
+    "height",
+    "maxWidth",
+    "minWidth",
+    "maxHeight",
+    "minHeight",
+    "fills",
+    "strokes",
+    "effects",
+    "strokeWeight",
+    "cornerRadius",
+    "textStyleId",
+    "textAlignHorizontal",
+    "fontFamily",
+    "fontStyle",
+    "fontSize",
+    "fontWeight",
+    "lineHeight",
+    "letterSpacing",
+    "itemSpacing",
+    "padding",
+    "layoutMode",
+    "alignItems",
+    "opacity",
+    "mainComponent",
+    "gridRowGap",
+    "gridColumnGap",
+    "gridRowCount",
+    "gridColumnCount",
+    "gridRowAnchorIndex",
+    "gridColumnAnchorIndex",
+    "gridRowSpan",
+    "gridColumnSpan",
+];
+// Zod schema for annotation property
+const annotationPropertySchema = z.object({
+    type: z
+        .enum(ANNOTATION_PROPERTY_TYPES)
+        .describe("Design property to pin (e.g., 'fills', 'width', 'fontSize')"),
+});
+// Zod schema for a single annotation
+const annotationSchema = z.object({
+    label: z
+        .string()
+        .optional()
+        .describe("Plain text annotation label"),
+    labelMarkdown: z
+        .string()
+        .optional()
+        .describe("Rich text annotation label with markdown formatting. Supports bold, italic, links, lists, code, and headers."),
+    properties: z
+        .array(annotationPropertySchema)
+        .optional()
+        .describe("Design properties to pin to this annotation (e.g., fills, width, fontSize)"),
+    categoryId: z
+        .string()
+        .optional()
+        .describe("Annotation category ID. Use figma_get_annotation_categories to list available categories."),
+});
+// ============================================================================
+// Tool Registration
+// ============================================================================
+export function registerAnnotationTools(server, getDesktopConnector) {
+    // -----------------------------------------------------------------------
+    // Tool: figma_get_annotations
+    // -----------------------------------------------------------------------
+    server.tool("figma_get_annotations", "Read annotations from a Figma node. Annotations are designer-authored specs attached to nodes — they can include notes (plain text or markdown), pinned design properties (fills, width, fontSize, etc.), and category labels. Use this to discover animation timings, interaction specs, accessibility requirements, and other implementation details that designers annotate directly on the design. Set include_children=true to get annotations from child nodes too (useful for full component documentation). Requires Desktop Bridge plugin.", {
+        nodeId: z
+            .string()
+            .describe("Node ID to read annotations from (e.g., '695:313')"),
+        include_children: z.preprocess((v) => (typeof v === "string" ? v === "true" : v), z.boolean().optional().default(false)).describe("Also read annotations from child nodes. Useful for getting all annotations within a component tree."),
+        depth: z.preprocess((v) => (typeof v === "string" ? Number(v) : v), z.number().optional().default(1)).describe("How many levels deep to traverse when include_children is true (default: 1, max recommended: 5)"),
+    }, async ({ nodeId, include_children = false, depth = 1 }) => {
+        try {
+            logger.info({ nodeId, include_children, depth }, "Getting annotations");
+            const connector = await getDesktopConnector();
+            const result = await connector.getAnnotations(nodeId, include_children, Math.min(depth, 10));
+            if (!result || (result.success === false)) {
+                throw new Error(result?.error || "Failed to get annotations");
+            }
+            // The result may come back as { success, data } (WebSocket) or directly as data
+            const data = result.data || result;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(data),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error({ error }, "Failed to get annotations");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "get_annotations_failed",
+                            message: `Cannot get annotations. ${message}`,
+                            hint: "Annotations require the Desktop Bridge plugin to be running in Figma.",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // -----------------------------------------------------------------------
+    // Tool: figma_set_annotations
+    // -----------------------------------------------------------------------
+    server.tool("figma_set_annotations", "Write or clear annotations on a Figma node. Annotations communicate design specs to developers — use them to document animation timings, easing curves, interaction behaviors, accessibility requirements, and implementation notes. Supports plain text labels, rich markdown labels, pinned design properties, and annotation categories. Pass an empty array to clear all annotations. Use mode='append' to add to existing annotations, or mode='replace' (default) to overwrite. Requires Desktop Bridge plugin. This operation is undoable in Figma (Cmd+Z).", {
+        nodeId: z
+            .string()
+            .describe("Node ID to write annotations to (e.g., '695:313')"),
+        annotations: z.preprocess((v) => {
+            if (typeof v === "string") {
+                try {
+                    return JSON.parse(v);
+                }
+                catch {
+                    return v;
+                }
+            }
+            return v;
+        }, z.array(annotationSchema)).describe("Array of annotations to set. Each annotation can have a label (plain or markdown), pinned properties, and a category. Pass an empty array [] to clear all annotations."),
+        mode: z
+            .enum(["replace", "append"])
+            .optional()
+            .default("replace")
+            .describe("'replace' (default) overwrites all existing annotations. 'append' adds new annotations while keeping existing ones."),
+    }, async ({ nodeId, annotations, mode = "replace" }) => {
+        try {
+            logger.info({ nodeId, count: annotations.length, mode }, "Setting annotations");
+            const connector = await getDesktopConnector();
+            const result = await connector.setAnnotations(nodeId, annotations, mode);
+            if (!result || (result.success === false)) {
+                throw new Error(result?.error || "Failed to set annotations");
+            }
+            const data = result.data || result;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            ...data,
+                            note: "Annotations set successfully. This operation is undoable in Figma (Cmd+Z).",
+                        }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error({ error }, "Failed to set annotations");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "set_annotations_failed",
+                            message: `Cannot set annotations. ${message}`,
+                            hint: "Annotations require the Desktop Bridge plugin to be running in Figma.",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // -----------------------------------------------------------------------
+    // Tool: figma_get_annotation_categories
+    // -----------------------------------------------------------------------
+    server.tool("figma_get_annotation_categories", "List available annotation categories in the current Figma file. Categories group annotations by purpose (e.g., interactions, accessibility, development notes). Use the returned category IDs when creating annotations with figma_set_annotations. Requires Desktop Bridge plugin.", {}, async () => {
+        try {
+            logger.info("Getting annotation categories");
+            const connector = await getDesktopConnector();
+            const result = await connector.getAnnotationCategories();
+            if (!result || (result.success === false)) {
+                throw new Error(result?.error || "Failed to get annotation categories");
+            }
+            const data = result.data || result;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(data),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            logger.error({ error }, "Failed to get annotation categories");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: "get_annotation_categories_failed",
+                            message: `Cannot get annotation categories. ${message}`,
+                            hint: "Annotation categories require the Desktop Bridge plugin to be running in Figma.",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=annotation-tools.js.map

package/dist/core/annotation-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"annotation-tools.js","sourceRoot":"","sources":["../../src/core/annotation-tools.ts"],"names":[],"mappings":"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"}

package/dist/core/deep-component-tools.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Deep Component Extraction MCP Tool
+ *
+ * Provides unlimited-depth component tree extraction via the Desktop Bridge
+ * Plugin API. Returns full visual properties, resolved design token names,
+ * instance references (mainComponent), prototype reactions, and annotations
+ * at every level of the tree.
+ *
+ * This complements figma_get_component_for_development (REST API, depth 4)
+ * with deeper, richer data when the Desktop Bridge plugin is connected.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerDeepComponentTools(server: McpServer, getDesktopConnector: () => Promise<any>): void;
+//# sourceMappingURL=deep-component-tools.d.ts.map

package/dist/core/deep-component-tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deep-component-tools.d.ts","sourceRoot":"","sources":["../../src/core/deep-component-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAMzE,wBAAgB,0BAA0B,CACzC,MAAM,EAAE,SAAS,EACjB,mBAAmB,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,GACrC,IAAI,CAyIN"}