figma-mcp-setup 1.0.0

package/README.md

@@ -0,0 +1,145 @@
+# Figma MCP Setup
+
+<div align="center">
+  <img src="https://img.shields.io/npm/v/figma-mcp-setup" alt="NPM Version" />
+  <img src="https://img.shields.io/badge/UI-Clack-blue?color=0023d7" alt="Clack UI" />
+  <img src="https://img.shields.io/badge/Security-Strict-success" alt="Security Validated" />
+</div>
+
+<br />
+
+**If you use `figma-mcp-setup`, you will instantly secure and scaffold your AI agent's connection to Figma's Dev Mode without manual configuration or risking credential theft.**
+
+> **Created by Muhaideen Nausar**
+
+---
+
+## 🚀 The Quick Win: Getting Started
+
+### The Pitch
+`figma-mcp-setup` is a secure, interactive CLI tool that bootstraps a Figma Model Context Protocol (MCP) server for your AI agents. It handles the secure storage of your Personal Access Token (PAT) and configuration mapping in seconds, so you can focus on building agents, not configuring them.
+
+### Installation
+You need **Node.js v18+** installed. You can run the CLI directly without installing it globally:
+
+```bash
+npx figma-mcp-setup
+```
+
+### The "Hello World" Example
+To get your AI agent ready to talk to Figma:
+1. Open your terminal in your project's root folder.
+2. Run `npx figma-mcp-setup`.
+3. Paste your Figma Personal Access Token when prompted.
+4. The CLI will automatically create a secure `.agents/mcp_config.json` and update your `.gitignore`.
+
+### Key Limitations & Prerequisites
+- **API Key Required**: You must have a Figma Personal Access Token (PAT).
+
+**How to get your Figma PAT:**
+1. Log in to your Figma account on the web or desktop app.
+2. Click your profile picture in the top-left corner and select **Settings**.
+3. Navigate to the **Personal access tokens** section.
+4. Click **Generate new token**.
+5. Give it a name (e.g., "AI Agent MCP") and ensure it has the appropriate read permissions for your files.
+6. Copy the generated token immediately. It will start with `figd_`.
+
+---
+
+## 📚 The Mechanics: Reference Manual
+
+While primarily a CLI tool, `figma-mcp-setup` is built with modularity in mind. Below is the API reference for the core internal mechanics, useful for developers wishing to contribute or extend the package programmatically.
+
+### `initCommand()`
+- **Description**: The primary entry point for the CLI tool. Orchestrates the prompts, file system hardening, and config generation.
+- **Parameters**: None.
+- **Return Value**: `Promise<void>`.
+- **Error Handling**: Catches internal errors, stops the UI spinner, and gracefully exits the process with a clean `cancel()` message to the terminal.
+
+### `promptForToken()`
+- **Description**: Securely prompts the user for their Figma PAT using masked terminal inputs.
+- **Parameters**: None.
+- **Return Value**: `Promise<string>` - Resolves to the validated token string.
+- **Error Handling**: Returns validation errors in the UI if the token is empty or does not strictly match the `^figd_[a-zA-Z0-9\-_]+$` regex.
+
+### `mergeFigmaConfig(configPath: string, token: string)`
+- **Description**: Merges the Figma MCP configuration into the target JSON file without overwriting existing unrelated server configurations.
+- **Parameters**:
+  - `configPath` (type: `string`, required): Absolute path to the `mcp_config.json` file.
+  - `token` (type: `string`, required): The validated Figma PAT.
+- **Return Value**: `void`.
+- **Error Handling**: Throws a security error if the target path is a symlink (preventing arbitrary file overwrite). Throws a `SyntaxError` if the existing JSON is corrupted.
+
+### `ensureAgentsFolder(cwd: string)`
+- **Description**: Scaffolds the `.agents` folder and enforces strict POSIX security.
+- **Parameters**:
+  - `cwd` (type: `string`, required): The current working directory.
+- **Return Value**: `void`.
+- **Error Handling**: Throws if `.agents` is a symlink or if it exists but is not a directory. Safely catches `ENOENT` to create the directory with `0o700` permissions.
+
+---
+
+## ⚙️ How the MCP Server JSON Works (Under the Hood)
+
+You might be wondering: *"How does generating a JSON file actually run a server?"*
+
+When `figma-mcp-setup` completes, it generates a `.agents/mcp_config.json` file that looks something like this:
+
+```json
+{
+  "mcpServers": {
+    "figma-dev-mode-mcp-server": {
+      "command": "npx",
+      "args": ["-y", "figma-developer-mcp", "--stdio"],
+      "env": {
+        "FIGMA_API_KEY": "figd_YourSecureTokenHere"
+      }
+    }
+  }
+}
+```
+
+Here is exactly what happens when your AI Agent (the **MCP Client**) reads this file:
+
+1. **The Execution**: The AI agent sees the `"command": "npx"` and uses Node.js to dynamically download and execute the `figma-developer-mcp` package. *(Note: This is an external third-party package maintained by the community, not part of this CLI tool.)*
+2. **The Connection (`--stdio`)**: It launches this package as a background child process and communicates with it via standard input and output streams (`stdio`).
+3. **The Authentication**: It securely passes your `FIGMA_API_KEY` into the environment variables of that child process.
+4. **The Interaction**: When the AI agent wants to read a Figma file, it sends a JSON-RPC message over `stdio`. The `figma-developer-mcp` server receives the message, uses your PAT to make a REST API call to Figma's servers, and returns the real-time Dev Mode data back to the AI.
+
+---
+
+## 💡 Advanced Use Cases & Tutorials
+
+### How to Automate Figma AI Agent Setup
+If you are deploying a template repository for AI agents, you can instruct your users to run `npx figma-mcp-setup` as part of your repository setup scripts.
+1. Add `"setup": "npx figma-mcp-setup"` to your `package.json` scripts.
+2. When developers clone your repository and run `npm run setup`, the CLI will automatically trigger, prompting them for their Figma PAT.
+3. The secure `.agents/mcp_config.json` is instantly generated and ready for your local LLM runner (like Claude Desktop) to consume.
+
+### Best Practice: Integrating the MCP Config into Your AI Agents
+Once `figma-mcp-setup` completes, it generates an `mcp_config.json` file. 
+**Best Practice:** Do not read this file directly into your application bundle or version control. Instead, configure your MCP client (like Claude Desktop or a custom LangChain agent) to point directly to the `.agents/mcp_config.json` file path. The CLI has already secured this file with strict `0o600` permissions, ensuring only the active system user can read it.
+
+---
+
+## 🩹 Maintenance & Ecosystem
+
+### FAQ & Troubleshooting
+
+**Q: I'm getting an "Invalid token format" error.**
+- **Cause**: You pasted an OAuth token or an invalid string.
+- **Fix**: Ensure your token was generated directly from Figma's "Personal access tokens" settings. It must begin with exactly `figd_`.
+
+**Q: I see a "Security Alert: .agents is a symlink" error.**
+- **Cause**: The CLI detected that `.agents` is a symbolic link. This is a severe security risk.
+- **Fix**: Delete the existing `.agents` symlink (`rm -rf .agents`) and run the setup again to let the CLI create a secure, genuine directory.
+
+### Contributing
+We welcome contributions! To get started:
+1. Clone the repository and run `npm install`.
+2. The codebase is written in TypeScript. Core logic is split between `src/commands` and `src/services`.
+3. To test your changes locally, run `npm run build` followed by `node dist/index.js`.
+4. **Security Policy**: Please ensure all new file system operations include strict symlink checks and permission constraints (e.g., `0o600` for files).
+
+### Versioning
+We follow Semantic Versioning (SemVer). Breaking changes will be clearly documented in the GitHub Releases page. Every major version (e.g., v2.0) will include a "Breaking Changes" guide so users are never surprised.

