0-co/mcp-diff
Schema lockfile and breaking-change detector for MCP servers — like package-lock.json for MCP
Platform-specific configuration:
{
"mcpServers": {
"mcp-diff": {
"command": "npx",
"args": [
"-y",
"mcp-diff"
]
}
}
}Add the config above to .claude/settings.json under the mcpServers key.
Schema lockfile and breaking-change detector for MCP servers.
The problem: MCP servers serve tool schemas at runtime. When a description changes, agent behavior changes silently — no diff, no CI failure, no warning.
The solution: Commit a mcp-schema.lock to git. Fail CI on breaking changes.
pip install mcp-diff# Snapshot your server's current schema
mcp-diff snapshot python3 my_server.py
# Check for breaking changes (exits 1 if found)
mcp-diff check python3 my_server.py
# Human-readable report (always exits 0)
mcp-diff report python3 my_server.pymcp-diff check python3 my_server.py
[BREAKING] read_file: Tool 'read_file' was removed.
[BREAKING] search_files.pattern: Parameter 'pattern' type changed: 'string' → 'array' in tool 'search_files'.
[WARNING] search_files: Tool description changed.
was: 'Search for files matching a pattern.'
now: 'Search files. Use glob patterns.'
[INFO] write_file: Tool 'write_file' was added.
Found 2 breaking, 1 warning, 1 info changes.| Severity | When | CI impact | |---|---|---| | breaking | Tool removed, required param added/removed, param type changed | exits 1 | | warning | Tool or param description changed (descriptions are behavioral contracts for LLMs) | exits 0 | | info | Tool added, optional param added | exits 0 |
- name: Snapshot MCP schema
run: mcp-diff snapshot python3 my_server.py
# Commit mcp-schema.lock to your repo
- name: Check for breaking changes
run: mcp-diff check python3 my_server.py
# Exits 1 and fails the build if breaking changes are detected{
"version": "1",
"created_at": "2026-03-22T03:00:00Z",
"command": "python3 my_server.py",
"tools": [
{
"name": "search_files",
"description": "Search for files matching a pattern",
"inpLoading reviews...