claude-figjam 1.0.0

package/dist/bridge.js

@@ -0,0 +1,86 @@
+// claude-figjam/mcp-server/src/bridge.ts
+import WebSocket, { WebSocketServer } from "ws";
+import { randomUUID } from "node:crypto";
+export class Bridge {
+    wss;
+    ws = null;
+    queue = [];
+    pending = new Map();
+    constructor(port) {
+        this.wss = new WebSocketServer({ port });
+        this.wss.on("connection", (ws) => {
+            this.ws = ws;
+            setTimeout(() => this.flushQueue(), 0);
+            ws.on("message", (data) => {
+                let msg;
+                try {
+                    msg = JSON.parse(data.toString());
+                }
+                catch {
+                    return; // ignore malformed messages
+                }
+                const cmd = this.pending.get(msg.id);
+                if (!cmd)
+                    return;
+                this.pending.delete(msg.id);
+                if (msg.error)
+                    cmd.reject(new Error(msg.error));
+                else
+                    cmd.resolve(msg.result);
+            });
+            ws.on("close", () => {
+                this.ws = null;
+                for (const cmd of this.pending.values()) {
+                    cmd.reject(new Error("Plugin disconnected"));
+                }
+                this.pending.clear();
+            });
+        });
+    }
+    flushQueue() {
+        while (this.queue.length > 0 && this.ws?.readyState === WebSocket.OPEN) {
+            const cmd = this.queue.shift();
+            this.dispatch(cmd);
+        }
+    }
+    dispatch(cmd) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            cmd.reject(new Error("No active connection"));
+            return;
+        }
+        this.pending.set(cmd.id, cmd);
+        const msg = {
+            id: cmd.id,
+            type: cmd.type,
+            params: cmd.params,
+        };
+        this.ws.send(JSON.stringify(msg));
+    }
+    execute(type, params) {
+        return new Promise((resolve, reject) => {
+            const cmd = {
+                id: randomUUID(),
+                type,
+                params,
+                resolve,
+                reject,
+            };
+            if (this.ws?.readyState === WebSocket.OPEN) {
+                this.dispatch(cmd);
+            }
+            else {
+                this.queue.push(cmd);
+            }
+        });
+    }
+    get connected() {
+        return this.ws !== null && this.ws.readyState === WebSocket.OPEN;
+    }
+    close(callback) {
+        // Terminate all active connections so wss.close() can invoke its callback
+        for (const client of this.wss.clients) {
+            client.terminate();
+        }
+        this.wss.close(callback);
+    }
+}

package/dist/cli.js

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+const args = process.argv.slice(2);
+if (args.includes("--stdio")) {
+    // Claude Code is starting the MCP server — run it
+    await import("./index.js");
+}
+else if (args[0] === "setup") {
+    const { setup } = await import("./setup.js");
+    await setup();
+}
+else {
+    console.log("");
+    console.log("Claude FigJam MCP Server");
+    console.log("");
+    console.log("Usage:");
+    console.log("  npx claude-figjam setup     Configure Claude Code for FigJam");
+    console.log("  npx claude-figjam --stdio   Start the MCP server (used by Claude Code)");
+    console.log("");
+}
+export {};

package/dist/index.js

