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; } }