Magento Bricklayer

Magento Bricklayer

An MCP server that gives AI coding agents runtime visibility into Magento 2. Agents reading source files miss the full picture — DI preferences, plugin chains, EAV attributes, and event observers are resolved at runtime across dozens of modules. Bricklayer exposes this runtime state so agents make informed architectural decisions instead of guessing.

Table of Contents

• [What is Bricklayer?](#what-is-bricklayer)
• [How Agents Use Bricklayer](#how-agents-use-bricklayer)
• [Requirements](#requirements)
• [Installation](#installation)
• [Quick Start](#quick-start)
• [Supported AI Agents](#supported-ai-agents)
• [Available Commands](#available-commands)
• [install](#install)
• [init](#init)
• [mcp](#mcp)
• [inspect](#inspect)
• [update](#update)
• [verify](#verify)
• [Docker / Container Environments](#docker--container-environments)
• [Automatic Container Detection](#automatic-container-detection)
• [MCP Tools Overview](#mcp-tools-overview)
• [Application & Module Tools](#application--module-tools)
• [Database Tools](#database-tools)
• [EAV Tools](#eav-tools)
• [Configuration & DI Tools](#configuration--di-tools)
• [Routing & API Tools](#routing--api-tools)
• [GraphQL Tools](#graphql-tools)
• [View Tools](#view-tools)
• [Message Queue Tools](#message-queue-tools)
• [Catalog Tools](#catalog-tools)
• [Order Tools](#order-tools)
• [Customer Tools](#customer-tools)
• [Development Tools](#development-tools)
• [Log Tools](#log-tools)
• [Diagnostic Tools](#diagnostic-tools)
• [Code Runner Tool](#code-runner-tool)
• [Code Generation Tools](#code-generation-tools)
• [Development Context Tool](#development-context-tool)
• [Context-Aware Hints](#context-aware-hints)
• [Pagination](#pagination)
• [MCP Resources](#mcp-resources)
• [Guidelines Resource](#guidelines-resource)
• [Coding Standards Resource](#coding-standards-resource)
• [Skills Resource](#skills-resource)
• [Template & Reference Resources](#template--reference-resources)
• [Configuration](#configuration)
• [Per-Tool Configuration](#per-tool-configuration)
• [Recommended Production Configuration](#recommended-production-configuration)
• [Environment Variable Overrides](#environment-variable-overrides)
• [Architecture](#architecture)
• [Auto-Reinitialize](#auto-reinitialize)
• [Config Hot-Reload](#config-hot-reload)
• [Project-Local Overrides](#project-local-overrides)
• [Directory layout](#directory-layout)
• [Override vs addition semantics](#override-vs-addition-semantics)
• [Optional SKILL.md frontmatter](#optional-skillmd-frontmatter)
• [Typical workflow](#typical-workflow)
• [Extending Bricklayer](#extending-bricklayer)
• [Add a tool to an existing class](#add-a-tool-to-an-existing-class)
• [Add a new tool class](#add-a-new-tool-class)
• [Add a guideline](#add-a-guideline)
• [Add a skill](#add-a-skill)
• [Add a development-context category](#add-a-development-context-category)
• [Regenerate documentation](#regenerate-documentation)
• [Security](#security)
• [Query & Log Safety](#query--log-safety)
• [Production Mode Protection](#production-mode-protection)
• [Per-Tool Configuration](#per-tool-configuration-1)
• [Code Execution Safety](#code-execution-safety)
• [Contributing](#contributing)
• [License](#license)
• [Credits](#credits)

What is Bricklayer?

Bricklayer is a Composer library that implements an MCP server for Magento 2. When started, it exposes 83 tools that AI agents can invoke to:

• Check runtime state before writing code — see actual plugin chains, DI resolution, preferences, and event observers across all installed modules
• Inspect database schema, EAV attributes, and system configuration as they exist at runtime
• Diagnose errors with full context (exception + stack trace + DI + plugin chains + fix suggestions)
• Analyze performance across indexes, cache, cron, and query patterns
• Manage products, orders, and customers through Magento's service layer
• Generate Magento-compliant module scaffolding with conflict detection
• Load domain-specific development guidelines and coding standards on demand

Only 17 essential tools are visible at startup — the remaining 66 are discoverable via search-tools, reducing token overhead while keeping all tools callable.

The name "Bricklayer" reflects the methodical, structured approach to building Magento 2 modules and extensions, laying each component (the "bricks") in the correct order and position to construct a solid, maintainable codebase.

How Agents Use Bricklayer

Magento resolves DI configuration, plugin chains, preferences, and event observers at runtime across all installed modules. An agent reading source files sees only one module's perspective — it misses overrides, conflicts, and customizations from other modules. Bricklayer bridges this gap.

Before writing a plugin, an agent calls check-class to see existing plugins and their sortOrders, DI preferences, and class rewrites — preventing conflicts that would only surface in environments with more extensions installed.

Before working with products or customers, an agent calls eav-attributes to discover custom attributes that exist only in the database, not in any source file.

When debugging, an agent calls diagnose-error which combines the exception log, stack trace, DI context, and plugin chain analysis into a single actionable diagnosis — far more than reading var/log/exception.log alone.

Before writing any code, an agent calls development-context to load domain-specific guidelines (plugin patterns, EAV best practices, Hyvä checkout APIs, etc.) ensuring the generated code follows Magento conventions.

Each tool response includes hints pointing to the next logical step — introspection tools suggest relevant guidelines to load, and guidelines suggest which runtime checks to perform. This creates a natural workflow: check → learn → write.

Requirements

• PHP 8.1 or higher
• Magento 2.4.4 or higher
• Composer 2.2 or higher

Installation

As a Development Dependency (Recommended)

composer require --dev inchoo/magento-bricklayer

Global Installation

composer global require inchoo/magento-bricklayer

Quick Start

1. Install Agent Configuration

Run from your Magento project root:

vendor/bin/bricklayer install

This prompts you to select which AI agents to configure and generates:

• .mcp.json - MCP server configuration (always created)
• .bricklayer.json - Tool safety configuration with deploy-mode-aware defaults
• Agent-specific guideline files based on your selection (e.g. CLAUDE.md, .cursorrules)

2. Start Using with Your AI Agent

The MCP server is automatically started by compatible agents. Your agent can now:

• Use application-info to understand your Magento installation
• Use module-list to see installed modules
• Use database-schema to inspect table structures
• Use product-get, order-get, customer-get for data access
• Use diagnose-error to diagnose errors with full context and fix suggestions
• Use development-context to load coding guidelines for your task
• And many more tools for comprehensive Magento development

Supported AI Agents

| Agent | Configuration Files | Status | |-------|---------------------|--------| | Claude Code | .mcp.json + CLAUDE.md | Fully Supported | | Cursor | .mcp.json + .cursorrules | Fully Supported | | GitHub Copilot | .mcp.json + .github/copilot-instructions.md | Supported | | JetBrains AI (PhpStorm) | .mcp.json + .junie/guidelines.md | Supported | | Gemini CLI | .mcp.json + AGENTS.md | Supported |

Available Commands

install

Generates agent configuration files for your AI tools.

vendor/bin/bricklayer install [options]

Options:

• --magento-root=PATH - Specify Magento root directory (auto-detected by default)
• --agents=AGENT - Agent to configure; repeat the flag for multiple (e.g. --agents=claude-code --agents=cursor). Valid values: claude-code, cursor, phpstorm, copilot, gemini. Omit to choose interactively
• --force - Overwrite existing configuration files

init

Generates .bricklayer.json configuration file with deploy-mode-aware defaults.

vendor/bin/bricklayer init [options]

Options:

• --magento-root=PATH - Specify Magento root directory (auto-detected by default)
• --force - Overwrite existing .bricklayer.json

The generated config contains one entry per runtime-configurable tool (35 tools at the time of writing). The list is discovered by scanning the source for requireToolEnabled() call sites, so every key the file contains is one the runtime actually honors — no dead keys, no drift.

Deploy-mode behavior:

• production — 11 tools disabled (code-runner + all 10 destructive/code-generation tools), database-query.max_rows lowered to 50
• developer/default — 10 destructive tools (*-delete, order-cancel, creditmemo-create, 4 generate-*) disabled by default, everything else enabled, code-runner read-only

This command is also called automatically during bricklayer install. Additionally, bricklayer verify will auto-generate the file if it's missing.

config:set

Update a single value in .bricklayer.json with full validation, round-trip verification, and a guided interactive mode for discoverability.

# Interactive — walks you through tool selection, setting, and value
vendor/bin/bricklayer config:set

# Scripted — dot-notation key + value
vendor/bin/bricklayer config:set tools.product-delete.enabled true
vendor/bin/bricklayer config:set tools.database-query.max_rows 250
vendor/bin/bricklayer config:set tools.code-runner.allow_write false

Options:

• --magento-root=PATH — Specify Magento root directory (auto-detected by default)

Interactive mode (no arguments) is the recommended path for newcomers. It lists all 35 runtime-configurable tools with their current values inline, lets you pick a tool, pick a setting (when more than one is available), and enter a new value with type-aware validation (bool picker, int validator that re-prompts on non-numeric input).

Scripted mode (positional arguments) is for automation. Values are parsed automatically: true/false → bool, null → null, numeric → int/float, [...]/{...} → JSON-decoded, anything else → string.

Safety checks on every successful set:

• Validation — refuses to write if the resulting config fails ConfigValidator (e.g. negative max_rows, non-bool enabled)
• Round-trip verification — re-loads the file through ConfigLoader and confirms the new value is readable
• Non-configurable tool warning — warns if you try to set enabled on a read-only introspection tool that does not honor the flag at runtime
• Environment-variable shadow warning — warns if a matching BRICKLAYER_* env var is set that would override your file change
• Hot-reload note — reminds you that the running MCP server picks up changes on its next tool call, so no agent restart is required

Auto-creates .bricklayer.json with deploy-mode-aware defaults if the file is missing.

Negative integer values need the -- separator (standard Symfony Console behavior):

vendor/bin/bricklayer config:set -- tools.database-query.max_rows -1  # will fail validation

mcp

Starts the MCP server (invoked automatically by AI agents).

vendor/bin/bricklayer mcp [options]

Options:

• --magento-root=PATH - Specify Magento root directory

inspect

Displays information about the current Magento installation.

vendor/bin/bricklayer inspect [options]

Options:

• --json - Output as JSON instead of formatted table
• --no-bootstrap - Skip full Magento bootstrap (faster, limited info)

update

Regenerates agent configuration files (CLAUDE.md, .cursorrules, etc.) from the current bundled content plus any project-local overrides in .bricklayer/.

vendor/bin/bricklayer update [options]

Options:

• --magento-root=PATH - Specify Magento root directory (auto-detected by default)

When the project has files under .bricklayer/ (see [Project-Local Overrides](#project-local-overrides)), the command reports which local files were applied alongside the regenerated agent files.

verify

Runs a post-install health check against your Bricklayer installation.

vendor/bin/bricklayer verify [options]

Options:

• --magento-root=PATH - Specify Magento root directory (auto-detected by default)
• --json - Output results as JSON

Checks performed: Magento bootstrap, deploy mode detection, MCP server creation and tool count, agent configuration files, PsySH availability for code-runner, database connectivity, log directory writability, and .bricklayer.json validation. If .bricklayer.json is missing, verify auto-generates it with deploy-mode-aware defaults.

Docker / Container Environments

Bricklayer automatically detects Docker, DDEV, and Warden environments:

# The install command generates appropriate configuration
vendor/bin/bricklayer install

# For Docker Compose, it generates:
# "command": "docker compose exec -T php php vendor/bin/bricklayer-mcp"

# For DDEV:
# "command": "ddev exec php vendor/bin/bricklayer-mcp"

# For Warden:
# "command": "warden shell -c php vendor/bin/bricklayer-mcp"

Automatic Container Detection

For Docker environments with dynamic or non-standard container names, use the bricklayer-mcp-docker wrapper script. This script automatically detects the PHP container at runtime:

{
    "mcpServers": {
        "magento-bricklayer": {
            "command": "vendor/inchoo/magento-bricklayer/bin/bricklayer-mcp-docker",
            "args": []
        }
    }
}

The wrapper script:

• Automatically finds the PHP container by matching common patterns (apache-php, php-fpm, magento, web, app)
• Excludes utility containers (phpmyadmin, redis, elasticsearch, varnish, etc.)
• Returns a proper JSON-RPC error if no container is found
• Supports custom Magento root via MAGENTO_ROOT environment variable (defaults to /var/www/html)

This is useful when container names vary between environments or are dynamically generated (e.g., projectname-apache-php-1).

MCP Tools Overview

Bricklayer uses progressive disclosure — 17 essential tools are visible in tools/list while 66 additional tools remain callable and discoverable via search-tools. This reduces token overhead for AI agents. Tools marked with [tier 1] are always visible; all others are tier 2.

Application & Module Tools

• application-info — Magento version, PHP version, deploy mode, module counts. Use include=stores for website/store hierarchy
• module-list — All installed modules with version, status, and vendor
• module-structure — File/folder structure of a module with dependencies
• validate-module — Validates module code structure (registration.php, module.xml, composer.json, strict_types)

Database Tools

• database-schema [tier 1] — Table structures, columns, indexes, foreign keys
• database-query [tier 1] — Execute read-only SELECT queries with automatic LIMIT enforcement

EAV Tools

• eav-attributes [tier 1] — EAV attributes for entity types (catalogproduct, catalogcategory, customer, customer_address)
• eav-entity-types — List all supported EAV entity types

Configuration & DI Tools

• check-class [tier 1] — Combined pre-modification check: returns plugins, DI configuration, and preferences for any class in one call. Essential before writing plugins, preferences, or DI overrides
• configuration-get — Retrieve system configuration values by path (with scope support)
• configuration-list — List available configuration paths by section
• di-configuration [tier 1] — DI configuration showing preferences and plugins for cla

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Inchoo
• Source: Inchoo/magento-bricklayer
• License: MIT

Install and usage instructions live in the source repository linked above.