Searchspring Integration Assistant

Searchspring Integration Assistant (MCP Server)

MCP server designed as an integration assistant to help customers implement Searchspring APIs correctly.

This Model Context Protocol (MCP) server provides implementation guidance, code validation, and troubleshooting tools for Searchspring's e-commerce APIs. Instead of making direct API calls, it serves as an intelligent assistant that helps developers properly implement search, autocomplete, IntelliSuggest tracking, and recommendations in their applications.

Features

The server provides integration assistance for all major Searchspring APIs:

Implementation Guidance: Step-by-step code examples and API endpoint construction
Platform-Specific Code Generation: Ready-to-use code for Shopify, Magento, BigCommerce, etc.
Code Validation & Troubleshooting: Analyze existing implementations and identify issues
Best Practices: Security, performance, and reliability recommendations
Documentation Links: Direct links to relevant Searchspring documentation

Supported API Integrations:

Search API: Implementation guides for product search with filtering and pagination
Autocomplete API: Real-time search suggestions implementation patterns
Suggest API: Spell correction and alternative query suggestions
IntelliSuggest Tracking: Behavioral event tracking implementation (product views, cart, purchases)
Recommendations API: Personalized product recommendation integration
Trending API: Popular search terms and trending content
Beacon API: Analytics event tracking for recommendations
Bulk Indexing API: Product data indexing guidance (requires secret key)
Finder API: Advanced product discovery interfaces

Installation

Clone this repository
Install dependencies:
npm install
Build the project:
npm run build

Configuration

Configure your Searchspring credentials as environment variables:

# Required: Your Searchspring site ID  
SEARCHSPRING_SITE_ID=your_site_id_here

# Optional: Your Searchspring secret key (required only for bulk indexing)
SEARCHSPRING_SECRET_KEY=your_secret_key_here

# Optional: Request timeout in milliseconds (defaults to 10000)
SEARCHSPRING_TIMEOUT=10000

Usage

Running the Server

Start the MCP server:

npm start

For development with auto-reload:

npm run dev

Available Tools

1. Search API Implementation (`searchspring_search`)

Get implementation guidance for product search integration:

{
  "query": "running shoes",
  "page": 1,
  "resultsPerPage": 20,
  "filters": {
    "brand": ["Nike", "Adidas"],
    "color": "blue"
  },
  "sort": {
    "price": "asc",
    "popularity": "desc"
  }
}

Returns: Complete API endpoint URL, required parameters, JavaScript implementation example, and documentation links.

2. Autocomplete Implementation (`searchspring_autocomplete`)

Get implementation guidance for real-time search suggestions:

{
  "query": "runn",
  "resultsPerPage": 10
}

Returns: Complete autocomplete implementation with debouncing, error handling, and UI integration examples.

3. Search Suggestions (`searchspring_suggest`)

Get product discovery suggestions:

{
  "query": "athletic wear",
  "categories": ["shoes", "apparel"],
  "limit": 10
}

4. IntelliSuggest Tracking (`searchspring_intellisuggest_track`)

Track behavioral events for IntelliSuggest analytics and personalization:

{
  "type": "product",
  "event": {
    "sku": "ABC123",
    "name": "Running Shoes",
    "price": 99.99,
    "category": "footwear"
  }
}

Available event types:

product: Product page view
cart: Cart addition/view
sale: Purchase completion

5. Platform Implementation (`searchspring_platform_implementation`)

Get platform-specific IntelliSuggest tracking code:

{
  "platform": "shopify",
  "eventType": "product",
  "sku": "ABC123",
  "price": 99.99
}

Available platforms:

shopify, bigcommerce-stencil, magento2, custom, etc.

6. Search Result Click Guide (`searchspring_search_result_click`)

Get implementation guide for search result click tracking:

{
  "intellisuggestData": "data-from-search-api",
  "intellisuggestSignature": "signature-from-search-api"
}

7. Beacon Tracking (`searchspring_beacon_track`)

