Validate API contracts for compatibility, detect breaking changes, and generate migration plans with client impact analysis
Validate API contracts for compatibility, detect breaking changes, and generate migration plans with client impact analysis.
mode=BUILD before releasing a new API version to ensure backward compatibilitymode=DEBUG when an API client breaks after a server updatemode=EXPLORE to audit an API surface for design inconsistencies'validate' | 'diff' | 'migrate'
| Parameter | Type | Required | Description |
|---|---|---|---|
| current_contract | string | yes | Current API specification (file path, URL, or inline JSON/OpenAPI) |
| proposed_contract |
| string |
| no |
| Proposed new specification (if diffing two versions) |
| api_type | string | no | API type: openai, anthropic, google, custom (default: auto-detect) |
| strict | boolean | no | Whether to fail on warnings in addition to errors (default: false) |
Use view to read the contract files. Parse the API specification to extract endpoints, request/response schemas, parameters, and authentication requirements.
Use mcp_floyd-devtools_api_format_verifier with action validate_schema to check the contract structure. Verify all endpoints have complete request/response definitions, all parameters have types and descriptions, and all error responses are documented.
Compare current_contract against proposed_contract. Classify changes:
For each breaking change, generate a migration step: what clients must change, example before/after, and a deprecation timeline recommendation.
{
"validation": {
"valid": true,
"errors": ["string — schema violations"],
"warnings": ["string — non-critical issues"]
},
"diff": {
"breaking_changes": [
{
"endpoint": "string — affected endpoint",
"change": "string — what changed",
"impact": "string — which clients are affected",
"migration_step": "string — how to adapt"
}
],
"additive_changes": 5,
"modified_changes": 3
},
"migration_plan": {
"steps": ["string — ordered migration actions"],
"deprecation_timeline": "string — recommended timeline"
}
}
api_type auto-detection fails: prompt for explicit api_type specification{
"action": "diff",
"current_contract": "specs/api-v1.yaml",
"proposed_contract": "specs/api-v2.yaml",
"api_type": "custom"
}