Deploy

Phase 0 Status: This document describes target behavior. No Colibri TypeScript code exists yet. Implementation begins at Phase 0 once src/server.ts (P0.2.1) and data/colibri.db (P0.2.2) are created.

Deployment shape

Phase 0 Colibri is a single-node stdio MCP server. It has no network listener, no HTTP port, no clustering. It is launched by an MCP client (VS Code, Claude Code, an agent runtime) as a child process, speaks JSON-RPC over stdin/stdout, and exits when the client disconnects.

This is deliberate. Per ADR-004 and ADR-005, Phase 0 ships the three axes as specified and defers auth, rate limiting, watchers, remote transport, and agent spawning to Phase 1+. Deploying Phase 0 therefore means “arrange for a client to run the binary with the right environment and DB path.” Nothing else is in scope.

Entry point 

node dist/server.js

dist/server.js is the TypeScript compile output of src/server.ts. Running the source directly (tsx src/server.ts, node --loader …) is fine in development but production deployments should run the compiled JS to avoid a TS toolchain dependency at boot.

Environment variables

Phase 0 reads only the COLIBRI_* namespace. Four variables are defined:

Variable Values Default Meaning
COLIBRI_MODE FULL | READONLY | TEST | MINIMAL FULL Runtime mode (see below)
COLIBRI_DB_PATH absolute or relative path ./data/colibri.db SQLite database path
COLIBRI_LOG_LEVEL ERROR | WARN | INFO | DEBUG INFO Stderr log verbosity
COLIBRI_SESSION_ID string (e.g. s7-r75-…) generated at boot Stable session id; overrides boot-time generation

Logs go to stderr — never stdout. Stdout is reserved for the MCP JSON-RPC framing.

Runtime modes

COLIBRI_MODE selects one of four behaviors:

Mode Reads DB Writes DB Registered tools Use case
FULL yes yes all 14 shipped tools Normal laptop / dev operation
READONLY yes no read-only subset Remote viewer, diagnostics
TEST yes (fresh temp DB) yes all 14 shipped tools CI runs, integration tests
MINIMAL yes no server_ping + server_health only Smoke check, first connect

The 14 shipped tools are defined in docs/reference/mcp-tools-phase-0.md per ADR-004 (R75 Wave H amendment; the original 19-tool plan is retained in that doc for heritage reference).

Boot sequence

When node dist/server.js starts, it runs the six-step boot defined in docs/2-plugin/boot.md:

  1. Config load. Read COLIBRI_* env, apply defaults, validate via Zod schema. Fatal if COLIBRI_MODE is unknown or COLIBRI_DB_PATH is not writable (except in READONLY).
  2. DB open. Open SQLite at COLIBRI_DB_PATH in WAL mode. Create colibri.db-wal and colibri.db-shm alongside. Fail fast if the file is locked by another process (Phase 0 is single-writer).
  3. Schema validate. Compare runtime schema against src/db/schema.sql. If version differs, refuse to start and surface a clear error — Phase 0 does not silent-migrate.
  4. Middleware register. Install the 5-stage α chain: tool-lock → schema-validate → audit-enter → dispatch → audit-exit. This is the full Phase 0 middleware stack; any layer beyond these five is deferred.
  5. Tools list. Register the 14 shipped Phase 0 tools. Advertise them in the MCP tools/list response. Note: capabilitiesFor(mode) is read at construction time but is currently advisory in Phase 0 — every registered tool is exposed in every mode regardless of the active capability record. Enforcement at registration time is a Phase 1 follow-up.
  6. MCP stdio handshake. Bind StdioServerTransport, handshake with the client, begin accepting JSON-RPC. The handshake must happen before any heavy work — otherwise the client times out.

MCP client wiring

Clients discover the server through their own MCP config. The canonical Phase 0 template lives at .vscode/mcp-settings.example.json:

{
  "mcpServers": {
    "colibri": {
      "command": "node",
      "args": ["dist/server.js"],
      "env": {
        "COLIBRI_MODE": "FULL",
        "COLIBRI_DB_PATH": "./data/colibri.db",
        "COLIBRI_LOG_LEVEL": "INFO"
      }
    }
  }
}

