# ControlPlane MCP

ControlPlane MCP v0.1 is a small local Python server for adopting an already-scoped project into a durable, repo-backed coordination pattern. Markdown and TOML in the target repository remain the database of record; MCP is only the interface.

## Install and run

Python 3.11 or newer is required. From this repository:

```powershell
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[test]"
```

The v0.1 package currently targets MCP Python SDK 2.0.x. Its dependency metadata
excludes 2.1 and later until their changed tool-exception rendering can be adopted
without weakening ControlPlane's stable actionable-error contract.

The server is scoped to one allowed workspace root at process startup. Set `CONTROLPLANE_ALLOWED_ROOT` to that existing directory, then launch the local stdio transport:

```powershell
$env:CONTROLPLANE_ALLOWED_ROOT = 'C:\path\to\allowed-workspace'
.\.venv\Scripts\python.exe -m controlplane_mcp
```

If the variable is omitted, the process working directory is the single allowed root. The target project directory must already exist beneath it. Relative project paths are resolved from that root; absolute paths are accepted only when their resolved location remains inside it.

For a generic MCP host, register these inputs in the host's own configuration:

- command: the environment's Python executable;
- arguments: `-m`, `controlplane_mcp`;
- working directory: this installed project or another suitable launch directory;
- environment: `CONTROLPLANE_ALLOWED_ROOT=<absolute allowed root>`;
- transport: stdio.

The generic stdio launch and all five tools are covered by automated tests, including a real subprocess integration test. For Codex, use a trusted project-local configuration where practical and confirm the server with `codex mcp list` or `/mcp`.

For exact Codex configuration, verification labels, and copyable fresh-thread adoption prompts, see [Documentation/CODEX_ADOPTION_RUNBOOK.md](Documentation/CODEX_ADOPTION_RUNBOOK.md).

## Tests

Install the test extra and run the full suite:

```powershell
.\.venv\Scripts\python.exe -m pip install -e ".[test]"
.\.venv\Scripts\python.exe -m pytest -q
```

The suite covers repository bootstrap and validation, role-scoped outputs,
resolved-path containment (including symlink/junction escape cases), MCP tool
metadata, and real STDIO startup/shutdown.

## Disposable rehearsal

The fixture and preparation helper build a fresh local Git repository, configure
the server project-locally, bootstrap the supplied demo brief, and verify that no
work order is fabricated:

```powershell
.\.venv\Scripts\python.exe scripts\prepare_codex_live_rehearsal.py `
  --workspace C:\path\to\new-disposable-workspace
```

The destination must not already exist. The script deliberately refuses to
overwrite it. See `examples/codex-live-rehearsal/PROJECT_BRIEF.md` for the neutral
demo purpose.

## Tools

- `bootstrap_project` is the only mutation. It accepts `project_path`, `project_id`, `project_name`, and non-empty caller-supplied `project_brief`. It creates only initial scaffolding and state, is idempotent for identical inputs, reports conflicts without overwriting, and never creates a work order.
- `get_project_status` returns compact canonical state and explicit validation errors.
- `get_orchestrator_bootstrap` returns project purpose, current state, authority, issuance guidance, and evidence-review gates.
- `get_worker_bootstrap` returns bounded worker context, first-order identity requirements, execution gates, evidence permissions, and stop/review behavior.
- `get_bootstrap_context` accepts only `orchestrator` or `worker` and returns structurally different, narrowly role-scoped context.

The four read tools are annotated read-only and closed-world. `bootstrap_project` is annotated non-destructive and idempotent. MCP annotations are client hints, not security controls.

## Canonical layout

```text
.controlplane/config.toml
Documentation/PROJECT_BRIEF.md
Documentation/CURRENT_STATE.md
WorkOrders/
Decisions/
Evidence/
```

The initial configuration stores only schema version and caller-supplied project identity. The Project Brief is written exactly as supplied. Initial `CURRENT_STATE` says no work is authorized. Empty work, decision, and evidence directories are created; no `WO-001` or other substantive order is invented.

## Minimal new-project example

With an allowed root `C:\work` and an existing empty directory `C:\work\sample`, call:

```json
{
  "name": "bootstrap_project",
  "arguments": {
    "project_path": "sample",
    "project_id": "sample",
    "project_name": "Sample Project",
    "project_brief": "# Sample Project\n\nBuild the caller-defined sample safely.\n"
  }
}
```

Calling again with exactly the same values returns an idempotent existing-state result. Different identity or brief content is a conflict and is never written over the canonical files.

## Authority and safety limits

Only an orchestrator transitions canonical work-order state. `READY` is not permission to execute, and worker completion is not acceptance. The canonical orchestrator and primary worker must be separate first-order, user-visible threads or tasks. A primary worker is a persistent project-level identity; work orders are temporary assignments. The worker bootstrap returns a manual lifecycle prompt only when no primary worker exists or replacement is explicitly recorded, and it reports worker reachability, start confirmation, assignment, and canonical activation separately.

Ordinary dispatch is one ACTIVE-plus-START message: the worker verifies the canonical ACTIVE commit, explicit START, identity, and scope, executes in that same turn, and next reports completion for orchestrator review. There is no acknowledgement-only turn.

v0.1 does not authenticate caller roles. Safety comes from a read-oriented API surface, one narrow initialization mutation, resolved-path containment, strict state validation, conflict refusal, and explicit authority protocol. Filesystem containment is checked before each operation, but v0.1 does not claim protection against an adversary racing filesystem links between validation and use.

## License

Apache License 2.0. See `LICENSE`.