figma-mcp-server 0.0.0-alpha.1 → 0.1.0-beta.1

package/Dockerfile

@@ -0,0 +1,9 @@
+FROM node:22.12-alpine AS builder
+
+WORKDIR /app
+COPY package.json package-lock.json ./
+RUN npm install
+
+COPY . .
+
+ENTRYPOINT ["node", "mcpServer.js"]

package/LICENSE

@@ -0,0 +1,19 @@
+MIT License
+
+Copyright (c) 2025 Abhimanyu Rana @planetabhi
+
+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, and/or publish 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

@@ -1,69 +1,42 @@
 # Figma MCP Server
+MCP server for Figma
 
-### 📥 Installation & Setup
-
-**1. Install dependencies**
-
-Run from your project's root directory:
-
-```sh
-npm install
-```
-
-### 🔐 Set tool environment variables
-
-In the `.env` file, you'll see environment variable placeholders, one for each workspace that the selected tools are from. For example, if you selected requests from 2 workspaces, e.g. Acme and Widgets, you'll see two placeholders:
+### Set tool environment variables
+In the `.env` file, set the `FIGMA_API_KEY` to your Figma API key.
 
 ```
-ACME_API_KEY=
-WIDGETS_API_KEY=
+FIGMA_API_KEY=
 ```
 
-Update the values with actual API keys for each API. These environment variables are used inside of the generated tools to set the API key for each request. You can inspect a file in the `tools` directory to see how it works.
-
-```javascript
-// environment variables are used inside of each tool file
-const apiKey = process.env.ACME_API_KEY;
-```
-
-**Caveat:** This may not be correct for every API. The generation logic is relatively simple - for each workspace, we create an environment variable with the same name as the workspace slug, and then use that environment variable in each tool file that belongs to that workspace. If this isn't the right behavior for your chosen API, no problem! You can manually update anything in the `.env` file or tool files to accurately reflect the API's method of authentication.
-
-### 🛠️ List Available Tools
-
-List descriptions and parameters from all generated tools with:
+### Install
+Install the server
 
 ```sh
-node index.js tools
+git clone https://github.com/planetabhi/figma-mcp-server.git
+cd figma-mcp-server
+pnpm i
 ```
 
-Example:
+### List Figma Tools
+List descriptions and parameters from all available Figma tools
 
-```
-Available Tools:
-
-Workspace: acme-workspace
-  Collection: useful-api
-    list_all_customers
-      Description: Retrieve a list of useful things.
-      Parameters:
-        - magic: The required magic power
-        - limit: Number of results returned
-        [...additional parameters...]
+```sh
+pnpm list-tools
 ```
 
-## 🌐 Running the MCP Server
+## Run the MCP Server
 
-The MCP Server (`mcpServer.js`) exposes your automated API tools to MCP-compatible clients, such as Claude Desktop or the Postman Desktop Application.
+The MCP Server (`mcpServer.js`) exposes your Figma API tools to MCP-compatible clients.
 
-### A) 🖥️ Run with Postman
+### Run with Postman
 
-The Postman Desktop Application is the easiest way to run and test MCP servers.
+Postman desktop app is the easiest way to run and test MCP servers.
 
-Step 1: Download the latest Postman Desktop Application from [https://www.postman.com/downloads/](https://www.postman.com/downloads/).
+Step 1: Download the latest Postman app from [https://www.postman.com/downloads/](https://www.postman.com/downloads/).
 
 Step 2: Read out the documentation article [here](https://learning.postman.com/docs/postman-ai-agent-builder/mcp-requests/overview/) for the next steps.
 
-### B) 👩‍💻 Run with Claude Desktop
+### Run with Claude Desktop
 
 To integrate with Claude Desktop:
 
@@ -96,7 +69,7 @@ Restart Claude Desktop to activate this change.
 
 ### Additional Options
 
-#### 🐳 Docker Deployment (Production)
+#### Docker Deployment (Production)
 
 For production deployments, you can use Docker:
 
@@ -123,41 +96,10 @@ Add Docker server configuration to Claude Desktop (Settings → Developers → E
 
 > Add your environment variables (API keys, etc.) inside the `.env` file.
 
-#### 🌐 Server-Sent Events (SSE)
+#### Server-Sent Events (SSE)
 
 To run the server with Server-Sent Events (SSE) support, use the `--sse` flag:
 
 ```sh
 node mcpServer.js --sse
