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=<absolute allowed root>;

• transport: stdio.

Универсальный stdio-запуск и все пять инструментов покрыты автоматическими тестами, включая реальный интеграционный тест с субпроцессом. Для Codex по возможности используйте доверенную конфигурацию в рамках проекта и проверьте сервер с помощью codex mcp list или /mcp.

Точную конфигурацию Codex, метки проверки и копируемые подсказки для внедрения в новом потоке см. в Documentation/CODEX_ADOPTION_RUNBOOK.md.

Related MCP server: Coding Tools MCP

Тесты

Установите тестовый extra и запустите полный набор тестов:

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

Набор покрывает начальную инициализацию и проверку репозитория, выходные данные с ограничением по ролям, ограничение разрешённых путей (включая случаи обхода через симлинки/соединения), метаданные MCP-инструментов и реальный запуск/останов STDIO.

Одноразовая репетиция

Фикстура и вспомогательный инструмент подготовки создают новый локальный 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 и возвращает структурно различные, узко ограниченные по роли контексты.

Четыре инструмента чтения аннотированы как read-only и closed-world. bootstrap_project аннотирован как неразрушающий и идемпотентный. Аннотации MCP — это подсказки клиенту, а не средства контроля безопасности.

Каноническая структура

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

Первоначальная конфигурация хранит только версию схемы и переданную вызывающей стороной идентичность проекта. Project Brief записывается точно в том виде, в котором он предоставлен. Изначальное значение CURRENT_STATE гласит, что никакие работы не разрешены. Создаются пустые каталоги work, decision и evidence; никакой 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 плюс START: исполнитель проверяет канонический коммит ACTIVE, явный START, идентичность и область действия, выполняет работу в том же ходе и затем сообщает о завершении для проверки оркестратором. Отдельного хода только с подтверждением получения не предусмотрено.

v0.1 не аутентифицирует роли вызывающих сторон. Безопасность обеспечивается API-поверхностью, ориентированной на чтение, одной узкой изменяющей операцией инициализации, ограничением разрешённых путей, строгой проверкой состояния, отказом при конфликтах и явным протоколом полномочий. Ограничение файловой системы проверяется перед каждой операцией, однако v0.1 не заявляет о защите от злоумышленника, который успевает подменить ссылки файловой системы между проверкой и использованием.

Лицензия

Apache License 2.0. См. LICENSE.