ControlPlane MCP v0.1 es un pequeño servidor local de Python para adoptar un proyecto ya delimitado en un patrón de coordinación duradero respaldado por el repositorio. Markdown y TOML en el repositorio de destino siguen siendo la base de datos de referencia; MCP es solo la interfaz.
Se requiere Python 3.11 o superior. Desde este repositorio:
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[test]"El paquete v0.1 apunta actualmente al MCP Python SDK 2.0.x. Sus metadatos de dependencia excluyen 2.1 y versiones posteriores hasta que se pueda adoptar el nuevo renderizado de excepciones de herramientas sin debilitar el contrato estable de errores accionables de ControlPlane.
El servidor está limitado a una única raíz de espacio de trabajo permitida al inicio del proceso. Establezca CONTROLPLANE_ALLOWED_ROOT en ese directorio existente y luego lance el transporte stdio local:
$env:CONTROLPLANE_ALLOWED_ROOT = 'C:\path\to\allowed-workspace'
.\.venv\Scripts\python.exe -m controlplane_mcpSi se omite la variable, el directorio de trabajo del proceso es la única raíz permitida. El directorio del proyecto de destino debe existir ya bajo ella. Las rutas relativas de proyecto se resuelven desde esa raíz; las rutas absolutas solo se aceptan cuando su ubicación resuelta permanece dentro de ella.
Para un host MCP genérico, registre estas entradas en la configuración del propio host:
comando: el ejecutable de Python del entorno;
argumentos: -m, controlplane_mcp;
directorio de trabajo: este proyecto instalado u otro directorio de lanzamiento adecuado;
entorno: CONTROLPLANE_ALLOWED_ROOT=<absolute allowed root>;
transporte: stdio.
El lanzamiento stdio genérico y las cinco herramientas están cubiertos por pruebas automatizadas, incluida una prueba de integración real con subprocesos. Para Codex, use una configuración local de proyecto de confianza cuando sea práctico y confirme el servidor con codex mcp list o /mcp.
Para la configuración exacta de Codex, las etiquetas de verificación y los mensajes de adopción copiables para hilos nuevos, consulte Documentation/CODEX_ADOPTION_RUNBOOK.md.
Related MCP server: continuity
Instale el extra de pruebas y ejecute la suite completa:
.\.venv\Scripts\python.exe -m pip install -e ".[test]"
.\.venv\Scripts\python.exe -m pytest -qLa suite cubre el arranque y la validación del repositorio, las salidas con ámbito de rol, la contención de rutas resueltas (incluidos los casos de escape mediante symlink/junction), los metadatos de herramientas MCP y el arranque/cierre real de STDIO.
El fixture y el asistente de preparación crean un repositorio Git local nuevo, configuran el servidor a nivel de proyecto, inicializan el brief de demostración proporcionado y verifican que no se fabrica ninguna orden de trabajo:
.\.venv\Scripts\python.exe scripts\prepare_codex_live_rehearsal.py `
--workspace C:\path\to\new-disposable-workspaceEl destino no debe existir ya. El script se niega deliberadamente a sobrescribirlo. Consulte examples/codex-live-rehearsal/PROJECT_BRIEF.md para conocer el propósito neutral de la demo.
bootstrap_project es la única mutación. Acepta project_path, project_id, project_name y un project_brief no vacío proporcionado por el llamador. Crea solo el andamiaje y el estado iniciales, es idempotente para entradas idénticas, informa conflictos sin sobrescribir y nunca crea una orden de trabajo.
get_project_status devuelve el estado canónico compacto y errores de validación explícitos.
get_orchestrator_bootstrap devuelve el propósito del proyecto, el estado actual, la autoridad, las pautas de emisión y las compuertas de revisión de evidencia.
get_worker_bootstrap devuelve el contexto de worker acotado, los requisitos de identidad de primer orden, las compuertas de ejecución, los permisos de evidencia y el comportamiento de detención/revisión.
get_bootstrap_context acepta solo orchestrator o worker y devuelve un contexto estructuralmente diferente y estrictamente limitado al rol.
Las cuatro herramientas de lectura están anotadas como de solo lectura y de mundo cerrado. bootstrap_project está anotada como no destructiva e idempotente. Las anotaciones MCP son sugerencias para el cliente, no controles de seguridad.
.controlplane/config.toml
Documentation/PROJECT_BRIEF.md
Documentation/CURRENT_STATE.md
WorkOrders/
Decisions/
Evidence/La configuración inicial almacena solo la versión del esquema y la identidad del proyecto proporcionada por el llamador. El Project Brief se escribe exactamente como se suministró. El CURRENT_STATE inicial indica que no se autoriza ningún trabajo. Se crean directorios vacíos de trabajo, decisión y evidencia; no se inventa ninguna WO-001 ni otra orden sustantiva.
Con una raíz permitida C:\work y un directorio vacío existente C:\work\sample, invoque:
{
"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"
}
}Volver a invocarlo con exactamente los mismos valores devuelve un resultado idempotente de estado existente. Una identidad o un contenido de brief diferentes suponen un conflicto y nunca se escriben sobre los archivos canónicos.
Solo un orquestador transiciona el estado canónico de las órdenes de trabajo. READY no es permiso para ejecutar, y la finalización del worker no es una aceptación. El orquestador canónico y el worker principal deben ser hilos o tareas separados de primer orden y visibles para el usuario. Un worker principal es una identidad persistente a nivel de proyecto; las órdenes de trabajo son asignaciones temporales. La inicialización del worker devuelve un aviso manual de ciclo de vida solo cuando no existe ningún worker principal o se ha registrado explícitamente un reemplazo, e informa por separado de la accesibilidad del worker, la confirmación de inicio, la asignación y la activación canónica.
El despacho ordinario es un único mensaje ACTIVE más START: el worker verifica el commit ACTIVE canónico, el START explícito, la identidad y el alcance, ejecuta en ese mismo turno y a continuación informa de la finalización para la revisión del orquestador. No existe un turno solo de acuse de recibo.
v0.1 no autentica los roles del llamador. La seguridad proviene de una superficie de API orientada a la lectura, una mutación de inicialización limitada, la contención de rutas resueltas, la validación estricta de estado, el rechazo de conflictos y un protocolo de autoridad explícito. La contención del sistema de archivos se comprueba antes de cada operación, pero v0.1 no afirma ofrecer protección contra un adversario que genere una carrera en los enlaces del sistema de archivos entre la validación y el uso.
Apache License 2.0. Consulte 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.