Task Checkpoint MCP

给长任务做"做一步、存一步"的存档：中断后新会话能接着做，做错了能退回任意一步。

一个 stdio MCP 服务器，只用 Python 标准库，不装任何第三方包。

快速开始 | 工具 | 客户端配置 | 使用限制 | English

快速开始

一、装

pipx install task-checkpoint-mcp

二、在客户端里接上（Claude Code、Codex、Cursor 等都是同一段配置）

{
  "mcpServers": {
    "task-checkpoint": { "command": "tc-mcp", "args": [] }
  }
}

三、把 SKILL.md 装进技能目录，不装的话 Agent 不会主动存档

tc-mcp --install-skill ~/.claude/skills/task-checkpoint

SKILL.md 随包一起装（wheel 里的包数据），不需要仓库、也不需要联网。想看内容用 tc-mcp --print-skill，想知道它在哪用 tc-mcp --skill-path。

（技能目录按客户端而定，见下面"把 SKILL.md 装进 Agent 的技能目录"。）

四、交给 Agent 用。 一个任务就四步：

tc_init    开任务
tc_save    每完成一步存一次（带 conclusion 和 next）
tc_resume  新会话开头先调这个接上进度
tc_restore 退回去（先 apply:false 预览，再 apply:true）

五、不用记工具名，直接说人话。

用 task-checkpoint 开个任务，目标是把 user 模块拆成 service 和 repository 两层。每完成一步存一次档，带结论和下一步。

它会调 tc_init 建任务，之后每完成一步调一次 tc_save。中途换会话、或者隔天接着做，你说一句"接着上次的做"，它调 tc_resume 就把进度拿回来了。

（"每完成一步就存档"这条约束的可靠来源是 SKILL.md —— 装进技能目录之后它是硬规则；不装，就只能靠你每次提醒。）

中途被打断、隔天换个模型重开，新会话调一次 tc_resume 拿到的是这个：

任务：重构认证模块
目标：把 session 改成 JWT
当前步骤：3
下一步：把三个视图函数切到新入口，删旧函数
未落档：src/views/auth.py, src/views/user.py

handoff 字段就是这段文本，可以直接粘给新会话。它同时告诉你哪几个文件改了但还没落档。

为什么不直接用 git stash 或随手 commit 一下

值得装：多步、可能被中断、需要能退回的编码或文档任务。 不值得装：一次能做完、不需要回退也不需要交接的改动。

装之前先知道

• 需要 Python 3.10 或更新，只用标准库。
• 不碰你的 git 历史：不 commit、不 reset、不 clean、不动已有分支和 HEAD，只额外加 refs/checkpoints/... 引用。
• 不是 git 仓库也能用，功能一样，只是少了那层 git 引用。
• 不保存聊天记录，只保存工作区文件和模型主动声明的步骤说明。
• 存档默认写在工作区的 .checkpoints/；指定外部 store 时，工作区仅留一个不含文件内容的 .task-checkpoint-store.json 路径指针。
• 敏感文件识别是路径黑名单，盖不全。 别把凭据放在被扫路径里 —— 详见"使用限制"。

安装

方式一：装成命令（推荐）

pipx install task-checkpoint-mcp
# 或
pip install task-checkpoint-mcp

也可以直接从 git 装，跟着仓库走、不走 PyPI 的版本号：

pipx install "git+https://github.com/qddfxp/task-checkpoint-mcp"

装完在客户端里用 tc-mcp 启动。包里有两个等价的入口点：tc-mcp 和 task-checkpoint-mcp（后者是给 uvx 这类按包名找命令的 runner 用的）：

{
  "mcpServers": {
    "task-checkpoint": { "command": "tc-mcp", "args": [] }
  }
}

方式二：直接用源码（不用安装）

git clone https://github.com/qddfxp/task-checkpoint-mcp