Track user events for recommendations analytics:

{
  "type": "profile.impression",
  "event": {
    "profile": {
      "tag": "similar-products",
      "placement": "product-page"
    }
  },
  "context": {
    "website": {
      "trackingCode": "abc123"
    },
    "userId": "user-123",
    "sessionId": "session-456"
  }
}

Available event types:

profile.render: Profile rendered on page
profile.impression: Profile viewed by user
profile.click: Profile clicked by user
profile.product.render: Product rendered in profile
profile.product.impression: Product viewed in profile
profile.product.click: Product clicked in profile

8. Recommendations (`searchspring_recommendations`)

Get personalized product recommendations:

{
  "tags": ["similar-products", "trending"],
  "products": ["ABC123"],
  "limits": [5, 10],
  "shopper": "user123"
}

Required parameters:

tags: Array of recommendation profile tags/IDs

Optional parameters:

products: Product SKUs being viewed (for cross-sell/similar)
limits: Maximum products per profile
shopper: Logged-in shopper ID for personalization
cart: Product SKUs in current cart
lastViewed: Recently viewed product SKUs
bought_together: Frequently bought together

9. Trending Data (`searchspring_trending`)

Get trending products or search terms:

{
  "type": "products",
  "timeframe": "day",
  "categoryId": "electronics",
  "limit": 20
}

10. Finder API (`searchspring_finder`)

Get product facets for building product finder interfaces:

{
  "filters": {
    "color": "blue",
    "brand": ["Nike", "Adidas"]
  },
  "includedFacets": ["color", "size", "brand"]
}

12. Code Validation (`searchspring_code_validator`)

NEW: Validate and troubleshoot your Searchspring implementation:

{
  "code": "<script>if (typeof ss != 'undefined') { ss.track.product.view({sku: 'ABC123'}); }</script>",
  "codeType": "tracking",
  "platform": "shopify",
  "issue": "Tracking events not appearing in analytics"
}

Returns:

✅ Validation results (what's working correctly)
⚠️ Warnings (potential issues)
💡 Suggestions (improvements)
🔧 Troubleshooting (specific issue diagnosis)

Supported code types:

tracking: IntelliSuggest event tracking validation
search: Search API implementation validation
autocomplete: Autocomplete implementation validation
recommendations: Recommendation integration validation

9. Finder API (`searchspring_finder`)

Advanced product discovery with faceting:

{
  "query": "athletic wear",
  "filters": {
    "brand": ["Nike", "Adidas"],
    "price": "25-100",
    "size": ["M", "L"]
  },
  "facets": ["brand", "price", "size", "color"],
  "sort": "popularity_desc",
  "page": 1,
  "resultsPerPage": 20,
  "includeMetadata": true
}

Integration with MCP Clients

This server can be used with any MCP-compatible client. Here's how to configure it with Claude Desktop:

Add to your MCP settings file (claude_desktop_config.json):

{
  "mcpServers": {
    "searchspring": {
      "command": "node",
      "args": ["path/to/searchspring-mcp-server/dist/index.js"],
      "env": {
        "SEARCHSPRING_API_KEY": "your_api_key",
        "SEARCHSPRING_SITE_ID": "your_site_id"
      }
    }
  }
}

Restart Claude Desktop

API Documentation

For detailed information about Searchspring APIs, visit:

Development

Project Structure

src/
├── index.ts              # Main MCP server setup
├── searchspring-client.ts # Searchspring API client
└── config.ts             # Configuration management

Adding New Tools

To add a new tool:

Add the tool definition to the tools array in index.ts
Add the corresponding method to SearchspringClient
Add the case handler in the tool call switch statement

Error Handling

The server includes comprehensive error handling:

Configuration validation on startup
API request/response error handling
Proper error messages returned to MCP clients

Contributing

Fork the repository
Create a feature branch
Make your changes
Add tests if applicable
Submit a pull request

License

MIT

Searchspring Integration Assistant