# 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:

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