Task Checkpoint MCP server

Task Checkpoint MCP

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

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

快速开始

一、装

pipx install task-checkpoint-mcp

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

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

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

mkdir -p ~/.claude/skills/task-checkpoint
curl -fsSL -o ~/.claude/skills/task-checkpoint/SKILL.md \
  https://raw.githubusercontent.com/qddfxp/task-checkpoint-mcp/main/SKILL.md

（技能目录按客户端而定，见下面"把 SKILL.md 装进 Agent 的技能目录"。如果 raw.githubusercontent.com 访问不了，先按下面"安装"里的方式二把仓库 clone 下来，再 cp SKILL.md 过去。）

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

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

中途被打断、隔天换个模型重开，新会话调一次 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。

怎么用

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

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

四条铁律：

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

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

工具

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

Shortened. The full README is on GitHub.