@muloka/figma-console-mcp 0.1.0

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

@@ -0,0 +1,334 @@
+import { z } from "zod";
+import { createChildLogger } from "./logger.js";
+const logger = createChildLogger({ component: "slot-tools" });
+const SLOT_LAYOUT_MODES = ["NONE", "HORIZONTAL", "VERTICAL"];
+const SLOT_CHILD_NODE_TYPES = [
+    "FRAME",
+    "RECTANGLE",
+    "ELLIPSE",
+    "TEXT",
+    "LINE",
+    "POLYGON",
+    "STAR",
+    "VECTOR",
+];
+const preferredValueSchema = z.object({
+    type: z.enum(["COMPONENT", "COMPONENT_SET"]).describe("Type of preferred value"),
+    key: z.string().describe("Component or component set key"),
+});
+/**
+ * Register MCP tools for Figma Slots (open beta).
+ * Requires Desktop Bridge and a Figma Desktop version with SlotNode API support.
+ */
+export function registerSlotTools(server, getDesktopConnector) {
+    server.tool("figma_create_slot", `Create a SlotNode inside a component using createSlot(). Automatically creates a linked SLOT component property named after the slot (renaming the slot renames the property). Slots are freeform drop zones for instance content — more flexible than INSTANCE_SWAP. Works on standalone COMPONENTs and variant COMPONENTs inside a COMPONENT_SET (call once per variant). GRID layout is not allowed on slots. Requires Desktop Bridge.`, {
+        nodeId: z
+            .string()
+            .describe("The COMPONENT node ID to add a slot to"),
+        name: z
+            .string()
+            .optional()
+            .describe("Slot layer name (e.g. 'Content', 'Footer')"),
+        width: z
+            .number()
+            .optional()
+            .describe("Initial slot width in pixels"),
+        height: z
+            .number()
+            .optional()
+            .describe("Initial slot height in pixels"),
+        layoutMode: z
+            .enum(SLOT_LAYOUT_MODES)
+            .optional()
+            .describe("Auto-layout mode for the slot (GRID is not supported)"),
+    }, async ({ nodeId, name, width, height, layoutMode }) => {
+        try {
+            const connector = await getDesktopConnector();
+            const result = await connector.createSlot(nodeId, {
+                name,
+                width,
+                height,
+                layoutMode,
+            });
+            if (!result.success) {
+                throw new Error(result.error || "Failed to create slot");
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            slot: result.slot,
+                            hint: "Use figma_get_slots to inspect slots. Populate instance slots with figma_append_to_slot (not figma_set_instance_properties).",
+                        }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error({ error }, "figma_create_slot failed");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: error instanceof Error ? error.message : String(error),
+                            hint: "Target a COMPONENT node (standalone or a variant inside a COMPONENT_SET). Ensure Figma Desktop supports Slots.",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.tool("figma_get_slots", `List SlotNode children on a component, component set, or instance. Returns slot IDs, names, property keys, dimensions, and current child nodes. Use on instances before figma_append_to_slot to discover slot names/IDs.`, {
+        nodeId: z
+            .string()
+            .describe("COMPONENT, COMPONENT_SET, or INSTANCE node ID"),
+    }, async ({ nodeId }) => {
+        try {
+            const connector = await getDesktopConnector();
+            const result = await connector.getSlots(nodeId);
+            if (!result.success) {
+                throw new Error(result.error || "Failed to get slots");
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ success: true, ...(result.data ?? {}) }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error({ error }, "figma_get_slots failed");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: error instanceof Error ? error.message : String(error),
+                            hint: "Ensure the node is a component or instance with slots, and Desktop Bridge is connected.",
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.tool("figma_append_to_slot", `Add content to a slot on a component instance. Clones sourceNodeId into the slot, or creates a new node (nodeType). SLOT content cannot be set via figma_set_instance_properties — use this tool instead. Widgets, stickies, and raw ComponentNodes cannot be appended to slots.`, {
+        slotId: z
+            .string()
+            .optional()
+            .describe("Direct SlotNode ID (from figma_get_slots)"),
+        instanceId: z
+            .string()
+            .optional()
+            .describe("Instance ID — use with slotName when slotId is unknown"),
+        slotName: z
+            .string()
+            .optional()
+            .describe("Slot layer name on the instance (e.g. 'Content')"),
+        sourceNodeId: z
+            .string()
+            .optional()
+            .describe("Node to clone into the slot (default: clone=true)"),
+        nodeType: z
+            .enum(SLOT_CHILD_NODE_TYPES)
+            .optional()
+            .describe("Create a new node in the slot instead of cloning"),
+        properties: z
+            .record(z.string(), z.union([z.string(), z.number()]))
+            .optional()
+            .describe("Properties for created nodes: name, text, width, height"),
+        clone: z
+            .boolean()
+            .optional()
+            .default(true)
+            .describe("When using sourceNodeId, clone the node (default true). Set false to move."),
+        clearExisting: z
+            .boolean()
+            .optional()
+            .default(false)
+            .describe("Remove existing slot children before appending"),
+    }, async (args) => {
+        try {
+            if (!args.slotId && !(args.instanceId && args.slotName)) {
+                throw new Error("Provide slotId OR (instanceId + slotName)");
+            }
+            if (!args.sourceNodeId && !args.nodeType) {
+                throw new Error("Provide sourceNodeId (clone into slot) or nodeType (create new content)");
+            }
+            const connector = await getDesktopConnector();
+            const result = await connector.appendToSlot(args);
+            if (!result.success) {
+                throw new Error(result.error || "Failed to append to slot");
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            slot: result.slot,
+                            appendedNode: result.appendedNode,
+                            hint: "Use figma_capture_screenshot to verify slot content visually.",
+                        }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error({ error }, "figma_append_to_slot failed");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: error instanceof Error ? error.message : String(error),
+                            hints: [
+                                "Use figma_get_slots on the instance to find slot IDs/names",
+                                "Clone instances or frames — not raw ComponentNodes",
+                                "SLOT properties cannot be set via figma_set_instance_properties",
+                            ],
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.tool("figma_reset_slot", `Reset a slot on a component instance to its default (empty) state from the main component. Uses SlotNode.resetSlot().`, {
+        slotId: z
+            .string()
+            .optional()
+            .describe("Direct SlotNode ID"),
+        instanceId: z
+            .string()
+            .optional()
+            .describe("Instance ID — use with slotName when slotId is unknown"),
+        slotName: z
+            .string()
+            .optional()
+            .describe("Slot layer name on the instance"),
+    }, async ({ slotId, instanceId, slotName }) => {
+        try {
+            if (!slotId && !(instanceId && slotName)) {
+                throw new Error("Provide slotId OR (instanceId + slotName)");
+            }
+            const connector = await getDesktopConnector();
+            const result = await connector.resetSlot({ slotId, instanceId, slotName });
+            if (!result.success) {
+                throw new Error(result.error || "Failed to reset slot");
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            slot: result.slot,
+                        }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error({ error }, "figma_reset_slot failed");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: error instanceof Error ? error.message : String(error),
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    server.tool("figma_add_slot_property", `Manually add a SLOT component property and bind it to an existing frame (alternative to figma_create_slot). The frame must be a direct child of the component, must not use GRID layout, and must not be nested inside another slot. Supports description and preferredValues.`, {
+        nodeId: z.string().describe("COMPONENT or COMPONENT_SET node ID"),
+        propertyName: z.string().describe("Slot property name (e.g. 'Content')"),
+        frameNodeId: z
+            .string()
+            .describe("Frame node ID to bind as the slot content area"),
+        description: z
+            .string()
+            .optional()
+            .describe("Slot property description (SLOT-only)"),
+        preferredValues: z
+            .array(preferredValueSchema)
+            .optional()
+            .describe("Preferred components for slot content (SLOT-only)"),
+    }, async ({ nodeId, propertyName, frameNodeId, description, preferredValues }) => {
+        try {
+            const connector = await getDesktopConnector();
+            const code = `
+const component = await figma.getNodeByIdAsync(${JSON.stringify(nodeId)});
+if (!component || (component.type !== 'COMPONENT' && component.type !== 'COMPONENT_SET')) {
+  throw new Error('Node must be COMPONENT or COMPONENT_SET');
+}
+const frame = await figma.getNodeByIdAsync(${JSON.stringify(frameNodeId)});
+if (!frame || frame.type !== 'FRAME') {
+  throw new Error('frameNodeId must be a FRAME node');
+}
+// For a COMPONENT the frame must be its direct child. For a COMPONENT_SET the
+// property lives on the set but the frame lives inside a variant COMPONENT —
+// accept a frame whose parent is a variant of this set.
+const directChild = frame.parent === component;
+const variantChild = component.type === 'COMPONENT_SET' &&
+  frame.parent && frame.parent.type === 'COMPONENT' && frame.parent.parent === component;
+if (!directChild && !variantChild) {
+  throw new Error(component.type === 'COMPONENT_SET'
+    ? 'Frame must be a direct child of one of the set\\'s variant components'
+    : 'Frame must be a direct child of the component');
+}
+if (frame.layoutMode === 'GRID') {
+  throw new Error('GRID layoutMode is not allowed on slot frames');
+}
+const options = {};
+${description ? `options.description = ${JSON.stringify(description)};` : ""}
+${preferredValues ? `options.preferredValues = ${JSON.stringify(preferredValues)};` : ""}
+const propKey = component.addComponentProperty(${JSON.stringify(propertyName)}, 'SLOT', '', Object.keys(options).length ? options : undefined);
+// Merge — assigning a fresh object would wipe the frame's existing bindings
+// (e.g. a BOOLEAN property driving 'visible').
+frame.componentPropertyReferences = Object.assign({}, frame.componentPropertyReferences, { slotContentId: propKey });
+return { propertyKey: propKey, frameId: frame.id, frameName: frame.name };
+`;
+            const result = await connector.executeCodeViaUI(code, 10000);
+            if (!result.success) {
+                throw new Error(result.error || "Failed to add slot property");
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            success: true,
+                            result: result.result,
+                            hint: "Prefer figma_create_slot() for new slots — it creates the SlotNode and property automatically.",
+                        }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            logger.error({ error }, "figma_add_slot_property failed");
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            error: error instanceof Error ? error.message : String(error),
+                        }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+}

package/dist/cloudflare/core/snippet-injector.js

@@ -0,0 +1,96 @@
+/**
+ * Snippet Injector
+ * Generates and manages console-based data extraction snippets for Figma
+ */
+import { createChildLogger } from './logger.js';
+const logger = createChildLogger({ component: 'snippet-injector' });
+export class SnippetInjector {
+    /**
+     * Generate variables extraction snippet for Figma console
+     */
+    generateVariablesSnippet() {
+        return `
+(async () => {
+  try {
+    const vars = await figma.variables.getLocalVariablesAsync();
+    const collections = await figma.variables.getLocalVariableCollectionsAsync();
+
+    const payload = {
+      timestamp: Date.now(),
+      variables: vars.map(v => ({
+        id: v.id,
+        name: v.name,
+        key: v.key,
+        resolvedType: v.resolvedType,
+        valuesByMode: v.valuesByMode,
+        variableCollectionId: v.variableCollectionId,
+        scopes: v.scopes,
+        description: v.description,
+        hiddenFromPublishing: v.hiddenFromPublishing
+      })),
+      variableCollections: collections.map(c => ({
+        id: c.id,
+        name: c.name,
+        key: c.key,
+        modes: c.modes.map(m => ({ modeId: m.modeId, name: m.name })),
+        defaultModeId: c.defaultModeId,
+        variableIds: c.variableIds
+      }))
+    };
+
+    console.log('[MCP_VARIABLES]', JSON.stringify(payload), '[MCP_VARIABLES_END]');
+    console.log('✅ Variables data captured! Run figma_get_variables({ parseFromConsole: true }) in Claude to retrieve.');
+
+  } catch (error) {
+    console.error('[MCP_VARIABLES_ERROR]', error.message);
+    console.log('❌ Make sure you\\'re running this in a Figma file with variables.');
+  }
+})();
+		`.trim();
+    }
+    /**
+     * Parse variables from console log entry
+     */
+    parseVariablesFromLog(logEntry) {
+        try {
+            // Check for marker
+            if (!logEntry.message.includes('[MCP_VARIABLES]')) {
+                return null;
+            }
+            // Extract JSON from args
+            // The snippet logs: console.log('[MCP_VARIABLES]', JSON.stringify(payload), '[MCP_VARIABLES_END]')
+            // So args[0] is the marker, args[1] is the JSON string
+            const jsonStr = logEntry.args[1] || logEntry.args[0];
+            if (!jsonStr) {
+                throw new Error('No data found in console log');
+            }
+            const data = typeof jsonStr === 'string' ? JSON.parse(jsonStr) : jsonStr;
+            logger.info({
+                variableCount: data.variables?.length || 0,
+                collectionCount: data.variableCollections?.length || 0,
+            }, 'Successfully parsed variables from console log');
+            return {
+                variables: data.variables || [],
+                variableCollections: data.variableCollections || [],
+                timestamp: data.timestamp || Date.now(),
+            };
+        }
+        catch (error) {
+            logger.error({ error }, 'Failed to parse variables from console log');
+            throw new Error(`Failed to parse variables from console log: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Find the most recent variables log entry
+     */
+    findVariablesLog(logs) {
+        // Search in reverse (most recent first)
+        for (let i = logs.length - 1; i >= 0; i--) {
+            const log = logs[i];
+            if (log.message.includes('[MCP_VARIABLES]')) {
+                return log;
+            }
+        }
+        return null;
+    }
+}

package/dist/cloudflare/core/tokens/alias-resolver.js

@@ -0,0 +1,205 @@
+/**
+ * Alias reference resolution and validation.
+ *
+ * DTCG alias references look like `{color.primary}` or `{tier-1.color.blue.500}`.
+ * They can chain (an alias can reference another alias), but cycles are an
+ * error.
+ *
+ * This module:
+ *   - Resolves an alias to its eventual literal value (for formatters that
+ *     can't natively express references — CSS, SCSS, Tailwind).
+ *   - Validates that every alias points to an existing token.
+ *   - Detects cycles.
+ */
+/**
+ * Slugify a set/collection name into the key used for the top-level set
+ * group in DTCG output AND the set-qualifier prefix in alias references
+ * (`{<set-slug>.<path.to.token>}`). Must stay in sync with the DTCG
+ * formatter's group keys so emitted references resolve inside the file.
+ */
+export function slugifySetName(name) {
+    return name
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+}
+/**
+ * Build a lookup map for alias resolution. Every token is indexed under its
+ * set-qualified key (`<set-slug>.<dot.path>` — the same shape the converter
+ * emits in references), and additionally under its bare dot-path
+ * (`color.primary`) when that bare path is unambiguous across sets.
+ *
+ * When two collections both contain the same bare path (e.g. two collections
+ * each defining `color/primary`), the bare key is NOT indexed — resolving a
+ * bare reference to "whichever set was indexed last" is exactly the
+ * cross-collection misresolution bug this guards against. Callers that pass
+ * a `warnings` array get one warning per ambiguous bare path.
+ */
+export function buildTokenIndex(doc, warnings) {
+    const index = new Map();
+    for (const [key, entry] of buildTokenLookup(doc, warnings)) {
+        index.set(key, entry.token);
+    }
+    return index;
+}
+/**
+ * Set-aware variant of buildTokenIndex — identical key scheme and ambiguity
+ * rules (set-qualified keys always; bare-path fallback only when unambiguous
+ * across sets), but each entry carries the owning set's name alongside the
+ * token. buildTokenIndex delegates to this so the two can never drift.
+ */
+export function buildTokenLookup(doc, warnings) {
+    const index = new Map();
+    // barePath → owning entries, used to detect cross-set ambiguity.
+    const bareOwners = new Map();
+    for (const set of doc.sets) {
+        const setKey = slugifySetName(set.name);
+        for (const token of set.tokens) {
+            const bare = token.path.join(".");
+            index.set(`${setKey}.${bare}`, { setName: set.name, token });
+            const owners = bareOwners.get(bare) ?? [];
+            owners.push({ setName: set.name, token });
+            bareOwners.set(bare, owners);
+        }
+    }
+    // Bare-path fallback: only when a path exists in exactly one set, and only
+    // when it doesn't shadow a set-qualified key that's already indexed.
+    for (const [bare, owners] of bareOwners) {
+        if (owners.length === 1) {
+            if (!index.has(bare))
+                index.set(bare, owners[0]);
+        }
+        else if (warnings) {
+            warnings.push(`Token path "${bare}" exists in multiple collections (${owners
+                .map((o) => `"${o.setName}"`)
+                .join(", ")}) — bare alias references to it are ambiguous and will not resolve. Use a set-qualified reference like {${slugifySetName(owners[0].setName)}.${bare}}.`);
+        }
+    }
+    return index;
+}
+/**
+ * Resolve a reference to the path segments of its TARGET token — for
+ * formatters that name-ify aliases (CSS `var(--...)`, SCSS `$...`,
+ * Tokens Studio / SD v3 `{...}` refs). Set-qualified references
+ * (`{set-slug.path.to.token}`) resolve to the target token's own path
+ * (WITHOUT the set qualifier), matching how those formatters name the
+ * target's declaration. Falls back to the raw reference path when the
+ * target isn't in the index (e.g. hand-written bare refs to tokens that
+ * weren't exported).
+ */
+export function referenceTargetPath(reference, index) {
+    const bare = reference.replace(/^\{|\}$/g, "");
+    const target = index.get(bare);
+    if (target)
+        return target.path;
+    return bare.split(".");
+}
+/**
+ * Resolve a single alias reference. Returns the eventual literal value, or
+ * throws if the reference is unresolvable or cyclic.
+ */
+export function resolveReference(reference, mode, index, seen = new Set()) {
+    // Strip the curly braces if present: "{color.primary}" → "color.primary"
+    const path = reference.replace(/^\{|\}$/g, "");
+    if (seen.has(path)) {
+        throw new Error(`[figma-console-mcp] Alias cycle detected: ${[...seen, path].join(" → ")}`);
+    }
+    seen.add(path);
+    const target = index.get(path);
+    if (!target) {
+        throw new Error(`[figma-console-mcp] Unresolvable alias reference: {${path}}`);
+    }
+    // Find the value for the requested mode; fall back to the only mode if
+    // there's just one (alias's target may be single-mode while the source
+    // is multi-mode, or vice versa).
+    const value = target.values[mode] ??
+        (Object.keys(target.values).length === 1
+            ? Object.values(target.values)[0]
+            : undefined);
+    if (!value) {
+        throw new Error(`[figma-console-mcp] Alias {${path}} has no value for mode "${mode}"`);
+    }
+    // Chain: if the target's value is itself an alias, recurse.
+    if (value.reference) {
+        return resolveReference(value.reference, mode, index, seen);
+    }
+    return value;
+}
+/**
+ * Resolve an alias chain to its final literal value, walking through
+ * intermediate alias hops. Returns the final TokenValue (with `literal` set
+ * if resolution succeeded) or `null` if the chain ends at a cross-library
+ * reference / unresolvable target / cycle.
+ *
+ * Used by formatters that can't natively express alias references in their
+ * output (Tailwind v3, TypeScript modules, plain JSON) — those need literal
+ * values at export time.
+ *
+ * Safer counterpart of `resolveReference` because it swallows errors
+ * (unresolvable / cycle) into `null` rather than throwing; formatters can
+ * then emit a comment or skip the token instead of failing the whole export.
+ */
+export function resolveAliasChain(value, mode, index) {
+    if (!value.reference)
+        return value;
+    // Cross-library aliases are not resolvable — formatters should skip with a comment.
+    const bare = value.reference.replace(/^\{|\}$/g, "");
+    if (bare.startsWith("__library:") || bare === "unknown")
+        return null;
+    try {
+        const resolved = resolveReference(value.reference, mode, index);
+        // resolveReference throws on cycles / unresolvable, so a returned value
+        // is either a literal or another reference. If still a reference,
+        // recurse (defensive — resolveReference already chases chains, but the
+        // top-level call may return a value with `reference` if mode-fallback
+        // routes through an aliased entry).
+        if (resolved.reference) {
+            return resolveAliasChain(resolved, mode, index);
+        }
+        return resolved;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Validate every alias in the document. Returns a list of error messages —
+ * empty array means all aliases resolve cleanly.
+ */
+export function validateAliases(doc) {
+    const index = buildTokenIndex(doc);
+    const errors = [];
+    for (const set of doc.sets) {
+        for (const token of set.tokens) {
+            for (const [mode, value] of Object.entries(token.values)) {
+                if (value.reference) {
+                    try {
+                        resolveReference(value.reference, mode, index);
+                    }
+                    catch (err) {
+                        errors.push(`${token.path.join(".")} (mode "${mode}"): ${err instanceof Error ? err.message : String(err)}`);
+                    }
+                }
+            }
+        }
+    }
+    return errors;
+}
+/**
+ * Format an alias reference for DTCG output. DTCG uses `{path.to.token}`
+ * syntax with curly braces.
+ */
+export function formatDtcgReference(referencePath) {
+    return `{${referencePath.join(".")}}`;
+}
+/**
+ * Parse a DTCG alias string back into a path array. Returns null if the
+ * string isn't an alias reference.
+ */
+export function parseDtcgReference(s) {
+    const match = s.match(/^\{([^}]+)\}$/);
+    if (!match)
+        return null;
+    return match[1].split(".");
+}