SFCC Development MCP Server

Instructions

Implementation Reference

• src/clients/sfra-client.ts:277-374 (handler)

  Core handler implementing the search logic: loads all SFRA docs, searches content line-by-line, computes relevance scores based on title/desc/matches, extracts contexts around matches, sorts by relevance.

  async searchSFRADocumentation(query: string): Promise<Array<{
    document: string;
    title: string;
    category: string;
    type: string;
    relevanceScore: number;
    matches: Array<{section: string; content: string; lineNumber: number}>;
  }>> {
    const cacheKey = `sfra:search:${query.toLowerCase()}`;
    const cached = this.cache.getSearchResults(cacheKey);
    if (cached) {return cached;}
  
    const documents = await this.getAvailableDocuments();
    const results = [];
    const queryLower = query.toLowerCase();
    const queryWords = queryLower.split(/\s+/).filter(word => word.length > 1);
  
    for (const doc of documents) {
      const documentContent = await this.getSFRADocument(doc.name);
      if (!documentContent) {continue;}
  
      const matches = [];
      const lines = documentContent.content.split('\n');
      let currentSection = '';
      let relevanceScore = 0;
  
      // Calculate relevance score based on title and description matches
      if (doc.title.toLowerCase().includes(queryLower)) {
        relevanceScore += 10;
      }
      if (doc.description.toLowerCase().includes(queryLower)) {
        relevanceScore += 5;
      }
  
      // Search through content
      for (let i = 0; i < lines.length; i++) {
        const line = lines[i];
        const lineLower = line.toLowerCase();
  
        if (line.startsWith('##')) {
          currentSection = line.replace(/^##\s*/, '').trim();
        }
  
        // Check for query matches
        let matchFound = false;
        let lineRelevance = 0;
  
        if (lineLower.includes(queryLower)) {
          matchFound = true;
          lineRelevance += 3;
        } else {
          // Check for partial matches with query words
          const wordMatches = queryWords.filter(word => lineLower.includes(word));
          if (wordMatches.length > 0) {
            matchFound = true;
            lineRelevance += wordMatches.length;
          }
        }
  
        if (matchFound) {
          // Get context around the match
          const contextStart = Math.max(0, i - 2);
          const contextEnd = Math.min(lines.length, i + 3);
          const context = lines.slice(contextStart, contextEnd)
            .map((contextLine, idx) => {
              const actualLineNumber = contextStart + idx;
              return actualLineNumber === i ? `>>> ${contextLine}` : contextLine;
            })
            .join('\n');
  
          matches.push({
            section: currentSection || 'Introduction',
            content: context,
            lineNumber: i + 1,
          });
  
          relevanceScore += lineRelevance;
        }
      }
  
      if (matches.length > 0) {
        results.push({
          document: doc.name,
          title: doc.title,
          category: doc.category,
          type: doc.type,
          relevanceScore,
          matches,
        });
      }
    }
  
    // Sort by relevance score (highest first)
    results.sort((a, b) => b.relevanceScore - a.relevanceScore);
  
    this.cache.setSearchResults(cacheKey, results);
    return results;
  }

• src/core/tool-definitions.ts:187-200 (schema)

  Tool definition including name, description, and input schema requiring a 'query' string parameter.

  {
    name: 'search_sfra_documentation',
    description: 'Search across all SFRA documentation for specific terms, concepts, or functionality. Use this when you need to find specific SFRA features, understand how to implement controller patterns, locate model information, or find information about routing, middleware, request handling, response management, cart functionality, product models, or customer management. Enhanced with relevance scoring and categorization.',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description: "Search term or concept (e.g., 'middleware', 'routing', 'render', 'querystring', 'cache', 'cart', 'product', 'billing', 'shipping', 'account', 'pricing')",
        },
      },
      required: ['query'],
    },
  },

• src/tool-configs/sfra-tool-config.ts:50-60 (registration)

  Tool registration configuration: validation for 'query' arg, exec handler delegating to SFRAClient, logging.

  search_sfra_documentation: {
    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.sfraClient as SFRAClient;
      return client.searchSFRADocumentation(args.query as string);
    },
    logMessage: (args: ToolArguments) => `Search SFRA ${args.query}`,
  },

• src/tool-configs/sfra-tool-config.ts:6-12 (registration)

  Array listing all SFRA tool names including search_sfra_documentation for type safety and registration reference.

  export const SFRA_TOOL_NAMES = [
    'get_available_sfra_documents',
    'get_sfra_document',
    'search_sfra_documentation',
    'get_sfra_documents_by_category',
    'get_sfra_categories',
  ] as const;