zapcode-figma-mcp 1.0.0 → 1.0.3

package/README.md

@@ -0,0 +1,112 @@
+Generated markdown
+
+# Zapcode Figma MCP Server
+
+[![npm version](https://img.shields.io/npm/v/zapcode-figma-mcp.svg)](https://www.npmjs.com/package/zapcode-figma-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+This package provides a Model Context Protocol (MCP) server that acts as a bridge between your **Figma designs** and any **MCP-compatible AI client** (like Claude for Desktop, Open WebUI, etc.).
+
+When invoked by an AI model, this server connects to the Zapcode Figma plugin to retrieve real-time context from your selected Figma frame, including its HTML/CSS structure, a generated image, and any exportable SVG assets.
+
+## ✨ Features
+
+- **Real-time Context**: Fetches live data directly from your currently selected frame in Figma.
+- **Rich Information**: Provides the LLM with rich context of the frame.
+- **Automatic Asset Handling**: Automatically extracts any SVG assets from the selection, saves them to your local workspace, and informs the LLM of their location.
+- **Easy Integration**: Runs as a simple command-line tool and can be easily configured with any MCP client.
+
+## 📋 Prerequisites
+
+1.  **Node.js**: You must have Node.js (v16 or higher) installed to use `npx`. You can download it from [nodejs.org](https://nodejs.org/).
+2.  [**Zapcode Figma Plugin**](https://www.figma.com/community/plugin/1454956820198178710/zapcode): You must have the Zapcode plugin installed and running in your Figma desktop application.
+
+## 🚀 Installation & Usage
+
+You can run this server directly from the npm registry without a manual installation using `npx`.
+
+## Integration with an MCP Client
+
+This is the most common use case. You configure your client to launch the server automatically. Below are examples for common clients.
+
+### Generic MCP Client Configuration
+
+For clients that use a similar JSON configuration, the structure is the same. This server does not require any environment variables.
+
+```json
+{
+  "mcpServers": {
+    "zapcode-figma-mcp": {
+      "command": "npx",
+      "args": ["zapcode-figma-mcp"]
+    }
+  }
+}
+```
+
+### GitHub Copilot
+
+```json
+{
+  "servers": {
+    "Zapcode stdio mcp": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["zapcode-figma-mcp"]
+    }
+  },
+  "inputs": []
+}
+```
+
+### Claude for Desktop
+
+Open your claude_desktop_config.json file and add the following entry to mcpServers.
+
+macOS/Linux: ~/Library/Application Support/Claude/claude_desktop_config.json
+Windows: %APPDATA%\Claude\claude_desktop_config.json
+
+```json
+{
+  "mcpServers": {
+    "zapcode-figma-mcp": {
+      "command": "npx",
+      "args": ["zapcode-figma-mcp"]
+    }
+  }
+}
+```
+
+**Note:** Restart Claude for Desktop for the changes to take effect.
+
+The server will start and wait for connections from both the Figma plugin and an MCP client.
+
+## 🛠️ Tool Details
+
+This server exposes a single, powerful tool to the LLM.
+
+get_figma_context
+
+- **Description**: Retrieves the selected Figma frame context. Saves any provided SVG assets to the local 'assets/svg' directory.
+- **Input Schema**: {} (No input arguments are required).
+- **Output**: A combination of prompts and Figma context
+
+## ⚠️ Troubleshooting
+
+```error
+Error: Figma plugin is not connected.
+```
+
+This is the most common error. It means the MCP server is running, but it cannot find the Zapcode Figma plugin to talk to.
+Solution: Make sure you have opened Figma and are running the Zapcode plugin on the design file you wish to query.
+
+```error
+Port Conflict / EADDRINUSE Error
+```
+
+If you see an error that the port is already in use, it means another application is using port 3001 or 32896.
+Solution: You need to stop the other application.
+
+## 📄 License
+
+This project is licensed under the MIT License. See the LICENSE.md file for details.

package/build/index.js

@@ -1,43 +1,34 @@
 #!/usr/bin/env node
-import { createServer as createHttpServer, } from "http";
+import { createServer as createHttpServer } from "http";
 import { Server as SocketIOServer } from "socket.io";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
-import { URL } from "url";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import * as fs from "fs";
 import * as path from "path";
-// --- Default Ports ---
+// --- Default Port for Figma Connection ---
 const DEFAULT_FIGMA_SOCKET_IO_PORT = 32896;
-const DEFAULT_MCP_HTTP_PORT = 3001;
-// --- Paths ---
-const MCP_SSE_PATH = "/zapcode-mcp-sse";
-const MCP_MESSAGE_PATH = "/mcp-messages";
-// --- Global Variables ---
+// --- Global Variables for Figma Connection ---
 let figmaHttpServer = null;
 let io = null;
 let connectedFigmaClient = null;
 const figmaContextRequests = new Map();
-const figmaHttpConnections = new Set();
-let mcpHttpServer = null;
-let mcpServerInstance = null;
-const mcpSseTransports = new Map();
 // --- Argument Parsing ---
 function parseArgs() {
     const args = process.argv.slice(2);
-    let mcpPort = DEFAULT_MCP_HTTP_PORT;
-    const portArgIndex = args.findIndex((arg) => arg === "--port" || arg === "-p");
-    if (portArgIndex !== -1 && args[portArgIndex + 1]) {
-        const port = parseInt(args[portArgIndex + 1], 10);
-        if (!isNaN(port)) {
-            mcpPort = port;
-        }
+    let figmaPort = DEFAULT_FIGMA_SOCKET_IO_PORT;
+    const figmaPortArgIndex = args.findIndex((arg) => arg === "--figma-port");
+    if (figmaPortArgIndex !== -1 && args[figmaPortArgIndex + 1]) {
+        const port = parseInt(args[figmaPortArgIndex + 1], 10);
+        if (!isNaN(port))
+            figmaPort = port;
     }
-    return { mcpPort };
+    return { figmaPort };
 }
 // --- Socket.IO Server Logic ---
 function startSocketIOServer(port) {
     return new Promise((resolve, reject) => {
-        console.log(`Attempting to start Socket.IO server for Figma on port ${port}...`);
+        // IMPORTANT: All logging must go to stderr to not interfere with MCP on stdout.
+        console.error(`Zapcode: Attempting to start Socket.IO server for Figma on port ${port}...`);
         try {
             figmaHttpServer = createHttpServer();
             io = new SocketIOServer(figmaHttpServer, {
@@ -45,7 +36,7 @@ function startSocketIOServer(port) {
                 cors: { origin: "*" },
             });
             io.on("connection", (socket) => {
-                console.log(`Figma plugin connected: ${socket.id}`);
+                console.error(`Zapcode: Figma plugin connected: ${socket.id}`);
                 if (connectedFigmaClient) {
                     connectedFigmaClient.disconnect(true);
                 }
@@ -65,38 +56,43 @@ function startSocketIOServer(port) {
                     }
                 });
                 socket.on("disconnect", (reason) => {
-                    console.log(`Figma plugin disconnected: ${socket.id}. Reason: ${reason}`);
+                    console.error(`Zapcode: Figma plugin disconnected: ${socket.id}. Reason: ${reason}`);
                     if (connectedFigmaClient === socket) {
                         connectedFigmaClient = null;
                     }
                 });
-                socket.on("error", (err) => console.error(`Figma Socket.IO error: ${err.message}`));
+                socket.on("error", (err) => console.error(`Zapcode: Figma Socket.IO error: ${err.message}`));
+            });
+            figmaHttpServer.on("error", (err) => {
+                console.error(`Zapcode: Figma HTTP server error: ${err.message}`);
+                reject(err);
             });
             figmaHttpServer.listen(port, () => {
-                console.log(`✅ Figma Socket.IO server listening on port ${port}`);
+                console.error(`Zapcode: ✅ Figma Socket.IO server is listening on port ${port}`);
                 resolve();
             });
         }
         catch (error) {
-            console.error(`Error creating Figma Socket.IO server: ${error}`);
+            console.error(`Zapcode: Error creating Figma Socket.IO server: ${error}`);
             reject(error);
         }
     });
 }
-// --- MCP Server Logic ---
-async function startMcpServer(port) {
-    console.log(`Attempting to start MCP HTTP/SSE server on port ${port}...`);
+// --- MCP Server Logic for Stdio ---
+async function startMcpServer() {
+    console.error("Zapcode: Initializing MCP server for Stdio transport.");
     const serverInfo = {
         name: "zapcode-figma-mcp-server",
         title: "Zapcode Figma MCP",
-        version: "1.0.2",
+        version: "1.0.3", // It's good practice to increment version on significant changes
     };
-    const serverOptions = { capabilities: { tools: {} } };
-    mcpServerInstance = new McpServer(serverInfo, serverOptions);
+    const mcpServerInstance = new McpServer(serverInfo, {
+        capabilities: { tools: {} },
+    });
     mcpServerInstance.tool("get_figma_context", "Retrieves the selected Figma frame context (HTML, CSS, prompt, image, assets). Saves any provided SVG assets to the local 'assets/svg' directory.", {}, async () => {
-        console.log("MCP Tool 'get_figma_context' invoked.");
+        console.error("Zapcode: MCP Tool 'get_figma_context' invoked.");
         if (!connectedFigmaClient?.connected) {
-            console.error("Error: Figma plugin not connected.");
+            console.error("Zapcode: Error - Figma plugin not connected.");
             return {
                 isError: true,
                 content: [
@@ -109,7 +105,7 @@ async function startMcpServer(port) {
         }
         const requestId = `figma-ctx-${Date.now()}`;
         try {
-            console.log(`Emitting 'request_context' to Figma (ID: ${requestId})`);
+            console.error(`Zapcode: Emitting 'request_context' to Figma (ID: ${requestId})`);
             connectedFigmaClient.emit("request_context", { requestId });
             const context = await new Promise((resolve, reject) => {
                 figmaContextRequests.set(requestId, { resolve, reject });
@@ -120,7 +116,7 @@ async function startMcpServer(port) {
                     }
                 }, 30000);
             });
-            console.log("Successfully received context from Figma.");
+            console.error("Zapcode: Successfully received context from Figma.");
             // Save assets to the current working directory
             const workspacePath = process.cwd();
             const assetResults = await saveSvgAssets(context.assets, workspacePath);
@@ -141,7 +137,7 @@ async function startMcpServer(port) {
             return { content: mcpContent };
         }
         catch (error) {
-            console.error(`Error during Figma context request: ${error.message}`);
+            console.error(`Zapcode: Error during Figma context request: ${error.message}`);
             return {
                 isError: true,
                 content: [
@@ -153,38 +149,12 @@ async function startMcpServer(port) {
             };
         }
     });
-    return new Promise((resolve, reject) => {
-        mcpHttpServer = createHttpServer(async (req, res) => {
-            const requestUrl = new URL(req.url || "", `http://${req.headers.host}`);
-            if (req.method === "GET" && requestUrl.pathname === MCP_SSE_PATH) {
-                const transport = new SSEServerTransport(MCP_MESSAGE_PATH, res);
-                mcpSseTransports.set(transport.sessionId, transport);
-                console.log(`New MCP client connected. SessionID: ${transport.sessionId}`);
-                req.socket.on("close", () => mcpSseTransports.delete(transport.sessionId));
-                await mcpServerInstance.connect(transport);
-            }
-            else if (req.method === "POST" &&
-                requestUrl.pathname === MCP_MESSAGE_PATH) {
-                const sessionId = requestUrl.searchParams.get("sessionId");
-                const transport = sessionId
-                    ? mcpSseTransports.get(sessionId)
-                    : undefined;
-                if (transport)
-                    await transport.handlePostMessage(req, res);
-                else
-                    res.writeHead(404).end("Session not found");
-            }
-            else {
-                res.writeHead(404).end("Not Found");
-            }
-        });
-        mcpHttpServer.listen(port, () => {
-            console.log(`✅ MCP HTTP/SSE server listening on http://localhost:${port}${MCP_SSE_PATH}`);
-            resolve();
-        });
-    });
+    // Use the Stdio transport
+    const transport = new StdioServerTransport();
+    await mcpServerInstance.connect(transport);
+    console.error("Zapcode: ✅ MCP server connected and listening on stdio.");
 }
-// --- Utility Functions (modified to remove vscode dependency) ---
+// --- Utility Functions ---
 async function saveSvgAssets(assets, basePath) {
     const savedFiles = [];
     const errors = [];
@@ -214,24 +184,28 @@ async function saveSvgAssets(assets, basePath) {
 }
 // --- Main Execution Logic ---
 async function main() {
-    const { mcpPort } = parseArgs();
-    console.log("Starting Figma MCP Server...");
+    const { figmaPort } = parseArgs();
     try {
-        await startSocketIOServer(DEFAULT_FIGMA_SOCKET_IO_PORT);
-        await startMcpServer(mcpPort);
-        console.log("🚀 All servers are up and running!");
-        console.log("Connect your Figma plugin and an MCP client to begin.");
+        await startSocketIOServer(figmaPort);
+        await startMcpServer();
     }
     catch (error) {
-        console.error("💥 Failed to start servers:", error);
+        console.error("Zapcode: 💥 Failed to start servers:", error);
         process.exit(1);
     }
 }
 // --- Graceful Shutdown ---
 async function shutdown() {
-    console.log("\nGracefully shutting down servers...");
-    // Implement stop functions if needed, or just exit for this simple case
-    process.exit(0);
+    console.error("\nZapcode: Gracefully shutting down...");
+    if (figmaHttpServer) {
+        figmaHttpServer.close(() => {
+            console.error("Zapcode: Figma HTTP server closed.");
+            process.exit(0);
+        });
+    }
+    else {
+        process.exit(0);
+    }
 }
 process.on("SIGINT", shutdown);
 process.on("SIGTERM", shutdown);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "zapcode-figma-mcp",
-    "version": "1.0.0",
+    "version": "1.0.3",
     "description": "An MCP server that exposes Figma context via a plugin and saves assets, from Zapcode.",
     "type": "module",
     "bin": {
@@ -19,7 +19,7 @@
         "zapcode"
     ],
     "author": "Zapcode",
-    "license": "SEE LICENSE IN LICENSE.md",
+    "license": "MIT",
     "files": [
         "build/"
     ],