@hex-core/mcp

Universal MCP server for Hex Core. Gives any MCP-capable AI agent — Claude Code, Cursor, Continue, Gemini CLI, ChatGPT Desktop, Zed — structured access to the component registry. No prose scraping, no copy-paste.

Install

Zero install — just run via npx:

npx -y @hex-core/mcp

Wire into your client

Pick your client below. Every snippet calls the same npx -y @hex-core/mcp; the only thing that changes is where the config file lives and what key it uses.

Tools exposed

Components & themes:

• search_components(query) — fuzzy search across name, description, tags, AI hints
• get_component(slug) — full RegistryItem (props, variants, examples, AI metadata)
• get_component_schema(slug) — props, variants, slots, AI hints without source
• list_themes() — available theme presets; in MCP Apps hosts also renders an interactive theme browser (see below)
• get_theme(name, format) — full token set for a theme (css / json / tailwind)
• scaffold_project(components, theme) — init + starter components in one call
• customize_component(slug, overrides) — generate a themed variant

Spec-driven build flow:

• list_recipes() — catalog of spec-driven blueprints (auth form, settings page, pricing table, …)
• get_recipe(slug) — ordered install steps, union of peer deps, post-install checklist
• resolve_spec(brief) — deterministic brief → ranked component + recipe shortlist (no LLM call server-side)
• verify_checklist(components, recipe?) — cross-check installed components against the internal-dependency graph and the recipe's checklist
• emit_app_context(theme, components, recipes?) — synthesize a paste-into-LLM markdown payload describing the chosen stack
• emit_figma_tokens(theme) — render a theme as a Figma Variables REST POST payload

AI-native intent layer (0.4.0+):

• describe_intent(name) — variant useWhen strings, structured antiPatterns with insteadUse slug, and the slice of defaultSemanticTokens for the component. Use BEFORE generating JSX — the per-variant intent + structured anti-patterns prevent the canonical LLM mistakes (picking destructive for non-destructive, picking Slider for booleans, nesting Cards, etc.).
• search_compositions(tags, limit?) — return component examples whose composition tags overlap the query. ["dialog", "destructive", "confirm"] returns the canonical AlertDialog-with-delete-Button composition, not a bare <Button variant="destructive">. Ranked by overlap count.

Agent-builder layer (0.7.0+):

• map_application(brief, limit?) — map a whole-application brief onto the catalog: screens typed as page-recipe / recipe / components, a requires-closure install manifest, related-component suggestions, anti-pattern warnings, merged checklist, and token budgets. Deterministic; the result is a hex.map.json the CLI consumes via hex add --from / hex poc --from.
• query_graph(mode, slug, to?, relations?) — query the catalog knowledge graph (registry/graph.json: items + recipes + themes; relations requires / composes / themes / related / instead-use). Modes: explain (node + grouped edges + community peers), neighbors, path, affected (reverse blast radius). Use instead of guessing component relationships.
• scaffold_poc({brief | map | recipe}, theme?, name?) — generate the complete file tree of a standalone runnable Next.js demo app: configs, theme globals.css, copied component sources with rewritten imports, and one generated route per page-recipe screen (assembled from schema examples). The tree also carries a demo panel that re-renders every frame as viewer / member / admin and flips it between populated and empty — a POC is the frames demoed, not just the frames. Returns JSON; nothing is written to disk.

MCP Apps (0.9.0+):

list_themes declares an interactive theme browser through the MCP Apps extension (SEP-1865): the tool's _meta.ui.resourceUri points at the self-contained ui://hex-core/theme-browser.html resource, and hosts that support MCP Apps — Claude, ChatGPT, VS Code — render it as a palette-previewing theme picker whose selection is handed back to the conversation. The HTML travels over resources/read, never through tool results, so the tool's text output and every token ceiling are unchanged. Hosts without MCP Apps support ignore the _meta and see the same list_themes they always did. The contract test below asserts both the _meta declaration and the ui:// resource.

Prompts that "just work"

• "Find a hex-core component for a confirmation dialog and add it"
• "Resolve this spec into hex-core components: build a settings page with notifications toggle"
• "Walk me through the hex-core auth-form recipe and install it"
• "Verify I have all the hex-core internal deps for combobox"

Pair with skills (Claude Code only)

The MCP server returns structured data. For prose reasoning context (when to pick recipe X, how themes compose, React 19 anti-patterns), the Hex Core skills pack adds Claude-Code-trigger-keyword docs alongside the typed tool calls:

npx @hex-core/cli skills install

The skills pack is Claude Code only today — its trigger system relies on Claude Code's prompt-rewriting hooks. Other clients in the list above run the MCP server unchanged but won't pull in the skills.

Verifying the server speaks standard MCP

The package ships a contract test that handshakes with the server using the official @modelcontextprotocol/sdk Client — the same SDK every supported client uses underneath. Run it locally to confirm wiring works:

pnpm --filter @hex-core/mcp test:contract

A green run proves the server speaks standard MCP regardless of which downstream client opens the connection. CI runs this on every push.

Upgrading from 0.3.0 → 0.4.0

The npx @hex-core/mcp binary works exactly as before — no config changes for users of the stdio MCP server. Two breaking changes affect direct importers (Next.js apps, generator scripts, CI fixtures): the pure-function builders moved to a new package @hex-core/payload, and the published tarball no longer ships registry/ directly. See MIGRATION.md for the full guide and replacement code snippets.

Docs

hex-core.dev/docs/mcp

License

MIT