figma-mcp-downloader 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuichiroh Arai
+
+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,117 @@
+# figma-mcp-downloader
+
+CLI for saving Figma MCP tool results to local files.
+
+> [!IMPORTANT]
+> This documentation is written exclusively for AI agents with access to the Figma MCP tool schema.
+
+## Prerequisites
+
+- Figma **Desktop** app must be running (Local MCP server starts automatically)
+
+## Installation
+
+```bash
+npm install -g figma-mcp-downloader
+```
+
+Or run directly with `npx`:
+
+```bash
+npx figma-mcp-downloader <subcommand> [options]
+```
+
+## Subcommands and MCP Tool Mapping
+
+Subcommands share the same names as MCP tools.
+
+| Subcommand           | MCP Tool             |
+| -------------------- | -------------------- |
+| `get_design_context` | `get_design_context` |
+| `get_metadata`       | `get_metadata`       |
+
+> [!NOTE]  
+> Other Figma MCP tools (e.g., `get_screenshot`, `get_variable_defs`) are not currently supported by this CLI.
+
+```bash
+npx figma-mcp-downloader [subcommand] <output-file> [options]
+```
+
+## Common Arguments/Options
+
+> [!IMPORTANT]  
+> Options without descriptions are identical to the corresponding Figma MCP tool parameters. Refer to the Figma MCP tool schema for details.  
+> The MCP response contains multiple content items: the first is the generated JSX code or XML, and the rest are supplementary AI guidance. Use `-c` to extract only the JSX code or XML.
+
+| Argument/Option                        | Figma MCP Parameter | Description                                                         |
+| -------------------------------------- | ------------------- | ------------------------------------------------------------------- |
+| `<output-file>`                        | -                   | Output file path                                                    |
+| `-c, --content-only`                   | -                   | Save only the first text content (JSX code or XML)                  |
+| `-i, --node-id <id>`                   | `nodeId`            | The ID of the node in the Figma document.                           |
+| `-l, --client-languages <languages>`   | `clientLanguages`   | A comma separated list of programming languages used by the client. |
+| `-f, --client-frameworks <frameworks>` | `clientFrameworks`  | A comma separated list of frameworks used by the client             |
+
+> [!NOTE]  
+> Both `-l` and `-f` options are used for logging purposes to understand which languages and frameworks are being used. Specify them based on available context, but omit them if unsure.
+
+## get_design_context
+
+Get the design context for a layer or selection and save the full JSON response from the MCP tool to a file.
+
+```bash
+npx figma-mcp-downloader get_design_context <output-file> [options]
+```
+
+> [!IMPORTANT]  
+> This CLI always sets `forceCode` to `true` when calling the MCP tool.
+
+| Argument/Option              | Figma MCP Parameter | Description                                             |
+| ---------------------------- | ------------------- | ------------------------------------------------------- |
+| `-a, --artifact-type <type>` | `artifactType`      | The type of artifact the user is creating or modifying. |
+| `-t, --task-type <type>`     | `taskType`          | The type of task being performed.                       |
+
+> [!NOTE]  
+> Valid values for `-a`: `WEB_PAGE_OR_APP_SCREEN`, `COMPONENT_WITHIN_A_WEB_PAGE_OR_APP_SCREEN`, `REUSABLE_COMPONENT`, `DESIGN_SYSTEM`  
+> Valid values for `-t`: `CREATE_ARTIFACT`, `CHANGE_ARTIFACT`, `DELETE_ARTIFACT`
+
+### Examples
+
+```bash
+# With -c: saves JSX only
+npx figma-mcp-downloader get_design_context design_context.jsx -i "123:456" -c -l typescript -f react,tailwindcss
+# Without -c: saves full JSON response
+npx figma-mcp-downloader get_design_context design_context.json -i "123:456" -l html,css,javascript -f vue
+```
+
+## get_metadata
+
+Get the sparse XML representation for a layer or selection and save the full JSON response from the MCP tool to a file.
+
+```bash
+npx figma-mcp-downloader get_metadata <output-file> [options]
+```
+
+### Examples
+
+```bash
+# With -c: saves XML only
+npx figma-mcp-downloader get_metadata metadata.xml -i "123:456" -c -l typescript -f react,tailwindcss
+# Without -c: saves full JSON response
+npx figma-mcp-downloader get_metadata metadata.json -i "123:456" -l html,css,javascript -f vue
+```
+
+## Environment Variables
+
+The MCP server URL can be configured via environment variables.
+
+| Variable        | Description    | Default                     |
+| --------------- | -------------- | --------------------------- |
+| `FIGMA_MCP_URL` | MCP server URL | `http://127.0.0.1:3845/mcp` |
+
+```bash
+# PowerShell
+$env:FIGMA_MCP_URL="http://localhost:4000/mcp"; npx figma-mcp-downloader get_design_context design_context.jsx -c
+
+# Linux/Mac
+FIGMA_MCP_URL="http://localhost:4000/mcp" npx figma-mcp-downloader get_metadata metadata.xml -c
+```

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+import { registerGetDesignContextCommand } from "./get_design_context.js";
+import { registerGetMetadataCommand } from "./get_metadata.js";
+const program = new Command();
+program
+    .name("figma-mcp-downloader")
+    .description("CLI tool to download design data from Figma MCP Server")
+    .version("0.1.0");
+registerGetDesignContextCommand(program);
+registerGetMetadataCommand(program);
+program.parse();

