Searchspring Integration Assistant

Instructions

Implementation Reference

• src/searchspring-client.ts:1357-1578 (handler)

  Core handler function implementing the searchspring_code_validator tool. Performs comprehensive static code analysis for Searchspring API implementations, validates endpoints, required parameters, tracking calls, platform compatibility (Shopify, BigCommerce, etc.), error handling, and provides actionable feedback including troubleshooting for specific issues.

    async validateCode(params: CodeValidationParams) {
      const { code, codeType, platform, issue } = params;
      const siteId = this.getSiteIdOrExample();
  
      const validationResults: string[] = [];
      const warnings: string[] = [];
      const suggestions: string[] = [];
  
      // Common validation checks
      if (codeType === "tracking" || codeType === "beacon") {
        // Check for IntelliSuggest script inclusion
        if (!code.includes("cdn.searchspring.net/intellisuggest") && !code.includes("is.min.js")) {
          validationResults.push("❌ Missing IntelliSuggest script: <script src='//cdn.searchspring.net/intellisuggest/is.min.js'></script>");
        } else {
          validationResults.push("✅ IntelliSuggest script inclusion detected");
        }
  
        // Check for ss.track usage
        if (!code.includes("ss.track")) {
          validationResults.push("❌ No tracking calls found (ss.track.product.view, ss.track.cart.add, ss.track.purchase.buy)");
        } else {
          validationResults.push("✅ Tracking calls detected");
        }
  
        // Check for typeof ss check
        if (!code.includes("typeof ss")) {
          warnings.push("⚠️  Consider adding safety check: if (typeof ss != 'undefined')");
        }
  
        // Check for required tracking fields
        if (code.includes("ss.track.product") && !code.includes("sku")) {
          validationResults.push("❌ Product tracking missing required 'sku' field");
        }
  
        if (code.includes("ss.track.cart") && (!code.includes("sku") || !code.includes("quantity"))) {
          validationResults.push("❌ Cart tracking missing required 'sku' and/or 'quantity' fields");
        }
  
        if (code.includes("ss.track.purchase") && (!code.includes("sku") || !code.includes("quantity"))) {
          validationResults.push("❌ Purchase tracking missing required 'sku' and/or 'quantity' fields");
        }
      }
  
      if (codeType === "search" || codeType === "autocomplete" || codeType === "suggest" || codeType === "trending" || codeType === "finder" || codeType === "recommendations") {
        // Check for API endpoint
        if (!code.includes(".a.searchspring.io")) {
          validationResults.push("❌ Missing Searchspring API endpoint (should include .a.searchspring.io)");
        } else {
          validationResults.push("✅ Searchspring API endpoint detected");
        }
  
        // Check for required parameters
        if (!code.includes("siteId")) {
          validationResults.push("❌ Missing required 'siteId' parameter");
        } else {
          validationResults.push("✅ siteId parameter detected");
        }
  
        if (!code.includes("userId") && !code.includes("sessionId")) {
          warnings.push("⚠️  Missing tracking parameters (userId, sessionId) - these are required for analytics");
        }
  
        // API-specific validations
        if (codeType === "search" && !code.includes("q=")) {
          validationResults.push("❌ Search API missing query parameter 'q'");
        }
  
        if (codeType === "autocomplete" && !code.includes("debounce")) {
          warnings.push("⚠️  Consider implementing debouncing for autocomplete to reduce API calls");
        }
  
        if (codeType === "recommendations" && !code.includes("pageLoadId")) {
          warnings.push("⚠️  Recommendations work better with pageLoadId parameter");
        }
  
        // Check for error handling
        if (!code.includes(".catch") && !code.includes("try")) {
          warnings.push("⚠️  No error handling detected - consider adding .catch() or try/catch");
        }
      }
  
      if (codeType === "beacon") {
        // Check for beacon endpoint
        if (!code.includes("beacon.searchspring.io")) {
          validationResults.push("❌ Missing Beacon API endpoint (should be beacon.searchspring.io)");
        } else {
          validationResults.push("✅ Beacon API endpoint detected");
        }
  
        // Check for POST method
        if (!code.includes("POST")) {
          validationResults.push("❌ Beacon API requires POST method");
        }
  
        // Check for required beacon fields
        if (!code.includes("type")) {
          validationResults.push("❌ Beacon tracking missing required 'type' field");
        }
      }
  
      if (codeType === "bulk-index") {
        // Check for bulk index endpoint
        if (!code.includes("index-api.searchspring.net")) {
          validationResults.push("❌ Missing Bulk Index API endpoint (should be index-api.searchspring.net)");
        } else {
          validationResults.push("✅ Bulk Index API endpoint detected");
        }
  
        // Check for secret key
        if (!code.includes("secretKey")) {
          validationResults.push("❌ Bulk Index API requires 'secretKey' parameter");
        }
  
        // Check for products array
        if (!code.includes("products")) {
          validationResults.push("❌ Bulk Index API missing 'products' array");
        }
      }
  
      // Platform-specific checks
      if (platform === "shopify") {
        if (codeType === "tracking" && !code.includes("{{")) {
          warnings.push("⚠️  No Liquid template variables detected - make sure you're using Shopify's template syntax");
        }
  
        if (code.includes("product.variants.first.sku") && !code.includes("product.selected_or_first_available_variant.sku")) {
          suggestions.push("💡 Consider using product.selected_or_first_available_variant.sku for better variant handling");
        }
  
        // Check for modern Shopify checkout extensibility
        if (codeType === "tracking" && code.includes("ss.track.purchase.buy") && code.includes("order.line_items")) {
          warnings.push("⚠️  IMPORTANT: For Shopify stores with checkout extensibility, sales tracking must use Web Pixel apps instead of thank you page code");
          suggestions.push("💡 Modern Shopify: Contact Searchspring support for Web Pixel app setup (https://help.searchspring.net/hc/en-us/articles/24882106349467)");
        }
      }
  
      if (platform === "bigcommerce") {
        if (codeType === "tracking" && !code.includes("{{#") && !code.includes("{{")) {
          warnings.push("⚠️  No Handlebars template syntax detected - make sure you're using BigCommerce's Stencil template syntax");
        }
  
        if (code.includes("product.sku") && !code.includes("{{product.sku}}")) {
          suggestions.push("💡 Use {{product.sku}} for BigCommerce Stencil template syntax");
        }
      }
  
      if (platform === "magento2") {
        if (codeType === "tracking" && !code.includes("<?=")) {
          warnings.push("⚠️  No PHP template syntax detected - make sure you're using Magento's .phtml syntax");
        }
  
        if (code.includes("$_product") && !code.includes("escapeHtml")) {
          suggestions.push("💡 Use $block->escapeHtml() for proper data escaping in Magento 2");
        }
      }
  
      // Issue-specific troubleshooting
      let troubleshooting = "";
      if (issue) {
        troubleshooting = `
  
  Troubleshooting for: "${issue}"
  `;
  
        if (issue.toLowerCase().includes("not working") || issue.toLowerCase().includes("not tracking")) {
          troubleshooting += `Common causes:
  - IntelliSuggest script not loaded or blocked by ad blockers
  - Script placed in wrong location (should be in <head> or before tracking calls)
  - Missing _isuid cookie (check browser dev tools > Application > Cookies)
  - SKU values don't match Searchspring indexed product SKU field
  - Browser console errors preventing script execution
  - SHOPIFY SPECIFIC: Modern Shopify stores with checkout extensibility require Web Pixel apps for sales tracking
  `;
        }
  
        if (issue.toLowerCase().includes("undefined") || issue.toLowerCase().includes("is not defined")) {
          troubleshooting += `Script loading issue:
  - Ensure IntelliSuggest script loads before your tracking code
  - Remove async/defer attributes from the IntelliSuggest script tag
  - Check browser console for script loading errors
  `;
        }
  
        if (issue.toLowerCase().includes("shopify") && issue.toLowerCase().includes("sales")) {
          troubleshooting += `Shopify sales tracking issues:
  - Modern Shopify (checkout extensibility): Use Web Pixel apps instead of thank you page
  - Traditional Shopify: Add code to order-status-url template
  - Contact Searchspring support for Web Pixel app setup
  - Verify _isuid cookie is being set correctly
  - Documentation: https://help.searchspring.net/hc/en-us/articles/24882106349467
  `;
        }
  
        if (issue.toLowerCase().includes("search") || issue.toLowerCase().includes("results")) {
          troubleshooting += `API integration issues:
  - Verify siteId is correct: ${siteId}
  - Check CORS settings if calling from browser
  - Ensure all required parameters are included
  - Check network tab for API response errors
  `;
        }
      }
  
      const summary = `Code Validation Results for ${codeType.toUpperCase()} implementation${platform ? ` on ${platform.toUpperCase()}` : ''}
  
  ${validationResults.join('\n')}
  
  ${warnings.length > 0 ? `Warnings:\n${warnings.join('\n')}\n` : ''}${suggestions.length > 0 ? `Suggestions:\n${suggestions.join('\n')}\n` : ''}${troubleshooting}
  For additional support:
  - Documentation: https://docs.searchspring.com/
  - Support: https://help.searchspring.net/
  - Implementation guides: https://help.searchspring.net/hc/en-us/sections/201185149`;
  
      return {
        content: [
          {
            type: "text",
            text: summary,
          },
        ],
      };
    }

