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: 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는 제한된 작업자 컨텍스트, 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를 참조하십시오.
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.