AI tool integrations

helixui is AI-native. Every component owns a machine-readable spec.md. The token system ships as DTCG JSON. The MCP server exposes everything over a single stdio interface. The goal: an LLM that has never seen helixui can produce correct, token-accurate, accessible UI on the first try.

This section is the per-tool wiring guide.

Per-tool guides

Claude Code — MCP server + CLAUDE.md.
Cursor — .cursorrules template + MCP wiring.
GitHub Copilot — .github/copilot-instructions.md.
Windsurf — built-in MCP support.
Generic agents — AGENTS.md for tool-agnostic agents.

What every tool reads

Artifact	Where	Purpose
`llms.txt`	served at site root	Compact tree the model fetches once.
`llms-full.txt`	served at site root	Full prose version of the docs (~80 KB, fits in any context window).
`components-manifest.json`	served at site root	Every component, its props, its tokens — machine-readable.
`tokens-manifest.json`	served at site root	DTCG flat dump of every token.
`DESIGN.md`	repo root	Canonical design-system summary in a single file.
`spec.md` (per component)	`packages/core/src/components/<name>/`	Per-component contract.

You can drop any of these into a model’s context and it’ll get useful answers. The MCP server (next section) is the recommended path because it stays in sync as your local helixui version evolves.

The MCP server

@helixui/mcp is a dependency-free Model Context Protocol server that speaks JSON-RPC 2.0 over stdio. Eight tools are available:

Tool	What it does
`helixui.search`	BM25 search across every component spec.
`helixui.validate`	Parse JSX, report unknown components / props.
`helixui.parse_dsl`	Convert the helixui prompt DSL into JSX.
`helixui.emit_dsl`	Convert JSX into compact DSL.
`helixui.express_dna`	Expand a DNA shorthand into a canonical DESIGN.md.
`helixui.parse_design`	Parse a DESIGN.md into JSON.
`helixui.list_presets`	List the built-in DNA presets.
`helixui.derive_dna_from_image`	Infer the closest helixui DNA from a screenshot.

Plus six resource URIs (helixui://components-manifest.json, helixui://tokens-manifest.json, helixui://components.md, helixui://llms-full.txt, helixui://DESIGN.md, helixui://DESIGN_MD_FORMAT.md) for static lookups.

Why this beats “just give the LLM the docs URL”

Three problems with the docs-URL approach:

Pull, not query. The model has to fetch all the docs and parse them, every time, even when it only needs Button’s props. Tokens spent on noise.
No interactive validation. The model generates JSX; only at runtime do you find out <Button tone="purple"> is invalid.
Drift. Docs URLs go to the latest version; the model is working against the version you have installed.

The MCP server fixes all three: queryable, validating, version-locked to your local install.

What “AI-friendly” actually means

You should be able to:

Mention “helixui” in a fresh Claude/Cursor/Copilot session.
The tool picks up the local MCP server (or the llms.txt you serve).
It writes JSX using the right components, the right tokens, the right a11y attributes — all on the first generation.
If it gets a component name wrong, helixui.validate tells it which names exist and the model self-corrects.

If your tool isn’t doing that, open an issue and tell us what you tried. This is a contract; helixui breaks if it breaks.