@mp3wizard/figma-console-mcp 1.29.2 → 1.30.1

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**.
 
-> **🆕 Shared Library Inspection (v1.29.0, patched v1.29.1):** Three new tools fill the gap between "I see a component key in search results" and "I can actually use it." `figma_get_library_component_by_key` resolves any component key to full property definitions + variant keys + visual specs — without needing the source library file's URL. `figma_get_library_variables` lists every variable from your subscribed libraries (no Enterprise plan required — uses the Plugin API path that works on Pro and Org). `figma_import_library_variable` brings a library token into the current file so it can be bound to nodes alongside the file's own variables. Works on every Figma plan. 106 tools total. **Patched v1.29.1:** `figma_get_design_system_kit` now reads variables on any plan via the bridge too — no more 403 for non-Enterprise users. [See what's new →](CHANGELOG.md#1291---2026-05-30)
+> **🆕 Native variable binding & typography (v1.30.0):** The structured write tools now handle the operations that used to force you into raw `figma_execute`. `figma_set_fills` / `figma_set_strokes` bind a fill or stroke to a color variable via a new `variableId` param (works on any Figma plan through the bridge — no Enterprise Variables API). `figma_set_text` gains `fontFamily` / `fontStyle` with space-insensitive normalization (`SemiBold` → `Semi Bold`) and graceful fallback. `figma_instantiate_component` now pre-loads instance fonts before text overrides (no more silently-skipped overrides) and reports failed overrides in a `warnings` array. Works on every Figma plan. [See what's new →](CHANGELOG.md#1300---2026-06-02)
 
 ## What is this?
 
@@ -808,9 +808,11 @@ The architecture supports adding new apps with minimal boilerplate — each app
 
 ## 🛤️ Roadmap
 
-**Current Status:** v1.29.1 (Stable) - Production-ready with 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, **106 tools** (Local) / **95 tools** (Cloud) / **9 tools** (Remote read-only), Comments API, cross-MCP identity disambiguation, and MCP Apps.
+**Current Status:** v1.30.0 (Stable) - Production-ready with 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, **106 tools** (Local) / **95 tools** (Cloud) / **9 tools** (Remote read-only), Comments API, cross-MCP identity disambiguation, and MCP Apps.
 
 **Recent Releases:**
+- [x] **v1.30.0** - Native variable binding + typography in the structured write tools, closing the Plugin API gaps that used to force raw `figma_execute`. `figma_set_fills` / `figma_set_strokes` accept a `variableId` to bind a fill/stroke to a color variable via `setBoundVariableForPaint` (any plan, via the bridge). `figma_set_text` gains `fontFamily` / `fontStyle` with space-insensitive normalization (`SemiBold` → `Semi Bold`) and graceful `Regular` fallback. `figma_instantiate_component` pre-loads instance text fonts before applying overrides (fixes silently-skipped text overrides on non-Regular weights) and returns a `warnings` array for failed overrides. Also fixes a mixed-font crash in `figma_set_text` and a `ui.html` relay that was dropping new message fields. No new tools; **plugin re-import required** (bridge `ui.html` + `code.js` changed). Validated live; 1185 tests passing.
+- [x] **v1.29.2** - Bug fix: `figma_generate_component_doc` now renders Figma component descriptions faithfully and reliably tags atomic-design level. Single-`#` headings in descriptions render as real sections (Usage Guidelines, Implementation Considerations, Accessibility Requirements, Content Configuration) instead of leaking as `- # Heading` list items; frontmatter `description` takes the first sentence instead of truncating on the word "Accessibility"; the generated Figma URL no longer doubles `?node-id=`; and the component's atomic level (atom/molecule/organism/template) is auto-detected via a single `ids=<node>` file request + divider walk-back, with no dependency on library publishing. No new tools; plugin re-import not required.
 - [x] **v1.29.1** - Bug fix: `figma_get_design_system_kit` now resolves variables bridge-first (Desktop Bridge / cloud relay → REST fallback) instead of calling the Enterprise-only Variables REST API directly. Non-Enterprise users no longer hit a 403 on the kit's token section when a bridge is connected, and a REST 403 now points the caller back to the bridge instead of dead-ending. 7 new tests, 1185 total passing. No new tools; plugin re-import not required.
 - [x] **v1.29.0** - Shared library inspection: three new tools close the gap between "I have a component key" and "I can actually use it." `figma_get_library_component_by_key` resolves any 40-char component key to full `componentPropertyDefinitions` + variants (with their published keys) + per-variant visual specs — without needing the source library file's URL. `figma_get_library_variables` lists library tokens via Plugin API (works on every Figma plan; the REST equivalent is Enterprise-only). `figma_import_library_variable` imports a library token to the current file so it can be bound to nodes. 27 new tests, 1178 total passing. Plugin re-import optional.
 - [x] **v1.28.1** - Bug fix patch surfacing from live-fire testing of the v1.28.0 formatters against multi-tier semantic-token design systems. Fixes: Tailwind v3 emitted empty `module.exports` for alias-only sets (now resolves alias chains to literal values); TypeScript module + JSON flat + JSON nested formatters emitted `"{alias.path}"` strings as literal values (now resolves); Tailwind v4 namespace-prefix doubling (`--color-theme-color-X` is now `--color-theme-X`). Adds `resolveAliasChain` public helper. 1151 tests still passing.

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

@@ -222,6 +222,8 @@ export class CloudWebSocketConnector {
                 params.fontWeight = options.fontWeight;
             if (options.fontFamily)
                 params.fontFamily = options.fontFamily;
+            if (options.fontStyle)
+                params.fontStyle = options.fontStyle;
         }
         return this.sendCommand('SET_TEXT_CONTENT', params);
     }

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

@@ -174,7 +174,7 @@ export function parseComponentDescription(description) {
     for (const line of lines) {
         const trimmed = line.trim();
         // Detect section headers: bold text (**Header**), markdown headers (## Header), or plain text exact matches
-        const markdownHeaderMatch = trimmed.match(/^(?:\*\*|###?\s*)(.+?)(?:\*\*)?$/);
+        const markdownHeaderMatch = trimmed.match(/^(?:\*\*|#{1,6}\s*)(.+?)(?:\*\*)?$/);
         const headerText = markdownHeaderMatch ? markdownHeaderMatch[1].trim().replace(/\*\*/g, "") : null;
         // Check if this is a Figma per-property documentation block (e.g., "Show Left Icon: True – Purpose")
         // These should be routed to "other" to avoid polluting content guidelines and accessibility sections
@@ -1380,7 +1380,47 @@ function buildParityInstruction(componentName, parityScore, counts, canonicalSou
 // ============================================================================
 // Documentation Section Generators
 // ============================================================================
-function generateFrontmatter(componentName, description, node, componentMeta, fileUrl, codeInfo, canonicalSource) {
+/**
+ * Detect the atomic-design level (atom | molecule | organism | template) of a component
+ * by finding its Figma page and walking the ordered page list back to the nearest
+ * section-divider page (e.g. "ATOMS", "MOLECULES", "ORGANISMS"). Returns null when the
+ * file doesn't use atomic-design page sections or the page can't be resolved — callers
+ * then simply omit the `level` frontmatter. Best-effort and never throws.
+ */
+async function detectAtomicLevel(api, fileKey, nodeId, setNodeId, _componentMeta, _allComponentsMeta) {
+    try {
+        const targetId = setNodeId || nodeId;
+        // Resolve the page the component lives on — independent of library-publish
+        // status (published `containing_frame` metadata is empty for many files).
+        // Requesting the file with `ids` returns every page in document order, but
+        // prunes each page's children to only the path reaching the requested node,
+        // so the single page whose subtree still contains the node is its home page.
+        const pages = (await api.getFile(fileKey, { ids: [targetId] }))?.document?.children || [];
+        const contains = (n) => n?.id === targetId || (Array.isArray(n?.children) && n.children.some(contains));
+        const idx = pages.findIndex((p) => contains(p));
+        if (idx < 0)
+            return null;
+        // Walk back to the nearest atomic-design divider page.
+        const LEVELS = [
+            ["ATOM", "atom"],
+            ["MOLECULE", "molecule"],
+            ["ORGANISM", "organism"],
+            ["TEMPLATE", "template"],
+        ];
+        for (let i = idx; i >= 0; i--) {
+            const stripped = (pages[i]?.name || "").toUpperCase().replace(/[^A-Z]/g, "");
+            for (const [marker, level] of LEVELS) {
+                if (stripped.startsWith(marker))
+                    return level;
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function generateFrontmatter(componentName, description, node, componentMeta, fileUrl, codeInfo, canonicalSource, level) {
     const status = codeInfo?.changelog?.[0]
         ? "stable"
         : componentMeta?.description?.toLowerCase().includes("deprecated")
@@ -1388,6 +1428,8 @@ function generateFrontmatter(componentName, description, node, componentMeta, fi
             : "stable";
     const version = codeInfo?.changelog?.[0]?.version || "1.0.0";
     const tags = [componentName.toLowerCase()];
+    if (level)
+        tags.push(level);
     if (node.type === "COMPONENT_SET")
         tags.push("variants");
     if (node.componentPropertyDefinitions)
@@ -1395,10 +1437,11 @@ function generateFrontmatter(componentName, description, node, componentMeta, fi
     const lines = [
         "---",
         `title: ${componentName}`,
-        `description: ${(description.split(/(?:When to Use|When NOT to Use|Variants|Content Requirements|Accessibility)/i)[0] || description).replace(/\n/g, " ").replace(/\s+/g, " ").trim() || `${componentName} component`}`,
+        `description: ${((description.split(/\n\s*\n|\n#{1,6}\s|\n\*\*/)[0] || description).replace(/\n/g, " ").replace(/\s+/g, " ").trim().split(/(?<=[.!?])\s+/)[0] || `${componentName} component`)}`,
         `status: ${status}`,
         `version: ${version}`,
         `category: components`,
+        ...(level ? [`level: ${level}`] : []),
         `tags: [${tags.join(", ")}]`,
         `figma: ${fileUrl}`,
     ];
@@ -2560,7 +2603,9 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
                     logger.warn("Desktop Bridge fetch failed, proceeding without bridge-sourced data");
                 }
             }
-            const fileUrl_ = `${url}?node-id=${nodeId.replace(":", "-")}`;
+            // Strip any existing query (e.g. the connected file's ?node-id=<page>) before
+            // appending the target node, otherwise the URL ends up with a doubled ?node-id=.
+            const fileUrl_ = `${url.split("?")[0]}?node-id=${nodeId.replace(":", "-")}`;
             // Parse the component description for structured content
             const parsedDesc = parseComponentDescription(description);
             // Determine canonical source
@@ -2589,7 +2634,8 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
             const parts = [];
             const includedSections = [];
             if (includeFrontmatter) {
-                parts.push(generateFrontmatter(componentName, description, node, componentMeta, fileUrl_, codeInfo, canonicalSource));
+                const atomicLevel = await detectAtomicLevel(api, fileKey, nodeId, setInfo.setNodeId, componentMeta, allComponentsMeta);
+                parts.push(generateFrontmatter(componentName, description, node, componentMeta, fileUrl_, codeInfo, canonicalSource, atomicLevel));
                 parts.push("");
             }
             if (s.overview) {

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

@@ -30,7 +30,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.29.1";
+const MCP_VERSION = "1.30.0";
 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:

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

@@ -230,6 +230,8 @@ export class WebSocketConnector {
                 params.fontWeight = options.fontWeight;
             if (options.fontFamily)
                 params.fontFamily = options.fontFamily;
+            if (options.fontStyle)
+                params.fontStyle = options.fontStyle;
         }
         return this.wsServer.sendCommand('SET_TEXT_CONTENT', params);
     }

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

@@ -872,8 +872,13 @@ After instantiating components, use figma_take_screenshot to verify the result l
                         type: "text",
                         text: JSON.stringify({
                             success: true,
-                            message: "Component instantiated successfully",
+                            message: result.warnings && result.warnings.length
+                                ? "Component instantiated, but some overrides did not apply (see warnings)"
+                                : "Component instantiated successfully",
                             instance: result.instance,
+                            ...(result.warnings && result.warnings.length
+                                ? { warnings: result.warnings }
+                                : {}),
                             timestamp: Date.now(),
                         }),
                     },
@@ -1184,7 +1189,7 @@ After instantiating components, use figma_take_screenshot to verify the result l
         }
     });
     // Tool: Set Node Fills
-    server.tool("figma_set_fills", "Set the fill colors on a node. Accepts hex color strings (e.g., '#FF0000') or full paint objects.", {
+    server.tool("figma_set_fills", "Set the fill colors on a node. Accepts hex color strings (e.g., '#FF0000'). To bind a fill to a design token / color variable, pass that fill's variableId — the variable drives the color and this works on any Figma plan via the bridge (no raw figma_execute needed).", {
         nodeId: z.string().describe("The node ID to modify"),
         fills: z
             .array(z.object({
@@ -1193,11 +1198,16 @@ After instantiating components, use figma_take_screenshot to verify the result l
                 .describe("Fill type (currently only SOLID supported)"),
             color: z
                 .string()
-                .describe("Hex color string (e.g., '#FF0000', '#FF000080' for transparency)"),
+                .optional()
+                .describe("Hex color string (e.g., '#FF0000', '#FF000080' for transparency). Optional when variableId is provided."),
             opacity: z
                 .number()
                 .optional()
                 .describe("Opacity 0-1 (default: 1)"),
+            variableId: z
+                .string()
+                .optional()
+                .describe("Bind this fill's color to a Figma variable by id (e.g. 'VariableID:1:23' from figma_get_variables). When set, the variable drives the color. Import library variables first via figma_import_library_variable."),
         }))
             .describe("Array of fill objects"),
     }, async ({ nodeId, fills }) => {
@@ -1279,13 +1289,20 @@ After instantiating components, use figma_take_screenshot to verify the result l
         }
     });
     // Tool: Set Node Strokes
-    server.tool("figma_set_strokes", "Set the stroke (border) on a node. Accepts hex color strings and optional stroke weight.", {
+    server.tool("figma_set_strokes", "Set the stroke (border) on a node. Accepts hex color strings and optional stroke weight. To bind a stroke to a design token / color variable, pass that stroke's variableId — works on any Figma plan via the bridge.", {
         nodeId: z.string().describe("The node ID to modify"),
         strokes: z
             .array(z.object({
             type: z.literal("SOLID").describe("Stroke type"),
-            color: z.string().describe("Hex color string"),
+            color: z
+                .string()
+                .optional()
+                .describe("Hex color string. Optional when variableId is provided."),
             opacity: z.number().optional().describe("Opacity 0-1"),
+            variableId: z
+                .string()
+                .optional()
+                .describe("Bind this stroke's color to a Figma variable by id (e.g. 'VariableID:1:23' from figma_get_variables). When set, the variable drives the color."),
         }))
             .describe("Array of stroke objects"),
         strokeWeight: z
@@ -1443,14 +1460,24 @@ After instantiating components, use figma_take_screenshot to verify the result l
         }
     });
     // Tool: Set Text Content
-    server.tool("figma_set_text", "Set the text content of a text node. Optionally adjust font size.", {
+    server.tool("figma_set_text", "Set the text content of a text node. Optionally adjust font size and the font family/style. Font style names are space-sensitive ('Semi Bold', not 'SemiBold'), but this tool auto-corrects common no-space variants and falls back gracefully — so you don't need raw figma_execute to change typography.", {
         nodeId: z.string().describe("The text node ID"),
         text: z.string().describe("The new text content"),
         fontSize: z.number().optional().describe("Optional font size to set"),
-    }, async ({ nodeId, text, fontSize }) => {
+        fontFamily: z
+            .string()
+            .optional()
+            .describe("Optional font family to apply (e.g., 'Inter')"),
+        fontStyle: z
+            .string()
+            .optional()
+            .describe("Optional font style/weight to apply (e.g., 'Bold', 'Semi Bold'). No-space variants like 'SemiBold' are auto-corrected."),
+    }, async ({ nodeId, text, fontSize, fontFamily, fontStyle }) => {
         try {
             const connector = await getDesktopConnector();
-            const result = await connector.setTextContent(nodeId, text, fontSize ? { fontSize } : undefined);
+            const result = await connector.setTextContent(nodeId, text, fontSize || fontFamily || fontStyle
+                ? { fontSize, fontFamily, fontStyle }
+                : undefined);
             if (!result.success) {
                 throw new Error(result.error || "Failed to set text");
             }

package/dist/cloudflare/index.js

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

package/dist/core/design-code-tools.d.ts.map

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

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

@@ -174,7 +174,7 @@ export function parseComponentDescription(description) {
     for (const line of lines) {
         const trimmed = line.trim();
         // Detect section headers: bold text (**Header**), markdown headers (## Header), or plain text exact matches
-        const markdownHeaderMatch = trimmed.match(/^(?:\*\*|###?\s*)(.+?)(?:\*\*)?$/);
+        const markdownHeaderMatch = trimmed.match(/^(?:\*\*|#{1,6}\s*)(.+?)(?:\*\*)?$/);
         const headerText = markdownHeaderMatch ? markdownHeaderMatch[1].trim().replace(/\*\*/g, "") : null;
         // Check if this is a Figma per-property documentation block (e.g., "Show Left Icon: True – Purpose")
         // These should be routed to "other" to avoid polluting content guidelines and accessibility sections
@@ -1380,7 +1380,47 @@ function buildParityInstruction(componentName, parityScore, counts, canonicalSou
 // ============================================================================
 // Documentation Section Generators
 // ============================================================================
-function generateFrontmatter(componentName, description, node, componentMeta, fileUrl, codeInfo, canonicalSource) {
+/**
+ * Detect the atomic-design level (atom | molecule | organism | template) of a component
+ * by finding its Figma page and walking the ordered page list back to the nearest
+ * section-divider page (e.g. "ATOMS", "MOLECULES", "ORGANISMS"). Returns null when the
+ * file doesn't use atomic-design page sections or the page can't be resolved — callers
+ * then simply omit the `level` frontmatter. Best-effort and never throws.
+ */
+async function detectAtomicLevel(api, fileKey, nodeId, setNodeId, _componentMeta, _allComponentsMeta) {
+    try {
+        const targetId = setNodeId || nodeId;
+        // Resolve the page the component lives on — independent of library-publish
+        // status (published `containing_frame` metadata is empty for many files).
+        // Requesting the file with `ids` returns every page in document order, but
+        // prunes each page's children to only the path reaching the requested node,
+        // so the single page whose subtree still contains the node is its home page.
+        const pages = (await api.getFile(fileKey, { ids: [targetId] }))?.document?.children || [];
+        const contains = (n) => n?.id === targetId || (Array.isArray(n?.children) && n.children.some(contains));
+        const idx = pages.findIndex((p) => contains(p));
+        if (idx < 0)
+            return null;
+        // Walk back to the nearest atomic-design divider page.
+        const LEVELS = [
+            ["ATOM", "atom"],
+            ["MOLECULE", "molecule"],
+            ["ORGANISM", "organism"],
+            ["TEMPLATE", "template"],
+        ];
+        for (let i = idx; i >= 0; i--) {
+            const stripped = (pages[i]?.name || "").toUpperCase().replace(/[^A-Z]/g, "");
+            for (const [marker, level] of LEVELS) {
+                if (stripped.startsWith(marker))
+                    return level;
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+function generateFrontmatter(componentName, description, node, componentMeta, fileUrl, codeInfo, canonicalSource, level) {
     const status = codeInfo?.changelog?.[0]
         ? "stable"
         : componentMeta?.description?.toLowerCase().includes("deprecated")
@@ -1388,6 +1428,8 @@ function generateFrontmatter(componentName, description, node, componentMeta, fi
             : "stable";
     const version = codeInfo?.changelog?.[0]?.version || "1.0.0";
     const tags = [componentName.toLowerCase()];
+    if (level)
+        tags.push(level);
     if (node.type === "COMPONENT_SET")
         tags.push("variants");
     if (node.componentPropertyDefinitions)
@@ -1395,10 +1437,11 @@ function generateFrontmatter(componentName, description, node, componentMeta, fi
     const lines = [
         "---",
         `title: ${componentName}`,
-        `description: ${(description.split(/(?:When to Use|When NOT to Use|Variants|Content Requirements|Accessibility)/i)[0] || description).replace(/\n/g, " ").replace(/\s+/g, " ").trim() || `${componentName} component`}`,
+        `description: ${((description.split(/\n\s*\n|\n#{1,6}\s|\n\*\*/)[0] || description).replace(/\n/g, " ").replace(/\s+/g, " ").trim().split(/(?<=[.!?])\s+/)[0] || `${componentName} component`)}`,
         `status: ${status}`,
         `version: ${version}`,
         `category: components`,
+        ...(level ? [`level: ${level}`] : []),
         `tags: [${tags.join(", ")}]`,
         `figma: ${fileUrl}`,
     ];
@@ -2560,7 +2603,9 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
                     logger.warn("Desktop Bridge fetch failed, proceeding without bridge-sourced data");
                 }
             }
-            const fileUrl_ = `${url}?node-id=${nodeId.replace(":", "-")}`;
+            // Strip any existing query (e.g. the connected file's ?node-id=<page>) before
+            // appending the target node, otherwise the URL ends up with a doubled ?node-id=.
+            const fileUrl_ = `${url.split("?")[0]}?node-id=${nodeId.replace(":", "-")}`;
             // Parse the component description for structured content
             const parsedDesc = parseComponentDescription(description);
             // Determine canonical source
@@ -2589,7 +2634,8 @@ export function registerDesignCodeTools(server, getFigmaAPI, getCurrentUrl, vari
             const parts = [];
             const includedSections = [];
             if (includeFrontmatter) {
-                parts.push(generateFrontmatter(componentName, description, node, componentMeta, fileUrl_, codeInfo, canonicalSource));
+                const atomicLevel = await detectAtomicLevel(api, fileKey, nodeId, setInfo.setNodeId, componentMeta, allComponentsMeta);
+                parts.push(generateFrontmatter(componentName, description, node, componentMeta, fileUrl_, codeInfo, canonicalSource, atomicLevel));
                 parts.push("");
             }
             if (s.overview) {