# freento/module-mcp-audit

> MCP Audit Tools for Magento 2

`composer require freento/module-mcp-audit`

Canonical URL: https://packagento.com/freento/module-mcp-audit

## At a glance

- **Vendor**: Freento (https://packagento.com/freento.md)
- **Latest version**: 1.0.0 — released 2026-05-27
- **Pricing**: Free
- **Package type**: Magento 2 module
- **Status**: active, accepting new buyers

## Installation

Packagento is licence-gated, so even free packages need a licence on a project before Composer can resolve them.

1. **Sign in or create an account** at https://packagento.com/customer/account/.

2. **Add the package to your account.** Open https://packagento.com/freento/module-mcp-audit and complete the free checkout. A licence is minted automatically.

3. **Create or pick a project, then activate the licence on it.**
   - Projects represent the Magento installs you deploy to. Manage them at https://packagento.com/projects/.
   - Activate the new licence on the project you'll deploy this package to. Activation is what generates the Composer credentials scoped to that project.

4. **Add the project credentials to your Magento codebase.**

   Grab the project's public + private key from https://packagento.com/projects/ (open the project, then its Credentials tab), and add them to `auth.json`:

   ```json
   {
     "http-basic": {
       "packagento.com": {
         "username": "ppk_live_...",
         "password": "psk_live_..."
       }
     }
   }
   ```

   Add the Packagento Composer repository to `composer.json`:

   ```json
   {
     "repositories": [
       { "type": "composer", "url": "https://packagento.com" }
     ]
   }
   ```

5. **Install and apply.**

   ```bash
   composer require freento/module-mcp-audit:*
   bin/magento setup:upgrade
   bin/magento setup:di:compile
   bin/magento cache:flush
   ```

## What it does

MCP Audit Tools for Magento 2

## README

Add-on for [Freento_Mcp](../Mcp) that registers a set of audit and diagnostic MCP tools. The tools are designed for AI-driven store audits — collecting structured data about the filesystem, database, configuration, logs, indexers, cron, third-party modules, code quality and email delivery, all exposed over the standard MCP protocol provided by `Freento_Mcp`.

### Features

- 16 ready-to-use audit tools registered into the parent module's `ToolRegistry`
- Single admin toggle to hide every audit tool everywhere (tools/list, tools/call, ACL UI)
- Log error grouping with smart message normalization (UUIDs, IDs, quoted values, emails)
- Two-step on-demand SQL query counter for any frontend URL (bypasses FPC)
- Sensitive `env.php` keys (passwords, secrets, hosts, ports, etc.) automatically masked
- Curated critical-settings check (deployment mode, 2FA, MySQL optimizer, Xdebug/APCu, key rotation, …)

### Requirements

- Magento 2.4.x
- PHP 8.1+
- `freento/module-mcp` `^1.2` (loaded as a module sequence dependency)
- `magento/magento-coding-standard` (declared as a composer dependency; required by `run_code_sniffer`)

### Installation

#### Via Composer

```bash
composer require freento/module-mcp-audit
php bin/magento module:enable Freento_McpAudit
php bin/magento setup:upgrade
php bin/magento cache:flush
```

#### Manual

Copy the module to `app/code/Freento/McpAudit/` and run:

```bash
php bin/magento module:enable Freento_McpAudit
php bin/magento setup:upgrade
php bin/magento cache:flush
```

### Configuration

`Stores > Configuration > Freento > MCP > MCP Audit`

| Field | Path | Description |
|-------|------|-------------|
| Enable Audit Tools | `freento_mcp/audit/enabled` | When disabled, all McpAudit tools are hidden everywhere — they are not exposed via `tools/list`, cannot be called, and do not appear in the ACL Rule tools list. |

The toggle is enforced at the `ToolRegistry` level via `Plugin\ToolRegistryPlugin`, which filters out every tool whose class lives under the `Freento\McpAudit\` namespace when the module is disabled.

### Available Tools

#### Database & Filesystem

| Tool | Description |
|------|-------------|
| `get_table_sizes` | Database table sizes (rows + MB) sorted by size, with optional `LIKE` pattern, min-size and limit filters. |
| `get_log_file_sizes` | Files in `var/log` and `var/report` sorted by size, with each file's inode change time (`ctime`). |

#### Logs & Errors

| Tool | Description |
|------|-------------|
| `get_log_errors` | Greps `var/log/*.log` for `ERROR`/`CRITICAL` entries, groups identical errors after normalizing UUIDs, IDs, quoted strings and emails. Filterable by date range (silently truncated to the first 31 days starting at `from_date`), sortable by `count`/`first_seen`/`last_seen`. Defaults: `from_date`/`to_date` = today, `limit` = 50 (max 200). |

#### Indexers & Cron

| Tool | Description |
|------|-------------|
| `get_indexer_statuses` | All indexers with status (`valid`/`invalid`/`working`), mode (`schedule`/`save`) and changelog backlog count. |
| `get_cron_config` | Cron groups configuration: schedule/lifetime/cleanup settings (XML defaults vs DB overrides), `use_separate_process` flag, and per-group job list with cron expressions. |
| `get_cron_schedule` | Cron schedule history (`cron_schedule` table) with filtering, sorting and aggregation, plus a derived `execution_time` field (`finished_at - executed_at`, rendered as a human-readable duration like `5m 30s`). |

#### Configuration

| Tool | Description |
|------|-------------|
| `get_critical_settings` | Curated checks that are awkward to express via the generic config tools: deployment mode, admin URL, 2FA status, active cart rules without a coupon (always-on rules), MySQL `optimizer_switch` / `optimizer_use_condition_selectivity`, Xdebug + APCu state, search terms count, presence of an active `admin` user, and whether the encryption key has been rotated. |
| `get_config_data` | Fully resolved `ScopeConfigInterface` values (config.xml + `core_config_data` + env.php overrides). Accepts exact paths or path prefixes; supports `default`/`websites`/`stores` scopes and `all_scopes: true` for a full dump. |
| `get_php_ini_settings` | `ini_get()` lookup for an explicit list of php.ini directives. |
| `get_deployment_config` | Values from `app/etc/env.php` for an explicit `paths` list. Sensitive entries are silently omitted — match either a substring (`password`, `passwd`, `secret`, `token`, `crypt`, `salt`, `private`, `credential`, `api_key`, `access_key`, `bearer`, `oauth`, `signature`, `hmac`) or a full path segment (`host`, `port`, `server`, `dbname`, `username`, `user`, `pwd`, `pass`, `key`, `auth`, `pem`, `cert`). |

#### Modules & Code Quality

| Tool | Description |
|------|-------------|
| `get_third_party_modules` | Installed non-`Magento` and non-`PayPal` modules grouped by vendor, with composer name and install location (`app/code` vs `vendor/`). Optional `include_latest_version` queries the configured composer repositories for available stable upgrades. |
| `run_code_sniffer` | Runs `vendor/bin/phpcs --standard=Magento2` against a module name (`Vendor_Module`), relative path, or absolute path. Output is parsed from JSON, filtered by severity, capped at 200 KB, and grouped per file. |

#### Catalog & Customer

| Tool | Description |
|------|-------------|
| `get_customer_groups` | `customer_group` rows with filtering and aggregation (entity-tool framework). |
| `get_eav_attributes` | `eav_attribute` rows with filtering by entity type, backend type, frontend input, native vs user-defined. |

#### Performance & Email

_(README truncated for .md surface. Full README on https://packagento.com/freento/module-mcp-audit.)_

## Recent Versions

| Version | Released |
|---|---|
| 1.0.0 | 2026-05-27 |

## Dependencies

### Require

| Package | Constraint |
|---|---|
| freento/module-mcp | ^1.2 |
| magento/magento-coding-standard | * |
| php | ^8.1 |

## Quality

Latest release (1.0.0) fails the Packagento QA pipeline. Verdicts below are per-cell (Magento line × PHP version) for the matrixed tools, and run-once for the static / security tiers.


### Compatibility

Each Magento line is installed on its supported PHP versions, then the module is built (DI compile + static-content deploy). Cells show passed / failed / untested; staircase gaps render as `–`.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | 1 | 1 | – | – |
| 2.4.8 | – | 1 | 1 | – |
| 2.4.9 | – | – | 1 | 1 |


### Code Quality

Advisory checks against the module's source. Never affect the Compatibility verdict — a phpcs finding can't make a module incompatible.

#### Static Analysis

Coding standards (phpcs), mess detection (phpmd), copy-pasted code (cpd), PHP cross-version compatibility, composer.json validity. Each runs once for the whole module.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| PHPCS | Fail | 27 | 2 errors, 25 warnings (ruleset: Magento2) |
| PHPMD | Warning | 28 | 28 rule violations (MissingImport:16, NPathComplexity:5, CyclomaticComplexity:4, EmptyCatchBlock:1, ExcessiveClassComplexity:1) |
| Cpd | Pass | 0 |  |
| Composer validate | Info | 2 | valid; 2 advisory notes (composer validate --strict) |

#### PHPStan

Type-checks the module against a real Magento install. Re-runs per Magento + PHP version because resolvable symbols differ between releases.

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | 7 | 7 | – | – |
| 2.4.8 | – | 7 | 7 | – |
| 2.4.9 | – | – | 7 | 7 |


### Tests

Unit and integration suites run per Magento + PHP cell. Test failures speak to the module's behaviour, not its compatibility with a line, so they're reported here separately.

#### Unit Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |

#### Integration Tests

| Magento | PHP 8.2 | PHP 8.3 | PHP 8.4 | PHP 8.5 |
|---|---|---|---|---|
| 2.4.7 | N/A | N/A | – | – |
| 2.4.8 | – | N/A | N/A | – |
| 2.4.9 | – | – | N/A | N/A |


### Security

Dependency-advisory audit (composer audit) plus a source malware scan. A malware detection fails the version outright.

| Tool | Status | Findings | Summary |
|---|---|---|---|
| Composer audit | Pass | 0 |  |
| Malware scan | Pass | 0 |  |

## Licence and pricing

Free. A licence is still minted on checkout and bound to your project for Composer access — no payment step.

Refundable within 14 days of first purchase via https://packagento.com/account/refunds/.

## Install via Claude Code or any MCP client

The Packagento MCP server can run the licence + project + Composer steps above in one tool call:

```
purchase_and_install_packages(
  composer_names=["freento/module-mcp-audit"],
  project_id="proj_xxx"
)
```

This handles cart, checkout, licence minting, project activation, and writes auth.json credentials. Connect a client with `claude mcp add packagento https://mcp.packagento.com`. Full setup at https://packagento.com/docs/mcp-setup.

## Vendor

Freento is a Magento 2 vendor on Packagento. See https://packagento.com/freento.md for their full catalogue.