{
  "mcpServers": {
    "task-checkpoint": {
      "command": "/absolute/path/to/python",
      "args": ["/absolute/path/to/task-checkpoint-mcp/scripts/tc_mcp.py"]
    }
  }
}

command 要写解释器的绝对路径，不要写 python —— 客户端不一定能解析到你要的那个。装过之后也可以直接 python -m tc_mcp。

方式三：用 npx 启动

npm 上有一个同名的 task-checkpoint-mcp，但它是启动器，不是服务器本体：

npx -y task-checkpoint-mcp

它只做一件事：找到本机装了 tc_mcp 的 Python 解释器，然后把 stdio 透传给 python -m tc_mcp。所以本机仍然要先有 Python 包（方式一或方式二）。没有的话它会打印安装命令、以退出码 1 结束，而不是丢一堆 traceback 给你。

适合客户端只认 npm 式启动命令的情况：

{
  "mcpServers": {
    "task-checkpoint": { "command": "npx", "args": ["-y", "task-checkpoint-mcp"] }
  }
}

npx -y task-checkpoint-mcp --version / --help 是启动器自己的开关，不需要本机有 Python。

配置文件放哪

上面那段 mcpServers JSON 要写进客户端的配置文件。各客户端的位置和顶层键：

两个容易踩的：

VS Code 的顶层键是 servers，不是 mcpServers。 直接抄上面的 JSON 不会生效，得改键名：

{
  "servers": {
    "task-checkpoint": { "command": "tc-mcp", "args": [] }
  }
}

Codex 用 TOML。 同样一段配置要写成：

[mcp_servers.task-checkpoint]
command = "tc-mcp"
args = []

其余客户端以各自的文档为准。

怎么用

最重要的一条：文件变化由后台线程自动记录，但"这一步在做什么、结论是什么、下一步干什么"只有模型主动调 tc_save 才会留下。

所以要让 Agent 每完成一步就存一步 —— 这份约束写在 SKILL.md 里，得把它装进 Agent 的技能目录（见下面"把 SKILL.md 装进 Agent 的技能目录"）。不装它，文件回退点照常产生，但没人知道当初要干什么、下一步该干什么。

四条铁律：

1. 开长任务前先 tc_init，一个任务一个名。已有活动任务会被挂起而不是关闭，可以 tc_switch 切回去。
2. 每完成一步就 tc_save，并且必须填 conclusion 和 next。不填，新会话就只看得到一堆文件路径。
3. 新会话、或中断后继续时，第一件事是 tc_resume，不要从零猜进度。
4. 回退前先预览：先 apply: false 看清单，确认了再 apply: true。

一步的粒度：能独立说清"做完了、结论是 X"的单元。太细（每个文件一次）会淹没有效信息，太粗（整个任务一次）就失去了回退的意义。

工具

10 个。第一个参数都是 root，指工作区目录（通常是当前项目的绝对路径）。

tc_save 的完整参数：

• title（必填）——这一步一句话标题，写"做了什么"，不写"改了什么"
• conclusion——这一步的结论。最有价值的字段
• next——下一步要干什么。接续工作的关键
• description——为什么这么做（决策理由，事后没人记得）
• verified——已验证项列表（跑了什么测试、确认了什么事实）
• open_questions——还没解决、留给后面的问题
• close: true——收尾时用。关闭后不能再存档，但还能读

回退操作本身也会被记成一条变更记录，返回里的 recovered 就是它的 drift_id —— 退错了可以再用它退回来。

返回值里几个值得看的字段

