figma-console-mcp 1.38.0 → 1.39.0

package/README.md

@@ -8,7 +8,7 @@
 
 > **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**, **debugging**, and **bidirectional token sync**.
 
-> **🆕 Ongoing Component Changelogs in Generated Docs (v1.38.0):** `figma_generate_component_doc` now pulls a *real* changelog instead of only echoing hand-written entries. Opt in with `history: { figma: true, git: true }` to get a `## History` section combining **design history** — Figma version history diffed per version and scoped to that component, so you see the rename, the property that was added, the tokens that got bound — with **code history** from `git log` on the component's source files, auto-derived from `codeInfo`. Prefers labeled versions and falls back to auto-saves when a file has none (most don't). Off by default, so existing calls are byte-identical. Server-only release — **no plugin re-import needed**. [See what's new →](CHANGELOG.md#1380---2026-07-25)
+> **🗂 Multi-File Execution (v1.39.0):** Work across several Figma files at once. `figma_execute_across_files` runs one script against every (or a chosen subset of) connected file **concurrently** — for auditing a multi-file design system for the same problem, or applying one fix across a known set, instead of switching the active file and repeating yourself. Four files × 2s of work completes in ~3s, not ~8s. `figma_execute` also takes an optional `fileKey` to target a single file without moving the active file or releasing target lock. You must name `fileKeys` or pass `allFiles: true` — there's no fan-out-to-everything default, since this runs code in files you may be actively editing. From community PR [#107](https://github.com/southleft/figma-console-mcp/pull/107) by [@Wolfr](https://github.com/Wolfr). Also fixes a relay bug that silently dropped `resultAnalysis` and `fileContext` from every `figma_execute` response — **re-import `manifest.json`** for those two fields; everything else works without it. [See what's new →](CHANGELOG.md#1390---2026-08-02)
 
 ## What is this?
 
@@ -56,9 +56,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** | **113** | **101** | **9** |
+| **Total tools available** | **114** | **101** | **9** |
 
-> **Bottom line:** Remote SSE is **read-only** with 9 tools. **Cloud Mode** unlocks write access (101 tools) from web AI clients without Node.js. NPX/Local Git gives the full 113 tools with real-time monitoring.
+> **Bottom line:** Remote SSE is **read-only** with 9 tools. **Cloud Mode** unlocks write access (101 tools) from web AI clients without Node.js. NPX/Local Git gives the full 114 tools with real-time monitoring.
 
 ---
 
@@ -66,7 +66,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 113 tools including design creation, variable management, and component instantiation.
+**What you get:** All 114 tools including design creation, variable management, and component instantiation.
 
 #### Prerequisites
 
@@ -163,7 +163,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 113 tools as NPX, plus full source code access.
+**What you get:** Same 114 tools as NPX, plus full source code access.
 
 #### Quick Setup
 
@@ -309,7 +309,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** | **113** | **101** | **113** | **9** (read-only) |
+| **Total tools** | **114** | **101** | **114** | **9** (read-only) |
 | **Design creation** | ✅ | ✅ | ✅ | ❌ |
 | **Variable management** | ✅ | ✅ | ✅ | ❌ |
 | **Component instantiation** | ✅ | ✅ | ✅ | ❌ |
@@ -324,7 +324,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 113 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 114 tools.
 
 **📖 [Complete Feature Comparison](docs/mode-comparison.md)**
 
@@ -417,6 +417,10 @@ When you first use design system tools:
   - Create frames, shapes, text, components
   - Apply auto-layout, styles, effects
   - Build complete UI mockups programmatically
+  - Optional `fileKey` targets one specific connected file directly (Local Mode only), without touching the active file or target lock
+- `figma_execute_across_files` - **Local Mode only.** Run the same script in several Desktop Bridge-connected files at once, concurrently, returning a per-file result map — for cross-file consistency checks and fixes across a multi-file design system, replacing "open file, run plugin, repeat per file"
+  - Name the files with `fileKeys` (from `figma_list_open_files`), or pass `allFiles: true` to hit every connected file — one of the two is required, so a script never fans out to files you didn't mean to touch
+  - Per-file timeouts and error isolation: one slow or failing file doesn't delay or fail the others
 - `figma_create_component_set` - **Create a component set with variants in one declarative call**
   - Generate every variant combination from an axes matrix (e.g. `{ State: ["default", "hover", "disabled"], Size: ["sm", "lg"] }` → 6 variants) off a base component, or combine existing components
   - `Prop=Value` variant naming, `combineAsVariants` under the hood, optional auto-arranged labeled grid
@@ -682,7 +686,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 113 tools work through the WebSocket transport
+- All 114 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).
 
