Inchoo/magento-bricklayer: Magento 2용 AI 코딩 에이전트 런타임 가시성 제공 서버

Magento 2에 AI 코딩 에이전트가 런타임 가시성을 확보할 수 있도록 해주는 MCP(Model Context Provider) 서버입니다. 소스 파일을 읽는 에이전트는 전체 그림을 놓치기 쉽습니다. DI preferences, plugin chains, EAV attributes, 그리고 event observers와 같은 요소들은 수십 개의 모듈에 걸쳐 런타임에 해결되기 때문입니다. Bricklayer는 이러한 런타임 상태를 노출하여 에이전트가 추측하는 대신 정보에 기반한 아키텍처 결정을 내릴 수 있도록 합니다.

• Bricklayer란 무엇인가?

• 에이전트가 Bricklayer를 사용하는 방법

• 요구 사항

• 설치

• 빠른 시작

• 지원되는 AI 에이전트

• 사용 가능한 명령어

• Docker / 컨테이너 환경

• MCP 도구 개요

• 애플리케이션 및 모듈 도구

• 데이터베이스 도구

• EAV 도구

• 구성 및 DI 도구

• 라우팅 및 API 도구

• GraphQL 도구

• 뷰 도구

• 메시지 큐 도구

• 카탈로그 도구

• 주문 도구

• 고객 도구

• 개발 도구

• 로그 도구

• 진단 도구

• 코드 실행기 도구

• 코드 생성 도구

• 개발 컨텍스트 도구

• 컨텍스트 인식 힌트

• 페이지네이션

• MCP 리소스

• 구성

• 아키텍처

• 프로젝트 로컬 오버라이드

• Bricklayer 확장하기

• 보안

• 기여

• 라이선스

• 크레딧

Bricklayer는 Magento 2용 MCP 서버를 구현하는 Composer 라이브러리입니다. 시작되면, AI 에이전트가 호출할 수 있는 84개의 도구를 노출하여 다음 작업을 수행하게 합니다:

코드 작성 전 런타임 상태 확인 — 모든 설치된 모듈에 걸친 실제 플러그인 체인, DI 해결(resolution), preferences, 및 event observers를 확인합니다.

• 런타임 시점에 존재하는 데이터베이스 스키마, EAV attributes, 시스템 구성을 검사합니다.
• 전체 컨텍스트로 오류 진단 (예외 + 스택 트레이스 + DI + 플러그인 체인 + 수정 제안)
• 인덱스, 캐시, 크론, 쿼리 패턴 전반의 성능 분석
• Magento의 서비스 계층을 통해 제품, 주문, 고객 관리
• 충돌 감지 기능을 포함하여 Magento 규격에 맞는 모듈 스캐폴딩 생성
• 온디맨드(on demand)로 도메인별 개발 가이드라인 및 코딩 표준 로드

시작 시에는 17개의 필수 도구만 표시되며, 나머지 67개는 search-tools를 통해 발견할 수 있어, 모든 도구를 호출 가능하게 유지하면서 토큰 오버헤드를 줄여줍니다.

이름 'Bricklayer'는 Magento 2 모듈 및 확장 기능을 구축하는 체계적이고 구조화된 접근 방식을 반영합니다. 각 구성 요소(즉, '벽돌')를 올바른 순서와 위치에 배치하여 견고하고 유지보수 가능한 코드베이스를 구축하는 방식입니다.

Magento는 설치된 모든 모듈 전반에서 런타임 시점에 DI 설정 (Dependency Injection configuration), 플러그인 체인 (plugin chains), 선호도 (preferences), 이벤트 옵저버 (event observers) 등을 해결합니다. 소스 파일을 읽는 에이전트는 단지 하나의 모듈 관점만을 볼 수 있습니다. 이로 인해 다른 모듈의 오버라이드(overrides), 충돌(conflicts), 사용자 정의 내용은 놓치게 됩니다. Bricklayer가 이러한 격차를 메워줍니다.