-```
-
-## 🐳 Dockerfile (Included)
-
-The project comes bundled with the following minimal Docker setup:
-
-```dockerfile
-FROM node:22.12-alpine AS builder
-
-WORKDIR /app
-COPY package.json package-lock.json ./
-RUN npm install
-
-COPY . .
-
-ENTRYPOINT ["node", "mcpServer.js"]
-```
-
-## ➕ Adding New Tools
-
-Extend your agent with more tools easily:
-
-1. Visit [Postman Agent Generator](https://postman.com/explore/agent-generator).
-2. Pick new API request(s), generate a new agent, and download it.
-3. Copy new generated tool(s) into your existing project's `tools/` folder.
-4. Update your `tools/paths.js` file to include new tool references.
-
-## 💬 Questions & Support
-
-Visit the [Postman Agent Generator](https://postman.com/explore/agent-generator) page for updates and new capabilities.
-
-Visit the [Postman Community](https://community.postman.com/) to share what you've built, ask questions and get help.
+```

package/commands/tools.js

@@ -0,0 +1,65 @@
+import { discoverTools } from "../lib/tools.js";
+
+export function registerToolsCommand(program) {
+  program
+    .command("tools")
+    .description("List all available API tools")
+    .action(async () => {
+      const tools = await discoverTools();
+      if (tools.length === 0) {
+        console.log("No tools found. Tools should be organized as:");
+        console.log("tools/workspace/collection/request.js\n");
+        return;
+      }
+
+      console.log("\nAvailable Tools:\n");
+
+      // Group tools by workspace/collection
+      const groupedTools = tools.reduce((acc, tool) => {
+        // Extract workspace and collection from path
+        const parts = tool.path.split("/");
+        const workspace = parts[1] || "Unknown Workspace";
+        const collection = parts[2] || "Unknown Collection";
+
+        if (!acc[workspace]) acc[workspace] = {};
+        if (!acc[workspace][collection]) acc[workspace][collection] = [];
+
+        acc[workspace][collection].push(tool);
+        return acc;
+      }, {});
+
+      // Print tools in a hierarchical structure
+      for (const [workspace, collections] of Object.entries(groupedTools)) {
+        console.log(`Workspace: ${workspace}`);
+        for (const [collection, tools] of Object.entries(collections)) {
+          console.log(`  Collection: ${collection}`);
+          tools.forEach(
+            ({
+              definition: {
+                function: { name, description, parameters },
+              },
+            }) => {
+              console.log(`    ${name}`);
+              console.log(
+                `      Description: ${description || "No description provided"}`
+              );
+              if (parameters?.properties) {
+                console.log("      Parameters:");
+                Object.entries(parameters.properties).forEach(
+                  ([name, details]) => {
+                    console.log(
+                      `        - ${name}: ${
+                        details.description || "No description"
+                      }`
+                    );
+                  }
+                );
+              }
+              console.log("");
+            }
+          );
+        }
+        console.log("");
+      }
+    });
+}

package/lib/tools.js

@@ -0,0 +1,16 @@
+import { toolPaths } from "../tools/paths.js";
+
+/**
+ * Discovers and loads available tools from the tools directory
+ * @returns {Promise<Array>} Array of tool objects
+ */
+export async function discoverTools() {
+  const toolPromises = toolPaths.map(async (file) => {
+    const module = await import(`../tools/${file}`);
+    return {
+      ...module.apiTool,
+      path: file,
+    };
+  });
+  return Promise.all(toolPromises);
+}

package/mcpServer.js

