Onsystem MCP Server

onsystem

Keeps coding agents on your design system: it knows your real components, props, variants and tokens, catches the moment an agent invents one and has it fix it, and the same check gates your PRs. Local, zero config, works alongside @shadcn/lint.

Built for design-system and platform teams with a React design-system package; a shadcn/ui app is the zero-config demo. Formerly @dgesteves/design-system-mcp (what changed).

Using the GitHub Action? uses: dgesteves/onsystem@v0 checks the lines a pull request changed: see CI and baselines.

Also works with

Website and docs: onsystem.vercel.app, with a playground that checks your own code.

https://github.com/user-attachments/assets/900cc1fa-387c-4e76-a524-a818521dd1a0

On the website, an agent drafts a settings card, check_ui finds 11 problems with a fix each, and the agent applies them. Then a real Claude Code session with the plugin: Claude looks the components up before writing, and check_ui passes. Last, the benchmark.

The problem

Coding agents write UI from their training data, not from your design system. Ask for a settings card and you get bg-[#ef4444], p-[13px], a native <button>, variant="danger" on a Button that only has destructive, and <Card.Header> where the system exports CardHeader. On the demo draft above, tsc reports 3 of the 11 problems, and review catches the rest when someone has the time. Describing the design system to the agent helps; what holds is checking what it actually wrote, at the edit and at the pull request.

What it checks

onsystem reads your components, cva and tv variants, parts and tokens from source with the TypeScript compiler, and checks .tsx and .jsx against them. Every finding has a rule id, a location and the fix. Tokens come from your stylesheets, DTCG 2025.10 files or a DESIGN.md, and onsystem export writes them out as either.

How often it is wrong. The corpus job runs check on 12 public repositories pinned by commit (Documenso, Dub, Cal.com, midday, Flowise and others, the four monorepos also from their root, and Dub's app also with a config and with @dub/ui set up by init: 24 runs, 14,541 distinct findings) and compares the findings with labels made by an AI reviewer. Its random sample does not give a false-positive rate for all findings: the runs and rules it has labels for hold 28.0% of them, and 27 of its 30 false positives were fixed, so what is left of it under-counts them. The rate will come from a fresh seeded sample, published here with its confidence interval and who labelled it. Code installed from a shadcn registry, such as the chatbot's components/ai-elements, has no labels yet (Code from shadcn registries). Shipped code rarely invents components, props or variants: those three rules have 56 findings in the corpus, 55 of them in Flowise, an MUI app that passes props and values MUI's components do not take, and the 10 still in the sample are all right. The rules reference shows each rule on an example and how to suppress a finding.

Quickstart

Run it from the app's folder or from the monorepo root, with Node.js 20.19 or later:

npx -y onsystem inspect   # what it found; --explain says why
npx -y onsystem check .   # the same check the agent and CI run
npx -y onsystem init      # write the config, and offer a baseline

At a monorepo root, inspect lists every app and design-system package, and check checks each file by its own project's design system. In a design-system package, init sets it up for every app that depends on it, workspace or npm, with no config in the apps.

In a new create-next-app, the template page's hardcoded colors already make the first check . fail; init offers to record them as a baseline, so only new findings fail. Folders installed from a shadcn registry, such as components/ai-elements, are someone else's code: Code from shadcn registries says how to check them or leave them out.

Claude Code. The plugin brings the hook, the MCP server and a skill:

/plugin marketplace add dgesteves/onsystem
/plugin install onsystem@dgesteves

After each Write or Edit of a .tsx or .jsx file, the hook runs onsystem check on it. Errors go back to Claude as a blocking error with the fix, so Claude corrects the file before it moves on; warnings go as a note. It stays quiet in projects without a design system. What it runs and touches.

Cursor or VS Code. , or commit the config. The agent gets the tools and runs check_ui on what it writes.

Other agents. npx skills add dgesteves/onsystem adds the skill to any agent with Agent Skills, and there are plugins for Codex, GitHub Copilot CLI, VS Code and Cursor.

Any MCP client. Run npx -y onsystem as a stdio server. There are configs for Claude Desktop, Codex CLI, GitHub Copilot CLI, Windsurf, JetBrains IDEs, Zed, Gemini CLI and Grok Build.

CI. Install it as a dev dependency, accept the findings the codebase already has once, and fail pull requests only on new ones:

npm install --save-dev onsystem
npx onsystem check . --update-baseline   # writes onsystem.baseline.json: commit it

- run: npx onsystem check . --format github --require-design-system

Findings show up as annotations on the pull request, and --require-design-system fails the job when the design system is no longer found. CI and baselines has the whole workflow. The GitHub Action, uses: dgesteves/onsystem@v0, annotates only the lines a pull request changed: make it a required check on agent pull requests.

ESLint. The same rules for ESLint 8.57, 9 and 10: add onsystem.configs.recommended from onsystem/eslint to eslint.config.mjs (ESLint plugin, with @shadcn/lint).

Works with @shadcn/lint

@shadcn/lint checks the Tailwind classes written against a component and the theme (restyling, raw colors, arbitrary and unknown classes) as ESLint or Oxlint rules on Tailwind v4. onsystem checks that the components, props and variant values exist, flags native elements and unnamed icon buttons on Tailwind v3 or v4, and in Claude Code catches an invented one right after the edit, so run both.

Does it help?

Benchmark v2 gave 6 models from 3 providers (Anthropic, OpenAI and Google) 20 single-file UI tasks in 5 open-source repositories, without onsystem, with its skill, MCP server or hook, and with all three: 1,200 runs, 240 per arm. Counted by onsystem 0.5.0's own check, design-system errors per run went from 0.85 without onsystem to 0.00 with all three, with no measurable change in the tsc pass rate (93% → 92%).

That count is onsystem's own, and the MCP server and the hook show the agent the same errors to fix. In tasks that ask for a green status label in a design system with no success token, agents with onsystem often used chart-* tokens, which it counts as clean. The blind labels by an AI reviewer, 12 files per arm, are too few to confirm the count either way, and every violation they found with the hook or all three is a palette color in Dub, whose tokens 0.5.0 did not read. The benchmark page has every table, and bench/v2 the method, the per-run data and every generated file.

Docs

On the website, and as Markdown in docs/:

• Quickstart, Claude Code plugin, CI and baselines and Set up your agent, with the config for each client
• Configuration, Rules, MCP tools and Troubleshooting
• How it works, FAQ and Migrating from design-system-mcp

Contributing, security and the changelog are in the repository.

License

MIT © Diogo Esteves