mcp-code-worker

English | 简体中文

mcp-code-worker is a TypeScript orchestration runtime for multi-model engineering workflows. It is designed to keep worker execution, repository context selection, deterministic validation, and local task artifacts under explicit control through a CLI and MCP server.

What this is

• A TypeScript/Node.js monorepo for orchestrating worker execution, validation, and task artifacts
• A CLI callable by humans or other coding agents through shell commands
• An MCP server exposing orchestration capabilities as structured tools
• A safe workflow engine that defaults to dry-run behavior
• A local execution layer that keeps repository reads, patch lifecycle, and worker qualification auditable

What this is not

• Not a Codex, OpenCode, Cursor, or Claude Code clone
• Not an interactive coding terminal or TUI
• Not a full chat interface
• Not a web UI product

Host relationship

In host-driven use cases such as Codex, cw stays as the controlled execution/runtime layer.

• The host agent stays responsible for user intent, final judgment, and acceptance.
• cw provides the controlled runtime: worker routing, repository context packs, deterministic validation, artifact persistence, and patch gates.
• The recommended host-facing path is cw_start_task and other host-managed tools.
• For narrow repo-grounded checks, prefer explicit file lists with strict file mode so CW fails fast instead of silently widening or skipping critical evidence.

Architecture diagram

Human / Coding Agent / CI / MCP Client
                |
                v
           cw CLI / MCP
                |
                v
   Orchestration Runtime Layer
      |            |         \
      v            v          v
 Worker Routing  Deterministic Tools  CW Storage / Artifacts
      |
      v
 Worker Models / Local Clients

Monorepo layout

packages/
  core/
  models/
  graph/
  tools/
  mcp-server/
  cli/
apps/
  playground/
examples/
  host-worker-basic/
docs/

Runtime requirements

• Node.js 22
• pnpm >=10

This repository targets actively maintained Node.js LTS releases only. CI currently validates Node 22. Other Node.js >=22 versions are best-effort until they are added to the CI matrix.

Install

Global npm install:

npm i -g mcp-code-worker
cw doctor
cw mcp list-tools

Development checkout:

node --version
pnpm install
pnpm build
pnpm exec cw doctor
pnpm exec cw setup --allow-write
pnpm exec cw doctor
pnpm typecheck
pnpm test

First run

pnpm exec cw setup --allow-write
pnpm exec cw doctor
pnpm exec cw mcp config

Internal-trial installation and MCP launch guidance lives in docs/install.md. The current official internal distribution shape is documented in docs/distribution.md.

Unless noted otherwise, read every cw ... example below as pnpm exec cw ... from the repository root for the current internal-trial install path.

Legacy repository-local .cw/ directories are unsupported and ignored by current builds.

cw setup creates user-scoped CW workspace storage under ~/.cw/workspaces/<workspace-id>/ by default:

• config.json
• workers.json
• worker-profiles.json
• audit/
• runs/

CLI usage

cw review repo --scope packages/graph
cw review diff --base main --head HEAD
cw review files --file packages/graph/src/index.ts --strict-files
cw validate --typecheck --lint --test
cw fix error --error-log-file ./tmp/tsc-error.log --scope packages/schema-codegen
cw task start --goal "Fix failing typecheck" --scope packages/core --typecheck --error-log-file ./tmp/tsc-error.log --run-fix --allow-write-session
cw task report <taskId>
cw cleanup runs
cw cleanup audit
cw models list
cw mcp config
cw mcp serve
cw mcp list-tools

cw review files --strict-files and cw_run_host_worker now expose debug evidence for host-managed worker runs, including requested files, selected files, worker metadata, and structured-output failure details.

Worker onboarding

Workers are not treated as automatically qualified just because a model endpoint exists.

Use onboarding evaluation before assigning real work:

cw worker interview --provider litellm --model qwen3-coder
cw worker interview --provider litellm --model qwen3-coder --save
cw worker list
cw worker profile litellm:qwen3-coder

The interview workflow evaluates:

