figmanage 1.2.9 → 1.3.0

package/README.md

@@ -49,23 +49,25 @@ figmanage runs as an MCP server for Claude, ChatGPT, Cursor, and other AI assist
 
 ```bash
 # Claude Code
-claude mcp add figmanage -- npx -y figmanage --mcp
+claude mcp add figmanage -- npx -y figmanage
 
-# Claude Desktop / Cowork
-# Add to claude_desktop_config.json:
+# Claude Desktop / Cursor / other clients
+# Add to your MCP config:
 {
   "mcpServers": {
     "figmanage": {
       "command": "npx",
-      "args": ["-y", "figmanage", "--mcp"]
+      "args": ["-y", "figmanage"]
     }
   }
 }
 ```
 
-Credentials are read from `~/.config/figmanage/` (set up via `figmanage login`). Env vars (`FIGMA_PAT`, `FIGMA_AUTH_COOKIE`, etc.) override the config file for backwards compatibility.
+On first run, figmanage walks you through setup right in the conversation -- extracts your Chrome session cookie, asks you to create a PAT, and stores credentials locally. No env vars, no JSON editing, no separate terminal step.
 
-MCP mode exposes all 85 tools to the AI assistant. HTTP transport available via `--mcp --http <port>`.
+If you prefer CLI setup or need to reconfigure: `npx figmanage login`.
+
+Env vars (`FIGMA_PAT`, `FIGMA_AUTH_COOKIE`, etc.) override the config file for backwards compatibility. HTTP transport available via `--mcp --http <port>`.
 
 ### toolset presets (MCP only)
 
@@ -87,9 +89,9 @@ figmanage uses two Figma API surfaces:
 | Internal API | Session cookie | Workspace management, search, permissions, org admin, seats, billing |
 | Public API | Personal Access Token | Comments, export, file reading, components, versions, webhooks, variables |
 
-Cookie auth unlocks all 85 tools. PAT-only gives ~30 (reading, comments, export, components). Both together is recommended.
+Both together give full access to all 85 tools. Cookie-only or PAT-only work but limit available tools.
 
-Auth resolution: env vars > config file > prompt to run `figmanage login`.
+Auth resolution: env vars > config file > interactive setup (MCP) or `figmanage login` (CLI).
 
 ## commands
 

package/dist/mcp.js

@@ -5,6 +5,7 @@ import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { loadAuthConfig, hasPat, hasCookie } from './auth/client.js';
 import { registerTools } from './tools/register.js';
+import { registerSetupTools } from './tools/setup.js';
 // Import tool modules (side-effect: registers via defineTool)
 import './tools/navigate.js';
 import './tools/files.js';
