mcp-supervisor-squad

Python MCP 服务器，提供最小化的 “contract-first + coder” 工作流，仅支持 stdio 传输，默认日志级别 ERROR 以保证 stdout 只输出 MCP JSON。

当前版本的核心思路：

主会话生成并覆盖写 /.codex/contract.json（必须存在且无未解决的 questions，否则拒绝执行）。
squad_start 在仓库内直接写代码（无 patch 文件、无 dual 模式、无 KB），但强制读取 contract 约束 scope/denylist/验收/预算。
返回值永远只有 1–3 行 digest（goal 复述 + 变更概览 + artifact 路径），避免上下文堆叠。
默认启用 lease + watchdog：若客户端停止轮询且 lease 到期（默认 120s），会自动终止 codex 子进程并标记 canceled。

工具

squad_start(cwd, query, options?)
- 必填 cwd（目标仓库内的绝对路径）。
- 读取 /.codex/contract.json；缺失或无效/存在 questions 时直接报错并拒绝执行。
- 创建 run，记录元数据，异步启动 coder 子任务（模型/沙箱/审批策略由 options 提供，默认为 workspace-write + never）。
- 默认 lease_ttl_s=120，客户端需按 forced_wait_s 轮询以续租，否则将自动取消。
- 返回简短状态：run_id、forced_wait_s、event_lines（≤3 行 digest）。
squad_status(run_id, options?)
- 必填 options.cwd（目标仓库内绝对路径）。
- 可选 cancel/cancel_reason 取消运行。
- 非终态调用会自动续租（重置 lease 过期时间）；断开轮询超过 lease_ttl_s 后，watchdog 会终止 codex。
- 返回简短状态：run_id、forced_wait_s、event_lines（终态附带 next_step=stop polling; print event_lines once）。缺少或找不到 run 时返回可操作错误提示（≤3 行）。

无 squad_apply：coder 直接写入仓库，当前不生成 patch。

调用流程（director）

调用 squad_start(cwd, query, options)，记下 run_id。
按返回的 forced_wait_s 轮询 squad_status(run_id, options={"cwd":"<仓库内绝对路径>"})。非终态不要提早轮询。
如需中止，调用 squad_status(..., options={"cwd":"<仓库内绝对路径>", "cancel":true, "cancel_reason":"..."})。

返回字段

所有响应都会包含：

{
  "run_id": "ss-...",
  "forced_wait_s": 8.0,
  "event_lines": ["...<=3 lines..."],   // 终态附加 next_step（含 digest 与 artifact 路径）
  "next_step": "stop polling; print event_lines once" // 仅终态
}

终态（done/error/canceled）时 forced_wait_s=0，非终态需按推荐等待后再 poll。

存储布局（仓库本地）

<repo_root>/.codex/supervisor-squad/：

runs/<run_id>/state.json：运行状态
runs/<run_id>/artifacts/report.md：简要执行报告（含 digest 与 diffstat 路径）
runs/<run_id>/artifacts/diffstat.txt：git diff --stat 摘要
runs/<run_id>/jobs/<job_id>/*：coder 子任务日志与元数据
worktrees/<run_id>/：预留工作树目录（当前未使用）
prune_meta.json：清理元信息

保留策略：启动时按 retention_days（默认 10 天）和最近 20 个 run 做清理。

运行

poetry install
poetry run mcp-supervisor-squad --transport stdio   # stdout 仅 JSON，日志输出到 stderr（级别 ERROR）

测试

python -m compileall src/mcp_supervisor_squad

Metadata

Release files for mcp-supervisor-squad 0.1.52

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mcp-supervisor-squad 0.1.52
File	Size	Uploaded	Provenance
mcp_supervisor_squad-0.1.52.tar.gz	18.0 kB	Jan 10, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for mcp-supervisor-squad 0.1.52
File	Interpreter	ABI	Platform	Reset
mcp_supervisor_squad-0.1.52-py3-none-any.whl 23.6 kB Jan 10, 2026 Without provenance	Python 3	none	any	Details

Total release size: 41.6 kB

Release files / mcp_supervisor_squad-0.1.52.tar.gz

Download URL	mcp_supervisor_squad-0.1.52.tar.gz
Size	18.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`20a096489c08f3f0910335661521a4633bf672f3bb31d444f7c097f46448c576`
BLAKE2b-256 checksum How to use checksums	`602126632f86fea2a327f045bfefc9664b3c4d1760d9a26cd4e8343d7aa1dce2`
Upload date	Jan 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.2.1 CPython/3.14.2 Darwin/24.6.0`

Release files / mcp_supervisor_squad-0.1.52-py3-none-any.whl

Download URL	mcp_supervisor_squad-0.1.52-py3-none-any.whl
Size	23.6 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`99d963d9cc5209715e99b93b6ec43c834949f33d1ef1e2bc54fb5fd88b816040`
BLAKE2b-256 checksum How to use checksums	`f2440a7120c29180285951394f9a0e500c73b772a8cce05811af0319e945fdca`
Upload date	Jan 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`poetry/2.2.1 CPython/3.14.2 Darwin/24.6.0`

Security for mcp-supervisor-squad 0.1.52

Report project as malware

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.