Skip to main content
Glama
plan-mode-mcp
by billy12151

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.


Related MCP server: Skillz

为什么做这个

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 任务恢复。

安装

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       # 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.

Available Tools

5 tools
enter_plan_modeA

Enter plan mode before attempting any complex, multi-step, or file-modifying task.

Use this PROACTIVELY for non-trivial coding, refactoring, or destructive operations. Once in plan mode you SHOULD:

  • research the task using read-only tools (read / grep / web search)

  • call todo_write to break the work into steps

  • then call exit_plan_mode with a concrete plan and WAIT for approval Avoid write / edit / exec while planning. This tool itself is non-destructive; it only marks state so the workflow is observable.

Args: reason: Short note on why plan mode is warranted for this task. goal: One-line description of what the plan should achieve.

Inputs: goal, reason. Returns: result

exit_plan_modeA

Submit your completed plan and wait for user approval.

Call this ONLY after you have a concrete, actionable plan. This blocks the agent run until the user decides:

  • approve -> plan mode ends, write/edit/exec tools may be used

  • deny -> stay in plan mode, revise and resubmit On clients without in-tool approval prompts, the tool returns immediately with status 'submitted' and approval is deferred to the client's own permission flow.

Args: plan: The full step-by-step plan, in markdown. todos: Optional updated todo list to persist alongside the plan.

Inputs: plan (required), todos. Returns: result

get_plan_mode_standardsA

Fetch the full plan-mode rulebook.

Call this ONCE at the start of a plan-mode task (after enter_plan_mode, before writing your plan). It returns the standards that apply for the duration of this task: when to use plan mode, the workflow, coding discipline, tool discipline, and red lines for design/review tasks.

These standards are NOT auto-injected into every conversation — you fetch them on demand so they are in context when you actually need them. If unsure whether you have the latest version, re-fetch.

Returns: A dict with the standards text and a short note.

Inputs: no named parameters. Returns: result

plan_recentA

List the most recent plans for debugging/observability.

Read-only — does not change any state. Useful for inspecting plan history (e.g. "what was the last rejected plan?") without opening the SQLite file directly.

Args: n: Maximum number of plans to return (default 10).

Inputs: n. Returns: result

todo_writeA

Maintain the task list for this session.

Send the FULL list on every call — it replaces prior state (same semantics as Claude Code's TodoWrite). Each entry is {content, status, priority?} where status is one of pending / in_progress / completed and priority is high / medium / low. At most ONE entry may be in_progress at a time.

Args: todos: Complete replacement list. Empty list clears the todos.

Inputs: todos (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.5/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool targets a distinct phase of the plan-mode workflow: entering, listing history, exiting, managing todos, and fetching standards. No two tools overlap in purpose.

    Naming Consistency4/5

    Tools use consistent underscore_case and mostly follow a verb_noun pattern (enter_plan_mode, exit_plan_mode, todo_write, get_plan_mode_standards). The exception is 'plan_recent', which uses noun_verb order, but the meaning remains clear.

    Tool Count5/5

    Five tools is well-scoped for a focused workflow server. Each tool serves a necessary role without redundancy, keeping the surface manageable for agents.

    Completeness5/5

    The toolset covers the full plan-mode lifecycle: entering, retrieving standards, managing todo lists, listing history, and submitting plans. No obvious gaps exist for the stated purpose.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers