API Change Sentinel MCP

An MCP server that compares API specs and turns raw diffs into upgrade intelligence: breaking-change reports, blast-radius estimates, migration guides, and release notes.

Overview

Most API tooling stops at one of these two layers:

serving the spec
showing a raw diff

That is not enough for real upgrades. Teams need help answering practical questions:

What will actually break?
How risky is this release for existing consumers?
What should client teams change first?
What should go into the changelog?

api-change-sentinel-mcp is designed to answer those questions through MCP so an assistant can reason over API version changes instead of just dumping endpoints.

Why this project is useful

This is aimed at:

API platform teams shipping versioned contracts
SDK maintainers tracking breaking changes
developer experience teams preparing migrations
release engineers writing upgrade notes
internal platform teams reviewing service-to-service API changes

Instead of wrapping another API, this server performs higher-value analysis on top of API contracts.

Current capabilities

Given two OpenAPI-style JSON specs, the server can:

compare versions and summarize changes
detect representative breaking changes
estimate consumer blast radius from change severity
draft a migration guide for downstream teams
draft release notes for changelogs, pull requests, or release pages

The current implementation is intentionally lightweight and local-first so the project is easy to run, inspect, and extend.

MCP tools

`compare_api_specs`

Returns a structured summary of:

previous and next versions
breaking changes
added endpoints
changed endpoints
blast-radius estimate

`list_breaking_changes`

Returns only the breaking changes in a concise engineer-friendly format.

`estimate_consumer_blast_radius`

Scores upgrade risk based on diff severity and optional consumer count.

`draft_migration_guide`

Builds a migration checklist that can be pasted into internal docs or release plans.

`draft_release_notes`

Builds changelog-ready release notes from the detected API changes.

Included example

The sample specs in examples/petstore-v1.json and examples/petstore-v2.json demonstrate a realistic version bump.

Representative findings from that diff:

GET /pets/{petId} was removed
required parameter cursor was added to GET /pets
response 400 was removed from POST /pets
new endpoint GET /pets/search was added

Example migration output:

Upgrade Petstore API from 1.0.0 to 2.0.0:
- [high] GET /pets/{petId} no longer exists in the new spec.
- [high] Required parameter "cursor" was added to GET /pets.
- [medium] Response code "400" was removed from POST /pets.
- [low] Summary changed from "List pets" to "List all pets".
- Review newly added endpoints: GET /pets/search
- Regenerate SDKs and rerun contract tests before release.

Repository structure

src/index.ts: MCP server entry point and tool registration
src/spec-diff.ts: spec loading, normalization, diffing, and report drafting
tests/run-tests.ts: local validation script
docs/architecture.md: design notes and next-step architecture
examples/: sample input specs

Local development

Install dependencies:

npm install

Build:

npm run build

Run tests:

npm test

Run the server over stdio:

npm run dev

Example prompts

Compare examples/petstore-v1.json and examples/petstore-v2.json.
List the breaking changes introduced in the new version.
Estimate the blast radius for 12 API consumers.
Draft migration notes for the v1 to v2 upgrade.
Generate release notes for this API version change.

Design direction

This repository is a first portfolio-quality version of a larger idea. The stronger long-term version should add:

real OpenAPI diff backends
remote spec fetching from URLs, Git refs, and repos
SDK symbol mapping for TypeScript and Python clients
machine-readable CI output
GitHub pull request annotations
compatibility scoring by consumer type

Why this stands out in the MCP ecosystem

Many MCP servers are thin wrappers around existing APIs. This project is different because it adds interpretation:

it reasons about changes rather than just exposing data
it helps plan upgrades rather than only inspect specs
it creates outputs engineers can use immediately in release workflows

That makes it a stronger portfolio project than a generic connector.

Roadmap

Add richer breaking-change classification
Support schema-level request and response diffs
Add remote spec resolution
Add GitHub Action and PR comment mode
Add generated SDK impact analysis
Add structured JSON report output for automation

MCP Servers