Skip to main content
Glama
billy12151
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) — 同步

恢复一条 approvedsubmitted 状态的 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_modectx.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.

ParametersJSON Schema
NameRequiredDescriptionDefault
goalNo
reasonNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.6/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description properly discloses that the tool 'is non-destructive; it only marks state so the workflow is observable.' It does not mention any side effects, but it is sufficiently transparent for the agent to understand the safe, stateful nature of the tool.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured, with a clear purpose statement, usage guidelines, a workflow bullet list, and a parameter section. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity and the presence of an output schema (which presumably describes the response), the description covers purpose, usage, and parameters adequately. It does not elaborate on the output, but the schema is expected to handle that.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, but the description adds meaning for both parameters: 'reason' is a short note on why plan mode is warranted, and 'goal' is a one-line description of the plan's achievement. This compensates for the missing schema descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's function: 'Enter plan mode before attempting any complex, multi-step, or file-modifying task.' It specifies the verb (enter) and resource (plan mode), and distinguishes it from siblings like exit_plan_mode and todo_write.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides explicit when-to-use guidance: 'Use this PROACTIVELY for non-trivial coding, refactoring, or destructive operations.' It also details the subsequent workflow: research, todo_write, exit_plan_mode, and wait for approval, while advising against write/edit/exec during planning.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
planYes
todosNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.7/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description discloses key behaviors: the tool blocks the agent run until user decision, and explains the approval flow. It also mentions deferred approval on certain clients. Lacks mention of side effects or permissions, but is sufficient for the tool's function.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured: purpose first, then conditions, then arguments. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has 2 parameters and no output description despite having output schema. The description covers usage and parameters well but omits return value details. Still complete enough for agent decision-making.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description explains both parameters: plan is 'The full step-by-step plan, in markdown' and todos is 'Optional updated todo list to persist alongside the plan.' This adds significant meaning beyond the schema, especially given 0% schema description coverage.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with a clear verb and resource: 'Submit your completed plan and wait for user approval.' It distinguishes itself from siblings like enter_plan_mode by specifying that this ends plan mode with user approval.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly states when to call it: 'Call this ONLY after you have a concrete, actionable plan.' It details the two possible outcomes (approve/deny) and behavior on different clients, providing clear guidance on when to use and what to expect.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. Discloses that it returns standards for the duration, is not auto-injected, and gives a brief description of the return format. Lacks details on exact structure or side effects, but for a simple fetch, it's adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Well-structured: clear actionable instruction, rationale, and bullet points for return value. Every sentence adds value, no waste.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Complete for a parameterless tool with an output schema. Covers when to use, why, and what it returns. No gaps.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has zero parameters, so schema coverage is 100%. Baseline 4 is appropriate; description adds no parameter info as none needed.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description starts with a clear verb-resource pair: 'Fetch the full plan-mode rulebook.' It also situates the tool within the workflow, distinguishing it from siblings by specifying it is called after enter_plan_mode and before writing the plan.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states when to call: 'ONCE at the start of a plan-mode task (after enter_plan_mode, before writing your plan).' Explains why it's needed and suggests re-fetching if unsure. Does not mention when not to use, but the context is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

ParametersJSON Schema
NameRequiredDescriptionDefault
nNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.3/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Explicitly declares read-only behavior and that it does not change state. No annotations are provided, so the description carries the full burden and does so well, though it could clarify ordering or recency definition.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Description is brief and includes an Args section, but there is some redundancy (e.g., ‘Read-only — does not change any state’ could be merged). Overall well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple list tool with one optional parameter and an output schema, the description covers purpose, usage, and parameter. It is complete enough without needing to detail return values.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description adds meaning for parameter 'n' (maximum number, default 10). Could be improved with range or constraints.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it lists the most recent plans for debugging/observability, with a specific verb and resource. It is distinct from sibling tools like enter_plan_mode or todo_write.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Provides a concrete example (inspecting plan history) and mentions use without opening SQLite, but does not explicitly state when not to use or name alternatives.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
todosYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses destructive behavior (replaces prior state), constraints (one in_progress), and clearing via empty list. No contradictions, but lacks details on error handling or authorization.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is concise and well-structured, with front-loaded purpose and clear formatting for details. Every sentence adds value without redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool (one parameter, output schema exists), the description covers behavior, constraints, and usage. It could mention error cases or confirmation behaviors, but overall it's thorough enough for an agent to use correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 0%, but the description fully compensates by defining the structure of each todo entry, including fields, enums for status and priority, and the effect of an empty list. This provides critical meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool maintains the task list for the session and explains the semantics of replacing the full list on every call. It distinguishes itself from siblings which are plan mode tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

It explicitly says to send the FULL list on every call and that it replaces prior state. It also notes the constraint of at most one entry being in_progress. It does not explicitly mention when not to use or alternatives, but the context is clear enough.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 5 tool updatesv0.1.0
    • First observedenter_plan_mode
    • First observedexit_plan_mode
    • First observedget_plan_mode_standards
    • First observedplan_recent
    • First observedtodo_write

TDQS

A4.5/5.0
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

ActivitySlowing
ResponsivenessNo issues

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/billy12151/plan-mode-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server