Skip to main content
Glama

Searchspring Integration Assistant

by yangjeep
README.md8.83 kB
# 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**: ```bash git clone <repo-url> cd searchspring-api-mcp npm install && npm run build ``` 2. **Configure Claude Desktop** - Add to your `claude_desktop_config.json`: ```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**: ```bash npm install npm run build ``` 2. **Start the server**: ```bash 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 | Tool | Input | Output | |------|-------|--------| | `searchspring_api_guide` | API name | Complete implementation guide with endpoints, examples, and best practices | | `searchspring_parameter_guide` | API name + parameter | Detailed parameter explanation with usage examples and best practices | **Supported APIs**: `search`, `autocomplete`, `suggest`, `trending`, `recommendations`, `finder`, `beacon`, `bulk-index` ### 🔧 Code Generation & Validation | Tool | Input | Output | |------|-------|--------| | `searchspring_code_generator` | API + platform (+ eventType for tracking) | Platform-specific implementation code | | `searchspring_code_validator` | Code + codeType (+ platform + issue) | Validation results, warnings, suggestions, and troubleshooting | **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 ```json // Get comprehensive guidance for any API Input: {"api": "search"} Output: Complete implementation guide with endpoints, examples, and best practices ``` ### Get Parameter Details ```json // Understand specific API parameters Input: {"api": "search", "parameter": "filters"} Output: Detailed explanation of filters parameter with examples and best practices ``` ### Generate Platform Code ```json // Generate platform-specific implementation Input: {"api": "beacon", "platform": "shopify", "eventType": "product"} Output: Ready-to-use Shopify tracking code with Liquid template syntax ``` ### Validate Implementation ```json // Validate existing code and get troubleshooting help Input: { "code": "<script>ss.track.product.view({sku: 'ABC'});</script>", "codeType": "tracking", "platform": "shopify", "issue": "Events not showing in analytics" } Output: ❌ Missing IntelliSuggest script, ⚠️ No safety check, 🔧 Troubleshooting steps ``` ## 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 ```bash npm test ``` ### Local Development with LLM Clients #### Claude Desktop Integration Add to your `claude_desktop_config.json`: ```json { "mcpServers": { "searchspring": { "command": "node", "args": ["/absolute/path/to/searchspring-api-mcp/dist/index.js"] } } } ``` #### Testing with OpenAI/Other LLMs Use any MCP-compatible client: ```bash # Start the MCP server npm start # Test with mcp-client or similar tools npx @modelcontextprotocol/inspector ``` #### Manual Tool Testing Test individual tools directly: ```bash # Example: Test API guide tool echo '{"method": "tools/call", "params": {"name": "searchspring_api_guide", "arguments": {"api": "search"}}}' | npm start ``` ### 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:** ``` "Show me how to implement Searchspring search API" "Generate Shopify tracking code for product views" "Explain the filters parameter for the search API" "Validate this search implementation code: [paste code]" "Create BigCommerce autocomplete code" "How do I implement bulk indexing for Magento?" ``` ### Interactive Development Testing 1. **Start development server**: ```bash 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 | Variable | Required | Description | |----------|----------|-------------| | `SEARCHSPRING_SITE_ID` | ❌ Optional | Your Searchspring site identifier (LLM can provide examples) | | `SEARCHSPRING_SECRET_KEY` | ❌ Optional | Only needed for bulk indexing guidance | | `SEARCHSPRING_TIMEOUT` | ❌ Optional | Request timeout in ms (default: 10000) | ## Docker Deployment Ready for production deployment with Docker: ```bash # Build the Docker image docker build -t searchspring-mcp . # Run without environment variables (LLM will handle site IDs) docker run searchspring-mcp # Or with optional environment variables docker run -e SEARCHSPRING_SITE_ID=your_site_id searchspring-mcp ``` **Security Features**: Non-root user, minimal Alpine base, production-optimized ### Kubernetes Deployment ```yaml apiVersion: apps/v1 kind: Deployment metadata: name: searchspring-mcp spec: replicas: 2 selector: matchLabels: app: searchspring-mcp template: metadata: labels: app: searchspring-mcp spec: containers: - name: searchspring-mcp image: searchspring-mcp:latest ports: - containerPort: 3000 # Environment variables are optional env: - name: SEARCHSPRING_TIMEOUT value: "10000" ``` ## 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

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/yangjeep/playground-searchspring-api-assist-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server