package/dist/get_design_context.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerGetDesignContextCommand(program: Command): void;

package/dist/get_design_context.js

@@ -0,0 +1,66 @@
+import { addCommonOptions, closeMcpTransport, createMcpClient, handleError, saveResult, } from "./utils.js";
+const VALID_ARTIFACT_TYPES = [
+    "WEB_PAGE_OR_APP_SCREEN",
+    "COMPONENT_WITHIN_A_WEB_PAGE_OR_APP_SCREEN",
+    "REUSABLE_COMPONENT",
+    "DESIGN_SYSTEM",
+];
+const VALID_TASK_TYPES = [
+    "CREATE_ARTIFACT",
+    "CHANGE_ARTIFACT",
+    "DELETE_ARTIFACT",
+];
+export function registerGetDesignContextCommand(program) {
+    addCommonOptions(program
+        .command("get_design_context")
+        .description("Get the design context for a layer or selection and save the full JSON response from the MCP tool to a file.")
+        .argument("<output-file>", "Output file path, e.g., design_context.jsx, design_context.json")
+        .option("-a, --artifact-type <type>", `The type of artifact the user is creating or modifying. Valid values: ${VALID_ARTIFACT_TYPES.join(", ")}`)
+        .option("-t, --task-type <type>", `The type of task being performed. Valid values: ${VALID_TASK_TYPES.join(", ")}`)).action(async (outputFile, options) => {
+        const nodeId = options.nodeId;
+        // Validate artifactType
+        if (options.artifactType &&
+            !VALID_ARTIFACT_TYPES.includes(options.artifactType)) {
+            console.error(`❌ Error: Invalid artifact type: ${options.artifactType}`);
+            console.log("\nValid artifact types:");
+            VALID_ARTIFACT_TYPES.forEach((type) => console.log(`  - ${type}`));
+            process.exit(1);
+        }
+        // Validate taskType
+        if (options.taskType &&
+            !VALID_TASK_TYPES.includes(options.taskType)) {
+            console.error(`❌ Error: Invalid task type: ${options.taskType}`);
+            console.log("\nValid task types:");
+            VALID_TASK_TYPES.forEach((type) => console.log(`  - ${type}`));
+            process.exit(1);
+        }
+        const { client, transport } = await createMcpClient("design-context");
+        try {
+            console.log(`\n🎨 Getting design context for Node ID: ${nodeId || "(selected)"}...`);
+            const result = await client.callTool({
+                name: "get_design_context",
+                arguments: {
+                    nodeId: nodeId,
+                    forceCode: true,
+                    ...(options.artifactType && {
+                        artifactType: options.artifactType,
+                    }),
+                    ...(options.taskType && { taskType: options.taskType }),
+                    ...(options.clientLanguages && {
+                        clientLanguages: options.clientLanguages,
+                    }),
+                    ...(options.clientFrameworks && {
+                        clientFrameworks: options.clientFrameworks,
+                    }),
+                },
+            });
+            saveResult(result, outputFile, options.contentOnly ?? false, nodeId || "(selected)", options.force ?? false);
+        }
+        catch (error) {
+            handleError(error);
+        }
+        finally {
+            await closeMcpTransport(transport);
+        }
+    });
+}

