figma-console-mcp 0.1.0

package/figma-desktop-bridge/README.md

@@ -0,0 +1,232 @@
+# Figma Desktop Bridge
+
+A Figma plugin that bridges the Variables API and Component descriptions to MCP (Model Context Protocol) clients without requiring an Enterprise plan.
+
+## Overview
+
+This plugin enables AI assistants like Claude Code and Claude Desktop to access your Figma variables AND component descriptions through the MCP protocol. It bypasses both Figma's plugin sandbox restrictions and the REST API's component description bug.
+
+## Architecture
+
+**For Variables (pre-loaded):**
+```
+Figma Plugin Worker → postMessage → Plugin UI Iframe → window object → Puppeteer → MCP Server
+```
+
+**For Components (on-demand):**
+```
+MCP Request → Plugin UI → postMessage → Plugin Worker → figma.getNodeByIdAsync() → Returns with description
+```
+
+**Key Features:**
+- ✅ No Enterprise plan required for variables
+- ✅ Access all local variables and collections
+- ✅ Reliable component descriptions (bypasses REST API bug)
+- ✅ Supports multiple variable modes
+- ✅ On-demand component data retrieval
+- ✅ Persistent connection (stays open until closed)
+- ✅ Clean, minimal UI
+- ✅ Real-time data updates
+
+## Installation
+
+### Quick Install (Recommended)
+
+1. **Open Figma Desktop**
+2. **Go to Plugins → Development → Import plugin from manifest...**
+3. **Navigate to:** `/path/to/figma-console-mcp/figma-desktop-bridge/manifest.json`
+4. **Click "Open"**
+
+The plugin will appear in your Development plugins list as "Figma Desktop Bridge".
+
+### Manual Installation
+
+Alternatively, you can install from the plugin directory:
+
+```bash
+# From the figma-console-mcp directory
+cd figma-desktop-bridge
+
+# Figma will use these files:
+# - manifest.json (plugin configuration)
+# - code.js (plugin worker logic)
+# - ui.html (plugin UI interface)
+```
+
+## Usage
+
+### Running the Plugin
+
+1. **Open your Figma file** with variables and/or components
+2. **Run the plugin:** Right-click → Plugins → Development → Figma Desktop Bridge
+3. **Wait for confirmation:** Plugin UI will show "✓ Desktop Bridge active"
+
+The plugin will:
+- Fetch all local variables and collections on startup
+- Display counts in the UI (e.g., "Variables: 404 in 2 collections")
+- Store variables in `window.__figmaVariablesData`
+- Provide on-demand component data via `window.requestComponentData(nodeId)`
+- Keep running until manually closed
+
+### Accessing Data via MCP
+
+Once the plugin is running, MCP clients can access both variables and components:
+
+**Variables (pre-loaded):**
+```typescript
+// From Claude Code or Claude Desktop
+figma_get_variables({
+  format: "summary"  // or "filtered" or "full"
+})
+```
+
+**Components (on-demand):**
+```typescript
+// Request component with description
+figma_get_component({
+  fileUrl: "https://figma.com/design/YOUR_FILE_KEY",
+  nodeId: "279:2861"
+})
+```
+
+**Important:** Keep the plugin running while querying. Variables are pre-loaded, but component data is fetched on-demand when requested.
+
+## How It Works
+
+### Plugin Worker (code.js)
+
+**On Startup (Variables):**
+1. Uses Figma's Variables API to fetch all local variables
+2. Formats data with full mode values
+3. Sends to UI via `postMessage`
+
+**On Request (Components):**
+1. Listens for component requests via `figma.ui.onmessage`
+2. Uses `figma.getNodeByIdAsync(nodeId)` to fetch component
+3. Extracts description, descriptionMarkdown, and metadata
+4. Sends response back to UI via `postMessage` with requestId
+
+### Plugin UI (ui.html)
+
+**Variables Flow:**
+1. Listens for `VARIABLES_DATA` message from worker
+2. Stores data on `window.__figmaVariablesData`
+3. Sets `window.__figmaVariablesReady = true`
+4. Displays status to user
+
+**Components Flow:**
+1. Exposes `window.requestComponentData(nodeId)` function
+2. Returns a Promise that resolves when worker responds
+3. Sends request to worker via `parent.postMessage()`
+4. Resolves promise when `COMPONENT_DATA` message received
+5. Includes 10-second timeout and error handling
+
+### MCP Desktop Connector
+
+**Variables (getVariablesFromPluginUI):**
+1. Connects to Figma Desktop via remote debugging port (9222)
+2. Enumerates plugin UI iframes
+3. Checks for `window.__figmaVariablesData` availability
+4. Retrieves pre-loaded variables data
+
+**Components (getComponentFromPluginUI):**
+1. Connects to same Figma Desktop instance
+2. Finds iframe with `window.requestComponentData` function
+3. Calls function with nodeId parameter
+4. Returns Promise with component data including descriptions
+
+## Troubleshooting
+
+### Plugin doesn't appear in menu
+- Make sure Figma Desktop is running (not browser)
+- Check that manifest.json path is correct
+- Try **Plugins → Development → Refresh plugin list**
+
+### "No plugin UI found with variables data" or "No plugin UI found with requestComponentData"
+- Ensure plugin is running (check for open plugin window showing "✓ Desktop Bridge active")
+- Try closing and reopening the plugin
+- Check browser console for errors
+- Verify Figma Desktop was launched with `--remote-debugging-port=9222`
+
+### Variables not updating
+- Close and reopen the plugin to refresh data
+- Use `refreshCache: true` parameter in MCP call
+- Check that you're viewing the correct Figma file
+
+### Component descriptions are empty or missing
+- **First, verify in Figma:** Check if the component actually has a description set
+- If using REST API fallback (not Desktop Bridge), descriptions may be missing due to known Figma API bug
+- Ensure the plugin is running - component data requires active plugin connection
+- Check that the nodeId is correct (format: "123:456")
+
+### Component request times out
+- Ensure plugin is running and shows "Desktop Bridge active"
+- Check that the component exists in the current file
+- Verify nodeId format is correct
+- Timeout is set to 10 seconds - complex files may take longer
+
+### Empty or outdated data
+- Plugin fetches variables on load - rerun plugin after making variable changes
+- Component data is fetched on-demand - always returns current state
+- Cache TTL is 5 minutes for variables - use `refreshCache: true` for immediate updates
+- Ensure you're in the correct file (plugin reads current file's data)
+
+## Development
+
+### File Structure
+```
+figma-desktop-bridge/
+├── manifest.json    # Plugin configuration
+├── code.js          # Plugin worker (accesses Figma API)
+├── ui.html          # Plugin UI (stores/requests data for MCP access)
+└── README.md        # This file
+```
+
+### Console Logging
+
+The plugin logs to Figma's console:
+
+**Variables (startup):**
+```
+🌉 [Desktop Bridge] Plugin loaded and ready
+🌉 [Desktop Bridge] Fetching variables...
+🌉 [Desktop Bridge] Found 404 variables in 2 collections
+🌉 [Desktop Bridge] Variables data sent to UI successfully
+🌉 [Desktop Bridge] UI iframe now has variables data accessible via window.__figmaVariablesData
+```
+
+**Components (on-demand):**
+```
+🌉 [Desktop Bridge] Fetching component: 279:2861
+🌉 [Desktop Bridge] Component data ready. Has description: true
+```
+
+**Ready state:**
+```
+🌉 [Desktop Bridge] Ready to handle component requests
+🌉 [Desktop Bridge] Plugin will stay open until manually closed
+```
+
+View logs: **Plugins → Development → Open Console** (Cmd+Option+I on Mac)
+
+## Security
+
+- Plugin requires **no network access** (allowedDomains: ["none"])
+- Data never leaves Figma Desktop
+- Uses standard Figma Plugin API (no unofficial APIs)
+- Read-only access (cannot modify variables or components)
+- Component requests are scoped to current file only
+
+## Why Desktop Bridge for Components?
+
+Figma's REST API has a known bug where component `description` and `descriptionMarkdown` fields are often missing or outdated. This is particularly problematic for:
+
+- **Local project components** (not published to team libraries)
+- **Unpublished components** in active development
+- **Team collaboration** where descriptions contain important usage guidelines
+
+The Desktop Bridge plugin bypasses this limitation by using the Figma Plugin API (`figma.getNodeByIdAsync()`), which has reliable, real-time access to all component fields including descriptions. This makes it ideal for teams working with local components in shared project files.
+
+## License
+
+Part of the figma-console-mcp project.

