comp-hub-mcp

MCP server for CompHub. Once connected, AI clients (Trae, Claude Desktop, Cursor, etc.) can create, preview, and publish CompHub components directly inside your current frontend project — no manual browser sessions or folder uploads.

Website: https://www.comphub.cn  ·  Studio: https://studio.comphub.cn  ·  Docs: https://docs.comphub.cn

Tools

| Tool | What it does | | --- | --- | | comp_status | Shows sign-in state, remote environment, local service, serverVersion, and project root — a pre-flight check before publishing. Also returns renderPort (the shell/preview port used for screenshots) and the workspace verdict (outsideWorkspace: true / false / "unknown") | | comp_use_project | Resolves the host project and starts (or reuses) the local service — the first step for a new component | | comp_skill | Reads the full component spec by name (required before writing component code) | | comp_preview | Headless render with screenshot, returning render status, errors (with stack and candidate source locations), warnings, timing, panel base size and screenshot size; supports hover / click / key actions, custom scale, frameless output, and a cover: true preset that writes a 680×500 (mini 340×250 at 2x) screenshot_mini.png into the component folder for the publish flow to reuse. Actions that cannot run (selector missing, invisible, disabled, pointer-events: none) are skipped instead of timing out, and reported back in skippedActions | | comp_open_preview | Returns a browser-openable short link to a local preview (works for unpublished components) | | comp_publish | Two-step publish: dry run by default, commits only with confirm: true. The plan returns writes (files and create/update actions); after confirm: true, published.writes lists what was actually written, so the caller can git add exact paths | | comp_release_service | Stops the local service child process for this component's host project only (same as comphub stop <hash>, never comphub kill). Returns stoppedProject (ports), confirmed (re-queried project table) and portReleased (true / false / "unknown" per port) so the release can be verified instead of trusted |

Typical flow: read comp_skill for the directory structure and file extensions → comp_use_project → write the entry, demo and README yourself → comp_preview to see the first screen → comp_publish for a dry run and fix every fix hint → comp_publish with confirm: true to publish → comp_release_service once you no longer need the local preview.

MCP does not scaffold component files: the spec returned by comp_skill lists the required entry, demo/mini / demo/full conventions and the supported extensions for each framework, and the agent creates them. comp.json is generated by the publish flow — do not write it by hand.

Requirements

• Node.js >= 20
• Signed in to CompHub: run npx comp-hub login in a terminal (credentials are written to ~/.comphub/credentials.json and shared with the CLI)
• A client that implements MCP roots/list, or a configured workspace root — component directories must live inside the current workspace. Configure either the COMPHUB_WORKSPACE environment variable (multiple roots separated by the platform path delimiter) or ~/.comphub/workspace.json ({ "roots": ["D:/code/ws"] }). When neither the client nor the config provides a root, comp_status returns outsideWorkspace: "unknown" plus workspaceSkipReason (client_unsupported / timeout / empty) and workspaceSource (client / config / none). In that mode the workspace boundary is only enforced by your prompt (Get-Location and "write inside the workspace" rules), not by the server
• Components must sit inside an existing frontend host project: it needs a package.json and installed dependencies (node_modules). MCP never creates a host project; if none is found, it asks you to choose an approach first

Installation & Configuration

Option 1: npx (recommended)

{
  "mcpServers": {
    "comp-hub": {
      "command": "npx",
      "args": ["-y", "comp-hub-mcp"]
    }
  }
}

Option 2: global install

npm install -g comp-hub-mcp

{
  "mcpServers": {
    "comp-hub": {
      "command": "comp-hub-mcp"
    }
  }
}

Add the entry to your client's MCP config and restart the client. Screenshots rely on Playwright's Chromium, which the playwright dependency prepares automatically; if it was stripped, run npx playwright install chromium.

Component Layout

A component is a folder, and the folder name is the component name (globally unique).

| Framework | Entry | Demo | | --- | --- | --- | | Vue 2 / 3 | index.vue | demo/mini.vue, demo/full.vue | | React 15 ~ 19 | index.jsx / index.js / index.tsx | demo/mini.jsx, demo/full.jsx | | Web Component | index.js (registers a custom element) | demo/mini.html, demo/full.html |