• tc_resume.handoff —— 一段现成的交接文本，可以直接粘给新会话；drift_paths 是工作区里还没落档的改动；health.errors 是存档自身的问题
• tc_save.idempotent —— 同一步（标题、文件摘要、结论、下一步、已验证项都一样）重复存，不会产生重复步骤
• tc_save.active_task_changed —— 传了别人的 task_id 时活动任务会被切过去（原任务变 suspended），这个字段就是在提示这件事
• tc_restore.recovered —— 回退本身也会被记成一条变更记录，这就是它的 drift_id
• tc_restore.plan.unrestorable / skipped_paths —— 目标里没能还原的文件；预览和执行给的是同一份清单
• tc_capture.waiting / partial —— 还在静默期，以及中间那条不完整的记录
• tc_init.exclude —— 回读你这次设进去的排除模式
• tc_export.path —— 交接包目录，里面有一个 HANDOFF.md，是给接手方的提示词

把 SKILL.md 装进 Agent 的技能目录

SKILL.md 是这个项目的另一半功能，不是可选文档：MCP 服务器负责存取，SKILL.md 负责让模型每完成一步真的去调 tc_save。

复制到客户端扫描的技能目录，目录名即技能名：

~/.agents/skills/ 是多个客户端共用的技能目录；客户端专属目录优先于它 —— 同名技能以客户端专属目录里的那份为准。OpenCode 等其它客户端放到它自己文档里的技能目录即可，规则不变。

tc-mcp --install-skill ~/.claude/skills/task-checkpoint

SKILL.md 是随包一起安装的（wheel 里的包数据），所以 pipx install 的用户不需要仓库，也不需要联网。目标已存在时会拒绝覆盖 —— 确实要覆盖加 --force；只想看内容用 tc-mcp --print-skill。

克隆了仓库的话，cp SKILL.md <技能目录>/ 效果一样。

Windows 路径形如 C:\Users\<你>\.claude\skills\task-checkpoint\SKILL.md。各客户端的技能目录可能不同，以它自己的文档为准；要求只有一条：文件落在技能目录下的 <技能名>/SKILL.md。重启客户端后生效。

自检（可选）

装完最快的一条，确认入口点活着、拿到版本号：

tc-mcp --version        # 版本号
tc-mcp --help           # 所有开关

下面几条都要先克隆仓库 —— pip 装出来的包里没有 tests/ 和 tools/。

在克隆下来的仓库里跑一遍回归测试：

python -m unittest discover -s tests -p "test_*.py" -v

最后一行是 OK 就对了。整套测试（100 多个用例）跑一次的时间完全看环境：

同一套代码差了七十倍。开销集中在 git 子进程（refs/checkpoints/ 相关用例占大头）和静默期等待，对磁盘和杀毒的实时扫描极其敏感 —— 别把秒数当承诺，也别拿一个数字去对比另一台机器。

全部只用标准库，不需要 pytest；在 Python 3.10 上也能跑，只有读 pyproject.toml 的那几条会因为 tomllib 被跳过（3.11+ 全跑）。

仓库里还能跑真机端到端演练（起真 MCP 子进程、真杀进程、建约 190 MB 的重工作区、逐项核对"不动你 git"的承诺）：

python tools/drill.py

它跑完默认把场地删掉；想看场地就 TC_DRILL_KEEP=1 python tools/drill.py（演练有未通过项时也会自动保留，方便排查）。

确认 MCP 服务器能起来 —— 会回一行带 serverInfo 的 JSON：

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18"}}' | python scripts/tc_mcp.py

从 pip 装的版本没有 scripts/，把上面那条改成 ... | tc-mcp（或 python -m tc_mcp）就行。

环境变量

使用限制

敏感文件：黑名单，盖不全

敏感文件不存内容、连哈希都不存，只能看出 mtime 和 size 变了没有。判定按路径匹配，所以两头都会漏：

• 漏判：名字无辜的凭据抓不到。config/database.yaml、docker-compose.yml、config.json 会被当普通文件明文存进 payload/。别把凭据放在被扫路径里；避不开时用 tc_init(exclude=[...]) 把整个目录排掉。
• 误拦：被误判为敏感的源码永远拿不到内容副本，回退时会静默跳过（只出现在 plan.unrestorable 里）。名单分两层就是为压低误拦。

拦的范围：