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:

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:

$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.

Related MCP server: Coding Tools MCP

Tests

Install the test extra and run the full suite:

.\.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:

.\.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

.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:

{
  "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.