@mp3wizard/figma-console-mcp 1.25.1 → 1.27.2

package/dist/core/tokens/types.d.ts

@@ -0,0 +1,228 @@
+/**
+ * Canonical internal token model for figma-console-mcp's token sync engine.
+ *
+ * Every parser (DTCG, Tokens Studio, CSS vars, Tailwind, etc.) produces this
+ * shape. Every formatter (DTCG, CSS vars, Tailwind v4, SCSS, TS, etc.) consumes
+ * this shape. Keeps the engine fan-out clean: N parsers + M formatters means
+ * N + M modules, not N * M conversion pairs.
+ *
+ * Aligned with the DTCG (Design Tokens Community Group) W3C spec where
+ * possible — see https://tr.designtokens.org/format/ — but the internal model
+ * is richer because it carries Figma metadata, multi-mode values per-token,
+ * and our $extensions for round-trip ID preservation.
+ */
+/**
+ * The DTCG-aligned set of token types. Maps directly to `$type` in DTCG output.
+ * Composite types (typography, shadow, gradient, etc.) have structured `$value`
+ * objects; primitive types have scalar values.
+ */
+export type TokenType = "color" | "dimension" | "fontFamily" | "fontWeight" | "duration" | "cubicBezier" | "number" | "string" | "boolean" | "shadow" | "typography" | "gradient" | "border" | "transition" | "strokeStyle";
+/**
+ * The DTCG composite token value shapes. Used inside TokenValue.literal when
+ * the token type is composite.
+ */
+export interface TypographyValue {
+    fontFamily: string | string[];
+    fontSize: string | number;
+    fontWeight: string | number;
+    lineHeight?: string | number;
+    letterSpacing?: string | number;
+}
+export interface ShadowValue {
+    color: string;
+    offsetX: string | number;
+    offsetY: string | number;
+    blur: string | number;
+    spread?: string | number;
+    inset?: boolean;
+}
+export interface GradientStop {
+    color: string;
+    position: number;
+}
+export interface GradientValue {
+    type: "linear" | "radial" | "conic";
+    angle?: number;
+    stops: GradientStop[];
+}
+export interface BorderValue {
+    color: string;
+    width: string | number;
+    style: string;
+}
+export interface TransitionValue {
+    duration: string | number;
+    timingFunction: string | number[];
+    delay?: string | number;
+}
+/**
+ * A single token value. Either a literal (primitive scalar or composite object)
+ * or an alias reference to another token by its dot-path.
+ *
+ * Examples:
+ *   { literal: "#4085F2" }                       // primitive color
+ *   { reference: "color.primitive.blue.500" }    // alias
+ *   { literal: { fontFamily: "Inter", ... } }    // composite typography
+ */
+export interface TokenValue {
+    literal?: string | number | boolean | TypographyValue | ShadowValue | ShadowValue[] | GradientValue | BorderValue | TransitionValue | Record<string, unknown>;
+    reference?: string;
+}
+/**
+ * Our vendor namespace inside DTCG $extensions. Survives round-trip through
+ * any DTCG-compliant tool that preserves $extensions verbatim (Style
+ * Dictionary v4, Tokens Studio, Figma's announced 2026 native export, etc).
+ *
+ * The presence of `variableId` is what makes diff-aware merge non-destructive:
+ * renames on either side don't create duplicates because the ID is the
+ * primary match key.
+ */
+export interface FigmaMcpExtensions {
+    /** Figma variable ID (`VariableID:1234:5678`). Survives renames. */
+    variableId?: string;
+    /** Figma collection ID. Used to route the variable to the right collection. */
+    collectionId?: string;
+    /**
+     * The value(s) that were synced to/from Figma the last time this tool ran.
+     * Used to detect true two-sided conflicts: if BOTH the current Figma value
+     * and the current code value differ from this, we don't have a clean winner.
+     */
+    lastSyncedValue?: Record<string, TokenValue>;
+    /** ISO timestamp of the last successful sync for this token. */
+    lastSyncedAt?: string;
+}
+/**
+ * A single design token in our internal model. Carries enough information to
+ * round-trip through Figma without losing identity, name, type, value, modes,
+ * description, or vendor extensions.
+ */
+export interface Token {
+    /**
+     * Hierarchical path, e.g. ["color", "primary"] or
+     * ["typography", "heading", "1"]. Joined with "/" for display and most
+     * output formats. Joined with "." for DTCG alias references.
+     */
+    path: string[];
+    /** DTCG-aligned token type. */
+    type: TokenType;
+    /** Optional human-readable description (DTCG `$description`). */
+    description?: string;
+    /**
+     * Map of mode name → value. Single-mode tokens have one entry. Multi-mode
+     * tokens (typically theme tokens) have one entry per mode.
+     *
+     * Mode names match the corresponding Figma collection's mode names by
+     * default; can be remapped via tokens.config.json's modes.map.
+     */
+    values: Record<string, TokenValue>;
+    /**
+     * Vendor extensions. Our own metadata lives under
+     * `extensions["figma-console-mcp"]`. We preserve other vendors' extensions
+     * verbatim during round-trip (e.g. `studio.tokens` from Tokens Studio).
+     */
+    extensions?: Record<string, unknown> & {
+        "figma-console-mcp"?: FigmaMcpExtensions;
+    };
+}
+/**
+ * A grouping of related tokens. Maps 1:1 to a Figma variable collection.
+ *
+ * Examples: a "Primitives" set with raw color/spacing primitives; a "Semantic"
+ * set with aliases to primitives; a "Theme" set with light/dark mode values.
+ */
+export interface TokenSet {
+    /** Display name. Maps to the Figma collection name. */
+    name: string;
+    description?: string;
+    /**
+     * Mode names in this set. Single-mode sets use a single mode (typically
+     * "Default" or "Value"). Multi-mode sets list each mode (e.g.
+     * ["Light", "Dark"]).
+     */
+    modes: string[];
+    tokens: Token[];
+    /** Set-level metadata. */
+    meta?: {
+        /** Figma collection ID. Set on first sync, used as primary match key. */
+        figmaCollectionId?: string;
+        /**
+         * Source files that contributed tokens to this set. Used by formatters
+         * that emit one-file-per-set to derive output filenames, and by parsers
+         * to track provenance for conflict reporting.
+         */
+        sourceFiles?: string[];
+    };
+}
+/**
+ * The top-level container that export produces and import consumes. Holds
+ * one or more TokenSets plus file-level metadata.
+ */
+export interface TokenDocument {
+    /**
+     * Format identifier. Helps consumers detect our extended DTCG output
+     * (where we stash Figma IDs in $extensions) vs vanilla DTCG.
+     */
+    $schema?: "https://tr.designtokens.org/format/" | "https://figma-console-mcp.southleft.com/schemas/dtcg-extended-v1.json";
+    sets: TokenSet[];
+    meta?: {
+        /** Figma file key the document was exported from. */
+        figmaFileKey?: string;
+        /** ISO timestamp the document was generated/parsed. */
+        exportedAt?: string;
+        /** MCP version that produced/parsed the document. */
+        mcpVersion?: string;
+    };
+}
+/**
+ * The strategies both tools accept. Mirrored on export and import sides for
+ * predictability — same name, same semantic, opposite direction.
+ */
+export type SyncStrategy = "merge" | "replace" | "dry-run";
+/**
+ * How to resolve true two-sided conflicts (both Figma and code changed the
+ * same token since last sync).
+ */
+export type ConflictResolution = 
+/** Surface the conflict to the AI/user, write nothing. */
+"ask"
+/** Figma's value wins, code gets overwritten. */
+ | "figma-wins"
+/** Code's value wins, Figma gets overwritten. */
+ | "code-wins"
+/** Skip the conflicted token, continue with the rest. */
+ | "skip";
+/**
+ * Diff result for a single token. Produced by the matcher, consumed by the
+ * applier and the dry-run reporter.
+ */
+export interface TokenDiff {
+    path: string[];
+    /** How the match was made — used for diagnostics and conflict explanation. */
+    matchedBy: "id" | "path" | "none";
+    /** What action the merge engine recommends. */
+    action: "create" | "update" | "rename" | "delete" | "no-op" | "conflict" | "preserve-other-side";
+    /** The token from the "left" side of the diff (typically Figma on export). */
+    before?: Token;
+    /** The token from the "right" side of the diff (typically code on export). */
+    after?: Token;
+    /** For conflicts: the last-synced value that diverged. */
+    lastSynced?: Record<string, TokenValue>;
+    /** Human-readable reason for the action, used in dry-run output. */
+    reason?: string;
+}
+/**
+ * Output formats supported by figma_export_tokens. Listed in priority order
+ * — earlier formats are the canonical/primary outputs.
+ */
+export type ExportFormat = "dtcg" | "tokens-studio" | "css-vars" | "tailwind-v4" | "tailwind-v3" | "scss" | "less" | "ts-module" | "json-flat" | "json-nested" | "style-dictionary-v3";
+/**
+ * Input formats supported by figma_import_tokens. `auto` triggers detection
+ * from payload structure or file extension.
+ */
+export type ImportFormat = "auto" | "dtcg" | "tokens-studio" | "css-vars" | "tailwind-v4" | "tailwind-v3-config" | "scss" | "style-dictionary-v3" | "json-flat" | "json-nested";
+/**
+ * Identifier returned in MCP-tagged responses so callers know which vendor
+ * extensions namespace to read.
+ */
+export declare const FIGMA_MCP_EXTENSION_KEY: "figma-console-mcp";
+//# sourceMappingURL=types.d.ts.map

