What is Spryker Mcp Server

Spryker MCP Server is a Model Context Protocol (MCP) server designed for seamless integration with the Spryker e-commerce platform APIs, enabling AI assistants to interact with e-commerce functionalities through standardized MCP tools.

Use cases

Use cases include enabling AI assistants to help customers find products, manage shopping carts, assist with checkout processes, and provide personalized recommendations based on user queries.

How to use

To use Spryker MCP Server, developers can set up the server in a development or testing environment. It is primarily intended for demonstration, showcasing integration capabilities, and educational purposes. For production use, consult Spryker’s professional services team.

Key features

Key features include natural language product search, intelligent filtering and sorting, shopping cart management, AI-guided checkout assistance, customer authentication, and support for multiple transport methods (stdio, HTTP, SSE). It also offers robust error handling and is built using TypeScript for type safety.

Where to use

Spryker MCP Server is suitable for e-commerce platforms that require AI integration for enhanced customer interactions, product discovery, and streamlined shopping experiences.

Spryker MCP Server

A Model Context Protocol (MCP) server that provides seamless integration with Spryker e-commerce platform APIs. This server enables AI assistants to interact with Spryker’s e-commerce functionality through standardized MCP tools.

⚠️ DEMO PREVIEW DISCLAIMER

This is a demo preview repository showcasing the capabilities of Spryker with Model Context Protocol (MCP).

This repository is intended for:

• Demonstration purposes only
• Showcasing Spryker-MCP integration capabilities
• Development and testing environments
• Educational and evaluation purposes

Do not use this in production environments. This demo version may contain:

• Simplified security implementations
• Incomplete error handling for production scenarios
• Development-focused configurations
• Limited scalability optimizations

For production implementations, please consult with Spryker’s professional services team for proper enterprise-grade solutions.

🚀 Features

Core Capabilities

Product Discovery & Search

• Natural language product search (“Find me wireless headphones under $200”)
• Intelligent filtering, sorting, comparison and recommendations
• Real-time inventory and pricing information

Shopping Cart Management

• Add/remove items with conversational commands
• Cart optimization suggestions
• Support for both guest and authenticated customers

Checkout & Orders

• AI-guided checkout assistance
• Payment and shipping option recommendations
• Order tracking and history access for authenticated customers
• Support for both guest and authenticated customers

Customer Experience

• Customer authentication
• Guest customers supported

Technical Excellence

• Multiple Transport Support: stdio, HTTP, and SSE transports for flexible integration
• TypeScript: Full type safety with strict compilation settings
• Modern Architecture: Clean separation of concerns with dependency injection
• Robust Error Handling: Error tracking and recovery
• Structured Logging: JSON-based logging with multiple levels and metadata
• Configuration Management: Environment-based configuration with validation
• API Resilience: Retry logic, timeouts, and graceful degradation
• Testing: Unit and integration test coverage

📋 Prerequisites

• Node.js: Version 18.0.0 or higher
• npm: Version 8.0.0 or higher
• Spryker API: Access to a Spryker Commerce OS API endpoint

🛠️ Installation & Usage

Option 1: NPX (Recommended)

Run directly without installation:

npx @spryker-sdk/spryker-mcp-server

Option 2: Global Installation

Install globally and run:

npm install -g @spryker-sdk/spryker-mcp-server
spryker-mcp-server

Option 3: Local Installation

Install in your project:

npm install @spryker-sdk/spryker-mcp-server
npx spryker-mcp-server

Option 4: Development Setup

Clone and build from source:

git clone https://github.com/spryker-sdk/spryker-mcp-server.git
cd spryker-mcp-server
npm install
npm run build
npm start

⚙️ Configuration

The server uses environment variables for configuration. Create a .env file or set these variables:

Required Variables

# Spryker API Configuration
SPRYKER_API_BASE_URL=https://your-spryker-api.com
SPRYKER_API_TIMEOUT=30000
SPRYKER_API_RETRY_ATTEMPTS=3
SPRYKER_API_RETRY_DELAY=1000

# Server Configuration
MCP_SERVER_NAME=spryker-mcp-server
MCP_SERVER_VERSION=1.0.0

# Logging Configuration (optional)
LOG_LEVEL=info
LOG_FORMAT=json

# MCP Transport Configuration (optional)
MCP_TRANSPORT=stdio                 # Transport type: stdio, http, or sse
MCP_HTTP_PORT=3000                 # HTTP port for http/sse transport
MCP_HTTP_HOST=localhost            # HTTP host for http/sse transport  
MCP_HTTP_ENDPOINT=/mcp             # HTTP endpoint path

