mcp-compat

Know before you deploy if you're breaking MCP users.

mcp-compat compares two MCP server schemas (before/after) and classifies every change as BREAKING, WARN, or SAFE. Gate your deploys on it.

mcp-compat: schema compatibility report

  2 BREAKING changes, 1 SAFE change

  BREAKING  get_weather  Parameter 'units' type changed: string → integer
  BREAKING  list_items   Required parameter 'limit' removed
  SAFE      create_item  New optional parameter 'tags' added

  Run with --ci to fail CI on breaking changes

Install

pip install mcp-compat

No external dependencies. Python 3.9+.

Quick start

# Compare two local schema files
mcp-compat before.json after.json

# Fail CI on breaking changes
mcp-compat before.json after.json --ci

# JSON output for scripting
mcp-compat before.json after.json --json

# Compare remote schemas
mcp-compat https://example.com/schema-v1.json https://example.com/schema-v2.json

Input is a JSON array of MCP tool objects (same format as agent-friend grade):

[
  {
    "name": "get_weather",
    "description": "Get current weather",
    "inputSchema": {
      "type": "object",
      "properties": {
        "city": {"type": "string", "description": "City name"},
        "units": {"type": "string", "description": "Units", "default": "celsius"}
      },
      "required": ["city"]
    }
  }
]

Change classification

CI integration

Add to your GitHub Actions workflow:

- name: Check MCP schema compatibility
  run: |
    pip install mcp-compat
    mcp-compat schema-before.json schema-after.json --ci

Or capture the schema before a deploy:

# Before deploy
mcp-compat-capture > schema-before.json  # save current schema

# After deploy candidate is ready
mcp-compat schema-before.json schema-after.json --ci

JSON output

mcp-compat before.json after.json --json

{
  "breaking_count": 1,
  "warn_count": 0,
  "safe_count": 2,
  "changes": [
    {
      "severity": "BREAKING",
      "tool": "get_weather",
      "message": "Parameter 'units' type changed: string → integer"
    },
    {
      "severity": "SAFE",
      "tool": "get_weather",
      "message": "New optional parameter 'format' added"
    }
  ]
}

Part of the MCP developer lifecycle

agent-friend   lint schemas before publishing
mcp-patch      security audit (prompt injection, over-permission)
mcp-pytest     test tool behavior end-to-end
mcp-snoop      debug stdio traffic in real time
mcp-diff       detect schema changes between versions
mcp-compat     classify breaking changes  ← you are here

All on PyPI. All open-source. All zero external dependencies.

License

MIT