# 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. Six tools (`enter_plan_mode` / `get_plan_mode_standards` / `todo_write` / `exit_plan_mode` / `plan_recent` / `resume_plan`) 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()` — 同步
获取完整规则手册(~4,000 字符)。规则手册覆盖八节:
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, original_user_request: str? = None, interpreted_user_intent: str? = 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)。`plan` 参数提交计划正文，`original_user_request` 保存用户原始请求（事实层/审计锚点），`interpreted_user_intent` 保存 agent 对目标、约束、成功标准的结构化理解（解释层/执行层）。不传时计划 Markdown 中对应节会以 `(not provided)` 占位。

### `todo_write(todos: list[{content, status, priority?}])` — 同步
全量替换 todo 列表(Claude Code TodoWrite 语义)。校验:每个 entry 有 content + 合法 status;同时最多一个 `in_progress`;非法 status/priority 报错。

### `plan_recent(n: int = 10)` — 同步
返回最近 N 条 plan 记录，用于调试/观察 plan 历史。

### `resume_plan(plan_id: int)` — 同步
恢复一条 `approved` 或 `submitted` 状态的 plan 到当前 session。会还原原 plan 的 todos 和历史上下文，并创建新的 `planning` 记录。配合 `plan_recent` 实现跨 session 任务恢复。

## 安装

```bash
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 二进制:

```json
{
  "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/`。

## 开发

```bash
.venv/bin/python -m pytest tests/ -v       # 88 个测试
.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/          # 88 测试(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 压缩掉。需要时重新调一次。
5. **Plan 文件可能包含敏感信息。** 开启 plan 持久化（默认）后，`exit_plan_mode` 批准的 plan 会写入 `PLAN_MODE_PLANS_DIR` 目录下的 `.md` 文件，其中可能包含项目路径、需求细节、实现方案等信息。请确保该目录的访问权限和备份策略符合你的安全要求；如需关闭，设 `PLAN_MODE_PERSIST_PLAN=false`。

## License

Apache-2.0.