ControlPlane MCP

ControlPlane MCP v0.1 是一个小型本地 Python 服务器，用于将已确定范围的项目纳入一种持久的、基于仓库的协调模式。目标仓库中的 Markdown 和 TOML 文件仍然是权威数据库；MCP 只是接口。

安装与运行

需要 Python 3.11 或更高版本。从本仓库：

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

v0.1 包当前以 MCP Python SDK 2.0.x 为目标。其依赖元数据排除了 2.1 及更高版本，直到其变更后的工具异常渲染方式可以在不削弱 ControlPlane 稳定的可操作错误契约的前提下被采用。

服务器在进程启动时限定为一个允许的工作区根目录。将 CONTROLPLANE_ALLOWED_ROOT 设置为该已存在的目录，然后启动本地 stdio 传输：

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

如果省略该变量，则进程工作目录即为唯一的允许根目录。目标项目目录必须已存在于其下。相对项目路径从该根目录解析；绝对路径仅在其解析后的位置仍位于根目录内部时才被接受。

对于通用 MCP 主机，请在主机自身的配置中注册以下输入：

• command：环境的 Python 可执行文件；

• arguments：-m、controlplane_mcp；

• working directory：本已安装项目或其他合适的启动目录；

• environment：CONTROLPLANE_ALLOWED_ROOT=<绝对允许根目录>；

• transport：stdio。

通用 stdio 启动和全部五个工具均由自动化测试覆盖，包括真实的子进程集成测试。对于 Codex，请在可行时使用受信任的项目本地配置，并通过 codex mcp list 或 /mcp 确认服务器。

有关确切的 Codex 配置、验证标签和可复制的全新线程采用提示，请参阅 Documentation/CODEX_ADOPTION_RUNBOOK.md。

Related MCP server: Coding Tools MCP

测试

安装测试附加依赖并运行完整测试套件：

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

该套件涵盖仓库引导与验证、按角色划分的输出、解析路径的包含性（包括符号链接/交接点逃逸情况）、MCP 工具元数据，以及真实的 STDIO 启动/关闭。

一次性演练

fixture 和准备辅助函数会构建一个全新的本地 Git 仓库，在项目本地配置服务器，引导所提供的演示简报，并验证不会编造任何工作单：

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

目标位置必须尚不存在。脚本刻意拒绝覆盖它。有关中立的演示目的，请参阅 examples/codex-live-rehearsal/PROJECT_BRIEF.md。

工具

• bootstrap_project 是唯一的变更操作。它接受 project_path、project_id、project_name 以及非空的调用方提供的 project_brief。它只创建初始脚手架和状态，对相同输入是幂等的，报告冲突而不覆盖，并且绝不创建工作单。

• get_project_status 返回紧凑的规范状态和明确的验证错误。

• get_orchestrator_bootstrap 返回项目目的、当前状态、权限、签发指南和证据审查门禁。

• get_worker_bootstrap 返回有界的工人上下文、一阶身份要求、执行门禁、证据权限以及停止/审查行为。

• get_bootstrap_context 仅接受 orchestrator 或 worker，并返回结构不同、严格按角色划分的上下文。

四个读取工具被标注为只读和封闭世界。bootstrap_project 被标注为非破坏性和幂等。MCP 标注是客户端提示，而非安全控制。

规范布局

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

初始配置仅存储模式版本和调用方提供的项目身份。项目简报完全按提供的原样写入。初始 CURRENT_STATE 声明未授权任何工作。创建空的工作、决策和证据目录；不会发明 WO-001 或其他实质性工作单。

最小新项目示例

使用允许根目录 C:\work 和已存在的空目录 C:\work\sample，调用：

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

使用完全相同的值再次调用会返回幂等的现有状态结果。不同的身份或简报内容属于冲突，绝不会覆盖规范文件。

权限与安全限制

只有编排者才能转换规范工作单状态。READY 不是执行许可，工人完成也不等于验收。规范编排者和主要工人必须是独立的、一阶的、用户可见的线程或任务。主要工人是持久的项目级身份；工作单是临时分配。仅当不存在主要工人或明确记录了替换时，工人引导才会返回手动生命周期提示，并且它会分别报告工人可达性、开始确认、分配和规范激活。

普通调度是一条 ACTIVE-plus-START 消息：工人在同一轮中验证规范 ACTIVE 提交、明确的 START、身份和范围，执行，然后报告完成以供编排者审查。不存在仅确认的轮次。

v0.1 不验证调用者角色。安全性来自面向读取的 API 表面、一个狭窄的初始化变更、解析路径的包含性、严格的状态验证、冲突拒绝和明确的权限协议。每次操作前都会检查文件系统包含性，但 v0.1 不声称能防御在验证与使用之间竞态文件系统链接的对手。

许可证

Apache License 2.0。请参阅 LICENSE。