# 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