mcp-diff

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.py

mcp-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",
      "inp