@mp3wizard/figma-console-mcp 1.25.1 → 1.27.2

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

@@ -0,0 +1,98 @@
+/**
+ * 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.
+ */
+/**
+ * Build a lookup map from dot-path strings (e.g. "color.primary") to Token
+ * objects. Used as the index for resolveAliases().
+ */
+export function buildTokenIndex(doc) {
+    const index = new Map();
+    for (const set of doc.sets) {
+        for (const token of set.tokens) {
+            const key = token.path.join(".");
+            index.set(key, token);
+        }
+    }
+    return index;
+}
+/**
+ * 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;
+}
+/**
+ * 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(".");
+}

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

@@ -0,0 +1,284 @@
+/**
+ * tokens.config.json schema, loader, and autodiscovery for the figma-console-mcp
+ * token sync engine.
+ *
+ * Both figma_export_tokens and figma_import_tokens read this single config so
+ * follow-up calls in a project are zero-arg. Autodiscovery walks up from the
+ * current working directory looking for `tokens.config.json` at each level
+ * — same convention as `tsconfig.json`, `package.json`, `.eslintrc`, etc.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { z } from "zod";
+/**
+ * Schema for a single output target in `tokens.config.json`. Each entry
+ * produces one or more files when figma_export_tokens runs.
+ */
+const OutputTargetSchema = z.object({
+    format: z.enum([
+        "dtcg",
+        "tokens-studio",
+        "css-vars",
+        "tailwind-v4",
+        "tailwind-v3",
+        "scss",
+        "less",
+        "ts-module",
+        "json-flat",
+        "json-nested",
+        "style-dictionary-v3",
+    ]),
+    /** Optional filename override. Default is derived from format + scope. */
+    filename: z.string().optional(),
+    /** Output prefix applied to every token name (e.g. "ds-", "al-"). */
+    prefix: z.string().optional(),
+    /** Emit one file per mode (e.g. tokens-light.css, tokens-dark.css). */
+    splitByMode: z.boolean().optional(),
+    /** Emit one file per token set / Figma collection. */
+    splitByCollection: z.boolean().optional(),
+    /**
+     * If true, alias references are resolved to literal values in the output.
+     * If false, aliases are preserved (default for JSON formats, forced true
+     * for CSS/SCSS/Tailwind/etc. since they can't natively express aliases).
+     */
+    resolveAliases: z.boolean().optional(),
+    /** Per-target transform options. Override the global defaults. */
+    transforms: z
+        .object({
+        colorFormat: z.enum(["hex", "hex8", "rgba", "oklch", "hsl"]).optional(),
+        sizeUnit: z.enum(["px", "rem", "pt", "dp"]).optional(),
+        remBase: z.number().positive().optional(),
+    })
+        .optional(),
+});
+/**
+ * Full schema for `tokens.config.json`. Every field is optional so the
+ * minimum-viable config is `{ "figmaFile": "..." }` — the rest gets sensible
+ * defaults.
+ */
+export const TokensConfigSchema = z
+    .object({
+    /** Optional JSON Schema URL for editor autocompletion. */
+    $schema: z.string().optional(),
+    /**
+     * Figma file URL or fileKey. When omitted, tools fall back to the
+     * currently-connected Desktop Bridge plugin's file (Local Mode) or the
+     * file context bound by figma_pair_plugin (Cloud Mode).
+     */
+    figmaFile: z.string().optional(),
+    /** Where the canonical (committed) token sources live. */
+    source: z
+        .object({
+        /** Directory holding the canonical token files. */
+        dir: z.string(),
+        /** Glob pattern within dir. Default: "*.tokens.json" */
+        pattern: z.string().optional(),
+        /**
+         * Canonical format for source files. DTCG is the recommended default;
+         * Tokens Studio is supported for users who already have a `$themes.json`
+         * setup (e.g. Altitude).
+         */
+        canonical: z.enum(["dtcg", "tokens-studio"]).default("dtcg"),
+    })
+        .default({ dir: "src/styles/tokens", canonical: "dtcg" }),
+    /** Where build outputs (CSS, Tailwind, etc.) get written. */
+    generated: z
+        .object({
+        dir: z.string().default("src/styles/generated"),
+        formats: z.array(OutputTargetSchema).default([]),
+    })
+        .optional(),
+    /** Mode name mappings (Figma mode name → output mode name). */
+    modes: z
+        .object({
+        /** e.g. { "Light": "light", "Dark": "dark" } */
+        map: z.record(z.string()).optional(),
+        /** Default mode if a token has no explicit mode (e.g. "Light"). */
+        default: z.string().optional(),
+    })
+        .optional(),
+    /** Default conflict-resolution strategy when not specified per-call. */
+    conflictResolution: z
+        .enum(["ask", "figma-wins", "code-wins", "skip"])
+        .default("ask"),
+    /** Behavior for tokens that exist on one side but not the other. */
+    sync: z
+        .object({
+        onMissingInCode: z
+            .enum(["preserve", "delete", "warn"])
+            .default("preserve"),
+        onMissingInFigma: z
+            .enum(["preserve", "delete", "warn"])
+            .default("preserve"),
+    })
+        .optional(),
+})
+    .strict();
+/**
+ * Walk up from `startDir` looking for `tokens.config.json`. Returns the first
+ * match, or `null` if none found by the filesystem root.
+ */
+export function findTokensConfig(startDir) {
+    let dir = resolve(startDir);
+    // Hard cap on directory traversal so a misconfigured startDir can't loop
+    // forever (defense against symlinks/weird filesystems).
+    const maxDepth = 32;
+    for (let i = 0; i < maxDepth; i++) {
+        const candidate = join(dir, "tokens.config.json");
+        if (existsSync(candidate)) {
+            return candidate;
+        }
+        const parent = dirname(dir);
+        if (parent === dir) {
+            // Hit filesystem root, no config found.
+            return null;
+        }
+        dir = parent;
+    }
+    return null;
+}
+/**
+ * Load and validate `tokens.config.json`. If `explicitPath` is provided, uses
+ * that; otherwise autodiscovers by walking up from `cwd` (default
+ * `process.cwd()`).
+ *
+ * Returns `null` if no config is found AND no explicit path was given. Throws
+ * if an explicit path doesn't exist, or if the discovered file fails schema
+ * validation.
+ */
+export function loadTokensConfig(opts = {}) {
+    const cwd = opts.cwd ?? process.cwd();
+    const configPath = opts.explicitPath
+        ? resolve(opts.explicitPath)
+        : findTokensConfig(cwd);
+    if (!configPath)
+        return null;
+    if (!existsSync(configPath)) {
+        throw new Error(`[figma-console-mcp] tokens.config.json not found at ${configPath}`);
+    }
+    const raw = readFileSync(configPath, "utf-8");
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new Error(`[figma-console-mcp] tokens.config.json at ${configPath} is not valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    const result = TokensConfigSchema.safeParse(parsed);
+    if (!result.success) {
+        const issues = result.error.issues
+            .map((i) => `  • ${i.path.join(".")}: ${i.message}`)
+            .join("\n");
+        throw new Error(`[figma-console-mcp] tokens.config.json at ${configPath} failed validation:\n${issues}`);
+    }
+    return {
+        config: result.data,
+        configPath,
+        projectRoot: dirname(configPath),
+    };
+}
+/**
+ * Default config used when none is found. Drives the "no-config detected"
+ * response shape from figma_export_tokens — the AI uses this to propose a
+ * scaffold to the user.
+ */
+export const DEFAULT_TOKENS_CONFIG = {
+    source: { dir: "src/styles/tokens", canonical: "dtcg" },
+    generated: {
+        dir: "src/styles/generated",
+        formats: [
+            { format: "css-vars", splitByMode: true },
+        ],
+    },
+    conflictResolution: "ask",
+};
+/**
+ * Build a `suggestedScaffold` payload returned when a tool is called and no
+ * `tokens.config.json` exists. The AI presents this scaffold to the user,
+ * writes the files via its native edit/write tools, then calls the original
+ * tool again.
+ */
+export function buildSuggestedScaffold(opts) {
+    const config = {
+        $schema: "https://figma-console-mcp.southleft.com/schemas/tokens.config.v1.json",
+        source: { dir: "src/styles/tokens", canonical: "dtcg" },
+        generated: {
+            dir: "src/styles/generated",
+            formats: pickStartingFormats(opts.detectedFramework),
+        },
+        conflictResolution: "ask",
+    };
+    const stylesheetImport = pickStylesheetImport(opts.detectedFramework);
+    return {
+        configContent: JSON.stringify(config, null, 2),
+        directories: [config.source.dir, config.generated?.dir ?? "src/styles/generated"],
+        stylesheetImport,
+        nextSteps: [
+            "1. Write `tokens.config.json` at the project root using `configContent`.",
+            `2. Create the directories: ${config.source.dir} and ${config.generated?.dir}.`,
+            `3. Add this line to your main stylesheet:\n     ${stylesheetImport}`,
+            "4. Run `figma_export_tokens` again — it'll pick up the new config and populate the source dir.",
+        ].join("\n"),
+    };
+}
+function pickStartingFormats(framework) {
+    // Always emit DTCG as the canonical committed source; layer the
+    // framework-appropriate runtime format on top.
+    const base = [];
+    switch (framework) {
+        case "tailwind-v4":
+            base.push({ format: "tailwind-v4", splitByMode: true });
+            break;
+        case "tailwind-v3":
+            base.push({ format: "tailwind-v3" });
+            break;
+        case "scss":
+            base.push({ format: "scss", splitByMode: true });
+            break;
+        case "ts":
+            base.push({ format: "ts-module" });
+            base.push({ format: "css-vars", splitByMode: true });
+            break;
+        case "css":
+        default:
+            base.push({ format: "css-vars", splitByMode: true });
+            break;
+    }
+    return base;
+}
+function pickStylesheetImport(framework) {
+    switch (framework) {
+        case "tailwind-v4":
+            return "@import './styles/generated/tailwind.theme.css';";
+        case "scss":
+            return "@use './styles/generated/tokens.scss' as *;";
+        case "ts":
+        case "css":
+        default:
+            return "@import './styles/generated/tokens.css';";
+    }
+}
+/**
+ * Pick the export formats from a loaded config that map to a given runtime
+ * format. Used by figma_export_tokens to decide which generated files to
+ * write. Returns the list verbatim if the caller passed an explicit format.
+ */
+export function resolveOutputTargets(config, explicitFormat) {
+    if (explicitFormat) {
+        // Caller specified a format directly; ignore config's generated list.
+        return [{ format: explicitFormat }];
+    }
+    if (!config?.generated?.formats?.length) {
+        // No formats configured. Default to DTCG only — produces the canonical
+        // source files but no derived runtime outputs.
+        return [{ format: "dtcg" }];
+    }
+    return config.generated.formats;
+}
+/**
+ * Resolve the conflict-resolution strategy. Per-call argument wins over config
+ * default, which wins over the global default ("ask").
+ */
+export function resolveConflictStrategy(config, perCall) {
+    return perCall ?? config?.conflictResolution ?? "ask";
+}

package/dist/cloudflare/core/tokens/figma-converter.js

@@ -0,0 +1,195 @@
+/**
+ * Convert Figma's variables API response into our canonical TokenDocument.
+ *
+ * Input: the shape produced by `formatVariables()` in src/core/figma-api.ts
+ * (an object with `collections` and `variables` arrays, matching either the
+ * REST API's response or the Desktop Bridge plugin's `getLocalVariablesAsync`
+ * normalized payload).
+ *
+ * Output: a TokenDocument with one TokenSet per collection, paths derived
+ * from Figma variable names (slash-separated → path arrays), values
+ * normalized to our TokenValue shape, and Figma IDs preserved in
+ * $extensions["figma-console-mcp"] for round-trip non-destructiveness.
+ */
+/**
+ * Convert a Figma variables payload to our canonical TokenDocument.
+ */
+export function convertFigmaVariablesToDocument(payload, opts = {}) {
+    const warnings = [];
+    // Build a variable index for alias resolution: variableId → variable
+    const variableById = new Map();
+    for (const v of payload.variables)
+        variableById.set(v.id, v);
+    // Filter collections per scope.
+    const wantedCollections = opts.collectionIds?.length
+        ? payload.collections.filter((c) => opts.collectionIds.includes(c.id))
+        : payload.collections;
+    const sets = wantedCollections.map((collection) => convertCollection(collection, payload.variables, variableById, opts, warnings));
+    return {
+        document: {
+            $schema: "https://figma-console-mcp.southleft.com/schemas/dtcg-extended-v1.json",
+            sets,
+            meta: {
+                figmaFileKey: opts.figmaFileKey,
+                exportedAt: opts.exportedAt ?? new Date().toISOString(),
+                mcpVersion: opts.mcpVersion,
+            },
+        },
+        warnings,
+    };
+}
+function convertCollection(collection, allVariables, variableById, opts, warnings) {
+    // Mode filter: keep only modes the caller wants, intersected with what
+    // the collection actually has.
+    const wantedModes = !opts.modes || opts.modes === "all"
+        ? collection.modes
+        : collection.modes.filter((m) => opts.modes.includes(m.name));
+    // Variables in this collection.
+    const collectionVars = allVariables.filter((v) => v.variableCollectionId === collection.id);
+    const tokens = collectionVars.map((variable) => convertVariable(variable, wantedModes, variableById, opts, warnings));
+    return {
+        name: collection.name,
+        modes: wantedModes.map((m) => m.name),
+        tokens,
+        meta: {
+            figmaCollectionId: collection.id,
+        },
+    };
+}
+function convertVariable(variable, wantedModes, variableById, opts, warnings) {
+    // Derive the hierarchical path from the Figma variable name. Figma uses
+    // slashes to indicate grouping: "color/brand/primary" → ["color", "brand", "primary"].
+    let name = variable.name;
+    if (opts.stripPrefix && name.startsWith(opts.stripPrefix)) {
+        name = name.slice(opts.stripPrefix.length);
+    }
+    const path = name.split("/").filter(Boolean);
+    // Map resolvedType to TokenType.
+    const type = mapResolvedType(variable.resolvedType, variable.name, warnings);
+    // Convert each (mode → value) pair to our TokenValue shape, filtered by
+    // the wanted modes.
+    const values = {};
+    for (const mode of wantedModes) {
+        const rawValue = variable.valuesByMode[mode.modeId];
+        if (rawValue === undefined) {
+            warnings.push(`Variable "${variable.name}" has no value for mode "${mode.name}" (${mode.modeId}); skipping that mode.`);
+            continue;
+        }
+        values[mode.name] = convertValue(rawValue, variable.resolvedType, variableById, warnings);
+    }
+    return {
+        path,
+        type,
+        description: variable.description || undefined,
+        values,
+        extensions: {
+            "figma-console-mcp": {
+                variableId: variable.id,
+                collectionId: variable.variableCollectionId,
+                lastSyncedAt: new Date().toISOString(),
+                // We snapshot the synced value so future merge calls can detect
+                // two-sided conflicts.
+                lastSyncedValue: { ...values },
+            },
+        },
+    };
+}
+function mapResolvedType(resolvedType, variableName, warnings) {
+    switch (resolvedType) {
+        case "COLOR":
+            return "color";
+        case "FLOAT":
+            // Figma FLOAT covers both pure numbers and dimensions. We default to
+            // "dimension" because the typical FLOAT variable represents spacing,
+            // sizing, or radius — all dimensions. A future enhancement could
+            // sniff the variable name (e.g. "opacity/*" → "number") for better
+            // type fidelity.
+            return inferFloatType(variableName);
+        case "STRING":
+            return inferStringType(variableName);
+        case "BOOLEAN":
+            return "boolean";
+        default: {
+            const _exhaustive = resolvedType;
+            warnings.push(`Unknown resolvedType "${_exhaustive}" for variable "${variableName}"; treating as string.`);
+            return "string";
+        }
+    }
+}
+function inferFloatType(variableName) {
+    const lower = variableName.toLowerCase();
+    if (lower.includes("opacity") || lower.includes("alpha"))
+        return "number";
+    if (lower.includes("font-weight") || lower.includes("weight"))
+        return "fontWeight";
+    if (lower.includes("duration") || lower.includes("delay"))
+        return "duration";
+    // Default: treat numeric variables as dimensions (px values).
+    return "dimension";
+}
+function inferStringType(variableName) {
+    const lower = variableName.toLowerCase();
+    if (lower.includes("font-family") || lower.includes("font/family"))
+        return "fontFamily";
+    return "string";
+}
+function convertValue(rawValue, resolvedType, variableById, warnings) {
+    // Alias references: convert variable ID → path-based reference for DTCG.
+    if (isVariableAlias(rawValue)) {
+        const target = variableById.get(rawValue.id);
+        if (!target) {
+            // Cross-library alias — target is in a published library this file
+            // consumes, not in the local variable set. Preserve the original
+            // Figma variable ID in the reference syntax so round-trip can
+            // recover it AND formatters can detect this is unresolvable (vs a
+            // genuine local-path alias).
+            warnings.push(`Alias to unknown variable ID ${rawValue.id} (likely a cross-library reference). Original ID preserved in reference for round-trip.`);
+            return { reference: `{__library:${rawValue.id}}` };
+        }
+        // The DTCG alias path uses dots: "color.brand.primary".
+        const dotPath = target.name.replace(/\//g, ".");
+        return { reference: `{${dotPath}}` };
+    }
+    // Literal values per type.
+    if (resolvedType === "COLOR") {
+        if (typeof rawValue === "object" && rawValue !== null && "r" in rawValue) {
+            return { literal: rgbaToHex(rawValue) };
+        }
+        warnings.push(`COLOR value isn't an RGB object: ${JSON.stringify(rawValue)}`);
+        return { literal: String(rawValue) };
+    }
+    if (resolvedType === "FLOAT") {
+        return { literal: typeof rawValue === "number" ? rawValue : Number(rawValue) };
+    }
+    if (resolvedType === "BOOLEAN") {
+        return { literal: Boolean(rawValue) };
+    }
+    // STRING and fallthrough.
+    return { literal: typeof rawValue === "string" ? rawValue : String(rawValue) };
+}
+function isVariableAlias(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "type" in value &&
+        value.type === "VARIABLE_ALIAS");
+}
+/**
+ * Convert Figma's `{r, g, b, a}` floats (0–1 range) to a hex string. Returns
+ * `#RRGGBB` when alpha is 1 (or absent), `#RRGGBBAA` when alpha < 1.
+ */
+function rgbaToHex(rgba) {
+    const r = clampByte(rgba.r);
+    const g = clampByte(rgba.g);
+    const b = clampByte(rgba.b);
+    const a = rgba.a ?? 1;
+    const hex = `#${byteToHex(r)}${byteToHex(g)}${byteToHex(b)}`;
+    if (a >= 1)
+        return hex;
+    return `${hex}${byteToHex(clampByte(a))}`;
+}
+function clampByte(f) {
+    return Math.max(0, Math.min(255, Math.round(f * 255)));
+}
+function byteToHex(byte) {
+    return byte.toString(16).padStart(2, "0").toUpperCase();
+}