@@ -823,9 +827,12 @@ The architecture supports adding new apps with minimal boilerplate — each app
 
 ## 🛤️ Roadmap
 
-**Current Status:** v1.38.0 (Stable) - Production-ready. Latest: Ongoing component changelogs in generated docs — `figma_generate_component_doc` takes an opt-in `history` parameter that pulls per-component **design history** from Figma version history (each version diffed and scoped to that component, so renames, added properties, and token bindings show up as rows) alongside **code history** from `git log` on the component's source files, rendered as a `## History` section with design, code, and release-note tables. Prefers labeled versions, falls back to auto-saves when a file has none, and is off by default so existing calls are unchanged (server-only, no plugin re-import). On top of v1.37.x's design-system health audit for every client — `figma_audit_design_system_report` runs the dashboard's deterministic six-category scoring engine and returns the report as data with per-finding remediation, live-first fileKey-verified data (source disclosed), chunked per-category drill-down, and a 5-minute cache (server-only, no plugin re-import). On top of v1.36.0's target lock for multi-file parallel work — — `figma_navigate` takes a `lock: true` flag that pins the active file so an AI agent can work in one file while you work in another without commands routing to the wrong file. On top of v1.35.0's Figma Slots write support — create, inspect, populate, and reset Slots (GA at Config 2026) via 5 new tools (`figma_create_slot`, `figma_get_slots`, `figma_append_to_slot`, `figma_reset_slot`, `figma_add_slot_property`), live-validated against the GA Plugin API and based on community PR #77. On top of v1.34.0's Bidirectional Token Sync v2 + DTCG 2025.10 — `figma_import_tokens` applies the complete diff plan (creates missing collections/variables, applies renames, writes real `VARIABLE_ALIAS` references, and deletes only under explicit `replace`), `figma_export_tokens` speaks the DTCG 2025.10 dialect on request (legacy default byte-identical), variable scopes/codeSyntax round-trip via `$extensions`, `figma_setup_design_tokens` accepts alias values via DTCG brace references, and `figma_create_component_set` builds a full variant set from an axes matrix in one call. On top of the v1.33.x line: version-handshake fix (re-import banner only fires when plugin files actually changed), security dependency sweep, and the v1.33.0 connection UX overhaul (honest status pill derived from live connection state, `/health` auto-discovery with self-healing reconnect) + a 33-fix full-codebase audit (lossless DTCG multi-mode round-trips, cross-collection alias resolution, branch-URL correctness across REST tools, cache-poisoning and CSWSH fixes, bridge-first screenshots). Built on WCAG-accurate accessibility auditing (line height below 1.5× is no longer mis-flagged as a failure; readability hints decoupled from conformance checks and scoped to multi-line text; code-side WCAG 1.4.12 check), a self-healing Desktop Bridge connection (zombie-process reaper + auto-reconnect watchdog — fixes the recurring "not connected until restart" bug), native variable binding on fills/strokes + typography control in the write tools, shared-library inspection (key-based component resolution + library variable read/import without Enterprise plan), 10-format token export pipeline (DTCG, CSS, Tailwind v4, Tailwind v3, SCSS, TS module, JSON flat/nested, Style Dictionary v3, Tokens Studio), bidirectional Figma↔code token sync, version history & time-series awareness, FigJam + Slides support, Cloud Write Relay, Design System Kit, WebSocket-only connectivity, smart multi-file tracking, **113 tools** (Local) / **101 tools** (Cloud) / **9 tools** (Remote read-only), Comments API, cross-MCP identity disambiguation, and MCP Apps.
+**Current Status:** v1.39.0 (Stable) - Production-ready. Latest: multi-file execution — `figma_execute_across_files` runs one script against several Desktop Bridge-connected files concurrently (four files x 2s of work in ~3s, not ~8s), and `figma_execute` takes an optional `fileKey` to target a single file without moving the active file or releasing target lock; targeting must be explicit (`fileKeys` or `allFiles: true`), so nothing fans out to files you did not name. From community PR #107 by @Wolfr. Ships with a relay fix: `handleResult()` in the plugin's ui.html rebuilt each response field by field and silently dropped `resultAnalysis` and `fileContext`, so the `resultAnalysis.warning` check that `figma_execute`'s own description tells callers to perform has never been possible (re-import `manifest.json` for those two fields; everything else works without it). On top of v1.38.2's connection-stability fix — the server's own orphan reaper was terminating healthy MCP servers because its liveness probe used an IPv4 literal while the server binds the IPv6 loopback, which turned every kill-safety gate into a rubber stamp; this was the cause of recurring "Server disconnected" errors across all MCP clients. Alongside v1.38.1's fix for the shared-library variable tools, which had silently reported zero collections since v1.29.0 and reported failed imports as successes. On top of v1.38.0's ongoing component changelogs in generated docs — `figma_generate_component_doc` takes an opt-in `history` parameter that pulls per-component **design history** from Figma version history (each version diffed and scoped to that component, so renames, added properties, and token bindings show up as rows) alongside **code history** from `git log` on the component's source files, rendered as a `## History` section with design, code, and release-note tables. Prefers labeled versions, falls back to auto-saves when a file has none, and is off by default so existing calls are unchanged (server-only, no plugin re-import). On top of v1.37.x's design-system health audit for every client — `figma_audit_design_system_report` runs the dashboard's deterministic six-category scoring engine and returns the report as data with per-finding remediation, live-first fileKey-verified data (source disclosed), chunked per-category drill-down, and a 5-minute cache (server-only, no plugin re-import). On top of v1.36.0's target lock for multi-file parallel work — — `figma_navigate` takes a `lock: true` flag that pins the active file so an AI agent can work in one file while you work in another without commands routing to the wrong file. On top of v1.35.0's Figma Slots write support — create, inspect, populate, and reset Slots (GA at Config 2026) via 5 new tools (`figma_create_slot`, `figma_get_slots`, `figma_append_to_slot`, `figma_reset_slot`, `figma_add_slot_property`), live-validated against the GA Plugin API and based on community PR #77. On top of v1.34.0's Bidirectional Token Sync v2 + DTCG 2025.10 — `figma_import_tokens` applies the complete diff plan (creates missing collections/variables, applies renames, writes real `VARIABLE_ALIAS` references, and deletes only under explicit `replace`), `figma_export_tokens` speaks the DTCG 2025.10 dialect on request (legacy default byte-identical), variable scopes/codeSyntax round-trip via `$extensions`, `figma_setup_design_tokens` accepts alias values via DTCG brace references, and `figma_create_component_set` builds a full variant set from an axes matrix in one call. On top of the v1.33.x line: version-handshake fix (re-import banner only fires when plugin files actually changed), security dependency sweep, and the v1.33.0 connection UX overhaul (honest status pill derived from live connection state, `/health` auto-discovery with self-healing reconnect) + a 33-fix full-codebase audit (lossless DTCG multi-mode round-trips, cross-collection alias resolution, branch-URL correctness across REST tools, cache-poisoning and CSWSH fixes, bridge-first screenshots). Built on WCAG-accurate accessibility auditing (line height below 1.5× is no longer mis-flagged as a failure; readability hints decoupled from conformance checks and scoped to multi-line text; code-side WCAG 1.4.12 check), a self-healing Desktop Bridge connection (zombie-process reaper + auto-reconnect watchdog — fixes the recurring "not connected until restart" bug), native variable binding on fills/strokes + typography control in the write tools, shared-library inspection (key-based component resolution + library variable read/import without Enterprise plan), 10-format token export pipeline (DTCG, CSS, Tailwind v4, Tailwind v3, SCSS, TS module, JSON flat/nested, Style Dictionary v3, Tokens Studio), bidirectional Figma↔code token sync, version history & time-series awareness, FigJam + Slides support, Cloud Write Relay, Design System Kit, WebSocket-only connectivity, smart multi-file tracking, **114 tools** (Local) / **101 tools** (Cloud) / **9 tools** (Remote read-only), Comments API, cross-MCP identity disambiguation, and MCP Apps.
 
 **Recent Releases:**