package/dist/get_metadata.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function registerGetMetadataCommand(program: Command): void;

package/dist/get_metadata.js

@@ -0,0 +1,32 @@
+import { addCommonOptions, closeMcpTransport, createMcpClient, handleError, saveResult, } from "./utils.js";
+export function registerGetMetadataCommand(program) {
+    addCommonOptions(program
+        .command("get_metadata")
+        .description("Get the sparse XML representation for a layer or selection and save the full JSON response from the MCP tool to a file.")
+        .argument("<output-file>", "Output file path, e.g., metadata.xml, metadata.json")).action(async (outputFile, options) => {
+        const nodeId = options.nodeId;
+        const { client, transport } = await createMcpClient("metadata");
+        try {
+            console.log(`\n📋 Getting metadata for Node ID: ${nodeId || "(selected)"}...`);
+            const result = await client.callTool({
+                name: "get_metadata",
+                arguments: {
+                    ...(nodeId && { nodeId: nodeId }),
+                    ...(options.clientLanguages && {
+                        clientLanguages: options.clientLanguages,
+                    }),
+                    ...(options.clientFrameworks && {
+                        clientFrameworks: options.clientFrameworks,
+                    }),
+                },
+            });
+            saveResult(result, outputFile, options.contentOnly ?? false, nodeId || "(selected)", options.force ?? false);
+        }
+        catch (error) {
+            handleError(error);
+        }
+        finally {
+            await closeMcpTransport(transport);
+        }
+    });
+}

package/dist/types.d.ts

@@ -0,0 +1,7 @@
+export interface ContentItem {
+    type: string;
+    text?: string;
+}
+export interface ToolResult {
+    content: ContentItem[];
+}

package/dist/types.js

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

package/dist/utils.d.ts

@@ -0,0 +1,23 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { Command } from "commander";
+import { ToolResult } from "./types.js";
+export declare const FIGMA_MCP_URL: string;
+export declare function createMcpClient(scriptName: string): Promise<{
+    client: Client;
+    transport: StreamableHTTPClientTransport;
+}>;
+export declare function closeMcpTransport(transport: StreamableHTTPClientTransport): Promise<void>;
+export declare function saveResult(result: ToolResult, outputFile: string, contentOnly: boolean, nodeIdLabel: string, force?: boolean): boolean;
+export declare function handleError(error: unknown): void;
+export interface CommonOptions {
+    nodeId?: string;
+    clientLanguages: string;
+    clientFrameworks: string;
+    contentOnly?: boolean;
+    force?: boolean;
+}
+/**
+ * 共通オプションをコマンドに追加する
+ */
+export declare function addCommonOptions(command: Command): Command;

package/dist/utils.js