package/figma-desktop-bridge/code.js

@@ -0,0 +1,133 @@
+// Figma Desktop Bridge - MCP Plugin
+// Bridges Figma API to MCP clients via plugin UI window
+// Supports: Variables, Components, Styles, and more
+// Uses postMessage to communicate with UI, bypassing worker sandbox limitations
+// Puppeteer can access UI iframe's window context to retrieve data
+
+console.log('🌉 [Desktop Bridge] Plugin loaded and ready');
+
+// Show UI to keep plugin running and receive data
+figma.showUI(__html__, { width: 320, height: 240, visible: true });
+
+// Immediately fetch and send variables data to UI
+(async () => {
+  try {
+    console.log('🌉 [Desktop Bridge] Fetching variables...');
+
+    // Get all local variables and collections
+    const variables = await figma.variables.getLocalVariablesAsync();
+    const collections = await figma.variables.getLocalVariableCollectionsAsync();
+
+    console.log(`🌉 [Desktop Bridge] Found ${variables.length} variables in ${collections.length} collections`);
+
+    // Format the data
+    const variablesData = {
+      success: true,
+      timestamp: Date.now(),
+      fileKey: figma.fileKey || null,
+      variables: variables.map(v => ({
+        id: v.id,
+        name: v.name,
+        key: v.key,
+        resolvedType: v.resolvedType,
+        valuesByMode: v.valuesByMode,
+        variableCollectionId: v.variableCollectionId,
+        scopes: v.scopes,
+        description: v.description,
+        hiddenFromPublishing: v.hiddenFromPublishing
+      })),
+      variableCollections: collections.map(c => ({
+        id: c.id,
+        name: c.name,
+        key: c.key,
+        modes: c.modes,
+        defaultModeId: c.defaultModeId,
+        variableIds: c.variableIds
+      }))
+    };
+
+    // Send to UI via postMessage
+    figma.ui.postMessage({
+      type: 'VARIABLES_DATA',
+      data: variablesData
+    });
+
+    console.log('🌉 [Desktop Bridge] Variables data sent to UI successfully');
+    console.log('🌉 [Desktop Bridge] UI iframe now has variables data accessible via window.__figmaVariablesData');
+
+  } catch (error) {
+    console.error('🌉 [Desktop Bridge] Error fetching variables:', error);
+    figma.ui.postMessage({
+      type: 'ERROR',
+      error: error.message || String(error)
+    });
+  }
+})();
+
+// Listen for requests from UI (e.g., component data requests)
+figma.ui.onmessage = async (msg) => {
+  if (msg.type === 'GET_COMPONENT') {
+    try {
+      console.log(`🌉 [Desktop Bridge] Fetching component: ${msg.nodeId}`);
+
+      const node = await figma.getNodeByIdAsync(msg.nodeId);
+
+      if (!node) {
+        throw new Error(`Node not found: ${msg.nodeId}`);
+      }
+
+      if (node.type !== 'COMPONENT' && node.type !== 'COMPONENT_SET' && node.type !== 'INSTANCE') {
+        throw new Error(`Node is not a component. Type: ${node.type}`);
+      }
+
+      // Extract component data including description fields
+      const componentData = {
+        success: true,
+        timestamp: Date.now(),
+        nodeId: msg.nodeId,
+        component: {
+          id: node.id,
+          name: node.name,
+          type: node.type,
+          description: node.description || null,
+          descriptionMarkdown: node.descriptionMarkdown || null,
+          visible: node.visible,
+          locked: node.locked,
+          // For components with properties
+          componentPropertyDefinitions: (node.type === 'COMPONENT' || node.type === 'COMPONENT_SET')
+            ? node.componentPropertyDefinitions
+            : undefined,
+          // Get children info (lightweight)
+          children: node.children ? node.children.map(child => ({
+            id: child.id,
+            name: child.name,
+            type: child.type
+          })) : undefined
+        }
+      };
+
+      console.log(`🌉 [Desktop Bridge] Component data ready. Has description: ${!!componentData.component.description}`);
+
+      // Send to UI
+      figma.ui.postMessage({
+        type: 'COMPONENT_DATA',
+        requestId: msg.requestId, // Echo back the request ID
+        data: componentData
+      });
+
+    } catch (error) {
+      console.error(`🌉 [Desktop Bridge] Error fetching component:`, error);
+      figma.ui.postMessage({
+        type: 'COMPONENT_ERROR',
+        requestId: msg.requestId,
+        error: error.message || String(error)
+      });
+    }
+  }
+};
+
+console.log('🌉 [Desktop Bridge] Ready to handle component requests');
+console.log('🌉 [Desktop Bridge] Plugin will stay open until manually closed');
+
+// Plugin stays open - no auto-close
+// UI iframe remains accessible for Puppeteer to read data from window object