@@ -0,0 +1,70 @@
+import express from "express";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Bridge } from "./bridge.js";
+import { registerTools } from "./tools.js";
+const MCP_PORT = parseInt(process.env.FIGJAM_MCP_PORT || "3055", 10);
+const WS_PORT = parseInt(process.env.FIGJAM_WS_PORT || "3766", 10);
+const STDIO_MODE = process.argv.includes("--stdio");
+const bridge = new Bridge(WS_PORT);
+const mcpServer = new McpServer({ name: "claude-figjam", version: "1.0.0" });
+registerTools(mcpServer, bridge);
+if (STDIO_MODE) {
+    // Stdio transport: CC manages this process. All logs must go to stderr.
+    const app = express();
+    app.get("/health", (_req, res) => {
+        res.json({ status: "ok", pluginConnected: bridge.connected });
+    });
+    app.listen(MCP_PORT, "127.0.0.1", () => {
+        console.error("Claude FigJam MCP server running (stdio mode)");
+        console.error(`  WebSocket: ws://localhost:${WS_PORT}`);
+        console.error(`  Health:    http://localhost:${MCP_PORT}/health`);
+    });
+    const transport = new StdioServerTransport();
+    await mcpServer.connect(transport);
+}
+else {
+    // HTTP/SSE mode: manual startup for development or CLI use.
+    const app = express();
+    app.use(express.json());
+    const transports = new Map();
+    app.get("/sse", async (req, res) => {
+        try {
+            const transport = new SSEServerTransport("/message", res);
+            transports.set(transport.sessionId, transport);
+            await mcpServer.connect(transport);
+            req.on("close", () => transports.delete(transport.sessionId));
+        }
+        catch (err) {
+            console.error("SSE connection failed:", err);
+            if (!res.headersSent)
+                res.status(500).end();
+        }
+    });
+    app.post("/message", async (req, res) => {
+        const sessionId = req.query.sessionId;
+        const transport = transports.get(sessionId);
+        if (!transport) {
+            res.status(404).json({ error: "Session not found" });
+            return;
+        }
+        try {
+            await transport.handlePostMessage(req, res);
+        }
+        catch (err) {
+            console.error("Message handling failed:", err);
+            if (!res.headersSent)
+                res.status(500).end();
+        }
+    });
+    app.get("/health", (_req, res) => {
+        res.json({ status: "ok", pluginConnected: bridge.connected });
+    });
+    app.listen(MCP_PORT, "127.0.0.1", () => {
+        console.log("Claude FigJam MCP server running");
+        console.log(`  MCP (SSE):  http://localhost:${MCP_PORT}/sse`);
+        console.log(`  WebSocket:  ws://localhost:${WS_PORT}`);
+        console.log(`  Health:     http://localhost:${MCP_PORT}/health`);
+    });
+}

package/dist/setup.js

@@ -0,0 +1,75 @@
+import fs from "fs";
+import path from "path";
+import readline from "readline";
+export async function setup() {
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+    });
+    const question = (q) => new Promise((resolve) => rl.question(q, resolve));
+    console.log("");
+    console.log("Claude FigJam — Setup");
+    console.log("─────────────────────────────────────────");
+    console.log("Configures Claude Code to use the FigJam");
+    console.log("MCP server for live board editing.");
+    console.log("");
+    const defaultDir = process.cwd();
+    const answer = await question(`Claude Code project directory\n  [${defaultDir}]: `);
+    const projectDir = path.resolve(answer.trim() || defaultDir);
+    rl.close();
+    if (!fs.existsSync(projectDir)) {
+        console.error(`\nDirectory not found: ${projectDir}`);
+        process.exit(1);
+    }
+    // Write .mcp.json (merge with existing)
+    const mcpPath = path.join(projectDir, ".mcp.json");
+    let mcpConfig = {};
+    if (fs.existsSync(mcpPath)) {
+        try {
+            mcpConfig = JSON.parse(fs.readFileSync(mcpPath, "utf8"));
+        }
+        catch {
+            console.error(`\nCould not parse existing ${mcpPath} — aborting to avoid overwriting it.`);
+            process.exit(1);
+        }
+    }
+    const command = process.platform === "win32" ? "npx.cmd" : "npx";
+    const servers = mcpConfig.mcpServers ?? {};
+    mcpConfig.mcpServers = {
+        ...servers,
+        "claude-figjam": {
+            command,
+            args: ["claude-figjam", "--stdio"],
+        },
+    };
+    fs.writeFileSync(mcpPath, JSON.stringify(mcpConfig, null, 2) + "\n");
+    console.log(`\n  ✓ ${mcpPath}`);
+    // Write .claude/settings.local.json (merge with existing)
+    const claudeDir = path.join(projectDir, ".claude");
+    if (!fs.existsSync(claudeDir)) {
+        fs.mkdirSync(claudeDir, { recursive: true });
+    }
+    const settingsPath = path.join(claudeDir, "settings.local.json");
+    let settings = {};
+    if (fs.existsSync(settingsPath)) {
+        try {
+            settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+        }
+        catch {
+            console.error(`\nCould not parse existing ${settingsPath} — aborting to avoid overwriting it.`);
+            process.exit(1);
+        }
+    }
+    settings.enableAllProjectMcpServers = true;
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+    console.log(`  ✓ ${settingsPath}`);
+    console.log("");
+    console.log("Setup complete.");
+    console.log("");
+    console.log("Next steps:");
+    console.log("  1. Install the Claude FigJam plugin from Figma Community");
+    console.log("  2. Open Claude Code in your project directory");
+    console.log("  3. Send any message — the MCP server starts automatically");
+    console.log("  4. Open a FigJam file and run the plugin — it connects within 3 seconds");
+    console.log("");
+}

