mcp-magento-audit

mcp-magento-audit

AI エージェントに、Magento 2 / Adobe Commerce プロジェクトを対象の PHP および Magento バージョンとの互換性、カスタムモジュールの品質、依存関係のセキュリティという 3 つの軸で評価するツールを提供する MCP サーバーです。

Magento エージェンシーで繰り返し持ち上がる、次の疑問に答えます。 「このクライアントを新しいバージョンにアップグレードできるか、何が妨げになっているのか、どこから始めればよいのか？」

ステータス：初期段階です。 平日の夜や週末に開発しています。計画していた 8 つのツール （get_project_status、check_updates、scan_module_risk、audit_security、check_outdated_packages、 fetch_release_notes、build_upgrade_plan、build_fleet_overview）はすべて動作しています。次の予定については ROADMAP.md をご覧ください。

composer audit との違い

composer audit と composer outdated は Composer に組み込まれており、適切に機能します — audit_security と check_outdated_packages は、CVE データベースやバージョン比較を再実装するのではなく、実際にこれらのコマンドをシェルから実行します。このサーバーは、通常の Composer では得られない情報を対象としています。

1. app/code を確認できません。 カスタムモジュールは Packagist に存在しないため、脆弱性データベースによるカバー率はゼロです。しかも、エージェンシーが書くコードこそがまさにそれです。 scan_module_risk は、代わりに phpcs／phpstan／rector を使ってこの側面をカバーします。
2. 複数の軸を組み合わせません。 「このモジュールはアップグレードを妨げ、未解決の CVE があり、作者によるメンテナンスが終了していて、プロジェクト内で最も複雑度が高い — まずこれを修正すべきです」という答えを一度に得ることはできません。build_upgrade_plan は audit_security の勧告を、Composer の制約やコード品質に関する阻害要因と合わせて提示します。
3. 複数のプロジェクトを横断して集約しません。 「所有する 20 店舗のうち、今日アップグレードできるのはどれか」を把握するには、複数のディレクトリから手作業で結果をつなぎ合わせる必要があります。build_fleet_overview は、1 回の呼び出しで指定されたすべてのプロジェクトパスに対して Composer の制約チェックを実行します — 迅速な初回確認であり、プロジェクトごとの完全な build_upgrade_plan に代わるものではありません。

このサーバーがうたっていないこと：「モジュール X は Magento 2.4.8 で動作する」という整ったデータセットはありません。結果は、composer.json の宣言、コードスキャン、ベンダー独自のリリースノートから導き出されます。これは意思決定を支援するツールであり、絶対的な答えを出すものではありません。本番ストアのアップグレードには、レポートだけでなくテストが必要です。

インストール

git clone https://github.com/michalper/mcp-magento-audit.git
cd mcp-magento-audit
python3.12 -m venv .venv
.venv/bin/pip install -e ".[dev]"

Claude Code への接続

{
  "mcpServers": {
    "magento-audit": {
      "command": "/path/to/mcp-magento-audit/.venv/bin/mcp-magento-audit"
    }
  }
}

Docker/DDEV/Warden/Lando 内で開発するプロジェクト

