@unpunnyfuns/swatchbook-mcp

High-level summary of the project — total token count per theme, axes (with contexts) and how they compose, preset list, diagnostic counts by severity, css-var prefix, and the DTCG `$type`s present. Good first call for an agent that needs an orientation before querying specifics.

Return the full project CSS — a `:root` baseline + per-axis singleton cells (`[data-<prefix>-<axis>="<context>"]`) + compound joint-override blocks for tokens whose value at a multi-axis combination diverges from cascade composition + a trailing chrome alias block. Same output the addon injects into Storybook and the docs-site chrome pipeline writes to disk. Useful when an agent needs to inline the stylesheet into a generated artifact.

List token paths in the project, optionally filtered by path glob (`color.*`, `color.palette.**`) and/or DTCG `$type` (color, dimension, typography, …). Returns path + $type + stringified value from the default theme. Use this first to discover what tokens exist; follow with get_token for details.

Get full details for a single token: resolved value in every theme, DTCG `$type`, `$description`, `$deprecated` (message or `true` when the token is deprecated), an axis-variance summary (`kind` + the axes it flips across, present only when it varies — see `get_axis_variance` for the per-axis breakdown), alias chain, aliased-by list, and CSS var reference. Use after `list_tokens` to inspect a specific path.

List the project axes — each axis has a name, its contexts (discrete values like `Light` / `Dark`), a default, and a source (`resolver` for DTCG-resolver-driven, `layered` for authored layered axes, `synthetic` for single-theme projects). Also returns the named themes (one per default tuple + per-axis non-default singleton + preset) and any presets defined in the project config.

Forward alias chain for a token — the sequence of paths it resolves through on the way to a primitive value (e.g. `color.accent.bg → color.brand.blue.700 → color.palette.blue.700`). Returns the chain per theme because aliases can resolve through different paths per axis context. Empty chain when the token is a primitive (no aliases) or missing.

Backward alias tree for a token — every token that resolves through this path at any depth. Breadth-first walk with cycle protection; `maxDepth` caps recursion (default 6). Empty when nothing aliases the token.

For a color token, return its value rendered in every format the addon toolbar exposes — `hex`, `rgb`, `hsl`, `oklch`, and the raw JSON. Each entry carries an `outOfGamut` flag when the chosen colorspace can't losslessly represent the token (wide-gamut tokens rendered in sRGB, for example). Skips non-color tokens.

Compute the contrast between two color tokens for a given theme. The score is returned under `value`: WCAG 2.1 returns the ratio (1–21) plus AA/AAA pass flags for normal + large text; APCA returns the signed Lc value plus body / large-text / non-text pass flags (absolute-value thresholds 75 / 60 / 45). Use this when reasoning about text legibility, focus-ring visibility, border contrast, etc., without having to reimplement the luminance math in the agent. Per-theme so the same pair can be checked against Light, Dark, High-contrast, etc.

Classify how a token's resolved value depends on the project's axes. Returns `kind` — `constant` (same across every tuple), `single` (varies with exactly one axis, e.g. mode only), or `multi` (varies across two or more axes). Also returns `varyingAxes` / `constantAcrossAxes` plus a `perAxis` breakdown with each context's stringified value (holding other axes at their defaults). Use when reasoning about whether a token is theme-independent, whether a refactor changed an axis dependency, or to confirm that (say) a role token only varies with `contrast`.

Fuzzy search across token paths, `$description`, and stringified values. Case-insensitive, tolerates a single-character typo per term, and accepts out-of-order terms (`"blue palette"` finds `color.palette.blue.500`). Returns matches ranked by relevance with a short snippet pointing at where the match hit. Use when you know what you want but not the exact path. Scopes to a single theme (default: project default).

Resolve the full token map for a given axis tuple. Agent passes a partial tuple (`{ mode: "Dark", brand: "Brand A" }`); any axis omitted — or the whole `tuple` argument itself — falls back to that axis\'s default, so calling with no `tuple` resolves the project default theme. Returns the matching theme name, the complete tuple after filling defaults, and the resolved `{ path: { value, type, aliasOf?, aliasChain? } }` map — effectively "what do all tokens look like if I pin this combination".

CSS var reference + resolved value + HTML data-attribute activation for a token under an optional axis tuple. Tells an agent everything it needs to write a stylesheet or JSX snippet that pins a particular theme combination — `selector` is the compound CSS selector that matches the tuple on `<html>`, `attrs` is the same information as HTML attributes, `cssVar` is the `var(--…)` reference. Tuple defaults to the project default when omitted.

List parser / resolver / validation diagnostics for the project. Each entry carries a severity (`error`, `warn`, `info`), group, message, and optional filename / line / column for locating the issue.