Cronus UI

cronus-ui-mcp

一个面向 Cronus UI 的 Model Context Protocol（MCP）服务。它让兼容 MCP 的 AI Agent 和助手能够发现、获取并安装 Cronus UI 组件和区块，直接从注册表中取用；还能组合完整应用、添加页面、设置主题以及升级已安装的组件和已组合的页面。因此，Agent 不仅可以列出可用内容、搜索内容、获取精确的源文件，还能沿着产品工作流（组合 → 添加页面 → 主题 → 升级）不断扩展正在开发的项目，而不只是 add button。

此 MCP 服务不会搭建新应用。全新项目应从 npx create-cronus-app 开始；写入工具随后会在已初始化的项目中运行。

它通过 stdio（本地 IDE，支持完整的读取和写入功能）以及 https://aicronus.com/mcp 上的 Streamable HTTP（托管服务，只读目录——云端构建工具无法启动本地 CLI）提供 MCP 服务。

两个入口读取的是同一注册表；cronus-ui CLI 也从该注册表安装内容。

官方 MCP Registry 名称：io.github.pedrogbraz/cronus-ui（stdio npm 包及托管的远程服务）。所有客户端的设置说明均位于 aicronus.com/docs/mcp。

提供的功能

只读工具

工具	输入	返回内容
list_components	—	所有可安装组件（registry:ui）：名称、标题、标签、依赖项和安装命令。
list_blocks	—	所有可安装区块（registry:block）——由 Hero、定价、登录和仪表盘等部分组合而成。
list_catalog	{ kind?: component|block|variant|template }	适用于 Hydra 的精简卡片（描述、设计风格、配色、动效、意图）。不含源文件。
match_catalog	{ query?, intent?, style?, palette?, motion?, kind?, limit? }	面向低上下文 Agent 的双查询匹配。query: "login page with smooth animation" 会推断意图和动效，并返回 pick / intent / motion 匹配结果。
search_registry	{ query: string }	名称（或易读标题）与 query 匹配的组件和区块（不区分大小写的子字符串匹配）。
get_component	{ name: string }	单个组件或区块的完整详情：源文件 files（路径 + 内容）、npm dependencies、registryDependencies 和安装命令。
get_install_command	{ names: string[] }	一个或多个项目的 npx cronus-ui add ... 命令。
get_design_context	{ theme?: aurora|neutral|midnight|sunset|emerald, look?: default|brutalist|glass, format?: compact|extended }	Cronus 的视觉风格（DESIGN.md）。生成 UI 前请先阅读。

这些工具均标记为 readOnlyHint: true——不会触碰项目。

写入工具

工具	输入	功能
compose_app	{ template: "saas"|"store"|"landing"|"landing-*"|"mail"|"chat"|"finance", brand?: string, dryRun?: boolean, yes?: boolean, skipInstall?: boolean, overwrite?: boolean, variant?: string[] }	在项目中运行 cronus-ui compose <template> -y（Agent 默认使用 -y；如果未提供模板，则会组合 saas）。可选参数包括 --brand、--dry-run、--skip-install、--overwrite，以及针对每个 variant 条目的一个 --variant <slug=id>。当用户需要基于经过验证的模板构建完整的多页应用时，优先使用此工具，而不是手动编写页面。不会搭建新的仓库。
add_page	{ route: string, blocks: string, nav?: string, title?: string, chrome?: string, dryRun?: boolean, skipInstall?: boolean, overwrite?: boolean, manifest?: string, app?: string }	运行 cronus-ui add-page --route <route> --blocks <blocks>，为已组合的应用添加一个页面（安装区块、编写堆叠的 <main> 页面并更新导航）。可选参数包括 --skip-install、--overwrite、--manifest（用于自定义组合应用），以及 --app（当项目包含多个已组合的应用时必需）。
set_theme	{ name: "aurora"|"neutral"|"midnight"|"sunset"|"emerald", mode?: "dark"|"light" }	运行 cronus-ui theme set <name>（可选 --mode）切换内置预设。对于 Create Studio 永久链接，请使用 apply_theme。
install_component	{ names: string[], overwrite?: boolean, skipInstall?: boolean }	在项目中运行 cronus-ui add <names...>：写入组件/区块源文件、解析注册表依赖，并使用项目的包管理器安装 npm 依赖。除非设置了 overwrite，否则会跳过现有文件。如果文件已存在且你希望从上游拉取更新，同时保留本地修改，请优先使用 upgrade_components。
upgrade_components	{ names?: string[], all?: boolean, dryRun?: boolean, yes?: boolean, manifest?: string }	运行 cronus-ui upgrade --all（省略 names 时的默认行为）或 cronus-ui upgrade <names...>。对已安装的组件以及已组合的页面/布局执行三方合并，以保留本地修改。优先使用此工具，而不是通过 install_component 覆盖，或使用 compose --overwrite。建议先运行 dryRun（--dry-run）；仅在 yes 为 true 时使用 -y。自定义组合应用可选用 manifest（--manifest）。
apply_theme	{ source: string, dryRun?: boolean }	在项目中运行 cronus-ui theme add <source>：更新应用布局的主题属性，将主题覆盖区块写入全局样式表，并在 cronus-ui.json 中记录主题。source 可以是 Create Studio 永久链接、纯 c= 载荷或导出的主题 JSON 文件。dryRun 可预览而不写入文件。

写入工具会返回结构化 JSON 结果，其中包含 status（success / failed / timeout）、检测到的 projectRoot、实际运行的 command、解析后的报告（写入/跳过的文件、依赖状态、主题变更或 CLI 说明），以及 CLI 原样返回的 stdout/stderr。这些工具标注为非只读（destructiveHint: true、idempotentHint: true）。

