@muloka/figma-console-mcp 0.5.2 → 0.5.4

package/dist/cloudflare/apps/design-system-dashboard/server.js

@@ -0,0 +1,159 @@
+/**
+ * Design System Dashboard MCP App - Server Registration
+ *
+ * Registers tools and resource for the Design System Dashboard MCP App.
+ * Uses the official @modelcontextprotocol/ext-apps helpers for proper
+ * MCP Apps protocol compatibility with Claude Desktop.
+ *
+ * Data flow:
+ *   1. LLM calls figma_audit_design_system → server fetches + scores data,
+ *      returns SHORT summary to LLM (avoids context exhaustion)
+ *   2. UI opens, connects, calls ds_dashboard_refresh (app-only visibility)
+ *   3. ds_dashboard_refresh returns full JSON → UI renders
+ */
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { RESOURCE_MIME_TYPE, registerAppResource, registerAppTool, } from "@modelcontextprotocol/ext-apps/server";
+import { z } from "zod";
+import { scoreDesignSystem } from "./scoring/engine.js";
+const DASHBOARD_URI = "ui://figma-console/design-system-dashboard";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+// Shared state
+let lastFileUrl;
+/**
+ * Register the Design System Dashboard MCP App with the server.
+ *
+ * @param server - The MCP server instance
+ * @param getDesignSystemData - Function to fetch raw design system data from Figma
+ * @param getCurrentUrl - Optional function to get the current browser URL (for lastFileUrl tracking)
+ */
+export function registerDesignSystemDashboardApp(server, getDesignSystemData, getCurrentUrl) {
+    // Tool: fetches + scores data, returns SHORT summary to LLM
+    registerAppTool(server, "figma_audit_design_system", {
+        title: "Audit Design System Health",
+        description: "Analyze the health and AI-readiness of a Figma file's design system. Produces a scored dashboard evaluating naming conventions, token architecture, component metadata, accessibility, consistency, and coverage. Results are displayed in the dashboard UI.",
+        inputSchema: {
+            fileUrl: z
+                .string()
+                .url()
+                .optional()
+                .describe("Figma file URL. If not provided, uses the currently active file."),
+        },
+        _meta: {
+            ui: { resourceUri: DASHBOARD_URI },
+        },
+    }, async ({ fileUrl }) => {
+        try {
+            // Track the actual URL used (explicit or current browser URL)
+            // This ensures ds_dashboard_refresh uses the correct file
+            lastFileUrl = fileUrl || getCurrentUrl?.() || undefined;
+            const data = await getDesignSystemData(fileUrl);
+            const scored = scoreDesignSystem(data);
+            const categorySummaries = scored.categories
+                .map((c) => `${c.label}: ${c.score}/100`)
+                .join(", ");
+            const fileName = scored.fileInfo?.name || "Unknown file";
+            const unavailableNote = scored.dataAvailability && !scored.dataAvailability.variables
+                ? " Note: Variable/token data was unavailable (requires Enterprise plan or Desktop Bridge). Token Architecture scores reflect missing data, not actual quality."
+                : "";
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Design System: ${fileName}. Health: ${scored.overall}/100 — ${scored.status}. ${categorySummaries}.${unavailableNote} The dashboard UI is now showing detailed results.`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Design System Dashboard error: ${errorMessage}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Tool: returns full JSON data (app-only, hidden from LLM)
+    registerAppTool(server, "ds_dashboard_refresh", {
+        title: "Dashboard Refresh",
+        description: "Refresh dashboard data (called from MCP App UI)",
+        inputSchema: {
+            fileUrl: z
+                .string()
+                .url()
+                .optional()
+                .describe("Figma file URL to refresh data for."),
+        },
+        _meta: {
+            ui: {
+                resourceUri: DASHBOARD_URI,
+                visibility: ["app"],
+            },
+        },
+    }, async ({ fileUrl }) => {
+        try {
+            const url = fileUrl || lastFileUrl;
+            const data = await getDesignSystemData(url);
+            const scored = scoreDesignSystem(data);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(scored),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: errorMessage,
+                            overall: 0,
+                            status: "poor",
+                            categories: [],
+                            summary: [],
+                            meta: {
+                                componentCount: 0,
+                                variableCount: 0,
+                                collectionCount: 0,
+                                styleCount: 0,
+                                componentSetCount: 0,
+                                standaloneCount: 0,
+                                variantCount: 0,
+                                timestamp: Date.now(),
+                            },
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Resource: serves the Vite-built HTML
+    registerAppResource(server, "Design System Dashboard App", DASHBOARD_URI, {
+        description: "Interactive dashboard for evaluating design system health and AI-readiness",
+    }, async () => {
+        const htmlPath = resolve(__dirname, "mcp-app.html");
+        const html = await readFile(htmlPath, "utf-8");
+        return {
+            contents: [
+                {
+                    uri: DASHBOARD_URI,
+                    mimeType: RESOURCE_MIME_TYPE,
+                    text: html,
+                },
+            ],
+        };
+    });
+}

package/dist/cloudflare/apps/token-browser/server.js

@@ -0,0 +1,136 @@
+/**
+ * Token Browser MCP App - Server Registration
+ *
+ * Registers tools and resource for the Token Browser MCP App.
+ * Uses the official @modelcontextprotocol/ext-apps helpers for proper
+ * MCP Apps protocol compatibility with Claude Desktop.
+ *
+ * Data flow:
+ *   1. LLM calls figma_browse_tokens → server fetches + caches data,
+ *      returns SHORT summary to LLM (avoids context exhaustion)
+ *   2. UI opens, connects, calls token_browser_refresh (app-only visibility)
+ *   3. token_browser_refresh returns full JSON → UI renders
+ */
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { RESOURCE_MIME_TYPE, registerAppResource, registerAppTool, } from "@modelcontextprotocol/ext-apps/server";
+import { z } from "zod";
+const TOKEN_BROWSER_URI = "ui://figma-console/token-browser";
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+/**
+ * Register the Token Browser MCP App with the server.
+ *
+ * @param server - The MCP server instance
+ * @param getVariablesHandler - Function to fetch variables data
+ */
+export function registerTokenBrowserApp(server, getVariablesHandler) {
+    // Shared state: remember last URL so refresh tool can reuse it
+    let lastFileUrl;
+    // Tool: fetches + caches data, returns SHORT summary to LLM
+    registerAppTool(server, "figma_browse_tokens", {
+        title: "Browse Design Tokens",
+        description: "Open an interactive browser to explore design tokens (variables) from a Figma file. Shows tokens organized by collection with search, filtering, and mode switching. Data is displayed in the UI — do not attempt to list or describe the tokens in chat.",
+        inputSchema: {
+            fileUrl: z
+                .string()
+                .url()
+                .optional()
+                .describe("Figma file URL. If not provided, uses the currently active file."),
+        },
+        _meta: {
+            ui: { resourceUri: TOKEN_BROWSER_URI },
+        },
+    }, async ({ fileUrl }) => {
+        try {
+            lastFileUrl = fileUrl;
+            const result = await getVariablesHandler(fileUrl);
+            const varCount = result.variables?.length || 0;
+            const colCount = result.collections?.length || 0;
+            // Count by type
+            const colors = result.variables?.filter((v) => v.resolvedType === "COLOR")
+                .length || 0;
+            const numbers = result.variables?.filter((v) => v.resolvedType === "FLOAT")
+                .length || 0;
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Token Browser opened: ${varCount} tokens across ${colCount} collections (${colors} colors, ${numbers} numbers). The interactive UI is now displaying the results — users can search, filter by type, and browse by collection.`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Token Browser error: ${errorMessage}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Tool: returns full JSON data (app-only, hidden from LLM)
+    registerAppTool(server, "token_browser_refresh", {
+        title: "Token Browser Refresh",
+        description: "Refresh token data (called from MCP App UI)",
+        inputSchema: {
+            fileUrl: z
+                .string()
+                .url()
+                .optional()
+                .describe("Figma file URL to refresh data for."),
+        },
+        _meta: {
+            ui: {
+                resourceUri: TOKEN_BROWSER_URI,
+                visibility: ["app"],
+            },
+        },
+    }, async ({ fileUrl }) => {
+        try {
+            const url = fileUrl || lastFileUrl;
+            const result = await getVariablesHandler(url);
+            return {
+                content: [{ type: "text", text: JSON.stringify(result) }],
+            };
+        }
+        catch (error) {
+            const errorMessage = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: errorMessage,
+                            variables: [],
+                            collections: [],
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Resource: serves the Vite-built HTML
+    registerAppResource(server, "Token Browser App", TOKEN_BROWSER_URI, {
+        description: "Interactive browser for exploring Figma design tokens and variables",
+    }, async () => {
+        const htmlPath = resolve(__dirname, "mcp-app.html");
+        const html = await readFile(htmlPath, "utf-8");
+        return {
+            contents: [
+                {
+                    uri: TOKEN_BROWSER_URI,
+                    mimeType: RESOURCE_MIME_TYPE,
+                    text: html,
+                },
+            ],
+        };
+    });
+}

package/dist/cloudflare/browser-manager.js

@@ -0,0 +1,157 @@
+/**
+ * Browser Manager
+ * Manages Puppeteer browser instance lifecycle for Cloudflare Browser Rendering API
+ */
+import puppeteer from '@cloudflare/puppeteer';
+import { createChildLogger } from './core/logger.js';
+const logger = createChildLogger({ component: 'browser-manager' });
+/**
+ * Browser Manager
+ * Handles browser instance creation, page management, and navigation
+ */
+export class BrowserManager {
+    constructor(env, config) {
+        this.browser = null;
+        this.page = null;
+        this.env = env;
+        this.config = config;
+    }
+    /**
+     * Launch browser instance
+     */
+    async launch() {
+        if (this.browser) {
+            logger.info('Browser already running, reusing instance');
+            return this.browser;
+        }
+        logger.info('Launching browser with Cloudflare Browser Rendering API');
+        try {
+            this.browser = await puppeteer.launch(this.env.BROWSER, {
+                keep_alive: 600000, // Keep alive for 10 minutes
+            });
+            logger.info('Browser launched successfully');
+            return this.browser;
+        }
+        catch (error) {
+            logger.error({ error }, 'Failed to launch browser');
+            throw new Error(`Browser launch failed: ${error}`);
+        }
+    }
+    /**
+     * Get or create a page instance
+     */
+    async getPage() {
+        if (!this.browser) {
+            await this.launch();
+        }
+        if (this.page && !this.page.isClosed()) {
+            return this.page;
+        }
+        logger.info('Creating new browser page');
+        this.page = await this.browser.newPage();
+        // Set viewport size
+        await this.page.setViewport({
+            width: 1920,
+            height: 1080,
+            deviceScaleFactor: 1,
+        });
+        logger.info('Browser page created');
+        return this.page;
+    }
+    /**
+     * Navigate to Figma URL
+     */
+    async navigateToFigma(figmaUrl) {
+        const page = await this.getPage();
+        // Default to Figma homepage if no URL provided
+        const url = figmaUrl || 'https://www.figma.com';
+        logger.info({ url }, 'Navigating to Figma');
+        try {
+            await page.goto(url, {
+                waitUntil: 'networkidle2',
+                timeout: 30000,
+            });
+            logger.info({ url }, 'Navigation successful');
+            return { page, action: 'navigated', url };
+        }
+        catch (error) {
+            logger.error({ error, url }, 'Navigation failed');
+            throw new Error(`Failed to navigate to ${url}: ${error}`);
+        }
+    }
+    /**
+     * Reload current page
+     */
+    async reload(hardReload = false) {
+        if (!this.page || this.page.isClosed()) {
+            throw new Error('No active page to reload');
+        }
+        logger.info({ hardReload }, 'Reloading page');
+        try {
+            await this.page.reload({
+                waitUntil: 'networkidle2',
+                timeout: 30000,
+            });
+            logger.info('Page reloaded successfully');
+        }
+        catch (error) {
+            logger.error({ error }, 'Page reload failed');
+            throw new Error(`Page reload failed: ${error}`);
+        }
+    }
+    /**
+     * Execute JavaScript in page context
+     */
+    async evaluate(fn) {
+        const page = await this.getPage();
+        return page.evaluate(fn);
+    }
+    // Screenshot functionality removed - use Figma REST API's getImages() instead
+    // See: figma_take_screenshot and figma_get_component_image tools
+    /**
+     * Check if browser is running
+     */
+    isRunning() {
+        return this.browser !== null && this.browser.isConnected();
+    }
+    /**
+     * Close browser instance
+     */
+    async close() {
+        if (!this.browser) {
+            return;
+        }
+        logger.info('Closing browser');
+        try {
+            await this.browser.close();
+            this.browser = null;
+            this.page = null;
+            logger.info('Browser closed successfully');
+        }
+        catch (error) {
+            logger.error({ error }, 'Failed to close browser');
+            throw error;
+        }
+    }
+    /**
+     * Get current page URL
+     */
+    getCurrentUrl() {
+        if (!this.page || this.page.isClosed()) {
+            return null;
+        }
+        return this.page.url();
+    }
+    /**
+     * Wait for navigation
+     */
+    async waitForNavigation(timeout = 30000) {
+        if (!this.page || this.page.isClosed()) {
+            throw new Error('No active page');
+        }
+        await this.page.waitForNavigation({
+            waitUntil: 'networkidle2',
+            timeout,
+        });
+    }
+}