플러그인을 작성하기 전에, 에이전트는 check-class를 호출하여 기존 플러그인과 그들의 정렬 순서 (sortOrders), DI 선호도, 클래스 재작성(class rewrites)을 확인합니다. 이를 통해 더 많은 확장이 설치된 환경에서만 표면화될 충돌을 예방할 수 있습니다.

제품이나 고객을 다루기 전에, 에이전트는 eav-attributes를 호출하여 소스 파일에는 존재하지 않고 데이터베이스에만 존재하는 사용자 정의 속성(custom attributes)을 발견합니다.

디버깅할 때, 에이전트는 diagnose-error를 호출합니다. 이는 예외 로그 (exception log), 스택 추적 (stack trace), DI 컨텍스트, 플러그인 체인 분석을 단일하고 실행 가능한 진단으로 결합하며, 단순히 var/log/exception.log만 읽는 것보다 훨씬 뛰어납니다.

어떤 코드를 작성하기 전에, 에이전트는 development-context를 호출하여 도메인별 지침(plugin 패턴, EAV 모범 사례, Hyvä 체크아웃 API 등)을 로드합니다. 이를 통해 생성된 코드가 Magento의 컨벤션을 따르도록 보장합니다.

각 도구 응답에는 다음 논리적 단계로 이어지는 힌트가 포함됩니다. 즉, 인트로스펙션(introspection) 도구는 로드할 관련 지침을 제안하고, 지침은 수행할 런타임 검사를 제안합니다. 이는 자연스러운 워크플로우를 만듭니다: 확인 (check) → 학습 (learn) → 작성 (write).

• PHP 8.3 이상
• Magento 2.4.7 이상
• Composer 2.2 이상

composer require --dev inchoo/magento-bricklayer

composer global require inchoo/magento-bricklayer

Magento 프로젝트 루트에서 실행:

vendor/bin/bricklayer install

이 명령어는 어떤 AI 에이전트를 구성할지 선택하도록 요청하고 다음 파일을 생성합니다:

.mcp.json

• MCP 서버 구성 (항상 생성됨): .bricklayer.json

• 배포 모드 인식 기본값을 사용한 도구 안전성 구성 - 선택한 에이전트에 기반한 가이드라인 파일 (예: CLAUDE.md, .cursorrules)

MCP 서버는 호환되는 에이전트에 의해 자동으로 시작됩니다. 이제 여러분의 에이전트는 다음을 수행할 수 있습니다:

• application-info를 사용하여 Magento 설치 정보를 파악 - module-list를 사용하여 설치된 모듈 확인 - database-schema를 사용하여 테이블 구조 검사 - 데이터 접근을 위해 product-get, order-get, customer-get 사용 - 전체 컨텍스트와 수정 제안으로 오류 진단: diagnose-error 사용 - 작업에 대한 코딩 가이드라인 로드: development-context 사용 - 그리고 포괄적인 Magento 개발을 위한 훨씬 더 많은 도구들

¹ 프로젝트 범위의 .codex/config.toml은 최신 Codex CLI 릴리스가 필요하며, Codex에서 프로젝트를 신뢰로 표시한 후에만 로드됩니다.

AI 도구를 위한 에이전트 구성 파일을 생성합니다.

vendor/bin/bricklayer install [옵션]

옵션:

--magento-root=PATH

• Magento 루트 디렉터리 지정 (기본적으로 자동 감지)
  --agents=AGENT
• 구성할 에이전트; 여러 개일 경우 플래그 반복 (예: --agents=claude-code --agents=cursor). 유효 값: claude-code, cursor, phpstorm, copilot, gemini, codex, mistral-vibe. 생략하면 대화형으로 선택합니다.
  --force
• 기존 구성 파일 덮어쓰기

배포 모드 인식 기본값을 가진 .bricklayer.json 구성 파일을 생성합니다.

vendor/bin/bricklayer init [옵션]

옵션:

--magento-root=PATH

• Magento 루트 디렉터리 지정 (기본적으로 자동 감지)
  --force
• 기존 .bricklayer.json 덮어쓰기

생성된 설정 파일에는 런타임 구성 가능한 도구당 하나의 항목이 포함됩니다 (작성 시점 기준 36개 도구). 이 목록은 소스에서 requireToolEnabled() 호출 지점을 스캔하여 발견되므로, 파일에 있는 모든 키는 런타임이 실제로 인식하는 값이며 — 사장된 키도, 드리프트 현상도 없습니다.

