# Magento Bricklayer

> AI-assisted development toolkit for Magento 2. An MCP (Model Context Protocol) server that enables AI coding agents to interact with Magento installations through introspection tools, code generation capabilities, and comprehensive Magento knowledge.

- **Type:** MCP server
- **Install:** `agentstack add mcp-inchoo-magento-bricklayer`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Inchoo](https://agentstack.voostack.com/s/inchoo)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Inchoo](https://github.com/Inchoo)
- **Source:** https://github.com/Inchoo/magento-bricklayer

## Install

```sh
agentstack add mcp-inchoo-magento-bricklayer
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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)

```bash
composer require --dev inchoo/magento-bricklayer
```

### Global Installation

```bash
composer global require inchoo/magento-bricklayer
```

## Quick Start

### 1. Install Agent Configuration

Run from your Magento project root:

```bash
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.

```bash
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.

```bash
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.

```bash
# 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):
```bash
vendor/bin/bricklayer config:set -- tools.database-query.max_rows -1  # will fail validation
```

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

```bash
vendor/bin/bricklayer mcp [options]
```

Options:
- `--magento-root=PATH` - Specify Magento root directory

### inspect
Displays information about the current Magento installation.

```bash
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/`.

```bash
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.

```bash
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:

```bash
# 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:

```json
{
    "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 (catalog_product, catalog_category, 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](https://github.com/Inchoo)
- **Source:** [Inchoo/magento-bricklayer](https://github.com/Inchoo/magento-bricklayer)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-inchoo-magento-bricklayer
- Seller: https://agentstack.voostack.com/s/inchoo
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.