@muloka/figma-console-mcp 0.1.2 → 0.3.0

package/README.md

@@ -18,7 +18,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**.
 
-> **🆕 Figma Slots Support (v1.35.0):** Create, inspect, populate, and reset Figma Slots (GA at Config 2026) programmatically — `figma_create_slot` adds slots to components (variants included), `figma_append_to_slot` populates instance slots with cloned or new content, plus `figma_get_slots`, `figma_reset_slot`, and `figma_add_slot_property`. Live-validated against the GA Plugin API; closes the most-requested issue [#29](https://github.com/southleft/figma-console-mcp/issues/29), based on community PR [#77](https://github.com/southleft/figma-console-mcp/pull/77). **Plugin re-import required** (`code.js` + `ui.html` changed). [See what's new →](CHANGELOG.md#1350---2026-07-09)
+> **🆕 Target Lock for Parallel Work (v1.36.0):** `figma_navigate` now takes a `lock: true` flag that pins the active file — so an AI agent can keep working in one Figma file while you work in another, without commands silently routing to the wrong file. New connections, reconnects, and your own selection/page changes in other files no longer move the target; the pin auto-releases if that file disconnects. `figma_list_open_files` reports a `targetLocked` flag for a pre-write guard. Server-only release — **no plugin re-import needed**. [See what's new →](CHANGELOG.md#1360---2026-07-16)
 
 ## What is this?
 
@@ -829,9 +829,10 @@ The architecture supports adding new apps with minimal boilerplate — each app
 
 ## 🛤️ Roadmap
 
-**Current Status:** v1.35.0 (Stable) - Production-ready. Latest: 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, **112 tools** (Local) / **101 tools** (Cloud) / **9 tools** (Remote read-only), Comments API, cross-MCP identity disambiguation, and MCP Apps.
+**Current Status:** v1.36.0 (Stable) - Production-ready. Latest: 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 (server-only, no plugin re-import). 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, **112 tools** (Local) / **101 tools** (Cloud) / **9 tools** (Remote read-only), Comments API, cross-MCP identity disambiguation, and MCP Apps.
 
 **Recent Releases:**
+- [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.
 - [x] **v1.35.0** - Figma Slots write support, closing [#29](https://github.com/southleft/figma-console-mcp/issues/29) (the tracker's most-requested feature) via community PR [#77](https://github.com/southleft/figma-console-mcp/pull/77) by @simonesalvucci, updated to the GA API. Five new tools: `figma_create_slot` (slot + auto-linked SLOT property; variants inside component sets supported — the beta restriction was lifted at GA), `figma_get_slots`, `figma_append_to_slot` (clone or create content into instance slots; snaps clones to the slot origin), `figma_reset_slot`, and `figma_add_slot_property` (retrofit an existing frame as a slot). Hardened by live validation: VARIANT `defaultValue` passthrough restored (Figma requires non-empty), destructive-path reorder in the append handler (content validated before `clearExisting` empties anything), relay whitelist fix for `slot` payloads. **Plugin re-import required** (`code.js` + `ui.html` changed).
 - [x] **v1.34.0** - Bidirectional Token Sync v2 + DTCG 2025.10. `figma_import_tokens` now applies the *complete* diff plan: missing collections and variables are created (with modes, inferred/recorded types, and values set in dependency order — aliases in a second pass), token-path renames route to the update phase by round-trip variable ID (no more create+delete pairs that would permanently destroy the original under `replace`), reference values write real `{ type: "VARIABLE_ALIAS", id }` payloads via a four-tier resolver, and deletes are strictly gated behind `strategy: "replace"`. `figma_export_tokens` gains `dtcgDialect: "2025"` (object-form colors from full-precision floats, object dimensions) while the legacy default stays byte-identical; import accepts both dialects unconditionally with dialect-insensitive diff normalization. Variable `scopes` + `codeSyntax` round-trip through `$extensions["figma-console-mcp"]`. `figma_setup_design_tokens` accepts DTCG brace references (`"{color.blue.600}"`) that resolve to real aliases, including forward references. New tool `figma_create_component_set` builds a variant set from an axes matrix (or combines existing components) with `Prop=Value` naming, optional auto-arranged grid, and variant keys in the response — with count-scaled timeouts and rollback on failure. **Plugin re-import required** (`code.js` + `ui.html` changed — the component-set handler and relay). 183 tests across the token/write-tools suites.
 - [x] **v1.33.2** - Version-handshake false-positive fix. The v1.33.0 handshake compared the plugin's reported version against the server's *package* version, so server-only releases (like the v1.33.1 dependency sweep) flagged every up-to-date plugin as stale and pushed the re-import banner for files that hadn't changed. The server now compares against the `PLUGIN_VERSION` embedded in the `figma-desktop-bridge/code.js` it ships — exactly what a re-import would install — and `PLUGIN_VERSION` itself now means "last release in which plugin files changed" (release tooling bumps it only when `figma-desktop-bridge/` actually changed since the last tag). `figma_get_status` gains `transport.websocket.bundledPluginVersion`; `figma_diagnose` blames the right version. No new tools, **no plugin re-import required** (one-time exception: if you re-imported at v1.33.1, the banner appears once more — clear it with one final re-import). 1245 tests passing (9 new).

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

@@ -1 +1 @@
-{"version":3,"file":"figma-tools.d.ts","sourceRoot":"","sources":["../../src/core/figma-tools.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIzE,OAAO,KAAK,EAAE,QAAQ,EAAgB,MAAM,gBAAgB,CAAC;AAwwB7D;;GAEG;AACH,UAAU,oBAAoB;IAC7B,iGAAiG;IACjG,YAAY,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACpC,MAAM,EAAE,SAAS,EACjB,WAAW,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,EACpC,aAAa,EAAE,MAAM,MAAM,GAAG,IAAI,EAClC,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,GAAG,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,EAC9D,OAAO,CAAC,EAAE,oBAAoB,EAC9B,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,QAglGxC"}
+{"version":3,"file":"figma-tools.d.ts","sourceRoot":"","sources":["../../src/core/figma-tools.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAIzE,OAAO,KAAK,EAAE,QAAQ,EAAgB,MAAM,gBAAgB,CAAC;AAwwB7D;;GAEG;AACH,UAAU,oBAAoB;IAC7B,iGAAiG;IACjG,YAAY,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CACpC,MAAM,EAAE,SAAS,EACjB,WAAW,EAAE,MAAM,OAAO,CAAC,QAAQ,CAAC,EACpC,aAAa,EAAE,MAAM,MAAM,GAAG,IAAI,EAClC,cAAc,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE;IAAE,IAAI,EAAE,GAAG,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC,EAC9D,OAAO,CAAC,EAAE,oBAAoB,EAC9B,mBAAmB,CAAC,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,QAqoGxC"}

package/dist/core/figma-tools.js

@@ -951,21 +951,24 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
             .optional()
             .default(false)
             .describe("DEPRECATED — setting this to true now raises an explicit error. The Puppeteer-based console parser no longer exists. Open the Figma Console MCP Desktop Bridge plugin in Figma Desktop and call figma_get_variables() without parseFromConsole; the plugin returns full variable data through the WebSocket bridge."),
+        // NOTE: deliberately no .default() on either param. Every consumer below
+        // applies its own fallback (?? 1 / ?? 50), and leaving these undefined is
+        // what lets format='full' tell "caller asked for page 2" apart from
+        // "caller passed nothing" — without that distinction, honoring them would
+        // silently truncate every full response to 50 variables.
         page: z
             .number()
             .int()
             .min(1)
             .optional()
-            .default(1)
-            .describe("Page number for paginated results (1-based). Use when response is too large (>1MB). Each page returns up to 50 variables."),
+            .describe("Page number for paginated results (1-based). Use when the response is too large to handle in one call. Applies to format='filtered' and format='full'. Default: 1. IMPORTANT: a page number beyond the last page is CLAMPED to the last page, not rejected — it returns that page's data again with currentPage set to the real last page. Drive iteration off pagination.hasNextPage; a loop that just increments page will repeat the final page forever."),
         pageSize: z
             .number()
             .int()
             .min(1)
             .max(100)
             .optional()
-            .default(50)
-            .describe("Number of variables per page (1-100). Default: 50. Smaller values reduce response size."),
+            .describe("Number of variables per page. Hard limit 100 — higher values are rejected with a validation error, not clamped. Default: 50. Applies to format='filtered' and format='full'. For format='full', pagination is applied only when page or pageSize is explicitly passed; otherwise the complete dataset is returned. SOFT LIMIT: a page that exceeds ~25K estimated tokens is auto-summarized, so the page is discarded rather than returned — measured on a 689-variable file, pageSize=100 reached ~16K tokens at standard verbosity and ~20K with verbosity='full' plus resolveAliases. 100 is safe at roughly 200 tokens/variable; prefer 50 when resolving aliases on a mode-heavy file."),
         resolveAliases: z
             .boolean()
             .optional()
@@ -1199,6 +1202,22 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
                 }
                 else {
                     // format === 'full'
+                    // Honor page/pageSize when the caller explicitly passed either one.
+                    // Previously they were accepted, silently ignored, and omitted from
+                    // the response, so a caller had no way to tell paging had not
+                    // happened (southleft/figma-console-mcp#98).
+                    //
+                    // This runs BEFORE the token estimate on purpose: slicing is exactly
+                    // how a caller retrieves a large dataset in pieces that fit under the
+                    // limit, so summarizing first would defeat the request.
+                    //
+                    // Both params are undefined unless passed (no zod .default()), so an
+                    // un-paginated full request still returns the complete dataset.
+                    if (page !== undefined || pageSize !== undefined) {
+                        const paginated = paginateVariables(responseData, page ?? 1, pageSize ?? 50);
+                        responseData = paginated.data;
+                        paginationInfo = paginated.pagination;
+                    }
                     // Check if we need to auto-summarize
                     const estimatedTokens = estimateTokens(responseData);
                     if (estimatedTokens > 25000) {
@@ -1435,19 +1454,30 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
                             };
                         }
                     }
-                    // Apply pagination if requested
+                    // Apply pagination if requested.
+                    //
+                    // page/pageSize no longer carry zod .default() values (see the note on
+                    // the schema), so this branch restates the 1/50 it previously received
+                    // implicitly. That keeps the REST path's behavior byte-identical: it
+                    // has always paginated to 50 whether or not the caller asked. Reaching
+                    // this code requires a Figma Enterprise plan, so it cannot be exercised
+                    // from this fork — left deliberately unchanged rather than "fixed"
+                    // blind. The divergent field names here vs. paginateVariables() are
+                    // southleft/figma-console-mcp#99.
+                    const restPage = page ?? 1;
+                    const restPageSize = pageSize ?? 50;
                     let paginationInfo;
-                    if (pageSize) {
-                        const startIdx = (page - 1) * pageSize;
-                        const endIdx = startIdx + pageSize;
+                    if (restPageSize) {
+                        const startIdx = (restPage - 1) * restPageSize;
+                        const endIdx = startIdx + restPageSize;
                         const totalVars = localFormatted.variables.length;
                         paginationInfo = {
-                            page,
-                            pageSize,
+                            page: restPage,
+                            pageSize: restPageSize,
                             totalItems: totalVars,
-                            totalPages: Math.ceil(totalVars / pageSize),
+                            totalPages: Math.ceil(totalVars / restPageSize),
                             hasNextPage: endIdx < totalVars,
-                            hasPrevPage: page > 1,
+                            hasPrevPage: restPage > 1,
                         };
                         localFormatted.variables = localFormatted.variables.slice(startIdx, endIdx);
                         if (includePublished && publishedFormatted) {
@@ -1627,6 +1657,10 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
                         }
                         // Apply format logic
                         let responseData = dataForCache;
+                        // Declared out here so the response builder below can see it —
+                        // it was previously scoped inside the 'filtered' branch, computed,
+                        // and then unreachable at return time.
+                        let paginationInfo = null;
                         if (format === 'summary') {
                             responseData = generateSummary(dataForCache);
                             logger.info({ fileKey, estimatedTokens: estimateTokens(responseData) }, 'Generated summary from fetched data');
@@ -1644,7 +1678,6 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
                                 filteredCount: responseData.variables?.length,
                             }, 'Applied filters to fetched data');
                             // Apply pagination (CRITICAL - was missing!)
-                            let paginationInfo = null;
                             const paginated = paginateVariables(responseData, page || 1, pageSize || 50);
                             responseData = paginated.data;
                             paginationInfo = paginated.pagination;
@@ -1694,6 +1727,19 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
                         }
                         else {
                             // format === 'full'
+                            // Same fix as the cached path above (southleft#98): honor
+                            // page/pageSize when explicitly passed, before the token
+                            // estimate, so slicing is what keeps a large dataset under the
+                            // limit rather than the summarizer discarding it.
+                            //
+                            // This branch serves cache-miss requests. It is a separate code
+                            // path from the cached one and needed the fix independently —
+                            // a live check against a warm cache exercises only the other.
+                            if (page !== undefined || pageSize !== undefined) {
+                                const paginated = paginateVariables(responseData, page ?? 1, pageSize ?? 50);
+                                responseData = paginated.data;
+                                paginationInfo = paginated.pagination;
+                            }
                             // Check if we need to auto-summarize
                             const estimatedTokens = estimateTokens(responseData);
                             if (estimatedTokens > 25000) {
@@ -1773,6 +1819,11 @@ export function registerFigmaAPITools(server, getFigmaAPI, getCurrentUrl, variab
                                         timestamp: dataForCache.timestamp,
                                         data: responseData,
                                         cached: false,
+                                        // paginationInfo was computed above and then dropped on the
+                                        // floor, so a cache-miss request through the Desktop Bridge
+                                        // received sliced data with no indication more pages existed
+                                        // — silent truncation. Same shape the cache path returns.
+                                        ...(paginationInfo && { pagination: paginationInfo }),
                                     }),
                                 },
                             ],