scan_module_risk（phpcs/phpstan/rector）、check_updates の code_compatibility シグナル、そして audit_security/check_outdated_packages は、いずれもプロジェクト独自の vendor/bin/* と composer をシェル経由で実行します。プロジェクトで PHP/Composer を利用できるのが開発コンテナの内部だけの場合 — Magento ではよくある構成です — MCP サーバーがホスト上で動作していると、これらのチェックはすべて 理由とともに scanned=false を正しく報告します。誤った結果を黙って返すことはありませんが、 「チェックできなかった」ではなく「何も見つからなかった」と誤解されやすいので注意が必要です。

MCP_MAGENTO_AUDIT_EXEC_PREFIX を設定して、これらの呼び出しをコンテナ内で実行するコマンドでラップしてください。例：

export MCP_MAGENTO_AUDIT_EXEC_PREFIX="ddev exec --"
# or: export MCP_MAGENTO_AUDIT_EXEC_PREFIX="docker compose exec -T app"

これは一般的なバインドマウント構成（プロジェクトディレクトリが、ルートだけ異なる同じ相対配置でコンテナ内にも存在する）を前提としています。vendor/bin/phpcs のようなホスト上の絶対パスはラップする前にプロジェクトルートからの相対パスに書き換えられ、composer はホスト側ではなくコンテナ独自の PATH から解決されます。この前提が特定の環境で成り立たない場合は、このサーバーを開発コンテナ内から直接実行する方法（プレフィックスは不要）が、より確実な代替策です。

GitHub API 呼び出しのレート制限

fetch_release_notes は GitHub REST API を呼び出します。未認証の場合、IP あたりの上限は 1 時間に 60 リクエストです。多数のプロジェクトに対して build_fleet_overview や build_upgrade_plan を実行する共有オフィス／CI の IP では、簡単に上限に達する可能性があります。環境変数に GITHUB_TOKEN（または GH_TOKEN）を設定すると、上限を 1 時間に 5000 リクエストまで引き上げられます。この処理では公開リリースデータを読み取るだけなので、読み取り専用のスコープなしトークンで十分です。

例

独自の phpstan.neon がなく、放棄された PHP 7 専用パッケージが 1 つあるストアに対して、エージェントが build_upgrade_plan を呼び出す例（省略版 — 実際の結果には release_notes も含まれ、各ブロッカーの根拠となった update_check/scan_module_risk の全結果も含まれます）：

{
  "ready": false,
  "unverified": [
    "phpstan: no phpstan.neon(.dist) in project — skipping static analysis"
  ],
  "blockers": [
    {
      "source": "composer",
      "description": "legacy/module",
      "detail": "^7.4 does not cover PHP 8.3"
    }
  ]
}

ready が false なのは、推測ではなく実際のブロッカーがあるためです。unverified は phpstan が一度も実行されていないことを示し、別の箇所で問題のない結果が出ても「すべてチェック済み」と誤解されないようにします。

ツール

ツール	状態	説明
get_project_status	動作中	Magento のバージョン、PHP の要件、パッケージ数、放棄されたパッケージ
check_updates	動作中	対象の PHP／Magento バージョンに照らしたパッケージごとの判定と、コード自体に変更が必要かどうかを確認する Rector ベースのチェック
scan_module_risk	動作中	プロジェクトの phpcs（Magento2 コーディング標準）、プロジェクト独自の phpstan、プロジェクト独自の rector.php（デッドコード／品質）を使ってコードをスキャンします。さらに、サードパーティ製 vendor/ Magento モジュールを対象にした別個の phpcs チェック（参考情報であり、アップグレードの阻害要因ではありません）、app/code 内の ObjectManager::getInstance() の誤用を調べる単純な正規表現スキャン（標準の独自 sniff とは異なり、.phtml に限定されません）、コアのオーバーライドチェック（同じ FQCN で vendor/magento/* クラスを再宣言する app/code のクラス。アップグレードの阻害要因です）、参照先のないクラスのチェック（di.xml／events.xml／crontab.xml／レイアウト XML／indexer.xml／schema.graphqls で、存在しなくなった PHP クラスを指定している箇所。参考情報です）も実施します
audit_security	動作中	composer.lock にあるインストール済みパッケージ（Magento コア、サードパーティ製 vendor/ 拡張機能、開発依存関係を含む）すべてを composer audit で既知のアドバイザリについてチェックします
check_outdated_packages	動作中	既知の CVE や対象バージョンとの互換性とは独立して、インストール済みパッケージすべてについて、より新しいバージョンが利用可能か composer outdated でチェックします
fetch_release_notes	動作中	magento/magento2 の GitHub Releases からリリースノートを取得します。モデルの記憶に基づいて回答することはありません
build_upgrade_plan	動作中	他のツールを組み合わせ、具体的な阻害要因を一覧にします。阻害要因がなくなった場合にのみ ready=true になります
build_fleet_overview	動作中	check_updates のみを使って、対象の PHP／Magento バージョンに照らし、多数のプロジェクトを一度にトリアージします（「これら N 個のストアのうち、今日アップグレードできるのはどれか」）。高速な初回チェックであり、プロジェクトごとの build_upgrade_plan の代わりにはなりません

開発

.venv/bin/python -m pytest --cov        # tests + coverage
.venv/bin/ruff check .                  # lint
.venv/bin/mypy src                      # types
.venv/bin/bandit -c pyproject.toml -r src   # security
.venv/bin/pip-audit                     # dependency vulnerabilities

.venv/bin/pre-commit install を一度実行すると、コミットのたびに上記すべてが実行されます（ネットワークアクセスが必要な pip-audit は除きます。これは CI 専用です）。

アーキテクチャ上の決定は docs/adr/ に記録されています。各リリースでの変更点については CHANGELOG.md を参照してください。

ライセンス

MIT