Design system MCP

What it is

@reva/design-system-mcp is an in-repo MCP (Model Context Protocol) server — a CLI for the design language that coding agents speak directly. It gives an agent working inside this monorepo precise, token-cheap answers about the design system, lints code against the system's rules, and (for tokens) authors the DTCG source for you.

It's organised as three independent pillars:

Each pillar loads independently and fails open — if one isn't available, the others keep working.

It's already on

The server is registered for the whole monorepo — there's nothing to install. Each editor reads a different config file:

Both files carry the same server entry:

{
  "mcpServers": {
    "design-system": {
      "command": "bun",
      "args": ["packages/design-system-mcp/src/index.ts"]
    }
  }
}

In Claude Code, run /mcp to see the design-system server and its tools listed (they appear to the model as mcp__design-system__*). In Cursor, open Settings → MCP — you should see design-system under Workspace MCP Servers. Toggle it off and on (or restart Cursor) if it doesn't connect on first open.

Build prerequisites

The server reads from the same build artifacts the rest of the system produces. Run these once (and after the relevant sources change):

If a tool replies with an actionable "cache not built" message, that's the cue to run the matching command above — it never errors out, it tells you exactly what to build.

The tools

The server exposes twelve tools, grouped by pillar.

Tokens — read

Audit — read + compute

audit and usage_report run the token rules (color-literal, raw-tailwind-scale, raw-stop-vs-role, arbitrary-value) alongside the eight component rules (layout-primitive, typography-tag, icon-import, row-as-item, bespoke-vs-primitive, variant-conformance, uppercase-eyebrow, cardcontent-padding).

The audit also gates CI + pre-commit

The audit engine runs outside the MCP as a CLI too, so adherence is enforced deterministically — no agent required:

bun run audit:design                    # audit the default consumer surfaces (apps, prototypes)
bun run audit:design apps/foo/Bar.tsx   # audit specific files (e.g. a changed-files list)

CI runs it over the .tsx a PR changes and blocks on error-severity findings (off-palette colours, hex literals, non-Phosphor icons); the husky pre-commit audits staged UI files best-effort. Warnings — e.g. uppercase-eyebrow, cardcontent-padding — print but don't block. The MCP audit tool is the interactive path; the CLI is the gate; both share one rule set.

Tokens — author (write)

Components — read

Examples — read

Getting the best out of it

The win is asking the system instead of guessing a class name or hand-editing JSON. Talk to your agent in plain language — it picks the right tool. A few patterns:

Audit before you commit — CI already does. The CI gate and husky pre-commit run these rules automatically (blocking on errors), but pointing audit at your diff interactively surfaces off-system colours, raw <div className="flex …">, raw <p>/<h*> typography, non-Phosphor icon imports, all-caps eyebrows, CardContent padding, and invalid cva variant values earlier — before CI flags them.

Prefer the tools over manual edits. Reach for set_token instead of hand-editing token JSON, and get_component_examples instead of guessing an API — the tools carry the invariants you'd otherwise have to remember.

Guarantees & caveats

The authoring (write) tools are deliberately conservative:

• Validated against the real lint gate. Every write is checked by the actual @reva/design-tokens lint gate, run on a temporary copy of the token tree. On any failure the write aborts untouched and returns the gate's own messages — with the temp-copy paths re-rooted back to the real packages/design-tokens/src/… source so you know which file to fix.
• Minimal, hook-stable diffs. The committed token sources are kept in the writer's canonical format (which Biome leaves byte-identical), so a one-token set_token adds just that token's lines instead of reformatting the whole file — and the pre-commit biome check is a no-op on the change.
• Path-validated. A malformed dot-path (traversal like color.x/../evil, empty or whitespace segments) is rejected before anything is touched.
• Atomic. Writes are tmp-then-rename — no half-written files.
• Never auto-commits. The tools mutate the source on disk; git stays yours. Review the diff and commit when you're ready.
• Light/dark parity is preserved, and the palette-generator-owned src/core/foundation/colors.json is off-limits — a write targeting it is rejected with a pointer to scripts/gen-palettes.ts.
• rename_node / remove_node report code consumers but never rewrite app code — you stay in control of the call sites.

How it relates to the rules

The design system already ships conventions for agents — the AGENTS.md baseline, the per-package rules, and the reva-design-system-adherence skill. Those describe what on-brand looks like. The MCP server is how an agent checks and authors it: the same rules, made executable and queryable. Use the rules to set the defaults, and the server to look things up, lint against them, and write tokens without leaving the conversation.