package/figma-desktop-bridge/manifest.json

@@ -0,0 +1,13 @@
+{
+  "name": "Figma Desktop Bridge",
+  "id": "figma-desktop-bridge-mcp",
+  "api": "1.0.0",
+  "main": "code.js",
+  "ui": "ui.html",
+  "editorType": ["figma", "dev"],
+  "capabilities": ["inspect"],
+  "documentAccess": "dynamic-page",
+  "networkAccess": {
+    "allowedDomains": ["none"]
+  }
+}

package/figma-desktop-bridge/ui.html

@@ -0,0 +1,200 @@
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="UTF-8">
+  <style>
+    * {
+      box-sizing: border-box;
+      margin: 0;
+      padding: 0;
+    }
+
+    body {
+      font-family: -apple-system, BlinkMacSystemFont, 'Inter', 'Segoe UI', Roboto, Oxygen, Ubuntu, Cantarell, sans-serif;
+      background: #ffffff;
+      color: #1a1a1a;
+      padding: 24px;
+      min-height: 100vh;
+      display: flex;
+      flex-direction: column;
+      align-items: center;
+      justify-content: center;
+    }
+
+    .container {
+      max-width: 320px;
+      width: 100%;
+    }
+
+    .status {
+      font-size: 14px;
+      font-weight: 500;
+      margin-bottom: 8px;
+      display: flex;
+      align-items: center;
+      gap: 8px;
+    }
+
+    .icon {
+      font-size: 16px;
+      line-height: 1;
+    }
+
+    .details {
+      font-size: 12px;
+      color: #666;
+      line-height: 1.6;
+      margin-top: 8px;
+    }
+
+    .details strong {
+      color: #1a1a1a;
+      font-weight: 500;
+    }
+
+    .success {
+      color: #059669;
+    }
+
+    .error {
+      color: #dc2626;
+    }
+
+    .loading {
+      color: #6b7280;
+    }
+
+    .divider {
+      height: 1px;
+      background: #e5e7eb;
+      margin: 16px 0;
+    }
+
+    .footer {
+      font-size: 11px;
+      color: #9ca3af;
+      margin-top: 16px;
+      text-align: center;
+    }
+  </style>
+</head>
+<body>
+  <div class="container">
+    <div id="content">
+      <div class="status loading">
+        <span class="icon">⏳</span>
+        <span>Loading data...</span>
+      </div>
+      <div class="details">Connecting to Figma API</div>
+    </div>
+    <div class="divider"></div>
+    <div class="footer">Made with ❤️ by Southleft</div>
+  </div>
+
+  <script>
+    // Global variables to store data for Puppeteer access
+    window.__figmaVariablesData = null;
+    window.__figmaVariablesReady = false;
+    window.__figmaComponentData = null;
+    window.__figmaComponentRequests = new Map(); // Track pending requests
+
+    let requestIdCounter = 0;
+
+    // Function to request component data from plugin worker
+    window.requestComponentData = (nodeId) => {
+      return new Promise((resolve, reject) => {
+        const requestId = `component_${++requestIdCounter}_${Date.now()}`;
+
+        // Store the promise callbacks
+        window.__figmaComponentRequests.set(requestId, { resolve, reject });
+
+        // Send request to plugin worker
+        parent.postMessage({
+          pluginMessage: {
+            type: 'GET_COMPONENT',
+            requestId: requestId,
+            nodeId: nodeId
+          }
+        }, '*');
+
+        console.log('[Desktop Bridge] Requested component:', nodeId, 'requestId:', requestId);
+
+        // Timeout after 10 seconds
+        setTimeout(() => {
+          if (window.__figmaComponentRequests.has(requestId)) {
+            window.__figmaComponentRequests.delete(requestId);
+            reject(new Error('Component request timed out'));
+          }
+        }, 10000);
+      });
+    };
+
+    // Listen for messages from plugin worker
+    window.onmessage = (event) => {
+      const msg = event.data.pluginMessage;
+
+      if (msg.type === 'VARIABLES_DATA') {
+        // Store data on window object for Puppeteer
+        window.__figmaVariablesData = msg.data;
+        window.__figmaVariablesReady = true;
+
+        const varCount = msg.data.variables?.length || 0;
+        const collCount = msg.data.variableCollections?.length || 0;
+
+        // Update UI
+        document.getElementById('content').innerHTML = `
+          <div class="status success">
+            <span class="icon">✓</span>
+            <span>Desktop Bridge active</span>
+          </div>
+          <div class="details">
+            <strong>Variables:</strong> ${varCount} in ${collCount} ${collCount === 1 ? 'collection' : 'collections'}<br>
+            <strong>Components:</strong> On-demand via MCP<br>
+            <br>
+            <code style="font-size: 10px; background: #f3f4f6; padding: 2px 6px; border-radius: 4px; display: block; margin-top: 4px;">window.__figmaVariablesData</code>
+            <code style="font-size: 10px; background: #f3f4f6; padding: 2px 6px; border-radius: 4px; display: block; margin-top: 2px;">window.requestComponentData(id)</code>
+          </div>
+        `;
+
+        console.log('[Desktop Bridge] Variables ready:', { varCount, collCount });
+
+      } else if (msg.type === 'COMPONENT_DATA') {
+        // Store component data
+        window.__figmaComponentData = msg.data;
+
+        console.log('[Desktop Bridge] Component data received:', msg.data.component.name);
+
+        // Resolve the promise
+        const request = window.__figmaComponentRequests.get(msg.requestId);
+        if (request) {
+          request.resolve(msg.data);
+          window.__figmaComponentRequests.delete(msg.requestId);
+        }
+
+      } else if (msg.type === 'COMPONENT_ERROR') {
+        console.error('[Desktop Bridge] Component error:', msg.error);
+
+        // Reject the promise
+        const request = window.__figmaComponentRequests.get(msg.requestId);
+        if (request) {
+          request.reject(new Error(msg.error));
+          window.__figmaComponentRequests.delete(msg.requestId);
+        }
+
+      } else if (msg.type === 'ERROR') {
+        window.__figmaVariablesReady = false;
+
+        document.getElementById('content').innerHTML = `
+          <div class="status error">
+            <span class="icon">✕</span>
+            <span>Error loading data</span>
+          </div>
+          <div class="details">${msg.error}</div>
+        `;
+
+        console.error('[Desktop Bridge] Error:', msg.error);
+      }
+    };
+  </script>
+</body>
+</html>