• The first paragraph of README.md becomes the component description
• comp.json is maintained by the platform (__id__ / name / version) — do not write it by hand; when the source changed but the version did not, bump it via bump: "patch"
• Component names accept PascalCase (SimpleCard) or kebab-case (simple-card); the first kebab-case segment must be letters only, so d3-activity-heatmap is invalid
• Keep only the entry, demos, README, and required assets in the folder — file count and size are quota-limited

The full spec ships as a built-in skill: call comp_skill with name: "comp-hub-create" to read it.

Local Service & Previews

• MCP starts (or reuses) the comp-hub local master service on demand, defaulting to http://127.0.0.1:5478
• Each project is registered under a path hash and served at /{hash}/main/, sharing the same service as projects started by the CLI
• comp_open_preview returns a /p/{id} short link (older masters fall back to the full URL); links depend on the local service and stop working once it shuts down
• Use comp_status when you only want status without starting the service; manage running projects with comphub status / comphub stop --all, or call comp_release_service to stop just this component's project

How MCP and the CLI share the local service

The two are two shells over one mechanism, not a client/server pair — MCP never shells out to the CLI, and the CLI never depends on MCP.

| Layer | Owner | Responsibility | | --- | --- | --- | | Mechanism | @comp-hub/node-comphub | Discover / spawn / register projects, wait for readiness, and reconcile leftover masters | | Operations | comphub CLI | Human-facing start / status / stop / kill / fix | | Automation | MCP | comp_status / comp_use_project / comp_preview / comp_publish / comp_release_service |

Before spawning a master, both sides call the same reconcileMaster(): if master.json is missing but an old master still holds a port, it is identified by its /__master__/health response or by its command line (must contain master.js and the package name), shut down gracefully, then killed only if it does not exit. Processes that cannot be identified are never killed — they are reported as skipped. A healthy master.json short-circuits the whole step, so reuse stays zero-cost.

comp_status reports ports by layer: localService.master.managementPort / publicPort (the master), projects[].childPort (the MidwayJS child process), and projects[].subPort / renderPort (the shell / preview app used for screenshots — renderPort is the value to use directly, do not infer it from projectUrl).

Troubleshooting

| Symptom | Fix | | --- | --- | | Not signed in / 401 | Run npx comp-hub login in a terminal, then retry | | Host is missing node_modules | Install dependencies in that project first, then retry | | outside_workspace | The component directory is outside the current workspace; confirm it is the intended repo, then retry with allowOutsideWorkspace: true. outsideWorkspace: "unknown" means neither the client nor the MCP config provided a workspace root — configure COMPHUB_WORKSPACE if you want a real verdict | | Behaviour contradicts the spec returned by comp_skill | Check serverVersion in comp_status: the skill is inlined at build time, so an outdated comp-hub-mcp serves stale rules. Upgrade or rebuild the MCP package | | No host project found | Choose a path first: create a new frontend project in the current directory (the AI scaffolds it) or place the component under an existing project's src/components/ | | Screenshot timeout / late first frame | For ECharts maps, large data tables, etc., raise waitMs (e.g. 3000–8000) or timeoutMs | | 等待本地 master 启动超时 / stale master holds the port | The error now lists the ports and PIDs it found. Run comphub fix in a terminal (identifies, shuts down, and only then kills a confirmed leftover master), then retry | | Publish blocked by blocking items | Each item carries code / message / fix; apply the fix and run the dry run again |

Local Development (in this repo)

pnpm --filter comp-hub-mcp build        # esbuild bundle → dist/index.js (single-file ESM, minified)
pnpm --filter comp-hub-mcp type-check   # tsc --noEmit
pnpm --filter comp-hub-mcp test         # vitest
pnpm --filter comp-hub-mcp release      # build → print package size → confirm → pnpm publish

During bundling, @comp-hub/* packages are inlined. Only playwright, @modelcontextprotocol/server, zod, and comp-hub stay external — the last one is resolved via require.resolve only, to locate its dist/master.js, and is not bundled.

Links

• Website: https://www.comphub.cn
• Studio (browser-based component workspace): https://studio.comphub.cn
• Docs: https://docs.comphub.cn