Mcpp Plan

mcpp计划

AI编码代理的持久任务和步骤跟踪器。使Claude Code（或任何兼容MCP的代理）能够将工作分解为任务，跟踪每个任务中的步骤，并准确记住它在会话中的中断位置。

新来的？ 看 RAPIDSTART.md --在10分钟内克隆、配置并开始使用它。

每天吃狗粮。 该模块通过自身开发、维护和不断改进。每个功能在构建的那一刻都会进行真实世界的测试。 代理便携。 在一个代理中启动一个任务，在另一个代理中将其拾取——不会丢失上下文。状态存在于数据库中，而不是对话中。

为什么

AI代理在会话之间失去上下文。当你继续谈话时，代理人不知道它在做什么，完成了哪些步骤，或者下一步是什么。mcpp计划通过为代理提供一个由SQLite支持的结构化、持久的任务管理器来解决这个问题。

代理通过MCP工具与它对话。你用简单的英语和代理人说话。代理人管理其余部分。

运作原理

project
  └── user (auto-detected from $USER)
        └── task (a focus area, like "build login page")
              └── step (individual action, like "create user table")

• 任务 是顶级工作项（功能、错误、重构）
• 步骤 是任务中有序的操作
• 一次只有一个任务和一个步骤处于活动状态 --代理人总是知道下一步该做什么
• 国家坚持 在 plan.db 在模块目录内
• 多用户 --每个操作系统用户在共享数据库中获得独立的任务游标

安装

mcpp计划是 mcpp 工具模块。通过将工具路径添加到mcpp配置中来安装它。

先决条件

• Python 3.10+
• SQLite 3（与Python捆绑在一起）
• MCP兼容代理（克劳德代码等）

设置

1. 将两个存储库克隆为兄弟库：

cd ~/projects
git clone git@github.com:pacmac/mcpp.git
git clone git@github.com:pacmac/mcpp-plan.git

mcpp的默认值 tools.yaml 已经包括 ../mcpp-plan，因此，如果它们并排放置，则不需要额外的配置。

1. 使用Claude代码注册MCP服务器：

claude mcp add mcpp --scope user \
  --env MCPP_LOG_LEVEL=error \
  --env MCPP_TIMEOUT_SECONDS=30 \
  -- python3 ~/projects/mcpp/mcpp.py

替换 ~/projects 使用您的安装文件夹。

1. 数据库是按照以下方式自动创建的 plan.db 首次使用时在模块目录中。无需设置。

工具

所有工具均通过MCP暴露 plan_ 前缀。

任务工具

步骤工具

用户工具

项目工具

报表工具

报告将以带有日期戳的文件名写入工作区目录（例如。 project_report_260215.md, task_report_build-auth_260215.md).当天文件被覆盖。

版本控制

Git操作（检查点、提交、推送、日志、状态、差异、文件历史、文件还原）由提供 使用 mcpp-git 作为 dev_* 工具。呼唤老人 plan_* git工具名称返回一条重定向消息，指向正确的 dev_* 等效。

配置工具

效用

用法

您通过您的代理以自然语言与计划进行交互。示例：

"Create a task called build-auth with steps: design schema, implement JWT, add middleware, write tests"

"What am I working on?"

"Mark step 1 as done"

"Switch to step 2"

"Add a note: decided to use refresh tokens"

"Show me all my tasks"

"Switch to the fix-search task"

代理会自动将这些转换为MCP工具调用。

步骤生命周期

planned  →  started  →  complete

只能迈出一步 started 在任务中的某个时间。当你切换步骤时，新的步骤变成 started.完成一步标志着它 complete.

钞票种类

笔记有 kind 对其目的进行分类的字段：

设置注释

使用 _set 创建或更新笔记的工具。对于目标/计划类型，注释按类型排列（每个任务只有一个目标和一个计划）。对于常规笔记，请通过 id 更新或省略以创建新：

plan_task_notes_set  text="Implement user authentication"  kind="goal"
plan_task_notes_set  text="Use JWT with refresh tokens"    kind="plan"
plan_task_notes_set  text="Decided to skip OAuth for now"

再次设定目标或计划会取代现有的目标或计划——没有重复。

札记

使用 _get 查看笔记的工具。笔记会返回ID，以便您可以更新或删除它们：

plan_task_notes_get                  # all notes
plan_task_notes_get  kind="goal"     # only goal notes

更新和删除笔记

把纸条递给我 id （返回者 _get, _set, show，以及 switch)要更新或删除：

plan_task_notes_set     text="Revised note"  id=42    # update note 42
plan_task_notes_delete  id=42                          # delete note 42

工作流执行

默认情况下，任务至少需要一个 goal 还有一个 plan 在切换或完成步骤之前请注意。这确保了每项任务在实施之前都有明确的目标和方法。在中禁用此功能 config.yaml:

workflow:
  require_goal_and_plan: false

显示

plan_task_show 和 plan_task_switch 内联显示目标和计划注释，并返回所有带有ID的注释，因此目的和方法始终可见，注释可以在一次后续通话中更新。 plan_step_show 和 plan_step_switch 同样，包括带有ID的步骤注释。

迁移的任务

在引入注释类型之前存在的任务具有迁移占位符注释("(migrated — no goal defined)").这些内容未显示在 plan_task_show 并且不满足工作流执行。通过在这些任务中添加真正的目标和计划注释来取代它们。

任务采纳

使用 plan_task_adopt 将其他用户的任务（或克隆您自己的任务）深度复制到您的任务列表中。当多个代理或用户想要独立处理类似的任务时，或者当你想将一个任务作为起点时，这很有用。

plan_task_adopt  name="build-auth"  new_name="build-auth-v2"

被复制的内容：

