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 以降を除外しています。

サーバーはプロセス起動時に、許可された 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=<absolute allowed root>;

• transport: stdio.

一般的な stdio 起動と 5 つのツールすべては、実際のサブプロセス統合テストを含む自動テストでカバーされています。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 は、制限されたワーカーコンテキスト、第一級のアイデンティティ要件、実行ゲート、証拠権限、停止/レビュー動作を返します。

• get_bootstrap_context は orchestrator または worker のみを受け入れ、構造的に異なる、ロールに厳密にスコープされたコンテキストを返します。

4 つの読み取りツールは、読み取り専用かつクローズドワールドとして注釈付けされています。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 は実行の許可ではなく、ワーカーの完了は受理ではありません。正規のオーケストレーターとプライマリワーカーは、別個の第一級の、ユーザーに見えるスレッドまたはタスクでなければなりません。プライマリワーカーは永続的なプロジェクトレベルのアイデンティティであり、作業指示は一時的な割り当てです。ワーカーブートストラップは、プライマリワーカーが存在しないか、置き換えが明示的に記録されている場合にのみ手動ライフサイクルプロンプトを返し、ワーカーの到達可能性、開始確認、割り当て、正規のアクティブ化を別々に報告します。

通常のディスパッチは、1 つの ACTIVE プラス START メッセージです。ワーカーは正規の ACTIVE コミット、明示的な START、アイデンティティ、スコープを検証し、同じターン内で実行し、次にオーケストレーターのレビューのために完了を報告します。確認のみのターンはありません。

v0.1 は呼び出し元のロールを認証しません。安全性は、読み取り指向の API サーフェス、1 つの狭い初期化変更、解決済みパスの封じ込め、厳格な状態検証、競合拒否、明示的な権限プロトコルに由来します。ファイルシステムの封じ込めは各操作の前にチェックされますが、v0.1 は検証と使用の間のファイルシステムリンクを競う攻撃者からの保護を主張するものではありません。

ライセンス

Apache License 2.0。LICENSE を参照してください。