figmanage 1.3.0 → 1.3.1

package/dist/tools/register.js

@@ -56,21 +56,16 @@ export function registerTools(server, config, enabledToolsets, readOnly) {
 export function toolResult(text) {
     return { content: [{ type: 'text', text }] };
 }
+/** Format a tool response with a summary line, JSON data, and optional next-step guidance. */
+export function toolSummary(summary, data, nextStep) {
+    const parts = [summary, '', JSON.stringify(data, null, 2)];
+    if (nextStep)
+        parts.push('', nextStep);
+    return { content: [{ type: 'text', text: parts.join('\n') }] };
+}
 export function toolError(message) {
     return { isError: true, content: [{ type: 'text', text: message }] };
 }
-export function resolveOrgId(config, explicit) {
-    const id = explicit || config.orgId;
-    if (id && !/^[\w.:-]+$/.test(id))
-        throw new Error('Invalid org ID format');
-    return id;
-}
-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;
-}
+// Re-export from helpers so existing tool imports still work
+export { resolveOrgId, requireOrgId } from '../helpers.js';
 //# sourceMappingURL=register.js.map

package/dist/tools/teams.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { defineTool, toolResult, toolError, figmaId } from './register.js';
+import { defineTool, toolResult, toolError, toolSummary, figmaId } from './register.js';
+import { formatApiError } from '../helpers.js';
 import { createTeam, renameTeam, deleteTeam } from '../operations/teams.js';
 // -- create_team --
 defineTool({
@@ -16,10 +17,10 @@ defineTool({
         }, async ({ name, org_id }) => {
             try {
                 const result = await createTeam(config, { name, org_id });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary(`Created team.`, result, 'Use create_project to add projects to this team.');
             }
             catch (e) {
-                return toolError(`Failed to create team: ${e.response?.status || e.message}`);
+                return toolError(`Failed to create team: ${formatApiError(e)}`);
             }
         });
     },
@@ -42,7 +43,7 @@ defineTool({
                 return toolResult(msg);
             }
             catch (e) {
-                return toolError(`Failed to rename team: ${e.response?.status || e.message}`);
+                return toolError(`Failed to rename team: ${formatApiError(e)}`);
             }
         });
     },
