MCP Server Interface
Relevant source files
The following files were used as context for generating this wiki page:
The Model Context Protocol (MCP) Server Interface for chkpt provides a standardized way for AI agents and LLM-powered tools (such as Claude Code) to interact with the filesystem checkpoint engine. It acts as a bridge between the core Rust library and external clients, exposing tools for saving, listing, restoring, and deleting workspace snapshots.
The interface is implemented as a standalone Rust crate (chkpt-mcp) that utilizes the rmcp crate and standard I/O (stdio) transport for communication. It allows AI assistants to proactively protect user work by suggesting checkpoints before risky operations and executing them directly through a set of defined MCP tools.
Sources: CLAUDE.md:12, README.md:16-24, crates/chkpt-mcp/Cargo.toml:10-18
Architecture and Components
The MCP server is part of the broader chkpt workspace and is designed to wrap the functionality provided by chkpt-core. It is distributed both as a Rust binary and as an npm package (@chkpt/mcp) for easy integration via npx.
System Context
The following diagram illustrates how the MCP Server fits into the overall chkpt ecosystem:
The MCP Server functions as one of several interfaces (alongside CLI and Node.js bindings) to the core engine.
Sources: README.md:92-99, CLAUDE.md:10-16
Key Dependencies
The server relies on several key Rust crates to function:
chkpt-core: The underlying logic for scanning, hashing, and storage.rmcp: The implementation of the Model Context Protocol.tokio: The asynchronous runtime.serde/serde_json: For serialization of MCP messages and data structures.
Sources: crates/chkpt-mcp/Cargo.toml:9-18
MCP Tools Reference
The interface exposes four primary tools that allow a client to manage checkpoints. All tools require a workspace_path to identify the project context.
| Tool Name | Description | Required Parameters | Optional Parameters |
|---|---|---|---|
checkpoint_save | Saves a new workspace snapshot | workspace_path | message (String) |
checkpoint_list | Lists available checkpoints for the workspace | workspace_path | limit (Integer) |
checkpoint_restore | Restores the workspace to a specific snapshot | workspace_path, snapshot_id | dry_run (Boolean) |
checkpoint_delete | Removes a specific snapshot from the store | workspace_path, snapshot_id | N/A |
Sources: crates/chkpt-plugin/SKILL.md:13-16, crates/chkpt-plugin/README.md:15-20
Parameter Definitions
- workspace_path: The absolute path to the root of the project being checkpointed.
- snapshot_id: A unique identifier for a specific checkpoint, typically a 16-character hex string derived from the project path and metadata.
- dry_run: A critical flag for the restore operation. If true, the server returns the changes that would be made without modifying the filesystem.
Sources: crates/chkpt-plugin/SKILL.md:41-45, crates/chkpt-napi/test/config.spec.ts:9-11
Operation Workflows
The MCP Server is often utilized by the Claude Code plugin to implement proactive automation.
Restore Safety Workflow
To prevent accidental data loss, the interface and its consuming skills enforce a "Dry Run First" pattern.
Proactive Saving
The MCP interface is designed to support automation patterns where an agent detects "risky" operations (e.g., large refactors, dependency updates, or directory deletions) and suggests a checkpoint_save before proceeding.
Sources: crates/chkpt-plugin/SKILL.md:23-31, crates/chkpt-plugin/skills/chkpt/references/automation-patterns.md:3-15
Deployment and Execution
The server is available across multiple platforms including macOS (arm64, x64), Linux (arm64, x64), and Windows (x64). It can be executed via Cargo or through the npm distribution.
Execution Commands
# Running via Cargo (development)
cargo run -p chkpt-mcp
# Running via npx (production)
npx @chkpt/mcp
Sources: CLAUDE.md:24, README.md:55-57, crates/chkpt-mcp-npm/package.json:5-7
Implementation Detail: Transport
The server uses stdio as its transport layer, which is the standard for MCP implementations where the host application (like Claude Code) spawns the server as a subprocess.
Sources: CLAUDE.md:14, crates/chkpt-plugin/README.md:28-29
Summary
The MCP Server Interface provides a robust, tool-based API for filesystem state management within the chkpt ecosystem. By exposing core functionalities like atomic restoration and content-addressed saving through standardized protocol tools, it enables AI agents to provide a safety net for developers during complex or risky workspace operations. Key to its design is the enforcement of user confirmation through dry-run previews and the utilization of efficient, content-deduplicated storage.