+- [x] **v1.39.0** - Multi-file execution. New `figma_execute_across_files` runs one script against several Desktop Bridge-connected files concurrently, with per-file error isolation and independent timeouts (verified live: four files × 2s of work in ~3.0s, all dispatches within 5ms — versus ~8s serialized). `figma_execute` gained an optional `fileKey` to target a single non-active file without moving the active file or releasing target lock. Targeting is deliberately explicit — `fileKeys` or `allFiles: true`, no fan-out-to-everything default — because this runs arbitrary code in files you may be actively editing, including one pinned by target lock. The transport was already concurrent (`sendCommand` has always taken a target file key, and every hop is request-id keyed); only the tool layer was missing. Community PR #107 by @Wolfr. Also fixes a Desktop Bridge relay bug that silently dropped `resultAnalysis` and `fileContext` from every `figma_execute` response since they were introduced — making the `resultAnalysis.warning` check the tool's own description tells callers to perform impossible — guarded now by a test that reads the real plugin files. **Re-import `manifest.json`** for those two fields; the rest works without it, and mixed plugin versions degrade cleanly. 52 suites / 1443 tests.
+- [x] **v1.38.2** - Connection stability: the orphan reaper was terminating healthy MCP servers, the cause of recurring "Server disconnected" errors across every MCP client (reproduced in both Claude Code and Claude Desktop; unrelated to the Desktop Bridge plugin). The reaper probes a sibling's `/health` before deciding it is dead, but requested `127.0.0.1` while the WebSocket server binds `localhost` — resolved to the IPv6 loopback on dual-stack macOS, with nothing on IPv4 — so the probe reported "nothing responding" for healthy servers and every kill-safety gate built on it became a rubber stamp, including the one written to spare siblings after the machine sleeps. Three supporting defects: port files written non-atomically (a reader landing mid-rewrite got a parse error that both cleanup paths treated as "corrupt, delete it", stranding a healthy server), an orphan path that terminated fileless port-holders without probing at all, and a heartbeat that gave up permanently once its own file went missing. Fixes: probe `localhost`, atomic temp+rename writes, never delete on a parse failure, health-probe before the orphan kill in both paths, and self-healing re-advertisement guarded by in-process port ownership. **Fully restart MCP clients after upgrading** — older running builds keep the broken probe and still terminate healthy siblings. Server-only, no plugin re-import. 1422 tests (7 new regressions, each verified to fail pre-fix).
+- [x] **v1.38.1** - Shared-library variable tools fixed. `figma_get_library_variables` returned `totalCollections: 0` for every file, on every plan, since it shipped in v1.29.0, and `figma_import_library_variable` reported failed imports as successes with `id: undefined`. Both read the Desktop Bridge's `{ success, result }` envelope as if it were the injected script's bare return value, so `Array.isArray()` was always false, the `__error` guard was dead code, and `.id` was always undefined. The failure presented as a *success* with a plausible hint attached ("subscribe a library via the Assets panel"), which is why it survived two months unreported. Both tools now unwrap through a shared helper that also maps a bridge-level `success: false` onto the error path, so a plugin timeout surfaces as a real error instead of being swallowed as "0 collections"; an import yielding no `id` is now an explicit error. All 26 `executeCodeViaUI` call sites audited — only these two were affected. Test mocks had encoded a wire contract that does not exist, which is why CI stayed green; they now reproduce the real envelope, plus six regression tests verified to fail against the pre-fix source. Reported by Isabella Minzly. Server-only — no plugin re-import needed.
 - [x] **v1.38.0** - Ongoing component changelogs in generated docs. `figma_generate_component_doc` gained an opt-in `history` parameter that produces a real changelog instead of only echoing hand-written `codeInfo.changelog` rows: `history.figma` walks Figma version history and diffs each consecutive pair scoped to the component (reusing the same engine as `figma_diff_versions`, so a rename, a newly added component property, or a token binding each become a row), while `history.git` runs `git log` over the component's source files auto-derived from `codeInfo.filePath` / `sourceFiles[]`. Labeled versions are preferred but auto-saves are used automatically when a file has none — verified against a mature system with 72 auto-saves and 0 labeled versions, where a labeled-only walk yields nothing. Detailed-mode bindings group by property (binding one token across a 24-variant set otherwise produced 44 near-identical bullets in a single table cell). Both sources default off, so existing callers get byte-identical output. No new tools; server-only, no plugin re-import.
 - [x] **v1.37.0** - Design-system health audit for every MCP client. New `figma_audit_design_system_report` runs the Design System Dashboard's deterministic scoring engine (naming, token architecture, component metadata, accessibility, consistency, coverage) and returns the scored report as data — no MCP Apps support or `ENABLE_MCP_APPS` needed (the previous registration gated everything, making the audit unreachable outside Claude Desktop). Component data is now live-first: a fileKey-verified per-page bridge crawl (30s/page, failures isolated per page) with REST published-library fallback, and the chosen source is disclosed in the report (`bridge-live` / `rest-published` / `none`) so stale-publish scores can't masquerade as live ones. Output is token-safe by design: bounded summary, per-category chunked drill-down, clamped full JSON, 5-minute raw-data cache. Every finding carries a remediation verdict — auto-fixable by this MCP's write tools, fixable after a design decision, or manual — with the exact tools named. Scoring accuracy pass: variant components no longer poison PascalCase/casing checks, Title Case accepted, component-set names count toward core-component coverage, `color/content/*` recognized in contrast pairing, state synonyms (`active`≈`pressed` etc.), and `.`/`_`-prefixed internals excluded. Server-only — no plugin re-import needed.
 - [x] **v1.36.0** - Target lock for multi-file parallel work. `figma_navigate` gains a `lock: true` flag that pins the active file — new connections, reconnects, and the user's own selection/page changes in other files no longer move the command target, so an agent can safely write to one file while the user works in another. Auto-releases when the pinned file disconnects or navigates away; `figma_list_open_files` reports a `targetLocked` flag for pre-write guards. Server-only — no plugin re-import needed.

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

