BumpGuard

BumpGuard

Protege tus actualizaciones de dependencias. BumpGuard es un servidor Model Context Protocol (MCP) que le dice a tu agente de codificación con IA exactamente qué líneas de tu código se rompen cuando actualizas una dependencia — y verifica el código escrito por IA contra la API que realmente está instalada, para que deje de llamar a funciones que no existen.

Lo hace mediante análisis estático únicamente. BumpGuard nunca importa ni ejecuta código de terceros; lee la API pública real de un paquete directamente desde su código fuente.

Los documentos le dicen a tu agente lo que debería existir. BumpGuard le dice lo que realmente existe aquí.

---

Por qué existe esto

La frustración número 1 que los desarrolladores reportan con las herramientas de codificación con IA es código que está "casi bien, pero no del todo". Una gran parte de eso es deriva de API y alucinación:

• El modelo escribe pydantic.BaseSettings o openai.ChatCompletion.create(...) — perfectamente válido hace dos versiones, desaparecido en la versión que tienes instalada.
• Actualizas pandas de 1.5 a 2.2 y descubres la rotura un traceback a la vez.
• Un changelog lista 1,800 cambios disruptivos; solo te importan los tres que tu código realmente toca.

BumpGuard cierra esa brecha con la verdad real de tu entorno en lugar de la memoria del modelo.

---

Qué hace

Un ejemplo real — actualizar pydantic 1 → 2 en código que usa 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'"
    }
  ]
}

De 2,015 cambios disruptivos de API, BumpGuard sacó a la superficie el único que afecta este código — con el número de línea y una pista de solución.

---

Herramientas

Herramienta	Qué responde
check_upgrade ⭐	"Si actualizo package a to_version, ¿qué en este código se rompe?" Compara la API instalada (o from_version) contra la objetivo y reporta solo los cambios que tu código realmente encuentra, con severidad y pistas de solución.
diff_versions	"¿Qué cambió entre dos versiones de esta librería?" La lista cruda de cambios disruptivos, sin escaneo de código — bueno para planificar una migración.
verify_snippet	"¿Las importaciones y llamadas a API en este código realmente existen aquí?" Detecta nombres de paquetes alucinados/errados (slopsquatting) y atributos que no están en el paquete instalado.
check_import	"¿Está instalado este paquete? Si no, ¿cuál es el nombre real más cercano?"
list_symbols	"¿Cuál es la API pública real de este paquete?" Descubre funciones/clases/métodos + firmas en lugar de adivinar — para la versión instalada o cualquier versión obtenida.
list_languages	Qué proveedores de ecosistemas están disponibles.

Cada respuesta está fundamentada en evidencia (versión instalada, ubicación del código fuente). Como el análisis es estático, "sin hallazgos" significa "nada probado que se rompa", no una garantía — BumpGuard es explícito sobre eso en su salida.

---

Instalación

pip install bumpguard-mcp

Requiere Python 3.10+. El servidor habla MCP sobre stdio.

Instala BumpGuard en el mismo entorno que el proyecto en el que estás trabajando, para que vea los paquetes que realmente tienes instalados.

---

Configura tu cliente MCP

Claude Desktop / Claude Code (claude_desktop_config.json):

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

Cursor / Windsurf / VS Code (Copilot) — apunta tu configuración MCP al comando bumpguard-mcp (o python -m bumpguard.server). Cualquier cliente compatible con MCP funciona.

Luego pregúntale a tu agente cosas como:

• "Antes de actualizar pandas a 2.2, verifica si mi pipeline de datos se rompe."
• "Verifica que este fragmento realmente use el SDK de OpenAI instalado."
• "Lista los métodos reales en httpx.Client."

---

Cómo funciona

                 ┌──────────────── 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. Extrae la superficie de API pública de un paquete analizando su código fuente con el ast de Python — para la versión instalada y para la versión objetivo (descargada como wheel y descomprimida, nunca instalada ni ejecutada).
2. Compara las dos superficies en símbolos eliminados / con firma cambiada / añadidos, y clasifica cada uno como disruptivo, potencialmente disruptivo o informativo.
3. Escanea tu código (también vía ast) en busca de usos — resolviendo alias de importación, re-exportaciones, llamadas a métodos de instancia y los argumentos de palabra clave/posicionales que cada llamada pasa.
4. Empareja los usos contra los cambios y reporta un veredicto preciso, línea por línea.

Seguridad: BumpGuard nunca importa código de terceros, por lo que no hay efectos secundarios de importación, ni cuelgues por paquetes pesados, ni ejecución arbitraria de código. Las descargas de wheels están aisladas en un directorio temporal, con límite de tiempo y protegidas contra path traversal / zip bombs.

---

Multi-lenguaje por diseño

BumpGuard está construido alrededor de una interfaz de proveedor conectable. El motor de comparación, el clasificador de cambios disruptivos, el analizador, el reporte y las herramientas MCP son todos neutrales al lenguaje; solo la extracción de superficie y el escaneo de usos son específicos del ecosistema.

• ✅ Python (PyPI) — disponible ahora.
• ✅ .NET (NuGet) — disponible ahora. Lee la API pública de metadatos de ensamblados mediante carga solo-reflexión (sin ejecutar código); necesita el .NET SDK (dotnet) en PATH. Un pequeño helper se compila una vez en el primer uso.
• ✅ Java (Maven) — disponible ahora. Lee la API pública directamente del bytecode .jar compilado (pool de constantes, flags de acceso, descriptores) en Python puro — sin JDK ni Maven requeridos y sin ejecutar código de terceros.
• 🔜 JS/TS (npm) — analiza declaraciones .d.ts.

