ControlPlane MCP

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.

Instalación y ejecución

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_mcp

Si 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: Coding Tools MCP

Pruebas

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 -q

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

Ensayo desechable

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-workspace

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

Herramientas

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

Estructura canónica

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

Ejemplo mínimo de proyecto nuevo

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.

Límites de autoridad y seguridad

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.

Licencia

Apache License 2.0. Consulte LICENSE.