forgekit-radix-mcp

Radix Primitives' APIs and accessibility contracts, exposed to AI coding agents.

Coding agents (Claude Code, Cursor) routinely hallucinate Radix prop names, drop required parts, and miss the ARIA/keyboard contract of a primitive. There's no machine-readable source of truth for how to use Radix correctly — only prose docs an agent has to guess from.

forgekit-radix-mcp is an MCP server that gives an agent the real thing: each primitive's parts, props, and — the part nobody else ships — its accessibility contract and the common mistakes to avoid.

My coding agent stopped hallucinating Radix props — and now it knows a tooltip isn't a label.

Part of ForgeKit. MIT licensed.

Why

Props can be inferred from types. The accessibility contract can't — that's hand-authored knowledge: which Provider is required, which part supplies the accessible name, what the keyboard model is, and the misuse that quietly breaks a11y (a Tooltip used as a label, a Popover that auto-opens a nested Tooltip, a Select with an empty-string item value). This server encodes that so agents generate correct, accessible Radix code on the first try.

Install

npm i -g forgekit-radix-mcp
# or run on demand
npx forgekit-radix-mcp

Register with an MCP client

Claude Code / Cursor (stdio server):

{
  "mcpServers": {
    "radix": {
      "command": "npx",
      "args": ["-y", "forgekit-radix-mcp"]
    }
  }
}

Tools

Tool	Returns
list_primitives	Every documented primitive + one-line description
get_primitive	Parts, props by part, a11y contract, and a correct example
get_a11y_contract	Just the accessibility contract — highest-signal payload

Example

Agent call:

get_primitive  { "name": "Tooltip" }

Returns (abridged):

{
  "name": "Tooltip",
  "import": "import { Tooltip } from 'radix-ui';",
  "parts": ["Provider", "Root", "Trigger", "Portal", "Content", "Arrow"],
  "a11yContract": {
    "roles": "Content renders role=\"tooltip\"; Trigger gets aria-describedby when open",
    "keyboard": ["Tab: focus the trigger → opens instantly", "Escape: closes"],
    "focus": "Opens on focus AND hover; focus never moves into the tooltip",
    "requires": ["Tooltip.Provider must wrap the app once"],
    "commonMistakes": [
      "Using a tooltip for essential/interactive content (use Popover/HoverCard)",
      "Wrapping a disabled button directly — it fires no focus/hover events",
      "Using a tooltip as the only label for an icon button"
    ]
  },
  "correctExample": "<Tooltip.Provider> ... </Tooltip.Provider>"
}

Coverage

26 primitives. Dialog · AlertDialog · Popover · Tooltip · HoverCard · DropdownMenu · ContextMenu · Menubar · NavigationMenu · Select · Tabs · Accordion · Collapsible · Checkbox · RadioGroup · Switch · Toggle · ToggleGroup · Slider · Toast · Progress · Avatar · Label · Separator · AspectRatio · ScrollArea.

Data reflects the radix-ui public API and the WAI-ARIA Authoring Practices.

Pairs with WorkOS AuthKit MCP

For agents that act on behalf of a user, AuthKit MCP handles secured, tool-scoped access — forgekit-radix-mcp is a read-only knowledge server that slots cleanly behind it.

Development

npm install
npm run build
npm test