SFCC Development MCP Server

Instructions

Implementation Reference

• src/tool-configs/sfra-tool-config.ts:34-48 (handler)

  The handler configuration for the 'get_sfra_document' tool, including defaults, input validation (requires 'documentName' string), execution logic that fetches the document via SFRAClient and throws if not found, and logging message.

  get_sfra_document: {
    defaults: (args: ToolArguments) => args,
    validate: (args: ToolArguments, toolName: string) => {
      ValidationHelpers.validateArguments(args, CommonValidations.requiredString('documentName'), toolName);
    },
    exec: async (args: ToolArguments, context: ToolExecutionContext) => {
      const client = context.sfraClient as SFRAClient;
      const result = await client.getSFRADocument(args.documentName as string);
      if (!result) {
        throw new Error(`SFRA document "${args.documentName}" not found`);
      }
      return result;
    },
    logMessage: (args: ToolArguments) => `SFRA doc ${args.documentName}`,
  },

• src/core/tool-definitions.ts:173-186 (schema)

  The tool schema definition including name, description, and inputSchema requiring 'documentName' as a string.

  {
    name: 'get_sfra_document',
    description: 'Get complete SFRA class, module, or model documentation with detailed information about properties, methods, and usage examples. Use this when working with SFRA controllers, middleware, models, or when you need to understand how SFRA components work together. Perfect for implementing SFRA-based features. Now supports all 26+ SFRA documents including core classes, product models, order/cart models, customer models, pricing models, and more.',
    inputSchema: {
      type: 'object',
      properties: {
        documentName: {
          type: 'string',
          description: 'The SFRA document name (e.g., \'server\', \'request\', \'response\', \'querystring\', \'render\', \'cart\', \'product-full\', \'account\', \'billing\', \'shipping\', etc.). Use get_available_sfra_documents to see all available options.',
        },
      },
      required: ['documentName'],
    },
  },

• src/clients/sfra-client.ts:240-272 (helper)

  The core helper method getSFRADocument that loads the SFRA document from filesystem, uses caching, path validation, and falls back to metadata if full content fails. Called by the tool handler.

  async getSFRADocument(documentName: string): Promise<SFRADocument | null> {
    // Normalize document name for consistent lookup
    const normalizedDocumentName = documentName.toLowerCase();
  
    // First try to get from metadata cache
    const metadata = await this.getSFRADocumentMetadata(documentName);
    if (!metadata) {
      return null;
    }
  
    // If the content is already loaded, return it
    if (metadata.content?.trim()) {
      return metadata;
    }
  
    // Otherwise, load the full content
    try {
      const filePath = await this.validateAndConstructPath(documentName);
      const content = await fs.readFile(filePath, 'utf-8');
  
      const fullDocument: SFRADocument = {
        ...metadata,
        content,
      };
  
      // Update cache using normalized name
      this.documentsCache.set(normalizedDocumentName, fullDocument);
      return fullDocument;
    } catch (error) {
      this.logger.error(`Error loading full SFRA document ${normalizedDocumentName}:`, error);
      return metadata; // Return metadata even if content loading failed
    }
  }

• src/clients/sfra-client.ts:165-235 (helper)

  Private helper method getSFRADocumentMetadata that extracts metadata (title, description, sections, type, category, properties, methods) from the markdown file, with caching and parsing logic.

  private async getSFRADocumentMetadata(documentName: string): Promise<SFRADocument | null> {
    // Normalize document name for consistent caching and lookup
    const normalizedDocumentName = documentName.toLowerCase();
  
    // Check if we already have this document cached
    if (this.documentsCache.has(normalizedDocumentName)) {
      return this.documentsCache.get(normalizedDocumentName)!;
    }
  
    try {
      const filePath = await this.validateAndConstructPath(documentName);
      const stats = await fs.stat(filePath);
  
      // Check if we have a cached version that's still valid
      const cacheKey = `sfra:metadata:${normalizedDocumentName}`;
      const cached = this.cache.getFileContent(cacheKey);
      if (cached) {
        const cachedData = JSON.parse(cached);
        if (cachedData.lastModified && new Date(cachedData.lastModified) >= stats.mtime) {
          return cachedData;
        }
      }
  
      // Read only the first part of the file to extract metadata
      const content = await fs.readFile(filePath, 'utf-8');
      const lines = content.split('\n');
  
      // Extract title
      const titleLine = lines.find(line => line.startsWith('#'));
      const title = titleLine?.replace(/^#+\s*/, '').trim() ?? this.formatDocumentName(normalizedDocumentName);
  
      // Determine type based on title and content
      const type = this.determineDocumentType(title, content);
  
      // Determine category - use normalized name for consistent mapping
      const category = (CATEGORY_MAPPINGS[normalizedDocumentName] || 'other') as SFRADocument['category'];
  
      // Extract description (first substantial paragraph after title)
      const description = this.extractDescription(lines, title);
  
      // Extract sections (## headers)
      const sections = lines
        .filter(line => line.startsWith('##'))
        .map(line => line.replace(/^##\s*/, '').trim())
        .filter(section => section.length > 0);
  
      const document: SFRADocument = {
        title,
        description,
        sections,
        content, // Keep full content for now, optimize later if needed
        type,
        category,
        filename: `${normalizedDocumentName}.md`,
        lastModified: stats.mtime,
        ...(type === 'class' || type === 'model' ? {
          properties: this.extractProperties(lines),
          methods: this.extractMethods(lines),
        } : {}),
      };
  
      // Cache the metadata using normalized name
      this.cache.setFileContent(cacheKey, JSON.stringify(document));
      this.documentsCache.set(normalizedDocumentName, document);
  
      return document;
    } catch (error) {
      this.logger.error(`Error loading SFRA document metadata ${normalizedDocumentName}:`, error);
      return null;
    }
  }