Magento 2 Coding Standards

An MCP (Model Context Protocol) server that provides comprehensive Magento 2 coding standards knowledge, enabling AI assistants to write Magento-compliant code naturally — vibe coding for Magento.

Works with Claude Code, Claude Desktop, Cursor IDE, VS Code Copilot, Gemini CLI, Continue.dev, Windsurf, Augment Code, and any MCP-compatible client.

---

Why This Exists

Writing Magento 2 code correctly is hard. There are 83+ coding standard rules, 150+ discouraged functions, 50+ restricted classes, theme-specific conventions, and security requirements that developers must follow. AI assistants don't know these rules — they generate code that looks correct but violates Magento standards.

This MCP server teaches AI assistants Magento's rules so they write compliant code from the start:

• Ask for a "jQuery widget" with Hyva theme active → get Alpine.js component instead
• Paste PHP code → get instant validation with line numbers and fix suggestions
• Ask "how to read a file" → get DriverInterface pattern, not file_get_contents()

---

Features

• 83+ Coding Standard Rules — Security, Legacy, PHP, Functions, Templates, LESS/CSS, GraphQL, HTML, Framework, Exceptions, and more
• 150+ Discouraged Functions — Every PHP function Magento wants you to avoid, with the correct replacement
• 50+ Restricted Classes — Zend Framework → Laminas migrations, deprecated class replacements
• 25+ jQuery Deprecations — Deprecated jQuery methods with modern replacements
• 19 LESS/CSS Rules — Frontend styling standards
• 7 MCP Tools — Pattern lookup, code validation, security checking, rule explanations, theme management
• 4 Built-in Theme Presets — Hyva, Luma, Breeze, Porto with full validation rules and pattern overrides
• Custom Theme Support — Add your own theme standards via JSON files
• Multi-Platform — Works with every major AI coding tool

---

Quick Start

1. Clone and Build

git clone https://github.com/Midhun-edv/magento-coding-standard-mcp.git
cd magento-coding-standard-mcp
npm install
npm run build

2. Connect to Your AI Tool

Pick your platform below and add the MCP server:

Claude Code (CLI)

claude mcp add magento-coding-standard -- node /path/to/magento-coding-standard-mcp/dist/index.js

Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "magento-coding-standard": {
      "command": "node",
      "args": ["/path/to/magento-coding-standard-mcp/dist/index.js"]
    }
  }
}

Cursor IDE

Add to .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "magento-coding-standard": {
      "command": "node",
      "args": ["/path/to/magento-coding-standard-mcp/dist/index.js"]
    }
  }
}

VS Code Copilot

Add to .vscode/mcp.json in your project root:

{
  "servers": {
    "magento-coding-standard": {
      "type": "stdio",
      "command": "node",
      "args": ["/path/to/magento-coding-standard-mcp/dist/index.js"]
    }
  }
}

Gemini CLI

Add to ~/.gemini/settings.json:

{
  "mcpServers": {
    "magento-coding-standard": {
      "command": "node",
      "args": ["/path/to/magento-coding-standard-mcp/dist/index.js"]
    }
  }
}

Continue.dev

Add to ~/.continue/config.json:

{
  "mcpServers": [
    {
      "name": "magento-coding-standard",
      "command": "node",
      "args": ["/path/to/magento-coding-standard-mcp/dist/index.js"]
    }
  ]
}

Windsurf

Add to Windsurf MCP settings:

{
  "mcpServers": {
    "magento-coding-standard": {
      "command": "node",
      "args": ["/path/to/magento-coding-standard-mcp/dist/index.js"]
    }
  }
}

Augment Code

Add in Augment Code settings:

{
  "mcpServers": {
    "magento-coding-standard": {
      "command": "node",
      "args": ["/path/to/magento-coding-standard-mcp/dist/index.js"]
    }
  }
}

Note: Replace /path/to/ with your actual installation path. On Windows, use forward slashes: C:/Users/name/magento-coding-standard-mcp/dist/index.js

---

Available Tools

1. get_magento_pattern

Get the correct Magento 2 way to accomplish a task. Returns the proper pattern, code example, what to avoid, and why.

Task: "read a file"
→ Returns: DriverInterface::fileGetContents() with full example, avoidPatterns, explanation

Supported tasks: File operations, Escaping (HTML/URL/JS/CSS), JSON/Serialization, Validation, Templates/ViewModels, HTTP requests, JavaScript (RequireJS, UI Components, Widgets), Translation, Logging, Database queries

When a theme is active, patterns are automatically overridden with theme-specific versions (e.g., "jQuery widget" → Alpine.js component when Hyva is active).

2. validate_code

Validate code against Magento coding standards. Returns violations with severity, line numbers, rule names, and fix suggestions.

Input: { code: "<?php echo $name; ?>", fileType: "phtml" }
→ Returns: XSS violation at line 1, suggestion to use $escaper->escapeHtml()

