# Magento 2 Coding Standards MCP Server
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
```bash
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)
```bash
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`
```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:
```json
{
"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:
```json
{
"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`:
```json
{
"mcpServers": {
"magento-coding-standard": {
"command": "node",
"args": ["/path/to/magento-coding-standard-mcp/dist/index.js"]
}
}
}
```
#### Continue.dev
Add to `~/.continue/config.json`:
```json
{
"mcpServers": [
{
"name": "magento-coding-standard",
"command": "node",
"args": ["/path/to/magento-coding-standard-mcp/dist/index.js"]
}
]
}
```
#### Windsurf
Add to Windsurf MCP settings:
```json
{
"mcpServers": {
"magento-coding-standard": {
"command": "node",
"args": ["/path/to/magento-coding-standard-mcp/dist/index.js"]
}
}
}
```
#### Augment Code
Add in Augment Code settings:
```json
{
"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/`:
```json
{
"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](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
```bash
# 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](LICENSE) for details.
