BumpGuard

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:

// check_upgrade(package="pydantic", to_version="2.0.3", from_version="1.10.13", code="...")
{
  "safe_to_upgrade": false,
  "summary": { "breaking": 1, "total_api_changes": 4919, "breaking_api_changes": 2015 },
  "findings": [
    {
      "symbol": "pydantic.BaseSettings",
      "line": 2,
      "severity": "breaking",
      "message": "You use 'pydantic.BaseSettings', which no longer exists in the target version...",
      "suggestion": "Consider 'pydantic.v1.env_settings.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

pip install bumpguard-mcp

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

{
  "mcpServers": {
    "bumpguard": {
      "command": "bumpguard-mcp"
    }
  }
}

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

                 ┌──────────────── language‑neutral core ────────────────┐
   MCP tools  →  │  diff engine · breaking‑change classifier · analyzer  │
                 │  (matches API changes against YOUR usage)             │
                 └───────────────────────┬──────────────────────────────┘
                                         │ Provider interface
                 ┌───────────────────────┴──────────────────────────────┐
                 │  Python provider  │  .NET (NuGet)   │  Java (Maven)   │
                 │  • AST surface    │  • DLL metadata │  • jar bytecode │
                 │  • usage scanner  │  • Roslyn scan  │  • source scan  │
                 │  • wheel fetch    │  • nupkg fetch  │  • jar fetch    │
                 └──────────────────────────────────────────────────────┘

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.
3. Scan your code (also via ast) for usages — resolving import aliases, re‑exports, instance‑method calls, and the keyword/positional arguments each call passes.
4. Match usages against changes and report a precise, per‑line verdict.

Safety: BumpGuard never imports third‑party code, so there are no import side effects, no hangs from heavy packages, and no arbitrary code execution. Wheel downloads are sandboxed to a temp dir, time‑bounded, and guarded against path traversal / zip bombs.

---

Multi‑language by design

BumpGuard is built around a pluggable provider interface. The diff engine, breaking‑change classifier, analyzer, reporting, and MCP tools are all language‑neutral; only the surface extraction and usage scanning are ecosystem‑specific.

• ✅ Python (PyPI) — available now.
• ✅ .NET (NuGet) — available now. Reads public API from assembly metadata via reflection-only loading (no code executed); needs the .NET SDK (dotnet) on PATH. A small helper is built once on first use.
• ✅ Java (Maven) — available now. Reads public API directly from compiled .jar bytecode (constant pool, access flags, descriptors) in pure Python — no JDK or Maven required and no third‑party code is executed.
• 🔜 JS/TS (npm) — parse .d.ts declarations.

Adding an ecosystem means implementing one Provider — see docs/ADD_A_PROVIDER.md.

.NET specifics (v1)

• Pass language: "dotnet". Example: "Before upgrading Azure.AI.OpenAI to 2.1.0, check whether my client code breaks (from_version 1.0.0-beta.17)."
• Supported: check_upgrade, diff_versions, list_symbols, check_import.
• Prefer passing from_version — the "installed" baseline is taken from the NuGet global cache, which isn't your project's pinned version.
• Reliable signal: type / method / property removals and additions (e.g. the OpenAIClient → AzureOpenAIClient rename is caught as a breaking removal with a suggestion). Parameter-level diffs run only for unambiguous single-overload members; overloaded members are tracked by presence (a documented v1 limit).
• Fully-qualified references are reported confidently; short names resolved via using are reported as lower-confidence "potentially breaking" to avoid false hard-breaks from namespace collisions.
• verify_snippet is not supported for .NET in v1 (accurate C# hallucination detection needs semantic binding).

Java specifics (v1)

• Pass language: "java" and identify packages by their Maven coordinate group:artifact (e.g. com.google.code.gson:gson). Example: "Before upgrading com.google.code.gson:gson to 2.10.1, check whether my code breaks (from_version 2.8.9)."
• Supported: check_upgrade, diff_versions, list_symbols, check_import.
• The public API surface is read directly from .jar bytecode (the jar is a zip of .class files; BumpGuard parses the class‑file structure with struct — reading metadata, never running it). The target jar is fetched from Maven Central (sandboxed, size‑capped, time‑bounded). No JDK/Maven needed.
• Prefer passing from_version — the "installed" baseline is read from your local ~/.m2 cache, which may not match your project's pinned version.
• Reliable signal: type / method / field / constructor removals and additions, and arity changes. Fully-qualified references hard-break; short names resolved via import are reported as lower-confidence "potentially breaking" to avoid false hard-breaks from namespace collisions.
• Documented v1 limits: generics are erased in bytecode descriptors (so generic type-argument changes aren't seen); return-type-only changes and varargs removal are tracked conservatively; overloaded members are tracked by presence (per-overload removal isn't detected); multi-release jars use the highest version overlay. The source usage scanner is a robust heuristic, not a full parser — it can pick up a name's own declaration or import line as a reference, but these resolve to unqualified names that are capped at "potentially breaking" and can never produce a false hard-break. verify_snippet is not supported for Java in v1 (accurate hallucination detection needs semantic binding).

---

Known limitations (v1, Python)

BumpGuard is honest about static analysis. It may miss (false negatives) or, rarely, over‑flag (false positives):

• Dynamically generated APIs (__getattr__ modules, plugin registries, boto3‑style clients). BumpGuard detects __getattr__ modules and suppresses confident "missing symbol" findings under them.
• Members created at runtime that aren't visible in source.
• Compiled (C/Rust) extension internals — the Python‑level surface is still read.
• Deep instance‑flow tracking is limited to direct x = Class(...) patterns.
• Star re‑exports (from .x import *) are not expanded.

Treat findings as high‑signal guidance, and absence of findings as "not proven unsafe," not a guarantee.

---

Development

git clone https://github.com/appcreationsca/bumpguard-mcp
cd bumpguard-mcp
python -m venv .venv && . .venv/Scripts/activate   # Windows
pip install -e ".[dev]"
pytest

The test suite (42 tests) runs offline using fixture packages — no network required.

Releasing

Releases are automated via GitHub Actions. To cut a release:

1. Bump the version in pyproject.toml and src/bumpguard/__init__.py.
2. Move the CHANGELOG.md "Unreleased" notes under a new version heading.
3. Commit, then tag and push:

git tag v0.1.0
git push origin v0.1.0

The Release workflow runs the tests, builds the wheel + sdist, and publishes to PyPI via Trusted Publishing (OIDC — no stored tokens). The CI workflow runs the test matrix (Linux + Windows, Python 3.10/3.13) on every push and PR.

---

License

MIT — see LICENSE.