BumpGuard

BumpGuard

依存関係のバージョンアップを見守ります。 BumpGuard は、依存関係をアップグレードしたときに、AI コーディングエージェントに、あなたのコードのどの行が壊れるかを正確に伝える Model Context Protocol（MCP）サーバーです。また、AI が生成したコードを実際にインストールされている API と照合して検証するため、存在しない関数を呼び出さなくなります。

その方法は静的解析のみです。BumpGuard はサードパーティのコードをインポートも実行もせず、パッケージの実際の公開 API をソースから直接読み取ります。

ドキュメントは、何が存在する「はず」かをエージェントに伝えます。BumpGuard は、ここに「実際に」存在するものを伝えます。

---

これが必要な理由

開発者が AI コーディングツールへの不満として最も多く挙げるのは、「ほぼ正しいけれど、少し違う」コードです。その大きな原因のひとつが、API の変化とハルシネーションです。

• モデルが pydantic.BaseSettings や openai.ChatCompletion.create(...) を書きます。2 つ前のバージョンでは完全に有効でしたが、インストール済みのバージョンでは削除されています。
• pandas を 1.5 から 2.2 にバージョンアップすると、スタックトレースをひとつずつ確認しながら問題を見つけることになります。
• 変更履歴には1,800 件の破壊的変更が並んでいますが、気になるのは実際にコードが使用している3 件だけです。

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

API の破壊的変更2,015 件のうち、BumpGuard はこのコードに影響する1 件を、行番号と修正のヒントとともに報告しました。

---

ツール

ツール	回答する質問
check_upgrade ⭐	「package を to_version にアップグレードすると、このコードのどこが壊れますか？」 インストール済み（または from_version）の API とアップグレード先を比較し、実際にコードが使用している変更のみを、深刻度と修正のヒントとともに報告します。
diff_versions	「このライブラリの 2 つのバージョン間で何が変わりましたか？」 コードのスキャンなしで、破壊的変更の一覧をそのまま表示します。移行計画に役立ちます。
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 互換のクライアントならどれでも使用できます。

エージェントに、次のように尋ねてみてください。

• 「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. 差分の検出 — 2 つの公開 API を比較し、削除／シグネチャの変更／追加に分類して、それぞれを破壊的、破壊的である可能性あり、または情報として分類します。
3. スキャン — コード（こちらも ast を使用）をスキャンして使用箇所を特定し、インポートのエイリアス、再エクスポート、インスタンスメソッドの呼び出し、および各呼び出しで渡されるキーワード引数／位置引数を解決します。
4. 照合 — 使用箇所を変更内容と照合し、行ごとに正確な判定を報告します。

安全性： BumpGuard はサードパーティーのコードをインポートしないため、インポート時の副作用、重いパッケージによるハング、任意のコード実行は発生しません。wheel のダウンロードは一時ディレクトリ内に隔離し、時間制限を設け、パストラバーサルや zip bomb を防止します。

---

マルチ言語を前提とした設計

BumpGuard はプラグイン可能なプロバイダーインターフェースを中心に構築されています。差分エンジン、破壊的変更の分類器、アナライザー、レポート機能、MCP ツールはすべて言語に依存せず、公開 API の抽出と使用箇所のスキャンのみがエコシステム固有です。

• ✅ Python（PyPI） — 現在利用できます。
• ✅ .NET（NuGet） — 現在利用できます。リフレクション専用の読み込みでアセンブリメタデータから公開 API を読み取ります（コードは実行されません）。PATH 上に .NET SDK（dotnet）が必要です。初回使用時に小さなヘルパーを一度だけビルドします。
• ✅ Java（Maven） — 現在利用できます。コンパイル済みの .jar バイトコード（定数プール、アクセスフラグ、記述子）から、純粋な Python で公開 API を直接読み取ります — JDK も Maven も不要で、サードパーティーのコードも実行されません。
• 🔜 JS/TS（npm） — .d.ts 宣言を解析します。

エコシステムを追加するには、Provider を 1 つ実装します — 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 行を参照として拾うことがありますが、これらは修飾されていない名前として解決され、最大でも**「破壊的変更の可能性あり」**に制限されるため、誤って確実な破壊的変更と判定されることはありません。verify_snippet は、正確な幻覚検出にセマンティックバインディングが必要なため、v1 では Java に対応していません。

---

既知の制限事項（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 件のテスト）は、フィクスチャパッケージを使ってオフラインで実行できます。ネットワークは不要です。

リリース

リリースは 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 を参照してください。