Configuration Schema

All configuration is validated using Zod schemas:

• SPRYKER_API_BASE_URL: Valid HTTPS URL to Spryker Glue API
• SPRYKER_API_TIMEOUT: Request timeout in milliseconds (default: 30000)
• SPRYKER_API_RETRY_ATTEMPTS: Number of retry attempts (default: 3)
• SPRYKER_API_RETRY_DELAY: Delay between retries in milliseconds (default: 1000)

🚀 Usage

Transport Options

The server supports three transport modes:

1. stdio Transport (Default)

Traditional standard input/output communication for MCP clients:

# Using npm scripts
npm run start:stdio

# Using the binary directly
npx spryker-mcp-server --transport stdio

2. HTTP Transport

HTTP-based communication with SSE for real-time updates:

# Using npm scripts
npm run start:http

# Using the binary directly
npx spryker-mcp-server --transport http --port 3000 --host localhost

# Access endpoints:
# Health check: http://localhost:3000/health
# MCP endpoint: http://localhost:3000/mcp

3. SSE Transport

Server-Sent Events for real-time web applications:

# Using npm scripts  
npm run start:sse

# Using the binary directly
npx spryker-mcp-server --transport sse --port 3000 --host localhost --endpoint /mcp

Development Mode

npm run dev

Production Mode

npm run build
npm start

🛡️ MCP Integration

Claude Desktop Configuration (stdio transport)

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "spryker": {
      "command": "npx",
      "args": [
        "spryker-mcp-server"
      ],
      "env": {
        "SPRYKER_API_BASE_URL": "https://your-spryker-api.com"
      }
    }
  }
}

See Claude Desktop MCP Integration for more details on MCP integration with Claude Desktop.

HTTP/SSE Transport Integration

For web applications using HTTP or SSE transport:

// HTTP client example
const response = await fetch('http://localhost:3000/mcp', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'tools/list',
    params: {}
  })
});

// SSE client example
const eventSource = new EventSource('http://localhost:3000/mcp');
eventSource.onmessage = function(event) {
  const message = JSON.parse(event.data);
  console.log('Received:', message);
};

VS Code MCP Extension

Add to .vscode/mcp.json:

{
  "servers": {
    "spryker": {
      "command": "npx",
      "args": [
        "spryker-mcp-server"
      ]
    }
  }
}

See VS Code MCP Extension for more details on MCP integration with VS Code.

🔧 Available Tools

The server provides 11 MCP tools for e-commerce operations:

Product Management

• Product Search (product-search) - Advanced product catalog search with filtering
• Product Details (get-product) - Retrieve detailed product information

Authentication & User Management

• Authentication (authenticate) - Customer login and guest session creation

Shopping Cart Operations

• Add to Cart (add-to-cart) - Add products to authenticated customer carts
• Guest Add to Cart (guest-add-to-cart) - Add products to guest user carts
• Get Cart (get-cart) - Retrieve cart contents and totals
• Remove from Cart (remove-from-cart) - Remove items from carts
• Update Cart Item (update-cart-item) - Modify cart item quantities

Order Processing & Checkout

• Get Checkout Data (get-checkout-data) - Retrieve payment methods and shipping options
• Checkout (checkout) - Process complete order checkout with payment and shipping
• Get Order (get-order) - Retrieve order details and history

Product Search (product-search)

Search for products with advanced filtering capabilities.

Parameters:

• q (string, optional): Search query text
• rangeFacets (array, optional): Range facet values for filtering (e.g., price ranges). Each object contains:
  • name (string, required): Range facet name
  • min (number, optional): Minimum value
  • max (number, optional): Maximum value
• valueFacets (array, optional): Exact value facet filters (e.g., brands, labels). Each object contains:
  • name (string, required): Facet name
  • value (string, required): Facet value
• sort (string, optional): Sort parameter name for ordering results
• ipp (number, default: 20): Items per page (1-100)
• page (number, default: 0): Page offset for pagination (0-based)

Example:

{
  "q": "laptop",
  "rangeFacets": [
    {
      "name": "price",
      "min": 500,
      "max": 2000
    }
  ],
  "ipp": 10,
  "page": 0
}

Authentication (authenticate)

Authenticate customers and obtain access tokens, or create guest sessions.

Parameters:

• username (string, optional): Customer username or email
• password (string, optional): Customer password

Note: If username and password are not provided, a guest session token will be generated for anonymous shopping.

Product Details (get-product)

Retrieve detailed information about a specific product.

Parameters:

• sku (string, required): Product SKU

Add to Cart (add-to-cart)

Add products to a customer’s shopping cart.

Parameters:

