SFCC Development MCP Server

--- description: Enhanced SFRA model development patterns and best practices with 26+ SFRA documents and model architecture guidance globs: cartridges/**/models/*.js alwaysApply: false --- # Enhanced SFRA Model Development Use this rule when creating or modifying SFRA models. Now with access to 26+ SFRA documents, smart categorization, and comprehensive model architecture best practices. ## 🎯 SFRA Model Override Requirements - MANDATORY MCP VERIFICATION **CRITICAL**: For ANY SFRA model override, verify paths and patterns with MCP tools: ### Model Override MCP Workflow: ``` MANDATORY sequence for model overrides: 1. → mcp_sfcc-dev_get_best_practice_guide(guideName: "sfra_models") 2. → Review "Model Customization Strategies" section 3. → Confirm proper superModule usage: var base = module.superModule; 4. → Verify exact override path: cartridge/models/[exact_base_path] 5. → Generate model ONLY after MCP verification ``` ### Model Override Rules from MCP Guide: - **Use module.superModule**: Always import base model with `var base = module.superModule;` - **Extend, Don't Replace**: Call base constructor and extend functionality - **Maintain Interface**: Keep same public API as base model for template compatibility - **Override Complete Path**: Place model in exact same path as base cartridge **NEVER create SFRA model overrides without MCP tool verification!** ## ⚠️ CRITICAL: Decorator Index.js File Warning **DANGER**: Avoid creating `index.js` files in the `decorators` folder. This can accidentally override SFRA's main `index.js` file, causing application failures and unexpected behavior. ### The Problem: - SFRA relies on its core `index.js` file for proper initialization - Adding an `index.js` in decorators can interfere with SFRA's module resolution - Can lead to silent failures that are difficult to debug ### Safe Alternative - Direct Import Pattern: ```javascript 'use strict'; var base = module.superModule; // ✅ SAFE: Import decorator directly var customDecorator = require('*/cartridge/scripts/decorators/customDecorator'); var productDecorator = require('*/cartridge/scripts/decorators/productDecorator'); function CustomProduct(product, options) { base.call(this, product, options); // ✅ Apply decorators directly customDecorator(this); productDecorator(this); } module.exports = CustomProduct; ``` ### What NOT to do: ```javascript // ❌ DANGEROUS: Avoid this pattern var decorators = require('*/cartridge/scripts/decorators'); // Could conflict with SFRA ``` ### Best Practices for Decorators: 1. **Import Explicitly**: Always import specific decorator files by name 2. **Use Full Paths**: Specify complete paths to decorator modules 3. **No Index Files**: Never create `index.js` in decorators folder 4. **Namespace Decorators**: Use descriptive names like `productPriceDecorator.js` ## 🚀 Enhanced MCP Tools Sequence **BEFORE writing ANY SFRA model code:** ### Phase 1: Explore SFRA Model Architecture 1. `mcp_sfcc-dev_get_sfra_categories` - Discover all 7 SFRA documentation categories 2. `mcp_sfcc-dev_get_best_practice_guide` with guideName: "sfra_models" - Get comprehensive model patterns and architecture 3. `mcp_sfcc-dev_get_best_practice_guide` with guideName: "performance" - Performance optimization for models ### Phase 2: Research Core SFRA Components 4. `mcp_sfcc-dev_get_sfra_documents_by_category` with category: "core" - Get core SFRA classes for model integration 5. `mcp_sfcc-dev_get_sfra_document` with documentName: "render" - Template rendering with model data 6. `mcp_sfcc-dev_get_sfra_document` with documentName: "querystring" - URL parameter handling in models ### Phase 3: Model Category-Specific Research (based on model type) **For Product Models:** - `mcp_sfcc-dev_get_sfra_documents_by_category` with category: "product" - `mcp_sfcc-dev_get_sfra_document` with documentName: "product-full" - Complete product model structure - `mcp_sfcc-dev_get_sfra_document` with documentName: "product-bundle" - Bundle product modeling - `mcp_sfcc-dev_get_sfra_document` with documentName: "product-tile" - Lightweight product display models - `mcp_sfcc-dev_search_sfra_documentation` with query: "variation" - Product variation handling **For Cart/Order Models:** - `mcp_sfcc-dev_get_sfra_documents_by_category` with category: "order" - `mcp_sfcc-dev_get_sfra_document` with documentName: "cart" - Cart model architecture - `mcp_sfcc-dev_get_sfra_document` with documentName: "billing" - Billing address models - `mcp_sfcc-dev_get_sfra_document` with documentName: "shipping" - Shipping models and calculations - `mcp_sfcc-dev_get_sfra_document` with documentName: "totals" - Order totals and tax models **For Customer Models:** - `mcp_sfcc-dev_get_sfra_documents_by_category` with category: "customer" - `mcp_sfcc-dev_get_sfra_document` with documentName: "account" - Customer account models - `mcp_sfcc-dev_get_sfra_document` with documentName: "address" - Address model patterns **For Pricing Models:** - `mcp_sfcc-dev_get_sfra_documents_by_category` with category: "pricing" - `mcp_sfcc-dev_get_sfra_document` with documentName: "price-default" - Standard pricing models - `mcp_sfcc-dev_get_sfra_document` with documentName: "price-range" - Price range modeling - `mcp_sfcc-dev_get_sfra_document` with documentName: "price-tiered" - Tiered pricing structures **For Store/Location Models:** - `mcp_sfcc-dev_get_sfra_documents_by_category` with category: "store" - `mcp_sfcc-dev_get_sfra_document` with documentName: "store" - Individual store models - `mcp_sfcc-dev_get_sfra_document` with documentName: "stores" - Store collection models ### Phase 4: Security and Performance 7. `mcp_sfcc-dev_search_best_practices` with query: "security" - Model security patterns 8. `mcp_sfcc-dev_search_best_practices` with query: "performance" - Model performance optimization 9. `mcp_sfcc-dev_search_best_practices` with query: "validation" - Input validation in models 10. `mcp_sfcc-dev_search_sfra_documentation` with query: [specific functionality] - Find relevant model patterns ## 📂 SFRA Model Documentation Categories (26+ documents) ### Available Categories for Model Development: - **Core** (5 docs): server, request, response, querystring, render - Integration patterns - **Product** (5 docs): product-full, product-bundle, product-tile, product-search, product-line-items - Product modeling - **Order** (6 docs): cart, order, billing, shipping, payment, totals - Commerce flow models - **Customer** (2 docs): account, address - Customer data models - **Pricing** (3 docs): price-default, price-range, price-tiered - Pricing logic models - **Store** (2 docs): store, stores - Store/location models - **Other** (3+ docs): categories, content, locale - Supporting models ## MCP-Enhanced Model Development Workflows ### Workflow 1: Product Model Development ``` 1. mcp_sfcc-dev_get_best_practice_guide with guideName: "sfra_models" 2. mcp_sfcc-dev_get_sfra_documents_by_category with category: "product" 3. mcp_sfcc-dev_get_sfra_document with documentName: "product-full" 4. mcp_sfcc-dev_search_sfra_documentation with query: "decorator" 5. mcp_sfcc-dev_search_best_practices with query: "performance" ``` ### Workflow 2: Cart/Order Model Development ``` 1. mcp_sfcc-dev_get_best_practice_guide with guideName: "sfra_models" 2. mcp_sfcc-dev_get_sfra_documents_by_category with category: "order" 3. mcp_sfcc-dev_get_sfra_document with documentName: "cart" 4. mcp_sfcc-dev_get_sfra_document with documentName: "totals" 5. mcp_sfcc-dev_search_best_practices with query: "validation" ``` ### Workflow 3: Customer Account Model Development ``` 1. mcp_sfcc-dev_get_best_practice_guide with guideName: "sfra_models" 2. mcp_sfcc-dev_get_sfra_documents_by_category with category: "customer" 3. mcp_sfcc-dev_get_sfra_document with documentName: "account" 4. mcp_sfcc-dev_search_best_practices with query: "security" ``` ### Workflow 4: Custom Pricing Model Development ``` 1. mcp_sfcc-dev_get_best_practice_guide with guideName: "sfra_models" 2. mcp_sfcc-dev_get_sfra_documents_by_category with category: "pricing" 3. mcp_sfcc-dev_get_sfra_document with documentName: "price-default" 4. mcp_sfcc-dev_search_sfra_documentation with query: "promotion" ``` ## Enhanced MCP-Guided Model Template ```javascript 'use strict'; /** * [Model Name] Model * Purpose: [Brief description of model functionality and data transformation] * * Implementation based on Enhanced SFRA Model Documentation: * - mcp_sfcc-dev_get_best_practice_guide with guideName: "sfra_models" * - mcp_sfcc-dev_get_sfra_categories (discovered 7 categories) * - mcp_sfcc-dev_get_sfra_documents_by_category with category: "[relevant_category]" * - mcp_sfcc-dev_search_best_practices with query: "performance" * - mcp_sfcc-dev_search_best_practices with query: "security" * - mcp_sfcc-dev_search_best_practices with query: "validation" */ var base = module.superModule; /** * Model Constructor * @param {dw.catalog.Product|dw.order.Basket|dw.customer.Customer|Object} sourceObject - Source SFCC API object * @param {Object} options - Configuration options for model transformation * @constructor * * Model Architecture Pattern: * 1. Extend base SFRA model when applicable * 2. Transform SFCC API objects to JSON-ready structures * 3. Apply decorators for additional functionality * 4. Implement caching strategies for performance * 5. Add validation for data integrity */ function [ModelName](sourceObject, options) { base.call(this, sourceObject, options); // Model-specific transformations based on MCP research: // - Followed patterns from mcp_sfcc-dev_get_sfra_document with documentName: "[relevant_document]" // - Applied security patterns from mcp_sfcc-dev_search_best_practices with query: "security" // - Implemented performance optimizations from best practice guide if (sourceObject) { this.transformSourceObject(sourceObject, options); } } /** * Transform source SFCC object to model properties * @param {Object} sourceObject - Source SFCC API object * @param {Object} options - Transformation options * @private */ [ModelName].prototype.transformSourceObject = function (sourceObject, options) { // Implement transformation logic following SFRA model patterns // Pattern discovered from: mcp_sfcc-dev_get_sfra_document with documentName: "[base_model]" // Security consideration: Sanitize sensitive data // Pattern from: mcp_sfcc-dev_search_best_practices with query: "security" // Performance consideration: Lazy load expensive properties // Pattern from: mcp_sfcc-dev_search_best_practices with query: "performance" }; /** * Apply decorators for additional functionality * @param {Array} decorators - Array of decorator functions * @returns {[ModelName]} Enhanced model instance */ [ModelName].prototype.applyDecorators = function (decorators) { // Decorator pattern implementation // Based on research: mcp_sfcc-dev_search_sfra_documentation with query: "decorator" var self = this; decorators.forEach(function (decorator) { if (typeof decorator === 'function') { decorator(self); } }); return this; }; /** * Validate model data integrity * @returns {Object} Validation result with errors array */ [ModelName].prototype.validate = function () { // Validation logic following SFRA patterns // Based on: mcp_sfcc-dev_search_best_practices with query: "validation" var errors = []; // Implement validation rules specific to model type // Pattern from relevant SFRA model documentation return { valid: errors.length === 0, errors: errors }; }; /** * Convert model to JSON-ready object for template rendering * @returns {Object} Plain object suitable for JSON serialization */ [ModelName].prototype.toJSON = function () { // JSON serialization following SFRA patterns // Ensure circular references are handled // Remove functions and private properties var result = {}; // Copy public properties only Object.keys(this).forEach(function (key) { if (key.charAt(0) !== '_' && typeof this[key] !== 'function') { result[key] = this[key]; } }.bind(this)); return result; }; module.exports = [ModelName]; ``` ## SFRA Model Development Best Practices ### 1. Model Architecture Patterns - **Extend Base Models**: Leverage existing SFRA models when possible - **Decorator Pattern**: Use decorators for optional functionality - **Factory Pattern**: Implement factory methods for complex model creation - **Builder Pattern**: Use builders for models with many optional properties ### 2. Performance Optimizations - **Lazy Loading**: Load expensive properties only when needed - **Caching Strategy**: Implement appropriate caching for frequently accessed data - **Batch Operations**: Process multiple items efficiently - **Index-Friendly APIs**: Use SFCC APIs that leverage database indexes ### 3. Security Considerations - **Data Sanitization**: Always sanitize user input - **Sensitive Data Handling**: Never expose passwords or tokens - **Input Validation**: Validate all input parameters - **XSS Prevention**: Escape output for template rendering ### 4. Model Testing Patterns ```javascript // Example test structure for SFRA models describe('[ModelName] Model', function () { it('should transform source object correctly', function () { // Test transformation logic }); it('should validate input properly', function () { // Test validation rules }); it('should apply decorators correctly', function () { // Test decorator application }); it('should serialize to JSON properly', function () { // Test JSON conversion }); }); ``` ## Common Model Implementation Patterns ### Product Model Extension ```javascript // Pattern from: mcp_sfcc-dev_get_sfra_document with documentName: "product-full" function CustomProduct(product, options) { base.call(this, product, options); // Add custom properties this.customAttribute = product.custom.customAttribute; this.calculatedProperty = this.calculateCustomValue(); } ``` ### Cart Model Enhancement ```javascript // Pattern from: mcp_sfcc-dev_get_sfra_document with documentName: "cart" function CustomCart(basket, options) { base.call(this, basket, options); // Add custom totals calculation this.customTotals = this.calculateCustomTotals(basket); this.loyaltyPoints = this.calculateLoyaltyPoints(); } ``` ### Customer Model Customization ```javascript // Pattern from: mcp_sfcc-dev_get_sfra_document with documentName: "account" function CustomAccount(customer, options) { base.call(this, customer, options); // Add customer segment information this.segment = this.determineCustomerSegment(); this.preferences = this.buildPreferenceModel(); } ``` ## Advanced Model Patterns ### 1. Composite Models Combine multiple SFCC objects into a single model for complex views. ### 2. View Models Create specialized models optimized for specific template rendering needs. ### 3. Command Models Implement models that encapsulate business logic and operations. ### 4. Event-Driven Models Models that respond to system events and update accordingly. ## Integration with Controllers ```javascript // Controller integration pattern server.get('Show', function (req, res, next) { // Use MCP-researched model patterns var customModel = new CustomModel(sourceObject, { // Options based on MCP research }); // Apply decorators discovered through MCP tools customModel.applyDecorators(['decorator1', 'decorator2']); res.render('template', { model: customModel }); next(); }); ``` Remember: Always research existing SFRA model patterns using the MCP tools before implementing custom solutions. This ensures consistency with SFRA architecture and leverages proven patterns for optimal performance and maintainability.