@mp3wizard/figma-console-mcp 1.15.3 → 1.17.3

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.
+
+> **🆕 FigJam + Slides — AI Across All Figma Products:** 24 new tools bring AI to FigJam boards and Figma Slides. Create stickies, flowcharts, and tables on whiteboards. Manage entire presentations — slides, transitions, content, and reordering. [FigJam Guide →](docs/figjam.md) | [Slides Guide →](docs/slides.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** | **84+** | **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 84+ 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 84+ tools including design creation, variable management, and component instantiation.
 
 #### Prerequisites
 
@@ -78,7 +83,7 @@ Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
 
 **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 +95,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 +132,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 +158,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 84+ tools as NPX, plus full source code access.
 
 #### Quick Setup
 
@@ -242,7 +247,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:** 76 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 +304,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** | **84+** | **43** | **84+** | **22** (read-only) |
 | **Design creation** | ✅ | ✅ | ✅ | ❌ |
 | **Variable management** | ✅ | ✅ | ✅ | ❌ |
 | **Component instantiation** | ✅ | ✅ | ✅ | ❌ |
+| **FigJam boards** | ✅ | ✅ | ✅ | ❌ |
 | **Real-time monitoring** | ✅ | ❌ | ✅ | ❌ |
 | **Desktop Bridge plugin** | ✅ | ✅ | ✅ | ❌ |
 | **Variables (no Enterprise)** | ✅ | ✅ | ✅ | ❌ |
@@ -313,7 +319,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 84+ tools.
 
 **📖 [Complete Feature Comparison](docs/mode-comparison.md)**
 
@@ -426,6 +432,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 +513,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 +651,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 84+ 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 +769,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 +788,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, 84+ 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
@@ -758,28 +814,6 @@ The architecture supports adding new apps with minimal boilerplate — each app
 
 ---
 
-## 🔒 Security
-
-This repository has undergone **two security reviews** — most recently on 2026-03-18 (v1.14.0).
-
-### What Was Reviewed
-
-- Authentication & token handling
-- Input validation and sanitization
-- Rate limiting and abuse prevention
-- Error message exposure
-- Dependency vulnerabilities
-- Secrets management
-
-### Review Outcome
-
-All identified security findings have been addressed and patched in this fork. No sensitive credentials are exposed, and error messages have been sanitized to prevent information leakage.
-
-📄 **Latest report:** [SECURITY-REVIEW-2026-03-18.md](Security%20review%20report/SECURITY-REVIEW-2026-03-18.md)
-📄 **Previous report:** [SECURITY-REVIEW-2026-03-16.md](Security%20review%20report/SECURITY-REVIEW-2026-03-16.md)
-
----
-
 ## 💻 Development
 
 ```bash

package/dist/cloudflare/core/cloud-websocket-relay.js

@@ -164,7 +164,6 @@ export class PluginRelayDO extends DurableObject {
         }
         const body = await request.json();
         const { method, params = {}, timeoutMs = 15000 } = body;
-        const safeTimeout = Math.min(Math.max(timeoutMs, 1000), 60000); // clamp 1s–60s
         const id = `relay_${++this.requestIdCounter}_${Date.now()}`;
         // Send command to plugin
         try {
@@ -178,9 +177,9 @@ export class PluginRelayDO extends DurableObject {
             const timeoutId = setTimeout(() => {
                 if (this.pendingRequests.has(id)) {
                     this.pendingRequests.delete(id);
-                    resolve(new Response(JSON.stringify({ error: `Command ${method} timed out after ${safeTimeout}ms` }), { status: 504, headers: { 'Content-Type': 'application/json' } }));
+                    resolve(new Response(JSON.stringify({ error: `Command ${method} timed out after ${timeoutMs}ms` }), { status: 504, headers: { 'Content-Type': 'application/json' } }));
                 }
-            }, safeTimeout);
+            }, timeoutMs);
             this.pendingRequests.set(id, { resolve, reject: () => { }, timeoutId });
         });
     }

package/dist/cloudflare/core/config.js

@@ -30,7 +30,7 @@ const DEFAULT_CONFIG = {
         args: [
             '--disable-blink-features=AutomationControlled',
             '--disable-dev-shm-usage',
-            // '--no-sandbox' removed from defaults; enable via config file if required by your environment
+            '--no-sandbox', // Note: Only use in trusted environments
         ],
     },
     console: {

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

@@ -94,12 +94,16 @@ export class FigmaAPI {
         // OAuth tokens start with 'figu_' and require Authorization: Bearer header
         // Personal Access Tokens use X-Figma-Token header
         const isOAuthToken = this.accessToken.startsWith('figu_');
-        logger.debug({
+        // Debug logging to verify token is being used
+        const tokenPreview = this.accessToken ? `${this.accessToken.substring(0, 10)}...` : 'NO TOKEN';
+        logger.info({
             url,
+            tokenPreview,
             hasToken: !!this.accessToken,
+            tokenLength: this.accessToken?.length,
             isOAuthToken,
             authMethod: isOAuthToken ? 'Bearer' : 'X-Figma-Token'
-        }, 'Making Figma API request');
+        }, 'Making Figma API request with token');
         const headers = {
             'Content-Type': 'application/json',
             ...(options.headers || {}),

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

@@ -429,8 +429,7 @@ export class FigmaDesktopConnector {
         } catch (error) {
           return {
             success: false,
-            error: error.message,
-            stack: error.stack
+            error: error.message
           };
         }
       })()

package/dist/cloudflare/core/port-discovery.js

@@ -80,7 +80,7 @@ export function advertisePort(port, host = 'localhost') {
     };
     const filePath = getPortFilePath(port);
     try {
-        writeFileSync(filePath, JSON.stringify(data, null, 2), { mode: 0o600 });
+        writeFileSync(filePath, JSON.stringify(data, null, 2));
         logger.info({ port, filePath }, 'Port advertised');
     }
     catch (error) {
@@ -103,7 +103,7 @@ export function refreshPortAdvertisement(port) {
         if (data.pid !== process.pid)
             return;
         data.lastSeen = new Date().toISOString();
-        writeFileSync(filePath, JSON.stringify(data, null, 2), { mode: 0o600 });
+        writeFileSync(filePath, JSON.stringify(data, null, 2));
     }
     catch {
         // Best-effort — heartbeat failures are non-fatal
@@ -265,6 +265,77 @@ export function cleanupStalePortFiles() {
     }
     return cleaned;
 }
+/**
+ * Deep scan for orphaned MCP server processes that hold ports but have no port files.
+ * These are processes left behind by Claude Desktop when tabs close without proper cleanup.
+ *
+ * Uses lsof (macOS/Linux) to find PIDs listening on each port in the range,
+ * then verifies they're figma-console-mcp before terminating.
+ *
+ * Call AFTER cleanupStalePortFiles() — that handles the port-file-based cleanup first,
+ * then this catches any remaining ghosts.
+ */
+export function cleanupOrphanedProcesses(preferredPort = DEFAULT_WS_PORT) {
+    // Only supported on macOS/Linux (lsof)
+    if (process.platform === 'win32')
+        return 0;
+    let cleaned = 0;
+    const myPid = process.pid;
+    const ports = getPortRange(preferredPort);
+    // Collect PIDs that have valid port files (known-good servers)
+    const knownPids = new Set();
+    for (const port of ports) {
+        const data = readPortFile(port);
+        if (data)
+            knownPids.add(data.pid);
+    }
+    knownPids.add(myPid); // Never kill ourselves
+    for (const port of ports) {
+        try {
+            // Find PIDs listening on this port via lsof
+            const { execSync } = require('child_process');
+            const output = execSync(`lsof -i :${port} -sTCP:LISTEN -t 2>/dev/null`, {
+                encoding: 'utf-8',
+                timeout: 3000,
+            }).trim();
+            if (!output)
+                continue;
+            const pids = output.split('\n').map(Number).filter(Boolean);
+            for (const pid of pids) {
+                if (knownPids.has(pid))
+                    continue; // Skip known-good servers
+                // Verify this is actually a figma-console-mcp process before killing
+                try {
+                    const cmdline = execSync(`ps -p ${pid} -o command= 2>/dev/null`, {
+                        encoding: 'utf-8',
+                        timeout: 2000,
+                    }).trim();
+                    if (cmdline.includes('figma-console-mcp') || cmdline.includes('figma_console_mcp') || cmdline.includes('local.js')) {
+                        logger.info({ port, pid, command: cmdline.substring(0, 120) }, 'Terminating orphaned MCP server (no port file, holding port)');
+                        terminateProcess(pid);
+                        cleaned++;
+                    }
+                }
+                catch {
+                    // Can't read process info — skip to be safe
+                }
+            }
+        }
+        catch {
+            // lsof failed for this port — skip
+        }
+    }
+    if (cleaned > 0) {
+        // Give terminated processes a moment to release their ports
+        try {
+            const { execSync } = require('child_process');
+            execSync('sleep 0.5', { timeout: 2000 });
+        }
+        catch { /* non-critical */ }
+        logger.info({ cleaned }, `Cleaned up ${cleaned} orphaned MCP server process(es)`);
+    }
+    return cleaned;
+}
 /**
  * Register process exit handlers to clean up port advertisement file.
  * Should be called once after the port is successfully bound.

package/dist/cloudflare/core/websocket-server.js

@@ -14,7 +14,8 @@
  */
 import { WebSocketServer as WSServer, WebSocket } from 'ws';
 import { EventEmitter } from 'events';
-import { readFileSync } from 'fs';
+import { createServer as createHttpServer } from 'http';
+import { readFileSync, existsSync } from 'fs';
 import { join } from 'path';
 import { createChildLogger } from './logger.js';
 // Read version from package.json
@@ -27,11 +28,37 @@ try {
 catch {
     // Non-critical — version will show as 0.0.0
 }
+/**
+ * Load the full plugin UI HTML content that gets served to the bootloader.
+ * Falls back to a minimal error page if the file isn't found.
+ */
+function loadPluginUIContent() {
+    const candidates = [
+        // ESM runtime: dist/core/ → ../../figma-desktop-bridge/
+        typeof __dirname !== 'undefined'
+            ? join(__dirname, '..', '..', 'figma-desktop-bridge', 'ui-full.html')
+            : join(process.cwd(), 'figma-desktop-bridge', 'ui-full.html'),
+        // Direct from project root
+        join(process.cwd(), 'figma-desktop-bridge', 'ui-full.html'),
+    ];
+    for (const path of candidates) {
+        try {
+            if (existsSync(path)) {
+                return readFileSync(path, 'utf-8');
+            }
+        }
+        catch {
+            // try next candidate
+        }
+    }
+    return '<html><body><p>Plugin UI not found. Please reinstall figma-console-mcp.</p></body></html>';
+}
 const logger = createChildLogger({ component: 'websocket-server' });
 export class FigmaWebSocketServer extends EventEmitter {
     constructor(options) {
         super();
         this.wss = null;
+        this.httpServer = null;
         /** Named clients indexed by fileKey — each represents a connected Figma file */
         this.clients = new Map();
         /** Clients awaiting FILE_INFO identification, mapped to their pending timeout */
@@ -44,21 +71,75 @@ export class FigmaWebSocketServer extends EventEmitter {
         this._startedAt = Date.now();
         this.consoleBufferSize = 1000;
         this.documentChangeBufferSize = 200;
+        /** Cached plugin UI HTML content — loaded once and served to bootloader requests */
+        this._pluginUIContent = null;
         this.options = options;
         this._startedAt = Date.now();
     }
     /**
-     * Start the WebSocket server
+     * Handle HTTP requests on the same port as WebSocket.
+     * Serves plugin UI content for the bootloader and health checks.
+     */
+    handleHttpRequest(req, res) {
+        // CORS headers for Figma plugin iframe (sandboxed, origin: null)
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        const url = req.url || '/';
+        // Plugin UI endpoint — bootloader redirects here
+        if (url === '/plugin/ui' || url === '/plugin/ui/') {
+            if (!this._pluginUIContent) {
+                this._pluginUIContent = loadPluginUIContent();
+            }
+            res.writeHead(200, {
+                'Content-Type': 'text/html; charset=utf-8',
+                'Cache-Control': 'no-cache, no-store, must-revalidate',
+            });
+            res.end(this._pluginUIContent);
+            return;
+        }
+        // Health/version endpoint
+        if (url === '/health' || url === '/') {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                status: 'ok',
+                version: SERVER_VERSION,
+                clients: this.clients.size,
+                uptime: Math.floor((Date.now() - this._startedAt) / 1000),
+            }));
+            return;
+        }
+        // 404 for anything else
+        res.writeHead(404, { 'Content-Type': 'text/plain' });
+        res.end('Not Found');
+    }
+    /**
+     * Start the HTTP + WebSocket server.
+     * HTTP serves the plugin UI content; WebSocket handles plugin communication.
      */
     async start() {
         if (this._isStarted)
             return;
         return new Promise((resolve, reject) => {
+            let rejected = false;
+            const rejectOnce = (error) => {
+                if (!rejected) {
+                    rejected = true;
+                    reject(error);
+                }
+            };
             try {
+                // Create HTTP server first — handles plugin UI requests
+                this.httpServer = createHttpServer((req, res) => this.handleHttpRequest(req, res));
+                // Attach WebSocket server to the HTTP server (shares the same port)
                 this.wss = new WSServer({
-                    port: this.options.port,
-                    host: this.options.host || 'localhost',
-                    maxPayload: 25 * 1024 * 1024, // 25MB — sufficient for screenshots; set FIGMA_WS_MAX_PAYLOAD_MB env var to override
+                    server: this.httpServer,
+                    maxPayload: 100 * 1024 * 1024, // 100MB — screenshots and large component data can be big
                     verifyClient: (info, callback) => {
                         // Mitigate Cross-Site WebSocket Hijacking (CSWSH):
                         // Reject connections from unexpected browser origins.
@@ -76,18 +157,38 @@ export class FigmaWebSocketServer extends EventEmitter {
                         }
                     },
                 });
-                this.wss.on('listening', () => {
-                    this._isStarted = true;
-                    logger.info({ port: this.options.port, host: this.options.host || 'localhost' }, 'WebSocket bridge server started');
-                    resolve();
-                });
-                this.wss.on('error', (error) => {
+                // Error handler for startup failures (EADDRINUSE, etc.)
+                // Must be on BOTH httpServer and wss — the WSS re-emits HTTP server errors
+                // and throws if no listener is attached.
+                const onStartupError = (error) => {
                     if (!this._isStarted) {
-                        reject(error);
+                        try {
+                            if (this.wss) {
+                                this.wss.close();
+                                this.wss = null;
+                            }
+                        }
+                        catch { /* ignore */ }
+                        try {
+                            if (this.httpServer) {
+                                this.httpServer.close();
+                                this.httpServer = null;
+                            }
+                        }
+                        catch { /* ignore */ }
+                        rejectOnce(error);
                     }
                     else {
-                        logger.error({ error }, 'WebSocket server error');
+                        logger.error({ error }, 'HTTP/WebSocket server error');
                     }
+                };
+                this.httpServer.on('error', onStartupError);
+                this.wss.on('error', onStartupError);
+                // Start listening on the HTTP server (which also handles WS upgrades)
+                this.httpServer.listen(this.options.port, this.options.host || 'localhost', () => {
+                    this._isStarted = true;
+                    logger.info({ port: this.options.port, host: this.options.host || 'localhost' }, 'WebSocket bridge server started (with HTTP plugin UI endpoint)');
+                    resolve();
                 });
                 this.wss.on('connection', (ws) => {
                     // Add to pending until FILE_INFO identifies the file
@@ -146,7 +247,7 @@ export class FigmaWebSocketServer extends EventEmitter {
                 });
             }
             catch (error) {
-                reject(error);
+                rejectOnce(error);
             }
         });
     }
@@ -177,6 +278,22 @@ export class FigmaWebSocketServer extends EventEmitter {
             }
             return;
         }
+        // Bootloader request: send the full plugin UI HTML
+        if (message.type === 'GET_PLUGIN_UI') {
+            if (!this._pluginUIContent) {
+                this._pluginUIContent = loadPluginUIContent();
+            }
+            try {
+                ws.send(JSON.stringify({
+                    type: 'PLUGIN_UI_CONTENT',
+                    html: this._pluginUIContent,
+                }));
+            }
+            catch {
+                // Non-critical — bootloader will show error
+            }
+            return;
+        }
         // Unsolicited data from plugin (FILE_INFO, events, forwarded data)
         if (message.type) {
             // FILE_INFO promotes pending clients to named clients
@@ -434,11 +551,19 @@ export class FigmaWebSocketServer extends EventEmitter {
      * Returns the actual port — critical when using port 0 for OS-assigned ports.
      */
     address() {
+        // Use the HTTP server's address (which is the actual listening socket)
+        if (this.httpServer) {
+            const addr = this.httpServer.address();
+            if (typeof addr === 'string' || !addr)
+                return null;
+            return addr;
+        }
+        // Fallback for backward compat
         if (!this.wss)
             return null;
         const addr = this.wss.address();
         if (typeof addr === 'string')
-            return null; // Unix socket path, not applicable
+            return null;
         return addr;
     }
     // ============================================================================
@@ -632,15 +757,20 @@ export class FigmaWebSocketServer extends EventEmitter {
         }
         this.clients.clear();
         this._activeFileKey = null;
+        // Close WS server first (handles WebSocket connections)
         if (this.wss) {
-            return new Promise((resolve) => {
-                this.wss.close(() => {
-                    this._isStarted = false;
-                    logger.info('WebSocket bridge server stopped');
-                    resolve();
-                });
+            await new Promise((resolve) => {
+                this.wss.close(() => resolve());
+            });
+        }
+        // Then close HTTP server (releases the port)
+        if (this.httpServer) {
+            await new Promise((resolve) => {
+                this.httpServer.close(() => resolve());
             });
+            this.httpServer = null;
         }
         this._isStarted = false;
+        logger.info('WebSocket bridge server stopped');
     }
 }