Adobe Commerce Development Tools

MCP server and Cursor rules for Adobe Commerce module development with AI-powered workflow guidance.

Version 1.0.0 | Changelog | Rebuild Summary

🎯 What This Provides

A complete 4-phase structured workflow for Adobe Commerce module development:

1. Cursor IDE Rules (5 files)

• main-orchestrator.mdc - Phase detection, gates, and keyword injection
• workflow-phase1.mdc - Requirements & Planning
• workflow-phase2.mdc - Module Structure & Setup
• workflow-phase3.mdc - Implementation & Development
• workflow-phase4.mdc - Testing & Validation

2. MCP Tools (9 tools organized by phase)

Phase 1: analyze-existing-module, validate-requirements
Phase 2: generate-module-structure, validate-module-structure
Phase 3: generate-component, validate-code-standards
Phase 4: run-unit-tests, run-static-analysis, validate-deployment

⚡ Quick Setup

npm Install

npm install --save-dev @trajendran/commerce-tools-mcp

Configure Cursor IDE

Create .cursor/mcp.json:

{
  "mcpServers": {
    "commerce-tools": {
      "command": "node",
      "args": ["node_modules/@trajendran/commerce-tools-mcp/mcp-server/index.js"]
    }
  }
}

Copy Cursor Rules (Optional)

cp -r node_modules/@trajendran/commerce-tools-mcp/rules/Cursor .cursor/rules

Restart Cursor IDE and you're ready!

🔄 Development Workflow

Phase 1: Requirements & Planning

User: "I need to create a module that adds a custom product attribute"

AI:

1. Creates REQUIREMENTS.md
2. Asks critical questions
3. Uses analyze-existing-module (if reference needed)
4. Uses validate-requirements
5. Marks Phase 1 complete ✅

Phase 2: Module Structure & Setup

User: "Create the module structure"

AI:

1. Uses generate-module-structure
2. Creates registration.php, module.xml, composer.json
3. Creates directory structure
4. Uses validate-module-structure
5. Runs setup:upgrade
6. Marks Phase 2 complete ✅

Phase 3: Implementation & Development

User: "Add the attribute and make it available via GraphQL"

AI:

1. Uses generate-component (setup patch)
2. Uses generate-component (GraphQL resolver)
3. Uses validate-code-standards (after each component)
4. Tests functionality
5. Marks Phase 3 complete ✅

Phase 4: Testing & Validation

User: "Run tests and validate"

AI:

1. Uses run-unit-tests
2. Uses run-static-analysis
3. Uses validate-code-standards
4. Uses validate-deployment
5. Generates report
6. Marks Phase 4 complete ✅ Module Ready!

🛠️ MCP Tools Reference

Phase 1: Requirements & Planning

analyze-existing-module

Analyze existing module to learn patterns.

Usage: "Analyze the Magento_Catalog module structure"

Parameters:

• module_path (required): Path to module (e.g., "vendor/magento/module-catalog")

Returns: Component breakdown, configurations, dependencies, useful patterns

validate-requirements

Validate REQUIREMENTS.md completeness.

Usage: "Validate my requirements document"

Parameters:

• requirements_path (optional): Path to REQUIREMENTS.md (default: "REQUIREMENTS.md")

Returns: Completeness score, missing items, recommendations

Phase 2: Module Structure & Setup

generate-module-structure

Generate complete module skeleton.

Usage: "Generate structure for Acme_CustomFeature"

Parameters:

• module_name (required): Module name (format: Vendor_ModuleName)
• requirements_path (optional): Path to REQUIREMENTS.md

Returns: Created files and directories, next steps

validate-module-structure

Validate module structure correctness.

Usage: "Validate the module structure"

Parameters:

• module_path (required): Path to module (e.g., "app/code/Vendor/Module")

Returns: Validation score, issues found, recommendations

Phase 3: Implementation & Development

generate-component

Generate specific component (Model, Controller, Observer, etc.).

Usage: "Generate a Model called Product"

Parameters:

• module_name (required): Module name
• component_type (required): model, resource_model, collection, repository, controller, observer, plugin, command, graphql_resolver
• component_name (required): Component name
• options (optional): Additional options (event_name, target_class, properties, route)

Returns: Generated code template, configuration, next steps

validate-code-standards

Run PHPCS with Magento2 standard.

Usage: "Check code standards"

Parameters:

• module_path (required): Path to module
• standard (optional): Magento2 (default), PSR2, PSR12
• autofix (optional): Auto-fix violations (default: false)

Returns: Violations found, fix instructions

Phase 4: Testing & Validation

run-unit-tests

Execute PHPUnit tests.

Usage: "Run unit tests"

Parameters:

• module_path (required): Path to module
• coverage (optional): Generate coverage report (default: false)
• specific_test (optional): Run specific test file

Returns: Test results, coverage report location

