# Api Change Sentinel Mcp

> MCP tool for monitoring API schema changes and breaking updates

- **Type:** MCP server
- **Install:** `agentstack add mcp-narkov-api-change-sentinel-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [narkov](https://agentstack.voostack.com/s/narkov)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [narkov](https://github.com/narkov)
- **Source:** https://github.com/narkov/api-change-sentinel-mcp

## Install

```sh
agentstack add mcp-narkov-api-change-sentinel-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

```text
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:

```bash
npm install
```

Build:

```bash
npm run build
```

Run tests:

```bash
npm test
```

Run the server over stdio:

```bash
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](https://github.com/narkov)
- **Source:** [narkov/api-change-sentinel-mcp](https://github.com/narkov/api-change-sentinel-mcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-narkov-api-change-sentinel-mcp
- Seller: https://agentstack.voostack.com/s/narkov
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.