AI-assisted development

Every Cassa UI scaffold ships the context an AI coding assistant needs to use the components correctly — conventions it reads automatically, a machine-readable index of every export, and an optional MCP server that turns all of it into live tools.

AGENTS.md

A curated conventions file at the project root. Cursor, Claude Code, and Copilot read it on open — token utility classes only, dark mode is automatic (never write a dark: variant), 'use client' boundaries, subpath import paths, and the gotchas (overlay triggers are the button; no display utility on a <dialog>).

component-manifest.json

Generated from the TypeScript types by scripts/build-manifest.mjs, and regenerated on npm install so it matches your preset. For every export it records the exact import path, whether it's a client component, CVA variant options and defaults, prop types with descriptions, and a working example — plus the design token names.

# Dialog  (@your-scope/ui-overlay)
import:  import { Dialog } from '@your-scope/ui-overlay/dialog'
client:  yes — needs 'use client'
parts:   DialogHeader, DialogTitle, DialogBody, DialogFooter
variants:
  size: sm | md | lg | xl   (default: md)
props:
  open: boolean
  onClose: () => void          Called on every dismissal
  closeOnBackdrop?: boolean    (default: true)

Regenerate it yourself after adding a component:

npm run manifest        # rewrite component-manifest.json
npm run manifest:check  # CI — fails if it has drifted from source

MCP server

The scaffold asks which assistants to wire the Model Context Protocol server for. Chosen ones get a config file (.mcp.json for Claude Code, .cursor/mcp.json for Cursor); Codex gets a codex mcp add command. Add it later with:

npm run mcp                              # the same prompt, from your project
npx create-cassa-ui mcp init --cursor    # non-interactive
npx create-cassa-ui@latest my-app --mcp claude,cursor   # at scaffold time

The server serves the manifest as five tools. It's stateless — it re-reads component-manifest.json on every call, so it's always current.

Tool	Returns
list_components	every export + a one-line summary (filter by package or kind)
get_component	import path, client flag, variants, prop types, referenced type shapes, compound parts, an example
get_tokens	colour / spacing / radius / font-size names, fill→foreground pairings, optional hex values
conventions	the coding rules from AGENTS.md
check_usage	lint a snippet: wrong prop names, out-of-range variants, and the conventions

check_usage — the assistant lints itself

A static file says “don't do X”; the assistant still does X sometimes. check_usage runs after it writes code and flags convention violations before they land:

> check_usage("<DropdownMenuTrigger><Button>Menu</Button></DropdownMenuTrigger>")

1 issue:
• A <Button> is nested inside a *Trigger — that renders a <button> inside a
  <button>. Give the trigger text and className={buttonVariants({ variant })}.

Editor support

Claude Code — reads .mcp.json, prompts to approve on open. /mcp lists connected servers.
Cursor — reads .cursor/mcp.json, shows it in Settings → MCP.
Codex CLI — run the printed codex mcp add command.
Editors without MCP support ignore the config files — the AGENTS.md and manifest still help.

Next: Theming →