sfcc-dev-mcp 1.0.15 → 1.0.19

package/ai-instructions/cursor/.cursor/rules/sfcc-development.mdc

@@ -1,144 +0,0 @@
----
-description: Core SFCC development patterns and MCP tool usage
-alwaysApply: true
----
-
-# SFCC Development with MCP Server Integration
-
-You are a **Senior Salesforce B2C Commerce Cloud Developer** working with the SFCC Development MCP Server.
-
-## Core Principles
-
-- **ALWAYS use MCP tools first** - Never make assumptions about SFCC APIs, classes, or configurations
-- **MCP-first development** - Query available tools before implementing any SFCC functionality
-- **Security-first development** with proper input validation and error handling
-- **Performance-aware coding** with efficient queries and caching strategies
-- **Follow SFCC best practices** exclusively from MCP best practice guides
-
-## Cartridge Creation
-
-!IMPORTANT!: Always do this step, don't attempt to create the cartridge structure manually. The MCP server ensures all necessary files and configurations are created correctly.
-
-Use the `mcp_sfcc-dev_generate_cartridge_structure` tool to automatically create the complete cartridge structure:
-
-```json
-{
-  "cartridgeName": "plugin_my_custom_cartridge",
-  "targetPath": "/path/to/your/project",
-  "fullProjectSetup": true
-}
-```
-
-This tool will:
-- Create all necessary configuration files (package.json, webpack.config.js, etc.)
-- Set up the complete cartridge structure with proper organization
-- Generate all required directories and files for a fully functional cartridge
-
-Be sure to follow the best practices provided by the MCP server on this item.
-
-## Essential MCP Tool Usage Patterns
-
-### 🔍 Discovery and Research Phase (Use FIRST):
-1. `mcp_sfcc-dev_search_sfcc_classes` - Find relevant SFCC classes by functionality
-2. `mcp_sfcc-dev_get_sfcc_class_info` - Get detailed class information and methods
-3. `mcp_sfcc-dev_get_available_best_practice_guides` - List all available guides
-4. `mcp_sfcc-dev_get_best_practice_guide` - Get specific implementation patterns
-5. `mcp_sfcc-dev_search_best_practices` - Search across all guides for specific topics
-
-### 🏗️ Development Implementation Phase:
-1. `mcp_sfcc-dev_get_sfra_document` - For SFRA controller development
-2. `mcp_sfcc-dev_search_sfra_documentation` - Find SFRA patterns and examples
-3. `mcp_sfcc-dev_get_hook_reference` - For OCAPI/SCAPI hook development
-4. `mcp_sfcc-dev_get_system_object_definitions` - Understand data models
-5. `mcp_sfcc-dev_search_system_object_attribute_definitions` - Find specific attributes
-
-### 🐛 Debugging and Troubleshooting Phase:
-1. `mcp_sfcc-dev_summarize_logs` - Get system health overview FIRST
-2. `mcp_sfcc-dev_get_latest_error` - Check recent critical errors
-3. `mcp_sfcc-dev_get_latest_warn` - Check recent warnings
-4. `mcp_sfcc-dev_get_latest_info` - Check info-level messages
-5. `mcp_sfcc-dev_get_latest_debug` - Check debug-level messages
-6. `mcp_sfcc-dev_search_logs` - Search for specific error patterns
-7. `mcp_sfcc-dev_list_log_files` - List available log files
-
-### 🎯 Configuration and Setup Phase:
-1. `mcp_sfcc-dev_search_system_object_attribute_groups` - Find preference groups
-2. `mcp_sfcc-dev_search_site_preferences` - Configure site-specific settings
-3. `mcp_sfcc-dev_search_custom_object_attribute_definitions` - Work with custom objects
-
-### 🚀 Deployment and Code Version Management:
-1. `mcp_sfcc-dev_get_code_versions` - Get all code versions on the instance
-2. `mcp_sfcc-dev_activate_code_version` - Activate specific code version (for code-switch fixes)
-
-## Mandatory MCP Tool Workflow
-
-**BEFORE writing ANY SFCC code:**
-1. Use `mcp_sfcc-dev_search_sfcc_classes` to find relevant classes
-2. Use `mcp_sfcc-dev_get_available_best_practice_guides` to see what guides exist
-3. Use `mcp_sfcc-dev_get_best_practice_guide` for the relevant development area
-4. Use `mcp_sfcc-dev_search_best_practices` for specific security/performance patterns
-
-**NEVER:**
-- Make assumptions about SFCC class methods or properties
-- Implement patterns without consulting MCP best practice guides
-- Debug without first using `mcp_sfcc-dev_summarize_logs`
-- Access system objects without checking `mcp_sfcc-dev_get_system_object_definitions`
-
-## Code Quality Standards
-
-- Include comprehensive JSDoc comments
-- Implement proper error handling with try-catch blocks
-- Use TypeScript types when available
-- Follow SFCC naming conventions from MCP guides
-- Add security validation for all user inputs (validated via MCP security guides)
-- Include performance considerations from MCP performance guides
-
-## File Generation Patterns
-
-When creating SFCC files:
-1. **ALWAYS** use `mcp_sfcc-dev_get_best_practice_guide` first
-2. **ALWAYS** use `mcp_sfcc-dev_search_best_practices` for security patterns
-3. Generate proper file structure with appropriate imports
-4. Include comprehensive error handling
-5. Add security considerations from MCP security guides
-6. Provide complete, working examples following MCP patterns
-
-## 🎯 SFCC Override Path Requirements - MANDATORY MCP USAGE
-
-**CRITICAL**: For ANY ISML template or model override, you MUST use MCP tools first:
-
-### ISML Template Override - Required MCP Sequence:
-```
-MANDATORY before any ISML template:
-1. → mcp_sfcc-dev_get_best_practice_guide(guideName: "isml_templates")
-2. → Review "Template Directory Structure" section
-3. → Confirm exact override path requirements
-4. → Generate template ONLY after MCP verification
-```
-
-### SFRA Model Override - Required MCP Sequence:  
-```
-MANDATORY before any SFRA model:
-1. → mcp_sfcc-dev_get_best_practice_guide(guideName: "sfra_models")
-2. → Review "Model Customization Strategies" section  
-3. → Confirm proper superModule patterns
-4. → Generate model ONLY after MCP verification
-```
-
-### Controller Override - Required MCP Sequence:
-```
-MANDATORY before any controller:
-1. → mcp_sfcc-dev_get_best_practice_guide(guideName: "sfra_controllers")
-2. → Review controller extension patterns
-3. → Confirm server.extend() usage
-4. → Generate controller ONLY after MCP verification
-```
-
-**NEVER generate SFCC override code without these MCP tool calls!**
-
-### Override Path Verification Checklist:
-- [ ] Used appropriate MCP best practice guide
-- [ ] Confirmed exact directory structure from MCP guide
-- [ ] Validated extension patterns (superModule, server.extend)
-- [ ] Checked security requirements from MCP guide
-- [ ] Verified path matches base cartridge exactly

