# API Contract Diff Checker MCP for AI Agents MCP

> API Contract Diff Checker detects breaking and additive changes in OpenAPI and GraphQL schemas. It helps you spot removed endpoints, type narrowing, and new fields instantly. Use it to ensure your API updates don't break downstream clients and to get automated SemVer recommendations for every change.

## Overview
- **Category:** developer-tools
- **Price:** Free
- **Endpoint:** https://edge.vinkius.com/vk_preview_YNoFUtgqNHWnECjvlVZlbBc74OvhGVwRY5w7zSGv/mcp
- **Tags:** openapi, graphql, semver, api-contract, diff-checker

## Description

The API Contract Diff Checker helps you spot structural changes between two versions of your API contracts. If you're tired of manually squinting at JSON files to see if you accidentally deleted an endpoint or changed a data type, this MCP handles the work for you. It compares your OpenAPI specifications or GraphQL SDL to find the "oh no" moments, like type narrowing or removed paths, while also highlighting the new fields you've added. It turns a stressful manual audit into a quick check. Because Vinkius makes it easy to connect these tools to your favorite AI client, you can just ask your agent to review your latest spec. You'll get a clear report of what's broken and what's new, along with a recommendation on whether your next version bump should be a major, minor, or patch release based on the actual impact of your changes.

## Tools

### diff_graphql
Compares two GraphQL SDL strings to identify breaking and additive changes. It shows you exactly which fields were added or removed in your schema.

### diff_openapi
Compares two OpenAPI specs to find structural differences and compatibility issues. It helps you identify if your REST API changes will break existing clients.

### evaluate_version_bump
Analyzes a collection of identified changes to recommend a Semantic Versioning increment. It tells you if your update qualifies as a MAJOR, MINOR, or PATCH release.

## Prompt Examples

**Prompt:** 
```
I have two GraphQL schemas. Can you check if I broke anything by adding a new field to the User type?
```

**Response:** 
```
### Schema Comparison Results

**Changes detected in `User` type:**
*   **Additive:** New field `email` added.
*   **Breaking:** None detected.

**Summary:**
| Field | Change Type | Impact |
| :--- | :--- | :--- |
| `email` | Additive | Safe to deploy.

Your update is safe for existing clients.
```

**Prompt:** 
```
Here is my old OpenAPI spec and the new one. Tell me what changed.
```

**Response:** 
```
### API Contract Audit

I've compared your OpenAPI specifications. Here are the structural differences:

**Breaking Changes:**
*   Path `/user` was removed.
*   Method `GET` on `/profile` now has a narrowed `id` type.

**Additive Changes:**
*   New field `phone_number` added to `/contact`.
*   New endpoint `/status` added.
```

**Prompt:** 
```
I have a list of changes: one removed field, two new fields, and one changed type. What should my next version be?
```

**Response:** 
```
### Versioning Recommendation

**Recommended Bump:** **MAJOR**

**Reasoning:**
The audit detected a **breaking change** (removed field). According to Semantic Versioning rules, any removal of existing functionality or breaking change to the contract requires a MAJOR version increment.
```

## Capabilities

### Identify breaking changes in REST APIs
It flags removed endpoints or narrowed types in your OpenAPI specs.

### Spot new fields in GraphQL schemas
It highlights all additive changes in your GraphQL SDL strings.

### Get automated SemVer recommendations
It suggests the correct version bump based on the severity of your changes.

### Detect removed endpoints in OpenAPI specs
It scans for paths that were present in the base spec but missing in the new one.

### Spot type narrowing in GraphQL
It identifies when a field's type has become more restrictive, which can break clients.

## Use Cases

### Catching type narrowing in GraphQL
A developer adds a field but accidentally changes a type from optional to required. Use diff_graphql to spot the narrowing before it crashes the frontend.

### Auditing legacy REST API migrations
A team is migrating a legacy REST API to a new version. Use diff_openapi to audit the old vs. new spec for any missing paths.

### Automating SemVer for release notes
A release manager needs to know if a PR requires a Major version bump. Use evaluate_version_bump on the change list to get an objective recommendation.

### Verifying GraphQL schema updates
A designer wants to see if a new GraphQL type is actually breaking for existing queries. Use diff_graphql to check the SDL for structural impacts.

## Benefits

- Stop breaking production by using diff_openapi to catch removed endpoints or narrowed types before they go live.
- Save hours of manual review by using diff_graphql to instantly see every new field in your schema.
- Remove the guesswork from versioning by using evaluate_version_bump to get a clear SemVer recommendation.
- Catch silent breaking changes like type narrowing that are often missed during standard code reviews.
- Maintain a consistent API contract with your customers by quickly identifying every additive change in your specs.

## How It Works

The bottom line is you get a clear, automated audit of your API changes without manual comparison.

1. Provide the old and new OpenAPI or GraphQL strings to your agent.
2. The MCP compares the two versions for structural differences.
3. You get a report of breaking changes and a versioning recommendation.

## Frequently Asked Questions

**Does the API Contract Diff Checker work with my REST API?**
Yes, it uses diff_openapi to handle RESTful specifications. It will check for removed paths, changed parameters, and other structural changes.

**Can I use this to find breaking changes in GraphQL?**
Yes, it specifically supports GraphQL SDL strings via diff_graphql. It can identify if your changes will break existing queries or mutations.

**How does it know if a change is breaking?**
It looks for structural changes that would cause existing clients to fail, such as removing a required endpoint or narrowing a data type.

**Will it tell me what version number to use next?**
Yes, the evaluate_version_bump tool analyzes your identified changes and suggests whether you should use a MAJOR, MINOR, or PATCH increment.

**Can I use this for my own internal API documentation?**
Absolutely. It is a great way to keep your internal documentation consistent and ensure that your own team doesn't break internal tools.

**Do I need to provide the full JSON file?**
You can provide the relevant schema strings for either OpenAPI or GraphQL. Your agent can help you extract these from your files if needed.

**What types of API contracts can I compare?**
You can compare OpenAPI specifications and GraphQL Schema Definition Language (SDL) strings.

**How does the tool recommend a version bump?**
The `evaluate_version_bump` tool analyzes detected changes. A MAJOR bump is recommended for breaking changes, MINOR for additive changes, and PATCH for informational updates.

**Can I detect type narrowing in OpenAPI?**
Yes, `diff_openapi` identifies type narrowing (e.g., changing a string to a specific regex pattern) as a breaking change.