@muloka/figma-console-mcp 0.1.0

package/dist/core/figma-api.d.ts

@@ -0,0 +1,254 @@
+/**
+ * Figma REST API Client
+ * Handles HTTP calls to Figma's REST API for file data, variables, components, and styles
+ */
+/**
+ * Figma API Client Configuration
+ */
+export interface FigmaAPIConfig {
+    accessToken: string;
+}
+/**
+ * Extract file key from Figma URL
+ * Branch-aware: for branch URLs (/design/KEY/branch/BRANCHKEY/Name) returns the
+ * BRANCH key — the branch is its own file in the REST API, and returning the
+ * main key would silently target the wrong file (comments/diffs/file-data).
+ * @example https://www.figma.com/design/abc123/My-File -> abc123
+ * @example https://www.figma.com/design/abc123/branch/xyz789/My-File -> xyz789
+ */
+export declare function extractFileKey(url: string): string | null;
+/**
+ * Normalize a node ID to Figma's canonical colon form.
+ * URLs use dashes ("695-313") but the REST API keys response maps by colon
+ * form ("695:313") — indexing a response with a dashed ID silently returns
+ * undefined, which reads as "node may not exist".
+ */
+export declare function normalizeNodeId(nodeId: string): string;
+/**
+ * Information extracted from a Figma URL
+ * Includes file key, optional branch ID, and optional node ID
+ */
+export interface FigmaUrlInfo {
+    fileKey: string;
+    branchId?: string;
+    nodeId?: string;
+}
+/**
+ * Extract comprehensive URL info including branch and node IDs
+ * Supports both URL formats:
+ * - Path-based: /design/{fileKey}/branch/{branchKey}/{fileName}
+ * - Query-based: /design/{fileKey}/{fileName}?branch-id={branchId}
+ *
+ * @example https://www.figma.com/design/abc123/branch/xyz789/My-File?node-id=1-2
+ *   -> { fileKey: 'abc123', branchId: 'xyz789', nodeId: '1:2' }
+ * @example https://www.figma.com/design/abc123/My-File?branch-id=xyz789&node-id=1-2
+ *   -> { fileKey: 'abc123', branchId: 'xyz789', nodeId: '1:2' }
+ */
+export declare function extractFigmaUrlInfo(url: string): FigmaUrlInfo | null;
+/**
+ * Wrap a promise with a timeout
+ * @param promise The promise to wrap
+ * @param ms Timeout in milliseconds
+ * @param label Label for error message
+ * @returns Promise that rejects if timeout exceeded
+ */
+export declare function withTimeout<T>(promise: Promise<T>, ms: number, label: string): Promise<T>;
+/**
+ * Figma API Client
+ * Makes authenticated requests to Figma REST API
+ */
+export declare class FigmaAPI {
+    private accessToken;
+    constructor(config: FigmaAPIConfig);
+    /**
+     * Make authenticated request to Figma API
+     */
+    private request;
+    /**
+     * GET /v1/files/:file_key
+     * Get full file data including document tree, components, and styles
+     */
+    getFile(fileKey: string, options?: {
+        version?: string;
+        ids?: string[];
+        depth?: number;
+        geometry?: 'paths' | 'screen';
+        plugin_data?: string;
+        branch_data?: boolean;
+    }): Promise<any>;
+    /**
+     * GET /v1/files/:file_key/variables/local
+     * Get local variables (design tokens) from a file
+     */
+    getLocalVariables(fileKey: string): Promise<any>;
+    /**
+     * GET /v1/files/:file_key/variables/published
+     * Get published variables from a file
+     */
+    getPublishedVariables(fileKey: string): Promise<any>;
+    /**
+     * GET /v1/files/:file_key/nodes
+     * Get specific nodes by ID
+     *
+     * Node IDs are normalized to Figma's colon form ("695-313" -> "695:313")
+     * before the request, and the response map is aliased back under any
+     * dashed IDs the caller passed — Figma keys the response by colon-format
+     * IDs, so without the alias a dashed lookup silently returns undefined.
+     */
+    getNodes(fileKey: string, nodeIds: string[], options?: {
+        version?: string;
+        depth?: number;
+        geometry?: 'paths' | 'screen';
+        plugin_data?: string;
+    }): Promise<any>;
+    /**
+     * GET /v1/files/:file_key/styles
+     * Get styles from a file
+     */
+    getStyles(fileKey: string): Promise<any>;
+    /**
+     * GET /v1/files/:file_key/components
+     * Get components from a file
+     */
+    getComponents(fileKey: string): Promise<any>;
+    /**
+     * GET /v1/files/:file_key/component_sets
+     * Get component sets (variants) from a file
+     */
+    getComponentSets(fileKey: string): Promise<any>;
+    /**
+     * GET /v1/components/:key
+     * Get metadata for a single published component by its key.
+     * Returns { status, error, meta: PublishedComponent } where meta includes
+     * file_key, node_id, name, description, containing_frame, user, etc.
+     * Use this to resolve a componentKey (from search results) to its source file.
+     */
+    getComponentByKey(key: string): Promise<any>;
+    /**
+     * GET /v1/component_sets/:key
+     * Get metadata for a single published component set (variant container) by its key.
+     * Returns { status, error, meta: PublishedComponentSet } with the same fields
+     * as getComponentByKey. The node_id points to the parent COMPONENT_SET node.
+     */
+    getComponentSetByKey(key: string): Promise<any>;
+    /**
+     * GET /v1/images/:file_key
+     * Renders images for specified nodes
+     * @param fileKey - The file key
+     * @param nodeIds - Node IDs to render (single string or array)
+     * @param options - Rendering options
+     * @returns Map of node IDs to image URLs (URLs expire after 30 days)
+     */
+    getImages(fileKey: string, nodeIds: string | string[], options?: {
+        scale?: number;
+        format?: 'png' | 'jpg' | 'svg' | 'pdf';
+        svg_outline_text?: boolean;
+        svg_include_id?: boolean;
+        svg_include_node_id?: boolean;
+        svg_simplify_stroke?: boolean;
+        contents_only?: boolean;
+    }): Promise<{
+        images: Record<string, string | null>;
+    }>;
+    /**
+     * GET /v1/files/:file_key/comments
+     * Get comments on a file
+     */
+    getComments(fileKey: string, options?: {
+        as_md?: boolean;
+    }): Promise<any>;
+    /**
+     * POST /v1/files/:file_key/comments
+     * Post a comment on a file
+     */
+    postComment(fileKey: string, message: string, clientMeta?: {
+        node_id?: string;
+        node_offset?: {
+            x: number;
+            y: number;
+        };
+    }, commentId?: string): Promise<any>;
+    /**
+     * DELETE /v1/files/:file_key/comments/:comment_id
+     * Delete a comment on a file
+     */
+    deleteComment(fileKey: string, commentId: string): Promise<any>;
+    /**
+     * GET /v1/files/:file_key/versions
+     * List a file's version history. Cursor-style pagination via before/after
+     * (cursors are version IDs). Response includes pagination.prev_page and
+     * pagination.next_page as full URLs — Figma recommends following those
+     * directly rather than reconstructing cursors. Requires the
+     * `file_versions:read` OAuth scope (or PAT "Versions" Read permission).
+     */
+    getFileVersions(fileKey: string, options?: {
+        page_size?: number;
+        before?: string;
+        after?: string;
+    }): Promise<{
+        versions: Array<{
+            id: string;
+            created_at: string;
+            label: string;
+            description: string;
+            user: {
+                id: string;
+                handle: string;
+                img_url: string;
+            };
+        }>;
+        pagination?: {
+            prev_page?: string;
+            next_page?: string;
+        };
+    }>;
+    /**
+     * Helper: Get all design tokens (variables) with formatted output
+     * Both local and published can fail gracefully (e.g., 403 without Enterprise plan)
+     */
+    getAllVariables(fileKey: string): Promise<{
+        local: any;
+        published: any;
+        localError?: string;
+        publishedError?: string;
+    }>;
+    /**
+     * Helper: Get component metadata with properties
+     * Normalizes dashed node IDs ("695-313") to colon form ("695:313") so the
+     * response-map lookup matches Figma's colon-keyed response.
+     */
+    getComponentData(fileKey: string, nodeId: string, depth?: number): Promise<any>;
+    /**
+     * Helper: Search for components by name
+     */
+    searchComponents(fileKey: string, searchTerm: string): Promise<any[]>;
+}
+/**
+ * Helper function to format variables for display
+ */
+export declare function formatVariables(variablesData: any): {
+    collections: any[];
+    variables: any[];
+    summary: {
+        totalCollections: number;
+        totalVariables: number;
+        variablesByType: Record<string, number>;
+    };
+};
+/**
+ * Helper function to format component data for display
+ */
+export declare function formatComponentData(componentNode: any): {
+    id: string;
+    name: string;
+    type: string;
+    description?: string;
+    descriptionMarkdown?: string;
+    properties?: any;
+    children?: any[];
+    bounds?: any;
+    fills?: any[];
+    strokes?: any[];
+    effects?: any[];
+};
+//# sourceMappingURL=figma-api.d.ts.map

package/dist/core/figma-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figma-api.d.ts","sourceRoot":"","sources":["../../src/core/figma-api.ts"],"names":[],"mappings":"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"}