Your AI writes the component,
MCP previews and ships it
comp-hub-mcp is an MCP server. Connect it to Trae, Claude Desktop or Cursor and the assistant can write components inside your current frontend project, render headless screenshots, clear every blocking item and publish — no browser upload, no zipped folders.
npx -y comp-hub-mcp · Node ≥ 20
Three things in place
MCP will not scaffold a host project or sign you in. Get these three right and every tool call goes through.
Node.js ≥ 20
Launched through npx, so there is nothing to install globally; Chromium is prepared automatically for the first screenshot.
Signed in from a terminal
Run npx comp-hub login once. Credentials land in ~/.comphub/credentials.json and are shared with the CLI.
A usable host project
The component folder must sit inside your current workspace, and the host needs a package.json with node_modules installed.
Sign in, paste, self-check
The configuration is a single mcpServers block. Paste it, restart the client, and the assistant sees seven comp_* tools.
- 01
Sign in once
Authorize in the browser from a terminal. Credentials are shared with the CLI, so the client never asks again.
npx comp-hub login - 02
Paste and restart
Drop this block into the client's MCP config and restart it. Already installed comp-hub-mcp globally? Change command to comp-hub-mcp.
mcpServers - 03
Let the agent self-check
Ask for comp_status: if it returns serverVersion, sign-in state and the local service, you are connected.
comp_status
{
"mcpServers": {
"comp-hub": {
"command": "npx",
"args": ["-y", "comp-hub-mcp"]
}
}
}Every action the agent needs
Tools only look and hand off — the agent still writes the code. Every call reports which project root and local service it used.
comp_statusRead-only check: sign-in state, remote environment, local service, version and project root. Never starts the service.
outsideWorkspace: true | false | "unknown"comp_use_projectResolves the host project and starts or reuses the local service, reporting whether the host is ready.
ready · host_missing · need_confirmationcomp_skillReads the full component spec: folder layout, entry extension, demo conventions. Required before writing code.
name: "comp-hub-create"comp_previewHeadless render plus screenshot, returning render errors, console errors, candidate source locations and timing.
actions · cover · scale · waitMscomp_open_previewReturns a short local preview link you can open in a browser — unpublished components included.
/p/{id}comp_publishTwo-step publish: a dry run by default that lists the files to write; commits only with confirm.
confirm: true · bump: "patch"comp_release_serviceStops the local service child process for this component's project only, and reports whether the port was released.
stopped · no_master · not_registeredFrom a sentence to the shelf
This chain lives in the server's instructions, so the assistant walks it in order — no commands to memorise.
Describe the component
Purpose, framework, interactions. Only the three supported frameworks apply, and the agent asks instead of guessing.
Confirm the host
The agent resolves the project and starts the local service. If the host is missing, the folder sits outside the workspace or too far away, it stops and asks.
Read the spec, write files
It reads the full skill first, then writes the entry, demo/mini, demo/full and README to the folder and naming conventions.
Screenshot check
Render the first screen, read the screenshot, errors and timing, fix, then render again — never wait until the whole component is written.
Dry run, publish, clean up
Clear every fix hint from the dry run, publish with confirm, then stop the project's local service.
Two shells, one mechanism
MCP never shells out to the CLI, and the CLI never depends on MCP. Both use @comp-hub/node-comphub to discover, spawn and register the local service — down to the same reconcile step.
| Aspect | MCP | CLI |
|---|---|---|
| Who drives it | The agent in your MCP client | You in a terminal |
| How it starts | An mcpServers block | npx comp-hub |
| Seeing the result | comp_preview screenshots, with optional actions | Open /{hash}/main/ in a browser |
| Publishing | comp_publish dry run, then confirm | comphub upload |
| Cleaning up | comp_release_service, this project only | comphub stop [hash] |
What it will not do
Boundaries on the record, so you never wait for an action that cannot happen.
Does not generate component code
The agent writes the entry, demos and README to spec; MCP never drops business code into the folder.
Does not create a host project
When no host exists it asks which route you want instead of inventing a project.
Does not hand-write comp.json
The platform owns comp.json: publishing generates it and writes back __id__. Changed source but same version? Pass bump: "patch".
Does not leave the workspace
The component folder must stay inside the current IDE workspace; anything else needs your explicit confirmation.
Does not stop other services
It unregisters this project only — the same as comphub stop [hash], not comphub kill.
Six places people get stuck
Most of them clear with one command or one retry.
The client shows no tools?
Restart the client first, then confirm the block sits under mcpServers and the command is npx -y comp-hub-mcp. If it still does not appear, run npx comp-hub-mcp in a terminal — errors print straight out.
401 or a not-signed-in error?
Run npx comp-hub login in a terminal. Credentials are written to ~/.comphub/credentials.json and shared with the CLI, so no client restart is needed.
outside_workspace?
The component folder is outside the current workspace. Check the path first; if it really is the target repo, retry with allowOutsideWorkspace: true.
host_missing?
There is no usable frontend host in this directory. Pick a route: scaffold one here, or move the component into an existing project's src/components/.
Screenshot timeout or a late first frame?
For ECharts maps or large data tables, raise waitMs to 3000–8000 and timeoutMs if needed.
The spec and the behaviour disagree?
Check serverVersion in comp_status: the skill text is inlined at build time, so an old comp-hub-mcp serves old rules. Upgrade and retry.
Let the agent finish the whole flow.
Connect MCP and the path from first line to publish stays in the conversation.