AI agents and MCP

Give Claude Code, Cursor, VS Code and other coding agents the complete kit docs, so they build with real components instead of guessing.

View as Markdown

The kits are newer than most models' training data, and the exact props matter. Two things fix that: an MCP server that answers from the docs of the exact version you installed, and plain Markdown for every page of this site.

MCP server

The CLI includes an MCP server (stdio, no network access, the docs are bundled). One command sets it up for the clients you use and adds the kit rules to AGENTS.md:

npx @twentyfirstmedia/ui mcp init --kit halo

It writes .mcp.json (Claude Code), .cursor/mcp.json (Cursor) and .vscode/mcp.json (VS Code). Pick clients with --client claude,cursor,vscode and skip the rules with --no-rules.

Or add it by hand. Claude Code:

claude mcp add twentyfirst-ui -- npx -y @twentyfirstmedia/ui mcp --kit halo

Cursor (.cursor/mcp.json), Windsurf and Claude Desktop use the same shape:

json

{
  "mcpServers": {
    "twentyfirst-ui": {
      "command": "npx",
      "args": ["-y", "@twentyfirstmedia/ui", "mcp", "--kit", "halo"]
    }
  }
}

VS Code (.vscode/mcp.json):

json

{
  "servers": {
    "twentyfirst-ui": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@twentyfirstmedia/ui", "mcp", "--kit", "halo"]
    }
  }
}

Codex (~/.codex/config.toml):

toml

[mcp_servers.twentyfirst-ui]
command = "npx"
args = ["-y", "@twentyfirstmedia/ui", "mcp", "--kit", "halo"]

Tools

Tool	What it returns
`search_docs`	Components, patterns, guides, tokens and icons that match a query
`list_components`	Every component page by group with a one-line summary
`get_component`	Description, import line, example code and props of a component
`get_pattern`	A complete screen built from kit parts, with its code
`get_guide`	Installation, CLI, theming, status and approvals, this page
`get_tokens`	Token names with Halo and Pro values, by group
`list_icons`	Every valid icon name
`check_usage`	Checks code: unknown components, props and icons, missing required props, colour literals

Every page is also a resource (twentyfirst-ui://components/ApprovalCard, twentyfirst-ui://guides/theming), and the prompts build_screen and review_ui start the two most common jobs.

Rules for agents

mcp init adds these to AGENTS.md (and CLAUDE.md when it exists); you can copy them by hand:

- Build UI from Twentyfirst UI components first; import them from `@twentyfirstmedia/halo`. Check names, props and examples with the `twentyfirst-ui` MCP server (`get_component`, `search_docs`) instead of guessing.
- Halo and Pro have the same components, props and markup. Never branch on the kit in code; switch looks with `data-kit` or `<UIProvider kit>`.
- No colour literals or arbitrary Tailwind values: use the shadcn-style theme variables (`var(--primary)`, `bg-card`, `text-muted-foreground`, `border-border`) so both kits, light and dark, and the app's theme keep working.
- Wrap the app once in `UIProvider` and import the kit's `styles.css` once (or `@twentyfirstmedia/ui-core/themes.css` for both kits).
- Format numbers, money, percentages and dates with `formatNumber`, `formatMoney`, `formatPercent`, `formatDate`.
- Icons: only names from `list_icons`; icon-only buttons need a `label`.
- Before finishing, run `check_usage` from the MCP server on new code.

Markdown and llms.txt

/llms.txt: what the kits are, the rules, and a link to every page.
/llms-full.txt: every guide and component page in one file.
Every page has a Markdown twin: append .md to its path, e.g. /halo/components/ApprovalCard.md. The "Markdown" button at the top of each page copies it.