@@ -0,0 +1,145 @@
+#!/usr/bin/env node
+import dotenv from "dotenv";
+import express from "express";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
+import {
+  CallToolRequestSchema,
+  ErrorCode,
+  ListToolsRequestSchema,
+  McpError,
+} from "@modelcontextprotocol/sdk/types.js";
+import { discoverTools } from "./lib/tools.js";
+
+import path from "path";
+import { fileURLToPath } from "url";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+dotenv.config({ path: path.resolve(__dirname, ".env") });
+
+const SERVER_NAME = "generated-mcp-server";
+
+async function transformTools(tools) {
+  return tools
+    .map((tool) => {
+      const definitionFunction = tool.definition?.function;
+      if (!definitionFunction) return;
+      return {
+        name: definitionFunction.name,
+        description: definitionFunction.description,
+        inputSchema: definitionFunction.parameters,
+      };
+    })
+    .filter(Boolean);
+}
+
+async function run() {
+  const args = process.argv.slice(2);
+  const isSSE = args.includes("--sse");
+
+  const server = new Server(
+    {
+      name: SERVER_NAME,
+      version: "0.1.0",
+    },
+    {
+      capabilities: {
+        tools: {},
+      },
+    }
+  );
+
+  server.onerror = (error) => console.error("[Error]", error);
+
+  // Gracefully shutdown on SIGINT
+  process.on("SIGINT", async () => {
+    await server.close();
+    process.exit(0);
+  });
+
+  const tools = await discoverTools();
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: await transformTools(tools),
+  }));
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const toolName = request.params.name;
+    const tool = tools.find((t) => t.definition.function.name === toolName);
+
+    if (!tool) {
+      throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${toolName}`);
+    }
+
+    const args = request.params.arguments;
+    const requiredParameters =
+      tool.definition?.function?.parameters?.required || [];
+
+    for (const requiredParameter of requiredParameters) {
+      if (!(requiredParameter in args)) {
+        throw new McpError(
+          ErrorCode.InvalidParams,
+          `Missing required parameter: ${requiredParameter}`
+        );
+      }
+    }
+
+    try {
+      const result = await tool.function(args);
+      return {
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(result, null, 2),
+          },
+        ],
+      };
+    } catch (error) {
+      console.error("[Error] Failed to fetch data:", error);
+      throw new McpError(
+        ErrorCode.InternalError,
+        `API error: ${error.message}`
+      );
+    }
+  });
+
+  if (isSSE) {
+    const app = express();
+    const transports = {};
+
+    app.get("/sse", async (_req, res) => {
+      const transport = new SSEServerTransport("/messages", res);
+      transports[transport.sessionId] = transport;
+
+      res.on("close", () => {
+        delete transports[transport.sessionId];
+      });
+
+      await server.connect(transport);
+    });
+
+    app.post("/messages", async (req, res) => {
+      const sessionId = req.query.sessionId;
+      const transport = transports[sessionId];
+
+      if (transport) {
+        await transport.handlePostMessage(req, res);
+      } else {
+        res.status(400).send("No transport found for sessionId");
+      }
+    });
+
+    const port = process.env.PORT || 3001;
+    app.listen(port, () => {
+      console.log(`[SSE Server] running on port ${port}`);
+    });
+  } else {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+  }
+}
+
+run().catch(console.error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "figma-mcp-server",
-  "version": "0.0.0-alpha.1",
+  "version": "0.1.0-beta.1",
   "description": "MCP server for Figma",
   "main": "index.js",
   "type": "module",
@@ -24,7 +24,12 @@
   ],
   "author": "@planetabhi",
   "license": "MIT",
-  "files": [
-    "README.md"
-  ]
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/planetabhi/figma-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/planetabhi/figma-mcp-server/issues"
+  },
+  "homepage": "https://github.com/planetabhi/figma-mcp-server#readme"
 }

package/tools/figma/figma-api/add-webhook.js

@@ -0,0 +1,57 @@
+/**
+ * Function to add a webhook in Figma.
+ *
+ * @returns {Promise<Object>} - The result of the webhook addition.
+ */
+const executeFunction = async () => {
+  const webhookUrl = 'https://api.figma.com/v2/webhooks';
+  const token = process.env.FIGMA_API_KEY;
+  try {
+    // Set up headers for the request
+    const headers = {
+      'X-Figma-Token': token,
+      'Content-Type': 'application/json'
+    };
+
+    // Perform the fetch request
+    const response = await fetch(webhookUrl, {
+      method: 'POST',
+      headers
+    });
+
+    // Check if the response was successful
+    if (!response.ok) {
+      const errorData = await response.json();
+      throw new Error(errorData);
+    }
+
+    // Parse and return the response data
+    const data = await response.json();
+    return data;
+  } catch (error) {
+    console.error('Error adding webhook:', error);
+    return { error: 'An error occurred while adding the webhook.' };
+  }
+};
+
+/**
+ * Tool configuration for adding a webhook in Figma.
+ * @type {Object}
+ */
+const apiTool = {
+  function: executeFunction,
+  definition: {
+    type: 'function',
+    function: {
+      name: 'add_webhook',
+      description: 'Add a webhook in Figma.',
+      parameters: {
+        type: 'object',
+        properties: {},
+        required: []
+      }
+    }
+  }
+};
+
+export { apiTool };

package/tools/figma/figma-api/create-variable-collection.js

@@ -0,0 +1,84 @@
+/**
+ * Function to create a variable collection in Figma.
+ *
+ * @param {Object} args - Arguments for creating the variable collection.
+ * @param {string} args.file_key - The key of the Figma file where the variable collection will be created.
+ * @param {string} args.name - The name of the new variable collection to be created.
+ * @returns {Promise<Object>} - The result of the variable collection creation.
+ */
+const executeFunction = async ({ file_key, name }) => {
+  const baseUrl = 'https://api.figma.com/v1';
+  const token = process.env.FIGMA_API_KEY;
+
+  try {
+    // Construct the URL for the request
+    const url = `${baseUrl}/files/${file_key}/variables`;
+
+    // Set up headers for the request
+    const headers = {
+      'X-Figma-Token': token,
+      'Content-Type': 'application/json'
+    };
+
+    // Create the request body
+    const body = JSON.stringify({
+      variableCollections: [
+        {
+          action: 'CREATE',
+          name: name
+        }
+      ]
+    });
+
+    // Perform the fetch request
+    const response = await fetch(url, {
+      method: 'POST',
+      headers,
+      body
+    });
+
+    // Check if the response was successful
+    if (!response.ok) {
+      const errorData = await response.json();
+      throw new Error(errorData);
+    }
+
+    // Parse and return the response data
+    const data = await response.json();
+    return data;
+  } catch (error) {
+    console.error('Error creating variable collection:', error);
+    return { error: 'An error occurred while creating the variable collection.' };
+  }
+};
+
+/**
+ * Tool configuration for creating a variable collection in Figma.
+ * @type {Object}
+ */
+const apiTool = {
+  function: executeFunction,
+  definition: {
+    type: 'function',
+    function: {
+      name: 'create_variable_collection',
+      description: 'Create a new variable collection in Figma.',
+      parameters: {
+        type: 'object',
+        properties: {
+          file_key: {
+            type: 'string',
+            description: 'The key of the Figma file where the variable collection will be created.'
+          },
+          name: {
+            type: 'string',
+            description: 'The name of the new variable collection to be created.'
+          }
+        },
+        required: ['file_key', 'name']
+      }
+    }
+  }
+};
+
+export { apiTool };

package/tools/figma/figma-api/delete-webhook.js

@@ -0,0 +1,64 @@
+/**
+ * Function to delete a specific webhook from Figma.
+ *
+ * @param {Object} args - Arguments for the deletion.
+ * @param {string} args.webhook_id - The ID of the webhook to delete.
+ * @returns {Promise<Object>} - The result of the deletion operation.
+ */
+const executeFunction = async ({ webhook_id }) => {
+  const baseUrl = 'https://api.figma.com/v1';
+  const token = process.env.FIGMA_API_KEY;
+  const webhookUrl = `${baseUrl}/webhooks/${webhook_id}`;
+
+  try {
+    // Set up headers for the request
+    const headers = {
+      'X-Figma-Token': token
+    };
+
+    // Perform the fetch request
+    const response = await fetch(webhookUrl, {
+      method: 'DELETE',
+      headers
+    });
+
+    // Check if the response was successful
+    if (!response.ok) {
+      const errorData = await response.json();
+      throw new Error(errorData);
+    }
+
+    // Return the response data (should be empty for successful deletion)
+    return {};
+  } catch (error) {
+    console.error('Error deleting webhook:', error);
+    return { error: 'An error occurred while deleting the webhook.' };
+  }
+};
+
+/**
+ * Tool configuration for deleting a webhook from Figma.
+ * @type {Object}
+ */
+const apiTool = {
+  function: executeFunction,
+  definition: {
+    type: 'function',
+    function: {
+      name: 'delete_webhook',
+      description: 'Delete a specific webhook from Figma.',
+      parameters: {
+        type: 'object',
+        properties: {
+          webhook_id: {
+            type: 'string',
+            description: 'The ID of the webhook to delete.'
+          }
+        },
+        required: ['webhook_id']
+      }
+    }
+  }
+};
+
+export { apiTool };

package/tools/figma/figma-api/get-actions-analytics.js

@@ -0,0 +1,67 @@
+/**
+ * Function to get actions analytics for a specific library file in Figma.
+ *
+ * @param {Object} args - Arguments for the request.
+ * @param {string} args.library_file_key - The key of the library file for which to retrieve actions analytics.
+ * @returns {Promise<Object>} - The actions analytics related to the library file.
+ */
+const executeFunction = async ({ library_file_key }) => {
+  const baseUrl = 'https://api.figma.com/v1';
+  const token = process.env.FIGMA_API_KEY;
+
+  try {
+    // Construct the URL for the request
+    const url = `${baseUrl}/analytics/libraries/${library_file_key}/actions`;
+
+    // Set up headers for the request
+    const headers = {
+      'X-Figma-Token': token
+    };
+
+    // Perform the fetch request
+    const response = await fetch(url, {
+      method: 'GET',
+      headers
+    });
+
+    // Check if the response was successful
+    if (!response.ok) {
+      const errorData = await response.json();
+      throw new Error(errorData);
+    }
+
+    // Parse and return the response data
+    const data = await response.json();
+    return data;
+  } catch (error) {
+    console.error('Error getting actions analytics:', error);
+    return { error: 'An error occurred while retrieving actions analytics.' };
+  }
+};
+
+/**
+ * Tool configuration for getting actions analytics for a library file in Figma.
+ * @type {Object}
+ */
+const apiTool = {
+  function: executeFunction,
+  definition: {
+    type: 'function',
+    function: {
+      name: 'get_actions_analytics',
+      description: 'Retrieve actions analytics for a specific library file in Figma.',
+      parameters: {
+        type: 'object',
+        properties: {
+          library_file_key: {
+            type: 'string',
+            description: 'The key of the library file for which to retrieve actions analytics.'
+          }
+        },
+        required: ['library_file_key']
+      }
+    }
+  }
+};
+
+export { apiTool };