ZCP — Zerops Control Plane

MCP server that gives an LLM full control over a Zerops project. Runs as a zcp@1 service inside the project it manages.

Integration model

User ←→ Claude Code (terminal in code-server) ←→ ZCP (MCP over STDIO) ←→ Zerops API
                                                                        ←→ sibling services (SSH/SSHFS over VXLAN)

The user opens code-server on the zcp service subdomain. Claude Code is preconfigured with ZCP as its MCP server. The user describes what they want, the LLM figures out what to do, calls ZCP tools to make it happen.

ZCP authenticates once at startup (env var or zcli token), discovers which project it's in, and exposes everything as MCP tools. The LLM sees a system prompt with the environment concept, current service classification, and available workflows — the LLM decides what to do.

Related MCP server: sprklai/zenii

What the LLM can do

Through ZCP tools, the LLM can:

• Bootstrap a full stack — from "I need a Node.js app with PostgreSQL" to running services with health checks, in one conversation

• Deploy code — writes files via SSHFS mount, triggers build pipeline via SSH push

• Debug — read logs, check events, verify service health

• Scale — adjust CPU, RAM, disk, container count

• Configure — manage env vars, subdomains, shared storage connections

• Monitor — discover services, check statuses

Architecture

cmd/zcp/main.go → internal/server  → MCP tools  → internal/ops       → internal/platform → Zerops API
                                                 → internal/workflow   (envelope → plan → atoms)
                                                 → internal/knowledge  (on-demand guides)
                                                 → internal/auth       (token resolution)

Pipeline

Every workflow-aware tool response runs through four stages:

1. ComputeEnvelope — reads project state, ServiceMetas, live services, active sessions; produces a typed StateEnvelope.

2. BuildPlan — pure envelope-shape dispatch; returns Plan{Primary, Secondary, Alternatives}. Each NextAction names a tool + args + rationale.

