figma-console-mcp 1.22.3 → 1.23.0

package/README.md

@@ -8,20 +8,19 @@
 
 > **Your design system as an API.** Model Context Protocol server that bridges design and development—giving AI assistants complete access to Figma for **extraction**, **creation**, and **debugging**.
 
-> **🆕 Comprehensive Accessibility Scanning (v1.22.0):** Full-spectrum WCAG coverage across design and code — 13 design-side lint rules, component accessibility scorecards with color-blind simulation, code-side scanning via axe-core (104 rules), and design-to-code accessibility parity checking. No rule database to maintain. [See what's new →](docs/figma-mcp-vs-figma-console-mcp.md)
+> **🆕 Version History & Time-Series Awareness (v1.23.0):** Six new tools turn a Figma file from a static snapshot into a queryable history — list versions, snapshot any past version, diff two versions for component/binding deltas, generate markdown changelogs ready for release notes, and trace exactly when (and by whom) a property or variant was introduced via a binary-search blame walker. Author attribution flows from autosaves, not just labeled releases. [See what's new →](CHANGELOG.md#1230---2026-05-09)
 
 ## What is this?
 
 Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
 
-- **🐛 Plugin debugging** - Capture console logs, errors, and stack traces
-- **📸 Visual debugging** - Take screenshots for context
 - **🎨 Design system extraction** - Pull variables, components, and styles
+- **📸 Visual debugging** - Take screenshots for context
 - **✏️ Design creation** - Create UI components, frames, and layouts directly in Figma
 - **🔧 Variable management** - Create, update, rename, and delete design tokens
-- **⚡ Real-time monitoring** - Watch logs as plugins execute
+- **⚡ Real-time monitoring** - Watch console logs from the Desktop Bridge plugin
 - **📌 FigJam boards** - Create stickies, flowcharts, tables, and code blocks on collaborative boards
-- **♿ Accessibility scanning** - 13 WCAG design checks, component scorecards, axe-core code scanning, design-to-code parity
+- **♿ Accessibility scanning** - 14 WCAG design checks with conformance level tagging, component scorecards, axe-core code scanning, design-to-code parity
 - **☁️ Cloud Write Relay** - Web AI clients (Claude.ai, v0, Replit) can design in Figma via cloud pairing
 - **🔄 Four ways to connect** - Remote SSE, Cloud Mode, NPX, or Local Git
 
@@ -52,9 +51,9 @@ Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
 | Real-time monitoring (console, selection) | ✅ | ❌ | ❌ |
 | Desktop Bridge plugin | ✅ | ✅ | ❌ |
 | Requires Node.js | Yes | **No** | No |
-| **Total tools available** | **94+** | **43** | **22** |
+| **Total tools available** | **100+** | **83** | **9** |
 
-> **Bottom line:** Remote SSE is **read-only** with ~38% of the tools. **Cloud Mode** unlocks write access from web AI clients without Node.js. NPX/Local Git gives the full 94+ tools with real-time monitoring.
+> **Bottom line:** Remote SSE is **read-only** with ~38% of the tools. **Cloud Mode** unlocks write access from web AI clients without Node.js. NPX/Local Git gives the full 100+ tools with real-time monitoring.
 
 ---
 
@@ -62,7 +61,7 @@ Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
 
 **Best for:** Designers who want full AI-assisted design capabilities.
 
-**What you get:** All 94+ tools including design creation, variable management, and component instantiation.
+**What you get:** All 100+ tools including design creation, variable management, and component instantiation.
 
 #### Prerequisites
 
@@ -75,7 +74,7 @@ Figma Console MCP connects AI assistants (like Claude) to Figma, enabling:
 1. Go to [Manage personal access tokens](https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens) in Figma Help
 2. Follow the steps to **create a new personal access token**
 3. Enter description: `Figma Console MCP`
-4. Set scopes: **File content** (Read), **Variables** (Read), **Comments** (Read and write)
+4. Set scopes: **File content** (Read), **File versions** (Read), **Variables** (Read), **Comments** (Read and write)
 5. **Copy the token** — you won't see it again! (starts with `figd_`)
 
 #### Step 2: Configure Your MCP Client
@@ -157,7 +156,7 @@ Create a simple frame with a blue background
 
 **Best for:** Developers who want to modify source code or contribute to the project.
 
-**What you get:** Same 94+ tools as NPX, plus full source code access.
+**What you get:** Same 100+ tools as NPX, plus full source code access.
 
 #### Quick Setup
 
@@ -303,7 +302,7 @@ AI Client → Cloud MCP Server → Durable Object Relay → Desktop Bridge Plugi
 | Feature | NPX (Recommended) | Cloud Mode | Local Git | Remote SSE |
 |---------|-------------------|------------|-----------|------------|
 | **Setup time** | ~10 minutes | ~5 minutes | ~15 minutes | ~2 minutes |
-| **Total tools** | **94+** | **43** | **94+** | **22** (read-only) |
+| **Total tools** | **100+** | **83** | **100+** | **9** (read-only) |
 | **Design creation** | ✅ | ✅ | ✅ | ❌ |
 | **Variable management** | ✅ | ✅ | ✅ | ❌ |
 | **Component instantiation** | ✅ | ✅ | ✅ | ❌ |
@@ -318,7 +317,7 @@ AI Client → Cloud MCP Server → Durable Object Relay → Desktop Bridge Plugi
 | **Automatic updates** | ✅ (`@latest`) | ✅ | Manual (`git pull`) | ✅ |
 | **Source code access** | ❌ | ❌ | ✅ | ❌ |
 
-> **Key insight:** Remote SSE is read-only. Cloud Mode adds write access for web AI clients without Node.js. NPX/Local Git give the full 94+ tools.
+> **Key insight:** Remote SSE is read-only. Cloud Mode adds write access for web AI clients without Node.js. NPX/Local Git give the full 100+ tools.
 
 **📖 [Complete Feature Comparison](docs/mode-comparison.md)**
 
@@ -364,7 +363,7 @@ When you first use design system tools:
 ### Local Mode - Personal Access Token (Manual)
 
 1. Visit https://help.figma.com/hc/en-us/articles/8085703771159-Manage-personal-access-tokens
-2. Generate token with scopes: **File content** (Read), **Variables** (Read), **Comments** (Read and write)
+2. Generate token with scopes: **File content** (Read), **File versions** (Read), **Variables** (Read), **Comments** (Read and write)
 3. Add to MCP config as `FIGMA_ACCESS_TOKEN` environment variable
 
 ---
@@ -652,7 +651,7 @@ The **Figma Desktop Bridge** plugin is the recommended way to connect Figma to t
 - The MCP server communicates via **WebSocket** through the Desktop Bridge plugin
 - The server tries port 9223 first, then automatically falls back through ports 9224–9232 if needed
 - The plugin scans all ports in the range and connects to every active server it finds
-- All 94+ tools work through the WebSocket transport
+- All 100+ tools work through the WebSocket transport
 
 **Multiple files:** The WebSocket server supports multiple simultaneous plugin connections — one per open Figma file. Each connection is tracked by file key with independent state (selection, document changes, console logs).
 
@@ -789,7 +788,7 @@ The architecture supports adding new apps with minimal boilerplate — each app
 
 ## 🛤️ Roadmap
 
-**Current Status:** v1.17.0 (Stable) - Production-ready with FigJam + Slides support, Cloud Write Relay, Design System Kit, WebSocket-only connectivity, smart multi-file tracking, 94+ tools, Comments API, and MCP Apps
+**Current Status:** v1.17.0 (Stable) - Production-ready with FigJam + Slides support, Cloud Write Relay, Design System Kit, WebSocket-only connectivity, smart multi-file tracking, 100+ tools, Comments API, and MCP Apps
 
 **Recent Releases:**
 - [x] **v1.17.0** - Figma Slides Support: 15 new tools for managing presentations — slides, transitions, content, reordering, and navigation. Inspired by Toni Haidamous (PR #11).

package/dist/cloudflare/core/accessibility-tools.js

@@ -0,0 +1,306 @@
+/**
+ * Code-side accessibility scanning via axe-core + JSDOM.
+ *
+ * Delegates all rule logic to axe-core (Deque) — the MCP never owns
+ * a rule database. JSDOM provides a lightweight DOM for structural checks
+ * (~50 rules: ARIA, semantics, alt text, form labels, headings, landmarks).
+ *
+ * Visual rules (color contrast, focus-visible) are NOT available via JSDOM —
+ * those are handled by the design-side figma_lint_design tool.
+ */
+import { z } from "zod";
+import { logger } from "./logger.js";
+// Lazy-load axe-core and jsdom to keep them optional
+let axeCore = null;
+let JSDOM = null;
+let depsLoaded = false;
+let depsError = null;
+async function loadDeps() {
+    if (depsLoaded)
+        return;
+    try {
+        axeCore = await import("axe-core");
+        // axe-core's default export structure
+        if (axeCore.default)
+            axeCore = axeCore.default;
+        const jsdomModule = await import("jsdom");
+        JSDOM = jsdomModule.JSDOM;
+        depsLoaded = true;
+    }
+    catch (e) {
+        depsError = `axe-core or jsdom not installed. Run: npm install axe-core jsdom\n${e.message}`;
+        throw new Error(depsError);
+    }
+}
+/**
+ * Run axe-core against an HTML string using JSDOM.
+ *
+ * JSDOM limitations: no computed styles, no layout, no visual rendering.
+ * This means ~50-60 structural rules work, but visual rules
+ * (color-contrast, focus-visible, etc.) will report as "incomplete".
+ */
+async function scanHtmlWithAxe(html, options = {}) {
+    await loadDeps();
+    // Wrap HTML fragment in a full document if needed
+    const fullHtml = html.includes("<html") || html.includes("<!DOCTYPE")
+        ? html
+        : `<!DOCTYPE html><html lang="en"><head><title>Scan</title></head><body>${html}</body></html>`;
+    const dom = new JSDOM(fullHtml, {
+        runScripts: "dangerously",
+        pretendToBeVisual: true,
+        url: "http://localhost",
+    });
+    const { document, window } = dom.window;
+    // Inject axe-core into the JSDOM window
+    const axeSource = axeCore.source;
+    const scriptEl = document.createElement("script");
+    scriptEl.textContent = axeSource;
+    document.head.appendChild(scriptEl);
+    // Configure axe run options
+    const runOptions = {};
+    if (options.tags && options.tags.length > 0) {
+        runOptions.runOnly = { type: "tag", values: options.tags };
+    }
+    // Disable rules that require visual rendering (always fail/incomplete in JSDOM)
+    if (options.disableVisualRules !== false) {
+        runOptions.rules = {
+            "color-contrast": { enabled: false },
+            "color-contrast-enhanced": { enabled: false },
+            "link-in-text-block": { enabled: false },
+        };
+    }
+    // Determine scan context
+    const context = options.context || document;
+    try {
+        const results = await window.axe.run(context, runOptions);
+        // Clean up
+        dom.window.close();
+        return results;
+    }
+    catch (err) {
+        dom.window.close();
+        throw new Error(`axe-core scan failed: ${err.message}`);
+    }
+}
+/**
+ * Extract a CodeSpec.accessibility object from HTML + axe-core results.
+ * This bridges Phase 3 (code scanning) → Phase 4 (parity comparison).
+ *
+ * Parses the HTML to extract semantic element, ARIA attributes, and states.
+ * Uses axe-core results to infer what the code supports.
+ */
+export function axeResultsToCodeSpec(html, axeResults) {
+    const spec = {};
+    // Parse HTML to extract attributes (lightweight regex-based, no DOM needed)
+    const htmlLower = html.toLowerCase();
+    // Semantic element: find the root/first meaningful element
+    const rootElementMatch = html.match(/<(button|a|input|select|textarea|details|dialog|nav|main|form|label|fieldset)\b/i);
+    if (rootElementMatch) {
+        spec.semanticElement = rootElementMatch[1].toLowerCase();
+    }
+    else {
+        const firstElementMatch = html.match(/<(\w+)[\s>]/);
+        if (firstElementMatch && !["div", "span", "html", "head", "body", "script", "style", "!doctype"].includes(firstElementMatch[1].toLowerCase())) {
+            spec.semanticElement = firstElementMatch[1].toLowerCase();
+        }
+        else {
+            spec.semanticElement = "div";
+        }
+    }
+    // ARIA role
+    const roleMatch = html.match(/role=["']([^"']+)["']/i);
+    if (roleMatch) {
+        spec.role = roleMatch[1];
+    }
+    // ARIA label
+    const ariaLabelMatch = html.match(/aria-label=["']([^"']+)["']/i);
+    if (ariaLabelMatch) {
+        spec.ariaLabel = ariaLabelMatch[1];
+    }
+    // Focus visible: check for :focus-visible or :focus in inline styles/class names,
+    // or infer from element type (native interactive elements have default focus)
+    const nativeFocusElements = ["button", "a", "input", "select", "textarea"];
+    const hasFocusCSS = /focus-visible|:focus\b|outline.*focus|ring.*focus|focus.*ring/i.test(html);
+    spec.focusVisible = hasFocusCSS || nativeFocusElements.includes(spec.semanticElement || "");
+    // Disabled support: only assert true when we find positive evidence.
+    // Absence of disabled/aria-disabled in a single HTML snapshot does NOT mean
+    // the component lacks disabled support — it may be in a non-disabled state.
+    if (/\bdisabled\b|aria-disabled/i.test(htmlLower)) {
+        spec.supportsDisabled = true;
+    }
+    // (leave undefined when not found — absence ≠ lack of support)
+    // Error support: same principle — only assert true on positive evidence.
+    // A default-state HTML snippet won't have aria-invalid; that doesn't mean
+    // the component can't enter an error state.
+    if (/aria-invalid|aria-errormessage|aria-describedby.*error/i.test(htmlLower)) {
+        spec.supportsError = true;
+    }
+    // (leave undefined when not found — scan a different state to confirm)
+    // Required: check for required or aria-required attributes
+    if (/aria-required=["']true["']|required(?!=)/i.test(html)) {
+        spec.ariaRequired = true;
+    }
+    else if (/aria-required=["']false["']/i.test(html)) {
+        spec.ariaRequired = false;
+    }
+    // Keyboard interactions: infer from element type
+    const keyboardInteractions = [];
+    if (spec.semanticElement === "button" || spec.role === "button") {
+        keyboardInteractions.push("Enter", "Space");
+    }
+    else if (spec.semanticElement === "a" || spec.role === "link") {
+        keyboardInteractions.push("Enter");
+    }
+    else if (spec.semanticElement === "input" || spec.semanticElement === "textarea") {
+        keyboardInteractions.push("Tab (focus)", "Type (input)");
+    }
+    else if (spec.semanticElement === "select" || spec.role === "listbox") {
+        keyboardInteractions.push("Arrow keys", "Enter", "Space");
+    }
+    else if (spec.role === "checkbox" || spec.role === "switch") {
+        keyboardInteractions.push("Space");
+    }
+    else if (spec.role === "tab") {
+        keyboardInteractions.push("Arrow keys");
+    }
+    // Check HTML for custom keyboard handlers
+    if (/onkeydown|onkeyup|onkeypress|@keydown|@keyup|v-on:keydown/i.test(html)) {
+        if (!keyboardInteractions.includes("Custom key handler")) {
+            keyboardInteractions.push("Custom key handler");
+        }
+    }
+    if (keyboardInteractions.length > 0) {
+        spec.keyboardInteractions = keyboardInteractions;
+    }
+    // Use axe-core results to refine: if certain violations exist, it tells us what's missing
+    if (axeResults?.violations) {
+        for (const v of axeResults.violations) {
+            // If button-name violation exists, the button has no accessible name
+            if (v.id === "button-name") {
+                spec.ariaLabel = undefined; // Explicitly missing
+            }
+            // If label violation exists, input lacks a label
+            if (v.id === "label") {
+                spec.ariaLabel = undefined;
+            }
+        }
+    }
+    return spec;
+}
+/**
+ * Format axe-core results into our standard lint-like output structure.
+ */
+function formatAxeResults(axeResults) {
+    const categories = [];
+    const severityMap = {
+        critical: "critical",
+        serious: "critical",
+        moderate: "warning",
+        minor: "info",
+    };
+    // Group violations
+    for (const violation of axeResults.violations || []) {
+        const severity = severityMap[violation.impact] || "warning";
+        const nodes = violation.nodes.map((node) => ({
+            html: node.html?.substring(0, 200),
+            target: node.target,
+            failureSummary: node.failureSummary?.substring(0, 300),
+        }));
+        categories.push({
+            rule: violation.id,
+            severity,
+            count: violation.nodes.length,
+            description: violation.help,
+            wcagTags: violation.tags.filter((t) => t.startsWith("wcag") || t.startsWith("best-practice")),
+            helpUrl: violation.helpUrl,
+            nodes: nodes.slice(0, 10), // Cap at 10 per rule
+        });
+    }
+    // Sort: critical first, then by count
+    categories.sort((a, b) => {
+        const sevOrder = { critical: 0, warning: 1, info: 2 };
+        if (sevOrder[a.severity] !== sevOrder[b.severity]) {
+            return sevOrder[a.severity] - sevOrder[b.severity];
+        }
+        return b.count - a.count;
+    });
+    // Summary
+    const summary = { critical: 0, warning: 0, info: 0, total: 0 };
+    for (const cat of categories) {
+        summary[cat.severity] += cat.count;
+        summary.total += cat.count;
+    }
+    return {
+        engine: "axe-core",
+        version: axeResults.testEngine?.version || "unknown",
+        mode: "jsdom-structural",
+        note: "JSDOM mode: structural/semantic checks only. Visual rules (color contrast, focus visibility) are disabled — use figma_lint_design for visual accessibility checks.",
+        categories,
+        summary,
+        passes: axeResults.passes?.length || 0,
+        incomplete: axeResults.incomplete?.length || 0,
+        inapplicable: axeResults.inapplicable?.length || 0,
+    };
+}
+export function registerAccessibilityTools(server) {
+    server.tool("figma_scan_code_accessibility", "Scan HTML code for accessibility violations using axe-core (Deque). " +
+        "Runs structural/semantic checks via JSDOM: ARIA attributes, roles, labels, alt text, " +
+        "form labels, heading order, landmarks, semantic HTML, tabindex, duplicate IDs, lang attribute, and ~50 more rules. " +
+        "Visual checks (color contrast, focus visibility) are disabled in this mode — use figma_lint_design for visual a11y on the design side. " +
+        "Together, these two tools provide full-spectrum accessibility coverage across design and code. " +
+        "Pass component HTML directly or use with figma_check_design_parity for design-to-code a11y comparison. " +
+        "No Figma connection required — this is a standalone code analysis tool.", {
+        html: z.string().describe("HTML string to scan. Can be a full document or a component fragment (will be wrapped in a valid document)."),
+        tags: z.array(z.string()).optional().describe("WCAG tag filter. Examples: ['wcag2a'], ['wcag2aa'], ['wcag21aa'], ['wcag22aa'], ['best-practice']. " +
+            "Defaults to all structural rules if omitted."),
+        context: z.string().optional().describe("CSS selector to scope the scan to a specific element (e.g., '#my-component', '.card'). Scans entire document if omitted."),
+        includePassingRules: z.boolean().optional().describe("If true, includes count of passing and incomplete rules in the response (default: false)."),
+        mapToCodeSpec: z.boolean().optional().describe("If true, includes a codeSpec.accessibility object auto-extracted from the HTML + scan results. " +
+            "Pass this directly into figma_check_design_parity's codeSpec.accessibility field for automated design-to-code a11y parity checking."),
+    }, async ({ html, tags, context, includePassingRules, mapToCodeSpec }) => {
+        try {
+            const axeResults = await scanHtmlWithAxe(html, {
+                tags: tags || undefined,
+                context: context || undefined,
+            });
+            const formatted = formatAxeResults(axeResults);
+            // Optionally strip pass/incomplete counts to save tokens
+            if (!includePassingRules) {
+                delete formatted.passes;
+                delete formatted.incomplete;
+                delete formatted.inapplicable;
+            }
+            // Auto-generate CodeSpec.accessibility from HTML + results
+            if (mapToCodeSpec) {
+                formatted.codeSpecAccessibility = axeResultsToCodeSpec(html, axeResults);
+                formatted.codeSpecAccessibility._usage = "Pass this object as codeSpec.accessibility in figma_check_design_parity for automated a11y parity checking.";
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(formatted, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const isDepsError = error.message?.includes("not installed");
+            logger.error({ error }, "Failed to scan code accessibility");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: error.message,
+                            hint: isDepsError
+                                ? "Install dependencies: npm install axe-core jsdom"
+                                : "Check that the HTML is valid. For visual accessibility checks, use figma_lint_design instead.",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/cloudflare/core/cloud-websocket-connector.js

@@ -32,25 +32,27 @@ export class CloudWebSocketConnector {
         return this.sendCommand('GET_VARIABLES_DATA', {}, 10000);
     }
     async getVariables(fileKey) {
+        // IMPORTANT: bare try/catch with top-level `return`, NO inner IIFE.
+        // See issue #68 + the matching note in websocket-connector.ts. The plugin
+        // (code.js) wraps every EXECUTE_CODE payload in its own async IIFE; nesting
+        // another swallows the inner return and silently drops the variables.
         const code = `
-      (async () => {
-        try {
-          if (typeof figma === 'undefined') {
-            throw new Error('Figma API not available in this context');
-          }
-          const variables = await figma.variables.getLocalVariablesAsync();
-          const collections = await figma.variables.getLocalVariableCollectionsAsync();
-          return {
-            success: true,
-            timestamp: Date.now(),
-            fileMetadata: { fileName: figma.root.name, fileKey: figma.fileKey || null },
-            variables: variables.map(function(v) { return { id: v.id, name: v.name, key: v.key, resolvedType: v.resolvedType, valuesByMode: v.valuesByMode, variableCollectionId: v.variableCollectionId, scopes: v.scopes, description: v.description, hiddenFromPublishing: v.hiddenFromPublishing }; }),
-            variableCollections: collections.map(function(c) { return { id: c.id, name: c.name, key: c.key, modes: c.modes, defaultModeId: c.defaultModeId, variableIds: c.variableIds }; })
-          };
-        } catch (error) {
-          return { success: false, error: error.message };
+      try {
+        if (typeof figma === 'undefined') {
+          throw new Error('Figma API not available in this context');
         }
-      })()
+        const variables = await figma.variables.getLocalVariablesAsync();
+        const collections = await figma.variables.getLocalVariableCollectionsAsync();
+        return {
+          success: true,
+          timestamp: Date.now(),
+          fileMetadata: { fileName: figma.root.name, fileKey: figma.fileKey || null },
+          variables: variables.map(function(v) { return { id: v.id, name: v.name, key: v.key, resolvedType: v.resolvedType, valuesByMode: v.valuesByMode, variableCollectionId: v.variableCollectionId, scopes: v.scopes, description: v.description, hiddenFromPublishing: v.hiddenFromPublishing }; }),
+          variableCollections: collections.map(function(c) { return { id: c.id, name: c.name, key: c.key, modes: c.modes, defaultModeId: c.defaultModeId, variableIds: c.variableIds }; })
+        };
+      } catch (error) {
+        return { success: false, error: error.message };
+      }
     `;
         return this.sendCommand('EXECUTE_CODE', { code, timeout: 30000 }, 32000);
     }
@@ -262,6 +264,17 @@ export class CloudWebSocketConnector {
         return this.sendCommand('LINT_DESIGN', params, 120000);
     }
     // ============================================================================
+    // Component accessibility audit
+    // ============================================================================
+    async auditComponentAccessibility(nodeId, targetSize) {
+        const params = {};
+        if (nodeId)
+            params.nodeId = nodeId;
+        if (targetSize !== undefined)
+            params.targetSize = targetSize;
+        return this.sendCommand('AUDIT_COMPONENT_ACCESSIBILITY', params, 120000);
+    }
+    // ============================================================================
     // FigJam operations
     // ============================================================================
     async createSticky(params) {