• src/index.ts:99-127 (registration)

  Tool registration definition including name, description, and complete inputSchema for validation parameters (code, codeType, platform, issue). Added to the tools array returned by ListToolsRequest.

    {
      name: "searchspring_code_validator",
      description: "Validate and troubleshoot Searchspring implementation code",
      inputSchema: {
        type: "object",
        properties: {
          code: {
            type: "string",
            description: "JavaScript/HTML code to validate",
          },
          codeType: {
            type: "string",
            enum: ["search", "autocomplete", "suggest", "trending", "recommendations", "finder", "beacon", "bulk-index", "tracking"],
            description: "Type of Searchspring implementation being validated",
          },
          platform: {
            type: "string",
            enum: ["shopify", "bigcommerce", "magento2", "custom", "other"],
            description: "E-commerce platform (optional)",
          },
          issue: {
            type: "string",
            description: "Specific issue or error message you're experiencing (optional)",
          },
        },
        required: ["code", "codeType"],
      },
    },
  ];

• src/index.ts:149-150 (handler)

  MCP CallToolRequest handler dispatch that routes calls to the searchspring_code_validator tool to the underlying SearchspringClient.validateCode method.

  case "searchspring_code_validator":
    return await searchspringClient.validateCode(args as any);

• src/searchspring-client.ts:11-16 (schema)

  TypeScript interface defining the input parameters for code validation, mirroring the tool's inputSchema for type safety.

  export interface CodeValidationParams {
    code: string;
    codeType: "search" | "autocomplete" | "suggest" | "trending" | "recommendations" | "finder" | "beacon" | "bulk-index" | "tracking";
    platform?: "shopify" | "bigcommerce" | "magento1" | "magento2" | "miva" | "commercev3" | "3dcart" | "volusion" | "custom" | "other";
    issue?: string;
  }