# <img src="https://raw.githubusercontent.com/appcreationsca/bumpguard-mcp/main/assets/logo.png" alt="BumpGuard logo" height="44" align="top">BumpGuard

<!-- mcp-name: io.github.appcreationsca/bumpguard -->

**Guard your dependency bumps.** BumpGuard is a [Model Context Protocol](https://modelcontextprotocol.io) (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.

<p align="center">
  <img src="https://raw.githubusercontent.com/appcreationsca/bumpguard-mcp/main/assets/demo.gif"
       alt="BumpGuard check_upgrade demo: out of 2,015 breaking changes in pydantic 2.0, it flags the one (BaseSettings) that hits your code, with the fix"
       width="820">
</p>

---

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

```jsonc
// 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

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

```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`](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

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

```bash
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](LICENSE).