@@ -0,0 +1,84 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import * as fs from "fs";
+import * as path from "path";
+// Requires Figma desktop app to be running
+// Can be overridden with FIGMA_MCP_URL environment variable
+export const FIGMA_MCP_URL = process.env.FIGMA_MCP_URL || "http://127.0.0.1:3845/mcp";
+export async function createMcpClient(scriptName) {
+    const transport = new StreamableHTTPClientTransport(new URL(FIGMA_MCP_URL));
+    const client = new Client({ name: `${scriptName}-script`, version: "1.0.0" }, { capabilities: {} });
+    console.log("🔌 Connecting to Figma MCP Server...");
+    await client.connect(transport);
+    console.log("✅ Connected!");
+    return { client, transport };
+}
+export async function closeMcpTransport(transport) {
+    try {
+        await transport.close();
+        console.log("\n🔌 Disconnected from server");
+    }
+    catch {
+        // Ignore close errors
+    }
+}
+export function saveResult(result, outputFile, contentOnly, nodeIdLabel, force = false) {
+    const savePath = path.resolve(process.cwd(), outputFile);
+    const cwd = process.cwd();
+    // Prevent path traversal attacks: ensure savePath is within cwd
+    // Skip check if --force is used
+    if (!force) {
+        const relativePath = path.relative(cwd, savePath);
+        if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+            console.error(`❌ Error: Output path must be within the current working directory.`);
+            console.error(`   Attempted path: ${savePath}`);
+            console.error(`   Current directory: ${cwd}`);
+            console.error(`   Use --force to bypass this check only if explicitly permitted by the user.`);
+            process.exitCode = 1;
+            return false;
+        }
+    }
+    const dir = path.dirname(savePath);
+    // Create directory if it doesn't exist
+    if (!fs.existsSync(dir)) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+    let saved = false;
+    if (contentOnly) {
+        // --content-only: Find the first type="text" item in the array and save it
+        for (const item of result.content) {
+            if (item.type === "text" && item.text) {
+                fs.writeFileSync(savePath, item.text, "utf-8");
+                console.log(`💾 Saved: ${savePath}`);
+                saved = true;
+                break;
+            }
+        }
+        if (!saved) {
+            console.warn(`⚠️  No text data returned for ${nodeIdLabel}`);
+            process.exitCode = 1;
+        }
+    }
+    else {
+        // Default: Save the full JSON response
+        fs.writeFileSync(savePath, JSON.stringify(result, null, 2), "utf-8");
+        console.log(`💾 Saved: ${savePath}`);
+        saved = true;
+    }
+    return saved;
+}
+export function handleError(error) {
+    console.error("❌ Error:", error instanceof Error ? error.message : error);
+    process.exitCode = 1;
+}
+/**
+ * 共通オプションをコマンドに追加する
+ */
+export function addCommonOptions(command) {
+    return command
+        .option("-i, --node-id <id>", 'The ID of the node in the Figma document, eg. "123:456" or "123-456"')
+        .option("-c, --content-only", "Save only the first text content, not the full JSON response")
+        .option("-l, --client-languages <languages>", "A comma separated list of programming languages used by the client in the current context", "unknown")
+        .option("-f, --client-frameworks <frameworks>", "A comma separated list of frameworks used by the client in the current context", "unknown")
+        .option("--force", "Allow writing outside the current working directory. Do not use unless explicitly permitted by the user.");
+}

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "figma-mcp-downloader",
+  "version": "1.0.0",
+  "description": "CLI for saving Figma MCP tool results to local files",
+  "author": "Yuichiroh Arai",
+  "license": "MIT",
+  "type": "module",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "bin": {
+    "figma-mcp-downloader": "dist/cli.js"
+  },
+  "scripts": {
+    "build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc",
+    "dev": "bun --watch src/cli.ts"
+  },
+  "keywords": [
+    "figma",
+    "mcp",
+    "cli",
+    "design",
+    "download",
+    "model-context-protocol"
+  ],
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/yuichiroharai/figma-mcp-downloader.git"
+  },
+  "homepage": "https://github.com/yuichiroharai/figma-mcp-downloader#readme",
+  "bugs": {
+    "url": "https://github.com/yuichiroharai/figma-mcp-downloader/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.24.1",
+    "commander": "^14.0.2"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.2",
+    "@types/node": "^24.10.1",
+    "eslint": "^9.39.2",
+    "globals": "^16.5.0",
+    "prettier": "^3.7.4",
+    "prettier-plugin-organize-imports": "^4.3.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.49.0"
+  },
+  "volta": {
+    "node": "24.12.0"
+  }
+}