3. Synthesize — filters the atom corpus (internal/content/atoms/*.md) against envelope axes (phases, modes, strategies, runtimes, environments, routes, steps, deployStates). For byte-equal envelopes the synthesized guidance is byte-identical.

4. RenderStatus — emits the markdown status block shown to the LLM.

The primary MCP entry is zerops_workflow action="start" workflow="develop" — every task that changes code or deploys opens a develop work session. action="status" is the canonical recovery call when state is unclear (after compaction or between tasks). workflow="bootstrap" creates or adopts infrastructure; workflow="cicd" and workflow="export" are stateless and return guidance only.

Direct tools (no workflow session): zerops_discover, zerops_logs, zerops_events, zerops_knowledge, zerops_env, zerops_manage, zerops_scale, zerops_subdomain, zerops_verify. Workflow-gated: zerops_deploy (needs adopted services), zerops_mount and zerops_import (need an active workflow session).

Workflows

Immediate (stateless, no session)

• cicd — generates pipeline config guidance.

• export — generates export guidance.

Orchestrated (session-tracked)

• bootstrap — 3 steps (discover / provision / close). Infrastructure-only; writes ServiceMetas + zerops.yaml scaffolding for verification. No application code, no first deploy.

• develop — per-PID Work Session. Scaffolds first deploy (deployStates=never-deployed branch) or edits the loop (deployStates=deployed branch). Auto-closes when every scope service has a succeeded deploy + passed verify.

Bootstrap workflow

Bootstrap opens with a two-call discovery+commit: the first call (no route argument) returns routeOptions[] ranked resume > adopt > classic. The second call supplies route=<chosen> and opens the session.

┌──────────┐   ┌───────────┐   ┌───────┐
│ DISCOVER │──▶│ PROVISION │──▶│ CLOSE │
└──────────┘   └───────────┘   └───────┘

Provision is single-shot. If the checker fails, the session surfaces the error and escalates to the user; bootstrap does not iterate. Generate + deploy work for application code is owned by the develop workflow's first-deploy branch.

Plan model

The discover step validates a ServicePlan:

ServicePlan
  └─ Targets[]
       ├─ Runtime
       │    ├─ DevHostname      "appdev"
       │    ├─ Type             "nodejs@22"
       │    ├─ BootstrapMode    "standard" | "dev" | "simple"
       │    └─ StageHostname()  → "appstage" (auto-derived for standard mode)
       └─ Dependencies[]
            ├─ Hostname       "db"
            ├─ Type           "postgresql@16"
            ├─ Mode           "NON_HA" (auto-defaulted)
            └─ Resolution     "CREATE" | "EXISTS" | "SHARED"

Standard mode (default): runtime gets a dev+stage pair. Dev uses deployFiles: [.] and startWithoutCode: true; stage builds from committed code (cross-deploy from dev or git-push).

Dev mode: single dev service, no stage. For prototyping and quick iterations.

Simple mode: single service with real start command + healthCheck.

Develop workflow

Every task that changes code or deploys runs under a per-PID Work Session at .zcp/state/work/{pid}.json. The session records intent + services in scope + a capped history of deploy/verify attempts; it does not copy strategy, mode, or service status (those are read fresh from ServiceMeta + API on every call).

Two branches, selected by deployStates:

• never-deployed — first-deploy branch atoms scaffold zerops.yaml, write application code, run the first deploy, stamp FirstDeployedAt. First deploy always uses the default self-deploy mechanism regardless of ServiceMeta.CloseDeployMode.

• deployed — edit-loop branch; per-service close-mode (auto / git-push / manual) drives the atoms that fire at develop close.

Auto-close fires when every scope service has Deploys[last].Success=true AND Verifies[last].Success=true. Failure-path iteration tiers (diagnose → systematic → STOP) are surfaced via BuildIterationDelta; defaultMaxIterations=5 caps the session, after which it closes with CloseReason=iteration-cap.

ServiceMeta

ServiceMeta is the per-service record of how this project uses a given hostname. Stored at {stateDir}/services/{hostname}.json, one file per runtime.

Close-mode + git-push state + build-integration are read fresh from disk on every workflow turn — never cached in session state. The git-push deploy strategy gates on the working tree carrying a commit (per spec D2b), not on FirstDeployedAt.

Deploy mechanics

ZCP sits on the same VXLAN network as every service in the project. Deploy path:

1. SSHFS mount (container environment) gives filesystem access to the target — code lives at /var/www/{hostname}/.

2. LLM writes code + zerops.yaml directly to the mount path.

3. zerops_deploy SSHes into the target and runs zcli push.

4. The Zerops build pipeline picks it up.

Local environment has no SSHFS mount: code lives in the user's working directory, zerops_deploy runs zcli push against the stage service.

Dev services use deployFiles: [.] and startWithoutCode: true. Stage services build from committed code. PHP runtimes omit start: entirely (implicit-webserver).

Knowledge system

Platform knowledge comes from two sources baked into the binary plus one fetched at runtime:

• Atom corpus (internal/content/atoms/*.md) — axis-tagged knowledge synthesized per turn by the workflow pipeline. Never delivered wholesale.

• Knowledge guides, themes, bases (internal/knowledge/) — pulled on demand via zerops_knowledge by topic or axis tuple.

• Live schemas — zerops.yaml and import.yaml JSON schemas fetched from the Zerops API at runtime, cached 24h. Provide authoritative enum values (service types, build bases, run bases, modes, policies) and field descriptions.

Guide sync

Guide markdown is gitignored — pulled from zeropsio/docs before build, edits pushed back as PRs.

zcp sync pull guides                        # All guides from zeropsio/docs (GitHub API)
zcp sync push guides                        # Creates PR on zeropsio/docs

No local clones — everything goes through gh CLI and the GitHub API. Config: .sync.yaml.

Authoring mode (maintainers)

Authoring tools (zerops_recipe — build a new recipe; zerops_port — port foreign OSS into a curated recipe) are gated behind ZCP_AUTHORING=1 — single owner runtime.Info.Authoring drives both the MCP tool surface and zcp init's AGENTS.md. To enable on a zcp container:

1. Set ZCP_AUTHORING=1 on the zcp service env — in the GUI, or just tell zcp to do it.

2. Restart the container — the MCP server comes up with the authoring tools registered.

3. Run zcp init — regenerates AGENTS.md with the authoring guidance.

The restart is needed because VS Code's code-server caches its env at boot. (A plain terminal opened after step 1 already inherits the new var, so there you can skip it.)

Boundary laws + contracts: docs/spec-authoring-boundary.md.

Session persistence

State lives at .zcp/state/:

Bootstrap sessions survive process restart and can be reattached via route=resume. Work sessions are per-process — they die with their PID; code work survives in git/disk.

Development

go test ./... -count=1 -short    # All tests, fast
go test ./... -count=1 -race     # All tests with race detection
go build -o bin/zcp ./cmd/zcp    # Build
make lint-fast                   # Lint (~3s)

E2E tests need a real Zerops project: go test ./e2e/ -tags e2e (requires ZCP_API_KEY or zcli login).

Release

make release        # Minor bump (e.g. v8.104.0 → v8.105.0)
make release-patch  # Patch bump (e.g. v8.104.0 → v8.104.1)

Both run tests before tagging. If tests fail, the release is aborted. Requires a clean worktree (no uncommitted changes to tracked files; untracked files are ignored).