mcp-magento-audit

mcp-magento-audit

这是一个 MCP 服务，为 AI Agent 提供工具，从三个维度评估 Magento 2 / Adobe Commerce 项目：与目标 PHP 和 Magento 版本的兼容性、自定义模块质量以及依赖项安全性。

它回答 Magento 服务机构中总会有人提出的问题： “我们能否将这个客户升级到较新版本？有哪些阻碍？应该从哪里着手？”

状态：早期阶段。 利用晚间和周末时间开发。计划中的全部八项工具 （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. 它不会跨项目汇总。 要回答“我们的二十家商店中，哪些现在可以升级”，就得手动拼接多个目录的结果。build_fleet_overview 只需调用一次，就能对提供的每个项目路径执行 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 解析，而非使用主机的 PATH。如果某个设置不符合这一假设，更可靠的备用方案是直接在开发容器内部运行此服务（无需设置前缀）。

GitHub API 调用的速率限制

fetch_release_notes 会调用 GitHub REST API；未经过身份验证时，每个 IP 每小时最多可发起 60 次请求。如果共享办公室/CI 的 IP 通过多个项目运行 build_fleet_overview 或 build_upgrade_plan，很容易触及此限制。在环境中设置 GITHUB_TOKEN（或 GH_TOKEN），即可将限制提高到每小时 5000 次；只读且无需任何权限范围的令牌就足够了，因为这里只会读取公开的发布数据。

示例

Agent 针对一个包含一个已弃用、仅支持 PHP 7 的软件包且自身没有 phpstan.neon 的商店调用 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() 的情况（不限于 .phtml，而标准自身的 sniff 有此限制），检查核心覆盖情况（app/code 中以相同 FQCN 重新声明 vendor/magento/* 类的类——这会阻止升级），并检查悬空引用（di.xml/events.xml/crontab.xml/布局 XML/indexer.xml/schema.graphqls 中引用了已不存在的 PHP 类——仅供参考）
audit_security	正常工作	通过 composer audit 检查 composer.lock 中安装的每个软件包——包括 Magento 核心、第三方 vendor/ 扩展和开发依赖项——是否存在已知安全公告
check_outdated_packages	正常工作	使用 composer outdated 检查每个已安装的软件包是否有更新的可用版本——与已知 CVE 或目标版本兼容性无关
fetch_release_notes	正常工作	从 magento/magento2 GitHub Releases 获取发行说明，不会根据模型的记忆作答
build_upgrade_plan	正常工作	将其他工具的结果汇总为具体阻碍事项列表，只有在列表为空时才会设置 ready=true
build_fleet_overview	正常工作	针对目标 PHP/Magento 版本一次性对多个项目进行分诊（“这些 N 个商店中，哪些今天可以升级？”），仅通过 check_updates 执行——这是快速初筛，不能替代对每个项目运行 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