• customerToken (string, required): Customer access token
• sku (string, required): Product SKU
• quantity (number, default: 1): Quantity to add

Guest Add to Cart (guest-add-to-cart)

Add products to cart for non-authenticated users.

Parameters:

• token (string, required): Guest session token
• sku (string, required): Product SKU
• quantity (number, default: 1): Quantity to add

Get Cart (get-cart)

Retrieve current cart contents and totals.

Parameters:

• token (string, required): Customer access token or guest token

Remove from Cart (remove-from-cart)

Remove an item from the shopping cart.

Parameters:

• token (string, required): Customer access token or guest token
• cartId (string, required): ID of the cart containing the item
• itemId (string, required): ID of the item to remove

Update Cart Item (update-cart-item)

Update the quantity of an item in the shopping cart.

Parameters:

• token (string, required): Customer access token or guest token
• cartId (string, required): ID of the cart containing the item
• itemId (string, required): ID of the item to update
• quantity (number, required): New quantity for the item

Get Checkout Data (get-checkout-data)

Get checkout data including payment methods, shipment methods, and customer addresses.

Parameters:

• token (string, required): Customer access token or guest token
• cartId (string, required): ID of the cart to get checkout data for

Checkout (checkout)

Process order checkout with payment and shipping.

Parameters:

• token (string, required): Customer access token or guest token
• cartId (string, required): Cart ID to checkout
• customerData (object, required): Customer information:
  • email (string, required): Customer email address
  • firstName (string, required): Customer first name
  • lastName (string, required): Customer last name
  • salutation (string, optional): Customer salutation (Mr, Mrs, Ms)
• billingAddress (object, required): Billing address:
  • firstName (string, required): First name
  • lastName (string, required): Last name
  • address1 (string, required): Primary address line
  • address2 (string, required): Secondary address line
  • zipCode (string, required): ZIP/Postal code
  • city (string, required): City
  • salutation (string, optional): Salutation
  • country (string, optional): Country ISO2 code (default: DE)
  • company (string, optional): Company name
  • phone (string, optional): Phone number
• shippingAddress (object, required): Shipping address with same structure as billing address
• paymentMethod (object, required): Payment method information:
  • provider (string, optional): Payment provider name (default: DummyPayment)
  • method (string, optional): Payment method (default: invoice)
• shipmentMethod (object, required): Shipment method:
  • id (number, required): Shipment method ID

Get Order (get-order)

Retrieve order details and history.

Parameters:

• token (string, required): Customer access token
• orderReference (string, optional): Specific order reference to retrieve. If not provided, returns all orders

🎯 Available Prompts

The server includes 5 prompts that provide context-aware guidance for different e-commerce scenarios. Each prompt is designed to help AI assistants understand how to effectively use the available tools.

Product Search (product-search)

Guides users through product discovery and search operations.

Parameters:

• query (string, optional): Product search query
• category (string, optional): Specific product category
• price_range (string, optional): Price range in format “min-max”
• brand (string, optional): Specific brand to filter by

Cart Management (cart-management)

Assists with shopping cart operations and checkout guidance.

Parameters:

• action (string, required): Cart action - add, remove, view, update, or checkout
• product_sku (string, optional): Product SKU for add/remove operations
• quantity (number, optional): Quantity for add/update operations
• customer_type (string, optional): Customer type - authenticated or guest

Customer Service (customer-service)

Provides support for customer authentication and account issues.

Parameters:

• support_type (string, required): Type of support needed - login, order_status, account_info, or general
• username (string, optional): Customer username or email for authentication
• order_reference (string, optional): Order reference number for order inquiries

Order Fulfillment (order-fulfillment)

Guides through the complete order process from cart to completion.

Parameters:

• customer_token (string, optional): Customer authentication token
• billing_address (object, optional): Billing address information
• shipping_address (object, optional): Shipping address information
• payment_method (string, optional): Selected payment method

Product Recommendations (product-recommendations)

Generates personalized product recommendations based on preferences.

Parameters:

• customer_token (string, optional): Customer authentication token
• category_preference (string, optional): Preferred product categories
• price_range (string, optional): Preferred price range
• occasion (string, optional): Special occasion or context
• recently_viewed (string, optional): Recently viewed products

Using Prompts

Prompts are automatically available through the MCP protocol and provide context-aware guidance that helps AI assistants:

1. Understand context: Each prompt provides specific guidance for different e-commerce scenarios
2. Use tools effectively: Prompts explain which tools to use and how to combine them
3. Handle edge cases: Include guidance for error handling and alternative approaches
4. Provide better UX: Structured templates ensure consistent, helpful responses

