kitsmith

A kit-agnostic MCP server and CLI that makes coding agents build UI from a specific React component kit instead of hand-rolling it.

Agents are bad at building on a given kit in three ways:

1. They don't reach for the kit. Left alone, an agent writes something "in the style of" the kit: a styled div instead of the kit's card, a raw <table> instead of its table, a home-made dialog instead of its modal.

2. When they do use it, they get props wrong: invented props, wrong value types, deprecated API.

3. They don't compose. When no ready-made component exists, they write from scratch instead of composing kit primitives.

kitsmith gives any MCP-capable agent host (Claude Code, Codex, OpenCode, Cursor, ...) tools to find the right component by intent, read its exact props, follow composition recipes, and validate the result. Kit-specific knowledge lives in a per-kit adapter; the core knows nothing about any concrete kit. The first adapter is for Ant Design (antd 6).

Everything runs locally. No network calls at runtime, no telemetry.

The decision ladder

Every UI need is resolved in this order. The rule is repeated in the server instructions, in tool descriptions and in the generated AGENTS.md.

1. An existing kit component fits: use it.

2. Nothing fits: compose it from kit components (a recipe may exist).

3. Still not covered: use an allowed external library listed in the adapter (for example charts or icons).

4. Only then write your own code, and say so.

Hand-rolled code that duplicates case 1 is reported by validate. Cases 2-4 are legitimate and are not flagged.

Related MCP server: UIShelf MCP Server

Quick start

Requires Node 22 or newer. Until the package is published, run it from a clone (npm run build must run first, because dist/cli.js is what agent hosts start):

git clone <this repo> && cd kitsmith
npm install && npm run build

New prototype

node dist/cli.js new demo --adapter adapters/antd --dir ..
cd ../demo && npm run dev

new copies a Vite + React + react-router sandbox with the kit installed, mock-data helpers, AGENTS.md, CLAUDE.md and .mcp.json already wired to kitsmith. When run from a clone, the generated MCP config starts the server with node <clone>/dist/cli.js serve --project ., so build the clone first; once kitsmith is installed from npm it uses npx kitsmith serve --project .. Then open the folder in your agent host and describe the screens you want. .kitsmith/ and the generated .mcp.json server command are machine-local (they hold absolute paths), so keep them out of version control. The project name must be lowercase and npm-safe. If npm install fails, the project is kept and you are told to run npm install yourself (--no-install skips the install step).

Existing project

node dist/cli.js init --adapter adapters/antd --project path/to/project

init adds .mcp.json, AGENTS.md and CLAUDE.md. Existing MCP servers and your own text are preserved; the kitsmith section is added or replaced idempotently. The kit must already be installed in the project (node_modules/<package>), otherwise you get a clear "run npm install" error.

Commands

--adapter can be omitted when the project has .kitsmith/config.json (written by new and init).

validate exit codes: 1 when there are findings, 2 when nothing was found but the check was incomplete (for example a file outside the tsconfig), 0 when clean and complete.

MCP tools

Everything is reachable through tools, so no feature depends on MCP resources, prompts or host-specific skills.

Search understands adapter synonyms, including non-English ones (for example "таблица" finds Table in the antd adapter).

Writing an adapter

An adapter is a directory with a kit.config.ts plus optional content. It is loaded by filesystem path, so it can live anywhere; built-in ones are in adapters/. All relative paths resolve against the adapter directory.

// adapters/antd/kit.config.ts
import type { AdapterConfig } from "../../src/adapter/types.js";

const config: AdapterConfig = {
  name: "antd",
  package: "antd",                 // npm package of the kit
  typesEntry: "es/index.d.ts",     // relative to the package dir
  deprecated: { source: "jsdoc" }, // extra?: string[] marks more components deprecated
  descriptions: "descriptions.yaml", // { [Component]: { description, category } }
  synonyms: "synonyms.yaml",         // { [Component]: string[] }
  detectorRules: "detector-rules.ts",
  tokens: "tokens.ts",
  recipes: "recipes",              // dir of .md files with frontmatter
  guidelines: "guidelines",        // dir of .md files with frontmatter
  allowedExternal: ["@ant-design/charts", "@ant-design/icons"],
  sandbox: {
    overlay: "sandbox",            // files laid over templates/sandbox
    dependencies: { antd: "^6.6.8", "@ant-design/icons": "^6" },
  },
};
export default config;

Only name, package and typesEntry are required. Optional examples is a directory of <Component>.tsx usage examples.

Type imports from the package are not exported yet: external adapters should define the few types they need locally or copy them from src/adapter/types.ts.

Recipes and guidelines

Markdown files with frontmatter; the body is served as-is.

---
title: Filter bar
intents: ["filter bar", "search and filter"]
components: [Space, Input, Select, DatePicker, Button]
---
Use above a list or table to narrow results...

Detector rules

detectorRules is a module whose default export is a factory that receives the rule helpers and returns rules:

export default function rules(h: RuleHelpers): DetectorRule[];

interface DetectorRule {
  id: string;
  suggest: string;      // the kit component to use instead
  description: string;
  rule: Rule.RuleModule; // a regular ESLint rule
}

Helpers (RuleHelpers, from src/validate/rule-helpers.ts):

Rules should stay quiet on legitimate composition and on allowed external libraries; ship negative fixtures for every rule.

Tokens

tokens is a module whose default export receives { projectDir, requireFromProject } and resolves to a plain object of design tokens.

Status

v1 core is implemented: index, intent search, the seven tools, validate, duplicate detector, sandbox, init and new, with the antd adapter.

Verified automatically: unit and integration test suite; a fresh antd prototype created with new installs, builds, and passes validate with no problems; an MCP client lists all seven tools from serve, and find_component resolves a Russian-language intent.

Pending: a manual check with real agent hosts (Claude Code, Codex, OpenCode) on a prompt such as "an orders page with filters, a table, a KPI row and an order details dialog".

Roadmap

• Second open kit (MUI or Mantine) as proof of kit-agnosticism, plus a published benchmark: agent without kitsmith vs with kitsmith across hosts and models (type-check pass rate, invented props, hand-rolled duplicates, kit-usage ratio).

• Stage 2, design reasoning: design standards, a self-critique pass, and several reasoned variants per request.

• Figma layer: map a design tree to kit components, report gaps instead of silently hand-rolling.

License

MIT. Component descriptions in the antd adapter are adapted from the Ant Design documentation (MIT).