package/dist/tools.js

@@ -0,0 +1,249 @@
+import { z } from "zod";
+// Exported for tests
+export const createNodeSchema = z.object({
+    type: z.enum(["sticky", "shape", "text", "section", "table", "code_block"]),
+    content: z.string().optional(),
+    x: z.number().optional(),
+    y: z.number().optional(),
+    width: z.number().optional(),
+    height: z.number().optional(),
+    color: z.string().optional(),
+    shape: z
+        .enum([
+        "square",
+        "rectangle",
+        "ellipse",
+        "diamond",
+        "triangle",
+        "parallelogram",
+        "star",
+        "cross",
+    ])
+        .optional(),
+    rows: z.number().int().positive().optional(),
+    cols: z.number().int().positive().optional(),
+    code: z.string().optional(),
+    language: z.string().optional(),
+});
+export const createConnectorSchema = z.object({
+    from_id: z.string(),
+    to_id: z.string(),
+    style: z.enum(["straight", "elbowed", "curved"]).optional(),
+    label: z.string().optional(),
+    arrow: z.enum(["forward", "back", "both", "none"]).optional(),
+});
+export const updateNodeSchema = z.object({
+    node_id: z.string(),
+    content: z.string().optional(),
+    x: z.number().optional(),
+    y: z.number().optional(),
+    width: z.number().optional(),
+    height: z.number().optional(),
+    color: z.string().optional(),
+});
+export const deleteNodesSchema = z.object({
+    node_ids: z.union([z.string(), z.array(z.string())]),
+});
+export function registerTools(server, bridge) {
+    server.tool("figjam_read_board", "Returns full board state: all nodes with IDs, types, positions, content, and colors.", {}, async () => {
+        try {
+            const result = await bridge.execute("read_board", {});
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(result, null, 2) },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                isError: true,
+                content: [{ type: "text", text: message }],
+            };
+        }
+    });
+    server.tool("figjam_create_node", "Creates any FigJam node (sticky, shape, text, section, table, code_block). Returns the new node ID.", {
+        type: z.enum([
+            "sticky",
+            "shape",
+            "text",
+            "section",
+            "table",
+            "code_block",
+        ]),
+        content: z.string().optional().describe("Text content"),
+        x: z.number().optional().describe("Canvas x position"),
+        y: z.number().optional().describe("Canvas y position"),
+        width: z.number().optional(),
+        height: z.number().optional(),
+        color: z.string().optional().describe("Hex color"),
+        shape: z
+            .enum([
+            "square",
+            "rectangle",
+            "ellipse",
+            "diamond",
+            "triangle",
+            "parallelogram",
+            "star",
+            "cross",
+        ])
+            .optional()
+            .describe("Required when type=shape"),
+        rows: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Required when type=table"),
+        cols: z
+            .number()
+            .int()
+            .positive()
+            .optional()
+            .describe("Required when type=table"),
+        code: z.string().optional().describe("Code content when type=code_block"),
+        language: z
+            .string()
+            .optional()
+            .describe("Language identifier when type=code_block, e.g. typescript"),
+    }, async (params) => {
+        try {
+            const result = await bridge.execute("create_node", params);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result) }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                isError: true,
+                content: [{ type: "text", text: message }],
+            };
+        }
+    });
+    server.tool("figjam_create_connector", "Draws a connector (arrow/line) between two existing nodes by their IDs.", {
+        from_id: z.string().describe("Source node ID"),
+        to_id: z.string().describe("Target node ID"),
+        style: z
+            .enum(["straight", "elbowed", "curved"])
+            .optional()
+            .describe("Line style, default: elbowed"),
+        label: z
+            .string()
+            .optional()
+            .describe("Optional text at connector midpoint"),
+        arrow: z
+            .enum(["forward", "back", "both", "none"])
+            .optional()
+            .describe("Arrow direction, default: forward"),
+    }, async (params) => {
+        try {
+            const result = await bridge.execute("create_connector", params);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result) }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                isError: true,
+                content: [{ type: "text", text: message }],
+            };
+        }
+    });
+    server.tool("figjam_update_node", "Edit any property of an existing node. Pass only the fields that need to change.", {
+        node_id: z.string().describe("ID of the node to update"),
+        content: z.string().optional(),
+        x: z.number().optional(),
+        y: z.number().optional(),
+        width: z.number().optional(),
+        height: z.number().optional(),
+        color: z.string().optional().describe("Hex color"),
+    }, async (params) => {
+        try {
+            const result = await bridge.execute("update_node", params);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result) }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                isError: true,
+                content: [{ type: "text", text: message }],
+            };
+        }
+    });
+    server.tool("figjam_delete_nodes", "Removes one or more nodes by ID. Accepts a single ID string or array of IDs.", {
+        node_ids: z
+            .union([z.string(), z.array(z.string())])
+            .describe("Node ID or array of IDs to delete"),
+    }, async (params) => {
+        try {
+            const result = await bridge.execute("delete_nodes", params);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result) }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                isError: true,
+                content: [{ type: "text", text: message }],
+            };
+        }
+    });
+    server.tool("figjam_list_pages", "Returns all pages in the FigJam file with their IDs, names, and which one is currently active.", {}, async () => {
+        try {
+            const result = await bridge.execute("list_pages", {});
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(result, null, 2) },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                isError: true,
+                content: [{ type: "text", text: message }],
+            };
+        }
+    });
+    server.tool("figjam_switch_page", "Switches the active FigJam page by name or ID. After switching, figjam_read_board will return the new page's content.", {
+        name: z.string().optional().describe("Page name to switch to"),
+        id: z.string().optional().describe("Page ID to switch to"),
+    }, async (params) => {
+        try {
+            const result = await bridge.execute("switch_page", params);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result) }],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                isError: true,
+                content: [{ type: "text", text: message }],
+            };
+        }
+    });
+    server.tool("figjam_get_selection", "Returns the nodes currently selected on the FigJam canvas.", {}, async () => {
+        try {
+            const result = await bridge.execute("get_selection", {});
+            return {
+                content: [
+                    { type: "text", text: JSON.stringify(result, null, 2) },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                isError: true,
+                content: [{ type: "text", text: message }],
+            };
+        }
+    });
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "claude-figjam",
+  "version": "1.0.0",
+  "description": "MCP server for live FigJam board editing from Claude Code",
+  "type": "module",
+  "bin": {
+    "claude-figjam": "dist/cli.js"
+  },
+  "files": [
+    "dist/"
+  ],
+  "keywords": [
+    "claude",
+    "mcp",
+    "figjam",
+    "figma",
+    "claude-code"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ABCreativeDesign/figma-plugins.git",
+    "directory": "claude-figjam/mcp-server"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "node --experimental-vm-modules node_modules/.bin/jest"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "express": "^4.18.0",
+    "ws": "^8.16.0",
+    "zod": "^3.22.0"
+  },
+  "devDependencies": {
+    "@types/express": "^4.17.0",
+    "@types/ws": "^8.5.10",
+    "@types/node": "^20.0.0",
+    "typescript": "^5.4.0",
+    "jest": "^29.7.0",
+    "@types/jest": "^29.5.0",
+    "ts-jest": "^29.1.0",
+    "tsx": "^4.7.0"
+  }
+}