Agent Config Snapshot Mcp

[](README.md) [](README_zh.md)

Agent Config Snapshot MCP

> Git-style snapshots for AI agent config files — your safety net when agents go rogue.

[](https://python.org) [](https://modelcontextprotocol.io/) [](LICENSE) [](https://github.com/TheIanLi/agent-config-snapshot-mcp/actions/workflows/test.yml)

Why This Exists

One day, I asked my AI agent to tweak a config. It modified config.yaml, rewrote SOUL.md, and then—the agent broke.

Not "hmm, this setting looks odd" broke. Corrupted-personality, fails-to-start, can't-even-read-the-error broke. I spent half a day manually reverting a dozen scattered changes. That's when it hit me: the same agent that manages my configs can destroy them in seconds.

This tool grew out of that disaster. The idea is simple — bring VM-style snapshots to agent config files. When things go wrong, roll back. One command, instant recovery.

What It Does

agent-config-snapshot-mcp gives your config files a time machine:

• Automatic capture with zero resident processes: the MCP server takes a baseline when your session starts and captures changes before each of its own tool calls — nothing to keep running in the background
• Content-addressed storage (CAS): identical content is stored once, every read is integrity-checked, rollback writes are atomic
• Diff the current version against any snapshot
• Roll back to any version with one command (the current state is auto-saved first)

Works as a standalone CLI and as an MCP server your AI agent can call directly.

How Automatic Capture Works (the no-daemon design)

The edit that corrupts your config usually never passes through this tool — the agent edits files with its own tooling. So capture happens in three layers, none of which needs a resident process:

| Layer | Mechanism | Coverage | |------|------|---------| | L0 session baseline | When the host agent launches the MCP server, every protected file is hash-compared and captured if changed | Every MCP-capable agent (Claude Code / Gemini / Codex / Hermes / OpenClaw…) | | L1 lazy checkpoint | Before each call to one of this server's own tools, changed files are captured first | Same as above | | L2 pre-edit hooks | agent-snapshot hooks prints host hook configs that run capture --quiet before every file edit | Hosts with hook support (Claude Code, Gemini CLI ≥0.26) |

Note the coverage boundary: L1 only fires before this server's own tool calls — the agent's own Edit/Write tooling does not go through this server, so a mid-session edit made with no snapshot tool call in between is not captured on its own. For a targeted operation (diff/rollback), the target label is also deliberately excluded from that pre-op checkpoint (so the pre-op capture can't prune away the very snapshot you're reading). Per-edit coverage is exactly what the L2 hooks add.

The result: when you notice a broken config and ask the agent to roll back, a good earlier version is already in the store. Without the L2 hooks, rollback granularity is "the session-start baseline plus every point where a snapshot tool was invoked" — install the hooks if you want a snapshot before every single edit.

Features

| Feature | CLI | MCP | Notes | |---------|:---:|:---:|-------------| | Discovery | — | ✓ | list_protected_files lists protected files and snapshot counts | | Snapshot | ✓ | ✓ | Save current state; deduplicated when content is unchanged | | History | ✓ | ✓ | List all snapshots (with snapshot_id), newest first | | Diff | ✓ | ✓ | Unified diff between the current file and any snapshot (by id) | | Rollback | ✓ | ✓ | Restore by id (current version auto-saved first, atomic write) | | Bulk capture | ✓ | — | capture grabs all changes at once, for hooks / cron | | Retention | ✓ | ✓ | Configurable max snapshots per file with auto-pruning | | Legacy migration | ✓ | — | migrate imports ≤0.3.x file-based snapshots (timestamps and reasons preserved) |

Quick Start

# 1. Clone
git clone https://github.com/TheIanLi/agent-config-snapshot-mcp.git
cd agent-config-snapshot-mcp

# 2. Install dependencies
uv sync

# 3. Initialize from a preset
uv run agent-snapshot init --preset hermes

# 4. Take your first snapshot
uv run agent-snapshot snapshot hermes_data/SOUL

# 5. View history (each entry has a snapshot_id)
uv run agent-snapshot list hermes_data/SOUL

> Platforms: Linux / macOS / Windows

CLI Reference

> The examples below assume the venv is activated (source .venv/bin/activate on Linux/macOS, .venv\Scripts\activate on Windows); otherwise prefix each command with uv run, e.g. uv run agent-snapshot init.

init — Initialize configuration

# Use a preset (recommended)
agent-snapshot init --preset hermes       # Hermes Agent
agent-snapshot init --preset openclaw     # OpenClaw
agent-snapshot init --preset claude-code  # Claude Code
agent-snapshot init --preset gemini       # Gemini CLI
agent-snapshot init --preset codex        # Codex CLI

# Interactive scan (auto-detects installed agents)
agent-snapshot init

# Scan extra directories — supports any agent, even ones not in the built-in list
agent-snapshot init --scan-dir ~/.my-agent

# Non-interactive: protect everything detected, no prompts
agent-snapshot init --all

# Overwrite an existing config (refused by default to protect your curated list)
agent-snapshot init --preset hermes --force

> By default init will not overwrite an existing snapshot-config.yaml. Pass --force (-f) to regenerate.

How scanning works: detection is not filename-based — every agent directory is scanned for small config-looking files (.yaml / .yml / .json / .md / .toml / .env, under 1MB), automatically skipping bulky dirs like sessions / logs / cache.

> Every file gets a unique label. Duplicate labels fail fast at config load time.

snapshot — Manual snapshot

agent-snapshot snapshot 
# If content matches the latest snapshot you'll be told "not created" — no duplicate pileup

list — Snapshot history

agent-snapshot list 
# Example output:
#   a3f8c2d19b04  2026-07-01 21:30:12  2.5KB  [manual]
#   7e12ff08aa31  2026-07-01 18:04:55  2.8KB  [auto]
#   09cc41b7d2e6  2026-07-01 09:11:02  2.8KB  [baseline]

The first column is the snapshot_id (sha256 prefix of the content). It is content-derived and never shifts when new snapshots appear — an id always points to the same bytes.

diff — Compare changes

agent-snapshot diff  
# Example
agent-snapshot diff hermes_data/SOUL a3f8c2d1   # any unique prefix of 4+ hex chars works

rollback — Restore a snapshot

agent-snapshot rollback  

The current version is auto-saved as a safety snapshot first; the write-back is atomic (temp file + rename), so a full disk or power loss can't leave a half-written file.

capture — Bulk change capture

agent-snapshot capture           # capture all changed protected files and print results
agent-snapshot capture --quiet   # silent, always exits 0 — designed for host hooks / cron

hooks — Generate pre-edit hook configs

agent-snapshot hooks   # prints hook snippets for Claude Code / Gemini CLI

migrate — Import legacy snapshots

agent-snapshot migrate   # imports ≤0.3.x file-based snapshots, preserving timestamps and reasons; originals untouched

> watch removed: the 0.3.x watcher daemon was removed in 0.4.0. Running agent-snapshot watch now just prints migration guidance pointing to hooks / capture instead of doing anything.

Snapshot Reason Tags

| Tag | Trigger | |-----|---------| | baseline | MCP server session-start baseline | | auto | Lazy checkpoint before an MCP tool call | | hook | Host pre-edit hook / capture --quiet | | manual | Manual snapshot command | | safe | Auto-saved safety snapshot before rollback |

Configuration

# snapshot-config.yaml
protected_files:
  - path: ~/.hermes_data/config.yaml
    label: hermes_data/config          # unique id used by CLI/MCP
  - path: ~/.hermes_data/SOUL.md
    label: hermes_data/SOUL
  - path: ~/.hermes_data/.env
    label: hermes_data/.env

snapshot_dir: ~/.agent-snapshots/      # snapshot storage path
retention:
  max_snapshots_per_file: 50           # max snapshots per file, pruned automatically

> Legacy (≤0.3.x) watch / daily_time fields are accepted and ignored — old configs keep working without edits.

> Where the config is found: the CLI and the MCP server share one discovery order — the SNAPSHOT_CONFIG env var, then snapshot-config.yaml in the current directory, then ~/.agent-snapshots/snapshot-config.yaml. The home-directory fallback lets agent-snapshot run from any directory. Malformed fields (e.g. a scalar retention, a protected_files entry missing path) are rejected with a readable error instead of a raw traceback.

MCP Integration

{
  "mcpServers": {
    "agent-config-snapshot": {
      "command": "uv",
      "args": ["run", "agent-snapshot-mcp"],
      "cwd": "/path/to/agent-config-snapshot-mcp"
    }
  }
}

Your agent gets 5 MCP tools:

| Tool | Purpose | |------|------| | list_protected_files | Discover labels and snapshot counts (the entry point for the other tools) | | snapshot(label) | Manual snapshot (explicitly reports when content is unchanged) | | list_snapshots(label) | History with snapshot_ids | | diff_snapshot(label, snapshot_id) | Compare changes | | rollback(label, snapshot_id) | Roll back (automatic safety snapshot) |

> Note: if the agent is completely broken and its MCP server won't start, the CLI (agent-snapshot rollback) runs independently — that's your real lifeline.

> Windows note: the snapshot directory is hardened best-effort with ACLs (icacls). Since snapshots contain plaintext secrets like .env / auth.json, please verify the directory is accessible only to you.

Safety & Reliability Design

| Mechanism | Details | |-----------|--------| | Pre-rollback snapshot | Every rollback first saves the current version as a safe snapshot — zero data-loss risk | | Atomic write-back | Rollback uses temp file + rename; a crash or full disk can't leave a half-written target | | Integrity check | Every snapshot read verifies sha256 — a corrupted snapshot fails loudly instead of silently restoring bad data | | Content dedup | Identical content is stored as one blob; repeated baselines and no-op triggers no longer eat retention slots | | Tolerant index | One corrupted index record loses only itself, never the whole label's history | | Retention cap | Configurable max snapshots per file, oldest pruned automatically | | Permission hardening | Snapshot dir forced to 700 (owner-only). ACL (icacls) on Windows | | Path sanitization | Labels are whitelist-sanitized (Unicode letters/digits plus _ . -, CJK preserved), preventing traversal and Windows reserved-name collisions |

Project Structure

agent-config-snapshot-mcp/
├── src/agent_snapshot/
│   ├── __init__.py        # Package init
│   ├── server.py          # MCP server (5 tools + L0/L1 auto capture)
│   ├── service.py         # Use-case layer shared by CLI and MCP
│   ├── store.py           # Content-addressed store (blobs + index.jsonl)
│   ├── migrate.py         # Legacy snapshot import
│   ├── config.py          # Config types and loading
│   ├── cli.py             # Command-line interface
│   ├── compat.py          # Cross-platform layer (POSIX / Windows)
│   ├── presets/           # Presets (hermes / openclaw / claude-code / gemini / codex)
│   └── __main__.py        # python -m entry point
├── tests/                 # Test suite
└── pyproject.toml

Dependencies

• Python ≥ 3.10
• [mcp[cli]](https://github.com/modelcontextprotocol/python-sdk) ≥ 1.0 — MCP protocol
• pydantic ≥ 2.0 — snapshot record validation
• PyYAML ≥ 6.0 — config parsing

License

MIT License

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: TheIanLi
• Source: TheIanLi/agent-config-snapshot-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.