package/bin/cli.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../dist/index.js';

package/dist/commands/init.js

@@ -0,0 +1,38 @@
+import { appendToGitignore, ensureAgentsFolder, getConfigPath, configExists, mergeFigmaConfig } from '../services/fileSystem.js';
+import { promptForToken, promptForMerge } from '../services/prompts.js';
+import { intro, outro, spinner, cancel, note } from '@clack/prompts';
+import chalk from 'chalk';
+import figlet from 'figlet';
+export async function initCommand() {
+    const brandColor = chalk.hex('#0023d7');
+    console.clear();
+    console.log('\n' + brandColor(figlet.textSync('Figma MCP')));
+    console.log(brandColor('                             by Muhaideen Nausar\n'));
+    intro(chalk.inverse(' Setup Figma MCP Server '));
+    const cwd = process.cwd();
+    const token = await promptForToken();
+    const configPath = getConfigPath(cwd);
+    if (configExists(configPath)) {
+        const shouldMerge = await promptForMerge();
+        if (!shouldMerge) {
+            cancel('Setup aborted by user.');
+            process.exit(0);
+        }
+    }
+    const s = spinner();
+    s.start('Configuring secure environment');
+    try {
+        ensureAgentsFolder(cwd);
+        mergeFigmaConfig(configPath, token);
+        appendToGitignore(cwd);
+        s.stop('Environment configured successfully');
+    }
+    catch (error) {
+        s.stop('Failed to configure environment');
+        cancel(error.message);
+        process.exit(1);
+    }
+    note('Figma MCP Server configuration added securely!\n' +
+        'The .agents directory is isolated and ignored by git.', 'Success');
+    outro(brandColor('You are all set!'));
+}

