figma-rust-mcp 3.2.5 → 3.2.8

package/README.md

@@ -28,7 +28,7 @@ Enables AI agents (Google Antigravity, Claude Code, Cursor, Windsurf, VS Code, Z
 ┌────────────────────────────────────────────────────────────────────────┐
 │                      Terminal / Background Service                     │
 │                       figma-mcp (Pure Rust Engine)                     │
-│  • MCP SSE Transport (/sse, /message) & Direct HTTP (/mcp)             │
+│  • MCP Streamable HTTP (/mcp) & legacy SSE (/sse, /message)             │
 │  • Dynamic Runtime Server (/plugin/code.js, /plugin/ui.html)           │
 │  • In-Memory Fast Index (<1ms Lookups & Incremental Diffs)             │
 │  • Design-to-Code Compiler (React/Tailwind, Vue, RN, SwiftUI)          │
@@ -36,8 +36,8 @@ 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/sse)
-                │ (Dynamic Code Streaming & Hot-Reload)  │ (JSON-RPC 2.0 / SSE)
+                │ (ws://127.0.0.1:38451/ws)              │ (http://127.0.0.1:38451/mcp)
+                │ (Dynamic Code Streaming & Hot-Reload)  │ (JSON-RPC 2.0 / Streamable HTTP)
       ┌─────────┴─────────┐                    ┌─────────┴─────────┐
       │   Figma Desktop   │                    │ AI Assistant(s)   │
       │ (Thin Loader)     │                    │ Google Antigravity│
@@ -107,6 +107,25 @@ npx -y figma-rust-mcp@latest --uninstall-service
 
 ---
 
+### Windows background mode
+
+Double-clicking `figma-mcp.exe` starts the server in a detached process and closes
+its launcher console. From PowerShell or Command Prompt, use:
+
+```powershell
+.\figma-mcp.exe --background
+```
+
+The server keeps running after the terminal closes. Logs are appended to
+`%LOCALAPPDATA%\figma-mcp\logs\server.log`. Use `--server` for the foreground
+terminal dashboard, or `--stdio` for an MCP client subprocess.
+
+`--install-service` through the npm runner configures background startup at login.
+Re-run the installation command to update an existing Windows task. Removing the
+task disables future login startup; stop an already detached server through Task
+Manager (`figma-mcp.exe`). The launcher console may appear briefly when opening
+the executable; the server itself does not retain a console window.
+
 ### 4. Build from Source (Optional)
 
 If you prefer building directly with the [Rust toolchain](https://rustup.rs/) (`cargo >= 1.80`):
@@ -122,7 +141,22 @@ cargo build --release
 
 ### 5. Configure Your MCP Client
 
-#### Google Antigravity (SSE Transport - Recommended)
+#### Codex and clients using Streamable HTTP (Recommended)
+
+Use the `/mcp` endpoint. It accepts `POST` JSON-RPC requests directly:
+
+```toml
+[mcp_servers.figma-mcp]
+url = "http://127.0.0.1:38451/mcp"
+```
+
+For Codex CLI, the equivalent command is:
+
+```bash
+codex mcp add figma-mcp --url http://127.0.0.1:38451/mcp
+```
+
+#### Google Antigravity (SSE Transport)
 Add to your `~/.gemini/config/mcp_config.json` or project `.agents/mcp_config.json`:
 ```json
 {
@@ -136,7 +170,7 @@ Add to your `~/.gemini/config/mcp_config.json` or project `.agents/mcp_config.js
 
 #### Claude Code / Cursor / Windsurf / VS Code / Zed
 
-**Option A: SSE Transport (Recommended for background service)**
+**Option A: SSE Transport (for clients that require SSE)**
 ```json
 {
   "mcpServers": {
@@ -147,6 +181,11 @@ Add to your `~/.gemini/config/mcp_config.json` or project `.agents/mcp_config.js
 }
 ```
 
+The SSE transport uses `GET /sse` to open the event stream and `POST /message`
+(or `/messages`) for JSON-RPC messages. Do not configure a Streamable HTTP
+client such as Codex against `/sse`: that endpoint does not accept `POST`, so
+the initialize request will return HTTP 405. Use `/mcp` instead.
+
 **Option B: Stdio Subprocess (via NPX)**
 ```json
 {
@@ -159,6 +198,18 @@ Add to your `~/.gemini/config/mcp_config.json` or project `.agents/mcp_config.js
 }
 ```
 
+### 6. Diagnose a stale Figma runtime
+
+Check the runtime bundle currently served to Figma Desktop:
+
+```bash
+curl http://127.0.0.1:38451/plugin/version
+```
+
+The response includes `version` and `runtimeHash`. If the hash changes after an
+upgrade, the dynamic plugin runtime is refreshed automatically. Restart the
+Figma plugin only if the reported hash does not change.
+
 ---
 
 ## 🛠️ MCP Tools Reference
@@ -183,6 +234,27 @@ Exports Figma Variables (Design Tokens), Color Styles, Typography Styles, and El
 - **`outputPath`**: Writes directly to disk (e.g. `src/styles/tokens.css` or `tailwind.config.js`).
 - **`collection`** / **`mode`** / **`prefix`**: Optional filters and naming prefixes.
 
+Token exports use schema v2 and preserve full paint/effect stacks, alpha, gradient
+transforms, collection modes and raw alias values. CSS, Tailwind, TypeScript and
+JSON share one normalized model. The `w3c` output uses DTCG 2025.10 color,
+dimension, gradient-stop and shadow values, with Figma-specific geometry and
+unsupported values retained in `$extensions`.
+
+Linear gradients on a node are projected using its actual dimensions. A diagonal
+gradient style has no target aspect ratio: use `get_css` on its consuming node.
+Radial/angular/diamond paints, unsupported blend modes and progressive blurs
+retain their raw data and report diagnostics recommending SVG instead of emitting
+approximate CSS. Unknown modes, unresolved aliases and sanitized name collisions
+fail explicitly. CSS exports include non-default modes under `data-theme`
+selectors; opacity/font-weight variables stay unitless.
+
+The plugin UI badge is stamped from the build version and updated from the
+connected server handshake. Package/Cargo/tag mismatches fail the build pipeline.
+Run `npm run build:plugin` after changing plugin source, and `npm run test:tokens`
+for the token/contract/version regression suite. Existing background servers need
+a restart with the new binary to load the updated runtime.
+
+
 ### 5. `figma_get_selection`
 Token-compressed inspection of currently selected layers/frames on the Figma canvas. Returns compacted layout and typography hierarchy with **60–80% fewer tokens**.
 - **`detail`**: `"compact"` (recommended), `"minimal"`, `"full"`.

package/bin/figma-mcp.js

@@ -6,7 +6,7 @@
  * caches it locally, and executes it transparently.
  */
 
-import { spawn, execSync } from 'node:child_process';
+import { spawn, execSync, execFileSync } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import os from 'node:os';
@@ -19,7 +19,7 @@ const __dirname = path.dirname(__filename);
 
 // Read package.json version
 const pkgPath = path.resolve(__dirname, '../package.json');
-let pkgVersion = '2.9.5';
+let pkgVersion = null;
 let repoOwner = 'BuiHung1612';
 let repoName = 'figma-mcp';
 
@@ -36,6 +36,7 @@ try {
     }
   }
 } catch (_) {}
