plan-mode-mcp

English summary below. 本文档以中文为主,顶部提供英文摘要。

跨平台 MCP server,提供 Claude Code 风格的 plan mode——通过四个工具让任何支持 MCP 的 client(openclaw / WorkBuddy / Claude Code / ZCode / VS Code)挂上即用。纯软引导,无硬 gate:工具 + description + SKILL.md 引导 agent 先想后做,不靠拦截写工具。

---

English Summary

A cross-platform MCP server that brings Claude Code-style plan mode to any MCP-capable client. Four tools (enter_plan_mode / get_plan_mode_standards / todo_write / exit_plan_mode) plus a companion SKILL.md guide the agent through a research → plan → approve → execute workflow. Pure soft guidance — no hard gate, no read-only enforcement. Works on openclaw, WorkBuddy, Claude Code, ZCode, VS Code, anything that speaks MCP.

• Why: Claude Code has first-class plan mode; not every client does. Rather than tie a hard-gate plugin to one platform's SDK, this server exposes the workflow as cross-platform MCP tools.
• Install: python3.12 -m venv .venv && .venv/bin/pip install -e ".[test]"
• Configure: point your client's MCP config at .venv/bin/plan-mode-mcp (see examples/).
• License: Apache-2.0.

See the Chinese sections below for full documentation.

---

为什么做这个

Claude Code 原生支持 plan mode(Shift+Tab → 调研 → 提交计划 → 用户审批 → 执行)。但不是每个 client 都有。与其把硬 gate 插件绑死在某个平台的 SDK 上(比如 openclaw 原生插件 WorkBuddy 不能加载),不如把这套工作流做成跨平台的 MCP 工具——任何支持 MCP 的 client 挂上即用。

设计取向:纯软引导,不做硬 gate。MCP 协议层没有拦截 host 工具调用的通道(这是 client hook 的事),所以本 server 只能靠工具 + description + SKILL.md 引导 agent 自觉。这契合"只想要 harness 增强、不要只读 gate"的诉求。

四个工具

enter_plan_mode(reason: str = "", goal: str? = None) — 同步

进入 plan 状态。创建 planning 记录,把之前的 open plan 标记为 superseded。本工具非破坏性,只改状态。

get_plan_mode_standards() — 同步

获取完整规则手册(~3,500 字符)。规则手册覆盖六节:

1. 何时用 plan mode(多步/重构/破坏性/设计 vs 琐碎任务跳过)
2. 工作流六步(enter → get_standards → research → todo → exit → execute)
3. 编码纪律(贴合既有代码风格 / 诚实报告 / 不可逆操作谨慎 / 删前先读 / 被拒不原样重试)
4. 工具纪律(优先专用工具 / 独立调用并行 / 绝对路径 / 降级时等用户确认)
5. 红线(设计/评审任务:四类区分 / 改语义标"建议变更待确认" / 不以"最佳实践"覆盖原设计)

规则是按需激活的——agent 进 plan mode 后主动调这个工具取规范,不是每次对话灌进 system。规范与 SKILL.md 配套使用:SKILL.md 负责触发时机(when),规范提供具体内容(what)。