package/package.json

@@ -0,0 +1,77 @@
+{
+	"name": "figma-console-mcp",
+	"version": "0.1.0",
+	"description": "MCP server for accessing Figma plugin console logs and screenshots via Cloudflare Workers or local mode",
+	"type": "module",
+	"main": "dist/local.js",
+	"types": "dist/local.d.ts",
+	"bin": {
+		"figma-console-mcp": "./dist/local.js"
+	},
+	"files": [
+		"dist",
+		"figma-desktop-bridge",
+		"README.md",
+		"LICENSE"
+	],
+	"scripts": {
+		"prepublishOnly": "npm run build",
+		"deploy": "wrangler deploy",
+		"dev": "wrangler dev",
+		"dev:local": "tsx src/local.ts",
+		"build": "npm run build:local && npm run build:cloudflare",
+		"build:local": "tsc -p tsconfig.local.json",
+		"build:cloudflare": "tsc -p tsconfig.cloudflare.json",
+		"start": "wrangler dev",
+		"test": "jest",
+		"test:watch": "jest --watch",
+		"test:coverage": "jest --coverage",
+		"format": "biome format --write",
+		"lint:fix": "biome lint --fix",
+		"cf-typegen": "wrangler types",
+		"type-check": "tsc --noEmit"
+	},
+	"keywords": [
+		"mcp",
+		"figma",
+		"plugin",
+		"console",
+		"debugging",
+		"ai",
+		"anthropic",
+		"claude",
+		"cloudflare",
+		"workers"
+	],
+	"author": "Your Name",
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/southleft/figma-console-mcp.git"
+	},
+	"engines": {
+		"node": ">=18.0.0"
+	},
+	"dependencies": {
+		"@cloudflare/puppeteer": "^1.0.4",
+		"@modelcontextprotocol/sdk": "1.19.1",
+		"agents": "^0.2.8",
+		"chrome-remote-interface": "^0.33.2",
+		"pino": "^9.5.0",
+		"pino-pretty": "^13.0.0",
+		"puppeteer-core": "^23.11.1",
+		"uuid": "^11.0.3",
+		"zod": "^3.25.76"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.2.5",
+		"@types/jest": "^29.5.14",
+		"@types/node": "^22.10.2",
+		"@types/uuid": "^10.0.0",
+		"jest": "^29.7.0",
+		"ts-jest": "^29.2.5",
+		"tsx": "^4.19.2",
+		"typescript": "5.9.3",
+		"wrangler": "^4.42.0"
+	}
+}