+if (!pkgVersion) throw new Error(`Cannot read package version from ${pkgPath}`);
 
 function getPlatformArch() {
   const platform = process.platform;
@@ -293,8 +294,10 @@ WantedBy=default.target
   } else if (platform === 'win32') {
     const taskName = 'FigmaMCPServer';
     // Use schtasks to create a task that runs at login
-    const cmd = `schtasks /Create /F /TN "${taskName}" /TR "${binPath}" /SC ONLOGON /RL HIGHEST`;
-    execSync(cmd, { stdio: 'inherit' });
+    // The native launcher detaches the server and redirects output to a log file.
+    const taskCommand = `"${binPath}" --background`;
+    execFileSync('schtasks', ['/Create', '/F', '/TN', taskName,
+      '/TR', taskCommand, '/SC', 'ONLOGON'], { stdio: 'inherit', windowsHide: true });
 
     // Start it immediately too
     try { execSync(`schtasks /Run /TN "${taskName}"`, { stdio: 'pipe' }); } catch (_) {}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-rust-mcp",
-  "version": "3.2.5",
+  "version": "3.2.8",
   "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-mcp",
   "type": "module",
@@ -16,9 +16,10 @@
     "LICENSE"
   ],
   "scripts": {
-    "build": "cargo build --release",
+    "build": "npm run build:plugin && cargo build --release",
     "build:plugin": "node scripts/build-plugin.js",
     "test": "./scripts/test-rust-mcp.sh",
+    "test:tokens": "node --test scripts/test-plugin-tokens.mjs && cargo test",
     "dev": "cargo run"
   },
   "engines": {

package/plugin/code.js

@@ -1,4 +1,4 @@
-// ─── FIGMA MCP BRIDGE — DYNAMIC THIN LOADER (v3.0.0) ───────────────────────────
+// ─── FIGMA MCP BRIDGE — DYNAMIC THIN LOADER ───────────────────────────
 // This file is a permanent micro-stub. You never need to reinstall or edit this file.
 // The actual runtime is loaded dynamically from the local figma-mcp Rust engine.
 

package/scripts/build-plugin.js

@@ -1,13 +1,19 @@
-// Build script — concatenate src/plugin/*.js into plugin/code.js
+// Build script — concatenate plugin-src/*.js into plugin-runtime/code.js
 // No module system used: files are plain JS sharing a single scope when concatenated.
 import { readFileSync, writeFileSync } from "fs";
 
 const { version } = JSON.parse(readFileSync("package.json", "utf8"));
+const cargoVersion = readFileSync("Cargo.toml", "utf8").match(/^version\s*=\s*"([^"]+)"/m)?.[1];
+if (version !== cargoVersion) throw new Error(`Version mismatch: package.json ${version}, Cargo.toml ${cargoVersion}`);
+if (process.env.GITHUB_REF_TYPE === "tag" && process.env.GITHUB_REF_NAME !== `v${version}`) {
+  throw new Error(`Release tag ${process.env.GITHUB_REF_NAME} does not match build version v${version}`);
+}
 
 const files = [
   "plugin-src/utils.js",
   "plugin-src/svg-path-helpers.js",
   "plugin-src/paint-and-effects.js",
+  "plugin-src/token-helpers.js",
   "plugin-src/read-helpers.js",
   "plugin-src/handlers-write.js",
   "plugin-src/handlers-library.js",
@@ -18,10 +24,9 @@ const files = [
   "plugin-src/main.js",
 ];
 
-const banner = `// figma-mcp — Figma Plugin main thread v1.2.1
+const banner = `// figma-mcp — Figma Plugin main thread v${version}
 // Handles both WRITE (draw UI) and READ (extract design) operations.
 // AUTO-GENERATED by scripts/build-plugin.js — edit plugin-src/*.js instead
-// Generated: ${new Date().toISOString()}
 `;
 
 const parts = files.map(f => {
@@ -30,5 +35,17 @@ const parts = files.map(f => {
 });
 
 const output = (banner + parts.join("\n")).replace(/\{\{PLUGIN_VERSION\}\}/g, version);
-writeFileSync("plugin-runtime/code.js", output);
+
+const uiPath = "plugin-runtime/ui.html";
+const ui = readFileSync(uiPath, "utf8").replace(/(<span class="brand-ver"[^>]*>)[^<]*(<\/span>)/,
+  `$1v${version}$2`);
+if (!ui.includes(`id="runtime-version">v${version}</span>`)) throw new Error("Missing runtime version badge");
+if (process.argv.includes('--check')) {
+  if (readFileSync("plugin-runtime/code.js", "utf8") !== output || readFileSync(uiPath, "utf8") !== ui) {
+    throw new Error("Plugin bundle is stale; run npm run build:plugin");
+  }
+} else {
+  writeFileSync("plugin-runtime/code.js", output);
+  writeFileSync(uiPath, ui);
+}
 console.log(`✓ plugin-runtime/code.js written (${output.length} chars, ${output.split("\n").length} lines)`);

package/scripts/test-plugin-tokens.mjs

@@ -0,0 +1,147 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import vm from 'node:vm';
+import { spawnSync } from 'node:child_process';
+
+function runtime(figma = {}) {
+  const context = vm.createContext({ figma, handlers: {}, console, setTimeout, Map, Set, Uint8Array });
+  for (const file of ['utils', 'token-helpers', 'handlers-read-detail', 'handlers-read', 'handlers-tokens', 'handlers-write-ops']) {
+    vm.runInContext(readFileSync(`plugin-src/${file}.js`, 'utf8'), context, { filename: file });
+  }
+  return context;
+}
+const plain = value => JSON.parse(JSON.stringify(value));
+const gradient = (transform = [[1, 0, 0], [0, 1, 0]]) => ({
+  type: 'GRADIENT_LINEAR', gradientTransform: transform, opacity: .5,
+  gradientStops: [{ position: 0, color: { r: 1, g: 0, b: 0, a: .5 } }, { position: 1, color: { r: 0, g: 0, b: 1, a: 1 } }],
+});
+const shadow = type => ({ type, color: { r: 0, g: 0, b: 0, a: .125 }, offset: { x: -1, y: 3 }, radius: 6, spread: -2, visible: true });
+
+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)']) {
+    assert.deepEqual(plain(r.parseColorValue(color)), { r: 1, g: 0, b: 0, a: .5 });
+    assert.equal(r.hexToRgbA(color).a, .5);
+    assert.equal(r.solidFill(color)[0].opacity, .5);
+  }
+  assert.equal(r.parseColorValue('#f008').a, 136 / 255);
+  assert.equal(r.parseColorValue('transparent').a, 0);
+  assert.equal(r.colorToCss({ r: 0, g: 0, b: 0, a: .9999 }), 'rgba(0, 0, 0, 0.9999)');
+  assert.throws(() => r.parseColorValue('rgba(garbage)'), /Invalid/);
+});
+
+test('gradient projection includes translations, aspect ratio, stop and paint alpha', () => {
+  const r = runtime();
+  const p = r.serializePaint(gradient());
+  assert.deepEqual(plain(p.gradientTransform), [[1, 0, 0], [0, 1, 0]]);
+  assert.match(r.paintToCss(p, 200, 100), /^linear-gradient\(90deg, rgba\(255, 0, 0, 0.25\) 0%, rgba\(0, 0, 255, 0.5\) 100%\)$/);
+  const diagonal = r.paintToCss(r.serializePaint(gradient([[1, 1, 0], [0, 1, 0]])), 200, 100);
+  assert.match(diagonal, /153\.434948/);
+  assert.match(diagonal, /50%/);
+  const shifted = r.paintToCss(r.serializePaint(gradient([[.5, 0, .25], [0, 1, 0]])), 200, 100);
+  assert.match(shifted, /-50%/);
+  assert.match(shifted, /150%/);
+  assert.throws(() => r.paintToCss({ ...p, type: 'GRADIENT_DIAMOND' }, 100, 100), /SVG/);
+});
+
+test('get_css uses the numeric paint, never hex slicing a serialized rgba', async () => {
+  const node = { id: '1:2', name: 'alpha', type: 'RECTANGLE', x: 0, y: 0, width: 200, height: 100,
+    fills: [{ type: 'SOLID', color: { r: 1, g: 0, b: 0 }, opacity: .25 }], effects: [shadow('DROP_SHADOW'), shadow('INNER_SHADOW')] };
+  const r = runtime();
+  r.findNodeByIdAsync = async () => node;
+  const result = await r.handlers.get_css({ id: node.id });
+  assert.match(result.css, /background-color: rgba\(255, 0, 0, 0.25\);/);
+  assert.doesNotMatch(result.css, /NaN|0.0625/);
+  assert.match(result.css, /inset -1px 3px 6px -2px rgba\(0, 0, 0, 0.125\)/);
+  assert.equal(result.detail.effects.length, 2);
+});
+
+test('styles retain full paints, effects, units and disabled layers', async () => {
+  const r = runtime({
+    getLocalPaintStylesAsync: async () => [{ id: 'p', name: 'Gradient', paints: [gradient()] }],
+    getLocalTextStylesAsync: async () => [{ id: 't', name: 'Body', fontName: { family: 'Inter', style: 'Regular' }, fontSize: 16, lineHeight: { unit: 'PERCENT', value: 150 }, letterSpacing: { unit: 'PERCENT', value: 2 } }],
+    getLocalEffectStylesAsync: async () => [{ id: 's', name: 'Card', effects: [shadow('DROP_SHADOW'), shadow('INNER_SHADOW'), { type: 'LAYER_BLUR', radius: 8, visible: false }] }],
+    getLocalGridStylesAsync: async () => [],
+  });
+  const styles = await r.handlers.get_styles();
+  assert.equal(styles.schemaVersion, 2);
+  assert.equal(styles.paintStyles[0].paints[0].gradientStops[0].rgba.a, .5);
+  assert.equal(styles.effectStyles[0].effects.length, 3);
+  assert.equal(styles.textStyles[0].lineHeightUnit, 'PERCENT');
+  assert.equal(r.effectsToCss(styles.effectStyles[0].effects).filter, '');
+});
+
+test('aliases use mode names across collections and retain false/zero values', async () => {
+  const cols = [
+    { id: 'semantic', name: 'Semantic', defaultModeId: 's-light', modes: [{ modeId: 's-light', name: 'Light' }, { modeId: 's-dark', name: 'Dark' }], variableIds: ['alias', 'zero'] },
+    { id: 'primitive', name: 'Primitive', defaultModeId: 'p-light', modes: [{ modeId: 'p-light', name: 'Light' }, { modeId: 'p-dark', name: 'Dark' }], variableIds: ['base'] },
+  ];
+  const variables = [
+    { id: 'alias', name: 'semantic', variableCollectionId: 'semantic', resolvedType: 'BOOLEAN', valuesByMode: { 's-light': { type: 'VARIABLE_ALIAS', id: 'base' }, 's-dark': { type: 'VARIABLE_ALIAS', id: 'base' } } },
+    { id: 'zero', name: 'zero', variableCollectionId: 'semantic', resolvedType: 'FLOAT', valuesByMode: { 's-light': 0, 's-dark': 1 } },
+    { id: 'base', name: 'base', variableCollectionId: 'primitive', resolvedType: 'BOOLEAN', valuesByMode: { 'p-light': false, 'p-dark': true } },
+  ];
+  const r = runtime({ variables: {
+    getLocalVariableCollectionsAsync: async () => cols, getLocalVariablesAsync: async () => variables,
+    getVariableByIdAsync: async id => variables.find(v => v.id === id),
+    getVariableCollectionByIdAsync: async id => cols.find(c => c.id === id),
+  } });
+  const result = await r.handlers.get_variables();
+  const alias = result.collections[0].variables[0];
+  assert.equal(alias.values['s-light'].resolvedValue, false);
+  assert.equal(alias.values['s-dark'].resolvedValue, true);
+  assert.equal(result.resolvedTokens.semantic, false);
+  assert.equal(result.resolvedTokens.zero, 0);
+  assert.equal(result.collections[0].defaultModeId, 's-light');
+  assert.deepEqual(plain(result.diagnostics), []);
+  const consumer = { resolvedVariableModes: { semantic: 's-dark', primitive: 'p-light' } };
+  variables[0].resolveForConsumer = () => ({ value: false, resolvedType: 'BOOLEAN' });
+  assert.equal((await r.resolveVariableValueAsync(variables[0], consumer)).resolvedValue, false);
+});
+
+test('export_node validates format and works through batch and aliases', async () => {
+  const r = runtime();
+  r.handlers.export_svg = async () => ({ svg: '<svg/>' });
+  r.handlers.export_image = async params => ({ format: params.format });
+  assert.equal((await r.resolveOperationHandler('exportNode')({ format: 'svg' })).svg, '<svg/>');
+  assert.equal((await r.handlers.export_node({ format: 'jpeg' })).format, 'JPG');
+  const batch = await r.handlers.batch({ operations: [{ operation: 'export_node', params: { format: 'SVG' } }, { operation: 'export_node', params: { format: 'bad' } }] });
+  assert.equal(batch.succeeded, 1);
+  assert.match(batch.results[1].error, /supports PNG/);
+});
+
+test('multiple paints preserve top-first ordering and node opacity stays separate', () => {
+  const r = runtime();
+  const paints = [{ type: 'SOLID', color: { r: 1, g: 0, b: 0 }, opacity: .5 }, { type: 'SOLID', color: { r: 0, g: 0, b: 1 }, opacity: 1 }].map(r.serializePaint);
+  const css = r.paintsToCss(paints, 200, 100);
+  assert.match(css.value, /^linear-gradient\(rgba\(255, 0, 0, 0.5\)/);
+  assert.match(css.value, /linear-gradient\(#0000ff, #0000ff\)$/);
+});
+
+test('UI badge uses release version initially and follows the server on reconnect', () => {
+  const pkg = JSON.parse(readFileSync('package.json', 'utf8'));
+  const html = readFileSync('plugin-runtime/ui.html', 'utf8');
+  assert.ok(html.includes(`id="runtime-version">v${pkg.version}</span>`));
+  const start = html.indexOf('    function updateRuntimeVersion(');
+  const end = html.indexOf('    var runtimeCapabilities', start);
+  const badge = {};
+  const context = vm.createContext({ document: { getElementById: () => badge } });
+  vm.runInContext(html.slice(start, end), context);
+  context.updateRuntimeVersion('3.2.7');
+  assert.equal(badge.textContent, 'v3.2.7');
+  context.updateRuntimeVersion('3.3.0');
+  assert.equal(badge.textContent, 'v3.3.0');
+  assert.ok(html.includes('updateRuntimeVersion(serverVer)'));
+  assert.ok(html.includes('type: "runtime-ready"'));
+});
+
+test('build rejects wrong release tags and checked-in bundle matches source', () => {
+  const check = spawnSync(process.execPath, ['scripts/build-plugin.js', '--check'], { encoding: 'utf8' });
+  assert.equal(check.status, 0, check.stderr);
+  const rejected = spawnSync(process.execPath, ['scripts/build-plugin.js'], {
+    encoding: 'utf8', env: { ...process.env, GITHUB_REF_TYPE: 'tag', GITHUB_REF_NAME: 'v0.0.0-invalid' },
+  });
+  assert.notEqual(rejected.status, 0);
+  assert.match(rejected.stderr, /does not match build version/);
+});

package/scripts/test-rust-mcp.sh

@@ -26,8 +26,8 @@ OUTPUT=$(echo "$INPUT" | $BIN_PATH --port 38499 2>/dev/null)
 echo "$OUTPUT" | head -n 4
 
 # Verify tool registration in JSON-RPC output
-echo "--- Test 3: Verify Tool Registrations (12 tools) ---"
-for TOOL in figma_status figma_get_selection figma_inspect_node figma_to_code figma_get_tokens figma_export_asset figma_export_assets figma_index figma_read figma_write figma_rules figma_docs; do
+echo "--- Test 3: Verify Tool Registrations (15 tools) ---"
+for TOOL in figma_status figma_get_selection figma_inspect_node figma_to_code figma_get_tokens figma_export_asset figma_export_assets figma_index figma_read figma_write figma_rules figma_docs figma_match_components figma_prepare_design figma_verify_ui; do
   echo "$OUTPUT" | grep -q "\"name\":\"$TOOL\"" && echo "✓ $TOOL registered"
 done