Repository navigation
Architecture Overview
tvranjes edited this page Aug 14, 2026
·
4 revisions
Magento Bricklayer is a standalone Composer library (not a Magento module) that connects to a Magento installation from outside the module system and exposes its capabilities through the Model Context Protocol (MCP).
┌─────────────────────┐
│ AI Coding Agent │ (Claude Code, Cursor, Copilot, etc.)
│ (MCP Client) │
└─────────┬───────────┘
│ stdin/stdout (MCP Protocol)
┌─────────▼───────────┐
│ Bricklayer MCP │
│ Server │
├──────────────────────┤
│ Tool Registry │ 84 tools, auto-discovered
│ Resource Provider │ Guidelines, Skills, Templates
│ Prompt Provider │ 8 prompts
├──────────────────────┤
│ Config Loader │ 3-tier config with hot reload
│ Bootstrap │ Magento ObjectManager init
│ Area Emulator │ Area code switching
└─────────┬───────────┘
│ ObjectManager / DI
┌─────────▼───────────┐
│ Magento 2 Instance │
│ (Database, Config, │
│ EAV, Modules, etc.)│
└──────────────────────┘
MagentoBootstrap initializes Magento's ObjectManager from outside the module system (following the n98-magerun2 pattern). It handles:
-
Magento root detection via
MagentoDetector - ObjectManager initialization with proper autoloader setup
-
Sentinel file tracking — monitors
app/etc/config.phpandgenerated/metadata/global.phpmtimes for automatic staleness detection and reinitialize -
Area emulation via
AreaEmulator— switches betweenadminhtml,frontend,webapi_rest,graphql, andcrontabareas
ConfigLoader implements a three-tier configuration strategy:
- Built-in defaults — Safe defaults for all 84 tools
-
Project configuration —
.bricklayer.jsonin project root - Environment variables — Highest priority overrides
Features:
-
Hot reload — Detects
.bricklayer.jsonmtime changes and reloads without server restart - Deploy-mode-aware defaults — Production mode blocks destructive tools by default
- Per-tool granular control — Each tool can be individually enabled/disabled
ToolRegistry provides centralized tool management:
-
Auto-discovery via PHP 8.1
#[McpTool]attributes - 21 tool classes organized into 11 groups
-
Progressive disclosure — Tier 1 (17 tools) visible in
tools/list; Tier 2 (67 tools) discoverable viasearch-tools -
Shared traits —
RequiresMagento,ChecksConfig,FiltersFields,ReadsLogFiles
6 resource providers serve documentation and templates:
| Resource | Content |
|---|---|
GuidelinesResource |
33 markdown development guidelines |
SkillsResource |
28 skill guides with code examples, plus focused sub-skills via magento://skills/{name}/{topic}
|
CodingStandardsResource |
PSR-12 and Magento standards |
ReferenceResource |
Event names, DI patterns, ACL |
TemplateResource |
Code templates for scaffolding |
All resources use FileLoaderTrait for auto-discovery from the config/ directory.
src/
├── Application.php # Symfony Console app
├── Bootstrap/
│ ├── MagentoBootstrap.php # ObjectManager init + staleness
│ ├── MagentoDetector.php # Root directory detection
│ └── AreaEmulator.php # Area code switching
├── Command/ # 6 CLI commands
├── Config/
│ ├── ConfigLoader.php # 3-tier config + hot reload
│ ├── ConfigValidator.php # Schema validation
│ ├── ConfigInitializer.php # .bricklayer.json generation
│ └── EnvironmentResolver.php # Docker/DDEV/Warden detection
├── Guidelines/
│ ├── GuidelinesCompiler.php # Compile for agent files
│ └── ToolScanner.php # Auto-discover tools
├── Integration/
│ └── McpConfigWriter.php # Write .mcp.json + agent files
└── Mcp/
├── McpServerFactory.php # MCP server creation
├── Tool/ # 21 tool classes (84 tools)
│ ├── Concern/ # Shared traits
│ ├── Diagnostic/ # Error parsing helpers
│ └── ToolRegistry.php # Central registry
├── Resource/ # 6 resource providers
└── Prompt/ # 8 prompt providers
- Bootstrap Process — Detailed bootstrap flow
- Tool System — Tool registration, groups, and progressive disclosure
- Configuration System — Config loading and validation
Getting Started
Architecture
Tools Reference
- Overview (84 Tools)
- Introspection
- Catalog
- Orders
- Customers
- Database
- Logs & Diagnostics
- GraphQL
- Development
Configuration
Guidelines & Skills
Code Generation
Diagnostics
Security