Development environment

Prerequisites

mcut is a Bun workspace monorepo managed with Turbo.

• Use Bun 1.3.14.
• Package consumers should use Node 20.11 or newer.
• Run commands from the repository root unless a package README says otherwise.

Install

bun install

CI uses a frozen lockfile:

bun install --frozen-lockfile

Workspace layout

• packages/*: publishable @mcut/* SDK packages.
• examples/*: runnable examples for headless editing and MCP workflows.
• apps/studio: the local editor and shadcn registry source.
• apps/web: the marketing site and /docs implementation.
• docs/: maintainer and release process notes for the repository.

Run locally

Editor + MCP bridge

Run this from the repo root:

bun run setup   # once per worktree
bun run dev

bun run dev starts:

• Studio at http://localhost:3000 by default
• the local bridge on port 44737 by default, with WebSocket browser sync at /mcut-mcp and Streamable HTTP MCP at /mcp

In Conductor workspaces, Studio uses CONDUCTOR_PORT and the bridge uses CONDUCTOR_PORT + 1, so each workspace can run concurrently.

Open the connected editor URL printed by bun run dev. To print it again:

bun run scripts/mcut-local-dev.ts url

Then enable the mcut-live MCP server in Codex. Codex connects MCP tools to the bridge's HTTP endpoint — it does not start a second bridge. To print the MCP URL:

bun run scripts/mcut-local-dev.ts mcp-url

The package also exposes compatibility stdio entrypoints: mcut-mcp for file-backed projects, mcut-mcp-live for clients that should start their own live bridge, and mcut-bridge mcp for clients that cannot connect over HTTP.

Docs site only

bun run dev:web

Validate changes

Use the narrowest command that covers your change while working, then run the broader checks before opening a pull request.

bun run build
bun run typecheck
bun run test
bun run lint
bun run smoke:packages

Release validation runs the full package gate:

bun run release:check

release:check builds packages, typechecks, runs tests, runs package smoke checks, and validates package metadata.

Website docs

The website docs are written in apps/web/content/docs. The web app generates Fumadocs sources and static Markdown mirrors during build:

bun run --filter=mcut-web build

Use the web package checks when editing docs or site code:

bun run --filter=mcut-web typecheck
bun run --filter=mcut-web lint