@@ -64,16 +65,27 @@ export async function startMcpServer() {
     const config = loadAuthConfig();
     const readOnly = process.env.FIGMA_READ_ONLY === '1' || process.env.FIGMA_READ_ONLY === 'true';
     const enabledToolsets = parseToolsets(process.env.FIGMA_TOOLSETS);
-    if (!hasPat(config) && !hasCookie(config)) {
-        console.error('No auth configured. Set FIGMA_PAT for public API access, or ' +
-            'FIGMA_AUTH_COOKIE + FIGMA_USER_ID for internal API access.');
-        process.exit(1);
-    }
     const server = new McpServer({
         name: 'figmanage',
         version: '0.1.0',
     });
-    registerTools(server, config, enabledToolsets, readOnly);
+    const fullyConfigured = hasPat(config) && hasCookie(config);
+    if (fullyConfigured) {
+        registerTools(server, config, enabledToolsets, readOnly);
+    }
+    else {
+        // No auth or partial auth: register setup tools.
+        // If env vars provide some auth, also register whatever tools are available.
+        if (hasPat(config) || hasCookie(config)) {
+            registerTools(server, config, enabledToolsets, readOnly);
+        }
+        registerSetupTools(server, () => {
+            // Re-load config after setup wrote credentials to disk
+            const newConfig = loadAuthConfig();
+            registerTools(server, newConfig, enabledToolsets, readOnly);
+            server.server.sendToolListChanged();
+        });
+    }
     const httpPort = parseHttpPort(process.argv);
     if (httpPort) {
         // Bearer token auth for HTTP transport

package/dist/tools/setup.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Interactive setup tools for first-run MCP configuration.
+ *
+ * Guides the user through cookie extraction and PAT creation
+ * via conversational tool calls. Registered when auth is missing;
+ * replaced by the full toolset once setup completes.
+ */
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function registerSetupTools(server: McpServer, onSetupComplete: () => void): void;
+//# sourceMappingURL=setup.d.ts.map

package/dist/tools/setup.js

@@ -0,0 +1,181 @@
+/**
+ * Interactive setup tools for first-run MCP configuration.
+ *
+ * Guides the user through cookie extraction and PAT creation
+ * via conversational tool calls. Registered when auth is missing;
+ * replaced by the full toolset once setup completes.
+ */
+import { platform } from 'node:os';
+import { z } from 'zod';
+import { extractCookies, validateSession, validatePat, resolveAccountInfo, } from '../auth/cookie.js';
+import { setActiveWorkspace, getActiveWorkspace } from '../config.js';
+import { loadAuthConfig, hasPat, hasCookie } from '../auth/client.js';
+// State shared across setup steps within a single session
+let pendingAccounts = [];
+export function registerSetupTools(server, onSetupComplete) {
+    server.tool('setup_status', 'Check figmanage authentication status and get setup instructions. Always call this before using any other tool.', {}, async () => {
+        const config = loadAuthConfig();
+        if (hasPat(config) && hasCookie(config)) {
+            return { content: [{ type: 'text', text: 'figmanage is fully configured. All tools are available.' }] };
+        }
+        const os = platform();
+        const lines = [
+            'figmanage needs two credentials to give you full access to all 85 Figma workspace tools:',
+            '',
+            '1. Browser cookie -- extracted automatically from Chrome',
+            '2. Personal Access Token (PAT) -- created in Figma settings',
+            '',
+        ];
+        if (!hasCookie(config)) {
+            lines.push('NEXT: Cookie extraction');
+            lines.push('The user must be logged into figma.com in Chrome before proceeding.');
+            if (os === 'darwin') {
+                lines.push('');
+                lines.push('When they proceed, a macOS Keychain prompt will appear asking to access');
+                lines.push('"Chrome Safe Storage". They need to click Allow.');
+            }
+            else if (os === 'linux') {
+                lines.push('');
+                lines.push('On Linux, Chrome cookies are decrypted using the system keyring or a default key.');
+            }
+            lines.push('');
+            lines.push('Ask the user to confirm they are logged into figma.com in Chrome, then call setup_extract_cookies.');
+        }
+        else {
+            lines.push('Cookie auth is configured.');
+            lines.push('');
+            lines.push('NEXT: Personal Access Token');
+            lines.push('Ask the user to create a PAT at: https://www.figma.com/settings');
+            lines.push('(Security > Personal access tokens)');
+            lines.push('Then call setup_save_pat with the token value.');
+        }
+        return { content: [{ type: 'text', text: lines.join('\n') }] };
+    });
+    server.tool('setup_extract_cookies', 'Extract Figma session cookies from Chrome. On macOS this triggers a Keychain prompt. IMPORTANT: Before calling, confirm the user is logged into figma.com in Chrome and knows a system prompt may appear.', {}, async () => {
+        try {
+            const accounts = extractCookies();
+            if (accounts.length === 0) {
+                return {
+                    content: [{
+                            type: 'text',
+                            text: 'No Figma cookies found in Chrome. The user needs to log into figma.com in Chrome first, then try again.',
+                        }],
+                };
+            }
+            pendingAccounts = accounts;
+            const infos = await Promise.all(accounts.map(a => resolveAccountInfo(a)));
+            const lines = [
+                `Found ${accounts.length} Figma account${accounts.length > 1 ? 's' : ''}:`,
+                '',
+            ];
+            for (let i = 0; i < accounts.length; i++) {
+                const info = infos[i];
+                const label = info.figmaEmail || `User ${accounts[i].userId}`;
+                lines.push(`  ${i + 1}. ${label} (Chrome profile: ${info.profileName})`);
+            }
+            lines.push('');
+            lines.push('Ask the user which account to use, then call setup_select_account with the chosen number.');
+            return { content: [{ type: 'text', text: lines.join('\n') }] };
+        }
+        catch (e) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: `Cookie extraction failed: ${e.message}` }],
+            };
+        }
+    });
+    server.tool('setup_select_account', 'Select a Figma account and validate the session. Call after setup_extract_cookies.', {
+        account_index: z.number().int().min(1).describe('Account number from the list returned by setup_extract_cookies'),
+    }, async ({ account_index }) => {
+        if (pendingAccounts.length === 0) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: 'No accounts available. Call setup_extract_cookies first.' }],
+            };
+        }
+        const idx = account_index - 1;
+        if (idx < 0 || idx >= pendingAccounts.length) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: `Invalid selection. Choose 1-${pendingAccounts.length}.` }],
+            };
+        }
+        const account = pendingAccounts[idx];
+        try {
+            const session = await validateSession(account.cookieValue, account.userId);
+            let orgId = session.orgId;
+            if (!orgId && session.orgs.length > 0) {
+                orgId = session.orgs[0].id;
+            }
+            const workspaceName = orgId || account.userId || 'default';
+            setActiveWorkspace(workspaceName, {
+                cookie: account.cookieValue,
+                user_id: account.userId,
+                org_id: orgId || undefined,
+                cookie_extracted_at: new Date().toISOString(),
+            });
+            const lines = [`Session valid (user ${account.userId}).`];
+            if (session.orgs.length > 0) {
+                const orgName = session.orgs.find(o => o.id === orgId)?.name;
+                lines.push(`Workspace: ${orgName ? `${orgName} (${orgId})` : orgId}`);
+            }
+            if (session.teams.length > 0) {
+                lines.push(`Teams: ${session.teams.map(t => t.name).join(', ')}`);
+            }
+            lines.push('');
+            lines.push('Cookie saved. Now need a Personal Access Token for full access.');
+            lines.push('Ask the user to create one at: https://www.figma.com/settings');
+            lines.push('(Security > Personal access tokens)');
+            lines.push('Then call setup_save_pat with the token.');
+            return { content: [{ type: 'text', text: lines.join('\n') }] };
+        }
+        catch (e) {
+            const status = e.response?.status;
+            if (status === 401 || status === 403) {
+                return {
+                    isError: true,
+                    content: [{ type: 'text', text: 'Cookie expired or invalid. Log into figma.com in Chrome and run setup_extract_cookies again.' }],
+                };
+            }
+            return {
+                isError: true,
+                content: [{ type: 'text', text: `Session validation failed: ${e.message}` }],
+            };
+        }
+    });
+    server.tool('setup_save_pat', 'Validate and save a Figma Personal Access Token. Completes setup and activates all tools.', {
+        pat: z.string().min(1).describe('Figma Personal Access Token (starts with figd_)'),
+    }, async ({ pat }) => {
+        try {
+            const patUser = await validatePat(pat);
+            // Update the active workspace with the PAT
+            const workspace = getActiveWorkspace();
+            if (!workspace) {
+                return {
+                    isError: true,
+                    content: [{ type: 'text', text: 'No workspace configured. Run setup_extract_cookies and setup_select_account first.' }],
+                };
+            }
+            workspace.pat = pat;
+            const workspaceName = workspace.org_id || workspace.user_id || 'default';
+            setActiveWorkspace(workspaceName, workspace);
+            // Clear setup state
+            pendingAccounts = [];
+            // Trigger full tool registration
+            onSetupComplete();
+            return {
+                content: [{
+                        type: 'text',
+                        text: `PAT valid (${patUser}). Setup complete -- all 85 figmanage tools are now available.`,
+                    }],
+            };
+        }
+        catch {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: 'PAT invalid or expired. Check the token and try again.' }],
+            };
+        }
+    });
+}
+//# sourceMappingURL=setup.js.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "figmanage",
   "mcpName": "io.github.dannykeane/figmanage",
-  "version": "1.2.9",
+  "version": "1.3.0",
   "description": "MCP server for managing your Figma workspace from the terminal.",
   "type": "module",
   "main": "dist/index.js",