package/dist/constants/configTemplate.js

@@ -0,0 +1,11 @@
+export const FIGMA_MCP_CONFIG = {
+    "command": "npx",
+    "args": [
+        "-y",
+        "figma-developer-mcp",
+        "--stdio"
+    ],
+    "env": {
+        "FIGMA_API_KEY": "YOUR_TOKEN_HERE"
+    }
+};

package/dist/index.js

@@ -0,0 +1,12 @@
+import { initCommand } from './commands/init.js';
+import { cancel } from '@clack/prompts';
+async function main() {
+    try {
+        await initCommand();
+    }
+    catch (error) {
+        cancel(error instanceof Error ? error.message : String(error));
+        process.exit(1);
+    }
+}
+main();

package/dist/services/fileSystem.js

@@ -0,0 +1,100 @@
+import fs from 'fs';
+import path from 'path';
+import { FIGMA_MCP_CONFIG } from '../constants/configTemplate.js';
+export function appendToGitignore(cwd) {
+    const gitignorePath = path.join(cwd, '.gitignore');
+    try {
+        const stats = fs.lstatSync(gitignorePath);
+        if (stats.isSymbolicLink()) {
+            console.warn('Security Warning: .gitignore is a symlink. Skipping modification to prevent arbitrary file overwrite.');
+            return;
+        }
+        const content = fs.readFileSync(gitignorePath, 'utf-8');
+        const lines = content.split(/\r?\n/).map(l => l.trim());
+        const isIgnored = lines.some(l => l === '.agents' || l === '.agents/' || l === '/.agents' || l === '/.agents/');
+        if (!isIgnored) {
+            const trailingNewline = content.length === 0 || content.endsWith('\n') || content.endsWith('\r');
+            const toAppend = trailingNewline ? '.agents\n' : '\n.agents\n';
+            fs.appendFileSync(gitignorePath, toAppend);
+        }
+    }
+    catch (e) {
+        if (e.code === 'ENOENT') {
+            fs.writeFileSync(gitignorePath, '.agents\n');
+        }
+        else {
+            throw e;
+        }
+    }
+}
+export function ensureAgentsFolder(cwd) {
+    const agentsPath = path.join(cwd, '.agents');
+    try {
+        const stats = fs.lstatSync(agentsPath);
+        if (stats.isSymbolicLink()) {
+            throw new Error('Security Alert: .agents is a symlink. Path traversal attack prevented.');
+        }
+        if (!stats.isDirectory()) {
+            throw new Error('Security Alert: .agents exists but is not a directory.');
+        }
+        // Restrict permissions even if folder already existed
+        fs.chmodSync(agentsPath, 0o700);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT') {
+            fs.mkdirSync(agentsPath, { recursive: true, mode: 0o700 });
+            // chmodSync ensures the 0o700 mode is properly applied regardless of umask
+            fs.chmodSync(agentsPath, 0o700);
+        }
+        else {
+            throw e;
+        }
+    }
+}
+export function getConfigPath(cwd) {
+    return path.join(cwd, '.agents', 'mcp_config.json');
+}
+export function configExists(configPath) {
+    try {
+        const stats = fs.lstatSync(configPath);
+        return stats.isFile(); // Ignore symlinks or directories
+    }
+    catch (e) {
+        return false;
+    }
+}
+export function mergeFigmaConfig(configPath, token) {
+    let config = { mcpServers: {} };
+    try {
+        const stats = fs.lstatSync(configPath);
+        if (stats.isSymbolicLink()) {
+            throw new Error('Security Alert: mcp_config.json is a symlink. Path traversal attack prevented.');
+        }
+        const content = fs.readFileSync(configPath, 'utf-8');
+        config = JSON.parse(content);
+        if (!config.mcpServers) {
+            config.mcpServers = {};
+        }
+    }
+    catch (e) {
+        if (e.code === 'ENOENT') {
+            // File doesn't exist, proceed with empty config
+        }
+        else if (e.name === 'SyntaxError') {
+            console.error('Error parsing existing mcp_config.json. Overwriting might corrupt data.');
+            throw new Error('Failed to parse existing mcp_config.json');
+        }
+        else {
+            throw e; // Bubble up unexpected errors
+        }
+    }
+    // Inject token into template
+    const figmaConfig = JSON.parse(JSON.stringify(FIGMA_MCP_CONFIG));
+    figmaConfig.env.FIGMA_API_KEY = token;
+    // Merge
+    config.mcpServers['figma-dev-mode-mcp-server'] = figmaConfig;
+    // Write back securely
+    fs.writeFileSync(configPath, JSON.stringify(config, null, 2) + '\n', { mode: 0o600 });
+    // chmodSync ensures correct permissions if file already existed with wider permissions
+    fs.chmodSync(configPath, 0o600);
+}

