SFCC Development MCP Server

Instructions

Implementation Reference

• src/tool-configs/sfra-tool-config.ts:22-32 (handler)

  Handler configuration defining the tool's validation, defaults, execution (calls SFRAClient.getAvailableDocuments()), and logging.

  get_available_sfra_documents: {
    defaults: (args: ToolArguments) => args,
    validate: (_args: ToolArguments, _toolName: string) => {
      // No validation needed for list operation
    },
    exec: async (_args: ToolArguments, context: ToolExecutionContext) => {
      const client = context.sfraClient as SFRAClient;
      return client.getAvailableDocuments();
    },
    logMessage: (_args: ToolArguments) => 'List SFRA docs',
  },

• src/clients/sfra-client.ts:100-160 (helper)

  Core implementation of getAvailableDocuments(): Scans SFRA docs directory for .md files (excluding README.md), extracts metadata for each using getSFRADocumentMetadata, categorizes, sorts (core first), caches, and returns list of document summaries.

  async getAvailableDocuments(): Promise<SFRADocumentSummary[]> {
    const cacheKey = 'sfra:available-documents-v2';
    const cached = this.cache.getSearchResults(cacheKey);
  
    // Check if we need to rescan the filesystem
    const now = Date.now();
    if (cached && (now - this.lastScanTime) < SFRAClient.SCAN_CACHE_TTL) {
      return cached;
    }
  
    try {
      const files = await fs.readdir(this.docsPath);
      const mdFiles = files.filter(file =>
        file.endsWith('.md') &&
        file !== 'README.md' &&
        !file.startsWith('.'),
      );
  
      const documents: SFRADocumentSummary[] = [];
  
      for (const filename of mdFiles) {
        try {
          const documentName = path.basename(filename, '.md');
          const document = await this.getSFRADocumentMetadata(documentName);
  
          if (document) {
            documents.push({
              name: documentName,
              title: document.title,
              description: document.description,
              type: document.type,
              category: document.category,
              filename: document.filename,
            });
          }
        } catch (error) {
          this.logger.error(`Error processing SFRA document ${filename}:`, error);
          // Continue processing other files
        }
      }
  
      // Sort documents by category and then by name
      documents.sort((a, b) => {
        if (a.category !== b.category) {
          // Prioritize core documents
          if (a.category === 'core') {return -1;}
          if (b.category === 'core') {return 1;}
          return a.category.localeCompare(b.category);
        }
        return a.name.localeCompare(b.name);
      });
  
      this.cache.setSearchResults(cacheKey, documents);
      this.lastScanTime = now;
  
      return documents;
    } catch (error) {
      this.logger.error('Error scanning SFRA documents directory:', error);
      return [];
    }
  }

• src/core/tool-definitions.ts:165-172 (schema)

  MCP tool schema: name, detailed description, and inputSchema (empty object, no parameters).

  {
    name: 'get_available_sfra_documents',
    description: 'Get a list of all available SFRA (Storefront Reference Architecture) documentation. Use this to discover what SFRA classes, modules, and models are documented, including Server, Request, Response, QueryString, render module, and comprehensive model documentation for account, cart, products, pricing, billing, shipping, and more. Essential for understanding SFRA architecture and available functionality.',
    inputSchema: {
      type: 'object',
      properties: {},
    },
  },

• src/core/server.ts:118-122 (registration)

  MCP server listTools handler registration: Adds SFRA_DOCUMENTATION_TOOLS array (containing this tool's schema) to the available tools list.

  tools.push(...SFCC_DOCUMENTATION_TOOLS);
  tools.push(...BEST_PRACTICES_TOOLS);
  tools.push(...SFRA_DOCUMENTATION_TOOLS);
  tools.push(...CARTRIDGE_GENERATION_TOOLS);

• src/core/handlers/sfra-handler.ts:13-55 (registration)

  SFRA tool handler class registration: Extends BaseToolHandler, provides SFRA_TOOL_CONFIG for dispatch, initializes SFRAClient, handles SFRA tool names including get_available_sfra_documents.

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