Searchspring Integration Assistant

A Model Context Protocol (MCP) server that provides implementation guidance, code validation, and troubleshooting for Searchspring's e-commerce APIs.

Important: This is an integration assistant, not an API proxy. It returns implementation guidance and code examples rather than live API data.

Quick Start for Claude Desktop

1. Install and build:

   git clone <repo-url> cd searchspring-api-mcp npm install && npm run build

2. Configure Claude Desktop - Add to your claude_desktop_config.json:

   { "mcpServers": { "searchspring": { "command": "node", "args": ["/absolute/path/to/searchspring-api-mcp/dist/index.js"] } } }

3. Restart Claude Desktop and ask:

   "Show me how to implement Searchspring search API"

The Searchspring tools will activate automatically - no special commands needed!

Developer Setup

1. Install dependencies:

   npm install npm run build

2. Start the server:

   npm start

Note: SEARCHSPRING_SITE_ID is optional - the LLM can provide example site IDs or ask users for their specific ID when needed.

What This MCP Does

✅ Implementation Guidance - Step-by-step API integration instructions for all 8 Searchspring APIs

✅ Code Validation - Analyze existing implementations for issues with platform-specific checks

✅ Platform-Specific Code - Generate code for Shopify, BigCommerce, Magento, and 7+ platforms

✅ Troubleshooting - Diagnose common integration problems with targeted solutions

✅ Modern Platform Support - Includes Shopify checkout extensibility and Web Pixel guidance

✅ Documentation Links - Direct links to relevant Searchspring docs

❌ Not an API Proxy - Does not make live API calls or return product data

Available Tools

🎯 Implementation Guidance

Supported APIs: search, autocomplete, suggest, trending, recommendations, finder, beacon, bulk-index

🔧 Code Generation & Validation

Supported Platforms: shopify, bigcommerce, magento1, magento2, miva, commercev3, 3dcart, volusion, javascript, php, python, custom Supported Code Types: search, autocomplete, suggest, trending, recommendations, finder, beacon, bulk-index, tracking

Example Usage

Get API Implementation Guide

Get Parameter Details

Generate Platform Code

Validate Implementation

Integration Workflow

1. Planning → Use searchspring_api_guide to understand API structure and requirements

2. Deep Dive → Use searchspring_parameter_guide for specific parameter details

3. Implementation → Use searchspring_code_generator to create platform-specific code

4. Validation → Use searchspring_code_validator to check your implementation

5. Troubleshooting → Use validator with specific issues for detailed diagnosis

Testing & Development

Basic Validation

Local Development with LLM Clients

Claude Desktop Integration

Add to your claude_desktop_config.json:

Testing with OpenAI/Other LLMs

Use any MCP-compatible client:

Manual Tool Testing

Test individual tools directly:

MCP Activation & Usage

Once configured in Claude Desktop, the Searchspring MCP tools are automatically available. No special activation command needed!

Available Tools:

• searchspring_api_guide - Get implementation guidance for any API

• searchspring_parameter_guide - Get detailed parameter explanations

• searchspring_code_generator - Generate platform-specific code

• searchspring_code_validator - Validate and troubleshoot existing code

Sample Prompts to Activate Tools:

Interactive Development Testing

1. Start development server:

   npm run dev

2. Test API guidance:

   • Ask Claude: "Show me how to implement Searchspring search API"

   • Ask Claude: "Generate Shopify tracking code for product views"

   • Ask Claude: "Validate this search implementation code: [paste code]"

3. Test platform-specific generation:

   • Test all platforms: Shopify, BigCommerce, Magento1/2, Miva, CommerceV3, 3dCart, Volusion

   • Test modern Shopify Web Pixel tracking scenarios

   • Test bulk indexing guidance (with and without secret key)

4. Validate cross-references:

   • Ensure all generated code references match docs.searchspring.com

   • Verify platform-specific template syntax (Liquid, Handlebars, PHP)

   • Check that troubleshooting advice matches Zendesk Knowledge Base

Configuration Options

Docker Deployment

Ready for production deployment with Docker:

Security Features: Non-root user, minimal Alpine base, production-optimized

Kubernetes Deployment

Common Use Cases

New Searchspring Customer: Get implementation guidance for search, autocomplete, and tracking Existing Implementation Issues: Validate code and get troubleshooting help Platform Migration: Generate platform-specific tracking code Development Team Onboarding: Understand API structure and best practices Modern Shopify Stores: Get guidance for checkout extensibility and Web Pixel tracking

Support

• 📖 Documentation: https://docs.searchspring.com/

• 🎯 Help Center: https://help.searchspring.net/

License

MIT