figma-console-mcp 1.40.1 → 1.40.2

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**.
 
-> **🆕 Design System Extraction (v1.40.0, patched v1.40.1):** Turn a production codebase into a design system. Seven new `figma_ds_*` tools (Local Mode) scan one or more app codebases — framework, styling-method, and vendor-layer detection; a usage-ranked component inventory classified vendored / wrapped / pure-vendor / bespoke; variant inference from real call sites; duplicate detection; and an architecture pass that separates a UI kit from a design system (`FollowButton` is really a `Button` — and here are the missing generic primitives). Then they mine the app's de-facto styling into DTCG tokens with per-token provenance — multi-mode CSS custom properties (`.dark`, `[data-theme]`, and friends), SCSS variables, Tailwind config values, shadcn HSL triples, Tailwind utility-class frequency mining valued from the app's own theme, and frequency-promoted raw values — scaffold the design-system package with token/typography/iconography showcase pages, wire a fresh Storybook workshop to the app's real theme layers and fonts, deep-extract components for porting with CSF3 story scaffolds, gate the result behind deterministic fidelity evals, and persist porting progress across sessions. The extracted `tokens/tokens.json` imports straight into Figma variables via `figma_import_tokens` — a full code → design system → Figma round-trip. Also fixes the token formatters quoting CSS functional expressions like `cubic-bezier(...)` (a quoted easing silently kills transitions — affects `figma_export_tokens` output too). Server-only — no plugin re-import needed. [See what's new →](CHANGELOG.md#1400---2026-08-16)
+> **🆕 Design System Extraction (v1.40.0, patched v1.40.2):** Turn a production codebase into a design system. Seven new `figma_ds_*` tools (Local Mode) scan one or more app codebases — framework, styling-method, and vendor-layer detection; a usage-ranked component inventory classified vendored / wrapped / pure-vendor / bespoke; variant inference from real call sites; duplicate detection; and an architecture pass that separates a UI kit from a design system (`FollowButton` is really a `Button` — and here are the missing generic primitives). Then they mine the app's de-facto styling into DTCG tokens with per-token provenance — multi-mode CSS custom properties (`.dark`, `[data-theme]`, and friends), SCSS variables, Tailwind config values, shadcn HSL triples, Tailwind utility-class frequency mining valued from the app's own theme, and frequency-promoted raw values — scaffold the design-system package with token/typography/iconography showcase pages, wire a fresh Storybook workshop to the app's real theme layers and fonts, deep-extract components for porting with CSF3 story scaffolds, gate the result behind deterministic fidelity evals, and persist porting progress across sessions. The extracted `tokens/tokens.json` imports straight into Figma variables via `figma_import_tokens` — a full code → design system → Figma round-trip. Also fixes the token formatters quoting CSS functional expressions like `cubic-bezier(...)` (a quoted easing silently kills transitions — affects `figma_export_tokens` output too). Server-only — no plugin re-import needed. [See what's new →](CHANGELOG.md#1400---2026-08-16)
 
 ## What is this?
 
@@ -840,9 +840,10 @@ The architecture supports adding new apps with minimal boilerplate — each app
 
 ## 🛤️ Roadmap
 
-**Current Status:** v1.40.1 (Stable) - Production-ready. Latest: accuracy fixes for generated component docs across variants — a descendant's fill (typically an icon's) could be documented as a variant's Background, Color Token headings kept only a property literally named `Variant`, spacing was read from the first variant alone, and icons were only detected by layer name — plus `figma_export_tokens` accepting a file path as `outputPath` instead of failing with a raw `EEXIST` or silently creating a directory (server-only, no plugin re-import). On top of v1.40.0's design system extraction from production codebases — seven Local-Mode `figma_ds_*` tools that scan one or more apps (framework/styling/vendor detection, usage-ranked component inventory classified vendored/wrapped/pure-vendor/bespoke, variant inference from real call sites, duplicate detection, and an architecture pass separating UI-kit specializations from the missing generic primitives), mine the de-facto styling into DTCG tokens with per-token provenance (multi-mode CSS custom properties, SCSS, Tailwind config, shadcn HSL triples, utility-class frequency mining valued from the app's own theme), scaffold the design-system package with showcase docs pages, wire a fresh Storybook workshop to the app's real theme layers and fonts, deep-extract components for porting with CSF3 story scaffolds, verify with deterministic fidelity evals, and persist porting progress across sessions — the extracted tokens import straight into Figma variables via `figma_import_tokens`. On top of v1.39.1's fix for a plugin-update banner that could never be cleared — an older server instance nagging a newer plugin to re-import, which only ever installs the same or a newer plugin. On top of v1.39.0's 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, **121 tools** (Local) / **101 tools** (Cloud) / **9 tools** (Remote read-only), Comments API, cross-MCP identity disambiguation, and MCP Apps.
+**Current Status:** v1.40.2 (Stable) - Production-ready. Latest: a data-loss fix for `figma_export_tokens` — with a different file active in Figma than intended, an export could replace a real token file with an empty one (or with another file's tokens) and report success; exports now refuse to write when a requested collection is missing, when the export is empty, when the target was generated from a different Figma file, or when overwriting would destroy tokens the export doesn't manage, and `strategy: "merge"` — documented as preserving code-only tokens but never implemented — is now a genuinely safe default (server-only, no plugin re-import). On top of v1.40.1's accuracy fixes for generated component docs across variants — a descendant's fill (typically an icon's) could be documented as a variant's Background, Color Token headings kept only a property literally named `Variant`, spacing was read from the first variant alone, and icons were only detected by layer name — plus `figma_export_tokens` accepting a file path as `outputPath` instead of failing with a raw `EEXIST` or silently creating a directory (server-only, no plugin re-import). On top of v1.40.0's design system extraction from production codebases — seven Local-Mode `figma_ds_*` tools that scan one or more apps (framework/styling/vendor detection, usage-ranked component inventory classified vendored/wrapped/pure-vendor/bespoke, variant inference from real call sites, duplicate detection, and an architecture pass separating UI-kit specializations from the missing generic primitives), mine the de-facto styling into DTCG tokens with per-token provenance (multi-mode CSS custom properties, SCSS, Tailwind config, shadcn HSL triples, utility-class frequency mining valued from the app's own theme), scaffold the design-system package with showcase docs pages, wire a fresh Storybook workshop to the app's real theme layers and fonts, deep-extract components for porting with CSF3 story scaffolds, verify with deterministic fidelity evals, and persist porting progress across sessions — the extracted tokens import straight into Figma variables via `figma_import_tokens`. On top of v1.39.1's fix for a plugin-update banner that could never be cleared — an older server instance nagging a newer plugin to re-import, which only ever installs the same or a newer plugin. On top of v1.39.0's 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, **121 tools** (Local) / **101 tools** (Cloud) / **9 tools** (Remote read-only), Comments API, cross-MCP identity disambiguation, and MCP Apps.
 
 **Recent Releases:**
+- [x] **v1.40.2** - Token export data-loss fix. `figma_export_tokens` reads from whichever file is active in Figma Desktop; with the wrong one focused it could overwrite a real token file with an empty document — or, for CSS/SCSS/Tailwind/TS outputs, with another file's tokens — and report `success: true`. Exports now refuse (writing nothing) when a requested collection isn't in the file that was read, when the export is empty, when the target was generated from a different Figma file (generated files now record their source), when a DTCG target can't be parsed or would be replaced by a different kind of output, or when overwriting would destroy hand-added tokens or another collection's tokens. `strategy: "merge"` had been documented as preserving code-only tokens but was never implemented; it is now the safe default and `replace` is the explicit override. Every response reports the `source` Figma file. Server-only. Reported by Isabella Minzly; two further loss paths found in code review.
 - [x] **v1.40.1** - Component-doc variant accuracy + token export file paths. `figma_generate_component_doc`: Background now comes only from the variant's own fills (a transparent outline/ghost variant no longer borrows its icon's color), Color Token headings name every variant property under any property names, Spacing Tokens are compared across all variants (`varies by **Size**: …`, with a Spacing Inconsistencies list for properties tokenized on some variants and hardcoded on others), and icons resolve from the main component and `INSTANCE_SWAP` slots rather than a layer name containing "icon". `figma_export_tokens`: an `outputPath` that is an existing file or ends in a token-file extension is written as that exact file; multi-file exports into a file path are rejected before anything is written. `figma_search_components` no longer reports a failed component load as a successful empty search. Server-only. Reported by Robin Di Capua and Isabella Minzly.
 - [x] **v1.40.0** - Design System Extraction. Seven new Local-Mode-only tools that turn a production codebase into a design system, plus the supporting extraction engine. `figma_ds_analyze` scans one or more app codebases: framework/styling/vendor-layer detection (React/Next/Angular/Web Components; Tailwind v3/v4, CSS Modules, SCSS, Emotion, styled-components; shadcn/ui, Radix, MUI, Chakra…), a usage-ranked component inventory classified vendored/wrapped/pure-vendor/bespoke with prop contracts, variant inference from real call sites, duplicate detection, iconography + typography capture, and an architecture classification separating a UI kit from a design system (atomic levels, specializations like FollowButton → Button, missing generic primitives). `figma_ds_extract_tokens` mines de-facto styling into DTCG tokens — multi-mode CSS custom properties across `.dark`/`[data-theme]` conventions, SCSS variables, Tailwind config values, shadcn HSL triples, Tailwind utility-class frequency mining valued from the app's own theme, frequency-promoted raw values — with per-token provenance in `$extensions`, importable straight into Figma variables via `figma_import_tokens`. `figma_ds_scaffold` generates the package (token files via the shared formatters, token/typography/iconography showcase pages); `figma_ds_setup_storybook` wires a fresh Storybook workshop to the app's real theme layers and fonts; `figma_ds_extract_component` produces per-component porting manifests with CSF3 story scaffolds; `figma_ds_verify` gates the result with deterministic fidelity evals plus Figma round-trip readiness; `figma_ds_status` persists porting progress across sessions. Also fixes the CSS/SCSS/Tailwind v4 formatters quoting CSS functional expressions (a quoted `cubic-bezier(...)` silently kills transitions — affects `figma_export_tokens` too). Server-only, no plugin re-import.
 - [x] **v1.39.1** - Plugin update banner could never be cleared. `computePluginUpdateAvailable()` was a bare inequality with no direction check, so a server whose bundled plugin copy was OLDER than the connected plugin still told the user to re-import — which only ever installs the same or a newer plugin. Not an edge case: the 9223–9232 port range keeps several server instances alive, `BUNDLED_PLUGIN_VERSION` is parsed once at module load, and every server left running from before an upgrade nags a correctly-updated plugin. Reproduced live with four leftover v1.38.2 servers against a freshly re-imported 1.39.0 plugin. Now flags only when the bundled copy is genuinely newer. Server-only, no plugin re-import. 1452 tests.

package/dist/cloudflare/core/tokens/schemas.js

@@ -71,7 +71,7 @@ export const ExportTokensInputSchema = z.object({
         .string()
         .optional()
         .describe("Explicit path to a tokens.config.json file. When omitted, the tool walks up from cwd looking for one — typical case is zero-arg."),
-    strategy: SyncStrategySchema.optional().describe("How to handle existing output files. 'merge' (default) diffs against current contents and writes only changed tokens, preserving code-only additions. 'replace' wipes and rewrites. 'dry-run' computes the diff and reports what would change without writing."),
+    strategy: SyncStrategySchema.optional().describe("How to handle existing output files. Export always replaces a target file's contents with the current Figma state — it does not merge token-by-token. 'merge' (default) is the SAFE mode: it refuses to write, leaving the file untouched, if overwriting an existing DTCG file would delete tokens the export does not manage (hand-added tokens, or tokens from collections not included in this export). 'replace' overwrites unconditionally. 'dry-run' reports what would be written without writing."),
     prefix: z
         .string()
         .optional()

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

@@ -35,7 +35,7 @@ const logger = createChildLogger({ component: "tokens-tools" });
  * on every exported token document. Kept in sync with package.json by
  * scripts/release.sh — see step 3 of the release flow.
  */
-const MCP_VERSION = "1.40.1";
+const MCP_VERSION = "1.40.2";
 const EXPORT_TOOL_DESCRIPTION = `Export Figma variables to design token files in your codebase. Bidirectional with figma_import_tokens — together they replace Style Dictionary and Tokens Studio's export pipeline for the popular styling methods.
 
 FULLY-IMPLEMENTED OUTPUT FORMATS:
@@ -52,7 +52,7 @@ FULLY-IMPLEMENTED OUTPUT FORMATS:
 
 ZERO-ARG USAGE: With a tokens.config.json at your project root, just call the tool with no args — it picks up source dir, output formats, modes, prefix, etc. from config. See the response's \`suggestedScaffold\` payload when no config is detected — present it to the user, write the scaffold via your file tools, then call again.
 
-MERGE STRATEGY: Default \`strategy: "merge"\` only writes tokens that actually changed in Figma since the last sync. Use \`dry-run\` to preview what would change. Use \`replace\` to wipe and rewrite (rare; for resetting drift).
+WRITE SAFETY: Export REPLACES the contents of each target file with the current Figma state — it does not merge into it. Under the default \`strategy: "merge"\` the tool refuses to write (and changes nothing) when overwriting an existing DTCG file would delete tokens it does not manage: tokens added by hand, or tokens from collections outside this export. It also refuses when a requested collectionId is not in the file it read, or when the export is empty — both usually mean a different file is active in Figma than you intended. Variables deleted in Figma are removed from the file as normal. Use \`dry-run\` to preview, \`replace\` to overwrite unconditionally. Generated files record the Figma file they came from (a \`Source: Figma file <key>\` header line; \`figmaFileKey\` in DTCG), and the default strategy also refuses to overwrite a file that was generated from a DIFFERENT Figma file. Plain-JSON formats (json-flat, json-nested, style-dictionary-v3, tokens-studio) cannot carry that record — pin \`figmaFile\` in tokens.config.json for a hard guarantee. Every response includes \`source\` (the Figma file name/key the data was read from) — check it.
 
 DTCG DIALECT (\`dtcgDialect\`, applies to dtcg/json-flat/json-nested outputs): legacy (default): hex-string colors, maximum compatibility (Style Dictionary v4, Tokens Studio). 2025: DTCG 2025.10 object colors/dimensions (Style Dictionary v5+). figma_import_tokens accepts BOTH dialects regardless of this setting.
 
@@ -82,7 +82,7 @@ export function registerExportTokensTool(server, getDesktopConnector, opts = {})
                         text: JSON.stringify({
                             error: err instanceof Error ? err.message : String(err),
                             // Output-location errors already say what to do; the format hint would only mislead.
-                            ...(/outputPath|Cannot write/.test(err instanceof Error ? err.message : String(err))
+                            ...(/outputPath|Cannot write|[Nn]othing was written/.test(err instanceof Error ? err.message : String(err))
                                 ? {}
                                 : {
                                     hint: "If this is a TokenFormatNotImplementedError for a non-DTCG/non-CSS format, export to 'dtcg' or 'css-vars' instead — those are the fully-implemented formats. The canonical DTCG JSON can be consumed by Style Dictionary v4 or any other DTCG-aware tooling.",
@@ -171,9 +171,27 @@ async function handleExport(args, getDesktopConnector, opts) {
     }
     // 3. Normalize to the converter's expected shape.
     const payload = normalizeFigmaPayload(variableData);
+    const sourceFileKey = (typeof variableData.fileKey === "string" && variableData.fileKey) ||
+        fileKey ||
+        null;
+    // 3b. Identify the Figma file the data ACTUALLY came from. Without a
+    //     tokens.config.json `figmaFile`, the bridge reads whichever file is
+    //     active in Figma Desktop — which may not be the one the caller means.
+    //     (With `figmaFile` pinned, sendCommand routes to that file's plugin
+    //     connection and rejects if it isn't connected, so no check is needed.)
+    const source = {
+        fileKey: sourceFileKey,
+        fileName: (sourceFileKey && opts.resolveFileName?.(sourceFileKey)) || null,
+    };
+    // 3c. Every requested collection must exist in that file. A partial or
+    //     empty match would otherwise be written over the target as if it were
+    //     the full export.
+    assertRequestedCollectionsFound(args.collectionIds, payload.collections, source);
     // 4. Convert to canonical TokenDocument.
     const { document, warnings } = convertFigmaVariablesToDocument(payload, {
-        figmaFileKey: fileKey,
+        // The file the data was ACTUALLY read from — stamped into DTCG output so a
+        // later export from a different Figma file can be recognized and refused.
+        figmaFileKey: sourceFileKey ?? undefined,
         collectionIds: args.collectionIds,
         modes: args.modes,
         stripPrefix: args.prefix,
@@ -207,7 +225,12 @@ async function handleExport(args, getDesktopConnector, opts) {
                 projectRoot: loaded?.projectRoot,
             });
             for (const file of result.files) {
-                allFiles.push({ format: target.format, ...file });
+                allFiles.push({
+                    format: target.format,
+                    ...file,
+                    content: stampSourceFile(file.content, sourceFileKey),
+                    splitByCollection: !!(args.splitByCollection ?? target.splitByCollection),
+                });
             }
             allWarnings.push(...result.warnings);
         }
@@ -228,6 +251,76 @@ async function handleExport(args, getDesktopConnector, opts) {
     const writtenPaths = [];
     const plan = planExportWrites(allFiles, args.outputPath, loaded);
     allWarnings.push(...plan.warnings);
+    // Validate EVERY planned write before performing ANY of them — a refused
+    // export must leave the disk exactly as it found it.
+    const totalTokens = document.sets.reduce((n, s) => n + s.tokens.length, 0);
+    if (totalTokens === 0) {
+        if (plan.writes.length > 0) {
+            throw new Error(`[figma-console-mcp] The export contains 0 tokens (read from ${describeSource(source)}), so nothing was written — writing it would have emptied ${plan.writes.length === 1 ? `"${plan.writes[0].fullPath}"` : `${plan.writes.length} files`}. Check that the right file is active in Figma and that the collectionIds/modes filters match it.`);
+        }
+        allWarnings.push(`The export contains 0 tokens (read from ${describeSource(source)}). Check that the right file is active in Figma and that the collectionIds/modes filters match it.`);
+    }
+    if (args.strategy !== "replace") {
+        const allExportedCollectionIds = document.sets
+            .map((s) => s.meta?.figmaCollectionId)
+            .filter((id) => typeof id === "string");
+        // Exported collections that ended up with no tokens appear in no file's
+        // content — yet a token stamped with one that vanishes was still
+        // legitimately deleted in Figma.
+        const emptyExportedCollectionIds = document.sets
+            .filter((s) => s.tokens.length === 0)
+            .map((s) => s.meta?.figmaCollectionId)
+            .filter((id) => typeof id === "string");
+        for (const write of plan.writes) {
+            if (!existsSync(write.fullPath))
+                continue;
+            let existing;
+            try {
+                existing = readFileSync(write.fullPath, "utf-8");
+            }
+            catch (err) {
+                // Unreadable target: we cannot prove the overwrite is safe, so don't.
+                throw new Error(`[figma-console-mcp] Nothing was written. "${write.fullPath}" exists but could not be read to check what overwriting it would destroy (${err instanceof Error ? err.message : String(err)}). Fix the file's permissions, or pass strategy: "replace" to overwrite it unconditionally.`);
+            }
+            // (a) Any format: was this file generated from a DIFFERENT Figma file?
+            const stampedKey = readSourceFileStamp(existing);
+            if (stampedKey && !sourceFileKey) {
+                // The target records its source, but this run can't say where ITS data
+                // came from — we cannot prove they match, so don't overwrite.
+                throw new Error(`[figma-console-mcp] Nothing was written. "${write.fullPath}" was generated from Figma file ${stampedKey}, but the Desktop Bridge plugin did not report which file this export read from, so it can't be confirmed to be the same one. Re-import the plugin manifest in Figma (the bundled manifest enables file-key reporting) and retry, or pass strategy: "replace" to overwrite anyway.`);
+            }
+            if (stampedKey && sourceFileKey && stampedKey !== sourceFileKey) {
+                throw new Error(`[figma-console-mcp] Nothing was written. "${write.fullPath}" was generated from Figma file ${stampedKey}, but this export read from ${describeSource(source)} — most likely a different file/tab is active in Figma than you intended. Switch to the right file (or use figma_navigate) and retry. If you really mean to re-source this file, pass strategy: "replace".`);
+            }
+            // (b) DTCG: would the overwrite destroy tokens this export doesn't manage?
+            //     A DTCG target we cannot parse (merge-conflict markers, a truncated
+            //     write) can't be checked — refuse rather than bulldoze it.
+            if (write.format === "dtcg" &&
+                stripBom(existing).trim() !== "" &&
+                !isParsableJson(existing)) {
+                throw new Error(`[figma-console-mcp] Nothing was written. "${write.fullPath}" exists but is not valid JSON (unresolved merge conflict? partial write?), so what overwriting it would destroy can't be checked. Fix the file, or pass strategy: "replace" to overwrite it unconditionally.`);
+            }
+            //     A DTCG token file must never be replaced by a DIFFERENT kind of
+            //     output (css-vars aimed at typography.tokens.json): the new side
+            //     isn't JSON, so the token comparison below would see nothing lost.
+            if (dtcgTokenCount(existing) > 0 && !isParsableJson(write.content)) {
+                throw new Error(`[figma-console-mcp] Nothing was written. "${write.fullPath}" is a DTCG token file (${dtcgTokenCount(existing)} tokens), and this export would replace it with ${write.format} output — every token in it would be lost. Point outputPath at a ${write.format} file instead, or pass strategy: "replace" if you really mean to convert this file.`);
+            }
+            //     Which collections does THIS file speak for? With splitByCollection
+            //     a file holds one collection, so only that one (a token from another
+            //     collection pasted in is NOT ours to drop). Otherwise every exported
+            //     collection feeds the file — including one that has just lost the
+            //     mode a splitByMode file is for, whose tokens rightly disappear.
+            const loss = findUnmanagedTokenLoss(existing, write.content, new Set(write.splitByCollection
+                ? [
+                    ...collectionIdsInDtcg(write.content),
+                    ...emptyExportedCollectionIds,
+                ]
+                : allExportedCollectionIds));
+            if (loss)
+                throw unmanagedLossError(loss, write.fullPath, source);
+        }
+    }
     if (!dryRun) {
         for (const write of plan.writes) {
             try {
@@ -250,6 +343,10 @@ async function handleExport(args, getDesktopConnector, opts) {
                     mode: dryRun ? "dry-run" : outputBase ? "written" : "inline",
                     configFound: !!loaded,
                     configPath: loaded?.configPath ?? null,
+                    // Which Figma file the variables were read from. Verify this is
+                    // the file you meant — the bridge reads the ACTIVE file unless
+                    // tokens.config.json pins `figmaFile`.
+                    source,
                     collections: document.sets.map((s) => ({
                         name: s.name,
                         modes: s.modes,
@@ -575,6 +672,244 @@ function resolveOutputBaseForFormat(outputPath, loaded, format) {
     }
     return null;
 }
+function describeSource(source) {
+    if (source.fileName && source.fileKey)
+        return `Figma file "${source.fileName}" (${source.fileKey})`;
+    if (source.fileKey)
+        return `Figma file ${source.fileKey}`;
+    return "the file currently active in Figma";
+}
+/**
+ * Throw unless every requested collection id exists in the pulled payload.
+ * All-or-nothing on purpose: exporting 1 of 2 requested collections over an
+ * existing file is still data loss, just a quieter one.
+ */
+export function assertRequestedCollectionsFound(requested, available, source) {
+    if (!Array.isArray(requested) || requested.length === 0)
+        return;
+    const have = new Set(available.map((c) => c.id));
+    const missing = requested.filter((id) => !have.has(id));
+    if (missing.length === 0)
+        return;
+    const listed = available
+        .slice(0, 12)
+        .map((c) => `${c.name ?? "(unnamed)"} [${c.id}]`)
+        .join(", ");
+    throw new Error(`[figma-console-mcp] ${missing.length} of ${requested.length} requested collection(s) not found in ${describeSource(source)}: ${missing.join(", ")}. Nothing was written. ` +
+        "The Desktop Bridge reads from the file that is active in Figma Desktop, so this usually means a different file/tab is focused than the one that owns the collection — switch to it (or use figma_navigate) and retry. " +
+        (available.length > 0
+            ? `Collections in that file: ${listed}${available.length > 12 ? ", …" : ""}.`
+            : "That file has no variable collections."));
+}
+const GENERATED_HEADER = "Generated by figma-console-mcp";
+/** Editors on Windows love a UTF-8 BOM; JSON.parse does not. */
+function stripBom(content) {
+    return content.charCodeAt(0) === 0xfeff ? content.slice(1) : content;
+}
+function isParsableJson(content) {
+    try {
+        JSON.parse(stripBom(content));
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Record which Figma file a generated TEXT output came from, as a
+ * `Source: Figma file <key>` comment line directly under the formatter's
+ * existing "Generated by figma-console-mcp" header — in that header's own
+ * comment style, so this works for every current and future text format
+ * without touching the formatters. JSON outputs are left alone here: DTCG
+ * carries the key in its root `$extensions`, and the plain-JSON formats have
+ * nowhere to put a comment.
+ */
+export function stampSourceFile(content, sourceFileKey) {
+    if (!sourceFileKey)
+        return content;
+    const lines = content.split("\n");
+    const idx = lines
+        .slice(0, 6)
+        .findIndex((line) => line.includes(GENERATED_HEADER));
+    if (idx === -1)
+        return content;
+    const header = lines[idx];
+    const label = `Source: Figma file ${sourceFileKey}`;
+    const indent = header.match(/^\s*/)?.[0] ?? "";
+    const trimmed = header.trimStart();
+    let stamp;
+    if (trimmed.startsWith("/*") && trimmed.trimEnd().endsWith("*/")) {
+        stamp = `${indent}/* ${label} */`;
+    }
+    else if (trimmed.startsWith("//")) {
+        stamp = `${indent}// ${label}`;
+    }
+    else if (trimmed.startsWith("*")) {
+        stamp = `${indent}* ${label}`;
+    }
+    else {
+        return content; // unknown comment style — never guess at syntax
+    }
+    lines.splice(idx + 1, 0, stamp);
+    return lines.join("\n");
+}
+/**
+ * Read back the Figma file key a previously exported file was generated from:
+ * DTCG root `$extensions["figma-console-mcp"].figmaFileKey`, or the
+ * `Source: Figma file <key>` header line of a text output. Null when the file
+ * carries no stamp (exported before stamping existed, or a plain-JSON format).
+ */
+export function readSourceFileStamp(rawContent) {
+    const content = stripBom(rawContent);
+    const head = content.slice(0, 800);
+    if (head.includes(GENERATED_HEADER)) {
+        const m = head.match(/Source: Figma file ([A-Za-z0-9_-]+)/);
+        if (m)
+            return m[1];
+    }
+    if (content.trimStart().startsWith("{")) {
+        try {
+            const key = JSON.parse(content)?.$extensions?.["figma-console-mcp"]
+                ?.figmaFileKey;
+            if (typeof key === "string" && key)
+                return key;
+        }
+        catch {
+            /* not JSON — no stamp */
+        }
+    }
+    return null;
+}
+/** Number of `$value` leaves in a DTCG document; 0 when it isn't one. */
+function dtcgTokenCount(content) {
+    let root;
+    try {
+        root = JSON.parse(stripBom(content));
+    }
+    catch {
+        return 0;
+    }
+    let count = 0;
+    const walk = (node) => {
+        if (!node || typeof node !== "object" || Array.isArray(node))
+            return;
+        const obj = node;
+        if ("$value" in obj) {
+            count++;
+            return;
+        }
+        for (const [key, child] of Object.entries(obj)) {
+            if (!key.startsWith("$"))
+                walk(child);
+        }
+    };
+    walk(root);
+    return count;
+}
+/** Collection ids present in a DTCG document (set-level and token-level stamps). */
+function collectionIdsInDtcg(content) {
+    let root;
+    try {
+        root = JSON.parse(stripBom(content));
+    }
+    catch {
+        return [];
+    }
+    const ids = new Set();
+    const walk = (node) => {
+        if (!node || typeof node !== "object" || Array.isArray(node))
+            return;
+        const obj = node;
+        const ext = obj.$extensions?.["figma-console-mcp"];
+        if (typeof ext?.figmaCollectionId === "string")
+            ids.add(ext.figmaCollectionId);
+        if (typeof ext?.collectionId === "string")
+            ids.add(ext.collectionId);
+        if ("$value" in obj)
+            return;
+        for (const [key, child] of Object.entries(obj)) {
+            if (!key.startsWith("$"))
+                walk(child);
+        }
+    };
+    walk(root);
+    return [...ids];
+}
+/**
+ * Compare an existing DTCG token file with the content about to replace it.
+ *
+ * A token that disappears is only a legitimate drop when the export MANAGES
+ * it: stamped with a variableId AND belonging to a collection included in this
+ * export — i.e. the variable was deleted in Figma. Anything else that would
+ * vanish is loss the caller never asked for:
+ *   • code-only tokens (no stamp) someone added by hand, and
+ *   • tokens from collections outside this export — a scoped export pointed at
+ *     a shared file, or an export read from the WRONG Figma file.
+ *
+ * Returns null when nothing unmanaged is lost, or when the existing file is
+ * not a DTCG JSON document (CSS/SCSS/TS outputs are generated artifacts).
+ */
+export function findUnmanagedTokenLoss(existingContent, newContent, exportedCollectionIds) {
+    let existing;
+    let next;
+    try {
+        existing = JSON.parse(stripBom(existingContent));
+        next = JSON.parse(stripBom(newContent));
+    }
+    catch {
+        return null;
+    }
+    const collect = (node, path, out) => {
+        if (!node || typeof node !== "object" || Array.isArray(node))
+            return;
+        const obj = node;
+        if ("$value" in obj) {
+            const ext = obj.$extensions?.["figma-console-mcp"];
+            out.set(path.join("."), ext && typeof ext === "object"
+                ? ext
+                : undefined);
+            return;
+        }
+        for (const [key, child] of Object.entries(obj)) {
+            if (key.startsWith("$"))
+                continue;
+            collect(child, [...path, key], out);
+        }
+    };
+    const before = new Map();
+    const after = new Map();
+    collect(existing, [], before);
+    collect(next, [], after);
+    if (before.size === 0)
+        return null;
+    const loss = { codeOnly: [], otherCollections: [] };
+    for (const [path, stamp] of before) {
+        if (after.has(path))
+            continue;
+        if (!stamp || typeof stamp.variableId !== "string") {
+            loss.codeOnly.push(path);
+        }
+        else if (typeof stamp.collectionId !== "string" ||
+            !exportedCollectionIds.has(stamp.collectionId)) {
+            loss.otherCollections.push(path);
+        }
+        // else: stamped + collection exported + gone = deleted in Figma. Fine.
+    }
+    return loss.codeOnly.length + loss.otherCollections.length > 0 ? loss : null;
+}
+function unmanagedLossError(loss, fullPath, source) {
+    const sample = (paths) => `${paths.slice(0, 5).join(", ")}${paths.length > 5 ? `, +${paths.length - 5} more` : ""}`;
+    const parts = [];
+    if (loss.otherCollections.length > 0) {
+        parts.push(`${loss.otherCollections.length} token(s) from collections that are not part of this export (${sample(loss.otherCollections)})`);
+    }
+    if (loss.codeOnly.length > 0) {
+        parts.push(`${loss.codeOnly.length} token(s) that were not exported from Figma, e.g. added by hand (${sample(loss.codeOnly)})`);
+    }
+    return new Error(`[figma-console-mcp] Nothing was written. Overwriting "${fullPath}" with this export (read from ${describeSource(source)}) would delete ${parts.join(" and ")}. ` +
+        "Export replaces the whole file — it does not merge into it. If the source file above is not the one you intended, switch files in Figma and retry. " +
+        'If the loss is intended, pass strategy: "replace" to overwrite anyway; otherwise export to a different path and reconcile by hand.');
+}
 /**
  * Extensions the formatters emit. An `outputPath` ending in one of these is a
  * FILE target, not a directory — nobody wants a directory named
@@ -636,6 +971,7 @@ export function planExportWrites(files, outputPath, loaded) {
                         sourcePath: file.path,
                         fullPath: target,
                         content: file.content,
+                        splitByCollection: file.splitByCollection,
                     },
                 ],
                 warnings,
@@ -652,6 +988,7 @@ export function planExportWrites(files, outputPath, loaded) {
             sourcePath: file.path,
             fullPath: isAbsolute(file.path) ? file.path : join(base, file.path),
             content: file.content,
+            splitByCollection: file.splitByCollection,
         });
     }
     return { writes, warnings };

package/dist/cloudflare/index.js

@@ -75,7 +75,7 @@ export class FigmaConsoleMCPv3 extends McpAgent {
         this.server = (() => {
             const s = new McpServer({
                 name: "Figma Console MCP",
-                version: "1.40.1",
+                version: "1.40.2",
             });
             // Identity wrap — every tool's response and thrown error gets stamped
             // with our MCP name so cross-MCP attribution is unambiguous.
@@ -1085,7 +1085,7 @@ export default {
             });
             const statelessServer = new McpServer({
                 name: "Figma Console MCP",
-                version: "1.40.1",
+                version: "1.40.2",
             });
             wrapServerForIdentity(statelessServer);
             // ================================================================
@@ -1723,7 +1723,7 @@ export default {
             return new Response(JSON.stringify({
                 status: "healthy",
                 service: "Figma Console MCP",
-                version: "1.40.1",
+                version: "1.40.2",
                 endpoints: {
                     mcp: ["/sse", "/mcp"],
                     oauth_mcp_spec: ["/.well-known/oauth-authorization-server", "/authorize", "/token", "/oauth/register"],

package/dist/core/tokens/schemas.js

@@ -71,7 +71,7 @@ export const ExportTokensInputSchema = z.object({
         .string()
         .optional()
         .describe("Explicit path to a tokens.config.json file. When omitted, the tool walks up from cwd looking for one — typical case is zero-arg."),
-    strategy: SyncStrategySchema.optional().describe("How to handle existing output files. 'merge' (default) diffs against current contents and writes only changed tokens, preserving code-only additions. 'replace' wipes and rewrites. 'dry-run' computes the diff and reports what would change without writing."),
+    strategy: SyncStrategySchema.optional().describe("How to handle existing output files. Export always replaces a target file's contents with the current Figma state — it does not merge token-by-token. 'merge' (default) is the SAFE mode: it refuses to write, leaving the file untouched, if overwriting an existing DTCG file would delete tokens the export does not manage (hand-added tokens, or tokens from collections not included in this export). 'replace' overwrites unconditionally. 'dry-run' reports what would be written without writing."),
     prefix: z
         .string()
         .optional()

package/dist/core/tokens/schemas.js.map

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

package/dist/core/tokens-tools.d.ts

@@ -38,6 +38,12 @@ export interface RegisterTokensToolsOptions {
      * are all Local Mode only.
      */
     isRemoteMode?: boolean;
+    /**
+     * Resolve a Figma fileKey to its display name (Local Mode: from the Desktop
+     * Bridge's connected-file registry). Used to tell the caller WHICH file an
+     * export actually read from — the bridge reads whatever file is active.
+     */
+    resolveFileName?: (fileKey: string) => string | null | undefined;
 }
 export declare function registerExportTokensTool(server: McpServer, getDesktopConnector: () => Promise<any>, opts?: RegisterTokensToolsOptions): void;
 export declare function registerImportTokensTool(server: McpServer, getDesktopConnector: () => Promise<any>, opts?: RegisterTokensToolsOptions): void;
@@ -45,6 +51,59 @@ export declare function registerImportTokensTool(server: McpServer, getDesktopCo
  * Convenience: register both tools at once.
  */
 export declare function registerTokensTools(server: McpServer, getDesktopConnector: () => Promise<any>, opts?: RegisterTokensToolsOptions): void;
+/** Where an export's variables were read from. */
+export interface ExportSource {
+    fileKey: string | null;
+    fileName: string | null;
+}
+/**
+ * Throw unless every requested collection id exists in the pulled payload.
+ * All-or-nothing on purpose: exporting 1 of 2 requested collections over an
+ * existing file is still data loss, just a quieter one.
+ */
+export declare function assertRequestedCollectionsFound(requested: string[] | undefined, available: Array<{
+    id: string;
+    name?: string;
+}>, source: ExportSource): void;
+/**
+ * Record which Figma file a generated TEXT output came from, as a
+ * `Source: Figma file <key>` comment line directly under the formatter's
+ * existing "Generated by figma-console-mcp" header — in that header's own
+ * comment style, so this works for every current and future text format
+ * without touching the formatters. JSON outputs are left alone here: DTCG
+ * carries the key in its root `$extensions`, and the plain-JSON formats have
+ * nowhere to put a comment.
+ */
+export declare function stampSourceFile(content: string, sourceFileKey: string | null): string;
+/**
+ * Read back the Figma file key a previously exported file was generated from:
+ * DTCG root `$extensions["figma-console-mcp"].figmaFileKey`, or the
+ * `Source: Figma file <key>` header line of a text output. Null when the file
+ * carries no stamp (exported before stamping existed, or a plain-JSON format).
+ */
+export declare function readSourceFileStamp(rawContent: string): string | null;
+/** Tokens an overwrite would destroy that the export has no authority over. */
+export interface UnmanagedTokenLoss {
+    /** Tokens with no figma-console-mcp variable stamp — hand-added / code-only. */
+    codeOnly: string[];
+    /** Tokens stamped with a collection that is not part of this export. */
+    otherCollections: string[];
+}
+/**
+ * Compare an existing DTCG token file with the content about to replace it.
+ *
+ * A token that disappears is only a legitimate drop when the export MANAGES
+ * it: stamped with a variableId AND belonging to a collection included in this
+ * export — i.e. the variable was deleted in Figma. Anything else that would
+ * vanish is loss the caller never asked for:
+ *   • code-only tokens (no stamp) someone added by hand, and
+ *   • tokens from collections outside this export — a scoped export pointed at
+ *     a shared file, or an export read from the WRONG Figma file.
+ *
+ * Returns null when nothing unmanaged is lost, or when the existing file is
+ * not a DTCG JSON document (CSS/SCSS/TS outputs are generated artifacts).
+ */
+export declare function findUnmanagedTokenLoss(existingContent: string, newContent: string, exportedCollectionIds: Set<string>): UnmanagedTokenLoss | null;
 /** A single file the export is going to write, with its resolved destination. */
 export interface PlannedExportWrite {
     format: string;
@@ -53,6 +112,8 @@ export interface PlannedExportWrite {
     /** Absolute destination on disk. */
     fullPath: string;
     content: string;
+    /** True when this file holds ONE collection (a splitByCollection target). */
+    splitByCollection?: boolean;
 }
 /**
  * Decide where every formatted file lands. `outputPath` is interpreted as:
@@ -72,6 +133,7 @@ export declare function planExportWrites(files: Array<{
     format: string;
     path: string;
     content: string;
+    splitByCollection?: boolean;
 }>, outputPath: string | undefined, loaded: ReturnType<typeof loadTokensConfig>): {
     writes: PlannedExportWrite[];
     warnings: string[];