figmanage 1.3.7 → 1.4.0

package/dist/tools/org.js

@@ -1,10 +1,11 @@
 import { z } from 'zod';
 import { defineTool, toolResult, toolError, toolSummary, figmaId } from './register.js';
 import { formatApiError } from '../helpers.js';
-import { listAdmins, listOrgTeams, seatUsage, listTeamMembers, billingOverview, listInvoices, orgDomains, aiCreditUsage, exportMembers, listOrgMembers, contractRates, changeSeat, } from '../operations/org.js';
+import { listAdmins, listOrgTeams, seatUsage, listTeamMembers, billingOverview, listInvoices, orgDomains, aiCreditUsage, exportMembers, listOrgMembers, contractRates, changeSeat, activityLog, listPayments, removeOrgMember, createUserGroup, deleteUserGroups, addUserGroupMembers, removeUserGroupMembers, } from '../operations/org.js';
 // -- list_admins --
 defineTool({
     toolset: 'org',
+    adminOnly: true,
     auth: 'cookie',
     register(server, config) {
         server.registerTool('list_admins', {
@@ -27,6 +28,7 @@ defineTool({
 // -- list_org_teams --
 defineTool({
     toolset: 'org',
+    adminOnly: true,
     auth: 'cookie',
     register(server, config) {
         server.registerTool('list_org_teams', {
@@ -49,6 +51,7 @@ defineTool({
 // -- seat_usage --
 defineTool({
     toolset: 'org',
+    adminOnly: true,
     auth: 'cookie',
     register(server, config) {
         server.registerTool('seat_usage', {
@@ -60,7 +63,7 @@ defineTool({
         }, async ({ org_id, search_query }) => {
             try {
                 const result = await seatUsage(config, { org_id, search_query });
-                return toolSummary('Seat usage breakdown:', result);
+                return toolSummary('Seat usage breakdown:', result, 'Use seat_optimization to find inactive seats, or change_seat to modify.');
             }
             catch (e) {
                 return toolError(`Failed to fetch seat usage: ${formatApiError(e)}`);
@@ -71,6 +74,7 @@ defineTool({
 // -- list_team_members --
 defineTool({
     toolset: 'org',
+    adminOnly: true,
     auth: 'cookie',
     register(server, config) {
         server.registerTool('list_team_members', {
@@ -81,7 +85,7 @@ defineTool({
         }, async ({ team_id }) => {
             try {
                 const result = await listTeamMembers(config, { team_id });
-                return toolSummary(`${result.length} member(s).`, result);
+                return toolSummary(`${result.length} member(s).`, result, 'Use add_team_member or remove_team_member to manage membership.');
             }
             catch (e) {
                 return toolError(`Failed to list team members: ${formatApiError(e)}`);
@@ -92,6 +96,7 @@ defineTool({
 // -- billing_overview --
 defineTool({
     toolset: 'org',
+    adminOnly: true,
     auth: 'cookie',
     register(server, config) {
         server.registerTool('billing_overview', {
@@ -102,7 +107,7 @@ defineTool({
         }, async ({ org_id }) => {
             try {
                 const result = await billingOverview(config, { org_id });
-                return toolSummary('Billing overview:', result);
+                return toolSummary('Billing overview:', result, 'Use list_invoices for open invoices, list_payments for payment history, or contract_rates for per-seat pricing.');
             }
             catch (e) {
                 return toolError(`Failed to fetch billing overview: ${formatApiError(e)}`);
@@ -113,6 +118,7 @@ defineTool({
 // -- list_invoices --
 defineTool({
     toolset: 'org',
+    adminOnly: true,
     auth: 'cookie',
     register(server, config) {
         server.registerTool('list_invoices', {
@@ -134,6 +140,7 @@ defineTool({
 // -- org_domains --
 defineTool({
     toolset: 'org',
+    adminOnly: true,
     auth: 'cookie',
     register(server, config) {
         server.registerTool('org_domains', {
@@ -155,16 +162,18 @@ defineTool({
 // -- ai_credit_usage --
 defineTool({
     toolset: 'org',
+    adminOnly: true,
     auth: 'cookie',
     register(server, config) {
         server.registerTool('ai_credit_usage', {
-            description: 'AI credit usage summary for a billing plan. Get the plan_id from billing_overview.',
+            description: 'AI credit usage summary. Provide a team_id and the plan is resolved automatically, or pass plan_id directly.',
             inputSchema: {
-                plan_id: figmaId.describe('Plan ID (from billing_overview response)'),
+                team_id: figmaId.describe('Team ID (used to resolve the billing plan)'),
+                plan_id: figmaId.optional().describe('Plan ID override (skips team folder lookup)'),
             },
-        }, async ({ plan_id }) => {
+        }, async ({ team_id, plan_id }) => {
             try {
-                const result = await aiCreditUsage(config, { plan_id });
+                const result = await aiCreditUsage(config, { team_id, plan_id });
                 return toolSummary('AI credit usage:', result);
             }
             catch (e) {
@@ -176,6 +185,7 @@ defineTool({
 // -- export_members --
 defineTool({
     toolset: 'org',
+    adminOnly: true,
     auth: 'cookie',
     mutates: true,
     register(server, config) {
@@ -198,6 +208,7 @@ defineTool({
 // -- list_org_members --
 defineTool({
     toolset: 'org',
+    adminOnly: true,
     auth: 'cookie',
     register(server, config) {
         server.registerTool('list_org_members', {
@@ -220,6 +231,7 @@ defineTool({
 // -- contract_rates --
 defineTool({
     toolset: 'org',
+    adminOnly: true,
     auth: 'cookie',
     register(server, config) {
         server.registerTool('contract_rates', {
@@ -241,6 +253,7 @@ defineTool({
 // -- change_seat --
 defineTool({
     toolset: 'org',
+    adminOnly: true,
     auth: 'cookie',
     mutates: true,
     destructive: true,
@@ -266,4 +279,186 @@ defineTool({
         });
     },
 });
+// -- activity_log --
+defineTool({
+    toolset: 'org',
+    adminOnly: true,
+    auth: 'cookie',
+    register(server, config) {
+        server.registerTool('activity_log', {
+            description: 'Org audit log. Shows who did what, when. Filter by email for per-user activity. Supports date ranges and cursor pagination.',
+            inputSchema: {
+                org_id: figmaId.optional().describe('Org ID override (defaults to current workspace)'),
+                emails: z.string().optional().describe('Comma-separated emails to filter (e.g. "alice@acme.com,bob@acme.com")'),
+                start_time: z.string().optional().describe('Start date (ISO or YYYY-MM-DD). Defaults to 30 days ago.'),
+                end_time: z.string().optional().describe('End date (ISO or YYYY-MM-DD). Defaults to now.'),
+                page_size: z.number().int().optional().describe('Entries per page (default: 50)'),
+                after: z.string().optional().describe('Pagination cursor from previous response'),
+            },
+        }, async ({ org_id, emails, start_time, end_time, page_size, after }) => {
+            try {
+                const result = await activityLog(config, { org_id, emails, start_time, end_time, page_size, after });
+                if (result.entries.length === 0)
+                    return toolResult('No activity log entries found.');
+                const paginationNote = result.pagination
+                    ? `\nMore results available. Pass after: "${result.pagination.after}" to get the next page.`
+                    : '';
+                return toolSummary(`${result.entries.length} log entry/entries.${paginationNote}`, result.entries);
+            }
+            catch (e) {
+                return toolError(`Failed to fetch activity log: ${formatApiError(e)}`);
+            }
+        });
+    },
+});
+// -- list_payments --
+defineTool({
+    toolset: 'org',
+    adminOnly: true,
+    auth: 'cookie',
+    register(server, config) {
+        server.registerTool('list_payments', {
+            description: 'List paid invoices / payment history for the org.',
+            inputSchema: {
+                org_id: figmaId.optional().describe('Org ID override (defaults to current workspace)'),
+            },
+        }, async ({ org_id }) => {
+            try {
+                const result = await listPayments(config, { org_id });
+                if (result.length === 0)
+                    return toolResult('No paid invoices found.');
+                return toolSummary(`${result.length} paid invoice(s).`, result, 'Use billing_overview for current billing status, or list_invoices for open invoices.');
+            }
+            catch (e) {
+                return toolError(`Failed to list payments: ${formatApiError(e)}`);
+            }
+        });
+    },
+});
+// -- remove_org_member --
+defineTool({
+    toolset: 'org',
+    adminOnly: true,
+    auth: 'cookie',
+    mutates: true,
+    destructive: true,
+    register(server, config) {
+        server.registerTool('remove_org_member', {
+            description: 'Permanently remove a member from the org. They lose all access to teams, projects, files, and apps. Cannot be undone. Requires confirm: true.',
+            inputSchema: {
+                user_identifier: z.string().describe('Email or user_id of the member to remove'),
+                org_id: figmaId.optional().describe('Org ID override (defaults to current workspace)'),
+                confirm: z.boolean().optional().describe('Must be true to execute. Without it, returns a warning explaining consequences.'),
+            },
+        }, async ({ user_identifier, org_id, confirm }) => {
+            try {
+                const msg = await removeOrgMember(config, { user_identifier, org_id, confirm });
+                return toolResult(msg);
+            }
+            catch (e) {
+                return toolError(`${formatApiError(e)}`);
+            }
+        });
+    },
+});
+// -- create_user_group --
+defineTool({
+    toolset: 'org',
+    adminOnly: true,
+    auth: 'cookie',
+    mutates: true,
+    register(server, config) {
+        server.registerTool('create_user_group', {
+            description: 'Create a user group. Provide team_id to auto-resolve the billing plan, or pass plan_id directly.',
+            inputSchema: {
+                name: z.string().describe('Group name'),
+                description: z.string().optional().describe('Group description'),
+                team_id: figmaId.optional().describe('Team ID (used to resolve billing plan)'),
+                plan_id: figmaId.optional().describe('Plan ID override (skips team lookup)'),
+                emails: z.array(z.string()).optional().describe('Emails to add as initial members'),
+                should_notify: z.boolean().optional().describe('Notify members (default true)'),
+            },
+        }, async ({ name, description, team_id, plan_id, emails, should_notify }) => {
+            try {
+                const result = await createUserGroup(config, { name, description, team_id, plan_id, emails, should_notify });
+                return toolSummary(`User group "${name}" created.`, result, 'Use add_user_group_members to add members, or delete_user_groups to remove.');
+            }
+            catch (e) {
+                return toolError(`Failed to create user group: ${formatApiError(e)}`);
+            }
+        });
+    },
+});
+// -- delete_user_groups --
+defineTool({
+    toolset: 'org',
+    adminOnly: true,
+    auth: 'cookie',
+    mutates: true,
+    destructive: true,
+    register(server, config) {
+        server.registerTool('delete_user_groups', {
+            description: 'Delete one or more user groups by ID.',
+            inputSchema: {
+                user_group_ids: z.array(figmaId).describe('User group IDs to delete'),
+            },
+        }, async ({ user_group_ids }) => {
+            try {
+                const msg = await deleteUserGroups(config, { user_group_ids });
+                return toolResult(msg);
+            }
+            catch (e) {
+                return toolError(`Failed to delete user groups: ${formatApiError(e)}`);
+            }
+        });
+    },
+});
+// -- add_user_group_members --
+defineTool({
+    toolset: 'org',
+    adminOnly: true,
+    auth: 'cookie',
+    mutates: true,
+    register(server, config) {
+        server.registerTool('add_user_group_members', {
+            description: 'Add members to a user group by email.',
+            inputSchema: {
+                user_group_id: figmaId.describe('User group ID'),
+                emails: z.array(z.string()).describe('Email addresses to add'),
+            },
+        }, async ({ user_group_id, emails }) => {
+            try {
+                const result = await addUserGroupMembers(config, { user_group_id, emails });
+                return toolSummary(`Added ${emails.length} member(s) to group.`, result);
+            }
+            catch (e) {
+                return toolError(`Failed to add members to group: ${formatApiError(e)}`);
+            }
+        });
+    },
+});
+// -- remove_user_group_members --
+defineTool({
+    toolset: 'org',
+    adminOnly: true,
+    auth: 'cookie',
+    mutates: true,
+    register(server, config) {
+        server.registerTool('remove_user_group_members', {
+            description: 'Remove members from a user group by user ID.',
+            inputSchema: {
+                user_group_id: figmaId.describe('User group ID'),
+                user_ids: z.array(z.string()).describe('User IDs to remove'),
+            },
+        }, async ({ user_group_id, user_ids }) => {
+            try {
+                const msg = await removeUserGroupMembers(config, { user_group_id, user_ids });
+                return toolResult(msg);
+            }
+            catch (e) {
+                return toolError(`Failed to remove members from group: ${formatApiError(e)}`);
+            }
+        });
+    },
+});
 //# sourceMappingURL=org.js.map

package/dist/tools/permissions.js

@@ -106,6 +106,7 @@ defineTool({
 defineTool({
     toolset: 'permissions',
     auth: 'cookie',
+    adminOnly: true,
     register(server, config) {
         server.registerTool('list_role_requests', {
             description: 'List pending file access requests. These come through the notification system.',
@@ -128,6 +129,7 @@ defineTool({
     toolset: 'permissions',
     auth: 'cookie',
     mutates: true,
+    adminOnly: true,
     register(server, config) {
         server.registerTool('approve_role_request', {
             description: 'Approve a pending file access request by notification ID.',
@@ -150,6 +152,7 @@ defineTool({
     toolset: 'permissions',
     auth: 'cookie',
     mutates: true,
+    adminOnly: true,
     register(server, config) {
         server.registerTool('deny_role_request', {
             description: 'Decline a pending file access request by notification ID.',

package/dist/tools/register.d.ts

@@ -10,10 +10,11 @@ export interface ToolDef {
     auth: AuthRequirement;
     mutates?: boolean;
     destructive?: boolean;
+    adminOnly?: boolean;
     register: (server: McpServer, config: AuthConfig) => void;
 }
 export declare function defineTool(def: ToolDef): void;
-export declare function registerTools(server: McpServer, config: AuthConfig, enabledToolsets: Set<Toolset>, readOnly: boolean): void;
+export declare function registerTools(server: McpServer, config: AuthConfig, enabledToolsets: Set<Toolset>, readOnly: boolean, isAdmin?: boolean): void;
 export declare function toolResult(text: string): {
     content: Array<{
         type: 'text';

package/dist/tools/register.js

@@ -35,11 +35,14 @@ function withAnnotations(server, tool) {
         },
     });
 }
-export function registerTools(server, config, enabledToolsets, readOnly) {
+export function registerTools(server, config, enabledToolsets, readOnly, isAdmin = true) {
     for (const tool of allTools) {
         // Filter by enabled toolsets
         if (!enabledToolsets.has(tool.toolset))
             continue;
+        // Filter admin-only tools for non-admin users
+        if (tool.adminOnly && !isAdmin)
+            continue;
         // Filter by read-only mode
         if (readOnly && tool.mutates)
             continue;

package/dist/tools/teams.js

@@ -1,12 +1,13 @@
 import { z } from 'zod';
 import { defineTool, toolResult, toolError, toolSummary, figmaId } from './register.js';
 import { formatApiError } from '../helpers.js';
-import { createTeam, renameTeam, deleteTeam } from '../operations/teams.js';
+import { createTeam, renameTeam, deleteTeam, addTeamMember, removeTeamMember } from '../operations/teams.js';
 // -- create_team --
 defineTool({
     toolset: 'teams',
     auth: 'cookie',
     mutates: true,
+    adminOnly: true,
     register(server, config) {
         server.registerTool('create_team', {
             description: 'Create a new team in the org.',
@@ -54,6 +55,7 @@ defineTool({
     auth: 'cookie',
     mutates: true,
     destructive: true,
+    adminOnly: true,
     register(server, config) {
         server.registerTool('delete_team', {
             description: 'Permanently delete a team and all its projects/files. This cannot be undone. All team members lose access.',
@@ -71,4 +73,54 @@ defineTool({
         });
     },
 });
+// -- add_team_member --
+defineTool({
+    toolset: 'teams',
+    auth: 'cookie',
+    mutates: true,
+    adminOnly: true,
+    register(server, config) {
+        server.registerTool('add_team_member', {
+            description: 'Add a member to a team by email. Level: 100 = can view (default), 300 = can edit, 999 = admin.',
+            inputSchema: {
+                team_id: figmaId.describe('Team ID'),
+                email: z.string().describe('Email address of the user to add'),
+                level: z.number().int().optional().describe('Permission level: 100 = view (default), 300 = edit, 999 = admin'),
+            },
+        }, async ({ team_id, email, level }) => {
+            try {
+                const msg = await addTeamMember(config, { team_id, email, level });
+                return toolResult(msg);
+            }
+            catch (e) {
+                return toolError(`Failed to add team member: ${formatApiError(e)}`);
+            }
+        });
+    },
+});
+// -- remove_team_member --
+defineTool({
+    toolset: 'teams',
+    auth: 'cookie',
+    mutates: true,
+    destructive: true,
+    adminOnly: true,
+    register(server, config) {
+        server.registerTool('remove_team_member', {
+            description: 'Remove a member from a team. The user loses access to all team projects and files.',
+            inputSchema: {
+                team_id: figmaId.describe('Team ID'),
+                user_id: figmaId.describe('User ID to remove'),
+            },
+        }, async ({ team_id, user_id }) => {
+            try {
+                const msg = await removeTeamMember(config, { team_id, user_id });
+                return toolResult(msg);
+            }
+            catch (e) {
+                return toolError(`Failed to remove team member: ${formatApiError(e)}`);
+            }
+        });
+    },
+});
 //# sourceMappingURL=teams.js.map

package/dist/tools/webhooks.js

@@ -1,7 +1,7 @@
 import { z } from 'zod';
 import { defineTool, toolResult, toolError, toolSummary, figmaId } from './register.js';
 import { formatApiError } from '../helpers.js';
-import { listWebhooks, createWebhook, updateWebhook, deleteWebhook, } from '../operations/webhooks.js';
+import { listWebhooks, createWebhook, updateWebhook, deleteWebhook, webhookRequests, } from '../operations/webhooks.js';
 const eventTypeEnum = z.enum([
     'FILE_UPDATE',
     'FILE_DELETE',
@@ -25,7 +25,7 @@ defineTool({
                 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.');
+                return toolSummary(`${result.count} webhook(s).`, result, 'Use webhook_requests to check delivery history, create_webhook to add, or update_webhook/delete_webhook to manage.');
             }
             catch (e) {
                 return toolError(`Failed to list webhooks: ${formatApiError(e)}`);
@@ -86,6 +86,29 @@ defineTool({
         });
     },
 });
+// -- webhook_requests --
+defineTool({
+    toolset: 'webhooks',
+    auth: 'pat',
+    register(server, config) {
+        server.registerTool('webhook_requests', {
+            description: 'List recent webhook delivery attempts (last 7 days). Shows payload, response status, and errors.',
+            inputSchema: {
+                webhook_id: figmaId.describe('Webhook ID'),
+            },
+        }, async ({ webhook_id }) => {
+            try {
+                const result = await webhookRequests(config, { webhook_id });
+                if (result.count === 0)
+                    return toolResult('No webhook deliveries in the last 7 days.');
+                return toolSummary(`${result.count} delivery attempt(s).`, result, 'Use update_webhook to fix failing endpoints.');
+            }
+            catch (e) {
+                return toolError(`Failed to list webhook requests: ${formatApiError(e)}`);
+            }
+        });
+    },
+});
 // -- delete_webhook --
 defineTool({
     toolset: 'webhooks',

package/package.json

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