io.github.michalper/mcp-magento-audit

mcp-magento-audit

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.git
cd mcp-magento-audit
python3.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

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