run-static-analysis

Run PHPStan static analysis.

Usage: "Run static analysis"

Parameters:

• module_path (required): Path to module
• level (optional): PHPStan level 0-9 (default: 6)

Returns: Issues found, fix recommendations

validate-deployment

Comprehensive pre-deployment validation.

Usage: "Validate deployment readiness"

Parameters:

• module_name (required): Module name
• module_path (required): Path to module

Returns: Deployment score, issues, readiness status

📊 Workflow Features

Phase Detection

The main orchestrator automatically detects which phase you're in by checking:

• Phase 1: REQUIREMENTS.md does not exist
• Phase 2: Phase 1 complete, module not created
• Phase 3: Phase 2 complete, implementation in progress
• Phase 4: Phase 3 complete, testing phase

Phase Gates

Non-negotiable transitions enforce quality:

• Gate 1→2: REQUIREMENTS.md must exist with "Phase 1 Complete ✅"
• Gate 2→3: Module structure validated
• Gate 3→4: Implementation complete, code standards pass
• Gate 4→Complete: All tests pass, deployment validated

Conditional Rule Loading

Rules load automatically based on phase keywords:

• Phase 1 keywords → workflow-phase1.mdc loads
• Phase 2 keywords → workflow-phase2.mdc loads
• Phase 3 keywords → workflow-phase3.mdc loads
• Phase 4 keywords → workflow-phase4.mdc loads

💡 Example: Complete Module Development

You: "I need a module that sends order confirmation emails to a third-party CRM"

AI (Phase 1):
- Creates REQUIREMENTS.md
- Asks: Module name? CRM API details? Authentication? Data format?
- Uses analyze-existing-module (to learn from Magento_Email)
- Uses validate-requirements
- Marks Phase 1 complete ✅

You: "Create the module Acme_CrmIntegration"

AI (Phase 2):
- Uses generate-module-structure
- Creates app/code/Acme/CrmIntegration/
- Creates registration.php, module.xml, composer.json
- Uses validate-module-structure
- Runs bin/magento setup:upgrade
- Marks Phase 2 complete ✅

You: "Implement the observer and API client"

AI (Phase 3):
- Uses generate-component (observer: OrderPlaceAfter)
- Uses generate-component (model: ApiClient)
- Implements event subscription in etc/events.xml
- Uses validate-code-standards
- Tests functionality
- Marks Phase 3 complete ✅

You: "Run all quality checks"

AI (Phase 4):
- Uses run-unit-tests (creates/runs tests)
- Uses run-static-analysis
- Uses validate-code-standards
- Uses validate-deployment
- All checks pass ✅
- Marks Phase 4 complete - Module ready for deployment! 🚀

🎓 Best Practices

DO ✅

• Follow the 4-phase workflow
• Let AI create REQUIREMENTS.md first
• Use MCP tools for validation at each phase
• Review generated code
• Run tests frequently
• Don't skip phases

DON'T ❌

• Skip requirements documentation
• Move to next phase without validation
• Generate code in Phase 1
• Skip testing in Phase 4
• Rush through phases

📦 Package Structure

@trajendran/commerce-tools-mcp/
├── mcp-server/              # MCP server
│   ├── index.js            # Entry point
│   └── src/
│       ├── server.js       # Server implementation
│       ├── tools/          # 9 tool handlers
│       ├── schemas/        # 9 JSON schemas
│       └── utils/          # Helper utilities
├── rules/Cursor/           # 5 Cursor IDE rules
│   ├── main-orchestrator.mdc
│   ├── workflow-phase1.mdc
│   ├── workflow-phase2.mdc
│   ├── workflow-phase3.mdc
│   └── workflow-phase4.mdc
├── .cursor/
│   └── mcp.json.example    # Configuration template
├── package.json
├── README.md               # This file
├── CHANGELOG.md            # Version history
└── REBUILD_SUMMARY.md      # Technical overview

🚀 Integration with ToolKit

Use the automated setup script:

cd /path/to/ToolKit
./setup.sh
# Select: 1 (Commerce Local Environment)

This installs Commerce + Docker + MCP + Cursor rules automatically!

📄 License

MIT License - See LICENSE

🔗 Related Projects

• commerce-extensibility-migration-tools - App Builder migration (similar pattern)
• Model Context Protocol - MCP specification
• Cursor IDE - AI-powered code editor

💡 Why This Workflow?

Structured Process

4 clear phases prevent common mistakes and ensure quality.

AI-Guided

Rules guide AI through proper Adobe Commerce development.

Quality Gates

Validation at each phase catches issues early.

Tool-Supported

MCP tools automate repetitive tasks and validations.

Proven Pattern

Based on successful App Builder workflow from commerce-extensibility-migration-tools.

Build better Adobe Commerce modules faster with structured AI-assisted development! 🚀