zerto-ai-rewind/CONTEXT.md

Zerto AI Rewind

PoC MCP that teaches an agent to discover Zerto protection, pin a tagged checkpoint before changing a VM, and recover a file from that tag. If the loop works, these tools are the delta to put in official ZVM MCP.

Language

Tagged checkpoint: A named bookmark in a VPG journal, inserted by POST /v1/vpgs/{id}/checkpoints (startVpgTaggedCheckpointInsert). Crash-consistent write-order only; not application-quiesced unless someone scripted that separately. CheckpointName is the only field the API accepts, so agent and intent go in the name: ai:<agent> | <action> | vm=<vm> | change=<id> | <utc>. Inserts are async tasks and are silently dropped if fired back to back at one VPG; insert, then wait until listed. Avoid: user checkpoint, snapshot, backup, restore point (unqualified)

VPG: A Virtual Protection Group. One to many VMs sharing a journal. A VM can belong to at most three VPGs, recovered to different sites. Avoid: job, policy, replication group

Rewind: The agent loop: find protection, tag every protecting VPG, mutate, then bounded recover. Not a Zerto product name. Avoid: failover (that's DR), undo (that's git or Moholo)

Bounded recover: FLR, offsite clone, or failover test. Failover Live is not a rewind tool. Avoid: recover (unqualified), fail back, restore the VPG

File-level recovery (FLR): Mount a VM from a journal checkpoint and pull files. The VM stays up. 10.9 FLR Operator RBAC is broken; Administrator is the documented workaround. Runs at the VPG's recovery site, so this server supports it only for locally replicated VPGs (protected site == recovery site). Paths are partition-rooted; on Windows the drive letter is the partition. Avoid: file restore (unqualified), instant restore (local-journal VMs only, not v1)

find_protection: Resolve a VM name, hostname, or Zerto vmIdentifier to exactly one VM and every VPG it is in. Zero or two-plus VMs is a hard stop. Avoid: GetVms (that's the raw inventory call)

Protecting VPG: A VPG whose status is MeetingSLA or a NotMeetingSLA variant, and whose substatus is not a sync. Only these get tagged. 10.9 status 0 is Initializing, not Protecting. A resync deletes existing checkpoints. Avoid: healthy, in sync, Protecting (as status 0)

Mutating catalog: The opt-in list of MCP tools that must call zerto_guard_before_mutate first. Paired with read_only_tools, the list known not to change a guest. A tool in neither is unknown, which is the normal case: the agent asks the human whether to checkpoint rather than assuming either way. Avoid: denylist, hold-everything, treating unknown as safe

Zerto task: Write operations return a task id, not a result. A 200 means queued. GET /v1/tasks/{id} carries the real outcome in Status.State: 1 InProgress, 4 Failed, 5 Stopped, 6 Completed (terminal is 4/5/6). A second tagged-checkpoint insert fired at a VPG while the first runs comes back Failed, which is only visible if the task is read. Avoid: treating HTTP 200 as success

Official ZVM MCP: HPE Zerto 10.9 MCP (ZVM.MCP): inventory, VPG settings, failover test. Not in the demo path. This PoC is one server. Avoid: Zerto MCP (unqualified when you mean this repo)