SFCC Development MCP Server

Instructions

Implementation Reference

• src/tool-configs/best-practices-tool-config.ts:21-31 (handler)

  Handler configuration defining the exec function for 'get_available_best_practice_guides' which delegates to SFCCBestPracticesClient.getAvailableGuides()

  get_available_best_practice_guides: {
    defaults: (args: ToolArguments) => args,
    validate: (_args: ToolArguments, _toolName: string) => {
      // No validation needed for list operation
    },
    exec: async (_args: ToolArguments, context: ToolExecutionContext) => {
      const client = context.bestPracticesClient as SFCCBestPracticesClient;
      return client.getAvailableGuides();
    },
    logMessage: (_args: ToolArguments) => 'List guides',
  },

• src/core/tool-definitions.ts:110-117 (schema)

  Tool schema definition including name, description, and empty input schema (no parameters required)

  {
    name: 'get_available_best_practice_guides',
    description: 'Get a list of all available SFCC best practice and how-to guides. Use this first to discover what guidance is available before implementing any SFCC features. Essential for understanding what best practice resources exist for cartridge creation, hooks, controllers, and custom endpoints',
    inputSchema: {
      type: 'object',
      properties: {},
    },
  },

• src/clients/best-practices-client.ts:39-114 (helper)

  Core implementation of getAvailableGuides() in SFCCBestPracticesClient, returning a hardcoded list of available best practice guides with caching

  async getAvailableGuides(): Promise<Array<{name: string; title: string; description: string}>> {
    const cacheKey = 'best-practices:available-guides';
    const cached = this.cache.getSearchResults(cacheKey);
    if (cached) {return cached;}
  
    const guides = [
      {
        name: 'cartridge_creation',
        title: 'Cartridge Creation Best Practices',
        description: 'Instructions and best practices for creating, configuring, and deploying custom SFRA cartridges',
      },
      {
        name: 'isml_templates',
        title: 'ISML Templates Best Practices',
        description: 'Comprehensive best practices for developing ISML templates within the SFRA framework, including security, performance, and maintainability guidelines',
      },
      {
        name: 'job_framework',
        title: 'Job Framework Best Practices',
        description: 'Comprehensive guide for developing custom jobs in the SFCC Job Framework, covering both task-oriented and chunk-oriented approaches with performance optimization and debugging strategies',
      },
      {
        name: 'localserviceregistry',
        title: 'LocalServiceRegistry Best Practices',
        description: 'Comprehensive guide for creating server-to-server integrations in SFCC using dw.svc.LocalServiceRegistry, including configuration patterns, callback implementation, OAuth flows, and reusable service module patterns',
      },
      {
        name: 'ocapi_hooks',
        title: 'OCAPI Hooks Best Practices',
        description: 'Best practices for implementing OCAPI hooks in Salesforce B2C Commerce Cloud',
      },
      {
        name: 'scapi_hooks',
        title: 'SCAPI Hooks Best Practices',
        description: 'Essential best practices for implementing SCAPI hooks with AI development assistance',
      },
      {
        name: 'scapi_custom_endpoint',
        title: 'Custom SCAPI Endpoint Best Practices',
        description: 'Best practices for creating custom SCAPI endpoints in B2C Commerce Cloud',
      },
      {
        name: 'sfra_controllers',
        title: 'SFRA Controllers Best Practices',
        description: 'Best practices and code patterns for developing SFRA controllers',
      },
      {
        name: 'sfra_models',
        title: 'SFRA Models Best Practices',
        description: 'Best practices for developing SFRA models in Salesforce B2C Commerce Cloud',
      },
      {
        name: 'sfra_client_side_js',
        title: 'SFRA Client-Side JavaScript Best Practices',
        description: 'Comprehensive patterns for architecting, extending, validating, and optimizing client-side JavaScript in SFRA storefronts using jQuery',
      },
      {
        name: 'sfra_scss',
        title: 'SFRA SCSS Best Practices',
        description: 'Implementation-focused SCSS override strategies for SFRA storefronts covering cartridge overlays, theming tokens, responsive mixins, and plugin extension guardrails',
      },
      {
        name: 'performance',
        title: 'Performance and Stability Best Practices',
        description: 'Comprehensive performance optimization strategies, coding standards, and stability guidelines for SFCC development including caching, index-friendly APIs, and job development',
      },
      {
        name: 'security',
        title: 'Security Best Practices',
        description: 'Comprehensive security best practices for SFCC development covering SFRA Controllers, OCAPI/SCAPI Hooks, and Custom SCAPI Endpoints with OWASP compliance guidelines',
      },
    ];
  
    this.cache.setSearchResults(cacheKey, guides);
    return guides;
  }

• src/core/handlers/best-practices-handler.ts:9-55 (registration)

  BestPracticesToolHandler registers all best practices tools including 'get_available_best_practice_guides' by checking tool names and providing the tool config and client context for execution

  /**
   * Handler for SFCC best practices tools using config-driven dispatch
   * Provides access to development guides, security recommendations, and hook references
   */
  export class BestPracticesToolHandler extends BaseToolHandler<BestPracticeToolName> {
    private bestPracticesClient: SFCCBestPracticesClient | null = null;
  
    constructor(context: HandlerContext, subLoggerName: string) {
      super(context, subLoggerName);
    }
  
    protected async onInitialize(): Promise<void> {
      if (!this.bestPracticesClient) {
        this.bestPracticesClient = new SFCCBestPracticesClient();
        this.logger.debug('Best practices client initialized');
      }
    }
  
    protected async onDispose(): Promise<void> {
      this.bestPracticesClient = null;
      this.logger.debug('Best practices client disposed');
    }
  
    canHandle(toolName: string): boolean {
      return BEST_PRACTICE_TOOL_NAMES_SET.has(toolName as BestPracticeToolName);
    }
  
    protected getToolNameSet(): Set<BestPracticeToolName> {
      return BEST_PRACTICE_TOOL_NAMES_SET;
    }
  
    protected getToolConfig(): Record<string, GenericToolSpec<ToolArguments, any>> {
      return BEST_PRACTICES_TOOL_CONFIG;
    }
  
    protected async createExecutionContext(): Promise<ToolExecutionContext> {
      if (!this.bestPracticesClient) {
        throw new Error('Best practices client not initialized');
      }
  
      return {
        handlerContext: this.context,
        logger: this.logger,
        bestPracticesClient: this.bestPracticesClient,
      };
    }
  }