배포 모드 동작:

production — 12개 도구 비활성화 (code-runner + 모든 11개의 파괴적/코드 생성 도구), database-query.max_rows는 50으로 낮아짐
developer/default — 기본적으로 11개 파괴적 도구 (*-delete, order-cancel, order-create, creditmemo-create, 4개의 generate-*) 비활성화, 나머지 모든 것은 활성화됨, code-runner는 읽기 전용

이 명령어는 bricklayer install 중에도 자동으로 호출됩니다. 또한, 파일이 누락된 경우 bricklayer verify가 자동으로 이 파일을 생성합니다.

.bricklayer.json의 단일 값을 전체 유효성 검사, 왕복 확인(round-trip verification), 그리고 발견 용이성을 위한 안내형 대화형 모드를 통해 업데이트할 수 있습니다.

# 대화형 (Interactive) — 도구 선택, 설정 및 값에 대해 단계별로 안내합니다
vendor/bin/bricklayer config:set
# 스크립트 방식 (Scripted) — 점 표기법(dot-notation) 키 + 값
...

옵션:

--magento-root=PATH
— Magento 루트 디렉터리 지정 (기본적으로 자동 감지)

대화형 모드 (인수 없음)는 초보자에게 권장되는 경로입니다. 이 모드는 36개 런타임 구성 가능 도구와 현재 값을 인라인으로 나열하고, 도구를 선택하고, 설정(여러 개가 사용 가능한 경우)을 선택하며, 타입 인식 유효성 검사(bool 선택기, 비숫자 입력 시 재요청하는 int 검증기)를 통해 새 값을 입력할 수 있게 해줍니다.

스크립트 방식 (위치 인수)은 자동화를 위한 것입니다. 값들은 자동으로 구문 분석됩니다: true/false → bool, null → null, 숫자 → int/float, [...]/{...} → JSON 디코딩, 그 외 모든 것 → string.

성공적으로 설정할 때마다 안전 검사가 수행됩니다.

Validation — 결과 설정이 실패할 경우 쓰기를 거부합니다 (ConfigValidator)

(예: 음수 값의 max_rows, 불리언 값이 아닌 enabled)

Round-trip verification — ConfigLoader를 통해 파일을 다시 로드하고, 새 값이 읽을 수 있는지 확인합니다.

Non-configurable tool warning — 런타임에 해당 플래그를 인식하지 않는 읽기 전용 인트로스펙션 도구에서 enabled를 설정하려고 할 때 경고합니다.

Environment-variable shadow warning — 파일 변경 사항을 덮어쓸 수 있는 일치하는 BRICKLAYER_* 환경 변수가 설정되어 있을 경우 경고합니다.

Hot-reload note — 실행 중인 MCP 서버는 다음 도구 호출에서 변경 사항을 가져오므로, 에이전트 재시작이 필요하지 않다는 점을 알려드립니다.

파일이 누락된 경우 배포 모드 인식 기본값으로 .bricklayer.json 파일을 자동 생성합니다.

음수 정수 값은 -- 구분 기호가 필요합니다 (표준 Symfony Console 동작):

vendor/bin/bricklayer config:set -- tools.database-query.max_rows -1 # 유효성 검사 실패할 것임

MCP 서버를 시작합니다 (AI 에이전트에 의해 자동으로 호출됨).

vendor/bin/bricklayer mcp [옵션]

옵션:

--magento-root=PATH

• Magento 루트 디렉터리를 지정합니다.

현재 Magento 설치에 대한 정보를 표시합니다.

vendor/bin/bricklayer inspect [옵션]

옵션:

--json

• 형식화된 테이블 대신 JSON으로 출력합니다.
  --no-bootstrap
• 전체 Magento 부트스트랩을 건너뜁니다 (더 빠르고, 정보가 제한적입니다).

현재 번들링된 콘텐츠와 .bricklayer/ 내의 프로젝트 로컬 오버라이드를 포함하여 에이전트 설정 파일을 재생성합니다 (CLAUDE.md, .cursorrules 등).