exit_plan_mode(plan: str, todos: list[dict>? = None) — async + elicitation

提交计划等审批。两种行为:

• client 支持 MCP elicitation(2025-06-18 规范,如 Claude Code):阻塞弹审批框,approve → status approved 可执行,deny → status rejected 修改重提
• client 不支持 elicitation(WorkBuddy / ZCode / openclaw,运行时探测):立即返回 submitted,审批降级为对话里用户口头确认

server 不依赖 client 支持 elicitation,try/except 兜底 + TypeError 重试(兼容老 SDK)。

todo_write(todos: list[{content, status, priority?}]) — 同步

全量替换 todo 列表(Claude Code TodoWrite 语义)。校验:每个 entry 有 content + 合法 status;同时最多一个 in_progress;非法 status/priority 报错。

安装

git clone <this repo> ~/OpenClawProject/plan-mode-mcp
cd ~/OpenClawProject/plan-mode-mcp
python3.12 -m venv .venv
.venv/bin/pip install -e ".[test]"

配置(每个 client)

见 examples/ 下四个模板(openclaw.mcp.json / workbuddy.mcp.json / claude-code.mcp.json / zcode.mcp.json)。简版——把 client 的 MCP 配置指向 venv 二进制:

{
  "mcpServers": {
    "plan-mode": {
      "command": "/Users/you/OpenClawProject/plan-mode-mcp/.venv/bin/plan-mode-mcp",
      "env": {
        "PLAN_MODE_CLIENT": "openclaw",
        "PLAN_MODE_DB_PATH": "/Users/you/.local/share/plan-mode/plan_mode.sqlite3"
      }
    }
  }
}

环境变量见 .env.example:PLAN_MODE_DB_PATH(SQLite 路径) / PLAN_MODE_CLIENT(client 身份) / PLAN_MODE_AGENT_ID(agent id) / PLAN_MODE_ELICIT_TIMEOUT(elicitation 超时秒)。

还要装 SKILL.md:skill/SKILL.md 是引导 agent 何时/怎么用这些工具的关键。各 client 装法不同——openclaw 用 openclaw skills install,WorkBuddy 在设置里导入 plan-mode-skill.zip,Claude Code 放 ~/.claude/skills/。

开发

.venv/bin/python -m pytest tests/ -v       # 68 个测试
.venv/bin/python -m plan_mode.server       # 手动跑 server (stdio)

项目结构(flat-layout,仿 memory-arbiter-mcp)

plan_mode/
  server.py     # FastMCP 入口 + 四工具 + _session_key helper
  tools.py      # 业务逻辑(可单测,无 MCP 依赖)+ session 隔离 + _STANDARDS 规范
  db.py         # SQLite connection factory + plans 表
  models.py     # PlanStatus enum + PlanApproval elicitation schema
  config.py     # Settings.from_env()
skill/SKILL.md  # 跨平台行为引导(中英混合,工具名英文)
tests/          # 68 测试(5 文件:test_tools/test_db/test_config/test_elicitation/test_session_isolation)
examples/       # 四份 client mcp.json 模板

设计要点

• 不做硬 gate。 MCP server 拦不了 host 工具调用。这是有意为之,契合"软引导"诉求,且让 server 跨平台。
• elicitation + 降级兜底。 exit_plan_mode 试 ctx.elicit,失败全 catch,降级为 submitted。server 不假设 client 一定支持。
• 规范按需激活,不每次灌。 get_plan_mode_standards 工具让 agent 主动取规范,而不是把规范塞进每次对话的 system prompt。规范和 SKILL.md 配对触发。
• SQLite,一张表。 plans + todos + status,不用向量/FTS/冲突仲裁。plan mode 只需要简单的结构化状态。
• 仿 memory-arbiter-mcp 形态。 同技术栈(Python + FastMCP + SQLite + stdio)、同部署方式(entry point + 环境变量)、同连接管理(WAL + busy_timeout + 每次操作新连接)。

已知限制(已文档化)

1. session 隔离是进程级,非分布式。 todos 用 session_key 在同一进程内隔离多个 session;不跨进程共享。stdio 一连接一进程的场景天然没问题。plans 持久化到 SQLite,跨进程存活。注意：todos 字典无自动清理机制——session 断开后其 todo 列表仍残留在进程内存中；对短生命周期 stdio 进程无影响，对长时间运行的 gateway 复用场景可能逐步增长。
2. 无硬约束。 工具不能物理阻止 agent 在 plan mode 下写文件(MCP 没有 host-hook 通道)。SKILL.md 提供软引导。这是有意为之。
3. elicitation 支持因 client 而异。 Claude Code 支持;Claude Desktop/Cowork 返回 cancel;WorkBuddy/ZCode/openclaw 尚未确认,运行时自动降级为 submitted。
4. 规范不是强制在场。 get_plan_mode_standards 取来的规范在 tool result 里,长对话可能被 compact 压缩掉。需要时重新调一次。

License

Apache-2.0.