{ "markdown": "# \"BumpGuardBumpGuard\n\n\n\n**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.\n\nIt 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.\n\n> Docs tell your agent what *should* exist. BumpGuard tells it what *actually* exists here.\n\n

\n \"BumpGuard\n

\n\n---\n\n## Why this exists\n\nThe #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**:\n\n- The model writes `pydantic.BaseSettings` or `openai.ChatCompletion.create(...)` — perfectly valid two versions ago, **gone** in the version you have installed.\n- You bump `pandas` from 1.5 to 2.2 and discover the breakage one stack trace at a time.\n- A changelog lists *1,800 breaking changes*; you only care about the **three** your code actually touches.\n\nBumpGuard closes that gap with ground truth from your environment instead of the model's memory.\n\n---\n\n## What it does\n\nA real example — upgrading `pydantic` 1 → 2 in code that uses `BaseSettings`:\n\n```jsonc\n// check_upgrade(package=\"pydantic\", to_version=\"2.0.3\", from_version=\"1.10.13\", code=\"...\")\n{\n \"safe_to_upgrade\": false,\n \"summary\": { \"breaking\": 1, \"total_api_changes\": 4919, \"breaking_api_changes\": 2015 },\n \"findings\": [\n {\n \"symbol\": \"pydantic.BaseSettings\",\n \"line\": 2,\n \"severity\": \"breaking\",\n \"message\": \"You use 'pydantic.BaseSettings', which no longer exists in the target version...\",\n \"suggestion\": \"Consider 'pydantic.v1.env_settings.BaseSettings'\"\n }\n ]\n}\n```\n\nOut of **2,015** breaking API changes, BumpGuard surfaced the **one** that affects this code — with the line number and a fix hint.\n\n---\n\n## Tools\n\n| Tool | What it answers |\n| --- | --- |\n| **`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. |\n| **`diff_versions`** | *\"What changed between two versions of this library?\"* The raw breaking‑change list, no code scan — good for planning a migration. |\n| **`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. |\n| **`check_import`** | *\"Is this package installed? If not, what's the closest real name?\"* |\n| **`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. |\n| **`list_languages`** | Which ecosystem providers are available. |\n\nEvery 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.\n\n---\n\n## Install\n\n```bash\npip install bumpguard-mcp\n```\n\nRequires Python 3.10+. The server speaks MCP over stdio.\n\n> Install BumpGuard into the **same environment as the project you're working on**, so it sees the packages you actually have installed.\n\n---\n\n## Configure your MCP client\n\n**Claude Desktop / Claude Code** (`claude_desktop_config.json`):\n\n```json\n{\n \"mcpServers\": {\n \"bumpguard\": {\n \"command\": \"bumpguard-mcp\"\n }\n }\n}\n```\n\n**Cursor / Windsurf / VS Code (Copilot)** — point your MCP config at the `bumpguard-mcp` command (or `python -m bumpguard.server`). Any MCP‑compatible client works.\n\nThen ask your agent things like:\n\n- *\"Before upgrading pandas to 2.2, check whether my data pipeline breaks.\"*\n- *\"Verify this snippet actually uses the installed OpenAI SDK.\"*\n- *\"List the real methods on `httpx.Client`.\"*\n\n---\n\n## How it works\n\n```\n ┌──────────────── language‑neutral core ────────────────┐\n MCP tools → │ diff engine · breaking‑change classifier · analyzer │\n │ (matches API changes against YOUR usage) │\n └───────────────────────┬──────────────────────────────┘\n │ Provider interface\n ┌───────────────────────┴──────────────────────────────┐\n │ Python provider │ .NET (NuGet) │ Java (Maven) │\n │ • AST surface │ • DLL metadata │ • jar bytecode │\n │ • usage scanner │ • Roslyn scan │ • source scan │\n │ • wheel fetch │ • nupkg fetch │ • jar fetch │\n └──────────────────────────────────────────────────────┘\n```\n\n1. **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**).\n2. **Diff** the two surfaces into removed / signature‑changed / added symbols, and classify each as breaking, potentially breaking, or info.\n3. **Scan** your code (also via `ast`) for usages — resolving import aliases, re‑exports, instance‑method calls, and the keyword/positional arguments each call passes.\n4. **Match** usages against changes and report a precise, per‑line verdict.\n\n**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.\n\n---\n\n## Multi‑language by design\n\nBumpGuard 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.\n\n- ✅ **Python (PyPI)** — available now.\n- ✅ **.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.\n- ✅ **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.\n- 🔜 **JS/TS (npm)** — parse `.d.ts` declarations.\n\nAdding an ecosystem means implementing one `Provider` — see [`docs/ADD_A_PROVIDER.md`](docs/ADD_A_PROVIDER.md).\n\n### .NET specifics (v1)\n\n- 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).\"*\n- Supported: `check_upgrade`, `diff_versions`, `list_symbols`, `check_import`.\n- **Prefer passing `from_version`** — the \"installed\" baseline is taken from the NuGet global cache, which isn't your project's pinned version.\n- 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).\n- 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.\n- `verify_snippet` is **not supported for .NET in v1** (accurate C# hallucination detection needs semantic binding).\n\n### Java specifics (v1)\n\n- 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).\"*\n- Supported: `check_upgrade`, `diff_versions`, `list_symbols`, `check_import`.\n- 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.**\n- **Prefer passing `from_version`** — the \"installed\" baseline is read from your local `~/.m2` cache, which may not match your project's pinned version.\n- 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.\n- 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).\n\n---\n\n## Known limitations (v1, Python)\n\nBumpGuard is honest about static analysis. It may **miss** (false negatives) or, rarely, **over‑flag** (false positives):\n\n- Dynamically generated APIs (`__getattr__` modules, plugin registries, `boto3`‑style clients). BumpGuard detects `__getattr__` modules and *suppresses* confident \"missing symbol\" findings under them.\n- Members created at runtime that aren't visible in source.\n- Compiled (C/Rust) extension internals — the Python‑level surface is still read.\n- Deep instance‑flow tracking is limited to direct `x = Class(...)` patterns.\n- Star re‑exports (`from .x import *`) are not expanded.\n\nTreat findings as **high‑signal guidance**, and absence of findings as \"not proven unsafe,\" not a guarantee.\n\n---\n\n## Development\n\n```bash\ngit clone https://github.com/appcreationsca/bumpguard-mcp\ncd bumpguard-mcp\npython -m venv .venv && . .venv/Scripts/activate # Windows\npip install -e \".[dev]\"\npytest\n```\n\nThe test suite (42 tests) runs offline using fixture packages — no network required.\n\n### Releasing\n\nReleases are automated via GitHub Actions. To cut a release:\n\n1. Bump the version in `pyproject.toml` and `src/bumpguard/__init__.py`.\n2. Move the `CHANGELOG.md` \"Unreleased\" notes under a new version heading.\n3. Commit, then tag and push:\n\n```bash\ngit tag v0.1.0\ngit push origin v0.1.0\n```\n\nThe **Release** workflow runs the tests, builds the wheel + sdist, and publishes\nto PyPI via **Trusted Publishing** (OIDC — no stored tokens). The **CI** workflow\nruns the test matrix (Linux + Windows, Python 3.10/3.13) on every push and PR.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n", "bytes": 11723, "sha": "5e4538e424490536a7b64226c1374ee7484141f9f64838de57dc95758a3cfb75", "repo_slug": "appcreationsca/bumpguard-mcp", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_appcreationsca_bumpguard_9f0ec603/readme" }