• instruction following
• structured JSON output
• strict scope discipline
• summarization
• evidence-linked repository review
• refusal when mandatory evidence is missing
• code understanding
• simple TypeScript code generation
• confidence calibration

Interview results produce a WorkerCapabilityProfile that affects routing:

• active: worker can receive the task types it qualified for
• limited: worker is restricted to low-risk tasks and requires host review
• blocked: worker is excluded from production workflows and emits warnings

Example warning output:

Worker litellm:qwen3-coder failed onboarding evaluation.

Status: limited

Reasons:
- structured-output: Output failed schema validation.
- codegen: Generated code uses any.
- confidence-calibration: Worker reported high confidence on an ambiguous task.

Recommended action:
- Do not assign codegen tasks.
- Limit this worker to qualified low-risk tasks.
- Require host review for every accepted output.

If the worker is significantly worse, the profile becomes blocked and production routing should treat it as unavailable.

Persisting worker profiles

Use --save if you want to persist the interview result:

cw worker interview --provider litellm --model qwen3-coder --save

Saved profiles are written to:

~/.cw/workspaces/<workspace-id>/worker-profiles.json

You can inspect persisted profiles with:

cw worker list
cw worker profile litellm:qwen3-coder

Current behavior is conservative: if a workflow is started without an explicit profile object, the system can re-run the interview instead of blindly trusting an old capability record.

Worker registry flow

Register a reusable worker, evaluate it, and keep the assignment explicit:

cw worker register \
  --provider litellm \
  --model qwen3-coder \
  --base-url http://localhost:4000/v1 \
  --allow-write

cw worker interview --worker litellm:qwen3-coder --save

cw task start \
  --goal "Review this repository" \
  --worker litellm:qwen3-coder \
  --require-profile

cw audit list

This flow keeps worker selection local, auditable, and gated by a persisted capability profile while leaving the host in control of the overall task.

Repository review flow

Use the dedicated repository workflows for day-to-day engineering checks:

cw review repo --scope packages/graph
cw review diff --base main --head HEAD
cw review files --file packages/graph/src/index.ts
cw validate --typecheck --lint --test
cw fix error --error-log-file ./tmp/tsc-error.log --scope packages/core

These commands build repository context packs, read scoped files safely, and route deterministic validation into the review output.

Patch lifecycle

Patch handling is intentionally separated into proposal, inspection, and gated apply steps:

cw fix error --error-log-file ./tmp/tsc.log --scope packages/core

cw patch propose \
  --goal "Fix failing typecheck" \
  --scope packages/core

cw patch inspect ./tmp/candidate.patch

cw patch apply ./tmp/candidate.patch --dry-run

cw patch apply ./tmp/candidate.patch \
  --allow-write \
  --confirm-apply \
  --typecheck \
  --lint \
  --test

Safety constraints for patch lifecycle:

• Dry-run is the default.
• Applying a patch requires both an explicit write gate and an explicit confirmation gate.
• No command creates commits or PRs automatically.
• Patch actions emit audit events.
• Validation can run after apply, but failed validation does not auto-revert in this iteration.

Task sessions

Task sessions keep local review artifacts and resumable state under ~/.cw/workspaces/<workspace-id>/runs by default:

cw task start \
  --goal "Fix failing typecheck in packages/core" \
  --scope packages/core \
  --worker litellm:qwen3-coder \
  --require-profile \
  --typecheck \
  --lint \
  --propose-patch \
  --allow-write-session

cw task status <taskId>
cw task resume <taskId>
cw task report <taskId>

Patch apply is still a separate explicit gate even inside task resume:

cw task resume <taskId> \
  --apply-patch \
  --allow-write \
  --confirm-apply

Session persistence is separate from repository writes. --allow-write-session only permits CW session artifacts under runs/. It does not enable patch apply.

See docs/permissions.md for the full write-gate model.

MCP server usage

Start the stdio server:

cw mcp serve

Print a generic stdio config snippet for local MCP clients:

cw mcp config

List exposed tool names:

cw mcp list-tools

Environment variables

See .env.example.