package/dist/services/prompts.js

@@ -0,0 +1,30 @@
+import { password, confirm, isCancel, cancel } from '@clack/prompts';
+export async function promptForToken() {
+    const token = await password({
+        message: 'Enter your Figma Personal Access Token (PAT):',
+        validate: (input) => {
+            if (!input || input.trim() === '') {
+                return 'Token cannot be empty.';
+            }
+            if (!/^figd_[a-zA-Z0-9\-_]+$/.test(input.trim())) {
+                return 'Invalid token format. Figma PATs must start with "figd_" followed by alphanumeric characters.';
+            }
+        }
+    });
+    if (isCancel(token)) {
+        cancel('Operation cancelled.');
+        process.exit(0);
+    }
+    return token.trim();
+}
+export async function promptForMerge() {
+    const shouldMerge = await confirm({
+        message: 'Found existing mcp_config.json. Merge Figma configuration into it?',
+        initialValue: true
+    });
+    if (isCancel(shouldMerge)) {
+        cancel('Operation cancelled.');
+        process.exit(0);
+    }
+    return shouldMerge;
+}

package/dist/types/index.js

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

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "figma-mcp-setup",
+  "version": "1.0.0",
+  "description": "Interactive CLI tool to instantly scaffold a secure Figma MCP server configuration for your AI agents.",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "figma-mcp-setup": "bin/cli.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run"
+  },
+  "keywords": [
+    "figma",
+    "mcp",
+    "model-context-protocol",
+    "cli",
+    "ai",
+    "agent"
+  ],
+  "author": "Muhaideen Nausar",
+  "license": "ISC",
+  "dependencies": {
+    "@clack/prompts": "^1.6.0",
+    "chalk": "^5.6.2",
+    "figlet": "^1.11.0"
+  },
+  "devDependencies": {
+    "@types/figlet": "^1.7.0",
+    "@types/node": "^26.1.0",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.9"
+  }
+}