@@ -56,7 +56,18 @@ export class CloudWebSocketConnector {
     `;
         return this.sendCommand('EXECUTE_CODE', { code, timeout: 30000 }, 32000);
     }
-    async executeCodeViaUI(code, timeoutMs = 5000) {
+    async executeCodeViaUI(code, timeoutMs = 5000, fileKey) {
+        // fileKey exists for IFigmaConnector parity but cannot be honored here —
+        // the cloud relay pairs with exactly one plugin instance, so there is no
+        // multi-file target to route between (matches getVariables* above).
+        // Reject rather than silently running against the paired file: a caller
+        // that asked for file B and got a successful write to file A has no way
+        // to tell from the response that it was misrouted.
+        if (fileKey) {
+            throw new Error('Per-file targeting (fileKey) is Local Mode only. Cloud Mode pairs with a single ' +
+                'plugin instance, so there is no second file to route to. Omit fileKey to run ' +
+                'against the paired file, or use Local Mode (NPX/Git) for multi-file work.');
+        }
         return this.sendCommand('EXECUTE_CODE', { code, timeout: timeoutMs }, timeoutMs + 2000);
     }
     // ============================================================================

package/dist/cloudflare/core/design-code-tools.js

@@ -1476,11 +1476,13 @@ latestDesignVersion) {
     if (latestDesignVersion) {
         // Quote the label — it's user-authored and may contain YAML-significant
         // characters (a colon in "v2: buttons" would otherwise break parsing).
+        // Unlabeled auto-saves fall back to the date rather than the raw 19-digit
+        // version ID, which carries no meaning for a docs reader.
+        const date = latestDesignVersion.created_at?.split("T")[0];
         const label = latestDesignVersion.label
             ? `"${latestDesignVersion.label.replace(/"/g, '\\"')}"`
