genable-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Genable
+
+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,156 @@
+# genable-mcp
+
+**The write-side complement to Figma's official MCP.** Build, edit, and search Figma nodes from any MCP client (Claude Code, Cursor, etc.) via the Genable plugin.
+
+## What this is
+
+Figma's official MCP is excellent for **reading** designs (`get_design_context`, code generation). But it's mostly read-only — there's no first-class way to write to the canvas, navigate across pages, or run plugin-API code from your MCP client.
+
+`genable-mcp` fills that gap. It exposes 39 tools focused on the **write** side:
+
+- **Tree creation** — build complete subtrees with JSX-like markup (`jsx`)
+- **Property edits** — text, fills, strokes, layout, all auto-layout aware (`set_text`, `set_fill`, `set_layout`, `set_stroke`, `edit`)
+- **Variables / tokens** — collections, modes, bindings (`create_variable`, `bind_variable`, `set_variable_mode`, etc.)
+- **Components** — create, combine, expose props, instance (`create_component`, `add_component_prop`, `create_instance`)
+- **Cross-page navigation** — `switch_page` (officially the painful gap)
+- **Search & inspect** — `find_nodes`, `inspect`, `describe`, `find_references`
+- **Visual verification** — `get_screenshot`
+- **Escape hatch** — `js` for raw plugin API access (with sandbox-limit docs in the tool description)
+
+We **recommend pairing** with Figma's official MCP. They cover read-for-codegen; we cover write-and-edit. The two MCPs together give an LLM full read+write access to a Figma file.
+
+## How it works
+
+```
+MCP client (Claude Code / Cursor / etc.)
+    ↓ stdio JSON-RPC
+genable-mcp (this package, Node.js)
+    ↓ WebSocket :3458
+Genable plugin (running inside Figma)
+    ↓ Figma Plugin API
+Figma file
+```
+
+The plugin runs in your Figma desktop app. `genable-mcp` is the bridge that lets external MCP clients call into it.
+
+## Setup
+
+### 1. Install the Genable plugin in Figma
+
+Search "Genable" in the Figma Community and install. Open it once in any file — it auto-connects to localhost:3458.
+
+(One-time. Plugin keeps connecting silently after the first run.)
+
+### 2. Add `genable-mcp` to your MCP client config
+
+#### Claude Code
+
+```json
+// .mcp.json (project) or ~/.claude.json (global)
+{
+  "mcpServers": {
+    "genable": {
+      "command": "npx",
+      "args": ["-y", "genable-mcp"]
+    }
+  }
+}
+```
+
+#### Cursor / Cline / other MCP clients
+
+Same idea — configure a STDIO server with `command: npx`, `args: ["-y", "genable-mcp"]`.
+
+### 3. Verify
+
+In your MCP client, ask: *"List the pages in my Figma file."* If the plugin is running, you'll see the page roster.
+
+## Pair with the official Figma MCP (recommended)
+
+```json
+{
+  "mcpServers": {
+    "figma": { /* official, read */ },
+    "genable": {
+      "command": "npx",
+      "args": ["-y", "genable-mcp"]
+    }
+  }
+}
+```
+
+Rule of thumb:
+- **Figma official** → "read this design and give me code" workflows
+- **Genable** → "build / edit / restructure this design" workflows
+- Both together → end-to-end "code ↔ Figma" round-trips
+
+## Configuration
+
+| Env var | Default | Purpose |
+|---|---|---|
+| `MCP_WS_PORT` | `3458` | Port the WebSocket relay listens on |
+| `RELAY_SECRET` | (empty) | If set, plugin must send matching secret in `identify` handshake. Use when sharing a host between multiple users. |
+
+## Tool reference
+
+Each tool's full description (parameters, examples, sandbox limits) is exposed via `ListTools` in the MCP protocol — your client surfaces them automatically. Below is a one-line index.
+
+### Tree creation
+- `jsx` — Build a complete subtree with JSX-like markup. Single-call atomicity.
+
+### Read
+- `inspect` — Read a node with selectable property facets (layout, paint, typography, etc.).
+- `describe` — Lint-style summary of a subtree.
+- `find_nodes` — Search by name/type within current page.
+- `discover_props` — Unique property values across a subtree.
+- `find_references` — Reverse lookup: who binds this variable?
+- `get_selection` — User's current Figma selection.
+
+### Write — properties
+- `edit` — Generic property updates on existing nodes.
+- `set_text`, `set_fill`, `set_stroke`, `set_layout` — Single-intent setters (font load + fallback included).
+- `replace_props` — Bulk find/replace of property values across a subtree.
+
+### Write — structure
+- `delete_node`, `move_node`, `clone_node` — Tree mutations.
+
+### Components
+- `create_component`, `combine_components` — Promote nodes to components.
+- `add_component_prop`, `list_component_props` — Variant / boolean / instance-swap props.
+- `create_instance` — Instantiate a component.
+
+### Variables / tokens
+- `list_variables` — Inventory of collections + variables in the file.
+- `create_collection`, `ensure_collection` — Token collections (idempotent ensure).
+- `create_variable`, `ensure_variable`, `set_variable_value`, `set_variable_mode` — Variable lifecycle.
+- `bind_variable` — Bind a variable to a node property.
+
+### Knowledge readers
+- `skill`, `style`, `anatomy`, `guideline`, `help` — Curated design knowledge baked into the plugin.
+
+### Page navigation
+- `switch_page` — Switch active page by ID or name. Returns the full page roster.
+
+### Visual verification
+- `get_screenshot` — Export a node as PNG, embedded as MCP image content.
+
+### Interaction
+- `ask_user` — Pause and ask the user a question (interactive client only).
+- `subtask` — Delegate a sub-prompt to a focused agent.
+
+### Escape hatch
+- `js` — `[advanced]` Run JS in the plugin runtime. Full `figma.*` API access. Sandbox limits documented in the tool description (cross-page loading, frozen arrays, font requirements, etc.).
+
+## Limitations
+
+- **Plugin must be open** — Figma writes require the plugin runtime. The plugin reconnects silently across files; you only need to launch it once per Figma session.
+- **One file at a time per port** — Multi-file workflows: spawn additional relay ports via `MCP_WS_PORTS=3458,3459,…`
+- **Sandbox quirks** — Some Figma plugin-API edges are sharp (font loading, frozen `fills` arrays, stale node IDs after reload). High-level tools wrap most of these; the `js` escape hatch description lists the rest.
+
+## License
+
+MIT.
+
+## Repo
+
+Source + issues: [github.com/muse40007/figma-ai-generator-dogfood](https://github.com/muse40007/figma-ai-generator-dogfood) (subdir `tools/mcp-server`).

package/dist/httpBridge.js

@@ -0,0 +1,186 @@
+"use strict";
+/**
+ * @file httpBridge.ts
+ * @description Standalone HTTP bridge to Figma plugin — no MCP protocol needed.
+ * Any AI CLI (Claude Code, OpenCode, Cursor, etc.) can call Figma tools via curl.
+ *
+ * Architecture:
+ *   AI Client (curl / fetch)
+ *     → This HTTP server (localhost:3460)
+ *       → WebSocket relay (port 3461, same process) → Figma Plugin
+ *
+ * Usage:
+ *   npx tsx tools/mcp-server/httpBridge.ts
+ *   # or with custom ports:
+ *   HTTP_PORT=3462 MCP_WS_PORT=3463 npx tsx tools/mcp-server/httpBridge.ts
+ *
+ * Endpoints:
+ *   GET  /health              — connection status + connected files
+ *   GET  /clients             — list connected Figma files (fileKey, fileName)
+ *   GET  /tools               — list available tools
+ *   POST /tool/:name          — call a tool (JSON body = parameters)
+ *   POST /tool/:name?file=KEY — call a tool targeting a specific Figma file
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+const http_1 = __importDefault(require("http"));
+const fs_1 = require("fs");
+const path_1 = require("path");
+const HTTP_PORT = parseInt(process.env.HTTP_PORT || '3460', 10);
+const WS_PORT = parseInt(process.env.MCP_WS_PORT || '3461', 10);
+function loadToolsSchema() {
+    const schemaPath = (0, path_1.join)(__dirname, 'tools-schema.json');
+    try {
+        return JSON.parse((0, fs_1.readFileSync)(schemaPath, 'utf-8'));
+    }
+    catch (err) {
+        console.error(`[HTTP Bridge] FATAL: failed to load ${schemaPath}: ${err.message}`);
+        console.error('[HTTP Bridge] Run `npx tsx tools/mcp-server/extract-schema.ts` to regenerate.');
+        process.exit(1);
+    }
+}
+// ── Helpers ──
+function jsonResponse(res, status, data) {
+    res.writeHead(status, {
+        'Content-Type': 'application/json',
+        'Access-Control-Allow-Origin': '*',
+    });
+    res.end(JSON.stringify(data));
+}
+function readBody(req) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('end', () => resolve(Buffer.concat(chunks).toString()));
+        req.on('error', reject);
+    });
+}
+// ── Main ──
+async function main() {
+    // Set WS port BEFORE importing wsRelay — it reads env at module top-level
+    process.env.MCP_WS_PORT = String(WS_PORT);
+    const { createWsRelay } = await import('./wsRelay.js');
+    const unifiedTools = loadToolsSchema();
+    const relay = createWsRelay();
+    // Tool catalog for /tools endpoint
+    const toolCatalog = unifiedTools.map((def) => ({
+        name: def.name,
+        description: def.description,
+        parameters: def.parameters,
+    }));
+    const toolSet = new Set(unifiedTools.map((d) => d.name));
+    const server = http_1.default.createServer(async (req, res) => {
+        const url = new URL(req.url || '/', `http://localhost:${HTTP_PORT}`);
+        // CORS preflight
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204, {
+                'Access-Control-Allow-Origin': '*',
+                'Access-Control-Allow-Methods': 'GET, POST, OPTIONS',
+                'Access-Control-Allow-Headers': 'Content-Type',
+            });
+            res.end();
+            return;
+        }
+        // GET /health
+        if (req.method === 'GET' && url.pathname === '/health') {
+            const clients = relay.listClients();
+            jsonResponse(res, 200, {
+                ok: true,
+                pluginConnected: relay.isPluginConnected(),
+                clients,
+            });
+            return;
+        }
+        // GET /clients
+        if (req.method === 'GET' && url.pathname === '/clients') {
+            jsonResponse(res, 200, { clients: relay.listClients() });
+            return;
+        }
+        // GET /tools
+        if (req.method === 'GET' && url.pathname === '/tools') {
+            jsonResponse(res, 200, { tools: toolCatalog });
+            return;
+        }
+        // POST /tool/:name[?file=fileKey]
+        const toolMatch = url.pathname.match(/^\/tool\/([a-z_]+)$/);
+        if (req.method === 'POST' && toolMatch) {
+            const toolName = toolMatch[1];
+            const fileKey = url.searchParams.get('file') || undefined;
+            if (!toolSet.has(toolName)) {
+                jsonResponse(res, 404, { error: `Unknown tool: ${toolName}` });
+                return;
+            }
+            // Require ?file= when multiple clients are connected
+            const clients = relay.listClients();
+            if (!fileKey && clients.length > 1) {
+                const fileList = clients.map(c => `  "${c.fileName}" (?file=${encodeURIComponent(c.fileName.replace('[Draft] ', ''))})`).join('\n');
+                jsonResponse(res, 400, {
+                    error: `Multiple Figma files connected. Add ?file=<name> to target one:\n${fileList}`,
+                });
+                return;
+            }
+            if (!relay.isPluginConnected()) {
+                jsonResponse(res, 503, {
+                    error: 'Figma plugin is not connected. Open Figma and run the plugin first.',
+                });
+                return;
+            }
+            try {
+                const body = await readBody(req);
+                const params = body ? JSON.parse(body) : {};
+                // Pit-of-success: screenshot=true implies mode:detail (screenshot only works in detail mode)
+                if (toolName === 'inspect' && params.screenshot && !params.mode) {
+                    params.mode = 'detail';
+                }
+                // Route to specific file or any available
+                const response = fileKey
+                    ? await relay.callToolForFile(fileKey, toolName, params)
+                    : await relay.callTool(toolName, params);
+                if (response.error) {
+                    jsonResponse(res, 422, { error: response.error });
+                }
+                else {
+                    const data = response.data ?? response;
+                    // Normalize __image → screenshot for cleaner API surface
+                    if (data?.__image) {
+                        data.screenshot = data.__image;
+                        delete data.__image;
+                    }
+                    // Forward tool warnings (sizing demotes, dependency violations, ambiguous
+                    // variable autopicks, etc.) — these mirror what the LLM sees and are
+                    // load-bearing for debugging "why didn't my intent take" cases.
+                    const out = { ok: true, data };
+                    if (response.warnings && response.warnings.length > 0) {
+                        out.warnings = response.warnings;
+                    }
+                    jsonResponse(res, 200, out);
+                }
+            }
+            catch (err) {
+                const isTimeout = err.message?.includes('timed out');
+                const isNotConnected = err.message?.includes('not connected') || err.message?.includes('No Figma file');
+                jsonResponse(res, isTimeout ? 504 : isNotConnected ? 404 : 500, { error: err.message });
+            }
+            return;
+        }
+        jsonResponse(res, 404, { error: 'Not found' });
+    });
+    server.listen(HTTP_PORT, () => {
+        console.error(`[HTTP Bridge] Listening on http://localhost:${HTTP_PORT}`);
+        console.error(`[HTTP Bridge] WebSocket relay on port ${WS_PORT}`);
+        console.error(`[HTTP Bridge] Endpoints:`);
+        console.error(`[HTTP Bridge]   GET  /health, /clients, /tools`);
+        console.error(`[HTTP Bridge]   POST /tool/:name[?file=fileKey]`);
+    });
+    process.on('SIGINT', () => {
+        relay.close();
+        server.close();
+        process.exit(0);
+    });
+}
+main().catch((err) => {
+    console.error('[HTTP Bridge] Fatal error:', err);
+    process.exit(1);
+});

package/dist/index.js

@@ -0,0 +1,121 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * @file MCP Server — Expose Figma plugin tools to external clients (Claude Code, etc.)
+ *
+ * Architecture:
+ *   Claude Code (MCP client, stdio)
+ *     → This MCP Server (Node.js, stdio transport)
+ *       → WebSocket relay (localhost:3458) → Figma Plugin
+ *
+ * Tool schema is loaded from `tools-schema.json` (generated by `extract-schema.ts`
+ * at build time). This decouples the published `genable-mcp` npm package from
+ * the rest of the dogfood codebase — the package only ships compiled JS + JSON,
+ * not the plugin's TS source tree.
+ *
+ * All calls are relayed to the Figma plugin via WebSocket.
+ *
+ * IMPORTANT: Use console.error() for logging — stdout is reserved for MCP JSON-RPC.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const fs_1 = require("fs");
+const path_1 = require("path");
+const wsRelay_js_1 = require("./wsRelay.js");
+function loadToolsSchema() {
+    const schemaPath = (0, path_1.join)(__dirname, 'tools-schema.json');
+    try {
+        return JSON.parse((0, fs_1.readFileSync)(schemaPath, 'utf-8'));
+    }
+    catch (err) {
+        console.error(`[MCP] FATAL: failed to load ${schemaPath}: ${err.message}`);
+        console.error('[MCP] Run `npx tsx tools/mcp-server/extract-schema.ts` to regenerate.');
+        process.exit(1);
+    }
+}
+const unifiedTools = loadToolsSchema();
+// ── Convert ToolDefinition.parameters → MCP inputSchema ──
+function toMcpInputSchema(def) {
+    return {
+        type: 'object',
+        properties: def.parameters.properties,
+        required: def.parameters.required ?? [],
+    };
+}
+// ── Build MCP content from tool response ──
+function buildMcpContent(response) {
+    // Error response
+    if (response.error) {
+        return {
+            content: [{ type: 'text', text: JSON.stringify({ error: response.error }) }],
+            isError: true,
+        };
+    }
+    const data = response.data ?? response;
+    const content = [];
+    // Extract image if present (get_screenshot tool — data.__image)
+    if (data?.__image) {
+        const { __image, ...rest } = data;
+        content.push({ type: 'text', text: JSON.stringify(rest) });
+        content.push({
+            type: 'image',
+            data: __image.data,
+            mimeType: __image.mimeType,
+        });
+    }
+    else {
+        content.push({ type: 'text', text: JSON.stringify(data) });
+    }
+    return { content };
+}
+// ── Main ──
+async function main() {
+    const relay = (0, wsRelay_js_1.createWsRelay)();
+    const server = new index_js_1.Server({ name: 'figma-ai-generator', version: '1.0.0' }, { capabilities: { tools: {} } });
+    // List tools — auto-convert from ToolDefinition
+    server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => ({
+        tools: unifiedTools.map((def) => ({
+            name: def.name,
+            description: def.description,
+            inputSchema: toMcpInputSchema(def),
+        })),
+    }));
+    // Call tool — relay to Figma plugin via WebSocket
+    server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+        const { name: toolName, arguments: params = {} } = request.params;
+        if (!relay.isPluginConnected()) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: 'Figma plugin is not connected. Open Figma and run the plugin first, then retry.',
+                    }],
+                isError: true,
+            };
+        }
+        try {
+            const response = await relay.callTool(toolName, params);
+            return buildMcpContent(response);
+        }
+        catch (err) {
+            return {
+                content: [{ type: 'text', text: err.message || String(err) }],
+                isError: true,
+            };
+        }
+    });
+    // Connect stdio transport
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    console.error('[MCP] Figma AI Generator MCP server running (stdio)');
+    // Graceful shutdown
+    process.on('SIGINT', () => {
+        relay.close();
+        process.exit(0);
+    });
+}
+main().catch((err) => {
+    console.error('[MCP] Fatal error:', err);
+    process.exit(1);
+});