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를 대상으로 합니다. 변경된 도구 예외 렌더링이 ControlPlane의 안정적인 실행 가능 오류 계약을 약화시키지 않고 채택될 수 있을 때까지 종속성 메타데이터는 2.1 이상을 제외합니다.

서버는 프로세스 시작 시 하나의 허용된 작업 공간 루트로 범위가 제한됩니다. 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 시작/종료를 다룹니다.

일회용 리허설

픽스처와 준비 헬퍼는 새로운 로컬 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는 제한된 작업자 컨텍스트, 1차 신원 요구 사항, 실행 게이트, 증거 권한, 중지/검토 동작을 반환합니다.

• get_bootstrap_context는 orchestrator 또는 worker만 허용하며 구조적으로 다르고 역할 범위가 좁은 컨텍스트를 반환합니다.

네 가지 읽기 도구는 읽기 전용 및 폐쇄 세계로 주석 처리됩니다. bootstrap_project는 비파괴적 및 멱등성으로 주석 처리됩니다. MCP 주석은 보안 제어가 아닌 클라이언트 힌트입니다.

정식 레이아웃

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

초기 구성은 스키마 버전과 호출자가 제공한 프로젝트 신원만 저장합니다. 프로젝트 브리프는 제공된 그대로 기록됩니다. 초기 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는 실행 권한이 아니며, 작업자 완료는 승인이 아닙니다. 정식 오케스트레이터와 기본 작업자는 별도의 1차 사용자에게 보이는 스레드 또는 작업이어야 합니다. 기본 작업자는 영구적인 프로젝트 수준 신원이며, 작업 지시는 임시 할당입니다. 작업자 부트스트랩은 기본 작업자가 없거나 교체가 명시적으로 기록된 경우에만 수동 수명 주기 프롬프트를 반환하며, 작업자 연결 가능성, 시작 확인, 할당, 정식 활성화를 별도로 보고합니다.

일반 디스패치는 하나의 ACTIVE와 START 메시지로 구성됩니다. 작업자는 정식 ACTIVE 커밋, 명시적 START, 신원 및 범위를 확인하고 같은 턴에서 실행한 뒤 오케스트레이터 검토를 위해 완료를 보고합니다. 확인 전용 턴은 없습니다.

v0.1은 호출자 역할을 인증하지 않습니다. 안전성은 읽기 중심 API 표면, 하나의 좁은 초기화 변경, 확인된 경로 격리, 엄격한 상태 검증, 충돌 거부, 명시적 권한 프로토콜에서 비롯됩니다. 파일 시스템 격리는 각 작업 전에 확인되지만, v0.1은 검증과 사용 사이에 파일 시스템 링크를 경쟁적으로 조작하는 공격자에 대한 보호를 주장하지 않습니다.

라이선스

Apache License 2.0. LICENSE를 참조하십시오.