package/dist/core/tokens/types.d.ts.map

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

package/dist/core/tokens/types.js

@@ -0,0 +1,19 @@
+/**
+ * Canonical internal token model for figma-console-mcp's token sync engine.
+ *
+ * Every parser (DTCG, Tokens Studio, CSS vars, Tailwind, etc.) produces this
+ * shape. Every formatter (DTCG, CSS vars, Tailwind v4, SCSS, TS, etc.) consumes
+ * this shape. Keeps the engine fan-out clean: N parsers + M formatters means
+ * N + M modules, not N * M conversion pairs.
+ *
+ * Aligned with the DTCG (Design Tokens Community Group) W3C spec where
+ * possible — see https://tr.designtokens.org/format/ — but the internal model
+ * is richer because it carries Figma metadata, multi-mode values per-token,
+ * and our $extensions for round-trip ID preservation.
+ */
+/**
+ * Identifier returned in MCP-tagged responses so callers know which vendor
+ * extensions namespace to read.
+ */
+export const FIGMA_MCP_EXTENSION_KEY = "figma-console-mcp";
+//# sourceMappingURL=types.js.map

package/dist/core/tokens/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/core/tokens/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAiSH;;;GAGG;AACH,MAAM,CAAC,MAAM,uBAAuB,GAAG,mBAA4B,CAAC"}

