BumpGuard

BumpGuard

守护你的依赖升级。 BumpGuard 是一个 Model Context Protocol（MCP）服务，它会准确指出升级依赖时你的代码中哪些行会出问题；同时还会依据实际安装的 API 验证 AI 编写的代码，让它不再调用不存在的函数。

它只使用静态分析。BumpGuard 从不导入或执行第三方代码，而是直接从源码读取软件包的真实公共 API。

文档告诉你的 Agent 应该有哪些内容。BumpGuard 告诉它这里实际有哪些内容。

---

为什么要做这个项目

开发者反馈使用 AI 编码工具时最令人头疼的问题是：代码“差不多正确，但又不完全正确”。其中很大一部分源于 API 演变和幻觉：

• 模型写出 pydantic.BaseSettings 或 openai.ChatCompletion.create(...)——两版之前完全有效，但你安装的版本中已不存在。
• 你把 pandas 从 1.5 升级到 2.2，然后逐条堆栈跟踪地发现问题。
• 变更日志列出了 1,800 项破坏性变更；你只关心代码实际用到的三项。

BumpGuard 使用来自你环境的事实依据，而非模型的记忆，填补这一空白。

---

功能

举个真实例子——将使用 BaseSettings 的代码中的 pydantic 从 1 升级到 2：

// 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'"
    }
  ]
}

在 2,015 项破坏性 API 变更中，BumpGuard 找出了影响这段代码的唯一一项，并提供行号和修复提示。

---

工具

工具	能回答的问题
check_upgrade ⭐	“如果我把 package 升级到 to_version，这段代码会有什么问题？” 对比已安装版本（或 from_version）与目标版本的 API，只报告代码实际遇到的变更，并提供严重程度和修复提示。
diff_versions	“这个库的两个版本之间有什么变化？” 列出原始破坏性变更，不扫描代码，适合规划迁移。
verify_snippet	“这段代码中的导入和 API 调用在这里确实存在吗？” 检查虚构或拼写错误的软件包名称（软件包名抢注）以及已安装软件包中不存在的属性。
check_import	“这个软件包已安装吗？如果没有，最接近的真实名称是什么？”
list_symbols	“这个软件包的真实公共 API 是什么？” 查找函数、类、方法及其签名，无需猜测；可查询已安装版本或获取的任意版本。
list_languages	查看有哪些生态系统提供程序可用。

每个回答都有证据支撑（已安装版本、源码位置）。由于分析是静态的，“没有发现问题”意味着“没有证据证明会出问题”，并非保证——BumpGuard 会在输出中明确说明这一点。

---

安装

pip install bumpguard-mcp

需要 Python 3.10+。服务通过 stdio 使用 MCP 通信。

请将 BumpGuard 安装到你正在使用的项目所在的同一环境中，这样它才能看到你实际安装的软件包。

---

配置 MCP 客户端

Claude Desktop / Claude Code（claude_desktop_config.json）：

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

Cursor / Windsurf / VS Code（Copilot）——将 MCP 配置指向 bumpguard-mcp 命令（或 python -m bumpguard.server）。任何兼容 MCP 的客户端都可以使用。

然后可以向你的 Agent 提出这类问题：

• “将 pandas 升级到 2.2 之前，检查我的数据管道是否会出问题。”
• “验证这段代码确实使用了已安装的 OpenAI SDK。”
• “列出 httpx.Client 的真实方法。”

工作原理

                 ┌──────────────── 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. 提取：使用 Python 的 ast 解析软件包源代码，提取其公共 API 接口——分别针对已安装版本和目标版本（下载 wheel 并解压，绝不安装或执行）。
2. 比较差异：将两个接口中的符号归类为已移除、签名已更改或新增，并将每项分类为破坏性变更、可能造成破坏的变更或信息提示。
3. 扫描：扫描你的代码（同样使用 ast），查找相关用法，包括解析导入别名、重新导出、实例方法调用，以及每次调用传递的关键字参数和位置参数。
4. 匹配：将用法与变更进行匹配，并报告精确到每一行的判断结果。

**安全性：**BumpGuard 从不导入第三方代码，因此不会产生导入副作用，不会因大型软件包而卡住，也不会执行任意代码。wheel 下载会隔离在临时目录中，设有时间限制，并防范路径遍历和 zip 炸弹。

---

专为多语言设计

BumpGuard 基于可插拔的提供程序接口构建。差异引擎、破坏性变更分类器、分析器、报告功能和 MCP 工具均与语言无关；只有接口提取和用法扫描针对各生态系统实现。