@@ -55,7 +56,7 @@ defineTool({
     destructive: true,
     register(server, config) {
         server.registerTool('delete_team', {
-            description: 'Delete a team. This is destructive and cannot be undone.',
+            description: 'Permanently delete a team and all its projects/files. This cannot be undone. All team members lose access.',
             inputSchema: {
                 team_id: figmaId.describe('Team ID'),
             },
@@ -65,7 +66,7 @@ defineTool({
                 return toolResult(msg);
             }
             catch (e) {
-                return toolError(`Failed to delete team: ${e.response?.status || e.message}`);
+                return toolError(`Failed to delete team: ${formatApiError(e)}`);
             }
         });
     },

package/dist/tools/variables.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { defineTool, toolResult, toolError, figmaId } from './register.js';
+import { defineTool, toolError, toolSummary, figmaId } from './register.js';
+import { formatApiError } from '../helpers.js';
 import { listLocalVariables, listPublishedVariables, updateVariables, isEnterpriseScopeError, ENTERPRISE_ERROR, } from '../operations/variables.js';
 // -- list_local_variables --
 defineTool({
@@ -14,12 +15,14 @@ defineTool({
         }, async ({ file_key }) => {
             try {
                 const result = await listLocalVariables(config, { file_key });
-                return toolResult(JSON.stringify(result, null, 2));
+                const vars = result.variables ? Object.keys(result.variables).length : 0;
+                const collections = result.variableCollections ? Object.keys(result.variableCollections).length : 0;
+                return toolSummary(`${vars} variable(s) in ${collections} collection(s).`, result);
             }
             catch (e) {
                 if (isEnterpriseScopeError(e))
                     return toolError(ENTERPRISE_ERROR);
-                return toolError(`Failed to list local variables: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list local variables: ${formatApiError(e)}`);
             }
         });
     },
@@ -37,12 +40,13 @@ defineTool({
         }, async ({ file_key }) => {
             try {
                 const result = await listPublishedVariables(config, { file_key });
-                return toolResult(JSON.stringify(result, null, 2));
+                const vars = result.variables ? Object.keys(result.variables).length : 0;
+                return toolSummary(`${vars} published variable(s).`, result);
             }
             catch (e) {
                 if (isEnterpriseScopeError(e))
                     return toolError(ENTERPRISE_ERROR);
-                return toolError(`Failed to list published variables: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list published variables: ${formatApiError(e)}`);
             }
         });
     },
@@ -55,7 +59,7 @@ defineTool({
     destructive: true,
     register(server, config) {
         server.registerTool('update_variables', {
-            description: 'Bulk create, update, or delete variables, collections, modes, and mode values. Requires Enterprise plan.',
+            description: 'Bulk create, update, or delete variables, collections, modes, and mode values. Requires Enterprise plan. Each operation object needs an action field (CREATE, UPDATE, or DELETE). Deletions are immediate and cannot be undone -- list variables first to verify IDs.',
             inputSchema: {
                 file_key: figmaId.describe('File key'),
                 variable_collections: z.array(z.record(z.any())).optional().describe('Collection operations (action: CREATE, UPDATE, or DELETE)'),
@@ -72,12 +76,12 @@ defineTool({
                     variables,
                     variable_mode_values,
                 });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary('Variables updated.', result, 'Use list_local_variables to verify changes.');
             }
             catch (e) {
                 if (isEnterpriseScopeError(e))
                     return toolError(ENTERPRISE_ERROR);
-                return toolError(`Failed to update variables: ${e.response?.status || e.message}`);
+                return toolError(`Failed to update variables: ${formatApiError(e)}`);
             }
         });
     },

package/dist/tools/versions.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { defineTool, toolResult, toolError, figmaId } from './register.js';
+import { defineTool, toolResult, toolError, toolSummary, figmaId } from './register.js';
+import { formatApiError } from '../helpers.js';
 import { listVersions, createVersion } from '../operations/versions.js';
 // -- list_versions --
 defineTool({
@@ -16,10 +17,10 @@ defineTool({
                 const result = await listVersions(config, { file_key });
                 if (result.length === 0)
                     return toolResult('No versions found.');
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary(`${result.length} version(s).`, result, 'Use create_version to add a named checkpoint.');
             }
             catch (e) {
-                return toolError(`Failed to list versions: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list versions: ${formatApiError(e)}`);
             }
         });
     },
@@ -40,10 +41,10 @@ defineTool({
         }, async ({ file_key, title, description }) => {
             try {
                 const result = await createVersion(config, { file_key, title, description });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary(`Created version "${result.label}".`, result);
             }
             catch (e) {
-                return toolError(`Failed to create version: ${e.response?.status || e.message}`);
+                return toolError(`Failed to create version: ${formatApiError(e)}`);
             }
         });
     },

package/dist/tools/webhooks.js

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import { defineTool, toolResult, toolError, figmaId } from './register.js';
+import { defineTool, toolResult, toolError, toolSummary, figmaId } from './register.js';
+import { formatApiError } from '../helpers.js';
 import { listWebhooks, createWebhook, updateWebhook, deleteWebhook, } from '../operations/webhooks.js';
 const eventTypeEnum = z.enum([
     'FILE_UPDATE',
@@ -15,17 +16,19 @@ defineTool({
     auth: 'pat',
     register(server, config) {
         server.registerTool('list_webhooks', {
-            description: 'List webhooks for a team.',
+            description: 'List webhook subscriptions for a team. Returns webhook IDs, endpoints, event types, and status.',
             inputSchema: {
                 team_id: figmaId.describe('Team ID'),
             },
         }, async ({ team_id }) => {
             try {
-                const webhooks = await listWebhooks(config, { team_id });
-                return toolResult(JSON.stringify(webhooks, null, 2));
+                const result = await listWebhooks(config, { team_id });
+                if (result.count === 0)
+                    return toolResult('No webhooks configured for this team.');
+                return toolSummary(`${result.count} webhook(s).`, result, 'Use create_webhook to add, or update_webhook/delete_webhook to manage.');
             }
             catch (e) {
-                return toolError(`Failed to list webhooks: ${e.response?.status || e.message}`);
+                return toolError(`Failed to list webhooks: ${formatApiError(e)}`);
             }
         });
     },
@@ -48,10 +51,10 @@ defineTool({
         }, async ({ team_id, event_type, endpoint, passcode, description }) => {
             try {
                 const result = await createWebhook(config, { team_id, event_type, endpoint, passcode, description });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary(`Created webhook ${result.id || 'unknown'} for ${result.event_type || event_type} events.`, result);
             }
             catch (e) {
-                return toolError(`Failed to create webhook: ${e.response?.status || e.message}`);
+                return toolError(`Failed to create webhook: ${formatApiError(e)}`);
             }
         });
     },
@@ -63,7 +66,7 @@ defineTool({
     mutates: true,
     register(server, config) {
         server.registerTool('update_webhook', {
-            description: 'Update a webhook.',
+            description: "Update a webhook's endpoint, event type, passcode, description, or status (ACTIVE/PAUSED).",
             inputSchema: {
                 webhook_id: figmaId.describe('Webhook ID'),
                 event_type: eventTypeEnum.optional().describe('Event type to subscribe to'),
@@ -75,10 +78,10 @@ defineTool({
         }, async ({ webhook_id, event_type, endpoint, passcode, description, status }) => {
             try {
                 const result = await updateWebhook(config, { webhook_id, event_type, endpoint, passcode, description, status });
-                return toolResult(JSON.stringify(result, null, 2));
+                return toolSummary(`Updated webhook ${result.id || webhook_id}.`, result);
             }
             catch (e) {
-                return toolError(`Failed to update webhook: ${e.response?.status || e.message}`);
+                return toolError(`Failed to update webhook: ${formatApiError(e)}`);
             }
         });
     },
@@ -91,7 +94,7 @@ defineTool({
     destructive: true,
     register(server, config) {
         server.registerTool('delete_webhook', {
-            description: 'Delete a webhook.',
+            description: 'Permanently delete a webhook. The webhook stops receiving events immediately. Cannot be undone.',
             inputSchema: {
                 webhook_id: figmaId.describe('Webhook ID'),
             },
@@ -101,7 +104,7 @@ defineTool({
                 return toolResult(`Deleted webhook ${webhook_id}`);
             }
             catch (e) {
-                return toolError(`Failed to delete webhook: ${e.response?.status || e.message}`);
+                return toolError(`Failed to delete webhook: ${formatApiError(e)}`);
             }
         });
     },

package/package.json

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