• WORKER_MODEL_PROVIDER
• WORKER_MODEL_NAME
• WORKER_MODEL_BASE_URL
• WORKER_MODEL_API_KEY
• LITELLM_BASE_URL
• MCP_SERVER_NAME
• MCP_SERVER_VERSION
• LOG_LEVEL
• CW_ROOT_DIR
• CW_HOME_DIR
• CW_WORKER_CLIENT_COMMAND
• CW_DRY_RUN
• CW_ALLOW_WRITE
• CW_ALLOWED_COMMANDS

Config precedence

Runtime configuration resolves in this order:

1. CLI flags
2. Environment variables
3. ~/.cw/workspaces/<workspace-id>/config.json
4. built-in defaults

config.json no longer stores secret env-var names. Provide runtime secrets through fixed variables such as WORKER_MODEL_API_KEY.

Repository context settings in the user-scoped CW config.json control default ignoredPaths and strictFiles behavior for review, fix, patch, and task workflows.

Workflows

• host-worker-workflow: runs one explicit worker task under host control with answer-quality gates
• review-workflow: summarizes diff impact, risks, missing tests, and follow-up items
• fix-error-workflow: analyzes error logs and proposes safe validation-oriented fix steps
• patch-proposal-workflow: generates and inspects patch proposals without applying repository writes
• task-session-workflow: runs the end-to-end persisted task pipeline
• worker-interview-workflow: evaluates a worker model before production routing and generates a capability profile

How to run the basic example

Run pnpm exec tsx examples/host-worker-basic/src/index.ts to inspect the host-managed example workflow.

How to add a new worker

1. Add a worker class under packages/graph/src/workers.
2. Give it a clear WorkerCapability with Zod-backed schemas.
3. Declare the worker's supported task types so routing can enforce capability limits.
4. Route it from a workflow and keep its output reviewable.
5. Make sure onboarding interview results can constrain how it is assigned.
6. Add tests for the workflow path it affects.

How to add a new workflow

1. Create a workflow file under packages/graph/src/workflows.
2. Use LangGraph.js to model transitions explicitly.
3. Reuse core contracts and host-managed quality gates.
4. Expose it through the CLI or MCP only after tests exist.

How to add a new MCP tool

1. Add a tool definition in packages/mcp-server/src/tools.
2. Keep the handler thin and delegate to core workflow APIs.
3. Register it in packages/mcp-server/src/server.ts.
4. Add a registration test.

How to configure LiteLLM

Set WORKER_MODEL_PROVIDER=litellm, then provide:

• LITELLM_BASE_URL Use WORKER_MODEL_BASE_URL when worker traffic should target a non-default endpoint.

Safety model

• Default mode is dry-run.
• File writes require explicit policy allowance.
• Shell execution is allowlisted.
• Read-only git inspection commands such as git diff can still execute inside dry-run so review workflows keep working without enabling writes.
• cw setup, cw cleanup, worker registry writes, and task session persistence remain local-only inside CW-managed storage.
• Repository reads stay inside the repo root and block secret-like files such as .env and private keys.
• Dedicated review and fix flows return structured JSON and do not apply patches.
• Patch proposal, inspection, and apply are separated to keep write actions reviewable.
• If structured patch generation fails, the fallback proposal is marked as a blocked [PLACEHOLDER] artifact and cannot be applied.
• Validation commands go through the safe command path and can be inspected through audit logs.
• cw audit list exposes the local audit trail for workflow, file, and command events.
• cw cleanup runs and cw cleanup audit only delete local CW artifacts and never touch project source files.
• In host-driven flows, worker outputs are not final until the host accepts them.
• Workers must pass onboarding evaluation before they should receive production tasks.
• Workers that fail structured output or reliability checks are limited or blocked.
• Secrets are expected from environment variables and should never be logged.

See docs/permissions.md for the concrete permission layers and write-gate examples.

Dist smoke

Use both smoke layers before shipping CLI changes:

pnpm smoke
pnpm smoke:dist

Roadmap

• Expand workflow coverage and richer deterministic validations
• Add domain-specific orchestration packages later
• Add CI automation for checks and releases
• Keep the core focused on orchestration rather than UI