Searchspring Integration Assistant

Instructions

Implementation Reference

• src/index.ts:36-50 (registration)

  Registers the 'searchspring_api_guide' tool including name, description, and input schema definition.

  {
    name: "searchspring_api_guide",
    description: "Get comprehensive implementation guidance for any Searchspring API",
    inputSchema: {
      type: "object",
      properties: {
        api: {
          type: "string",
          enum: ["search", "autocomplete", "suggest", "trending", "recommendations", "finder", "beacon", "bulk-index"],
          description: "The Searchspring API to get implementation guidance for",
        },
      },
      required: ["api"],
    },
  },

• src/searchspring-client.ts:18-20 (schema)

  TypeScript interface defining the input parameters for the searchspring_api_guide tool.

  export interface ApiGuideParams {
    api: "search" | "autocomplete" | "suggest" | "trending" | "recommendations" | "finder" | "beacon" | "bulk-index";
  }

• src/index.ts:140-141 (handler)

  Switch case that handles tool dispatch by calling searchspringClient.getApiGuide.

  case "searchspring_api_guide":
    return await searchspringClient.getApiGuide(args as any);

• src/searchspring-client.ts:52-406 (handler)

  Core handler function that provides detailed implementation guides for Searchspring APIs using predefined data structures and formats the response as MCP content.

    async getApiGuide(params: ApiGuideParams) {
      const { api } = params;
  
      const siteId = this.getSiteIdOrExample();
  
      const apiGuides = {
        search: {
          name: "Search API",
          description: "Full-text product search with filtering, sorting, and pagination",
          endpoint: `https://${siteId}.a.searchspring.io/api/search/search.json`,
          requiredParams: ["siteId", "resultsFormat", "userId", "sessionId", "pageLoadId", "domain"],
          optionalParams: ["q", "page", "resultsPerPage", "filter.*", "bgfilter.*", "sort.*", "redirectResponse", "landingPage", "tag", "includedFacets", "excludedFacets", "disableInlineBanners", "lastViewed", "cart", "shopper"],
          example: `fetch('https://${siteId}.a.searchspring.io/api/search/search.json?siteId=${siteId}&resultsFormat=json&q=shoes&userId=user123&sessionId=session456&pageLoadId=page789&domain=https://yoursite.com')
    .then(response => response.json())
    .then(data => {
      console.log('Total results:', data.pagination.totalResults);
      data.results.forEach(product => {
        console.log(product.title, product.price);
      });
    })
    .catch(error => console.error('Search error:', error));`,
          useCases: [
            "Product catalog search",
            "Category page filtering",
            "Search results page",
            "Faceted navigation"
          ],
          bestPractices: [
            "Always include tracking parameters: userId (from ssUserId cookie), sessionId (from ssSessionIdNamespace cookie), pageLoadId (UUID v4), domain (window.location.href)",
            "Use background filters (bgfilter.*) for permanent filtering, not filter.*",
            "Implement proper error handling with .catch()",
            "Use debouncing for real-time search (minimum 50ms for autocomplete)",
            "Include pagination for large result sets",
            "Use query parameter (q) for all search requests"
          ]
        },
        autocomplete: {
          name: "Autocomplete API",
          description: "Real-time product preview as user types - REQUIRED for autocomplete functionality (not Search API)",
          endpoint: `https://${siteId}.a.searchspring.io/api/search/autocomplete.json`,
          requiredParams: ["siteId", "resultsFormat", "userId", "sessionId", "pageLoadId", "domain"],
          optionalParams: ["q", "resultsPerPage", "page", "filter.*", "bgfilter.*", "sort.*", "redirectResponse", "lastViewed", "cart", "shopper"],
          example: `const searchInput = document.getElementById('search');
  let debounceTimer;
  
  searchInput.addEventListener('input', function(e) {
    clearTimeout(debounceTimer);
    const query = e.target.value;
  
    if (query.length >= 2) {
      debounceTimer = setTimeout(() => {
        fetchAutocomplete(query);
      }, 50); // 50ms debounce as recommended by Searchspring docs
    }
  });
  
  function fetchAutocomplete(query) {
    fetch('https://${siteId}.a.searchspring.io/api/search/autocomplete.json?siteId=${siteId}&resultsFormat=json&q=' + query + '&userId=user123&sessionId=session456&pageLoadId=page789&domain=https://yoursite.com')
      .then(response => response.json())
      .then(data => displaySuggestions(data))
      .catch(error => console.error('Autocomplete error:', error));
  }`,
          useCases: [
            "Search input suggestions",
            "Product finder autocomplete",
            "Category autocomplete",
            "Brand/attribute suggestions"
          ],
          bestPractices: [
            "Use debouncing (300ms delay recommended)",
            "Start suggesting after 2+ characters",
            "Limit results to 8-10 suggestions",
            "Handle keyboard navigation (up/down arrows)",
            "Clear suggestions on blur or escape"
          ]
        },
        suggest: {
          name: "Suggest API",
          description: "Spell correction and alternative search term suggestions",
          endpoint: `https://${siteId}.a.searchspring.io/api/suggest/query`,
          requiredParams: ["siteId"],
          optionalParams: ["q", "language", "suggestionCount", "productCount"],
          example: `function getSuggestions(query) {
    fetch('https://${siteId}.a.searchspring.io/api/suggest/query?siteId=${siteId}&q=' + query + '&language=en&suggestionCount=4')
      .then(response => response.json())
      .then(data => {
        if (data.spellCorrection && data.spellCorrection.corrected) {
          showSpellCorrection(data.spellCorrection.corrected);
        }
        if (data.suggestions && data.suggestions.length > 0) {
          showAlternativeSuggestions(data.suggestions);
        }
      })
      .catch(error => console.error('Suggest error:', error));
  }`,
          useCases: [
            "Spell correction for misspelled queries",
            "Alternative search suggestions",
            "No results page suggestions",
            "Query expansion"
          ],
          bestPractices: [
            "Show spell corrections prominently",
            "Limit suggestions to 3-5 alternatives",
            "Use on no-results pages",
            "Consider user's language/locale"
          ]
        },
        trending: {
          name: "Trending API",
          description: "Popular search terms and trending content",
          endpoint: `https://${siteId}.a.searchspring.io/api/suggest/trending`,
          requiredParams: ["siteId"],
          optionalParams: ["limit"],
          example: `function loadTrendingTerms() {
    fetch('https://${siteId}.a.searchspring.io/api/suggest/trending?siteId=${siteId}&limit=6')
      .then(response => response.json())
      .then(data => {
        const container = document.getElementById('trending-terms');
        data.terms.forEach(term => {
          const link = document.createElement('a');
          link.href = '/search?q=' + encodeURIComponent(term.query);
          link.textContent = term.query;
          container.appendChild(link);
        });
      })
      .catch(error => console.error('Trending error:', error));
  }`,
          useCases: [
            "Homepage trending searches",
            "No results page alternatives",
            "Popular content widgets",
            "Search inspiration"
          ],
          bestPractices: [
            "Update trending terms regularly",
            "Limit to 5-8 terms for better UX",
            "Use on homepage and no-results pages",
            "Make terms clickable for easy searching"
          ]
        },
        recommendations: {
          name: "Recommendations API",
          description: "Personalized product recommendations",
          endpoint: `https://${siteId}.a.searchspring.io/boost/${siteId}/recommend`,
          requiredParams: ["tags"],
          optionalParams: ["products", "blockedItems", "categories", "brands", "shopper", "cart", "lastViewed", "limits", "filter.*"],
          example: `function getRecommendations() {
    const params = new URLSearchParams({
      tags: 'similar-products,trending',
      products: 'PRODUCT-123',
      limits: '5,10',
      shopper: 'user123'
    });
  
    fetch('https://${siteId}.a.searchspring.io/boost/${siteId}/recommend?' + params)
      .then(response => response.json())
      .then(data => {
        data.profiles.forEach(profile => {
          console.log('Profile:', profile.tag);
          profile.results.forEach(product => {
            console.log(' -', product.title, product.price);
          });
        });
      })
      .catch(error => console.error('Recommendations error:', error));
  }`,
          useCases: [
            "Product page cross-sells",
            "Homepage personalization",
            "Cart page upsells",
            "Related products"
          ],
          bestPractices: [
            "Use multiple recommendation types (tags)",
            "Include personalization data (shopper, cart, lastViewed)",
            "Block out-of-stock or inappropriate items",
            "Set reasonable limits per profile"
          ]
        },
        finder: {
          name: "Finder API",
          description: "Faceted search for building product finder interfaces - uses Search API with resultsPerPage=0",
          endpoint: `https://${siteId}.a.searchspring.io/api/search/search.json`,
          requiredParams: ["siteId", "resultsPerPage=0"],
          optionalParams: ["filter.*", "bgfilter.*", "includedFacets", "excludedFacets"],
          example: `function getFacets() {
    fetch('https://${siteId}.a.searchspring.io/api/search/search.json?siteId=${siteId}&resultsPerPage=0&filter.category=shoes')
      .then(response => response.json())
      .then(data => {
        data.facets.forEach(facet => {
          console.log('Facet:', facet.label);
          facet.values.forEach(value => {
            console.log(' -', value.label, '(' + value.count + ')');
          });
        });
      })
      .catch(error => console.error('Finder error:', error));
  }`,
          useCases: [
            "Product finder widgets",
            "Advanced filtering interfaces",
            "Category navigation",
            "Faceted search"
          ],
          bestPractices: [
            "Always set resultsPerPage=0 for facets-only",
            "Use includedFacets to limit returned facets",
            "Apply background filters for category pages",
            "Show facet counts for better UX"
          ]
        },
        beacon: {
          name: "Beacon API",
          description: "Advanced event tracking for Personalized Recommendations - NOTE: For basic product tracking use IntelliSuggest ss.track.* methods",
          endpoint: `https://beacon.searchspring.io/api/event`,
          requiredParams: ["array of event objects with: category, context, event, id, type"],
          optionalParams: ["pid (for profile.product.* events)"],
          example: `function trackEvent(eventType, eventData) {
    const payload = {
      type: eventType,
      category: 'searchspring.recommendations.user-interactions',
      siteId: '${siteId}',
      id: 'event-' + Date.now(),
      userid: 'user123',
      sessionid: 'session456',
      data: eventData,
      context: {
        website: { trackingCode: '${siteId}' },
        page: { url: window.location.href }
      }
    };
  
    fetch('https://beacon.searchspring.io/api/event', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json'
      },
      body: JSON.stringify(payload)
    })
    .then(response => response.json())
    .then(data => console.log('Event tracked:', data))
    .catch(error => console.error('Tracking error:', error));
  }`,
          useCases: [
            "Recommendation impression tracking",
            "Click-through analytics",
            "User behavior analytics",
            "Custom event tracking"
          ],
          bestPractices: [
            "Use consistent event categories",
            "Include user and session identifiers",
            "Batch events when possible",
            "Handle tracking failures gracefully",
            "Include relevant context data"
          ]
        },
        "bulk-index": {
          name: "Bulk Indexing API",
          description: "Bulk product data indexing and management",
          endpoint: `https://index-api.searchspring.net/api/index/feed`,
          requiredParams: ["feedId"],
          optionalParams: ["requestedBy"],
          example: `// Platform-specific bulk indexing implementation
  // For cart platforms (Shopify, BigCommerce) - use PUT method
  function triggerCartPlatformIndex(feedId, secretKey) {
    // Authentication via URL (siteId:secretKey@host)
    const url = 'https://${siteId}:' + secretKey + '@index-api.searchspring.net/api/index/feed?feedId=' + feedId;
  
    fetch(url, {
      method: 'PUT' // Downloads feed from cart platform
    })
    .then(response => response.json())
    .then(data => {
      if (data.success) {
        console.log('Bulk index triggered successfully');
      }
    })
    .catch(error => console.error('Bulk index error:', error));
  }
  
  // For custom feeds - use POST with file upload
  function uploadCustomFeed(feedId, secretKey, feedFile) {
    const formData = new FormData();
    formData.append('feedFile', feedFile);
  
    const url = 'https://${siteId}:' + secretKey + '@index-api.searchspring.net/api/index/feed?feedId=' + feedId;
  
    fetch(url, {
      method: 'POST',
      body: formData // multipart/form-data
    })
    .then(response => response.json())
    .then(data => console.log('Feed uploaded:', data))
    .catch(error => console.error('Upload error:', error));
  }`,
          useCases: [
            "Product catalog updates",
            "Inventory synchronization",
            "Scheduled data imports",
            "Content management integration"
          ],
          bestPractices: [
            "Use PUT method for cart platforms (Shopify, BigCommerce, etc.)",
            "Use POST method for custom feed uploads",
            "Authentication: siteId:secretKey@ in URL (not headers)",
            "Check status endpoint before triggering new index",
            "Only one index per hour allowed",
            "Use multipart/form-data for POST requests"
          ]
        }
      };
  
      const guide = apiGuides[api];
      if (!guide) {
        throw new Error(`Unknown API: ${api}`);
      }
  
      return {
        content: [
          {
            type: "text",
            text: this.addSiteIdNote(`# ${guide.name} Implementation Guide
  
  ## Overview
  ${guide.description}
  
  **API Endpoint**: ${guide.endpoint}
  
  ## Required Parameters
  ${guide.requiredParams.map(param => `- \`${param}\``).join('\n')}
  
  ## Optional Parameters
  ${guide.optionalParams.map(param => `- \`${param}\``).join('\n')}
  
  ## Implementation Example
  \`\`\`javascript
  ${guide.example}
  \`\`\`
  
  ## Common Use Cases
  ${guide.useCases.map(useCase => `- ${useCase}`).join('\n')}
  
  ## Best Practices
  ${guide.bestPractices.map(practice => `- ${practice}`).join('\n')}
  
  ## Documentation
  📖 **Full API Documentation**: https://docs.searchspring.com/api/${api}/
  🎯 **Help Center**: https://help.searchspring.net/
  🔧 **Implementation Guides**: https://help.searchspring.net/hc/en-us/sections/201185149`),
          },
        ],
      };
    }

• src/searchspring-client.ts:45-50 (helper)

  Helper method that appends site ID replacement instructions to guide text when no real site ID is configured.

  private addSiteIdNote(text: string): string {
    if (!this.config.siteId) {
      return text + "\n\n**Note**: Replace 'xyz789' with your actual Searchspring site ID (also known as tracking code) in all URLs and code examples above. This is a 6-character alphanumeric identifier provided by your Searchspring representative.";
    }
    return text;
  }