mcp-supervisor-squad 0.1.5

MCP server for the supervisor-squad workflow.

mcp-supervisor-squad

Python MCP server that implements a minimal “supervisor + coder squad” workflow with brief status.

Tools (public MCP API)

• squad_start(cwd, query, options?) → creates a run, executes an internal supervisor pass to generate requirements + shared KB, then dispatches 1–2 coder jobs in worktrees, returns brief status (lines ≤ 3).
• squad_status(run_id, options?) → returns brief status (lines ≤ 3) using cached state (no stdout tail by default).
• squad_apply(run_id, options?) → applies the final patch with git apply (dry_run default true) and returns the same brief status fields plus apply result fields.

Important: for deterministic run lookup, pass options.cwd (any path inside the target repo) to squad_status and squad_apply. Authoritative machine-readable contract is written to <repo_root>/.codex/supervisor-squad/contract.json.

External supervisors should treat contract.json as the stable integration surface: inject optional kb/inbox/external_report.*, call squad_start, then poll squad_status and read persisted artifacts under .codex/supervisor-squad/ as needed.

All tool responses include:

{
  "run_id": "ss-...",
  "next_action": "wait|apply",
  "recommended_poll_ms": 15000,
  "wait_reason": "agent_running|ready_to_apply|error",
  "lines": ["...<=3 lines..."]
}

squad_apply additionally includes:

{
  "applied": true,
  "dry_run": true,
  "summary": "files=3",
  "error": ""
}

Storage layout (repo-local)

Under <repo_root>/.codex/supervisor-squad/:

• contract.json – authoritative machine-readable contract (paths/limits/schema/workflow)
• config.json – repo-local defaults for execution (models/reasoning/sandbox)
• kb/inbox/external_report.md|json – optional external supervisor “research injection”
• kb/compact.md – compacted shared KB (kept small)
• kb/archive/* – archived injections (pruned)
• runs/<run_id>/state.json – run state and brief cache
• runs/<run_id>/artifacts/requirements*.md – requirements docs written before dispatch
• runs/<run_id>/artifacts/contract.json – dual-project contract (<=4KB)
• runs/<run_id>/artifacts/patch.diff – final patch to apply
• runs/<run_id>/jobs/<job_id>/* – codex exec stdout/stderr/meta
• worktrees/<run_id>/<slug> – per-task git worktrees (best-effort cleanup)
• kb/prune_meta.json – prune rate limit state
• kb/repo_profile.json – best-effort repo scan cache (reused across runs)

Configuration

Create <repo_root>/.codex/supervisor-squad/config.json to set repo-local defaults. Call-time options overrides these values.

Example:

{
  "execution": {
    "sandbox": "workspace-write",
    "approval_policy": "never"
  },
  "supervisor": {
    "model": "gpt-5.1-codex-max",
    "reasoning_effort": "medium",
    "extra_config": []
  },
  "coder": {
    "model": "gpt-5.1-codex-max",
    "reasoning_effort": "medium",
    "extra_config": []
  },
  "read_limits": {
    "max_files": 30,
    "max_file_bytes": 65536,
    "max_total_bytes": 1000000
  },
  "kb": {
    "inbox_max_kb": 20,
    "compact_max_kb": 10,
    "archive_keep": 5,
    "archive_max_kb": 200
  }
}

External Research Injection (Optional)

External supervisor (outside this MCP server) may write a short report to:

• <repo_root>/.codex/supervisor-squad/kb/inbox/external_report.md (<=20KB), or
• <repo_root>/.codex/supervisor-squad/kb/inbox/external_report.json (<=20KB)

On squad_start, the internal supervisor reads it, generates requirements + shared KB, then archives and clears the inbox.

Development

cd mcp-tools/mcp-supervisor-squad
poetry install

Running

poetry run mcp-supervisor-squad --transport stdio

Testing

python -m compileall src/mcp_supervisor_squad