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.
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_mcpWenn 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: continuity
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 -qDie 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.
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-workspaceDas 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.
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.
.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.
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.
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.
Apache License 2.0. Siehe LICENSE.
Initialize canonical scaffolding from an explicit caller-supplied brief.
The target directory must already exist under the configured workspace root. This never infers purpose, overwrites canonical state, or creates a work order.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| project_name | Yes | ||
| project_path | Yes | ||
| project_brief | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds valuable context: it never infers purpose, never overwrites canonical state, and never creates a work order. This goes beyond annotations and clarifies the side-effect profile, though it does not mention permission requirements or output format (which is covered by output schema).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose, followed by clear constraints and exclusions. There is no fluff or redundancy; every clause earns its place. It is an example of exemplary conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has four required parameters with zero schema descriptions and the description adds no parameter details. Usage guidance is only implicit. Though the output schema exists, the lack of any help on parameter semantics and selection criteria makes the description incomplete for an agent to invoke correctly without guessing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the tool description provides absolutely no explanation of any of the four required parameters. The parameters (project_id, project_name, project_path, project_brief) have only their names; no semantics are conveyed. The description fails entirely to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Initialize') and resource ('canonical scaffolding') and clarifies the deliberate, non-inferential nature, which distinguishes it from the getter siblings. It also gives explicit exclusions ('never infers purpose, overwrites canonical state, or creates a work order'), making the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear precondition ('target directory must already exist') and implies this is an initialization tool versus the getter siblings, but it does not explicitly state when to use this tool over alternatives or when not to use it. No explicit routing guidance is given, leaving the agent to infer from the sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return narrowly role-scoped canonical context for the requested role.
| Name | Required | Description | Default |
|---|---|---|---|
| role | Yes | ||
| project_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is known. The description adds that the context is 'canonical' and 'role-scoped', which provides some behavioral context, but it does not disclose specifics like error conditions, the exact structure of the response, or any side effects (though read-only implies none). It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence and is not verbose, but it sacrifices essential details for brevity. Phrases like 'narrowly role-scoped' add little concrete value. It could be more effective while remaining concise if it included the project_path parameter and a note on the sibling roles.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is incomplete for a tool that has direct role-specific siblings. It does not clarify the difference between get_bootstrap_context and get_orchestrator_bootstrap/get_worker_bootstrap, nor does it hint at the role of project_path. While an output schema exists (per context signals), the description still needs to convey what 'canonical context' means operationally. An agent would likely need to inspect sibling definitions to use this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden for parameter explanation. It mentions the 'role' concept but does not explain the allowed enum values or what 'project_path' refers to or its format. The role is only implied, and project_path is entirely absent from the description. This is a significant gap for a tool with only two required parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'return' and the resource 'canonical context' scoped by role. It implies a generic role-parameterized tool, but it does not explicitly distinguish itself from get_orchestrator_bootstrap and get_worker_bootstrap, which are direct role-specific alternatives. The word 'narrowly role-scoped' hints at the distinction but doesn't name the siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool instead of the sibling tools, particularly get_orchestrator_bootstrap and get_worker_bootstrap. The agent must infer the relationship from the role enum, which is not spelled out. There is no mention of exclusions, prerequisites, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return purpose, state, authority, issuance guidance, and review gates.
| Name | Required | Description | Default |
|---|---|---|---|
| project_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so read-only behavior is covered. The description lists returned fields, which is a small addition, but it does not explain any operational behavior such as error conditions, required permissions, or the meaning of the returned fields beyond their names. Minimal added context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and to the point, but it is little more than a list of return fields. It lacks any structural elements like a clear tool purpose or usage guidance. While concise, it is under-specified rather than efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although an output schema exists and likely details the return fields, the description offers no additional context about when to call this tool, how to interpret the output, or any side effects. For a tool with one parameter and a read-only annotation, the description is too sparse to be considered complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter project_path has zero description coverage (0%) in the input schema, and the description does not mention it at all. The description fails to compensate for the lack of schema-level documentation, leaving the agent to guess what project_path should be (path, ID, etc.).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states that the tool returns a list of items (purpose, state, authority, etc.) but lacks a specific action verb and does not clarify what 'orchestrator bootstrap' means or how it differs from siblings like get_worker_bootstrap. It is vague about the tool's core purpose beyond returning a set of fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No indication of when to use this tool versus the sibling tools (bootstrap_project, get_project_status, get_worker_bootstrap, get_bootstrap_context). The description provides no context, prerequisites, or explicit conditions for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return compact canonical status and explicit validation errors.
| Name | Required | Description | Default |
|---|---|---|---|
| project_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only behavior is covered. The description adds that the tool returns 'compact canonical status and explicit validation errors', which is a useful behavioral detail beyond the annotation. However, it does not describe any other side effects, prerequisites, or response nuances, so it adds limited context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the core action, and contains no extraneous wording. Every word contributes to meaning, making it appropriately concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return values are already defined. The main gaps are the lack of parameter explanation and missing usage guidance. For a simple one-parameter read-only tool, the description is minimally sufficient but not complete; an agent would still need to infer what 'project_path' means.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description completely fails to explain the required parameter 'project_path'. There is no indication of what the path refers to, its format, or constraints. The description provides zero value in clarifying the parameter beyond the schema's type/title.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Return') and resource (canonical status and validation errors). It is concise and clear about what the tool produces. However, it does not explicitly differentiate from sibling tools, though the siblings are bootstrap-related and thus functionally distinct in name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no explicit guidance on when to use this tool versus alternatives. It does not mention any exclusions or contexts. The purpose implicitly suggests use when needing status or validation info, but this is not stated, leaving the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return bounded worker entry context, execution gates, and stop behavior.
| Name | Required | Description | Default |
|---|---|---|---|
| project_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only safety profile is handled. The description gestures at behavior through 'execution gates' and 'stop behavior' but does not explain what those involve, any limits of 'bounded', or consequences beyond the fact that this is a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. Each phrase ('bounded worker entry context', 'execution gates', 'stop behavior') contributes a distinct aspect of the returned data, making it appropriately sized for a read-only tool with an output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema and readOnly annotation cover the return shape and safety profile. However, the description does not differentiate this tool from its sibling tools and leaves key terms ('bounded', 'execution gates') undefined, so the agent lacks enough context to confidently select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the tool description never mentions 'project_path'. The agent must infer from the bare property name that it is a path, with no guidance on format, required meaning, or how it relates to the worker bootstrap context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('Return') and a specific resource ('worker entry context'), and lists the returned facets: bounded context, execution gates, and stop behavior. It is distinguishable from 'get_orchestrator_bootstrap' by the word 'worker', though the terminology is somewhat unexpanded.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No statement tells the agent when to use this tool over the closely related siblings such as get_bootstrap_context or get_orchestrator_bootstrap. Usage is only implied by the word 'worker'; there are no exclusions, prerequisites, or alternative routing clues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0bootstrap_projectget_bootstrap_contextget_orchestrator_bootstrapget_project_statusget_worker_bootstrapScored across 5 tools
The getter tools for bootstrap context overlap: get_orchestrator_bootstrap, get_worker_bootstrap, and get_bootstrap_context all return role-scoped context, with the generic one likely covering the same ground. Only bootstrap_project is clearly distinct, while the getter separation by role is somewhat clear but not fully disambiguated.
All tool names are snake_case and follow a verb_noun pattern consistently. bootstrap_project stands out as an action, while the others use get_ prefix, but this is a typical and understandable distinction. The consistent prefix and structure make the naming predictable.
With only 5 tools, the surface is compact and well‑scoped for a control plane bootstrap service. Each tool appears to serve a distinct functional need without bloat, making the count appropriate for the apparent domain.
The tool set covers project bootstrap, status retrieval, and role‑specific context, but lacks lifecycle operations like listing or updating projects. The generic get_bootstrap_context seems redundant, and there are no endpoints for project deletion or modification, leaving notable gaps for a control plane.
Project memory, semantic code search, and grounded agent context.
One shared project for a team's coding agents: decisions, a task board and handoffs.
Shared project context for AI agents and teams: docs, tasks, and messages that stay current.
Give every project one workspace for its files, its team, and its AI agents.