Searchspring Integration Assistant

Instructions

Implementation Reference

• src/searchspring-client.ts:408-678 (handler)

  Core handler function that implements the searchspring_parameter_guide tool logic. Destructures api and parameter from input, looks up predefined guides, handles missing cases, and returns formatted parameter documentation in markdown.
  async getParameterGuide(params: ParameterGuideParams) { const { api, parameter } = params; const parameterGuides: Record<string, Record<string, any>> = { search: { q: { description: "Search query string - the terms users want to search for", type: "string", example: "running shoes", bestPractices: [ "URL encode special characters", "Trim whitespace before sending", "Consider query preprocessing (stemming, synonyms)", "Handle empty queries gracefully" ], useCases: ["Product search", "Site search", "Autocomplete"], relatedParams: ["redirectResponse", "landingPage"] }, filters: { description: "Apply filters to search results using filter.{field}=value format", type: "object", example: "filter.brand=Nike&filter.color=blue&filter.price=50-100", bestPractices: [ "Use exact field names from your product data", "For multiple values: filter.brand=Nike&filter.brand=Adidas", "For ranges: filter.price=min-max", "URL encode filter values" ], useCases: ["Category filtering", "Faceted navigation", "Price filtering"], relatedParams: ["bgfilters", "includedFacets", "excludedFacets"] }, bgfilters: { description: "Background filters applied permanently, not visible to users", type: "object", example: "bgfilter.status=active&bgfilter.visibility=public", bestPractices: [ "Use for system-level filtering (active products, visible items)", "Hide discontinued or out-of-stock products", "Apply site-specific rules", "Don't expose in filter UI" ], useCases: ["Product visibility", "Inventory filtering", "Site restrictions"], relatedParams: ["filters"] }, sort: { description: "Sort search results by field and direction", type: "object", example: "sort.price=asc&sort.popularity=desc", bestPractices: [ "Primary sort first, secondary sort second", "Use 'asc' for ascending, 'desc' for descending", "Common sorts: price, popularity, title, date", "Provide sort options to users" ], useCases: ["Price sorting", "Popularity sorting", "Name sorting", "Date sorting"], relatedParams: ["resultsPerPage", "page"] }, userId: { description: "Unique identifier for tracking user behavior - sourced from ssUserId cookie", type: "string", example: "value from ssUserId cookie", bestPractices: [ "Always get value from ssUserId cookie", "Automatically set by Searchspring tracking", "Do not manually generate - use cookie value", "Required for analytics and personalization" ], useCases: ["User tracking", "Personalization", "Analytics"], relatedParams: ["sessionId", "pageLoadId", "domain"] }, sessionId: { description: "Session identifier for tracking user journey - sourced from ssSessionIdNamespace cookie", type: "string", example: "value from ssSessionIdNamespace cookie", bestPractices: [ "Always get value from ssSessionIdNamespace cookie", "Automatically set by Searchspring tracking", "Do not manually generate - use cookie value", "Used for analytics and behavior tracking" ], useCases: ["Session tracking", "User journey analysis", "Analytics"], relatedParams: ["userId", "pageLoadId"] }, pageLoadId: { description: "Unique identifier for each page load/search - should be UUID v4", type: "string", example: "e560933a-b0fe-408d-8df5-807270e79fb8", bestPractices: [ "Generate new UUID v4 for each page load", "Update on every physical page load", "For SPA/headless: update on URL route change", "Critical for proper analytics tracking" ], useCases: ["Search tracking", "Click analytics", "Performance monitoring"], relatedParams: ["userId", "sessionId", "domain"] }, domain: { description: "Current page URL - should be window.location.href", type: "string", example: "https://yoursite.com/search?q=shoes", bestPractices: [ "Always use window.location.href value", "Include full URL with protocol and parameters", "Required for proper analytics and personalization", "Do not hardcode - get dynamically" ], useCases: ["Page tracking", "Analytics", "Personalization context"], relatedParams: ["userId", "sessionId", "pageLoadId"] } }, autocomplete: { q: { description: "Partial search query for autocomplete suggestions", type: "string", example: "runn (user typing 'running')", bestPractices: [ "Start suggestions after 2+ characters", "Use debouncing (50ms delay recommended by Searchspring)", "Handle special characters properly", "Clear suggestions when query is empty" ], useCases: ["Search input autocomplete", "Product suggestions", "Query completion"], relatedParams: ["resultsPerPage"] } }, recommendations: { tags: { description: "Recommendation profile tags/IDs that define recommendation types", type: "array", example: "['similar-products', 'trending', 'recently-viewed']", bestPractices: [ "Use meaningful profile names", "Configure profiles in Searchspring dashboard first", "Combine multiple recommendation types", "Order by priority/importance" ], useCases: ["Product recommendations", "Cross-selling", "Upselling", "Related products"], relatedParams: ["limits", "products", "shopper"] }, limits: { description: "Maximum number of products per recommendation profile", type: "array", example: "[5, 10, 3] (corresponds to tags array order)", bestPractices: [ "Match array length to tags array", "Consider page layout constraints", "Balance variety vs. performance", "Typical limits: 4-12 products" ], useCases: ["Controlling recommendation quantity", "Layout optimization"], relatedParams: ["tags"] }, shopper: { description: "Logged-in user identifier for personalization", type: "string", example: "user-12345", bestPractices: [ "Use only for authenticated users", "Consistent with your user system", "Improves recommendation quality", "Don't use for anonymous users" ], useCases: ["Personalized recommendations", "User-specific suggestions"], relatedParams: ["cart", "lastViewed"] } }, beacon: { type: { description: "Event type identifier for analytics tracking", type: "string", example: "profile.impression, profile.click, custom.event", bestPractices: [ "Use descriptive event names", "Follow consistent naming conventions", "Group related events with prefixes", "Document custom event types" ], useCases: ["Event categorization", "Analytics filtering", "Reporting"], relatedParams: ["category", "data"] }, category: { description: "Event category for grouping analytics events", type: "string", example: "searchspring.recommendations.user-interactions", bestPractices: [ "Use Searchspring standard categories when possible", "Create logical category hierarchies", "Document custom categories", "Keep category names consistent" ], useCases: ["Analytics grouping", "Event filtering", "Reporting dashboards"], relatedParams: ["type", "data"] }, data: { description: "Event payload containing specific event data", type: "object", example: "{profile: {tag: 'similar-products'}, product: {id: 'SKU123'}}", bestPractices: [ "Include relevant event context", "Keep payload size reasonable", "Use consistent data structure", "Validate data before sending" ], useCases: ["Event details", "Analytics context", "Personalization data"], relatedParams: ["type", "context"] } } }; const apiParams = parameterGuides[api]; if (!apiParams) { return { content: [ { type: "text", text: `Parameter guidance for ${api} API is not yet available. Use the searchspring_api_guide tool to get comprehensive API documentation.`, }, ], }; } const paramGuide = apiParams[parameter]; if (!paramGuide) { const availableParams = Object.keys(apiParams); return { content: [ { type: "text", text: `Parameter '${parameter}' not found for ${api} API. Available parameters for ${api}: ${availableParams.map(p => `- ${p}`).join('\n')} Use one of these parameter names to get detailed guidance.`, }, ], }; } return { content: [ { type: "text", text: `# ${parameter} Parameter Guide (${api.toUpperCase()} API) ## Description ${paramGuide.description} **Type**: ${paramGuide.type} ## Example Usage \`\`\` ${paramGuide.example} \`\`\` ## Best Practices ${paramGuide.bestPractices.map((practice: string) => `- ${practice}`).join('\n')} ## Common Use Cases ${paramGuide.useCases.map((useCase: string) => `- ${useCase}`).join('\n')} ## Related Parameters ${paramGuide.relatedParams.map((param: string) => `- \`${param}\``).join('\n')} ## Documentation 📖 **API Documentation**: https://docs.searchspring.com/api/${api}/ 🎯 **Parameter Reference**: https://docs.searchspring.com/api/${api}/#parameters`, }, ], }; }
• src/index.ts:54-68 (schema)

  Input schema defining the expected parameters: 'api' (enum of Searchspring APIs) and 'parameter' (string), both required.
  inputSchema: { type: "object", properties: { api: { type: "string", enum: ["search", "autocomplete", "suggest", "trending", "recommendations", "finder", "beacon", "bulk-index"], description: "The Searchspring API containing the parameter", }, parameter: { type: "string", description: "The specific parameter to get guidance for (e.g., 'filters', 'sort', 'tags')", }, }, required: ["api", "parameter"], },
• src/index.ts:51-69 (registration)

  Tool object registration in the tools array passed to MCP server, including name, description, and input schema.
  { name: "searchspring_parameter_guide", description: "Get detailed explanation for specific API parameters, their usage, and best practices", inputSchema: { type: "object", properties: { api: { type: "string", enum: ["search", "autocomplete", "suggest", "trending", "recommendations", "finder", "beacon", "bulk-index"], description: "The Searchspring API containing the parameter", }, parameter: { type: "string", description: "The specific parameter to get guidance for (e.g., 'filters', 'sort', 'tags')", }, }, required: ["api", "parameter"], }, },
• src/index.ts:143-144 (handler)

  Dispatch handler in the MCP tool call switch statement that invokes the SearchspringClient.getParameterGuide method.
  case "searchspring_parameter_guide": return await searchspringClient.getParameterGuide(args as any);
• src/searchspring-client.ts:22-25 (schema)

  TypeScript interface defining the input parameters for the parameter guide handler.
  export interface ParameterGuideParams { api: "search" | "autocomplete" | "suggest" | "trending" | "recommendations" | "finder" | "beacon" | "bulk-index"; parameter: string; }