# breaking-changes-mcp

> Stop your coding agent from hallucinating dependency migrations.

An [MCP](https://modelcontextprotocol.io) server that gives Claude, Cursor, and any MCP client **accurate, source-grounded breaking-change briefings** for any npm package — read straight from the real GitHub release notes and CHANGELOG, not from the model's stale training data.

LLMs are great at writing code and terrible at remembering exactly what changed between `react@18` and `react@19`, or `next@14` and `next@16`. That's where upgrades break. This server closes the gap: point it at a package and a version range, and the agent gets the actual breaking changes before it touches your code.

## Why this exists

Tools like Context7 inject *current* docs. But the most dangerous moment for an agent is a **version bump**, and nobody serves the *delta between two versions*. `breaking-changes-mcp` is that missing piece.

## Tools

| Tool | What it does |
|------|--------------|
| `breaking_changes_between` | The headline tool. Returns only the **breaking changes** for a package between two versions, grouped per version, newest first. Reads GitHub Releases, falls back to `CHANGELOG.md`. |
| `changelog_between` | The **full** release notes (features, fixes, deprecations) across a version range — when breaking-only isn't enough. |
| `list_versions` | Published versions + release dates, newest first — to discover valid `from`/`to` values. |

Every tool works on the public npm registry + GitHub with **no API key required**. Set `GITHUB_TOKEN` to raise GitHub's rate limit from 60 to 5000 requests/hour.

## Quick start

```bash
npx breaking-changes-mcp
```

### Claude Code

```bash
claude mcp add breaking-changes -- npx -y breaking-changes-mcp
# optional: higher GitHub rate limit
claude mcp add breaking-changes -e GITHUB_TOKEN=ghp_xxx -- npx -y breaking-changes-mcp
```

### Claude Desktop / Cursor / Windsurf / any MCP client

```json
{
  "mcpServers": {
    "breaking-changes": {
      "command": "npx",
      "args": ["-y", "breaking-changes-mcp"],
      "env": { "GITHUB_TOKEN": "ghp_xxx_optional" }
    }
  }
}
```

## Example prompts

- *"I'm on react 18.2.0 and want to go to 19. Use breaking-changes to tell me exactly what will break."*
- *"Before you upgrade next in this repo, check the breaking changes between the installed version and latest."*
- *"Give me the full changelog for @tanstack/react-query from 4.0.0 to 5.0.0."*

## Config

| Env var | Default | Purpose |
|---------|---------|---------|
| `GITHUB_TOKEN` / `GH_TOKEN` | — | Personal access token to raise GitHub API limits (60→5000/hr). Read-only, no scopes needed for public repos. |
| `NPM_REGISTRY` | `https://registry.npmjs.org` | Override for private/mirror registries. |

## How it works

```
package + from..to
   │
   ├─ npm registry ──► all versions, dates, repository URL
   ├─ versions in (from, to]
   ├─ GitHub Releases ──► release bodies for those versions
   │        └─ fallback: raw CHANGELOG.md sliced between version headers
   └─ extract "### Breaking…" sections + "BREAKING CHANGE" lines ──► grouped briefing
```

## Develop

```bash
npm install
npm run build
node dist/index.js   # speaks MCP over stdio
```

## Caveats

- Quality of output depends on the maintainer documenting breaking changes. If a project buries them in prose, `breaking_changes_between` says so and points you to `changelog_between`.
- Monorepo tags (`pkg@1.2.3`) and prefixed tags (`v1.2.3`, `release-1.2.3`) are handled; exotic tag schemes may miss.

## License

MIT © Anicodeth