🏗️ Architecture

Project Structure

src/
├── config/           # Configuration management
├── services/         # External service integrations
├── tools/           # MCP tool implementations
├── utils/           # Shared utilities
└── index.ts         # Main server entry point

Key Components

Configuration (src/config/)

• Environment variable validation with Zod
• Type-safe configuration objects
• Default value management

Services (src/services/)

• SprykerApiService: HTTP client with retry logic and error handling
• Request/response transformation
• Authentication management

Tools (src/tools/)

• Individual tool implementations
• Centralized tool registry
• Input validation with Zod schemas

Utilities (src/utils/)

• Structured logging with metadata support
• Environment validation
• Error handling utilities

🧪 Development

Code Quality

# Linting
npm run lint
npm run lint:fix

# Type checking
npm run type-check

# Testing
npm test
npm run test:watch
npm run test:coverage

Build Process

# Development build with watch
npm run dev

# Production build
npm run build

# Clean build artifacts
npm run clean

🤝 Contributing

Development Setup

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Install dependencies: npm install
4. Make your changes following the coding standards
5. Add tests for new functionality
6. Run the test suite: npm test
7. Commit your changes: git commit -m 'Add amazing feature'
8. Push to the branch: git push origin feature/amazing-feature
9. Open a Pull Request

Coding Standards

• TypeScript with strict type checking
• ESLint configuration with recommended rules
• Conventional commit messages
• JSDoc documentation
• Good test coverage for core functionality (current: ~94%)

📚 API Reference

Spryker API Compatibility

This server is compatible with Spryker Commerce OS Glue API:

• API Version: Latest stable version
• Authentication: Bearer tokens
• Response Format: JSON:API specification

Error Handling

All tools return standardized error responses:

{
  "content": [
    {
      "type": "text",
      "text": "Error: Detailed error message with context"
    }
  ]
}

📖 Changelog

Version 0.0.1 (Current)

• ✅ Initial TypeScript implementation
• ✅ Core Spryker API integration
• ✅ Eleven essential MCP tools (product search, authentication, cart management, checkout, order management)
• ✅ Five contextual MCP prompts for e-commerce guidance
• ✅ Error handling and logging
• ✅ Configuration management with validation
• ✅ Multiple transport support (stdio, HTTP, SSE)

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙋‍♂️ Support

Getting Help

• Documentation: Check this README and inline code documentation
• Issues: GitHub Issues

Common Issues

1. Connection Errors: Verify SPRYKER_API_BASE_URL is correct and accessible
2. Authentication Failures: Ensure customer tokens are valid and not expired
3. Tool Not Found: Check tool registration in src/tools/index.ts

---

🔧 Logging & Debugging

Dynamic Log Level Control

The server supports runtime log level changes through the MCP logging/setLevel method, allowing you to adjust logging verbosity without restarting the server.

Supported Log Levels:

• debug - Detailed debugging information
• info - General operational messages (default)
• notice - Significant events (mapped to info)
• warning - Warning conditions
• error - Error conditions
• critical - Critical conditions (mapped to error)
• alert - Alert conditions (mapped to error)
• emergency - Emergency conditions (mapped to error)

MCP Request Example:

{
  "method": "logging/setLevel",
  "params": {
    "level": "debug"
  }
}

Enhanced Response Format:
The setLevel method returns a detailed response confirming the level change:

{
  "message": "Log level changed from 'info' to 'debug'",
  "previousLevel": "info",
  "newLevel": "debug",
  "requestedLevel": "debug",
  "timestamp": "2025-06-03T16:30:00.000Z"
}

Response Fields:

• message - Human-readable confirmation message
• previousLevel - Log level before the change
• newLevel - Log level after the change
• requestedLevel - The level that was requested (may differ if invalid)
• timestamp - ISO timestamp when the change occurred

Claude Desktop Usage:
When using with Claude Desktop, you can ask the assistant to change the log level:

“Please set the logging level to debug so I can see more detailed information”

The assistant will receive the detailed response and can inform you of the successful change.

Benefits:

• Real-time debugging: Increase verbosity when troubleshooting issues
• Performance optimization: Reduce logging in production environments
• Flexible monitoring: Adjust detail level based on current needs
• No service interruption: Changes take effect immediately
• Confirmation feedback: Detailed response confirms the change was applied

Log Format

All logs are structured JSON with consistent fields:

{
  "timestamp": "2025-06-03T16:30:00.000Z",
  "level": "info",
  "component": "SprykerMCP",
  "message": "Tool executed successfully",
  "metadata": {
    "toolName": "product-search",
    "duration": 245
  }
}