Mcp Magento Audit

mcp-magento-audit

[mcp-magento-audit — an MCP server that audits Magento 2 / Adobe Commerce projects for AI coding agents]

[CI] [PyPI] [michalper/mcp-magento-audit MCP server] [License: MIT] [Python 3.12+] [Ruff] [Last commit]

An MCP server giving an AI agent tools to assess a Magento 2 / Adobe Commerce project along three axes: compatibility with a target PHP and Magento version, quality of custom modules, and dependency security.

It answers the question that never stops coming up in Magento agencies: "can we bump this client to a newer version, what's blocking it, and where do we start?"

Status: early stage. Built on evenings/weekends. All eight planned tools (get_project_status, check_updates, scan_module_risk, audit_security, check_outdated_packages, fetch_release_notes, build_upgrade_plan, build_fleet_overview) are working. See ROADMAP.md for what's next.

How this differs from composer audit

composer audit and composer outdated are built into Composer and do their job well — audit_security and check_outdated_packages actually shell out to them rather than reimplementing a CVE database or version comparison. This server targets what plain Composer doesn't give you:

1. It doesn't see app/code. Custom modules don't exist on Packagist, so they get zero coverage from vulnerability databases — and that's exactly the code agencies write. scan_module_risk covers that side with phpcs/phpstan/rector instead.
2. It doesn't combine axes. Nobody gets one answer: this module blocks the upgrade, has an open CVE, is abandoned by its author, and has the worst complexity in the project — fix this one first. build_upgrade_plan does, folding audit_security's advisories in alongside composer-constraint and code-quality blockers.
3. It doesn't aggregate across projects. "Which of our twenty stores can be upgraded today" requires stitching results together from many directories by hand. build_fleet_overview runs the composer-constraint check across every project path given to it in one call — a fast first pass, not a replacement for a full build_upgrade_plan per project.

What this server doesn't pretend to be: there's no clean dataset of "module X works with Magento 2.4.8". Results are derived from declarations in composer.json, a code scan, and the vendor's own release notes — this is a decision-support tool, not an oracle. Upgrading a production store still requires testing, not just a report.

Install

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

Connecting to Claude Code

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

Projects that develop inside Docker/DDEV/Warden/Lando

scan_module_risk (phpcs/phpstan/rector), check_updates's code_compatibility signal, and audit_security/check_outdated_packages all shell out to the project's own vendor/bin/* and composer. If that project only has PHP/Composer available inside a dev container — common for Magento — and this MCP server runs on the host, every one of those checks will correctly report scanned=false with a reason rather than silently being wrong, but that's easy to misread as "found nothing" instead of "couldn't check".

Set MCP_MAGENTO_AUDIT_EXEC_PREFIX to wrap every one of those calls in a command that runs it inside the container instead, e.g.:

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

This assumes the usual bind-mount setup (the project directory mirrors the same relative layout inside the container, just under a different root) — host-absolute paths like vendor/bin/phpcs are rewritten relative to the project root before being wrapped, and composer resolves against the container's own PATH rather than the host's. If that assumption doesn't hold for a given setup, running this server from inside the dev container directly (no prefix needed) is the more reliable fallback.

Rate limits on GitHub API calls

fetch_release_notes calls the GitHub REST API, capped at 60 requests/hour per IP when unauthenticated — easily hit from a shared office/CI IP running build_fleet_overview or build_upgrade_plan across many projects. Set GITHUB_TOKEN (or GH_TOKEN) in the environment to raise that to 5000/hour; a read-only, no-scope token is enough, since this only ever reads public release data.

Example

[Claude Code calling build_upgrade_plan against a store that has one abandoned, PHP-7-only package — ready: false, with the real blocker and a note that phpstan never ran]

An agent calling build_upgrade_plan against a store that has one abandoned, PHP-7-only package and no phpstan.neon of its own (trimmed — the real result also includes release_notes, and the full update_check/scan_module_risk results each blocker was derived from):

{  "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 is false because of a real blocker, not a guess; unverified says phpstan never ran at all, so a clean result elsewhere isn't mistaken for "everything was checked".

Tools

Development

.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

Run .venv/bin/pre-commit install once to run all of the above (except pip-audit, which needs network access and stays CI-only) on every commit.

Architectural decisions are recorded in docs/adr/. See CHANGELOG.md for what changed in each release.

License

MIT