• ✅ Python（PyPI）——现已可用。
• ✅ .NET（NuGet）——现已可用。通过仅反射加载，从程序集元数据中读取公共 API（不执行代码）；需要将 .NET SDK（dotnet）添加到 PATH。首次使用时会构建一个小型辅助程序。
• ✅ Java（Maven）——现已可用。使用纯 Python直接从已编译的 .jar 字节码（常量池、访问标志、描述符）中读取公共 API——无需 JDK 或 Maven，也不会执行第三方代码。
• 🔜 JS/TS（npm）——解析 .d.ts 声明。

添加一种生态系统意味着实现一个 Provider——参见 docs/ADD_A_PROVIDER.md。

.NET 具体说明（v1）

• 传入 language: "dotnet"。示例："升级 Azure.AI.OpenAI 到 2.1.0 前，检查我的客户端代码是否会出问题（from_version 1.0.0-beta.17）。"
• 支持：check_upgrade、diff_versions、list_symbols、check_import。
• 优先传入 from_version——“已安装”基准版本取自 NuGet 全局缓存，并非项目锁定的版本。
• 可靠的判断依据：类型、方法和属性的移除与新增（例如，会将 OpenAIClient 更名为 AzureOpenAIClient 识别为破坏性移除，并提供建议）。只有对于重载唯一的成员，才会执行参数级差异分析；对于重载成员，只跟踪其是否存在（这是 v1 中已说明的限制）。
• 对完全限定的引用可以给出有把握的判断；通过 using 解析的短名称会标记为低置信度的“可能造成破坏的变更”，以避免命名空间冲突导致错误地判定为硬性破坏。
• v1 不支持 .NET 的 verify_snippet（要准确检测 C# 幻觉，需要进行语义绑定）。

Java 特定说明（v1）

• 传入 language: "java"，并使用 Maven 坐标 group:artifact 标识包（例如 com.google.code.gson:gson）。示例：“将 com.google.code.gson:gson 升级到 2.10.1 之前，请检查我的代码是否会出问题（from_version 2.8.9）。”
• 支持：check_upgrade、diff_versions、list_symbols、check_import。
• 公共 API 表面会直接从 .jar 字节码读取（jar 是由 .class 文件组成的 zip；BumpGuard 使用 struct 解析类文件结构——只读取元数据，绝不运行它）。目标 jar 从 Maven Central 获取（在沙盒中执行，并限制大小和时间）。不需要 JDK/Maven。
• 建议传入 from_version——“已安装”基准版本读取自本地 ~/.m2 缓存，可能与项目锁定的版本不一致。
• 可靠信号：类型 / 方法 / 字段 / 构造函数的移除和新增，以及参数数量变化。完全限定的引用会造成硬性破坏；通过 import 解析的短名称会被报告为置信度较低的“可能造成破坏”，以避免因命名空间冲突而误报硬性破坏。
• 文档记录的 v1 限制：泛型在字节码描述符中会被擦除（因此不会检测到泛型类型参数的变化）；仅返回类型变化和移除可变参数会以保守方式跟踪；重载成员按是否存在来跟踪（不会检测到单个重载的移除）；多版本 jar 使用最高版本的覆盖内容。源代码用法扫描器是稳健的启发式方法，并非完整解析器——它可能会将名称自身的声明或 import 行识别为引用，但这些会解析为未限定名称，最高只会标记为**“可能造成破坏”**，绝不会导致误报硬性破坏。v1 不支持 Java 的 verify_snippet（准确检测幻觉需要语义绑定）。

---

已知限制（v1，Python）

BumpGuard 对静态分析的能力边界如实说明。它可能会漏检（假阴性），或偶尔过度标记（假阳性）：

• 动态生成的 API（__getattr__ 模块、插件注册表、boto3 风格的客户端）。BumpGuard 会检测 __getattr__ 模块，并在这些模块下抑制高置信度的“缺少符号”发现。
• 运行时创建、在源代码中不可见的成员。
• 编译型（C/Rust）扩展的内部内容——仍会读取 Python 层面的表面。
• 对实例的深层数据流跟踪仅限于 x = Class(...) 这类直接模式。
• 不会展开星号重导出（from .x import *）。

请将发现视为高信号参考；没有发现只能说明“尚未证明不安全”，并不构成保证。

---

开发

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

测试套件（42 个测试）使用 fixture 包离线运行——无需网络。

发布

发布通过 GitHub Actions 自动完成。创建发布版本的步骤：

1. 在 pyproject.toml 和 src/bumpguard/__init__.py 中更新版本。
2. 将 CHANGELOG.md 中的“Unreleased”说明移至新的版本标题下。
3. 提交，然后打标签并推送：

git tag v0.1.0
git push origin v0.1.0

Release 工作流会运行测试、构建 wheel 和 sdist，并通过 Trusted Publishing（OIDC——不存储令牌）发布到 PyPI。CI 工作流会在每次推送和 PR 时运行测试矩阵（Linux + Windows、Python 3.10/3.13）。

---

许可证

MIT — 详见 LICENSE。