figma-rust-mcp 3.0.5 → 3.2.1

package/README.md

@@ -21,69 +21,94 @@ Enables AI agents (Google Antigravity, Claude Code, Cursor, Windsurf, VS Code, Z
 
 ---
 
-## 🏛️ Architecture
+## 🏛️ Architecture & Zero-Touch Connection
 
 ```text
 ┌────────────────────────────────────────────────────────────────────────┐
-│                      Terminal / Standalone Service                     │
+│                      Terminal / Background Service                     │
 │                       figma-mcp (Pure Rust Engine)                     │
 │  • MCP SSE Transport (/sse, /message) & Direct HTTP (/mcp)             │
+│  • 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)          │
 │  • Design Token Transformer (CSS, Tailwind, TypeScript, W3C DTCG)      │
 │  • Sandboxed JS Runtime (Boa ECMAScript Engine)                        │
 │  • Binary MessagePack & Progressive Subtree Chunk Receiver             │
 └───────────────▲────────────────────────────────────────▲───────────────┘
-                │ (ws://127.0.0.1:38451)                 │ (http://127.0.0.1:38451/sse)
-                │ (MessagePack / JSON IPC)               │
+                │ (ws://127.0.0.1:38451/ws)              │ (http://127.0.0.1:38451/sse)
+                │ (Dynamic Code Streaming & Hot-Reload)  │ (JSON-RPC 2.0 / SSE)
       ┌─────────┴─────────┐                    ┌─────────┴─────────┐
       │   Figma Desktop   │                    │ AI Assistant(s)   │
-      │ (Plugin Bridge)   │                    │ Google Antigravity│
+      │ (Thin Loader)     │                    │ Google Antigravity│
       │                   │                    │ Cursor / Windsurf │
-      │ • Canvas Tracker  │                    │ Claude Code / Zed │
-      │ • SVG/PNG Render  │                    └───────────────────┘
+      │ • Zero-Touch Sync │                    │ Claude Code / Zed │
+      │ • Live Hot-Reload │                    └───────────────────┘
+      │ • SVG/PNG Render  │
       └───────────────────┘
 ```
 
+### 🔌 How the Zero-Touch Connection Works:
+1. **Permanent Thin Loader**: You only import the Figma plugin **once** (`~/.figma-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**.
+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.
+
 ---
 
 ## 🚀 Quick Start
 
-### 1. One-Line Launch with NPX (No Rust toolchain needed)
-
-Launch `figma-rust-mcp` on macOS, Linux, or Windows with zero manual setup:
+### 1. One-Line Setup & Launch with NPX (No Rust toolchain needed)
 
 ```bash
+# Launch interactive MCP server
 npx figma-rust-mcp
 ```
+*(Automatically downloads precompiled native binary for macOS Apple Silicon/Intel, Linux, or Windows).*
+
+---
+
+### 2. Install the Figma Plugin (Permanent One-Time Setup)
+
+Create the permanent Thin Loader folder in your home directory:
+
+```bash
+npx figma-rust-mcp --setup-plugin
+```
 
-This automatically downloads the prebuilt native binary for your OS and architecture and starts the server.
+1. Open **Figma Desktop**.
+2. Go to **Plugins** → **Development** → **Import plugin from manifest...**
+3. Select `~/.figma-mcp/plugin/manifest.json` (or `plugin/manifest.json` inside this repository).
+4. Run the plugin: **Plugins** → **Development** → **Figma MCP Bridge**.
+5. **Done!** Future updates to `figma-rust-mcp` will stream to Figma automatically.
 
 ---
 
-### 2. Auto-Start as Background Service (Recommended for SSE)
+### 3. Run as Auto-Start Background Service (Recommended)
 
-To make `figma-rust-mcp` start automatically upon OS login and run in the background across all your AI IDEs:
+Run `figma-rust-mcp` seamlessly in the background across all your AI editors without keeping a terminal open:
 
 ```bash
-# Install and start auto-start background service (macOS LaunchAgent, Linux systemd, Windows Task Scheduler)
+# Install and start background service (macOS LaunchAgent, Linux systemd, Windows Task)
 npx figma-rust-mcp --install-service
 
-# Update/Upgrade to the latest version and hot-reload background service
-npx -y figma-rust-mcp@latest --install-service
-
-# Check service status
+# Check live background service status & bridge health
 npx figma-rust-mcp --service-status
 
-# Uninstall background service
+# One-command upgrade to latest version & auto-restart background service
+npx figma-rust-mcp --upgrade
+
+# Add convenient 'figma-mcp' alias to your shell profile (~/.zshrc, ~/.bashrc)
+npx figma-rust-mcp --alias
+
+# Stop and remove background service
 npx figma-rust-mcp --uninstall-service
 ```
 
 ---
 
-### 3. Build from Source (Rust)
+### 4. Build from Source (Optional)
 
-Prerequisites: [Rust toolchain](https://rustup.rs/) (`cargo >= 1.80`).
+If you prefer building directly with the [Rust toolchain](https://rustup.rs/) (`cargo >= 1.80`):
 
 ```bash
 git clone https://github.com/BuiHung1612/figma-mcp.git
@@ -94,16 +119,6 @@ cargo build --release
 
 ---
 
-### 4. Install the Figma Plugin
-
-1. Open **Figma Desktop**.
-2. Go to **Plugins** → **Development** → **Import plugin from manifest...**
-3. Select `plugin/manifest.json` from this repository.
-4. Run the plugin (**Plugins** → **Development** → **Figma MCP Bridge**).
-5. The plugin UI will display a green dot (**Connected**).
-
----
-
 ### 5. Configure Your MCP Client
 
 #### Google Antigravity (SSE Transport - Recommended)

package/bin/figma-mcp.js

@@ -371,13 +371,151 @@ function isServiceInstalled() {
   return false;
 }
 
+function setupPlugin(customDir) {
+  const pluginDir = customDir || path.join(os.homedir(), '.figma-mcp', 'plugin');
+  const sourcePluginDir = path.resolve(__dirname, '../plugin');
+
+  fs.mkdirSync(pluginDir, { recursive: true });
+
+  const files = ['manifest.json', 'code.js', 'ui.html', 'icon16.png', 'icon32.png'];
+  for (const f of files) {
+    const src = path.join(sourcePluginDir, f);
+    const dest = path.join(pluginDir, f);
+    if (fs.existsSync(src)) {
+      fs.copyFileSync(src, dest);
+    }
+  }
+
+  const manifestPath = path.join(pluginDir, 'manifest.json');
+  console.log(`\n\x1b[32m✓ Figma MCP Dynamic Thin Plugin installed to:\x1b[0m`);
+  console.log(`  \x1b[36m${manifestPath}\x1b[0m\n`);
+  console.log(`\x1b[1mTo connect Figma (Do this ONCE forever):\x1b[0m`);
+  console.log(`  1. Open Figma Desktop`);
+  console.log(`  2. Go to Plugins → Development → Import plugin from manifest...`);
+  console.log(`  3. Select: ${manifestPath}`);
+  console.log(`  4. Done! All future updates load dynamically from figma-mcp without file re-imports.\n`);
+  return manifestPath;
+}
+
+function isNewer(latest, current) {
+  const pLatest = latest.split('.').map(n => parseInt(n, 10) || 0);
+  const pCurrent = current.split('.').map(n => parseInt(n, 10) || 0);
+  for (let i = 0; i < 3; i++) {
+    if ((pLatest[i] || 0) > (pCurrent[i] || 0)) return true;
+    if ((pLatest[i] || 0) < (pCurrent[i] || 0)) return false;
+  }
+  return false;
+}
+
+function checkForUpdatesAsync() {
+  const updateStateFile = path.join(os.homedir(), '.figma-mcp', 'update-check.json');
+  try {
+    if (fs.existsSync(updateStateFile)) {
+      const state = JSON.parse(fs.readFileSync(updateStateFile, 'utf8'));
+      const now = Date.now();
+      if (state.lastChecked && (now - state.lastChecked < 6 * 3600 * 1000)) {
+        if (state.latestVersion && isNewer(state.latestVersion, pkgVersion)) {
+          process.stderr.write(`\n\x1b[36m⚡ Update available: v${pkgVersion} → v${state.latestVersion} (Run: npx figma-rust-mcp --upgrade)\x1b[0m\n\n`);
+        }
+        return;
+      }
+    }
+  } catch (_) {}
+
+  const req = https.get('https://registry.npmjs.org/figma-rust-mcp/latest', {
+    headers: { 'User-Agent': 'figma-mcp-updater' },
+    timeout: 2000
+  }, (res) => {
+    let data = '';
+    res.on('data', chunk => { data += chunk; });
+    res.on('end', () => {
+      try {
+        if (res.statusCode === 200) {
+          const json = JSON.parse(data);
+          const latest = json.version;
+          fs.mkdirSync(path.join(os.homedir(), '.figma-mcp'), { recursive: true });
+          fs.writeFileSync(updateStateFile, JSON.stringify({
+            lastChecked: Date.now(),
+            latestVersion: latest
+          }, null, 2));
+          if (latest && isNewer(latest, pkgVersion)) {
+            process.stderr.write(`\n\x1b[36m⚡ Update available: v${pkgVersion} → v${latest}\x1b[0m\n\x1b[36m   Run: npx figma-rust-mcp --upgrade\x1b[0m\n\n`);
+          }
+        }
+      } catch (_) {}
+    });
+  });
+  req.on('error', () => {});
+  req.on('timeout', () => req.destroy());
+}
+
+async function upgrade() {
+  console.log('\x1b[36m[figma-mcp]\x1b[0m Checking for updates and upgrading figma-rust-mcp...');
+  try {
+    execSync('npm install -g figma-rust-mcp@latest', { stdio: 'inherit' });
+    console.log('\x1b[32m✓ Upgraded figma-rust-mcp to latest version.\x1b[0m');
+    setupPlugin();
+    if (isServiceInstalled()) {
+      console.log('\x1b[36mUpdating background service binary...\x1b[0m');
+      const binPath = await findOrDownloadBinary();
+      await installService(binPath);
+    }
+  } catch (err) {
+    console.log('\x1b[33mTip: Run directly with latest version:\x1b[0m\n  npx -y figma-rust-mcp@latest\n');
+  }
+}
+
+function setupAlias() {
+  const platform = process.platform;
+  if (platform === 'win32') {
+    console.log('\x1b[33mOn Windows, install globally for direct command access:\x1b[0m\n  npm install -g figma-rust-mcp\n');
+    return;
+  }
+
+  const shellRc = process.env.SHELL && process.env.SHELL.includes('zsh')
+    ? path.join(os.homedir(), '.zshrc')
+    : path.join(os.homedir(), '.bashrc');
+
+  const aliasLine = "alias figma-mcp='npx figma-rust-mcp'";
+  try {
+    let content = fs.existsSync(shellRc) ? fs.readFileSync(shellRc, 'utf8') : '';
+    if (!content.includes('alias figma-mcp=')) {
+      fs.appendFileSync(shellRc, `\n# Figma MCP alias\n${aliasLine}\n`);
+      console.log(`\x1b[32m✓ Added alias to ${shellRc}:\x1b[0m`);
+      console.log(`  ${aliasLine}`);
+      console.log(`\nRun \x1b[36msource ${shellRc}\x1b[0m to start using \x1b[1mfigma-mcp\x1b[0m command directly!`);
+    } else {
+      console.log(`\x1b[32m✓ Alias already exists in ${shellRc}\x1b[0m`);
+    }
+  } catch (err) {
+    console.error(`Failed to configure alias: ${err.message}`);
+  }
+}
+
 // ─── MAIN ─────────────────────────────────────────────────────────────────────
 
 async function main() {
   const args = process.argv.slice(2);
 
+  if (args.includes('--upgrade') || args.includes('--update')) {
+    await upgrade();
+    return;
+  }
+
+  if (args.includes('--alias')) {
+    setupAlias();
+    return;
+  }
+
+  if (args.includes('--setup-plugin') || args.includes('--export-plugin') || args.includes('--setup')) {
+    const customDir = args.find(a => !a.startsWith('-') && a !== '--setup-plugin' && a !== '--export-plugin' && a !== '--setup');
+    setupPlugin(customDir);
+    return;
+  }
+
   if (args.includes('--install-service')) {
     try {
+      setupPlugin();
       const binPath = await findOrDownloadBinary();
       await installService(binPath);
     } catch (err) {
@@ -409,6 +547,9 @@ async function main() {
     return;
   }
 
+  // Non-blocking auto update check
+  checkForUpdatesAsync();
+
   try {
     const binPath = await findOrDownloadBinary();
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-rust-mcp",
-  "version": "3.0.5",
+  "version": "3.2.1",
   "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",