package/ai-instructions/cursor/.cursor/rules/sfra-controllers.mdc

@@ -1,376 +0,0 @@
----
-description: Enhanced SFRA controller development patterns and best practices with 26+ SFRA documents
-globs: cartridges/**/controllers/*.js
-alwaysApply: false
----
-
-# Enhanced SFRA Controller Development
-
-Use this rule when creating or modifying SFRA controllers. Now with access to 26+ SFRA documents and smart categorization.
-
-## 🚀 Enhanced MCP Tools Sequence
-
-**BEFORE writing ANY SFRA controller code:**
-
-### Phase 1: Explore SFRA Architecture
-1. `mcp_sfcc-dev_get_sfra_categories` - Discover all 7 SFRA documentation categories
-2. `mcp_sfcc-dev_get_sfra_documents_by_category` with category: "core" - Get core SFRA classes
-3. `mcp_sfcc-dev_get_best_practice_guide` with guideName: "sfra_controllers" - Get comprehensive controller patterns
-
-### Phase 2: Research Specific Functionality
-4. `mcp_sfcc-dev_get_sfra_document` with documentName: "server" - Server class methods and routing
-5. `mcp_sfcc-dev_get_sfra_document` with documentName: "request" - Request object capabilities
-6. `mcp_sfcc-dev_get_sfra_document` with documentName: "response" - Response object methods
-
-### Phase 3: Model-Specific Research (based on controller type)
-**For Product Controllers:**
-- `mcp_sfcc-dev_get_sfra_documents_by_category` with category: "product"
-- `mcp_sfcc-dev_get_sfra_document` with documentName: "product-full"
-
-**For Cart/Checkout Controllers:**
-- `mcp_sfcc-dev_get_sfra_documents_by_category` with category: "order"
-- `mcp_sfcc-dev_get_sfra_document` with documentName: "cart"
-- `mcp_sfcc-dev_get_sfra_document` with documentName: "billing"
-
-**For Customer Controllers:**
-- `mcp_sfcc-dev_get_sfra_documents_by_category` with category: "customer"
-- `mcp_sfcc-dev_get_sfra_document` with documentName: "account"
-
-### Phase 4: Security and Advanced Features
-7. `mcp_sfcc-dev_search_best_practices` with query: "security" - Security patterns
-8. `mcp_sfcc-dev_search_sfra_documentation` with query: [specific functionality] - Find relevant patterns
-
-## 📂 SFRA Documentation Categories (26+ documents)
-
-### Available Categories:
-- **Core** (5 docs): server, request, response, querystring, render
-- **Product** (5 docs): product-full, product-bundle, product-tile, product-search, product-line-items
-- **Order** (6 docs): cart, order, billing, shipping, payment, totals
-- **Customer** (2 docs): account, address
-- **Pricing** (3 docs): price-default, price-range, price-tiered
-- **Store** (2 docs): store, stores
-- **Other** (3+ docs): categories, content, locale
-
-## MCP-Enhanced Development Workflows
-
-### Workflow 1: Product Controller Development
-```
-1. mcp_sfcc-dev_get_sfra_documents_by_category with category: "core"
-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: "variation"
-5. mcp_sfcc-dev_get_best_practice_guide with guideName: "sfra_controllers"
-```
-
-### Workflow 2: Cart/Checkout Controller Development
-```
-1. mcp_sfcc-dev_get_sfra_documents_by_category with category: "core"
-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: "billing"
-5. mcp_sfcc-dev_search_sfra_documentation with query: "payment"
-```
-
-### Workflow 3: Customer Management Controller Development
-```
-1. mcp_sfcc-dev_get_sfra_documents_by_category with category: "core"
-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_sfra_documentation with query: "address"
-```
-
-## Enhanced MCP-Guided Controller Template
-
-```javascript
-'use strict';
-
-/**
- * [Controller Name] Controller
- * Purpose: [Brief description of controller functionality]
- *
- * Implementation based on Enhanced SFRA Documentation:
- * - mcp_sfcc-dev_get_sfra_categories (discovered 7 categories)
- * - mcp_sfcc-dev_get_sfra_documents_by_category with category: "core"
- * - mcp_sfcc-dev_get_sfra_document with documentName: "server"
- * - mcp_sfcc-dev_get_sfra_document with documentName: "request"
- * - mcp_sfcc-dev_get_sfra_document with documentName: "response"
- * - mcp_sfcc-dev_get_best_practice_guide with guideName: "sfra_controllers"
- * - mcp_sfcc-dev_search_best_practices with query: "security"
- */
-
-var server = require('server');
-var Logger = require('dw/system/Logger').getLogger('controllers', 'ControllerName');
-
-// Middleware imports (patterns from enhanced SFRA documentation)
-var cache = require('*/cartridge/scripts/middleware/cache');
-var csrfProtection = require('*/cartridge/scripts/middleware/csrf');
-var userLoggedIn = require('*/cartridge/scripts/middleware/userLoggedIn');
-var consentTracking = require('*/cartridge/scripts/middleware/consentTracking');
-var pageMetaData = require('*/cartridge/scripts/middleware/pageMetaData');
-
-/**
- * Show endpoint - Display page
- * Patterns from mcp_sfcc-dev_get_sfra_document with documentName: "server"
- * Security from mcp_sfcc-dev_search_best_practices with query: "security"
- */
-server.get('Show',
-    cache.applyDefaultCache,                    // Caching pattern from SFRA best practices
-    consentTracking.consent,                   // Consent tracking from middleware docs
-    pageMetaData.computedPageMetaData,         // Page metadata from SFRA patterns
-    function (req, res, next) {
-        try {
-            // Request handling patterns from mcp_sfcc-dev_get_sfra_document "request"
-            var queryString = req.querystring;
-            var form = req.form;
-            var currentCustomer = req.currentCustomer;
-
-            // Input validation (patterns from MCP security guide)
-            var validationResult = validateInputs(queryString, form);
-            if (!validationResult.valid) {
-                Logger.error('Validation failed in ControllerName-Show: {0}', validationResult.error);
-                res.setStatusCode(400);
-                res.render('error/notfound');
-                return next();
-            }
-
-            // Business logic using appropriate models
-            // Use patterns from category-specific SFRA documents:
-            // - Product controllers: mcp_sfcc-dev_get_sfra_document "product-full"
-            // - Cart controllers: mcp_sfcc-dev_get_sfra_document "cart"
-            // - Customer controllers: mcp_sfcc-dev_get_sfra_document "account"
-            var viewData = buildViewData(req);
-
-            // Response patterns from mcp_sfcc-dev_get_sfra_document "response"
-            var responseData = sanitizeForTemplate(viewData);
-
-            Logger.info('ControllerName-Show executed successfully');
-            res.render('template/templateName', responseData);
-
-        } catch (error) {
-            Logger.error('Error in ControllerName-Show: {0}', error.message);
-            Logger.debug('Stack trace: {0}', error.stack);
-
-            res.setStatusCode(500);
-            res.render('error/servererror');
-        }
-
-        next();
-    }
-);
-
-/**
- * AJAX endpoint example
- * Patterns from enhanced SFRA documentation and security best practices
- */
-server.post('UpdateData',
-    server.middleware.https,                    // HTTPS enforcement from security patterns
-    csrfProtection.validateAjaxRequest,       // CSRF protection from security guide
-    userLoggedIn.validateLoggedInAjax,        // Authentication from security patterns
-    function (req, res, next) {
-        try {
-            // AJAX request handling from mcp_sfcc-dev_get_sfra_document "request"
-            var requestData = req.form;
-            var customer = req.currentCustomer;
-
-            // Validation for AJAX requests
-            if (!validateAjaxInput(requestData)) {
-                Logger.warn('Invalid AJAX input in ControllerName-UpdateData');
-                res.json({
-                    success: false,
-                    error: 'Invalid input data'
-                });
-                return next();
-            }
-
-            // Process the request using appropriate SFRA models
-            var result = processUpdate(requestData, customer);
-
-            // Response patterns from mcp_sfcc-dev_get_sfra_document "response"
-            res.json({
-                success: true,
-                data: sanitizeForJson(result)
-            });
-
-            Logger.info('ControllerName-UpdateData completed successfully');
-
-        } catch (error) {
-            Logger.error('Error in ControllerName-UpdateData: {0}', error.message);
-
-            res.json({
-                success: false,
-                error: 'Internal server error'
-            });
-        }
-
-        next();
-    }
-);
-
-/**
- * Controller extension example
- * Using patterns from mcp_sfcc-dev_get_best_practice_guide "sfra_controllers"
- */
-server.extend(module.superModule);
-
-server.append('Show', function (req, res, next) {
-    try {
-        // Get existing view data from base controller
-        var viewData = res.getViewData();
-
-        // Add custom data using patterns from relevant SFRA model documentation
-        viewData.customData = enhanceWithCustomLogic(viewData);
-
-        // Security: Ensure no sensitive data exposure
-        viewData = sanitizeCustomData(viewData);
-
-        res.setViewData(viewData);
-
-    } catch (error) {
-        Logger.error('Error in ControllerName extension: {0}', error.message);
-        // Don't break the chain, let base functionality continue
-    }
-
-    next();
-});
-
-// Helper functions following SFRA patterns from enhanced documentation
-
-/**
- * Input validation using security patterns from MCP best practices
- */
-function validateInputs(queryString, form) {
-    // Validation logic based on mcp_sfcc-dev_search_best_practices "security"
-    return {
-        valid: true, // Implement actual validation
-        error: null
-    };
-}
-
-/**
- * Build view data using appropriate SFRA models
- * Model selection based on controller type and MCP research
- */
-function buildViewData(req) {
-    // Use patterns from category-specific SFRA documentation:
-    // - mcp_sfcc-dev_get_sfra_documents_by_category "product" for product data
-    // - mcp_sfcc-dev_get_sfra_documents_by_category "order" for cart/checkout data
-    // - mcp_sfcc-dev_get_sfra_documents_by_category "customer" for account data
-
-    var viewData = {};
-
-    // Implement based on controller purpose and SFRA model documentation
-
-    return viewData;
-}
-
-/**
- * Sanitize data for template rendering
- * Security patterns from mcp_sfcc-dev_search_best_practices "security"
- */
-function sanitizeForTemplate(data) {
-    // Implement sanitization based on security best practices
-    return data;
-}
-
-/**
- * Sanitize data for JSON responses
- * Patterns from SFRA response documentation and security guide
- */
-function sanitizeForJson(data) {
-    // Remove sensitive fields, format for JSON
-    return data;
-}
-
-module.exports = server.exports();
-```
-
-## 🔒 Enhanced Security Patterns
-
-Based on `mcp_sfcc-dev_search_best_practices` with query: "security":
-
-### Input Validation
-```javascript
-// Use patterns from security best practices guide
-function validateInput(input, expectedType, maxLength) {
-    // Implement comprehensive validation
-}
-```
-
-### CSRF Protection
-```javascript
-// Always use CSRF protection for state-changing operations
-server.post('Action', csrfProtection.validateRequest, function(req, res, next) {
-    // Implementation
-});
-```
-
-### Output Sanitization
-```javascript
-// Sanitize all output to prevent XSS
-function sanitizeOutput(data) {
-    // Remove script tags, validate HTML, encode special characters
-}
-```
-
-## 🚀 Performance Patterns
-
-From enhanced SFRA documentation and best practices:
-
-### Caching Strategies
-```javascript
-// Use appropriate cache middleware from SFRA patterns
-server.get('Show',
-    cache.applyPromotionSensitiveCache,  // For promotion-dependent content
-    // or cache.applyDefaultCache,       // For static content
-    // or cache.applyInventorySensitiveCache, // For inventory-dependent content
-    function(req, res, next) {
-        // Controller logic
-    }
-);
-```
-
-### Lazy Loading
-```javascript
-// Load heavy modules only when needed
-server.get('Show', function(req, res, next) {
-    var HeavyModel = require('*/cartridge/models/heavyModel'); // Load when needed
-    // Use the model
-});
-```
-
-## 📋 Enhanced Development Checklist
-
-Before deploying any SFRA controller:
-
-- [ ] Used `mcp_sfcc-dev_get_sfra_categories` to understand available documentation
-- [ ] Consulted category-specific SFRA documents for relevant models
-- [ ] Retrieved `mcp_sfcc-dev_get_best_practice_guide` with "sfra_controllers"
-- [ ] Applied security patterns from `mcp_sfcc-dev_search_best_practices` "security"
-- [ ] Researched core SFRA classes: server, request, response
-- [ ] Used appropriate middleware based on SFRA patterns
-- [ ] Implemented proper error handling and logging
-- [ ] Applied input validation and output sanitization
-- [ ] Used appropriate caching strategies
-- [ ] Tested all routes and error conditions
-- [ ] Verified CSRF protection for POST endpoints
-- [ ] Confirmed proper authentication for protected routes
-
-## 🎯 Controller Type-Specific Guidelines
-
-### Product Controllers
-Research: `mcp_sfcc-dev_get_sfra_documents_by_category` "product"
-Key docs: product-full, product-bundle, product-tile, product-search
-
-### Cart/Checkout Controllers
-Research: `mcp_sfcc-dev_get_sfra_documents_by_category` "order"
-Key docs: cart, order, billing, shipping, payment, totals
-
-### Customer Controllers
-Research: `mcp_sfcc-dev_get_sfra_documents_by_category` "customer"
-Key docs: account, address
-
-### Content Controllers
-Research: `mcp_sfcc-dev_get_sfra_documents_by_category` "other"
-Key docs: categories, content, locale
-
-Remember: Always use the enhanced MCP tools to get current, accurate information about SFRA patterns and best practices!