figma-console-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Figma Console MCP Contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,328 @@
+# Figma Console MCP Server
+
+[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+> **Model Context Protocol server** that provides AI assistants with **real-time console access, visual debugging, and design system extraction** for Figma.
+
+## What is this?
+
+Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
+
+- **🐛 Plugin debugging** - Capture console logs, errors, and stack traces
+- **📸 Visual debugging** - Take screenshots for context
+- **🎨 Design system extraction** - Pull variables, components, and styles
+- **⚡ Real-time monitoring** - Watch logs as plugins execute
+- **🔄 Two modes** - Remote (zero setup) or Local (plugin development)
+
+---
+
+## ⚡ Quick Start
+
+Choose the setup that fits your needs:
+
+### For Most Users: Remote Mode (Zero Setup)
+
+Perfect for design system extraction and basic debugging. No installation required!
+
+#### Claude Desktop (Recommended)
+
+**Latest Method - No Config Files!**
+
+1. Open Claude Desktop → **Settings** → **Connectors**
+2. Click **"Add Custom Connector"**
+3. Enter:
+   - **Name:** `Figma Console`
+   - **URL:** `https://figma-console-mcp.southleft.com/sse`
+4. Click **"Add"**
+5. Done! ✅
+
+**What you get:**
+- ✅ All 14 Figma tools available immediately
+- ✅ OAuth authentication (automatic when you first use API tools)
+- ✅ Design system extraction (variables*, components, styles)
+- ✅ Console debugging and screenshots
+- ❌ Desktop Bridge plugin NOT available (use Local Mode for that)
+
+*Variables API requires Figma Enterprise plan OR use Local Mode + Desktop Bridge plugin
+
+---
+
+#### Claude Code
+
+One-line install:
+
+```bash
+claude mcp add --transport sse figma-console https://figma-console-mcp.southleft.com/sse
+```
+
+Verify: `/mcp` should show "figma-console: connected"
+
+---
+
+#### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "figma-console": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://figma-console-mcp.southleft.com/sse"]
+    }
+  }
+}
+```
+
+Restart Cursor after saving.
+
+---
+
+<details>
+<summary><b>Other MCP Clients (Windsurf, Zed, etc.)</b></summary>
+
+Consult your client's MCP documentation for the config file location, then add:
+
+```json
+{
+  "mcpServers": {
+    "figma-console": {
+      "command": "npx",
+      "args": ["-y", "mcp-remote", "https://figma-console-mcp.southleft.com/sse"]
+    }
+  }
+}
+```
+
+</details>
+
+---
+
+### For Plugin Developers: Local Mode
+
+**Use Local Mode if you:**
+- ✅ Are developing Figma plugins (need zero-latency console debugging)
+- ✅ Need variables WITHOUT Enterprise plan (via Desktop Bridge plugin)
+- ✅ Need reliable component descriptions (Figma API has bugs, plugin bypasses them)
+- ✅ Want direct access to Figma Desktop state
+
+**⚠️ Important:** The **Desktop Bridge plugin ONLY works in Local Mode**. Remote mode cannot access it because the plugin requires direct connection to Figma Desktop via `localhost:9222`.
+
+**Setup time:** 10-15 minutes
+
+**Prerequisites:**
+- Node.js 18+
+- Figma Desktop installed
+- Terminal access
+
+**[📖 See Local Mode Setup Guide](docs/CLAUDE_DESKTOP_SETUP_UPDATED.md#local-mode-setup-advanced)**
+
+---
+
+## 📊 Remote vs Local: Which Should I Use?
+
+| Feature | Remote Mode | Local Mode |
+|---------|-------------|------------|
+| **Setup** | 2 minutes | 10-15 minutes |
+| **Prerequisites** | None | Node.js, Figma restart |
+| **Console logs** | ✅ | ✅ (lower latency) |
+| **API access** | ✅ | ✅ |
+| **OAuth auth** | ✅ (automatic) | ❌ (manual PAT) |
+| **Desktop Bridge plugin** | ❌ | ✅ |
+| **Variables (no Enterprise)** | ❌ | ✅ (via plugin) |
+| **Reliable component descriptions** | ⚠️ (API bugs) | ✅ (via plugin) |
+
+**📖 [Complete Feature Comparison](docs/MODE_COMPARISON.md)**
+
+---
+
+## 🎯 Test Your Connection
+
+After setup, try these prompts:
+
+**Basic test (both modes):**
+```
+Navigate to https://www.figma.com and check status
+```
+
+**Design system test (requires auth):**
+```
+Get design variables from [your Figma file URL]
+```
+
+**Plugin test (Local Mode only):**
+```
+Show me the primary font for [your theme name]
+```
+
+---
+
+## 🔐 Authentication
+
+### Remote Mode - OAuth (Automatic)
+
+When you first use design system tools:
+1. Browser opens automatically to Figma authorization page
+2. Click "Allow" to authorize (one-time)
+3. Token stored securely and refreshed automatically
+4. Works with Free, Pro, and Enterprise Figma plans
+
+### Local Mode - Personal Access Token (Manual)
+
+1. Visit https://www.figma.com/developers/api#access-tokens
+2. Generate token
+3. Add to MCP config as `FIGMA_ACCESS_TOKEN` environment variable
+
+---
+
+## 🛠️ Available Tools
+
+All 14 tools work in both Remote and Local modes:
+
+### Navigation & Status
+- `figma_navigate` - Open Figma URLs
+- `figma_get_status` - Check connection status
+
+### Console Debugging
+- `figma_get_console_logs` - Retrieve console logs
+- `figma_watch_console` - Real-time log streaming
+- `figma_clear_console` - Clear log buffer
+- `figma_reload_plugin` - Reload current page
+
+### Visual Debugging
+- `figma_take_screenshot` - Capture UI screenshots
+
+### Design System Extraction
+- `figma_get_variables` - Extract design tokens/variables
+- `figma_get_component` - Get component data
+- `figma_get_component_for_development` - Component + image
+- `figma_get_component_image` - Just the image
+- `figma_get_styles` - Color, text, effect styles
+- `figma_get_file_data` - Full file structure
+- `figma_get_file_for_plugin` - Optimized file data
+
+**📖 [Detailed Tool Documentation](docs/TOOLS.md)**
+
+---
+
+## 📖 Example Prompts
+
+### Plugin Debugging
+```
+Navigate to my Figma plugin and show me any console errors
+Watch the console for 30 seconds while I test my plugin
+Get the last 20 console logs
+```
+
+### Design System Extraction
+```
+Get all design variables from https://figma.com/design/abc123
+Extract color styles and show me the CSS exports
+Get the Button component with a visual reference image
+```
+
+### Visual Debugging
+```
+Take a screenshot of the current Figma canvas
+Navigate to this file and capture what's on screen
+```
+
+**📖 [More Use Cases & Examples](docs/USE_CASES.md)**
+
+---
+
+## 🎨 Desktop Bridge Plugin (Local Mode Only)
+
+The **Figma Desktop Bridge** plugin enables:
+- ✅ Variables without Enterprise API
+- ✅ Reliable component descriptions (bypasses API bugs)
+- ✅ Multi-mode support (Light/Dark/Brand variants)
+
+**⚠️ Plugin Limitation:** Only works in Local Mode. Remote mode cannot access it.
+
+**Setup:**
+1. Install Local Mode MCP
+2. Download plugin from [Releases](https://github.com/southleft/figma-console-mcp/releases/latest)
+3. Import plugin: Figma Desktop → Plugins → Development → Import plugin from manifest
+4. Run plugin in your Figma file
+5. Ask Claude: "Show me the primary font for [your theme]"
+
+**📖 [Desktop Bridge Documentation](figma-desktop-bridge/README.md)**
+
+---
+
+## 🚀 Advanced Topics
+
+- **[Local Mode Setup](docs/CLAUDE_DESKTOP_SETUP_UPDATED.md)** - Complete local installation guide
+- **[Self-Hosting](docs/SELF_HOSTING.md)** - Deploy your own instance on Cloudflare
+- **[Architecture](docs/ARCHITECTURE.md)** - How it works under the hood
+- **[OAuth Setup](docs/OAUTH_SETUP.md)** - Configure OAuth for self-hosted deployments
+- **[Troubleshooting](docs/TROUBLESHOOTING.md)** - Common issues and solutions
+
+---
+
+## 🤝 vs. Figma Official MCP
+
+**Figma Console MCP (This Project)** - Debugging & data extraction
+- ✅ Real-time console logs from Figma plugins
+- ✅ Screenshot capture and visual debugging
+- ✅ Error stack traces and runtime monitoring
+- ✅ Raw design data extraction (JSON)
+- ✅ Works remotely or locally
+
+**Figma Official Dev Mode MCP** - Code generation
+- ✅ Generates React/HTML code from designs
+- ✅ Tailwind/CSS class generation
+- ✅ Component boilerplate scaffolding
+
+**Use both together** for the complete workflow: generate code with Official MCP, then debug and extract data with Console MCP.
+
+---
+
+## 🛤️ Roadmap
+
+- [ ] **Real-time collaboration** - Multi-user debugging sessions
+- [ ] **Component screenshot diffs** - Visual regression testing
+- [ ] **Batch operations** - Process multiple files at once
+- [ ] **Design linting** - Automated compliance checks
+- [ ] **Plugin template generation** - Generate plugin boilerplate
+
+**📖 [Full Roadmap](docs/ROADMAP.md)**
+
+---
+
+## 💻 Development
+
+```bash
+git clone https://github.com/southleft/figma-console-mcp.git
+cd figma-console-mcp
+npm install
+
+# Local mode development
+npm run dev:local
+
+# Cloud mode development
+npm run dev
+
+# Build
+npm run build
+```
+
+**📖 [Development Guide](docs/ARCHITECTURE.md)**
+
+---
+
+## 📄 License
+
+MIT - See [LICENSE](LICENSE) file for details.
+
+---
+
+## 🔗 Links
+
+- 📖 [Full Documentation](docs/)
+- 🐛 [Report Issues](https://github.com/southleft/figma-console-mcp/issues)
+- 💬 [Discussions](https://github.com/southleft/figma-console-mcp/discussions)
+- 🌐 [Model Context Protocol](https://modelcontextprotocol.io/)
+- 🎨 [Figma API](https://www.figma.com/developers/api)

package/dist/browser/base.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Browser Manager Interface
+ * Abstract interface for browser automation across different runtimes
+ */
+/**
+ * Browser Manager Interface
+ * Provides unified API for browser automation regardless of runtime (Cloudflare/Local)
+ *
+ * Note: Uses 'any' for Page type to support both puppeteer-core and @cloudflare/puppeteer
+ * implementations which have incompatible type definitions but compatible runtime behavior
+ */
+export interface IBrowserManager {
+    /**
+     * Launch or connect to browser instance
+     */
+    launch(): Promise<void>;
+    /**
+     * Get active page instance
+     */
+    getPage(): Promise<any>;
+    /**
+     * Navigate to Figma URL
+     */
+    navigateToFigma(url?: string): Promise<any>;
+    /**
+     * Reload current page
+     */
+    reload(hardReload?: boolean): Promise<void>;
+    /**
+     * Evaluate JavaScript in page context
+     */
+    evaluate<T>(fn: () => T): Promise<T>;
+    /**
+     * Check if browser is running
+     */
+    isRunning(): boolean;
+    /**
+     * Close browser instance
+     */
+    close(): Promise<void>;
+    /**
+     * Get current URL
+     */
+    getCurrentUrl(): string | null;
+    /**
+     * Wait for navigation to complete
+     */
+    waitForNavigation(timeout?: number): Promise<void>;
+}
+//# sourceMappingURL=base.d.ts.map

package/dist/browser/base.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.d.ts","sourceRoot":"","sources":["../../src/browser/base.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC/B;;OAEG;IACH,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAExB;;OAEG;IACH,OAAO,IAAI,OAAO,CAAC,GAAG,CAAC,CAAC;IAExB;;OAEG;IACH,eAAe,CAAC,GAAG,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC;IAE5C;;OAEG;IACH,MAAM,CAAC,UAAU,CAAC,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE5C;;OAEG;IACH,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;IAKrC;;OAEG;IACH,SAAS,IAAI,OAAO,CAAC;IAErB;;OAEG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IAEvB;;OAEG;IACH,aAAa,IAAI,MAAM,GAAG,IAAI,CAAC;IAE/B;;OAEG;IACH,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CACnD"}

package/dist/browser/base.js

@@ -0,0 +1,6 @@
+/**
+ * Browser Manager Interface
+ * Abstract interface for browser automation across different runtimes
+ */
+export {};
+//# sourceMappingURL=base.js.map

package/dist/browser/base.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"base.js","sourceRoot":"","sources":["../../src/browser/base.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/dist/browser/local.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Local Browser Manager
+ * Connects to Figma Desktop via Chrome Remote Debugging Protocol
+ */
+import { type Page } from 'puppeteer-core';
+import type { IBrowserManager } from './base.js';
+/**
+ * Local browser configuration
+ */
+export interface LocalBrowserConfig {
+    debugPort: number;
+    debugHost: string;
+}
+/**
+ * Local Browser Manager
+ * Connects to existing Figma Desktop instance via remote debugging port
+ */
+export declare class LocalBrowserManager implements IBrowserManager {
+    private browser;
+    private page;
+    private config;
+    constructor(config: LocalBrowserConfig);
+    /**
+     * Connect to Figma Desktop via remote debugging port
+     */
+    launch(): Promise<void>;
+    /**
+     * Find the best page for plugin debugging
+     * Actively searches for pages with workers across ALL tabs
+     */
+    private findBestPage;
+    /**
+     * Get active Figma page or create new one
+     * Prefers pages with active plugin workers for plugin debugging
+     */
+    getPage(): Promise<Page>;
+    /**
+     * Navigate to Figma URL
+     */
+    navigateToFigma(figmaUrl?: string): Promise<Page>;
+    /**
+     * Reload current page
+     */
+    reload(hardReload?: boolean): Promise<void>;
+    /**
+     * Execute JavaScript in page context
+     */
+    evaluate<T>(fn: () => T): Promise<T>;
+    /**
+     * Check if browser is connected
+     */
+    isRunning(): boolean;
+    /**
+     * Disconnect from browser (doesn't close Figma Desktop)
+     */
+    close(): Promise<void>;
+    /**
+     * Get current page URL
+     */
+    getCurrentUrl(): string | null;
+    /**
+     * Wait for navigation
+     */
+    waitForNavigation(timeout?: number): Promise<void>;
+}
+//# sourceMappingURL=local.d.ts.map

package/dist/browser/local.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"local.d.ts","sourceRoot":"","sources":["../../src/browser/local.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAkB,EAAgB,KAAK,IAAI,EAAE,MAAM,gBAAgB,CAAC;AAEpE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAIjD;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,qBAAa,mBAAoB,YAAW,eAAe;IAC1D,OAAO,CAAC,OAAO,CAAwB;IACvC,OAAO,CAAC,IAAI,CAAqB;IACjC,OAAO,CAAC,MAAM,CAAqB;gBAEvB,MAAM,EAAE,kBAAkB;IAItC;;OAEG;IACG,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC;IA2C7B;;;OAGG;YACW,YAAY;IA4C1B;;;OAGG;IACG,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC;IAkC9B;;OAEG;IACG,eAAe,CAAC,QAAQ,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAsBvD;;OAEG;IACG,MAAM,CAAC,UAAU,UAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;IAoB/C;;OAEG;IACG,QAAQ,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;IAQ1C;;OAEG;IACH,SAAS,IAAI,OAAO;IAIpB;;OAEG;IACG,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IAoB5B;;OAEG;IACH,aAAa,IAAI,MAAM,GAAG,IAAI;IAQ9B;;OAEG;IACG,iBAAiB,CAAC,OAAO,SAAQ,GAAG,OAAO,CAAC,IAAI,CAAC;CAUvD"}