magento2-mcp-module: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

What this module is

Magento 2 implementation of the Model Context Protocol (MCP, spec version 2025-06-18). Ships the transport, auth, ACL, audit, and tool registry — a single POST /mcp endpoint that speaks JSON-RPC 2.0 over HTTP with bearer auth. Domain tools live in satellite modules (Magebit_McpOrderTools, Magebit_McpCatalogTools, Magebit_McpCustomerTools, Magebit_McpCmsTools, Magebit_McpMarketingTools, Magebit_McpTaxTools, Magebit_McpReportTools, Magebit_McpGoogleAnalyticsTools, and Magebit_McpDbTools — the last one ships raw read-only SQL, is off by default, and is the canonical ContextualAclAwareInterface consumer); this repo ships its own set of 19 core system.* tools — store/config info, cache and indexer control, admin notifications, connection identity (system.whoami), scheduled-job diagnostics (system.cron.status), read-only log access (system.log.list / system.log.tail / system.log.grep), and allowlisted config writing (system.config.set).

The repo is checked out as a Magento module at app/code/Magebit/Mcp. The Magento root is /var/www/demo — Composer, bin/magento, and vendor/bin/* all run from there, not from this directory. Read the root README.md for protocol-level detail and client-onboarding snippets — this file complements it with architecture and workflow notes.

Commands

All commands run from the Magento root (/var/www/demo).

# Enable / rebuild after XML or DI changes
bin/magento module:enable Magebit_Mcp
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

# Module-specific CLI
bin/magento magebit:mcp:tools:list            # Every registered tool, ACL, write mode
bin/magento magebit:mcp:tools:validate-acl    # CI gate: tool ACLs must resolve + names must match regex
bin/magento magebit:mcp:token:create --admin-user=<u> --name='<label>'
bin/magento magebit:mcp:token:{list,revoke,delete}
bin/magento magebit:mcp:oauth:client:create --preset=claude_web --allow-all-tools
bin/magento magebit:mcp:oauth:client:{list,rotate-secret,set-status,delete}

# Static analysis — PHPStan level 9 on this module
vendor/bin/phpstan analyse app/code/Magebit/Mcp -c app/code/Magebit/Mcp/phpstan.neon

# Unit tests (module-scoped)
vendor/bin/phpunit -c dev/tests/unit/phpunit.xml.dist app/code/Magebit/Mcp/Test/Unit
# Single test class
vendor/bin/phpunit -c dev/tests/unit/phpunit.xml.dist app/code/Magebit/Mcp/Test/Unit/Model/JsonRpc/DispatcherTest.php
# Single method
vendor/bin/phpunit -c dev/tests/unit/phpunit.xml.dist --filter testDispatchMethodNotFound app/code/Magebit/Mcp/Test/Unit/Model/JsonRpc/DispatcherTest.php