Supported file types: php, phtml, js, less, css

When a theme is active, theme-specific validation rules are applied on top of base Magento rules.

3. check_security

Security-focused validation checking for:

• XSS vulnerabilities (unescaped output)
• SQL injection risks (raw queries)
• Insecure functions (exec, eval, shell_exec, etc.)
• Superglobal usage ($_GET, $_POST direct access)
• Object injection (serialize/unserialize)

4. explain_rule

Get detailed explanation of any rule with reasoning, bad/good examples, related rules, and documentation links.

Input: { ruleName: "XssTemplate" }
→ Returns: Full explanation with bad code, good code, and related rules

Also supports theme-specific rules (e.g., Hyva.JS.NoJQuery).

5. list_rules

List all rules with optional filtering:

• category: Security, Legacy, PHP, Functions, Templates, Less, GraphQL, etc.
• minSeverity: 1-10 (10 = most critical)
• searchTerm: Search in rule names and descriptions

When a theme is active, theme rules are included in the listing.

6. get_rules_summary

Get a summary of all rules grouped by category with counts of errors and warnings.

7. manage_theme

Manage theme-specific coding standards that layer on top of base Magento rules.

Action	Description	Example
list	Show all available themes	{ action: "list" }
set	Activate a theme	{ action: "set", themeId: "hyva" }
clear	Deactivate theme	{ action: "clear" }
info	Show theme details	{ action: "info", themeId: "hyva" }

---

Theme-Specific Standards

Different Magento themes use completely different frontend stacks. Code that's correct for Luma is wrong for Hyva and vice versa. This MCP supports 4 built-in theme presets and custom themes.

Built-in Presets

Theme	Stack	Rules	Description
hyva	Alpine.js + TailwindCSS	8 rules	No jQuery, No KnockoutJS, No RequireJS, No LESS
luma	jQuery + RequireJS + KnockoutJS + LESS	4 rules	Default Magento 2 frontend stack
breeze	Vanilla JS + Breeze API + LESS	4 rules	Lightweight, no RequireJS
porto	Luma-based + Porto widgets	4 rules	Always use child theme

How Themes Work

1. Activate a theme: The AI calls manage_theme({ action: "set", themeId: "hyva" })
2. Validation is enhanced: validate_code now flags jQuery, RequireJS, KnockoutJS usage as errors
3. Patterns are overridden: get_magento_pattern({ task: "jquery widget" }) returns Alpine.js component instead
4. Rules are extended: list_rules includes Hyva-specific rules like Hyva.JS.NoJQuery

Theme Details

Hyva Theme

• USE: Alpine.js (x-data, x-show, x-on), TailwindCSS, vanilla JS, ViewModelRegistry, $escaper
• AVOID: jQuery $(), KnockoutJS data-bind, RequireJS define()/require(), LESS, data-mage-init
• 5 pattern overrides with full code examples for requirejs modules, jquery widgets, template structure, escaping, UI components

Luma/Blank Theme

• USE: RequireJS AMD, jQuery, KnockoutJS, LESS with Magento UI Library, $.widget(), data-mage-init
• AVOID: Global variables, inline scripts, ES modules, Alpine.js
• 5 pattern overrides for requirejs modules, jquery widgets, UI components, template structure, LESS/CSS

Breeze Theme

• USE: Vanilla JS, Breeze component API ($.widget, $.view), lightweight LESS, fetch() API
• AVOID: RequireJS, heavy jQuery, KnockoutJS, uiComponent
• 3 pattern overrides for requirejs modules, jquery widgets, template structure

Porto Theme

• USE: Luma conventions + Porto widgets, Porto LESS variables, child theme pattern
• AVOID: Modifying core Porto files, hardcoded colors/fonts
• 3 pattern overrides for template structure, LESS/CSS, requirejs modules

Custom Themes

Create your own theme standards by placing JSON files in ~/.magento-mcp/themes/:

{
  "id": "my-theme",
  "name": "My Custom Theme",
  "version": "1.0.0",
  "description": "Custom standards for my project",
  "technologies": {
    "use": ["React", "TailwindCSS"],
    "avoid": ["jQuery"]
  },
  "validationRules": [
    {
      "pattern": "\\$\\(",
      "fileTypes": ["js", "phtml"],
      "severity": 8,
      "type": "warning",
      "message": "jQuery detected. My Theme uses React.",
      "rule": "MyTheme.JS.NoJQuery",
      "suggestion": "Use React components instead",
      "mode": "discourage"
    }
  ],
  "patternOverrides": [],
  "bestPractices": ["Use React for interactive UI"]
}

Override the directory with the MAGENTO_MCP_THEME_DIR environment variable.

See src/themes/custom/README.md for full JSON schema documentation.

---

Knowledge Base Coverage