-            : latestDesignVersion.version_id;
+            : date || latestDesignVersion.version_id;
         lines.push(`figmaVersion: ${label}`);
-        const date = latestDesignVersion.created_at?.split("T")[0];
         if (date)
             lines.push(`figmaVersionDate: ${date}`);
     }
@@ -2919,6 +2921,8 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
                                     entries: designHistory.entries.length,
                                     versionsScanned: designHistory._meta.versions_scanned,
                                     apiCalls: designHistory._meta.api_calls,
+                                    usedAutosaveFallback: designHistory._meta.used_autosave_fallback === true,
+                                    latestVersionId: latestDesignVersion?.version_id ?? null,
                                     notes: designHistory.notes,
                                 }
                                 : null,

package/dist/cloudflare/core/history/component-history.js

@@ -73,20 +73,37 @@ export async function buildDesignHistory(api, fileKey, nodeIds, options = {}) {
         return result;
     }
     // N rows needs N+1 snapshots: each row is a diff between adjacent versions.
-    const listed = await listVersions(api, fileKey, {
+    let listed = await listVersions(api, fileKey, {
         limit: versionsWanted + 1,
         includeAutosaves,
     });
     result._meta.api_calls += listed.apiCalls;
-    result._meta.versions_scanned = listed.versions.length;
     if (listed.error) {
+        result._meta.versions_scanned = listed.versions.length;
         result.notes.push(listed.error);
         return result;
     }
+    // Labeled versions are better changelog material when a team curates them,
+    // but plenty of real design-system files have none at all (verified: a mature
+    // file with 72 auto-saves and 0 labeled versions). Rather than silently
+    // emitting nothing there, fall back to auto-saves and say so. Autosave noise
+    // is largely absorbed downstream anyway — a version only becomes a row if it
+    // actually changed the scoped component.
+    if (!includeAutosaves && listed.versions.length < 2) {
+        const fallback = await listVersions(api, fileKey, {
+            limit: versionsWanted + 1,
+            includeAutosaves: true,
+        });
+        result._meta.api_calls += fallback.apiCalls;
+        if (!fallback.error && fallback.versions.length >= 2) {
+            listed = fallback;
+            result._meta.used_autosave_fallback = true;
+            result.notes.push("This file has no labeled versions, so history was built from Figma auto-saves. Name versions in Figma (right-click a version → Add label) for a more curated changelog.");
+        }
+    }
+    result._meta.versions_scanned = listed.versions.length;
     if (listed.versions.length < 2) {
-        result.notes.push(includeAutosaves
-            ? "Not enough version history to build a changelog (need at least 2 saved versions)."
-            : "Not enough labeled version history to build a changelog (need at least 2 named versions). Figma auto-saves are excluded by default — pass includeAutosaves to use them.");
+        result.notes.push("Not enough version history to build a changelog (need at least 2 saved versions).");
         return result;
     }
     // listVersions returns newest-first. Row i describes what changed when

package/dist/cloudflare/core/history/history-formatter.js

@@ -42,7 +42,10 @@ function appendDesignHistory(lines, design) {
         lines.push("| Version | Date | Author | Changes |");
         lines.push("|---------|------|--------|---------|");
         for (const e of design.entries) {
-            const version = e.label ? escapeCell(e.label) : `\`${e.version_id}\` _(autosave)_`;
+            // Auto-saves have no label and a 19-digit numeric ID that means nothing
+            // to a reader — the Date column already identifies the row. The raw ID
+            // stays available programmatically via historySummary / the entry object.
+            const version = e.label ? escapeCell(e.label) : "_(auto-save)_";
             const date = formatDate(e.created_at);
             const author = e.author ? escapeCell(e.author) : "—";
             const changes = e.changes.length > 0

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

@@ -317,6 +317,33 @@ export function registerLibraryTools(server, getFigmaAPI) {
 function safeKey(value) {
     return JSON.stringify(value);
 }
+/**
+ * Unwrap the Desktop Bridge envelope around an executeCodeViaUI() result.
+ *
+ * The bridge resolves to `{ success, result }` (built by handleResult() in
+ * figma-desktop-bridge/ui.html) — NEVER the bare value the injected script
+ * returned. Reading the envelope as if it were the script's own return value
+ * silently yields the wrong type: `Array.isArray(envelope)` is always false,
+ * and a `{ __error }` sentinel lands at `.result.__error`, not `.__error`.
+ * That turns a hard failure into a confident-looking empty success, which is
+ * worse than a crash — see the regression tests in tests/library-tools.test.ts.
+ *
+ * Returns the script's value, or `{ __error }` when the bridge itself reported
+ * failure so callers can route both failure modes through one guard. The
+ * `?? raw` fallback keeps this tolerant of a bare value, matching the
+ * defensive `execResult.result ?? execResult` precedent in tokens-tools.ts.
+ */
+function unwrapBridgeResult(raw) {
+    if (raw && typeof raw === "object" && raw.success === false) {
+        return {
+            __error: raw.error || "Desktop Bridge reported a failure with no error message.",
+        };
+    }
+    if (raw && typeof raw === "object" && "result" in raw) {
+        return raw.result ?? raw;
+    }
+    return raw;
+}
 export function registerLibraryVariableTools(server, getDesktopConnector) {
     // --------------------------------------------------------------------
     // figma_get_library_variables — list available variables from
@@ -393,15 +420,16 @@ export function registerLibraryVariableTools(server, getDesktopConnector) {
 					return out;
 				`;
             const raw = await connector.executeCodeViaUI(script, 30000);
+            const payload = unwrapBridgeResult(raw);
             // Detect the wrapped-error sentinel
-            if (raw && typeof raw === "object" && raw.__error) {
+            if (payload && typeof payload === "object" && payload.__error) {
                 return {
                     content: [
                         {
                             type: "text",
                             text: JSON.stringify({
                                 _mcp: "figma-console-mcp",
-                                error: raw.__error,
+                                error: payload.__error,
                                 hint: "Plugin sandbox could not access the team library API. Ensure Figma Desktop is recent and the Desktop Bridge is connected.",
                             }),
                         },
@@ -409,7 +437,7 @@ export function registerLibraryVariableTools(server, getDesktopConnector) {
                     isError: true,
                 };
             }
-            let collections = Array.isArray(raw) ? raw : [];
+            let collections = Array.isArray(payload) ? payload : [];
             // Apply server-side filters (cheaper to filter here than in plugin)
             if (libraryName) {
                 const needle = libraryName.toLowerCase();
@@ -520,8 +548,9 @@ After import, the variable becomes locally addressable by its returned 'id' and
 					}
 				`;
             const raw = await connector.executeCodeViaUI(script, 20000);
-            if (raw && typeof raw === "object" && raw.__error) {
-                const errMsg = raw.__error;
+            const imported = unwrapBridgeResult(raw);
+            if (imported && typeof imported === "object" && imported.__error) {
+                const errMsg = imported.__error;
                 let hint = "Verify the variableKey was returned by figma_get_library_variables and that the source library is subscribed by the current file.";
                 if (/not subscribed|not enabled|access/i.test(errMsg)) {
                     hint =
@@ -542,15 +571,35 @@ After import, the variable becomes locally addressable by its returned 'id' and
                     isError: true,
                 };
             }
+            // An import with no id is a failure however it got here — never
+            // report it as a success with `id: undefined`, which is
+            // indistinguishable from a real import to a scripted caller.
+            if (!imported || typeof imported !== "object" || !imported.id) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                _mcp: "figma-console-mcp",
+                                error: "Import returned no variable id — the variable was not imported.",
+                                hint: "Verify the variableKey came from figma_get_library_variables and that the source library is subscribed by the current file.",
+                                variableKey,
+                                received: imported,
+                            }),
+                        },
+                    ],
+                    isError: true,
+                };
+            }
             return {
                 content: [
                     {
                         type: "text",
                         text: JSON.stringify({
                             _mcp: "figma-console-mcp",
-                            imported: raw,
+                            imported,
                             usage: {
-                                bind: `Use the imported variable's id ('${raw?.id}') with figma_set_fills, figma_update_variable, or any other variable-binding tool to reference this token from nodes in the current file.`,
+                                bind: `Use the imported variable's id ('${imported.id}') with figma_set_fills, figma_update_variable, or any other variable-binding tool to reference this token from nodes in the current file.`,
                                 note: "Variables imported from a library remain linked to their source — updates published from the library will propagate here automatically.",
                             },
                         }),

package/dist/cloudflare/core/multi-file-tools.js

@@ -0,0 +1,161 @@
+import { z } from "zod";
+/**
+ * Register tools that operate across every Figma file connected via the
+ * Desktop Bridge plugin at once, rather than only the single active file.
+ * Local mode only — cloud/relay mode pairs with exactly one plugin instance.
+ */
+export function registerMultiFileTools(server, getWsServer, getDesktopConnector) {
+    server.tool("figma_execute_across_files", "Run the same JavaScript against multiple Figma files connected via the Desktop Bridge plugin, IN PARALLEL, without touching the active file or target lock. Built for cross-file consistency work — e.g. running the same structural check or fix against every file in a multi-file design system and diffing the results — instead of switching the active file and running figma_execute once per file in sequence. Each file's code runs in that file's own plugin context (same 'figma' global as figma_execute). You must say which files to target: pass fileKeys (read them from figma_list_open_files first — strongly preferred for anything that writes), or pass allFiles: true to hit every connected file. Requires Desktop Bridge plugin open in each target file. Local Mode only.", {
+        code: z
+            .string()
+            .describe("JavaScript code to execute in each targeted file. Has access to the 'figma' global object, same as figma_execute. Example: 'return { pageCount: figma.root.children.length };'"),
+        fileKeys: z
+            .array(z.string())
+            .optional()
+            .describe("Which connected files to target, by fileKey. Get fileKeys from figma_list_open_files. Required unless allFiles is true."),
+        allFiles: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Run against EVERY currently connected file. Opt-in on purpose: this executes the code in files the user may be actively working in, including any file pinned by target lock. Prefer naming fileKeys explicitly for anything that writes."),
+        timeout: z
+            .number()
+            .optional()
+            .default(10000)
+            .describe("Per-file execution timeout in milliseconds (default: 10000, max: 30000). Applies independently to each file — one slow/unresponsive file does not delay the others."),
+    }, async ({ code, fileKeys, allFiles, timeout }) => {
+        try {
+            const wsServer = getWsServer();
+            if (!wsServer?.isClientConnected()) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "No files connected. Open the Desktop Bridge plugin in Figma to connect files.",
+                                results: {},
+                            }),
+                        }],
+                    isError: true,
+                };
+            }
+            const connectedFiles = wsServer.getConnectedFiles();
+            const cappedTimeout = Math.min(timeout, 30000);
+            // Fanning out to every connected file has to be asked for. This
+            // runs arbitrary code in files the user may be actively editing,
+            // including one pinned by target lock — the exact misrouting that
+            // target lock exists to prevent. "All" is a decision, not a default.
+            const hasExplicitTargets = Boolean(fileKeys && fileKeys.length > 0);
+            if (!hasExplicitTargets && !allFiles) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "No target files specified. Pass fileKeys to name the files to run against, or allFiles: true to run against every connected file.",
+                                hint: "Call figma_list_open_files to see connected fileKeys. Naming files explicitly is strongly preferred for code that writes.",
+                                connectedFiles: connectedFiles.map((f) => ({
+                                    fileKey: f.fileKey,
+                                    fileName: f.fileName,
+                                    isActive: f.isActive,
+                                })),
+                            }),
+                        }],
+                    isError: true,
+                };
+            }
+            // A client is only ever registered under a real fileKey (see
+            // handleFileInfo), so this filter is belt-and-braces — but an
+            // entry without one must never fall through to sendCommand's
+            // active-file default, which would silently run the code against
+            // the active file instead and report it as a success.
+            const targetable = connectedFiles.filter((f) => Boolean(f.fileKey));
+            const unidentifiedFiles = connectedFiles
+                .filter((f) => !f.fileKey)
+                .map((f) => f.fileName);
+            let targets = targetable;
+            let missingFileKeys = [];
+            if (hasExplicitTargets) {
+                const connectedKeySet = new Set(targetable.map((f) => f.fileKey));
+                missingFileKeys = fileKeys.filter((k) => !connectedKeySet.has(k));
+                targets = targetable.filter((f) => fileKeys.includes(f.fileKey));
+            }
+            if (targets.length === 0) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: JSON.stringify({
+                                error: "No matching connected files to target.",
+                                requestedFileKeys: fileKeys,
+                                connectedFileKeys: connectedFiles.map((f) => f.fileKey),
+                            }),
+                        }],
+                    isError: true,
+                };
+            }
+            const connector = await getDesktopConnector();
+            const outcomes = await Promise.allSettled(targets.map((file) => connector.executeCodeViaUI(code, cappedTimeout, file.fileKey)));
+            const results = {};
+            let succeeded = 0;
+            let failed = 0;
+            outcomes.forEach((outcome, i) => {
+                const file = targets[i];
+                const key = file.fileKey;
+                if (outcome.status === "fulfilled") {
+                    const result = outcome.value;
+                    const ok = result?.success !== false;
+                    if (ok)
+                        succeeded++;
+                    else
+                        failed++;
+                    results[key] = {
+                        fileName: file.fileName,
+                        success: result?.success,
+                        result: result?.result,
+                        error: result?.error,
+                        // Reported by the plugin itself, so the caller can confirm
+                        // each result came from the file it was addressed to.
+                        fileContext: result?.fileContext,
+                    };
+                }
+                else {
+                    failed++;
+                    results[key] = {
+                        fileName: file.fileName,
+                        success: false,
+                        error: outcome.reason instanceof Error
+                            ? outcome.reason.message
+                            : String(outcome.reason),
+                    };
+                }
+            });
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            results,
+                            totalTargeted: targets.length,
+                            totalSucceeded: succeeded,
+                            totalFailed: failed,
+                            missingFileKeys: missingFileKeys.length > 0 ? missingFileKeys : undefined,
+                            // Connected but unaddressable (no fileKey reported) — skipped
+                            // rather than silently redirected to the active file.
+                            skippedUnidentifiedFiles: unidentifiedFiles.length > 0 ? unidentifiedFiles : undefined,
+                            timestamp: Date.now(),
+                        }),
+                    }],
+                isError: failed > 0 && succeeded === 0,
+            };
+        }
+        catch (error) {
+            return {
+                content: [{
+                        type: "text",
+                        text: JSON.stringify({
+                            error: error instanceof Error ? error.message : String(error),
+                            message: "Failed to execute across files",
+                        }),
+                    }],
+                isError: true,
+            };
+        }
+    });
+}