• 任务元数据（名称、描述）
• 所有步骤（重新映射父引用）
• 所有任务级笔记（目标、计划、笔记）
• 所有步骤级别注释

什么意思 不 复制：

• 变更日志——创建了一个“从｛user｝/｛task｝采用”条目

默认情况下，所有步骤状态都重置为 planned 所以你要重新开始。通过 reset=false 以保持原始状态。

所采用的任务将自动激活。A. new_name 如果项目中已存在具有源名称的任务，则需要。

数据库

所有州都位于一个SQLite数据库中 plan.db 在模块目录中，在所有项目中共享。每个项目都由其绝对文件系统路径标识。

模式

核心表：

• project --工作区元数据（名称、路径、描述）
• users --具有可选显示名称的操作系统用户
• contexts --任务（名称、状态、所有者、项目）
• tasks --任务中的步骤（标题、状态、排序）
• context_state --每个任务的活动步骤光标
• user_state --每个项目每个用户的活动任务光标
• context_notes / task_notes --打字笔记(goal, plan, note)
• changelog --所有状态更改的审核日志

模式迁移是通过中的编号补丁自动应用的 schema_patches/.

配置

全局设置已生效 config.yaml 在模块目录中（旁边 plan.db).该文件是可选的——所有键都有合理的默认值。设置按部分组织。

workflow:
  require_goal_and_plan: true      # require goal and plan notes before step progress
  allow_reopen_completed: false    # allow switching to completed tasks (reopens them)
  daily_backup: true               # create one backup per day on first use
  backup_retain_days: 7            # delete backups older than this many days
  enable_steps: true               # set false to hide step tools and strip step data

功能切换

禁用不需要的功能：

workflow:
  enable_steps: false        # hide step tools, strip step data from results

禁用时：

• 工具对MCP发现隐藏(tools/list)
• 直接调用返回一个明确的错误： "Tool 'X' is disabled (enable_Y: false in config.yaml)"
• 从任务结果和显示文本中删除步骤数据

默认值

行为

• 缺少文件=所有默认值
• 缺少密钥=这些密钥的默认值
• 未知密钥保留在文件中，但被系统忽略
• 无效的YAML将恢复为所有默认值

工具

• plan_config_show --显示当前设置（合并默认值+覆盖）
• MCP的配置是只读的--编辑 config.yaml 直接更改设置

迁移安全

架构迁移受到多层安全管道的保护(backup.py):

1. 已验证备份 -- plan.db 已复制到 .backups/plan.db.YYMMDDx 并且在继续之前，SHA-256校验和被验证为与实时DB匹配。
2. 在副本上进行试迁移 --所有补丁首先应用于数据库的临时副本。如果试验失败（SQL错误或数据丢失），则永远不会接触实时数据库。
3. 行数验证 --试验后，将每个表的行数与迁移前的行数进行比较。任何减少都会中止迁移。
4. 实时迁移+重新验证 --只有在试验通过后，才会将补丁应用于实时数据库，然后进行第二行计数验证。

如果在任何步骤中出现任何失败，迁移将中止，并显示一条明确的错误消息和备份文件的路径。实时数据库保持不变。

备份使用字母后缀(a-z)用于在同一天进行多个备份。应用补丁时会创建迁移备份。此外，每天首次使用时都会运行每日自动备份（可通过以下方式配置 daily_backup)，自动修剪早于 backup_retain_days.

提示和技巧

向代理人介绍一个新项目。 当开始处理新的代码库时，让代理先探索它：

> Discover what this project is about, including its structure,
> and add what you learn to the project notes.

这使代理能够构建自己对代码库的理解——什么在哪里，事物是如何连接的，使用了什么约定——并为未来的会话保留该上下文。

在不失去焦点的情况下捕捉想法。 如果你在处理任务时发现了一个无关的问题或想到了一些事情，告诉代理人注意并继续：

> Add a task: "refactor the cache expiry logic" -- then continue
> what you were doing.

这可以保持你当前的思维流不变，同时确保思想不会丢失。

让代理人先计划一下。 对于复杂的任务，在编写代码之前先考虑一下：

> Plan how you'd approach this before writing code.

使用帮助进行发现。 代理可以调用内置 help 工具查看可用内容——无需记住工具名称：

> What mcpp tools do you have?

建筑

tool.yaml          MCP tool definitions (schema for all plan_* tools)
mcpptool.py        MCP entry point -- routes tool calls to Python API
context.py         Business logic (create/switch/complete tasks and steps)
config.py          Global configuration (config.yaml loading + defaults)
db.py              SQLite connection, schema management, user/project helpers
backup.py          Migration safety pipeline (verified backup, trial-on-copy, row validation)
schema.sql         Base schema
schema_patches/    Incremental migrations (patch-4.sql through patch-11.sql)

入口点

• execute(tool_name, arguments, context) --每次工具调用时由MCP主机调用
• get_info(context) --返回工具元数据和用于自动完成的现有任务名称

工具调用的流程

1. MCP主机呼叫 execute("plan_step_done", {"number": 3}, {"workspace_dir": "/my/project"})
2. mcpptool.py 路线 _cmd_step_done
3. 处理程序构建命令列表并调用 _run_plan_cmd
4. _run_plan_cmd 动态导入 db.py 和 context.py，打开中央数据库，并分派
5. context.py 在事务中运行操作
6. 结果字典返回结构化数据和 display 用户的字符串

灵感源自

这个项目的灵感来自 安德烈亚斯·斯皮斯 ()和他的 人工智能辅助编码视频.

发布说明

看 发布.md 查看完整版本历史。

许可证

PolyForm非商业版1.0.0

免费供个人使用、研究、教育、非营利组织和政府使用。不允许用于商业用途。看 许可证 全文。