Api Change Sentinel Mcp

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](D:\usr\www\mcp-dev\api-change-sentinel-mcp\examples\petstore-v1.json) and [examples/petstore-v2.json](D:\usr\www\mcp-dev\api-change-sentinel-mcp\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](D:\usr\www\mcp-dev\api-change-sentinel-mcp\src\index.ts): MCP server entry point and tool registration
• [src/spec-diff.ts](D:\usr\www\mcp-dev\api-change-sentinel-mcp\src\spec-diff.ts): spec loading, normalization, diffing, and report drafting
• [tests/run-tests.ts](D:\usr\www\mcp-dev\api-change-sentinel-mcp\tests\run-tests.ts): local validation script
• [docs/architecture.md](D:\usr\www\mcp-dev\api-change-sentinel-mcp\docs\architecture.md): design notes and next-step architecture
• [examples/](D:\usr\www\mcp-dev\api-change-sentinel-mcp\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

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: narkov
• Source: narkov/api-change-sentinel-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.