SFCC Development MCP Server

Instructions

Implementation Reference

• src/core/tool-definitions.ts:57-70 (schema)

  MCP tool definition including name, description, and input schema for search_sfcc_classes

  {
    name: 'search_sfcc_classes',
    description: "Search for SFCC classes by name or functionality. Use this when you know part of a class name or need to find classes related to specific functionality (e.g., search 'catalog' to find catalog-related classes). Perfect starting point when you're unsure of the exact class name or exploring available APIs for a feature area.",
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: 'Search query for class names. Only use one word at a time (e.g., "catalog", "order", "customer"). Combining multiple words or attempting to look for multiple classes at the same time is not supported.',
        },
      },
      required: ['query'],
    },
  },

• src/tool-configs/docs-tool-config.ts:59-69 (handler)

  Tool handler specification defining validation, defaults, execution (delegates to client.searchClasses), and logging for search_sfcc_classes

  search_sfcc_classes: {
    defaults: (args: ToolArguments) => args,
    validate: (args: ToolArguments, toolName: string) => {
      ValidationHelpers.validateArguments(args, CommonValidations.requiredString('query'), toolName);
    },
    exec: async (args: ToolArguments, context: ToolExecutionContext) => {
      const client = context.docsClient as SFCCDocumentationClient;
      return client.searchClasses(args.query as string);
    },
    logMessage: (args: ToolArguments) => `Search classes ${args.query}`,
  },

• src/core/handlers/docs-handler.ts:9-51 (registration)

  DocsToolHandler class that handles execution dispatch for all documentation tools including search_sfcc_classes using DOCS_TOOL_CONFIG

  export class DocsToolHandler extends BaseToolHandler<DocToolName> {
    private docsClient: SFCCDocumentationClient | null = null;
  
    constructor(context: HandlerContext, subLoggerName: string) {
      super(context, subLoggerName);
    }
  
    protected async onInitialize(): Promise<void> {
      if (!this.docsClient) {
        this.docsClient = new SFCCDocumentationClient();
        this.logger.debug('Documentation client initialized');
      }
    }
  
    protected async onDispose(): Promise<void> {
      this.docsClient = null;
      this.logger.debug('Documentation client disposed');
    }
  
    canHandle(toolName: string): boolean {
      return DOC_TOOL_NAMES_SET.has(toolName as DocToolName);
    }
  
    protected getToolNameSet(): Set<DocToolName> {
      return DOC_TOOL_NAMES_SET;
    }
  
    protected getToolConfig(): Record<string, GenericToolSpec<ToolArguments, any>> {
      return DOCS_TOOL_CONFIG;
    }
  
    protected async createExecutionContext(): Promise<ToolExecutionContext> {
      if (!this.docsClient) {
        throw new Error('Documentation client not initialized');
      }
  
      return {
        handlerContext: this.context,
        logger: this.logger,
        docsClient: this.docsClient,
      };
    }
  }

• src/clients/docs-client.ts:82-101 (helper)

  Core implementation of searchClasses: initializes docs, checks cache, filters and sorts class names matching query (case-insensitive substring), formats names, caches result

  async searchClasses(query: string): Promise<string[]> {
    await this.initialize();
  
    // Check cache first
    const cacheKey = `search:classes:${query.toLowerCase()}`;
    const cachedResult = this.cacheManager.getSearchResults(cacheKey);
    if (cachedResult) {
      return cachedResult;
    }
  
    const lowercaseQuery = query.toLowerCase();
    const results = Array.from(this.classCache.keys())
      .filter(className => className.toLowerCase().includes(lowercaseQuery))
      .sort()
      .map(className => ClassNameResolver.toOfficialFormat(className));
  
    // Cache the results
    this.cacheManager.setSearchResults(cacheKey, results);
    return results;
  }

• src/core/server.ts:98-107 (registration)

  Server instantiation of all tool handlers, including DocsToolHandler for documentation tools like search_sfcc_classes (line 101)

  this.handlers = [
    new LogToolHandler(context, 'Log'),
    new JobLogToolHandler(context, 'JobLog'),
    new DocsToolHandler(context, 'Docs'),
    new BestPracticesToolHandler(context, 'BestPractices'),
    new SFRAToolHandler(context, 'SFRA'),
    new SystemObjectToolHandler(context, 'SystemObjects'),
    new CodeVersionToolHandler(context, 'CodeVersions'),
    new CartridgeToolHandler(context, 'Cartridge'),
  ];