ds-crit-mcp

An MCP server that critiques Figma designs against your design system. It flags where a design has drifted from the system, and when the wrong component is being used for the job, and it cites the rule every time.

It reviews; it never generates. No new design output, no autofixing your file. Just a quiet, consistent second opinion inside the AI tools you already use (Claude Code, Cursor, and other MCP clients).

Status: early. The deterministic checks are the trustworthy core. The component-choice checks are advisory and start narrow. Nothing here blocks anyone, by design.

What it catches

Two tiers, with different trust levels:

1. Deterministic checks — objective and code-evaluable (token binding, detached instances, off-scale values). Near-zero false positives.
2. Component-choice checks — semantic judgment ("this Chip is really a Badge"). Advisory. They explain their reasoning and never auto-apply anything.

What it connects to

• The Figma REST API — to read a frame by URL. You supply a Figma personal access token (read scope).
• An MCP client — Claude Code, Cursor, or anything that speaks MCP. It runs locally over stdio (or you can host it over HTTP; see below).
• Your design system (optional but recommended) — a rulebook.json where you list your token names and component library so the checks get sharper. It works out of the box without this; the token-binding, off-scale, and typography checks need no configuration.

Install

Zero runtime dependencies. You need Node 18+.

git clone https://github.com/chuckjob/ds-crit-mcp.git
cd ds-crit-mcp
npm test   # optional smoke test, no token needed

Get a Figma token

Figma → Settings → Security → Personal access tokens → Generate new token (read scope is enough). Then either:

mkdir -p ~/.config && echo "figd_your_token_here" > ~/.config/figma-token

or set FIGMA_TOKEN in the environment. The server reads FIGMA_TOKEN first, then ~/.config/figma-token, so nothing secret needs to live in your client config.

Connect your MCP client

Claude Code:

claude mcp add ds-crit --scope user -- node /absolute/path/to/ds-crit-mcp/src/mcp/server.mjs

Cursor (or any client that uses an mcpServers block — ~/.cursor/mcp.json):

{
  "mcpServers": {
    "ds-crit": {
      "command": "node",
      "args": ["/absolute/path/to/ds-crit-mcp/src/mcp/server.mjs"]
    }
  }
}

Restart the client, and you're set.

Use it

In your AI client:

• "crit this: <figma url>" → runs lint_figma_node (fetches the frame and critiques it).
• "which component should I use for a segmented selector?" → suggest_component.
• "explain token/unbound-fill" → explain_rule.

Tools

profile is design (default — drops the noisiest checks for low-noise critique of a work-in-progress frame) or all (everything).

Make it yours

Open rulebook.json and:

• validTokenRefs — add your design system's token names. (Enables sharper "did you mean <token>?" hints.)
• componentRegistry — add your library's components as { key, name }. This powers the detached-instance and non-library-component checks. Set registryComplete: true only once it covers every library component.
• guards — exempt decorative art, editor chrome, or pages you don't audit (examples included).
• componentChoiceRules / componentCatalog — tune the "which component?" guidance to your library's names.
• Scales — adjust SPACING_PX and RADIUS_PX at the top of src/engine/lint.mjs to your spacing/radius scales.

rulebook.schema.ts documents every field.

Host it over HTTP (optional)

If you'd rather host the server once and point multiple clients at it:

npm run http   # serves MCP at POST /mcp and health at GET /health (PORT=8080)
# or:
docker build -t ds-crit-mcp . && docker run -p 8080:8080 -e FIGMA_TOKEN=figd_... ds-crit-mcp

Findings log (optional)

Every crit appends an aggregate entry — finding types and counts only (e.g. detached-instance ×1), a timestamp, and the opaque Figma keys. Never layer names, messages, design content, or screenshots. Stored at ~/.ds-crit/findings.jsonl (override with DS_CRIT_LOG_DIR; opt out with DS_CRIT_NO_LOG=1).

See your top drift patterns:

npm run report        # last 30 days
node scripts/report.mjs 0   # all time

Use it to prioritize: fix the components behind the most-flagged checks, or add a rule where the same mistake keeps recurring.

How it works

rulebook.json            your design system as data (tokens, components, rules)
      │
      ▼
  engine (pure)  ──►  MCP server (stdio + HTTP)
  lintNode()          lint_figma_node · lint_node · suggest_component · explain_rule · drift_patterns

The engine is a pure function (src/engine/lint.mjs): node tree in, findings out. No Figma or network calls — that lives at the edges (src/mcp/figma.mjs, src/engine/adapter.mjs), which keeps the engine trivially testable.

License

MIT © Chuck Job