cronus-ui-mcp

A Model Context Protocol (MCP) server for Cronus UI. It lets MCP-compatible AI agents and assistants discover, fetch, and install Cronus UI components and blocks straight from the registry — and compose full apps, add pages, set themes, and upgrade installed components and composed pages — so an agent can list what's available, search it, pull the exact source files, and grow the project it is working in along the product loop (compose → add-page → theme → upgrade), not just add button.

The MCP server does not scaffold a new app. Greenfield starts with npx create-cronus-app; write tools then operate inside that already-inited project.

It speaks MCP over stdio (local IDEs, full read + write) and over Streamable HTTP at https://aicronus.com/mcp (hosted, read-only catalog — cloud builders cannot spawn a local CLI). Both surfaces read the same registry the cronus-ui CLI installs from.

Official MCP Registry name: io.github.pedrogbraz/cronus-ui (stdio npm package plus the hosted remote). Setup for every client lives at aicronus.com/docs/mcp.

What it exposes

Read-only tools

These are annotated readOnlyHint: true — they never touch the project.

Write tools

Write tools return a structured JSON result: status (success / failed / timeout), the detected projectRoot, the exact command that ran, the parsed report (files written/skipped, dependency state, theme changes, or CLI notes), and the CLI's verbatim stdout/stderr. They are annotated as non-read-only (destructiveHint: true, idempotentHint: true).

How writes work (security)

The server itself never writes files. Write tools only spawn the version-pinned cronus-ui CLI — bunx --bun cronus-ui@<the server's own version> (falling back to npx -y) — so the code that touches your project is exactly the published CLI release matching the server, resolving from the same pinned registry the read tools describe. The child runs at the detected project root (the nearest directory with a cronus-ui.json, else the nearest package.json, walking up from the server's working directory), with a 120s timeout. Item names are validated as registry slugs, compose/add-page/theme/variant arguments may not look like flags, and block specs reject -- / stray spaces, so tool arguments can never smuggle extra CLI options. The project must already exist and be initialised (npx create-cronus-app my-app --template saas, or npx cronus-ui init in an existing app); otherwise the CLI fails with a clear error and writes nothing. MCP write tools never scaffold a new repository.

Resources

Setup

Two transports. Pick one:

One command writes every project file:

npx cronus-ui mcp init

--client cursor,vscode for a subset; --force overwrites. create-cronus-app and cronus-ui ai emit the same files. Snippets: aicronus.com/docs/mcp.

The stdio server runs with npx — no global install needed.

Claude Code

claude mcp add cronus-ui -- npx -y cronus-ui-mcp

Hosted (read-only):

claude mcp add --transport http cronus-ui https://aicronus.com/mcp

Cursor / Windsurf (and other clients that use an mcpServers JSON)

Add this to your MCP config (e.g. ~/.cursor/mcp.json, or a project .cursor/mcp.json):

{
  "mcpServers": {
    "cronus-ui": {
      "command": "npx",
      "args": ["-y", "cronus-ui-mcp"]
    }
  }
}

Hosted (read-only):

{
  "mcpServers": {
    "cronus-ui": {
      "url": "https://aicronus.com/mcp"
    }
  }
}

To point at a different registry, add an env block (see below):

{
  "mcpServers": {
    "cronus-ui": {
      "command": "npx",
      "args": ["-y", "cronus-ui-mcp"],
      "env": { "CRONUS_UI_REGISTRY": "/absolute/path/to/registry" }
    }
  }
}

Configuration

The server fetches index.json for listings and <name>.json for item detail, and caches both in memory for the lifetime of the process. All diagnostics are written to stderr; stdout carries only the MCP protocol.

Example agent flow

Greenfield is not an MCP tool. Scaffold a new app first, then point the MCP server at that project:

npx create-cronus-app my-app --template saas

MCP write tools only run inside an already-inited project (cronus-ui.json or at least package.json). Then:

1. compose_app { "template": "saas", "brand": "Acme" } → installs the SaaS template's blocks and writes generated pages that stack them in <main>. Optional variant: ["login=split"], skipInstall, overwrite.
2. add_page { "route": "/pricing", "blocks": "pricing,cta", "nav": "Pricing" } → grows the composed app by one route. Optional skipInstall, overwrite, and manifest (custom compose apps).
3. set_theme { "name": "sunset", "mode": "dark" } → switches the baked-in preset. (Create Studio permalinks go through apply_theme instead.)
4. upgrade_components { "dryRun": true } → preview the 3-way merge of installed components and composed pages/layouts against the current registry (upgrade --all --dry-run). Prefer this over install_component with overwrite (and over compose --overwrite) so local edits survive. Optional manifest when the app was composed from a custom --manifest.

Low-context pick (Hydra / an agent that has not read the docs):

1. match_catalog { "query": "login page with smooth animation" } → two lookups (intent=login, motion=smooth) and a pick of compact cards (description, design style, palette, motion, intents). No source dumped.
2. get_component { "name": "<picked name>" } → source only after the pick.
3. install_component { "names": ["<picked name>"] } → write it into the project.

For a single primitive by name, keep using the registry tools:

1. search_registry { "query": "table" } → finds data-table, table, filter-bar.
2. get_component { "name": "data-table" } → returns the .tsx source, its npm deps (@tanstack/react-table, …), its registry deps, and npx cronus-ui add data-table.
3. install_component { "names": ["data-table"] } → the pinned CLI writes the files into the project, pulls in the registry dependencies, and installs the npm packages — the result lists every file written.

Development

bun run build      # tsc -> dist
bun run typecheck  # tsc --noEmit
bun run test       # vitest (tool logic, no network)

License

MIT