figma-rust-mcp 4.1.0 → 5.0.0

package/README.md

@@ -18,7 +18,7 @@ Enables AI agents (Google Antigravity, Claude Code, Cursor, Windsurf, VS Code, Z
 - **Batch Asset Extractor (`figma_export_assets` / `figma_export_asset`)**: Extracts SVG icons and raster images directly to project folders (`outputPath`) with auto-generated TypeScript barrel exports (`index.ts`) — zero chat token bloating.
 - **Sandboxed JS Drawing Engine (`figma_write`)**: Powered by **Boa** (pure Rust ECMAScript engine) with built-in asset resolvers and 7 icon packs (*Ionicons, Lucide, Tabler, Bootstrap, Fluent, Phosphor*).
 - **Multi-Tab / Multi-Session Support**: Seamlessly connects to multiple open Figma files simultaneously.
-- **100% Localhost Privacy**: All communication stays strictly on `127.0.0.1:38451`.
+- **100% Localhost Privacy**: All communication stays strictly on `127.0.0.1:41730`.
 
 ---
 
@@ -36,7 +36,7 @@ Enables AI agents (Google Antigravity, Claude Code, Cursor, Windsurf, VS Code, Z
 │  • Sandboxed JS Runtime (Boa ECMAScript Engine)                        │
 │  • Binary MessagePack & Progressive Subtree Chunk Receiver             │
 └───────────────▲────────────────────────────────────────▲───────────────┘
-                │ (ws://127.0.0.1:38451/ws)              │ (http://127.0.0.1:38451/mcp)
+                │ (ws://127.0.0.1:41730/ws)              │ (http://127.0.0.1:41730/mcp)
                 │ (Dynamic Code Streaming & Hot-Reload)  │ (JSON-RPC 2.0 / Streamable HTTP)
       ┌─────────┴─────────┐                    ┌─────────┴─────────┐
       │   Figma Desktop   │                    │ AI Assistant(s)   │
@@ -50,9 +50,10 @@ Enables AI agents (Google Antigravity, Claude Code, Cursor, Windsurf, VS Code, Z
 
 ### 🔌 How the Zero-Touch Connection Works:
 1. **Permanent Thin Loader**: You only import the Figma plugin **once** (`~/.figma-rust-mcp/plugin/manifest.json`).
-2. **Dynamic Runtime Streaming**: Upon launch, the Thin Loader contacts `http://127.0.0.1:38451/plugin/code.js` to fetch and execute the latest runtime in memory.
-3. **Live WebSocket Hot-Reload**: The plugin connects to `ws://127.0.0.1:38451/ws`. When you upgrade `figma-rust-mcp` or restart the daemon, the plugin automatically detects the new server version and hot-reloads seamlessly — **no need to re-import or restart the plugin in Figma**.
+2. **Dynamic Runtime Streaming**: Upon launch, the Thin Loader contacts `http://127.0.0.1:41730/plugin/code.js` to fetch and execute the latest runtime in memory.
+3. **Live WebSocket Hot-Reload**: The plugin connects to `ws://127.0.0.1:41730/ws`. When you upgrade `figma-rust-mcp` or restart the daemon, the plugin automatically detects the new server version and hot-reloads seamlessly — **no need to re-import or restart the plugin in Figma**.
 4. **Auto-Reconnect & Offline Buffer**: If Figma is opened before the Rust service starts, the plugin displays a waiting screen and connects automatically the instant the service is up.
+5. **Port Range & Auto-Switch**: The bridge uses ports `41730–41739`. On start it reuses a running server of the same version, skips any port held by another app or a different figma-rust-mcp version, and starts on the first free port. The plugin scans the same range, so it follows automatically. MCP clients configured by URL point at `41730`; the server prints a warning with the new port if it had to move.
 
 ---
 
@@ -148,13 +149,13 @@ Use the `/mcp` endpoint. It accepts `POST` JSON-RPC requests directly:
 
 ```toml
 [mcp_servers.figma-rust-mcp]
-url = "http://127.0.0.1:38451/mcp"
+url = "http://127.0.0.1:41730/mcp"
 ```
 
 For Codex CLI, the equivalent command is:
 
 ```bash
-codex mcp add figma-rust-mcp --url http://127.0.0.1:38451/mcp
+codex mcp add figma-rust-mcp --url http://127.0.0.1:41730/mcp
 ```
 
 #### Google Antigravity (SSE Transport)
@@ -163,7 +164,7 @@ Add to your `~/.gemini/config/mcp_config.json` or project `.agents/mcp_config.js
 {
   "mcpServers": {
     "figma-rust-mcp": {
-      "serverUrl": "http://127.0.0.1:38451/sse"
+      "serverUrl": "http://127.0.0.1:41730/sse"
     }
   }
 }
@@ -176,7 +177,7 @@ These clients can use the Streamable HTTP `/mcp` endpoint:
 {
   "mcpServers": {
     "figma-rust-mcp": {
-      "url": "http://127.0.0.1:38451/mcp"
+      "url": "http://127.0.0.1:41730/mcp"
     }
   }
 }
@@ -200,7 +201,7 @@ Alternatively, configure a stdio subprocess via NPX:
 Check the runtime bundle currently served to Figma Desktop:
 
 ```bash
-curl http://127.0.0.1:38451/plugin/version
+curl http://127.0.0.1:41730/plugin/version
 ```
 
 The response includes `version` and `runtimeHash`. If the hash changes after an

package/bin/agent-config.js

@@ -4,7 +4,7 @@ import os from 'node:os';
 import { applyEdits, modify, parse } from 'jsonc-parser';
 
 const SERVER_NAME = 'figma-rust-mcp';
-const HTTP_URL = 'http://127.0.0.1:38451/mcp';
+const HTTP_URL = 'http://127.0.0.1:41730/mcp';
 
 function existsAny(paths) {
   return paths.some(candidate => candidate && fs.existsSync(candidate));
@@ -78,7 +78,7 @@ function upsertCodex(filePath) {
 
 export function configureAgent(agent) {
   const entry = agent.id === 'antigravity'
-    ? { serverUrl: 'http://127.0.0.1:38451/sse' }
+    ? { serverUrl: 'http://127.0.0.1:41730/sse' }
     : agent.id === 'claude' || agent.id === 'vscode'
       ? { type: 'http', url: HTTP_URL }
       : { url: HTTP_URL };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-rust-mcp",
-  "version": "4.1.0",
+  "version": "5.0.0",
   "description": "Claude Code to Figma — Bidirectional MCP bridge. AI draws UI on Figma canvas, reads designs back. Works with Claude, Cursor, VS Code, Windsurf, Antigravity. No API key needed.",
   "mcpName": "io.github.BuiHung1612/figma-rust-mcp",
   "type": "module",

package/plugin/manifest.json

@@ -5,21 +5,33 @@
   "main": "code.js",
   "ui": "ui.html",
   "documentAccess": "dynamic-page",
-  "editorType": ["figma", "dev"],
+  "editorType": [
+    "figma",
+    "dev"
+  ],
   "networkAccess": {
     "allowedDomains": [
-      "http://localhost:38451",
-      "http://localhost:38452",
-      "http://localhost:38453",
-      "http://localhost:38454",
-      "http://localhost:38455",
-      "ws://localhost:38451",
-      "ws://localhost:38452",
-      "ws://localhost:38453",
-      "ws://localhost:38454",
-      "ws://localhost:38455"
+      "http://localhost:41730",
+      "http://localhost:41731",
+      "http://localhost:41732",
+      "http://localhost:41733",
+      "http://localhost:41734",
+      "http://localhost:41735",
+      "http://localhost:41736",
+      "http://localhost:41737",
+      "http://localhost:41738",
+      "http://localhost:41739",
+      "ws://localhost:41730",
+      "ws://localhost:41731",
+      "ws://localhost:41732",
+      "ws://localhost:41733",
+      "ws://localhost:41734",
+      "ws://localhost:41735",
+      "ws://localhost:41736",
+      "ws://localhost:41737",
+      "ws://localhost:41738",
+      "ws://localhost:41739"
     ],
-    "reasoning": "Thin loader connecting dynamically to the local figma-rust-mcp Rust engine on ports 38451-38455."
+    "reasoning": "Thin loader connecting dynamically to the local figma-rust-mcp Rust engine on ports 41730-41739."
   }
 }
-

package/plugin/ui.html

@@ -6,18 +6,18 @@
   <title>Figma Rust MCP Loader</title>
   <style>
     :root {
-      --bg: #0d0e12;
-      --surface-base: #12141a;
-      --surface-card: #171922;
-      --border-subtle: rgba(255, 255, 255, 0.08);
-      --border-ghost: rgba(147, 129, 255, 0.35);
-      --text-primary: #f4f4f7;
-      --text-secondary: #9aa1b2;
-      --text-muted: #52596d;
-      --ghost-lavender: #9381ff;
-      --ghost-mint: #34d399;
-      --font-ui: -apple-system, BlinkMacSystemFont, 'Inter', 'SF Pro Text', sans-serif;
-      --font-mono: 'JetBrains Mono', 'SF Mono', Menlo, monospace;
+      --bg: #fdf1dc;
+      --surface-base: #fffaf0;
+      --surface-card: #fffdf7;
+      --border-subtle: #1c1a17;
+      --border-ghost: #1c1a17;
+      --text-primary: #1c1a17;
+      --text-secondary: #4a453d;
+      --text-muted: #7d7567;
+      --ghost-lavender: #f4532c;
+      --ghost-mint: #2f8f3a;
+      --font-ui: ui-rounded, 'SF Pro Rounded', -apple-system, BlinkMacSystemFont, 'Inter', sans-serif;
+      --font-mono: ui-monospace, 'SF Mono', 'JetBrains Mono', Menlo, monospace;
     }
     *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
     html, body { width: 100%; height: 100%; overflow: hidden; background: var(--bg); color: var(--text-primary); font-family: var(--font-ui); font-size: 11px; }
@@ -58,7 +58,7 @@
       height: 14px;
       border-radius: 50%;
       background: var(--ghost-lavender);
-      box-shadow: 0 0 16px var(--ghost-lavender);
+      border: 2px solid #1c1a17;
     }
 
     @keyframes pulse {
@@ -85,7 +85,8 @@
       gap: 6px;
       padding: 4px 10px;
       background: var(--surface-card);
-      border: 1px solid var(--border-subtle);
+      border: 2px solid var(--border-subtle);
+      box-shadow: 2px 2px 0 #1c1a17;
       border-radius: 9999px;
       font-family: var(--font-mono);
       font-size: 10px;
@@ -94,7 +95,8 @@
     }
     .hint-box {
       background: var(--surface-base);
-      border: 1px solid var(--border-subtle);
+      border: 2px solid var(--border-subtle);
+      box-shadow: 2px 2px 0 #1c1a17;
       border-radius: 8px;
       padding: 10px 12px;
       max-width: 280px;
@@ -108,7 +110,7 @@
       color: var(--ghost-lavender);
       display: block;
       margin-top: 4px;
-      background: rgba(0,0,0,0.3);
+      background: rgba(28,26,23,0.06);
       padding: 3px 6px;
       border-radius: 4px;
     }
@@ -123,9 +125,9 @@
       <div class="radar-core"></div>
     </div>
     <div class="title">Connecting to figma-rust-mcp</div>
-    <div id="status" class="status-text">Scanning local ports (38451-38455)...</div>
+    <div id="status" class="status-text">Scanning local ports (41730-41739)...</div>
     <div class="badge">
-      <span>●</span> <span id="port-label">localhost:38451</span>
+      <span>●</span> <span id="port-label">localhost:41730</span>
     </div>
     <div class="hint-box">
       Ensure the local Rust server is running:
@@ -134,7 +136,8 @@
   </div>
 
   <script>
-    const PORTS = [38451, 38452, 38453, 38454, 38455];
+    // Must match DEFAULT_PORT / PORT_RANGE in src/bridge/server.rs and manifest.json.
+    const PORTS = Array.from({ length: 10 }, (_, i) => 41730 + i);
     let attempts = 0;
 
     async function checkPort(port) {
@@ -148,8 +151,9 @@
         clearTimeout(timeoutId);
         if (res.ok) {
           const data = await res.json();
-          return { ok: true, data };
+          if (data && data.name === "figma-rust-mcp") return { ok: true, data };
         }
+        return { ok: false, answered: true };
       } catch (_) {
         clearTimeout(timeoutId);
       }
@@ -174,7 +178,8 @@
         if (!uiRes.ok) throw new Error("Failed to load plugin UI: " + uiRes.status);
         const uiHtml = await uiRes.text();
 
-        // 3. Inject full UI cleanly
+        // 3. Inject full UI cleanly; the runtime reads the port from here (globals survive document.open).
+        window.__FIGMA_MCP_PORT = port;
         document.open();
         document.write(uiHtml);
         document.close();
@@ -190,17 +195,20 @@
       const statusEl = document.getElementById("status");
       const portEl = document.getElementById("port-label");
 
-      for (const port of PORTS) {
-        if (portEl) portEl.textContent = `localhost:${port}`;
-        const result = await checkPort(port);
-        if (result.ok) {
-          await bootstrapFromPort(port);
-          return;
-        }
+      if (portEl) portEl.textContent = `localhost:${PORTS[0]}-${PORTS[PORTS.length - 1]}`;
+      const results = await Promise.all(PORTS.map(checkPort));
+      const hit = results.findIndex(r => r.ok);
+      if (hit >= 0) {
+        if (portEl) portEl.textContent = `localhost:${PORTS[hit]}`;
+        await bootstrapFromPort(PORTS[hit]);
+        return;
       }
 
       if (statusEl) {
-        statusEl.textContent = `Waiting for server (attempt #${attempts})...`;
+        const busy = PORTS.filter((_, i) => results[i].answered);
+        statusEl.textContent = busy.length
+          ? `Port ${busy.join(", ")} answered but is not a compatible figma-rust-mcp. Run: npx -y figma-rust-mcp@latest --install-service (attempt #${attempts})`
+          : `Waiting for server (attempt #${attempts})...`;
       }
       setTimeout(findAndConnect, 1000);
     }

package/scripts/test-plugin-tokens.mjs

@@ -53,6 +53,20 @@ test('compact tree and scan preserve mixed typography instead of using the first
   assert.equal(r.resolveTextStyle(node).fontWeight, undefined);
 });
 
+test('scan_design expands instances by default and flags opaque ones as incomplete', async () => {
+  const text = { id: '1:3', name: 'Label', type: 'TEXT', characters: 'Hi', fontSize: 12, fontName: { family: 'Inter', style: 'Regular' }, visible: true };
+  const inst = { id: '1:2', name: 'Button', type: 'INSTANCE', visible: true, children: [text], getMainComponentAsync: async () => null };
+  const frame = { id: '1:1', name: 'Frame', type: 'FRAME', visible: true, children: [inst] };
+  const r = runtime({ root: { id: '0:0' }, currentPage: { id: '0:1' }, getNodeByIdAsync: async () => frame });
+  const full = plain(await r.handlers.scan_design({ id: '1:1' }));
+  assert.equal(full.totals.textNodes, 1);
+  assert.equal(full.complete, true);
+  const opaque = plain(await r.handlers.scan_design({ id: '1:1', expandInstances: false }));
+  assert.equal(opaque.totals.textNodes, 0);
+  assert.equal(opaque.totals.opaqueInstances, 1);
+  assert.equal(opaque.complete, false);
+});
+
 test('equivalent CSS syntaxes preserve alpha in reads and writes', () => {
   const r = runtime();
   for (const color of ['rgba(255, 0, 0, .5)', 'rgb(100% 0% 0% / 50%)', 'hsl(0 100% 50% / .5)', 'hsla(0, 100%, 50%, .5)']) {
@@ -204,8 +218,8 @@ test('agent setup detects installed clients and preserves existing JSONC and TOM
       configureAgent(agent);
       const config = parseJsonc(readFileSync(agent.configPath, 'utf8')).mcpServers['figma-rust-mcp'];
       assert.ok(config);
-      if (id === 'antigravity') assert.equal(config.serverUrl, 'http://127.0.0.1:38451/sse');
-      else assert.equal(config.url, 'http://127.0.0.1:38451/mcp');
+      if (id === 'antigravity') assert.equal(config.serverUrl, 'http://127.0.0.1:41730/sse');
+      else assert.equal(config.url, 'http://127.0.0.1:41730/mcp');
     }
 
     const cursor = agents.find(agent => agent.id === 'cursor');
@@ -215,21 +229,21 @@ test('agent setup detects installed clients and preserves existing JSONC and TOM
     const cursorConfig = parseJsonc(cursorText);
     assert.match(cursorText, /keep this note/);
     assert.equal(cursorConfig.mcpServers.other.url, 'http://example.test');
-    assert.equal(cursorConfig.mcpServers['figma-rust-mcp'].url, 'http://127.0.0.1:38451/mcp');
+    assert.equal(cursorConfig.mcpServers['figma-rust-mcp'].url, 'http://127.0.0.1:41730/mcp');
     assert.equal(configureAgent(cursor), false);
 
     const zed = agents.find(agent => agent.id === 'zed');
     writeFileSync(zed.configPath, '{\n  "theme": "One Dark",\n}\n');
     configureAgent(zed);
     assert.equal(parseJsonc(readFileSync(zed.configPath, 'utf8')).theme, 'One Dark');
-    assert.equal(parseJsonc(readFileSync(zed.configPath, 'utf8')).context_servers['figma-rust-mcp'].url, 'http://127.0.0.1:38451/mcp');
+    assert.equal(parseJsonc(readFileSync(zed.configPath, 'utf8')).context_servers['figma-rust-mcp'].url, 'http://127.0.0.1:41730/mcp');
 
     const codex = agents.find(agent => agent.id === 'codex');
     writeFileSync(codex.configPath, '[mcp_servers.other]\nurl = "http://other.test"\n');
     configureAgent(codex);
     const codexText = readFileSync(codex.configPath, 'utf8');
     assert.match(codexText, /\[mcp_servers\.other\]/);
-    assert.match(codexText, /\[mcp_servers\.figma-rust-mcp\]\nurl = "http:\/\/127\.0\.0\.1:38451\/mcp"/);
+    assert.match(codexText, /\[mcp_servers\.figma-rust-mcp\]\nurl = "http:\/\/127\.0\.0\.1:41730\/mcp"/);
     assert.equal(configureAgent(codex), false);
   } finally {
     rmSync(home, { recursive: true, force: true });
@@ -525,10 +539,10 @@ test('old UI socket callbacks cannot clear or dispatch through a replacement soc
     close() {} send() {}
   }
   const r = vm.createContext({
-    ws: null, wsConnected: false, sessionId: null, fileName: 'File', documentId: 'doc', BRIDGE: 'http://localhost:38451',
+    ws: null, wsConnected: false, sessionId: null, fileName: 'File', documentId: 'doc', BRIDGE: 'http://localhost:41730',
     WebSocket: Socket, setInterval: () => 1, clearInterval: () => {}, setTimeout: () => 1, clearTimeout: () => {},
     sendRuntimeCapabilities: () => {}, consecutiveErrors: 0, everConnected: false, retryTimer: null, polling: true,
-    setStatus: () => {}, log: () => {}, currentPort: 38451, READ_OPS: [],
+    setStatus: () => {}, log: () => {}, currentPort: 41730, READ_OPS: [],
     startLongPoll: () => assert.fail('stale socket started poll'), dispatchToMain: req => dispatched.push(req),
   });
   vm.runInContext(source, r);