solve-runner-mcp

solve-runner-mcp 是一个本地 FastMCP 服务，用来承载 Antigravity <-> Codex 的多轮协作工作流。

它适合这样的场景：

• 一个 agent 负责提出方案或修改代码
• Codex 负责校验、反驳、补充或收敛
• 双方可能需要多轮往返，最后才给用户一个可执行结论

这套方案的核心目标是把“讨论语义”和“执行状态”拆开：

• skill 负责理解用户意图、判断是否继续同一个 work item
• MCP 负责执行轮次、落盘状态、提供轮询接口
• Codex CLI 作为底层执行器被 MCP 调用

仓库结构

.
├─ src/solve_runner_mcp/          # MCP 服务与 solve 运行时
├─ scripts/smoke_test.py          # 本地回归 smoke test
├─ skills/solve-protocol/         # 推荐配套 skill
├─ examples/antigravity/          # Antigravity MCP 配置示例
└─ docs/                          # 接入与发布文档

提供的 MCP Tools

• solve_init_project
• solve_new_session
• solve_get_status
• solve_get_latest_artifacts
• solve_run_round
• solve_continue_until_consensus

服务会把状态写入项目内的 .solve-state/ 目录，并以异步方式执行 solve 轮次。

安装

普通安装：

pip install .

开发模式安装：

pip install -e .

启动

安装后的入口：

solve-runner-mcp

直接从源码目录启动：

python run_server.py

本地自测

python scripts/smoke_test.py

预期输出：

• solve-runner smoke test passed
• next_action=poll_status

配套 Skill

推荐配套的 skill 在这里：

skills/solve-protocol/SKILL.md

它负责 solve 的语义层；MCP 服务负责执行层和状态层。

这套协议最重要的约束是：

• solve_run_round 只负责启动后台轮次，不会同步等待完成
• 客户端必须轮询 solve_get_status，直到 running=false
• running=true 时，不能把 artifacts 当成最终结果
• 只有 artifacts 显示 READY_FOR_USER_DECISION 时，才能向用户输出最终结论

Antigravity 接入

见：

• docs/antigravity-setup.md
• examples/antigravity/mcp_config.sample.json

发布前检查

见：

• docs/release-checklist.md

发布前重点确认：

• 已选择并保留许可证
• 已把真实部署里的本机路径替换成泛化示例
• skill 和 MCP 文档中的路径是仓库路径，不是你的私有环境路径

License

MIT

说明

• run_server.py 是最简单的本地启动入口，适合直接指向源码目录的 MCP 客户端
• 长耗时的 Codex 轮次带有 heartbeat 更新，客户端可以区分“真的卡死”和“只是还在慢慢跑”