@mp3wizard/figma-console-mcp 1.25.1 → 1.28.2

package/dist/cloudflare/core/identity.js

@@ -0,0 +1,96 @@
+/**
+ * Server identity helpers.
+ *
+ * When a user has multiple Figma-related MCP servers configured at once
+ * (e.g. figma-console-mcp alongside Figma's native codegen MCP), an LLM can
+ * conflate errors from one server with the troubleshooting copy of another —
+ * producing remediation advice that points at the wrong tool. Tagging our
+ * responses with an explicit `[figma-console-mcp]` prefix and an `_mcp`
+ * field makes attribution unambiguous.
+ */
+export const MCP_NAME = "figma-console-mcp";
+export const ERROR_PREFIX = `[${MCP_NAME}]`;
+/**
+ * Prefix a thrown-error message with our MCP identity so cross-tool errors
+ * can't be mistakenly attributed to this server.
+ */
+export function identifiedError(message) {
+    return new Error(`${ERROR_PREFIX} ${message}`);
+}
+/**
+ * Tag a response payload with our MCP identity at the top level.
+ * The `_mcp` field is read by LLMs alongside the rest of the response and
+ * gives them a reliable signal for "which server produced this output".
+ */
+export function withIdentity(data) {
+    return { _mcp: MCP_NAME, ...data };
+}
+/**
+ * Tag every text/JSON content block in a tool response with our MCP identity.
+ * Idempotent — already-tagged content (from adaptiveResponse or explicit
+ * withIdentity calls) is left alone. Non-JSON text content is left alone.
+ */
+function tagToolResponse(result) {
+    if (!result ||
+        typeof result !== "object" ||
+        !("content" in result) ||
+        !Array.isArray(result.content)) {
+        return result;
+    }
+    const r = result;
+    const newContent = r.content.map((item) => {
+        if (item.type !== "text" || typeof item.text !== "string")
+            return item;
+        try {
+            const parsed = JSON.parse(item.text);
+            if (parsed &&
+                typeof parsed === "object" &&
+                !Array.isArray(parsed) &&
+                !("_mcp" in parsed)) {
+                return { ...item, text: JSON.stringify({ _mcp: MCP_NAME, ...parsed }) };
+            }
+        }
+        catch {
+            // Not JSON — leave the text untouched (e.g. AI instruction blocks
+            // emitted by adaptiveResponse, or plain-text error messages).
+        }
+        return item;
+    });
+    return { ...r, content: newContent };
+}
+/**
+ * Monkey-patch an MCP server instance so every tool registered on it gets
+ * identity tagging applied to its responses and an identity prefix on any
+ * Error it throws — without modifying the ~97 individual tool handlers.
+ *
+ * Call this once, immediately after constructing the McpServer, BEFORE any
+ * tool registration calls run. The wrap is idempotent at the response level
+ * (tools that already tag themselves via withIdentity or adaptiveResponse
+ * won't get double-tagged).
+ *
+ * Adds attribution coverage to every response path uniformly — see
+ * project_lauren_cross_mcp_confusion for why this matters.
+ */
+export function wrapServerForIdentity(server) {
+    const target = server;
+    const originalTool = target.tool.bind(target);
+    target.tool = function (...args) {
+        if (args.length === 0 || typeof args[args.length - 1] !== "function") {
+            return originalTool(...args);
+        }
+        const handler = args[args.length - 1];
+        const wrappedHandler = async (...handlerArgs) => {
+            try {
+                const result = await handler(...handlerArgs);
+                return tagToolResponse(result);
+            }
+            catch (err) {
+                if (err instanceof Error && !err.message.startsWith(ERROR_PREFIX)) {
+                    err.message = `${ERROR_PREFIX} ${err.message}`;
+                }
+                throw err;
+            }
+        };
+        return originalTool(...args.slice(0, -1), wrappedHandler);
+    };
+}

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

@@ -0,0 +1,135 @@
+/**
+ * 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;
+}
+/**
+ * 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(".");
+}

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";
+}