ControlPlane MCP

ControlPlane MCP v0.1 ist ein kleiner lokaler Python-Server, um ein bereits abgegrenztes Projekt in ein dauerhaftes, repository-gestütztes Koordinationsmuster zu überführen. Markdown und TOML im Ziel-Repository bleiben die maßgebliche Datenbank; MCP ist nur die Schnittstelle.

Installation und Ausführung

Python 3.11 oder neuer ist erforderlich. Aus diesem Repository:

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

Das v0.1-Paket zielt derzeit auf das MCP Python SDK 2.0.x. Seine Abhängigkeitsmetadaten schließen 2.1 und höher aus, bis deren geänderte Darstellung von Tool-Ausnahmen übernommen werden kann, ohne den stabilen, handlungsorientierten Fehlervertrag von ControlPlane zu schwächen.

Der Server ist beim Prozessstart auf ein einziges erlaubtes Arbeitsbereichsverzeichnis beschränkt. Setzen Sie CONTROLPLANE_ALLOWED_ROOT auf dieses vorhandene Verzeichnis und starten Sie dann den lokalen stdio-Transport:

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

Wenn die Variable weggelassen wird, ist das Arbeitsverzeichnis des Prozesses das einzige erlaubte Wurzelverzeichnis. Das Zielprojektverzeichnis muss bereits darunter existieren. Relative Projektpfade werden von dieser Wurzel aus aufgelöst; absolute Pfade werden nur akzeptiert, wenn ihr aufgelöster Speicherort darin bleibt.

Für einen generischen MCP-Host registrieren Sie diese Eingaben in der eigenen Konfiguration des Hosts:

• Befehl: die Python-Ausführbare Datei der Umgebung;

• Argumente: -m, controlplane_mcp;

• Arbeitsverzeichnis: dieses installierte Projekt oder ein anderes geeignetes Startverzeichnis;

• Umgebung: CONTROLPLANE_ALLOWED_ROOT=<absolutes erlaubtes Wurzelverzeichnis>;

• Transport: stdio.

Der generische stdio-Start und alle fünf Werkzeuge sind durch automatisierte Tests abgedeckt, einschließlich eines echten Subprozess-Integrationstests. Für Codex verwenden Sie, wo praktikabel, eine vertrauenswürdige projektspezifische Konfiguration und bestätigen den Server mit codex mcp list oder /mcp.

Für die genaue Codex-Konfiguration, Verifikationskennzeichnungen und kopierbare Aufforderungen zur Übernahme in neuen Threads siehe Documentation/CODEX_ADOPTION_RUNBOOK.md.

Related MCP server: Coding Tools MCP

Tests

Installieren Sie das Test-Extra und führen Sie die vollständige Suite aus:

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

Die Suite umfasst Repository-Bootstrap und -Validierung, rollenspezifische Ausgaben, Containment aufgelöster Pfade (einschließlich Symlink/Junction-Escape-Fälle), MCP-Tool-Metadaten und echten STDIO-Start/Stopp.

Wegwerf-Probe

Das Fixture und der Vorbereitungshelfer erstellen ein frisches lokales Git-Repository, konfigurieren den Server projektspezifisch, bootstrappen das mitgelieferte Demo-Briefing und verifizieren, dass kein Arbeitsauftrag erfunden wird:

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

Das Ziel darf nicht bereits existieren. Das Skript weigert sich bewusst, es zu überschreiben. Siehe examples/codex-live-rehearsal/PROJECT_BRIEF.md für den neutralen Demo-Zweck.

Werkzeuge

• bootstrap_project ist die einzige Mutation. Es akzeptiert project_path, project_id, project_name und ein nicht leeres, vom Aufrufer geliefertes project_brief. Es erstellt nur anfängliches Gerüst und Zustand, ist für identische Eingaben idempotent, meldet Konflikte ohne Überschreiben und erstellt niemals einen Arbeitsauftrag.

• get_project_status gibt kompakten kanonischen Zustand und explizite Validierungsfehler zurück.

• get_orchestrator_bootstrap gibt Projektzweck, aktuellen Zustand, Autorität, Ausstellungsrichtlinien und Evidenzprüf-Gates zurück.

• get_worker_bootstrap gibt begrenzten Worker-Kontext, Anforderungen an die Identität erster Ordnung, Ausführungs-Gates, Evidenzberechtigungen und Stopp-/Überprüfungsverhalten zurück.

• get_bootstrap_context akzeptiert nur orchestrator oder worker und gibt strukturell unterschiedlichen, eng rollenspezifischen Kontext zurück.

Die vier Lese-Werkzeuge sind als schreibgeschützt und geschlossene Welt annotiert. bootstrap_project ist als nicht destruktiv und idempotent annotiert. MCP-Annotationen sind Client-Hinweise, keine Sicherheitskontrollen.

Kanonisches Layout

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

Die anfängliche Konfiguration speichert nur die Schema-Version und die vom Aufrufer gelieferte Projektidentität. Das Projekt-Briefing wird genau wie geliefert geschrieben. Der anfängliche CURRENT_STATE besagt, dass keine Arbeit autorisiert ist. Leere Arbeits-, Entscheidungs- und Evidenzverzeichnisse werden erstellt; kein WO-001 oder anderer substanzieller Auftrag wird erfunden.

Minimales Beispiel für ein neues Projekt

Mit einem erlaubten Wurzelverzeichnis C:\work und einem vorhandenen leeren Verzeichnis C:\work\sample rufen Sie auf:

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

Ein erneuter Aufruf mit genau denselben Werten liefert ein idempotentes Ergebnis des bestehenden Zustands. Unterschiedliche Identität oder anderer Briefing-Inhalt ist ein Konflikt und wird niemals über die kanonischen Dateien geschrieben.

Autoritäts- und Sicherheitsgrenzen

Nur ein Orchestrator überführt den kanonischen Arbeitsauftragszustand. READY ist keine Erlaubnis zur Ausführung, und der Abschluss eines Workers ist keine Annahme. Der kanonische Orchestrator und der primäre Worker müssen getrennte Threads oder Aufgaben erster Ordnung sein, die für den Benutzer sichtbar sind. Ein primärer Worker ist eine dauerhafte Identität auf Projektebene; Arbeitsaufträge sind temporäre Zuweisungen. Der Worker-Bootstrap gibt nur dann eine manuelle Lebenszyklus-Aufforderung zurück, wenn kein primärer Worker existiert oder ein Ersatz explizit aufgezeichnet ist, und er meldet Worker-Erreichbarkeit, Startbestätigung, Zuweisung und kanonische Aktivierung getrennt.

Der normale Versand ist eine ACTIVE-plus-START-Nachricht: Der Worker verifiziert den kanonischen ACTIVE-Commit, explizites START, Identität und Umfang, führt in derselben Runde aus und meldet dann den Abschluss zur Überprüfung durch den Orchestrator. Es gibt keine reine Bestätigungsrunde.

v0.1 authentifiziert keine Aufruferrollen. Sicherheit ergibt sich aus einer leseorientierten API-Oberfläche, einer schmalen Initialisierungsmutation, Containment aufgelöster Pfade, strenger Zustandsvalidierung, Konfliktverweigerung und einem expliziten Autoritätsprotokoll. Dateisystem-Containment wird vor jeder Operation geprüft, aber v0.1 beansprucht keinen Schutz gegen einen Angreifer, der Dateisystem-Links zwischen Validierung und Verwendung umgeht.

Lizenz

Apache License 2.0. Siehe LICENSE.