checkpointer

MCP server for file checkpointing and undo. Built with the Python MCP SDK v2 (mcp[cli] 2.0.0b1), implementing the 2025-07-28 MCP spec.

Lets an AI agent safely read, write, and edit files within a project directory while maintaining a full snapshot history. Changes can be reverted per-file or globally without requiring git or any external VCS.

How it works

All file state is tracked in a .checkpointer/ directory at the project root. Before any mutating tool runs, the current file content is hashed, compressed, and stored as a snapshot. A master ledger (master.json) records the per-file undo stack and a global edit history.

This adds minimal token overhead — snapshots are stored on disk, not in context.

Tools

Tool	Description
read_file	Read a file with line numbers. Smart-truncates large files (head+tail). Supports start_line/end_line for ranges.
list_directory	List directory contents, optionally recursive to a given depth.
write_file	Overwrite or create a file. Snapshots before writing.
edit_file_lines	Replace a line range. Returns surrounding context with line numbers.
str_replace	Content-based find-and-replace. old_str must be unique in the file. No line numbers needed.
undo_file_edit	Revert a specific file to its state before the last mutation.
undo_global	Revert whichever file was last mutated.
revert_file	Discard all AI changes for a specific file.
reset_session	Revert all AI changes across the project and delete history.
get_session_diff	Unified diff of a file against its original state.

Setup

Requires Python 3.10+.

uv sync

Set PROJECT_DIR to the root of the project you want to checkpoint:

PROJECT_DIR=/path/to/project uv run main.py

Configuration

After cloning the repo, add to your Claude Code MCP config:

{
  "mcpServers": {
    "checkpointer": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/path/to/this/repo/",
        "server.py"
      ],
      "env": {
        "PROJECT_DIR": "/path/to/target/project/"
      }
    }
  }
}