figmanage 1.2.9 → 1.3.1

package/dist/cli/org.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { listAdmins, listOrgTeams, seatUsage, listTeamMembers, billingOverview, listInvoices, orgDomains, aiCreditUsage, exportMembers, listOrgMembers, contractRates, changeSeat, } from '../operations/org.js';
 import { output, error } from './format.js';
+import { formatApiError } from '../helpers.js';
 import { requireCookie } from './helpers.js';
 export function orgCommand() {
     const org = new Command('org')
@@ -21,7 +22,7 @@ export function orgCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -41,7 +42,7 @@ export function orgCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -61,7 +62,7 @@ export function orgCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -76,7 +77,7 @@ export function orgCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -92,7 +93,7 @@ export function orgCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -108,7 +109,7 @@ export function orgCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -124,7 +125,7 @@ export function orgCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -139,7 +140,7 @@ export function orgCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -155,7 +156,7 @@ export function orgCommand() {
             output({ message: msg }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -175,7 +176,7 @@ export function orgCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -191,7 +192,7 @@ export function orgCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -218,7 +219,7 @@ export function orgCommand() {
             }
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });

package/dist/cli/permissions.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { getPermissions, setPermissions, share, revokeAccess, listRoleRequests, approveRoleRequest, denyRoleRequest, } from '../operations/permissions.js';
 import { output, error } from './format.js';
+import { formatApiError } from '../helpers.js';
 import { requireCookie } from './helpers.js';
 export function permissionsCommand() {
     const permissions = new Command('permissions')
@@ -19,7 +20,7 @@ export function permissionsCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -39,7 +40,7 @@ export function permissionsCommand() {
             output({ message: msg }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -60,7 +61,7 @@ export function permissionsCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -71,6 +72,11 @@ export function permissionsCommand() {
         .action(async (resourceType, resourceId, userId, options) => {
         try {
             const config = requireCookie();
+            const { confirmAction } = await import('./helpers.js');
+            if (!await confirmAction(`Revoke ${userId}'s access to ${resourceType} ${resourceId}?`)) {
+                console.log('Cancelled.');
+                return;
+            }
             const msg = await revokeAccess(config, {
                 resource_type: resourceType,
                 resource_id: resourceId,
@@ -79,7 +85,7 @@ export function permissionsCommand() {
             output({ message: msg }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -94,7 +100,7 @@ export function permissionsCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -109,7 +115,7 @@ export function permissionsCommand() {
             output({ message: msg }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -124,7 +130,7 @@ export function permissionsCommand() {
             output({ message: msg }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });

package/dist/cli/projects.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { createProject, renameProject, moveProject, trashProject, restoreProject, setProjectDescription, } from '../operations/projects.js';
 import { output, error } from './format.js';
+import { formatApiError } from '../helpers.js';
 import { requireCookie } from './helpers.js';
 export function projectsCommand() {
     const projects = new Command('projects')
@@ -17,7 +18,7 @@ export function projectsCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -33,7 +34,7 @@ export function projectsCommand() {
             output({ renamed: projectId, name: options.name }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -52,7 +53,7 @@ export function projectsCommand() {
             output({ moved: projectId, destination_team_id: options.destination }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -63,11 +64,16 @@ export function projectsCommand() {
         .action(async (projectId, options) => {
         try {
             const config = requireCookie();
+            const { confirmAction } = await import('./helpers.js');
+            if (!await confirmAction(`Trash project ${projectId} and all its files?`)) {
+                console.log('Cancelled.');
+                return;
+            }
             await trashProject(config, { project_id: projectId });
             output({ trashed: projectId }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -82,7 +88,7 @@ export function projectsCommand() {
             output({ restored: projectId }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -101,7 +107,7 @@ export function projectsCommand() {
             output({ updated: projectId }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });

package/dist/cli/reading.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { getFile, getNodes } from '../operations/reading.js';
 import { output, error } from './format.js';
+import { formatApiError } from '../helpers.js';
 import { requirePat } from './helpers.js';
 export function readingCommand() {
     const reading = new Command('reading')
@@ -22,7 +23,7 @@ export function readingCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -42,7 +43,7 @@ export function readingCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });

package/dist/cli/teams.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { createTeam, renameTeam, deleteTeam } from '../operations/teams.js';
 import { output, error } from './format.js';
+import { formatApiError } from '../helpers.js';
 import { requireCookie } from './helpers.js';
 export function teamsCommand() {
     const teams = new Command('teams')
@@ -17,7 +18,7 @@ export function teamsCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -32,7 +33,7 @@ export function teamsCommand() {
             output({ message: msg }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -43,11 +44,16 @@ export function teamsCommand() {
         .action(async (teamId, options) => {
         try {
             const config = requireCookie();
+            const { confirmAction } = await import('./helpers.js');
+            if (!await confirmAction(`Permanently delete team ${teamId}? All projects and files will be lost.`)) {
+                console.log('Cancelled.');
+                return;
+            }
             const msg = await deleteTeam(config, { team_id: teamId });
             output({ message: msg }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });

package/dist/cli/variables.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { listLocalVariables, listPublishedVariables, updateVariables, isEnterpriseScopeError, ENTERPRISE_ERROR, } from '../operations/variables.js';
 import { output, error } from './format.js';
+import { formatApiError } from '../helpers.js';
 import { requirePat } from './helpers.js';
 export function variablesCommand() {
     const variables = new Command('variables')
@@ -13,6 +14,10 @@ export function variablesCommand() {
         try {
             const config = requirePat();
             const result = await listLocalVariables(config, { file_key: fileKey });
+            if (Object.keys(result.variables ?? {}).length === 0 && Object.keys(result.variableCollections ?? {}).length === 0) {
+                console.log('No variables found.');
+                return;
+            }
             output(result, options);
         }
         catch (e) {
@@ -20,7 +25,7 @@ export function variablesCommand() {
                 error(ENTERPRISE_ERROR);
             }
             else {
-                error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+                error(formatApiError(e));
             }
             process.exit(1);
         }
@@ -33,6 +38,10 @@ export function variablesCommand() {
         try {
             const config = requirePat();
             const result = await listPublishedVariables(config, { file_key: fileKey });
+            if (Object.keys(result.variables ?? {}).length === 0 && Object.keys(result.variableCollections ?? {}).length === 0) {
+                console.log('No published variables found.');
+                return;
+            }
             output(result, options);
         }
         catch (e) {
@@ -40,7 +49,7 @@ export function variablesCommand() {
                 error(ENTERPRISE_ERROR);
             }
             else {
-                error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+                error(formatApiError(e));
             }
             process.exit(1);
         }
@@ -56,12 +65,25 @@ export function variablesCommand() {
         .action(async (fileKey, options) => {
         try {
             const config = requirePat();
+            const variableCollections = options.variableCollections ? JSON.parse(options.variableCollections) : undefined;
+            const variableModes = options.variableModes ? JSON.parse(options.variableModes) : undefined;
+            const variables = options.variables ? JSON.parse(options.variables) : undefined;
+            const variableModeValues = options.variableModeValues ? JSON.parse(options.variableModeValues) : undefined;
+            const allOps = [...(variables || []), ...(variableCollections || []), ...(variableModes || []), ...(variableModeValues || [])];
+            const hasDeletes = allOps.some((op) => op.action === 'DELETE');
+            if (hasDeletes) {
+                const { confirmAction } = await import('./helpers.js');
+                if (!await confirmAction('This includes DELETE operations that cannot be undone. Continue?')) {
+                    console.log('Cancelled.');
+                    return;
+                }
+            }
             const result = await updateVariables(config, {
                 file_key: fileKey,
-                variable_collections: options.variableCollections ? JSON.parse(options.variableCollections) : undefined,
-                variable_modes: options.variableModes ? JSON.parse(options.variableModes) : undefined,
-                variables: options.variables ? JSON.parse(options.variables) : undefined,
-                variable_mode_values: options.variableModeValues ? JSON.parse(options.variableModeValues) : undefined,
+                variable_collections: variableCollections,
+                variable_modes: variableModes,
+                variables: variables,
+                variable_mode_values: variableModeValues,
             });
             output(result, options);
         }
@@ -70,7 +92,7 @@ export function variablesCommand() {
                 error(ENTERPRISE_ERROR);
             }
             else {
-                error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+                error(formatApiError(e));
             }
             process.exit(1);
         }

package/dist/cli/versions.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { listVersions, createVersion } from '../operations/versions.js';
 import { output, error } from './format.js';
+import { formatApiError } from '../helpers.js';
 import { requirePat, requireCookie } from './helpers.js';
 export function versionsCommand() {
     const versions = new Command('versions')
@@ -16,7 +17,7 @@ export function versionsCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -37,7 +38,7 @@ export function versionsCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });

package/dist/cli/webhooks.js

@@ -1,6 +1,7 @@
 import { Command } from 'commander';
 import { listWebhooks, createWebhook, updateWebhook, deleteWebhook, } from '../operations/webhooks.js';
 import { output, error } from './format.js';
+import { formatApiError } from '../helpers.js';
 import { requirePat } from './helpers.js';
 const VALID_EVENT_TYPES = [
     'FILE_UPDATE',
@@ -21,10 +22,14 @@ export function webhooksCommand() {
         try {
             const config = requirePat();
             const result = await listWebhooks(config, { team_id: teamId });
+            if (result.webhooks.length === 0) {
+                console.log('No webhooks found.');
+                return;
+            }
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -49,7 +54,7 @@ export function webhooksCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -76,7 +81,7 @@ export function webhooksCommand() {
             output(result, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });
@@ -87,11 +92,16 @@ export function webhooksCommand() {
         .action(async (webhookId, options) => {
         try {
             const config = requirePat();
+            const { confirmAction } = await import('./helpers.js');
+            if (!await confirmAction(`Delete webhook ${webhookId}?`)) {
+                console.log('Cancelled.');
+                return;
+            }
             await deleteWebhook(config, { webhook_id: webhookId });
             output({ deleted: webhookId }, options);
         }
         catch (e) {
-            error(e.response?.status ? `API error: ${e.response.status}` : e.message);
+            error(formatApiError(e));
             process.exit(1);
         }
     });

package/dist/helpers.d.ts

@@ -0,0 +1,11 @@
+import type { AuthConfig } from './auth/client.js';
+/**
+ * Extract actionable error info from Figma API errors.
+ * Includes response body when available, maps common status codes.
+ */
+export declare function formatApiError(e: any): string;
+/** Resolve an org ID from explicit param or config. Returns undefined if neither set. */
+export declare function resolveOrgId(config: AuthConfig, explicit?: string): string | undefined;
+/** Require an org ID, throwing with guidance if missing. */
+export declare function requireOrgId(config: AuthConfig, explicit?: string): string;
+//# sourceMappingURL=helpers.d.ts.map

package/dist/helpers.js

@@ -0,0 +1,41 @@
+/**
+ * Extract actionable error info from Figma API errors.
+ * Includes response body when available, maps common status codes.
+ */
+export function formatApiError(e) {
+    const status = e.response?.status;
+    if (!status)
+        return e.message || 'Unknown error';
+    const body = e.response?.data;
+    const detail = typeof body === 'string'
+        ? body
+        : body?.message || body?.err || body?.error || '';
+    const statusMessages = {
+        400: 'Bad request',
+        401: 'Authentication expired or invalid. Re-run setup.',
+        403: 'Insufficient permissions for this action',
+        404: 'Resource not found. Check the ID.',
+        409: 'Conflict -- resource may already exist or be in use',
+        429: 'Rate limited. Try again in a moment.',
+        500: 'Figma server error. Try again later.',
+    };
+    const base = statusMessages[status] || `HTTP ${status}`;
+    return detail ? `${base}: ${detail}` : base;
+}
+/** Resolve an org ID from explicit param or config. Returns undefined if neither set. */
+export function resolveOrgId(config, explicit) {
+    const id = explicit || config.orgId;
+    if (id && !/^[\w.:-]+$/.test(id))
+        throw new Error('Invalid org ID format');
+    return id;
+}
+/** Require an org ID, throwing with guidance if missing. */
+export function requireOrgId(config, explicit) {
+    const id = explicit || config.orgId;
+    if (!id)
+        throw new Error('Org context required. Run list_orgs to see available workspaces, or set FIGMA_ORG_ID.');
+    if (!/^[\w.:-]+$/.test(id))
+        throw new Error('Invalid org ID format');
+    return id;
+}
+//# sourceMappingURL=helpers.js.map

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/operations/analytics.js

@@ -1,5 +1,5 @@
 import { internalClient } from '../clients/internal-api.js';
-import { requireOrgId } from '../tools/register.js';
+import { requireOrgId } from '../helpers.js';
 export async function libraryUsage(config, params) {
     const lookback = params.days ?? 30;
     const end_ts = Math.floor(Date.now() / 1000);

package/dist/operations/components.d.ts

@@ -1,10 +1,16 @@
 import type { AuthConfig } from '../auth/client.js';
 export declare function listFileComponents(config: AuthConfig, params: {
     file_key: string;
-}): Promise<any[]>;
+}): Promise<{
+    count: number;
+    components: any[];
+}>;
 export declare function listFileStyles(config: AuthConfig, params: {
     file_key: string;
-}): Promise<any[]>;
+}): Promise<{
+    count: number;
+    styles: any[];
+}>;
 export declare function listTeamComponents(config: AuthConfig, params: {
     team_id: string;
     page_size?: number;

package/dist/operations/components.js

@@ -1,11 +1,13 @@
 import { publicClient } from '../clients/public-api.js';
 export async function listFileComponents(config, params) {
     const res = await publicClient(config).get(`/v1/files/${params.file_key}/components`);
-    return res.data?.meta?.components || [];
+    const components = res.data?.meta?.components || [];
+    return { count: components.length, components };
 }
 export async function listFileStyles(config, params) {
     const res = await publicClient(config).get(`/v1/files/${params.file_key}/styles`);
-    return res.data?.meta?.styles || [];
+    const styles = res.data?.meta?.styles || [];
+    return { count: styles.length, styles };
 }
 export async function listTeamComponents(config, params) {
     const queryParams = { page_size: params.page_size ?? 30 };