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 (project_status, check_updates, module_risk, security_audit, outdated_packages, fetch_release_notes, upgrade_plan, 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 — security_audit and 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. 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. upgrade_plan does, folding security_audit'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. 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 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"
    }
  }
}

Example

An agent calling 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/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