appcreationsca/bumpguard-mcp

**Guard your dependency bumps.** BumpGuard is a Model Context Protocol (MCP) server that tells your AI coding agent *exactly which lines of **your** code break* when you upgrade a dependency — and verifies AI‑written code against the API that is **actually installed**, so it stops calling functions that don't exist.
It does this by **static analysis only**. BumpGuard never imports or executes third‑party code; it reads a package's real public API straight from its source.
> Docs tell your agent what *should* exist. BumpGuard tells it what *actually* exists here.
---
Why this exists
The #1 frustration developers report with AI coding tools is code that's *"almost right, but not quite."* A huge slice of that is **API drift and hallucination**:
- The model writes pydantic.BaseSettings or openai.ChatCompletion.create(...) — perfectly valid two versions ago, **gone** in the version you have installed.
- You bump pandas from 1.5 to 2.2 and discover the breakage one stack trace at a time.
- A changelog lists *1,800 breaking changes*; you only care about the **three** your code actually touches.
BumpGuard closes that gap with ground truth from your environment instead of the model's memory.
---
What it does
A real example — upgrading pydantic 1 → 2 in code that uses BaseSettings:
Out of **2,015** breaking API changes, BumpGuard surfaced the **one** that affects this code — with the line number and a fix hint.
---
Tools
| Tool | What it answers |
| --- | --- |
| **check_upgrade** ⭐ | *"If I upgrade package to to_version, what in **this code** breaks?"* Diffs the installed (or from_version) API against the target and reports only the changes your code actually hits, with severity and fix hints. |
| **diff_versions** | *"What changed between two versions of this library?"* The raw breaking‑change list, no code scan — good for planning a migration. |
| **verify_snippet** | *"Do the imports and API calls in this code really exist here?"* Catches hallucinated/typo'd package names (slopsquatting) and attributes that aren't on the installed package. |
| **check_import** | *"Is this package installed? If not, what's the closest real name?"* |
| **list_symbols** | *"What's the real public API of this package?"* Discover functions/classes/methods + signatures instead of guessing — for the installed version or any fetched version. |
| **list_languages** | Which ecosystem providers are available. |
Every answer is grounded in evidence (installed version, source location). Because analysis is static, **"no findings" means "nothing proven to break," not a guarantee** — BumpGuard is explicit about that in its output.
---
Install
Requires Python 3.10+. The server speaks MCP over stdio.
> Install BumpGuard into the **same environment as the project you're working on**, so it sees the packages you actually have installed.
---
Configure your MCP client
**Claude Desktop / Claude Code** (claude_desktop_config.json):
**Cursor / Windsurf / VS Code (Copilot)** — point your MCP config at the bumpguard-mcp command (or python -m bumpguard.server). Any MCP‑compatible client works.
Then ask your agent things like:
- *"Before upgrading pandas to 2.2, check whether my data pipeline breaks."*
- *"Verify this snippet actually uses the installed OpenAI SDK."*
- *"List the real methods on httpx.Client."*
---
How it works
1. **Extract** a package's public API surface by parsing its source with Python's ast — for the installed version, and for the target version (downloaded as a wheel and unpacked, **never installed or executed**).
2. **Diff** the two surfaces into removed / signature‑changed / added symbols, and classify each as breaking, potentially breaking, or info.