Copy it to .vscode/mcp-settings.json (gitignored), edit paths, and the client launches Colibri automatically.

For Claude Code specifically, the same mcpServers block goes into that client’s MCP config file — the command / args / env shape is identical.

Deployment profiles

Three profiles cover Phase 0 needs:

Laptop (default) 

{
  "COLIBRI_MODE": "FULL",
  "COLIBRI_DB_PATH": "./data/colibri.db",
  "COLIBRI_LOG_LEVEL": "INFO"
}

Full read + write, all 14 shipped tools, local DB. This is what a developer runs daily.

CI 

{
  "COLIBRI_MODE": "TEST",
  "COLIBRI_DB_PATH": "./data/test-run.db",
  "COLIBRI_LOG_LEVEL": "DEBUG"
}

TEST mode provisions a fresh DB per run from src/db/schema.sql so tests start from known state. DEBUG logs make CI failure triage easier.

Remote-dev (readonly) 

{
  "COLIBRI_MODE": "READONLY",
  "COLIBRI_DB_PATH": "/mnt/snapshot/colibri.db",
  "COLIBRI_LOG_LEVEL": "WARN"
}

For inspecting a production snapshot without risking writes. The DB can be a read-only mount or a restored backup; writes are refused at the middleware layer, not just discouraged.

What Phase 0 does NOT deploy

The following are explicitly deferred and have no Phase 0 configuration knob. Do not try to configure them:

Capability Phase Reason
HTTP listener / network port Phase 1+ Stdio-only per S17 §2
File watcher / hot reload Phase 1+ No watcher in Phase 0 per S17 §2
Auth (JWT, ACL, OAuth) Phase 2+ per docs/spec/s13-hardening.md Single-user laptop model in Phase 0
Rate limiting Phase 2+ per spec/s13-hardening.md Single-client model in Phase 0
Multi-tenant / multi-user Phase 3+ Out of scope
Agent spawn / orchestration tools Phase 1.5 per ADR-005 agent_spawn, agent_status, agent_list not in the 14 shipped tools
P2P peer sync Phase 3+ No peers in Phase 0
Health-check interval daemon Phase 1+ server_health is an on-demand tool in Phase 0, not a periodic probe

Shutdown

Graceful shutdown is driven by SIGINT (Ctrl-C in the client, or the client closing its end of stdio).

The signal handler runs in order:

  1. Stop accepting new JSON-RPC requests.
  2. Finish the in-flight tool call (if any) to its natural end.
  3. Call thought_record for the final session reflection.
  4. Call merkle_finalize to seal the session’s Merkle tree. This must come after the last thought_record (per the writeback protocol) so the reflection is anchored.
  5. Checkpoint the WAL (PRAGMA wal_checkpoint(TRUNCATE);) so data/colibri.db is self-contained on exit.
  6. Close the DB handle.
  7. Exit with code 0.

A killed process (SIGKILL, power loss) skips all of the above. On next boot, SQLite WAL recovery replays committed writes; in-flight audit or Merkle state may be partial and will be surfaced by audit_verify_chain at the next verification step.

Troubleshooting

Common deploy-time symptoms (boot failure, stdio handshake timeout, DB lock, schema mismatch) are catalogued in the sister guide:

Heritage note

Prior AMS-era documentation referenced AMS_* environment variables (AMS_JWT_SECRET, AMS_PORT, AMS_WATCH_MODE, AMS_RATE_LIMIT_MAX, AMS_HEALTH_INTERVAL, etc.). These came from the pre-R53 AMS donor and are not read by Phase 0 code. The auth / rate-limit / watcher / HTTP-port capabilities they configured are deferred to Phase 2+ per docs/spec/s13-hardening.md. If a runbook tells you to set an AMS_* variable, it is HERITAGE and does not apply. Use the COLIBRI_* table above, or — if the knob does not appear there — understand that the feature does not ship in Phase 0.

Back to top

Colibri — documentation-first MCP runtime. Apache 2.0 + Commons Clause.

This site uses Just the Docs, a documentation theme for Jekyll.