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: continuity
テスト用エクストラをインストールし、完全なスイートを実行します:
.\.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 を参照してください。
Initialize canonical scaffolding from an explicit caller-supplied brief.
The target directory must already exist under the configured workspace root. This never infers purpose, overwrites canonical state, or creates a work order.
| Name | Required | Description | Default |
|---|---|---|---|
| project_id | Yes | ||
| project_name | Yes | ||
| project_path | Yes | ||
| project_brief | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare idempotentHint=true and destructiveHint=false, but the description adds valuable context: it never infers purpose, never overwrites canonical state, and never creates a work order. This goes beyond annotations and clarifies the side-effect profile, though it does not mention permission requirements or output format (which is covered by output schema).
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the primary purpose, followed by clear constraints and exclusions. There is no fluff or redundancy; every clause earns its place. It is an example of exemplary conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has four required parameters with zero schema descriptions and the description adds no parameter details. Usage guidance is only implicit. Though the output schema exists, the lack of any help on parameter semantics and selection criteria makes the description incomplete for an agent to invoke correctly without guessing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the tool description provides absolutely no explanation of any of the four required parameters. The parameters (project_id, project_name, project_path, project_brief) have only their names; no semantics are conveyed. The description fails entirely to compensate for the lack of schema documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Initialize') and resource ('canonical scaffolding') and clarifies the deliberate, non-inferential nature, which distinguishes it from the getter siblings. It also gives explicit exclusions ('never infers purpose, overwrites canonical state, or creates a work order'), making the tool's purpose unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides a clear precondition ('target directory must already exist') and implies this is an initialization tool versus the getter siblings, but it does not explicitly state when to use this tool over alternatives or when not to use it. No explicit routing guidance is given, leaving the agent to infer from the sibling names.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return narrowly role-scoped canonical context for the requested role.
| Name | Required | Description | Default |
|---|---|---|---|
| role | Yes | ||
| project_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The annotations already declare readOnlyHint=true and openWorldHint=false, so the safety profile is known. The description adds that the context is 'canonical' and 'role-scoped', which provides some behavioral context, but it does not disclose specifics like error conditions, the exact structure of the response, or any side effects (though read-only implies none). It does not contradict the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence and is not verbose, but it sacrifices essential details for brevity. Phrases like 'narrowly role-scoped' add little concrete value. It could be more effective while remaining concise if it included the project_path parameter and a note on the sibling roles.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is incomplete for a tool that has direct role-specific siblings. It does not clarify the difference between get_bootstrap_context and get_orchestrator_bootstrap/get_worker_bootstrap, nor does it hint at the role of project_path. While an output schema exists (per context signals), the description still needs to convey what 'canonical context' means operationally. An agent would likely need to inspect sibling definitions to use this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description carries the full burden for parameter explanation. It mentions the 'role' concept but does not explain the allowed enum values or what 'project_path' refers to or its format. The role is only implied, and project_path is entirely absent from the description. This is a significant gap for a tool with only two required parameters.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'return' and the resource 'canonical context' scoped by role. It implies a generic role-parameterized tool, but it does not explicitly distinguish itself from get_orchestrator_bootstrap and get_worker_bootstrap, which are direct role-specific alternatives. The word 'narrowly role-scoped' hints at the distinction but doesn't name the siblings.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool instead of the sibling tools, particularly get_orchestrator_bootstrap and get_worker_bootstrap. The agent must infer the relationship from the role enum, which is not spelled out. There is no mention of exclusions, prerequisites, or typical use cases.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return purpose, state, authority, issuance guidance, and review gates.
| Name | Required | Description | Default |
|---|---|---|---|
| project_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so read-only behavior is covered. The description lists returned fields, which is a small addition, but it does not explain any operational behavior such as error conditions, required permissions, or the meaning of the returned fields beyond their names. Minimal added context beyond annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very short and to the point, but it is little more than a list of return fields. It lacks any structural elements like a clear tool purpose or usage guidance. While concise, it is under-specified rather than efficiently structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Although an output schema exists and likely details the return fields, the description offers no additional context about when to call this tool, how to interpret the output, or any side effects. For a tool with one parameter and a read-only annotation, the description is too sparse to be considered complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The sole parameter project_path has zero description coverage (0%) in the input schema, and the description does not mention it at all. The description fails to compensate for the lack of schema-level documentation, leaving the agent to guess what project_path should be (path, ID, etc.).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states that the tool returns a list of items (purpose, state, authority, etc.) but lacks a specific action verb and does not clarify what 'orchestrator bootstrap' means or how it differs from siblings like get_worker_bootstrap. It is vague about the tool's core purpose beyond returning a set of fields.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No indication of when to use this tool versus the sibling tools (bootstrap_project, get_project_status, get_worker_bootstrap, get_bootstrap_context). The description provides no context, prerequisites, or explicit conditions for selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return compact canonical status and explicit validation errors.
| Name | Required | Description | Default |
|---|---|---|---|
| project_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only behavior is covered. The description adds that the tool returns 'compact canonical status and explicit validation errors', which is a useful behavioral detail beyond the annotation. However, it does not describe any other side effects, prerequisites, or response nuances, so it adds limited context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single sentence, front-loaded with the core action, and contains no extraneous wording. Every word contributes to meaning, making it appropriately concise and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool has an output schema, so return values are already defined. The main gaps are the lack of parameter explanation and missing usage guidance. For a simple one-parameter read-only tool, the description is minimally sufficient but not complete; an agent would still need to infer what 'project_path' means.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, and the description completely fails to explain the required parameter 'project_path'. There is no indication of what the path refers to, its format, or constraints. The description provides zero value in clarifying the parameter beyond the schema's type/title.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Return') and resource (canonical status and validation errors). It is concise and clear about what the tool produces. However, it does not explicitly differentiate from sibling tools, though the siblings are bootstrap-related and thus functionally distinct in name.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description offers no explicit guidance on when to use this tool versus alternatives. It does not mention any exclusions or contexts. The purpose implicitly suggests use when needing status or validation info, but this is not stated, leaving the agent to infer.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Return bounded worker entry context, execution gates, and stop behavior.
| Name | Required | Description | Default |
|---|---|---|---|
| project_path | Yes |
| Name | Required | Description |
|---|---|---|
No output parameters | ||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, so the read-only safety profile is handled. The description gestures at behavior through 'execution gates' and 'stop behavior' but does not explain what those involve, any limits of 'bounded', or consequences beyond the fact that this is a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single front-loaded sentence with no filler. Each phrase ('bounded worker entry context', 'execution gates', 'stop behavior') contributes a distinct aspect of the returned data, making it appropriately sized for a read-only tool with an output schema.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The output schema and readOnly annotation cover the return shape and safety profile. However, the description does not differentiate this tool from its sibling tools and leaves key terms ('bounded', 'execution gates') undefined, so the agent lacks enough context to confidently select and invoke the tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0% and the tool description never mentions 'project_path'. The agent must infer from the bare property name that it is a path, with no guidance on format, required meaning, or how it relates to the worker bootstrap context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific action ('Return') and a specific resource ('worker entry context'), and lists the returned facets: bounded context, execution gates, and stop behavior. It is distinguishable from 'get_orchestrator_bootstrap' by the word 'worker', though the terminology is somewhat unexpanded.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No statement tells the agent when to use this tool over the closely related siblings such as get_bootstrap_context or get_orchestrator_bootstrap. Usage is only implied by the word 'worker'; there are no exclusions, prerequisites, or alternative routing clues.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0bootstrap_projectget_bootstrap_contextget_orchestrator_bootstrapget_project_statusget_worker_bootstrapScored across 5 tools
The getter tools for bootstrap context overlap: get_orchestrator_bootstrap, get_worker_bootstrap, and get_bootstrap_context all return role-scoped context, with the generic one likely covering the same ground. Only bootstrap_project is clearly distinct, while the getter separation by role is somewhat clear but not fully disambiguated.
All tool names are snake_case and follow a verb_noun pattern consistently. bootstrap_project stands out as an action, while the others use get_ prefix, but this is a typical and understandable distinction. The consistent prefix and structure make the naming predictable.
With only 5 tools, the surface is compact and well‑scoped for a control plane bootstrap service. Each tool appears to serve a distinct functional need without bloat, making the count appropriate for the apparent domain.
The tool set covers project bootstrap, status retrieval, and role‑specific context, but lacks lifecycle operations like listing or updating projects. The generic get_bootstrap_context seems redundant, and there are no endpoints for project deletion or modification, leaving notable gaps for a control plane.
Project memory, semantic code search, and grounded agent context.
One shared project for a team's coding agents: decisions, a task board and handoffs.
Shared project context for AI agents and teams: docs, tasks, and messages that stay current.
Give every project one workspace for its files, its team, and its AI agents.