feat(mesh): autostart MCP project from cwd in bunx decocms

[vibegui]

Summary

When users run bunx decocms from a folder that contains an mcp/ subfolder (or whose cwd itself looks like an MCP project), Studio now detects the project, installs deps if needed, spawns its dev server, fetches its tools, creates a connection + Virtual MCP agent, and opens the browser straight into a chat with that agent.

The agent's system prompt is taken from an authored prompt.md / AGENTS.md / CLAUDE.md in the project root when present; otherwise a small Anthropic model drafts one from the README + tool list, with a template fallback when no provider key is configured. Tools exposing _meta.ui.resourceUri are auto-pinned as sidebar views, with the first one set as the default main view alongside chat.

Changes

New module — apps/mesh/src/cli/autostart/

• detect.ts — finds the project, package manager (lockfile-based), and starter script. Resolves agent name from README H1 → package.json#name (scope stripped) → basename. Surfaces prompt.md/AGENTS.md/CLAUDE.md if present.
• spawn.ts — picks a free port, runs bun/pnpm/yarn/npm install when node_modules is missing, spawns the dev script with PORT=…, pipes child output into the Ink TUI, races healthcheck against child exit so crashes surface fast.
• prompt.ts — prefers authored prompt file → one-shot Anthropic call with project context → deterministic template fallback.
• register.ts — deterministic IDs from sha256(absPath) (conn_auto_<12hex> / vir_auto_<12hex>); creates HTTP connection + Virtual MCP, refreshes URL on re-runs, persists pinnedViews + layout under metadata.ui.
• index.ts — orchestrates the flow, builds chat URL <base>/<orgSlug>/<uuid>?virtualmcpid=<id>, opens browser by default.

CLI wiring

• New flags: --no-autostart, --no-open. Also respects DECOCMS_NO_AUTOSTART=1.
• serve.ts returns resolved port so cli.ts can pass it to autostart.
• New autostartProject panel in the Ink TUI shows project name, status, chat URL.
• Graceful shutdown kills tracked autostart child processes.

Demo

Run from a folder with an mcp/ subfolder:

▶ Autostart: CEO Agent — Deco ✓ ready
  Chat: http://localhost:3000/<slug>/<uuid>?virtualmcpid=vir_auto_…

[autostart] node_modules missing, running bun install…
[autostart] $ bun run start (cwd=…/mcp, PORT=3001)
[mcp] HTTP server listening on http://localhost:3001
[autostart] fetched 24 tool(s) from mcp
[autostart] system prompt source=file
[autostart] 3 UI tool(s) detected (default: Survey Company)
[autostart] registered agent vir=vir_auto_… conn=conn_auto_…
[autostart] open: http://localhost:3000/…

Test plan

• bun test apps/mesh/src/cli/autostart/ — 23 tests pass (detect, register idempotency, prompt fallbacks).
• bun run check — clean across all workspaces.
• bun run lint — 0 warnings, 0 errors.
• Manual end-to-end: cwd with mcp/ (custom MCP) — install runs, dev server boots, agent registered, chat URL renders.
• Manual: cwd without mcp/ — silent no-op, normal Studio boot.
• Manual: child crash surfaces real exit code instead of healthcheck timeout.
• Ctrl-C kills both Studio and the spawned MCP cleanly.
• Reviewer: try bunx decocms in a decocms init-scaffolded folder and confirm the autostarted agent has functional tools + UI.

Notes

• Autostart only fires in local mode (single admin/org seeded automatically). Cloud/multi-tenant deployments are unaffected.
• Idempotent: re-running in the same folder reuses the same connection + agent and just refreshes the URL if the port changed. Layout/pinned views are set on first registration only — happy to expand to refresh on re-run if desired.

🤖 Generated with Claude Code

---

Summary by cubic

Auto-starts a local MCP project when running bunx decocms, then opens Studio directly into a chat with a pre-registered Virtual MCP agent. This streamlines local workflows by detecting the project, starting its dev server, wiring tools, and launching the chat automatically.

• New Features

  • Detects MCP projects in <cwd>/mcp first, then cwd if it has MCP shape (api/main.*.ts or deps like @decocms/runtime, @modelcontextprotocol/sdk).
  • Installs deps if node_modules is missing, picks a free port, and runs the dev/start script via the correct package manager; logs are piped into the TUI and crashes surface fast.
  • Fetches tools and auto-pins UI tools exposing _meta.ui.resourceUri; sets the first as the default main view next to chat.
  • Builds the agent system prompt from prompt.md/AGENTS.md/CLAUDE.md when present; otherwise drafts via a small model with a template fallback if no provider key is set.
  • Registers a deterministic HTTP connection and Virtual MCP agent (conn_auto_<hex>, vir_auto_<hex>); re-runs reuse IDs and refresh the URL if the port changes.
  • Graceful shutdown stops any spawned MCP dev servers.

• Migration

  • Default: running bunx decocms in a repo with mcp/ will auto-open the agent chat.
  • Opt out with --no-autostart or DECOCMS_NO_AUTOSTART=1; skip opening the browser with --no-open.
  • Local mode only; cloud/multi-tenant deployments are unchanged.

^{Written for commit e9ccedc. Summary will update on new commits.}

[github-actions]

🧪 Benchmark

Should we run the Virtual MCP strategy benchmark for this PR?

React with 👍 to run the benchmark.

Reaction	Action
👍	Run quick benchmark (10 & 128 tools)

Benchmark will run on the next push after you react.

[github-actions]

Release Options

Suggested: Minor (2.298.0) — based on feat: prefix

React with an emoji to override the release type:

Reaction	Type	Next Version
👍	Prerelease	2.297.4-alpha.1
🎉	Patch	2.297.4
❤️	Minor	2.298.0
🚀	Major	3.0.0

Current version: 2.297.3

Note: If multiple reactions exist, the smallest bump wins. If no reactions, the suggested bump is used (default: patch).