写入工作方式（安全性）

服务器本身不会写入文件。写入工具仅会启动固定版本的 cronus-ui CLI——bunx --bun cronus-ui@<the server's own version>（若不可用则回退到 npx -y）——因此，操作你项目的代码与服务器匹配，正是已发布的 CLI 版本，并且从读取工具所描述的同一固定注册表解析。子进程会在检测到的项目根目录中运行（从服务器的工作目录向上查找，优先使用最近的含有 cronus-ui.json 的目录，否则使用最近的含有 package.json 的目录），超时时间为 120s。条目名称会验证为注册表 slug；compose/add-page/theme/variant 参数不得看起来像标志；区块规格会拒绝 -- / 多余空格，因此工具参数绝不会偷偷带入额外的 CLI 选项。项目必须已存在并完成初始化（运行 npx create-cronus-app my-app --template saas，或在现有应用中运行 npx cronus-ui init）；否则 CLI 会报出明确错误，且不会写入任何内容。MCP 写入工具绝不会搭建新的代码仓库。

资源

资源	URI	描述
registry-index	cronus-ui://registry/index	完整的注册表列表（包含每个组件和区块及其依赖项），格式为 JSON。
catalog-tags	cronus-ui://catalog/tags	Hydra 用于排名的精简标签目录（不含源文件）。

设置

有两种传输方式，任选一种：

传输方式	URL / 命令	工具	适用场景
可流式传输的 HTTP（托管）	https://aicronus.com/mcp	只读目录	v0、Lovable、Replit、Bolt、Base44，或任何支持 URL 的客户端
stdio（本地）	npx -y cronus-ui-mcp	读取 + 写入（compose、add-page、install、theme、upgrade）	Claude Code、Cursor、VS Code、Codex、Grok CLI、OpenCode、Zed

一条命令即可写入项目的所有文件：

npx cronus-ui mcp init

使用 --client cursor,vscode 指定部分客户端；--force 会覆盖文件。create-cronus-app 和 cronus-ui ai 会生成相同的文件。代码片段：aicronus.com/docs/mcp。

stdio 服务器通过 npx 运行——无需全局安装。

Claude Code

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

托管版（只读）：

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

Cursor / Windsurf（以及其他使用 mcpServers JSON 的客户端）

将以下内容添加到你的 MCP 配置中（例如 ~/.cursor/mcp.json 或项目中的 .cursor/mcp.json）：

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

托管版（只读）：

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

要指向其他注册表，请添加 env 块（见下文）：

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

配置

环境变量	默认值	描述
CRONUS_UI_REGISTRY	固定版本对应的公开 Cronus UI 注册表。	注册表来源覆盖项——可以是 http(s) 基础 URL，也可以是本地目录路径。适用于在本地测试分支或尚未发布的注册表。此变量也会通过 install_component、compose_app、add_page 和 upgrade_components（--registry）转发给 CLI。
CRONUS_MCP_CLI_CMD	bunx --bun cronus-ui@<version>，然后是 npx -y cronus-ui@<version>	写入工具的启动器覆盖项（按空白字符拆分），例如 bun /repo/packages/cli/src/index.ts 可运行本地 CLI 检出版本。
CRONUS_MCP_CLI_TIMEOUT_MS	120000	写入工具单次 CLI 运行的最长耗时。

服务器会获取 index.json 以列出条目，并获取 <name>.json 以查看条目详情；两者都会在进程生命周期内缓存在内存中。所有诊断信息都会写入 stderr；stdout 仅承载 MCP 协议。

Agent 工作流示例

**Greenfield 不是 MCP 工具。**请先搭建新应用，再将 MCP 服务指向该项目：

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

MCP 写入工具只能在已初始化的项目中运行（cronus-ui.json 或至少包含 package.json）。然后：

1. compose_app { "template": "saas", "brand": "Acme" } → 安装 SaaS 模板的区块，并写入将这些区块堆叠在 <main> 中的生成页面。 可选参数：variant: ["login=split"]、skipInstall、overwrite。
2. add_page { "route": "/pricing", "blocks": "pricing,cta", "nav": "Pricing" } → 为组合后的应用新增一个路由。可选参数：skipInstall、overwrite 和 manifest（用于自定义组合应用）。
3. set_theme { "name": "sunset", "mode": "dark" } → 切换内置预设。 （Create Studio 永久链接则通过 apply_theme 应用。）
4. upgrade_components { "dryRun": true } → 预览已安装组件和组合页面／布局 与当前注册表之间的三方合并（upgrade --all --dry-run）。优先使用此工具， 而不是使用带 overwrite 的 install_component（也优于 compose --overwrite），以保留本地修改。若应用使用自定义 --manifest 组合，可选传入 manifest。

低上下文场景（Hydra／尚未阅读文档的 Agent）：

1. match_catalog { "query": "login page with smooth animation" } → 执行两次 查询（intent=login、motion=smooth），并通过 pick 返回精简卡片 （描述、设计风格、配色、动效、意图）。不会输出源码。
2. get_component { "name": "<picked name>" } → 仅在选定后返回源码。
3. install_component { "names": ["<picked name>"] } → 将其写入项目。

若要按名称获取单个基础组件，请继续使用注册表工具：

1. search_registry { "query": "table" } → 查找 data-table、table、filter-bar。
2. get_component { "name": "data-table" } → 返回 .tsx 源码、npm 依赖（@tanstack/react-table 等）、注册表依赖，以及 npx cronus-ui add data-table。
3. install_component { "names": ["data-table"] } → 固定版本的 CLI 将文件写入项目， 引入注册表依赖并安装 npm 包——结果会列出写入的所有文件。

开发

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

许可证

MIT