`.

vendor/bin/bricklayer update [옵션]

옵션:

--magento-root=PATH

• Magento 루트 디렉터리를 지정합니다 (기본값으로 자동 감지됨).

프로젝트에 .bricklayer/ 아래 파일이 있는 경우 (프로젝트 로컬 오버라이드 참조), 이 명령어는 재생성된 에이전트 파일과 함께 적용된 로컬 파일을 보고합니다.

Bricklayer 설치에 대한 사후 설치 상태 검사를 실행합니다.

vendor/bin/bricklayer verify [옵션]

옵션:

--magento-root=PATH

• Magento 루트 디렉터리를 지정합니다 (기본값으로 자동 감지됨)
  --json

• 수행된 검사: Magento 부트스트랩, 배포 모드 감지, MCP 서버 생성 및 도구 개수, 에이전트 설정 파일, code-runner를 위한 PsySH 사용 가능 여부, 데이터베이스 연결성, 로그 디렉터리 쓰기 권한, 그리고 .bricklayer.json 유효성 검사.

만약 .bricklayer.json이 누락된 경우, verify가 배포 모드 인식 기본값으로 이를 자동 생성합니다.

Bricklayer는 Docker, DDEV, Warden 환경을 자동으로 감지합니다:

# 설치 명령어는 적절한 설정을 생성합니다
vendor/bin/bricklayer install
# Docker Compose의 경우, 다음을 생성합니다:
...

동적 또는 비표준 컨테이너 이름을 가진 Docker 환경에서는 bricklayer-mcp-docker 래퍼 스크립트를 사용하십시오. 이 스크립트는 런타임에 PHP 컨테이너를 자동으로 감지합니다:

{
"mcpServers": {
"magento-bricklayer": {
...

이 래퍼 스크립트의 기능:

• 일반적인 패턴(apache-php, php-fpm, magento, web, app)을 일치시켜 PHP 컨테이너를 자동으로 찾음
• 유틸리티 컨테이너(phpmyadmin, redis, elasticsearch, varnish 등)는 제외함
• 컨테이너를 찾지 못하면 적절한 JSON-RPC 오류를 반환함
• MAGENTO_ROOT 환경 변수(기본값: /var/www/html)를 통해 사용자 지정 Magento 루트 지원

이는 컨테이너 이름이 환경별로 다르거나 동적으로 생성되는 경우(예: projectname-apache-php-1) 유용합니다.

Bricklayer는 점진적 공개(progressive disclosure) 방식을 사용합니다. 17개의 필수 도구는 tools/list에서 보이고, 나머지 67개의 추가 도구는 search-tools를 통해 호출 및 발견할 수 있습니다. 이는 AI 에이전트의 토큰 오버헤드를 줄여줍니다. **[tier 1]**로 표시된 도구는 항상 보이게 설정되며, 나머지는 tier 2입니다.

application-info — Magento 버전, PHP 버전, 배포 모드, 모듈 개수.
include=stores를 사용하면 웹사이트/스토어 계층 구조가 포함됩니다.
module-list — 버전, 상태 및 공급업체와 함께 설치된 모든 모듈
module-structure — 종속성을 가진 모듈의 파일/폴더 구조
validate-module

— 모듈 코드 구조 유효성 검사 (registration.php, module.xml, composer.json, strict_types)

database-schema

[tier 1]— 테이블 구조, 컬럼, 인덱스, 외래 키(database-query)

[tier 1]— 자동 LIMIT 적용을 통한 읽기 전용 SELECT 쿼리 실행

eav-attributes

[tier 1]— 엔티티 유형(catalog_product, catalog_category, customer, customer_address)에 대한 EAV 속성(eav-entity-types)

— 지원되는 모든 EAV 엔티티 유형 목록 조회

check-class

[tier 1]— 결합된 사전 수정 확인: 플러그인, DI 설정 및 선호도를 단일 호출로 반환합니다. 플러그인, 선호도 또는 DI 오버라이드를 작성하기 전에 필수적입니다(configuration-get)