Añadir un ecosistema significa implementar un Provider — ver docs/ADD_A_PROVIDER.md.

Especificidades de .NET (v1)

• Pasa language: "dotnet". Ejemplo: "Antes de actualizar Azure.AI.OpenAI a 2.1.0, verifica si mi código de cliente se rompe (from_version 1.0.0-beta.17)."
• Compatible: check_upgrade, diff_versions, list_symbols, check_import.
• Prefiere pasar from_version — la línea base "instalada" se toma de la caché global de NuGet, que no es la versión fijada de tu proyecto.
• Señal confiable: eliminaciones y adiciones de tipos / métodos / propiedades (por ejemplo, el renombrado OpenAIClient → AzureOpenAIClient se detecta como una eliminación disruptiva con una sugerencia). Las comparaciones a nivel de parámetros se ejecutan solo para miembros inequívocos de sobrecarga única; los miembros sobrecargados se rastrean por presencia (un límite documentado de v1).
• Las referencias totalmente calificadas se reportan con confianza; los nombres cortos resueltos vía using se reportan como "potencialmente disruptivos" de menor confianza para evitar falsas rupturas duras por colisiones de espacios de nombres.
• verify_snippet no es compatible con .NET en v1 (la detección precisa de alucinaciones en C# necesita vinculación semántica).

Especificidades de Java (v1)

• Pasa language: "java" e identifica los paquetes por su coordenada Maven group:artifact (por ejemplo, com.google.code.gson:gson). Ejemplo: "Antes de actualizar com.google.code.gson:gson a 2.10.1, verifica si mi código se rompe (from_version 2.8.9)."
• Compatible: check_upgrade, diff_versions, list_symbols, check_import.
• La superficie de API pública se lee directamente del bytecode .jar (el jar es un zip de archivos .class; BumpGuard analiza la estructura del archivo de clase con struct — leyendo metadatos, nunca ejecutándolo). El jar objetivo se obtiene de Maven Central (aislado, con límite de tamaño y tiempo). No se necesita JDK/Maven.
• Prefiere pasar from_version — la línea base "instalada" se lee de tu caché local ~/.m2, que puede no coincidir con la versión fijada de tu proyecto.
• Señal confiable: eliminaciones y adiciones de tipos / métodos / campos / constructores, y cambios de aridad. Las referencias totalmente calificadas rompen duro; los nombres cortos resueltos vía import se reportan como "potencialmente disruptivos" de menor confianza para evitar falsas rupturas duras por colisiones de espacios de nombres.
• Límites documentados de v1: los genéricos están borrados en los descriptores de bytecode (por lo que los cambios de argumentos de tipo genérico no se ven); los cambios solo de tipo de retorno y la eliminación de varargs se rastrean de forma conservadora; los miembros sobrecargados se rastrean por presencia (la eliminación por sobrecarga no se detecta); los jars multi-release usan la superposición de versión más alta. El escáner de usos del código fuente es una heurística robusta, no un analizador completo — puede captar la declaración propia de un nombre o la línea import como referencia, pero estos se resuelven a nombres no calificados que están limitados a "potencialmente disruptivos" y nunca pueden producir una falsa ruptura dura. verify_snippet no es compatible con Java en v1 (la detección precisa de alucinaciones necesita vinculación semántica).

---

Limitaciones conocidas (v1, Python)

BumpGuard es honesto sobre el análisis estático. Puede omitir (falsos negativos) o, raramente, marcar de más (falsos positivos):

• APIs generadas dinámicamente (módulos __getattr__, registros de plugins, clientes estilo boto3). BumpGuard detecta módulos __getattr__ y suprime hallazgos confiables de "símbolo faltante" bajo ellos.
• Miembros creados en tiempo de ejecución que no son visibles en el código fuente.
• Internos de extensiones compiladas (C/Rust) — la superficie a nivel de Python aún se lee.
• El seguimiento profundo de flujo de instancias está limitado a patrones directos de x = Class(...).
• Las re-exportaciones con asterisco (from .x import *) no se expanden.

Trata los hallazgos como orientación de alta señal, y la ausencia de hallazgos como "no probado inseguro", no una garantía.

---

Desarrollo

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

La suite de pruebas (42 pruebas) se ejecuta sin conexión usando paquetes de fixture — sin necesidad de red.

Publicación de versiones

Las versiones se automatizan vía GitHub Actions. Para cortar una versión:

1. Aumenta la versión en pyproject.toml y src/bumpguard/__init__.py.
2. Mueve las notas "Unreleased" de CHANGELOG.md bajo un nuevo encabezado de versión.
3. Haz commit, luego etiqueta y empuja:

git tag v0.1.0
git push origin v0.1.0

El flujo de trabajo Release ejecuta las pruebas, construye el wheel + sdist y publica en PyPI vía Trusted Publishing (OIDC — sin tokens almacenados). El flujo de trabajo CI ejecuta la matriz de pruebas (Linux + Windows, Python 3.10/3.13) en cada push y PR.

---

Licencia

MIT — ver LICENSE.