figmanage 0.1.0

package/dist/tools/projects.js

@@ -0,0 +1,160 @@
+import { z } from 'zod';
+import { internalClient } from '../clients/internal-api.js';
+import { defineTool, toolResult, toolError, figmaId } from './register.js';
+// -- create_project --
+defineTool({
+    toolset: 'projects',
+    auth: 'cookie',
+    mutates: true,
+    register(server, config) {
+        server.registerTool('create_project', {
+            description: 'Create a new project (folder) in a team.',
+            inputSchema: {
+                team_id: figmaId.describe('Team ID to create the project in'),
+                name: z.string().describe('Project name'),
+            },
+        }, async ({ team_id, name }) => {
+            try {
+                const res = await internalClient(config).post('/api/folders', {
+                    team_id,
+                    path: name,
+                    sharing_audience_control: 'org_view',
+                    team_access: 'team_edit',
+                });
+                const meta = res.data?.meta;
+                const p = Array.isArray(meta) ? meta[0] : (meta?.folder || meta || res.data);
+                return toolResult(JSON.stringify({
+                    id: String(p.id),
+                    name: p.name || p.path || name,
+                    team_id,
+                }, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to create project: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- rename_project --
+defineTool({
+    toolset: 'projects',
+    auth: 'cookie',
+    mutates: true,
+    register(server, config) {
+        server.registerTool('rename_project', {
+            description: 'Rename a project (folder).',
+            inputSchema: {
+                project_id: figmaId.describe('Project ID'),
+                name: z.string().describe('New name'),
+            },
+        }, async ({ project_id, name }) => {
+            try {
+                await internalClient(config).put('/api/folders/rename', {
+                    folder_id: project_id,
+                    name,
+                });
+                return toolResult(`Renamed project ${project_id} to "${name}"`);
+            }
+            catch (e) {
+                return toolError(`Failed to rename project: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- move_project --
+defineTool({
+    toolset: 'projects',
+    auth: 'cookie',
+    mutates: true,
+    register(server, config) {
+        server.registerTool('move_project', {
+            description: 'Move a project to a different team.',
+            inputSchema: {
+                project_id: figmaId.describe('Project ID to move'),
+                destination_team_id: figmaId.describe('Destination team ID'),
+            },
+        }, async ({ project_id, destination_team_id }) => {
+            try {
+                await internalClient(config).put('/api/folders/move', {
+                    folder_id: project_id,
+                    team_id: destination_team_id,
+                });
+                return toolResult(`Moved project ${project_id} to team ${destination_team_id}`);
+            }
+            catch (e) {
+                return toolError(`Failed to move project: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- trash_project --
+defineTool({
+    toolset: 'projects',
+    auth: 'cookie',
+    mutates: true,
+    destructive: true,
+    register(server, config) {
+        server.registerTool('trash_project', {
+            description: 'Move a project to trash.',
+            inputSchema: {
+                project_id: figmaId.describe('Project ID to trash'),
+            },
+        }, async ({ project_id }) => {
+            try {
+                await internalClient(config).put(`/api/folders/trash/${project_id}`);
+                return toolResult(`Trashed project ${project_id}`);
+            }
+            catch (e) {
+                return toolError(`Failed to trash project: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- restore_project --
+defineTool({
+    toolset: 'projects',
+    auth: 'cookie',
+    mutates: true,
+    register(server, config) {
+        server.registerTool('restore_project', {
+            description: 'Restore a project from trash.',
+            inputSchema: {
+                project_id: figmaId.describe('Project ID to restore'),
+            },
+        }, async ({ project_id }) => {
+            try {
+                await internalClient(config).put(`/api/folders/restore/${project_id}`);
+                return toolResult(`Restored project ${project_id}`);
+            }
+            catch (e) {
+                return toolError(`Failed to restore project: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- set_project_description --
+defineTool({
+    toolset: 'projects',
+    auth: 'cookie',
+    mutates: true,
+    register(server, config) {
+        server.registerTool('set_project_description', {
+            description: 'Set or update a project description.',
+            inputSchema: {
+                project_id: figmaId.describe('Project ID'),
+                description: z.string().describe('New description text'),
+            },
+        }, async ({ project_id, description }) => {
+            try {
+                await internalClient(config).put(`/api/folders/${project_id}/description`, {
+                    description,
+                });
+                return toolResult(`Updated description for project ${project_id}`);
+            }
+            catch (e) {
+                return toolError(`Failed to set description: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+//# sourceMappingURL=projects.js.map

package/dist/tools/reading.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=reading.d.ts.map

package/dist/tools/reading.js

@@ -0,0 +1,60 @@
+import { z } from 'zod';
+import { publicClient } from '../clients/public-api.js';
+import { defineTool, toolResult, toolError, figmaId } from './register.js';
+// -- get_file --
+defineTool({
+    toolset: 'reading',
+    auth: 'pat',
+    register(server, config) {
+        server.registerTool('get_file', {
+            description: 'Read file contents as a node tree. To read a branch, use the branch file key from list_branches.',
+            inputSchema: {
+                file_key: figmaId.describe('File key (or branch file key from list_branches)'),
+                depth: z.number().int().optional().describe('Tree depth limit. 0=root, 1=pages, 2=top-level frames. Omit for full tree.'),
+                node_id: figmaId.optional().describe('Start from a specific node instead of document root'),
+            },
+        }, async ({ file_key, depth, node_id }) => {
+            try {
+                const params = {};
+                if (depth !== undefined)
+                    params.depth = String(depth);
+                if (node_id)
+                    params['node-id'] = node_id;
+                const res = await publicClient(config).get(`/v1/files/${file_key}`, { params });
+                return toolResult(JSON.stringify(res.data, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to get file: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- get_nodes --
+defineTool({
+    toolset: 'reading',
+    auth: 'pat',
+    register(server, config) {
+        server.registerTool('get_nodes', {
+            description: 'Read specific nodes from a file. Returns node data for each requested node ID.',
+            inputSchema: {
+                file_key: figmaId.describe('File key'),
+                node_ids: z.array(figmaId).min(1).describe('Node IDs to fetch'),
+                depth: z.number().int().optional().describe('Depth limit per node'),
+            },
+        }, async ({ file_key, node_ids, depth }) => {
+            try {
+                const params = {
+                    ids: node_ids.join(','),
+                };
+                if (depth !== undefined)
+                    params.depth = String(depth);
+                const res = await publicClient(config).get(`/v1/files/${file_key}/nodes`, { params });
+                return toolResult(JSON.stringify(res.data, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to get nodes: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+//# sourceMappingURL=reading.js.map

package/dist/tools/register.d.ts

@@ -0,0 +1,32 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { AuthConfig } from '../auth/client.js';
+import type { Toolset } from '../types/figma.js';
+import { z } from 'zod';
+/** Validates that a string is a safe Figma ID (alphanumeric, hyphens, underscores, dots, colons) */
+export declare const figmaId: z.ZodString;
+export type AuthRequirement = 'pat' | 'cookie' | 'either';
+export interface ToolDef {
+    toolset: Toolset;
+    auth: AuthRequirement;
+    mutates?: boolean;
+    destructive?: 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 toolResult(text: string): {
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};
+export declare function toolError(message: string): {
+    isError: true;
+    content: Array<{
+        type: 'text';
+        text: string;
+    }>;
+};
+export declare function resolveOrgId(config: AuthConfig, explicit?: string): string | undefined;
+export declare function requireOrgId(config: AuthConfig, explicit?: string): string;
+//# sourceMappingURL=register.d.ts.map

package/dist/tools/register.js

@@ -0,0 +1,76 @@
+import { hasPat, hasCookie } from '../auth/client.js';
+import { z } from 'zod';
+/** Validates that a string is a safe Figma ID (alphanumeric, hyphens, underscores, dots, colons) */
+export const figmaId = z.string().regex(/^[\w.:-]+$/, 'Invalid ID format');
+const allTools = [];
+export function defineTool(def) {
+    allTools.push(def);
+}
+/** Build MCP tool annotations from ToolDef flags. */
+function buildAnnotations(tool) {
+    const annotations = { openWorldHint: true };
+    if (!tool.mutates) {
+        annotations.readOnlyHint = true;
+    }
+    else {
+        annotations.destructiveHint = !!tool.destructive;
+    }
+    return annotations;
+}
+/**
+ * Wrap an McpServer so that every registerTool call automatically
+ * injects annotations derived from the ToolDef metadata.
+ */
+function withAnnotations(server, tool) {
+    const annotations = buildAnnotations(tool);
+    return new Proxy(server, {
+        get(target, prop, receiver) {
+            if (prop === 'registerTool') {
+                return (name, config, ...rest) => {
+                    const augmented = { ...config, annotations: { ...annotations, ...(config.annotations || {}) } };
+                    return target.registerTool.call(target, name, augmented, ...rest);
+                };
+            }
+            return Reflect.get(target, prop, receiver);
+        },
+    });
+}
+export function registerTools(server, config, enabledToolsets, readOnly) {
+    for (const tool of allTools) {
+        // Filter by enabled toolsets
+        if (!enabledToolsets.has(tool.toolset))
+            continue;
+        // Filter by read-only mode
+        if (readOnly && tool.mutates)
+            continue;
+        // Filter by available auth
+        if (tool.auth === 'pat' && !hasPat(config))
+            continue;
+        if (tool.auth === 'cookie' && !hasCookie(config))
+            continue;
+        if (tool.auth === 'either' && !hasPat(config) && !hasCookie(config))
+            continue;
+        tool.register(withAnnotations(server, tool), config);
+    }
+}
+export function toolResult(text) {
+    return { content: [{ type: 'text', text }] };
+}
+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;
+}
+//# sourceMappingURL=register.js.map

package/dist/tools/teams.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=teams.d.ts.map

package/dist/tools/teams.js

@@ -0,0 +1,81 @@
+import { z } from 'zod';
+import { internalClient } from '../clients/internal-api.js';
+import { defineTool, toolResult, toolError, figmaId, requireOrgId } from './register.js';
+// -- create_team --
+defineTool({
+    toolset: 'teams',
+    auth: 'cookie',
+    mutates: true,
+    register(server, config) {
+        server.registerTool('create_team', {
+            description: 'Create a new team in the org.',
+            inputSchema: {
+                name: z.string().describe('Team name'),
+                org_id: figmaId.optional().describe('Org ID override (defaults to current workspace)'),
+            },
+        }, async ({ name, org_id }) => {
+            try {
+                let orgId;
+                try {
+                    orgId = requireOrgId(config, org_id);
+                }
+                catch (e) {
+                    return toolError(e.message);
+                }
+                const res = await internalClient(config).post('/api/teams/create', { team_name: name, org_id: orgId, sharing_audience_control: 'org_view' });
+                const team = res.data?.meta?.team || res.data?.meta || res.data;
+                return toolResult(JSON.stringify({ id: String(team.id), name: team.name }, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to create team: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- rename_team --
+defineTool({
+    toolset: 'teams',
+    auth: 'cookie',
+    mutates: true,
+    register(server, config) {
+        server.registerTool('rename_team', {
+            description: 'Rename an existing team.',
+            inputSchema: {
+                team_id: figmaId.describe('Team ID'),
+                name: z.string().describe('New team name'),
+            },
+        }, async ({ team_id, name }) => {
+            try {
+                await internalClient(config).put(`/api/teams/${team_id}`, { name });
+                return toolResult(`Team ${team_id} renamed to "${name}".`);
+            }
+            catch (e) {
+                return toolError(`Failed to rename team: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- delete_team --
+defineTool({
+    toolset: 'teams',
+    auth: 'cookie',
+    mutates: true,
+    destructive: true,
+    register(server, config) {
+        server.registerTool('delete_team', {
+            description: 'Delete a team. This is destructive and cannot be undone.',
+            inputSchema: {
+                team_id: figmaId.describe('Team ID'),
+            },
+        }, async ({ team_id }) => {
+            try {
+                await internalClient(config).delete(`/api/teams/${team_id}`);
+                return toolResult(`Team ${team_id} deleted.`);
+            }
+            catch (e) {
+                return toolError(`Failed to delete team: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+//# sourceMappingURL=teams.js.map

package/dist/tools/variables.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=variables.d.ts.map

package/dist/tools/variables.js

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+import { publicClient } from '../clients/public-api.js';
+import { defineTool, toolResult, toolError, figmaId } from './register.js';
+const ENTERPRISE_ERROR = 'Variables API requires Figma Enterprise plan. The file_variables:read/write scopes are not available on standard plans.';
+function isEnterpriseScopeError(e) {
+    if (e.response?.status !== 403)
+        return false;
+    const data = e.response?.data;
+    if (typeof data !== 'object' || !data)
+        return false;
+    const msg = String(data.message || data.error || data.err || '');
+    return msg.toLowerCase().includes('scope');
+}
+// -- list_local_variables --
+defineTool({
+    toolset: 'variables',
+    auth: 'pat',
+    register(server, config) {
+        server.registerTool('list_local_variables', {
+            description: 'List local variables and variable collections in a file. Requires Enterprise plan.',
+            inputSchema: {
+                file_key: figmaId.describe('File key'),
+            },
+        }, async ({ file_key }) => {
+            try {
+                const res = await publicClient(config).get(`/v1/files/${file_key}/variables/local`);
+                return toolResult(JSON.stringify(res.data?.meta ?? {}, null, 2));
+            }
+            catch (e) {
+                if (isEnterpriseScopeError(e))
+                    return toolError(ENTERPRISE_ERROR);
+                return toolError(`Failed to list local variables: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- list_published_variables --
+defineTool({
+    toolset: 'variables',
+    auth: 'pat',
+    register(server, config) {
+        server.registerTool('list_published_variables', {
+            description: 'List published variables from a library file. Requires Enterprise plan.',
+            inputSchema: {
+                file_key: figmaId.describe('File key'),
+            },
+        }, async ({ file_key }) => {
+            try {
+                const res = await publicClient(config).get(`/v1/files/${file_key}/variables/published`);
+                return toolResult(JSON.stringify(res.data?.meta ?? {}, null, 2));
+            }
+            catch (e) {
+                if (isEnterpriseScopeError(e))
+                    return toolError(ENTERPRISE_ERROR);
+                return toolError(`Failed to list published variables: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- update_variables --
+defineTool({
+    toolset: 'variables',
+    auth: 'pat',
+    mutates: true,
+    destructive: true,
+    register(server, config) {
+        server.registerTool('update_variables', {
+            description: 'Bulk create, update, or delete variables, collections, modes, and mode values. Requires Enterprise plan.',
+            inputSchema: {
+                file_key: figmaId.describe('File key'),
+                variable_collections: z.array(z.record(z.any())).optional().describe('Collection operations (action: CREATE, UPDATE, or DELETE)'),
+                variable_modes: z.array(z.record(z.any())).optional().describe('Mode operations (action: CREATE, UPDATE, or DELETE)'),
+                variables: z.array(z.record(z.any())).optional().describe('Variable operations (action: CREATE, UPDATE, or DELETE)'),
+                variable_mode_values: z.array(z.record(z.any())).optional().describe('Value assignments (action: CREATE, UPDATE, or DELETE)'),
+            },
+        }, async ({ file_key, variable_collections, variable_modes, variables, variable_mode_values }) => {
+            try {
+                if (!variable_collections?.length && !variable_modes?.length &&
+                    !variables?.length && !variable_mode_values?.length) {
+                    return toolError('At least one operation array is required.');
+                }
+                const body = {};
+                if (variable_collections)
+                    body.variableCollections = variable_collections;
+                if (variable_modes)
+                    body.variableModes = variable_modes;
+                if (variables)
+                    body.variables = variables;
+                if (variable_mode_values)
+                    body.variableModeValues = variable_mode_values;
+                const res = await publicClient(config).post(`/v1/files/${file_key}/variables`, body);
+                return toolResult(JSON.stringify(res.data, null, 2));
+            }
+            catch (e) {
+                if (isEnterpriseScopeError(e))
+                    return toolError(ENTERPRISE_ERROR);
+                return toolError(`Failed to update variables: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+//# sourceMappingURL=variables.js.map

package/dist/tools/versions.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=versions.d.ts.map

package/dist/tools/versions.js

@@ -0,0 +1,69 @@
+import { z } from 'zod';
+import { publicClient } from '../clients/public-api.js';
+import { internalClient } from '../clients/internal-api.js';
+import { defineTool, toolResult, toolError, figmaId } from './register.js';
+// -- list_versions --
+defineTool({
+    toolset: 'versions',
+    auth: 'pat',
+    register(server, config) {
+        server.registerTool('list_versions', {
+            description: 'List version history for a file. Returns named snapshots and auto-saves.',
+            inputSchema: {
+                file_key: figmaId.describe('File key'),
+            },
+        }, async ({ file_key }) => {
+            try {
+                const res = await publicClient(config).get(`/v1/files/${file_key}/versions`);
+                const versions = res.data?.versions || [];
+                const mapped = versions.map((v) => ({
+                    id: v.id,
+                    label: v.label || null,
+                    description: v.description || null,
+                    created_at: v.created_at,
+                    user: v.user?.handle || v.user?.id || null,
+                }));
+                if (mapped.length === 0)
+                    return toolResult('No versions found.');
+                return toolResult(JSON.stringify(mapped, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to list versions: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+// -- create_version --
+defineTool({
+    toolset: 'versions',
+    auth: 'cookie',
+    mutates: true,
+    register(server, config) {
+        server.registerTool('create_version', {
+            description: 'Create a named version (checkpoint) in a file\'s history.',
+            inputSchema: {
+                file_key: figmaId.describe('File key'),
+                title: z.string().describe('Version title/label'),
+                description: z.string().optional().describe('Version description'),
+            },
+        }, async ({ file_key, title, description }) => {
+            try {
+                const res = await internalClient(config).post(`/api/multiplayer/${file_key}/create_savepoint`, {
+                    label: title,
+                    description: description || '',
+                });
+                const v = res.data?.meta || {};
+                return toolResult(JSON.stringify({
+                    id: v.id || null,
+                    label: v.label || title,
+                    description: v.description || null,
+                    created_at: v.created_at || null,
+                }, null, 2));
+            }
+            catch (e) {
+                return toolError(`Failed to create version: ${e.response?.status || e.message}`);
+            }
+        });
+    },
+});
+//# sourceMappingURL=versions.js.map

package/dist/tools/webhooks.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=webhooks.d.ts.map