package/dist/core/tokens-tools.d.ts

@@ -0,0 +1,42 @@
+/**
+ * MCP tool registrar for figma_export_tokens and figma_import_tokens.
+ *
+ * Current scope (v1.27.0):
+ *   - figma_export_tokens: working for DTCG JSON (canonical) and CSS
+ *     custom properties output. Other formats (Tailwind v4, SCSS, TS
+ *     module, Tokens Studio, Style Dictionary v3) are scaffolded and
+ *     return TokenFormatNotImplementedError with a helpful message
+ *     directing users to DTCG.
+ *   - figma_import_tokens: working for DTCG JSON input with full
+ *     diff-aware merge. Apply phase pushes value updates (toUpdate) to
+ *     Figma via the plugin bridge — verified end-to-end against real
+ *     multi-mode design systems. toCreate / toDelete / alias-target
+ *     updates surface in the diff plan but are not yet wired through
+ *     the apply phase (use figma_setup_design_tokens /
+ *     figma_batch_create_variables / figma_delete_variable manually for
+ *     those for now).
+ *
+ * Both tools auto-discover `tokens.config.json` at the project root and use
+ * its source/generated/modes/conflictResolution settings as defaults. They
+ * stay zero-arg in normal use.
+ */
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export interface RegisterTokensToolsOptions {
+    /**
+     * True when registering in Cloud Mode (Cloudflare Workers). In Cloud Mode
+     * the MCP server has no local filesystem access, so the tools surface a
+     * clear "inline payload required" error instead of letting an fs ENOENT
+     * bubble up cryptically. Export still works with explicit content return;
+     * import still works with inline payload/files. tokens.config.json
+     * autodiscovery, outputPath disk writes, and config-source file reads
+     * are all Local Mode only.
+     */
+    isRemoteMode?: boolean;
+}
+export declare function registerExportTokensTool(server: McpServer, getDesktopConnector: () => Promise<any>, opts?: RegisterTokensToolsOptions): void;
+export declare function registerImportTokensTool(server: McpServer, getDesktopConnector: () => Promise<any>, opts?: RegisterTokensToolsOptions): void;
+/**
+ * Convenience: register both tools at once.
+ */
+export declare function registerTokensTools(server: McpServer, getDesktopConnector: () => Promise<any>, opts?: RegisterTokensToolsOptions): void;
+//# sourceMappingURL=tokens-tools.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tokens-tools.d.ts","sourceRoot":"","sources":["../../src/core/tokens-tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAWH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AA6CzE,MAAM,WAAW,0BAA0B;IACzC;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,SAAS,EACjB,mBAAmB,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,EACvC,IAAI,GAAE,0BAA+B,GACpC,IAAI,CAyBN;AAED,wBAAgB,wBAAwB,CACtC,MAAM,EAAE,SAAS,EACjB,mBAAmB,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,EACvC,IAAI,GAAE,0BAA+B,GACpC,IAAI,CAyBN;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,SAAS,EACjB,mBAAmB,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,EACvC,IAAI,GAAE,0BAA+B,GACpC,IAAI,CAGN"}