Category	Count	Examples
Security	8 rules	InsecureFunction, XSS, Superglobal, LanguageConstruct
Legacy	13 rules	Zend to Laminas, Mage::, deprecated configs, ObsoleteConnection
PHP	7 rules	FinalImplementation, Goto, ShortEchoSyntax, ReturnValueCheck
Functions	3 rules	DiscouragedFunction, StaticFunction, DeprecatedWithoutArgument
Templates	2 rules	ThisInTemplate, ObjectManager in templates
Less/CSS	19 rules	AvoidId, Indentation, Colors, ZeroUnits, ImportantProperty
GraphQL	5 rules	ValidTypeName, ValidFieldName, ValidEnumValue
Html	4 rules	SelfClosing, VoidTags, Binding, Directive
Framework	4 rules	Copyright, License headers
Exceptions	3 rules	DirectThrow, ThrowCatch, TryProcessSystemResources
+ more	15+ rules	Annotation, Commenting, Performance, SQL, Translation
Discouraged Functions	150+	file_get_contents, curl_*, mysql_*, die, sleep, compact...
Restricted Classes	50+	Zend_Json, Zend_Db, Zend_Log, Varien_*, Mage_* ...
jQuery Deprecations	25+	$.bind, $.live, $.size, $.isFunction, $.browser...

Severity Levels

Level	Type	Description
10	Error	Critical — security vulnerabilities, forbidden patterns
9	Warning	Security — possible security issues
8	Warning	Magento-specific — design violations
7	Warning	General — code quality issues
6	Warning	Style — formatting issues
5	Warning	Documentation — PHPDoc issues

---

Project Structure

magento-coding-standard-mcp/
  src/
    index.ts                          # MCP server entry point (7 tools)
    cli.ts                            # CLI entry point (--help, --version)
    knowledge/                        # Coding standards knowledge base
      index.ts                        # Central exports + utility functions
      insecure-functions.ts           # Forbidden functions (exec, eval, etc.)
      discouraged-functions.ts        # 150+ discouraged functions
      restricted-classes.ts           # 50+ restricted classes
      xss-escape-methods.ts           # XSS escape methods
      template-patterns.ts            # Template/ViewModel patterns
      jquery-deprecations.ts          # 25+ jQuery deprecations
      severity-rules.ts              # 83+ rules with severity levels
    themes/                           # Theme-specific standards
      types.ts                        # ThemeStandard interfaces
      index.ts                        # Public API
      theme-manager.ts                # Active theme state management
      presets/
        hyva.ts                       # Hyva: Alpine.js + TailwindCSS
        luma.ts                       # Luma: jQuery + RequireJS + LESS
        breeze.ts                     # Breeze: Vanilla JS
        porto.ts                      # Porto: Luma-based + Porto widgets
        index.ts                      # THEME_PRESETS registry
      custom/
        loader.ts                     # Loads user JSON themes
        README.md                     # JSON schema documentation
    tools/                            # MCP tool implementations
      index.ts                        # Tool exports
      get-magento-pattern.ts          # Pattern lookup (theme-aware)
      validate-code.ts                # Code validation (theme-aware)
      check-security.ts               # Security validation
      explain-rule.ts                 # Rule explanations (theme-aware)
      list-rules.ts                   # Rule listing (theme-aware)
      manage-theme.ts                 # Theme management tool
  examples/
    ai-platform-configs.md            # Full config examples for 7 platforms
  dist/                               # Compiled output (generated)
  package.json
  tsconfig.json

---

Development

# Install dependencies
npm install

# Build for production
npm run build

# Run in development mode (with hot reload)
npm run dev

# Start the server
npm start

# CLI help
node dist/cli.js --help

# CLI version
node dist/cli.js --version

Requirements

• Node.js >= 18.0.0
• npm >= 8.0.0

Tech Stack

• TypeScript with ESM modules
• @modelcontextprotocol/sdk for MCP protocol
• zod for input validation
• Zero runtime dependencies beyond MCP SDK and Zod

---

How It Works

1. You connect this MCP server to your AI tool (Claude, Cursor, Gemini, etc.)
2. The AI automatically uses the tools when writing Magento code
3. Before generating code, it calls get_magento_pattern to get the correct approach
4. After generating code, it calls validate_code to check for violations
5. Theme standards layer on top — set your theme once and all suggestions adapt

The AI doesn't need special prompting. The MCP tools are described clearly enough that AI assistants naturally call them when working on Magento projects.

---

Contributing

Contributions are welcome! Areas that could use help:

• Additional theme presets (e.g., Magezon, Amasty, custom frameworks)
• More validation rules for edge cases
• Integration tests
• Performance optimizations for large codebases
• Documentation improvements

Adding a New Theme Preset

1. Create src/themes/presets/my-theme.ts following the ThemeStandard interface
2. Export it from src/themes/presets/index.ts
3. Add to THEME_PRESETS record
4. Run npm run build — zero errors required

---

License

MIT - see LICENSE for details.