StateSet MCP Server

A production-ready Model Context Protocol (MCP) server for StateSet API integration, providing comprehensive e-commerce and supply chain operations management through a standardized interface. Built with enterprise-grade reliability, performance, and observability.

📖 Documentation

• Architecture Guide - System design and component overview
• Testing Guide - Testing strategy and coverage
• API Documentation - Generated TypeDoc API reference
• Contributing Guide - How to contribute

🚀 Features

Core Capabilities

• 166 MCP Tools: Complete CRUD operations for orders, returns, inventory, products, customers, shipments, manufacturing, and financial operations with full workflow support
• Advanced Search: Multi-filter search with sorting, pagination, aggregations, and full-text search across all resources
• Batch Operations: Execute multiple operations atomically with configurable parallelism and error handling
• Real-Time Updates: WebSocket support for live event streaming and resource change notifications
• Resource Templates: URI-based resource access (e.g., stateset-order:///ORD-123)

Enterprise-Grade Reliability

• Intelligent Caching: LRU/LFU/FIFO cache strategies with adaptive TTL, automatic cache warming, and optional Redis support for distributed caching
• Circuit Breaker: Automatic failure detection and recovery to prevent cascade failures
• Rate Limiting: Token bucket algorithm with per-tool limits and burst support
• Connection Pooling: Efficient connection reuse with health checks and automatic reconnection
• Graceful Degradation: Automatic fallback strategies with stale cache data when services are unavailable
• Retry Strategies: Exponential backoff with jitter and intelligent error classification
• Graceful Shutdown: Proper cleanup of connections, caches, and background tasks

Security & Validation

• Input Sanitization: XSS prevention, SQL injection protection, command injection detection, and HTML tag stripping
• Path Traversal Protection: Detection and blocking of path traversal attempts
• API Key Security: Automatic redaction in logs and error messages with sensitive data masking
• Request Validation: Zod schemas with comprehensive type checking
• CORS & Helmet: Security headers and cross-origin request protection

Observability

• Structured Logging: Pino-based JSON logging with correlation IDs and request context
• Request Correlation: Correlation IDs propagated through async operations for distributed tracing
• Prometheus Metrics: Request counts, durations, error rates, cache hit rates, and queue lengths
• Tool Metrics: Per-tool execution tracking with duration histograms, error rates, and category analysis
• Health Checks: Liveness and readiness probes for Kubernetes deployments
• OpenTelemetry: Distributed tracing support (optional)
• Performance Monitoring: Request timing, retry tracking, circuit breaker status, and slow tool detection

Developer Experience

• Type-Safe: Built with TypeScript 5.7 for maximum type safety and IntelliSense support
• Well-Tested: 297 passing tests across 21 test suites with unit and E2E coverage
• Hot Reloading: Development mode with automatic restart on file changes
• OpenAPI Converter: Generate MCP tools from OpenAPI specifications
• Comprehensive Documentation: Detailed tool descriptions optimized for AI understanding

📋 Table of Contents

• Installation
• Quick Start
• Configuration
• Usage Examples
• Architecture
• API Reference
• Development
• Testing
• Deployment
• Monitoring
• Troubleshooting
• Performance Tips
• Contributing
• License
• Support
• Roadmap

🔧 Installation

Using npm

npm install -g stateset-mcp-server

Using Docker

docker pull stateset/mcp-server:latest

From Source

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

🏃 Quick Start

1. Installation

# Clone the repository
git clone https://github.com/stateset/mcp-server.git
cd mcp-server

# Install dependencies
npm install

# Build the project
npm run build

2. Configuration

# Copy environment template
cp .env.example .env

# Edit .env with your StateSet API credentials
# Required: STATESET_API_KEY=your_api_key_here

3. Run the Server

# Development mode with hot reload
npm run dev

# Production mode
npm start

# Using Docker
docker build -t stateset-mcp-server .
docker run --env-file .env stateset-mcp-server

4. Connect with MCP Client

The server uses stdio transport for MCP communication:

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

// Create client
const client = new Client({
  name: 'my-app',
  version: '1.0.0',
});

// Create stdio transport
const transport = new StdioClientTransport({
  command: 'node',
  args: ['dist/index.js'],
  env: {
    STATESET_API_KEY: 'your_api_key_here'
  }
});

// Connect
await client.connect(transport);

// List available tools
const tools = await client.listTools();
console.log('Available tools:', tools.tools.length);

// Call a tool
const result = await client.callTool({
  name: 'stateset_list_orders',
  arguments: { page: 1, per_page: 10 }
});

5. WebSocket Connection (Optional)

For real-time updates, connect to the WebSocket server:

import WebSocket from 'ws';

const ws = new WebSocket('ws://localhost:8081');

// Subscribe to order updates
ws.send(JSON.stringify({
  type: 'subscribe',
  channel: 'orders',
  filter: { status: 'pending' }
}));

// Listen for updates
ws.on('message', (data) => {
  const event = JSON.parse(data);
  console.log('Received update:', event);
});

⚙️ Configuration

Environment Variables

Copy .env.example to .env and configure the following variables:

Required Configuration

Rate Limiting

Caching

Redis Configuration (Optional)

Circuit Breaker

Feature Flags

Server Configuration

💡 Usage Examples

Basic Operations

// Create a customer
const customer = await client.callTool({
  name: 'stateset_create_customer',
  arguments: {
    email: 'customer@example.com',
    name: 'John Doe',
    address: {
      line1: '123 Main St',
      city: 'San Francisco',
      state: 'CA',
      postal_code: '94102',
      country: 'US'
    }
  }
});

// Create an order
const order = await client.callTool({
  name: 'stateset_create_order',
  arguments: {
    customer_id: customer.id,
    items: [
      { product_id: 'PROD-001', quantity: 2, price: 29.99 },
      { product_id: 'PROD-002', quantity: 1, price: 49.99 }
    ],
    shipping_address: {
      line1: '123 Main St',
      city: 'San Francisco',
      state: 'CA',
      postal_code: '94102',
      country: 'US'
    }
  }
});

// Create a shipment
const shipment = await client.callTool({
  name: 'stateset_create_shipment',
  arguments: {
    order_id: order.id,
    carrier: 'UPS',
    tracking_number: '1Z999AA10123456784'
  }
});

// Mark as shipped
await client.callTool({
  name: 'stateset_mark_shipment_shipped',
  arguments: { shipment_id: shipment.id }
});

Advanced Search

// Search orders by multiple criteria
const searchResults = await client.callTool({
  name: 'stateset_advanced_search',
  arguments: {
    resource: 'orders',
    filters: [
      { field: 'status', operator: 'eq', value: 'pending' },
      { field: 'total', operator: 'gt', value: 100 },
      { field: 'created_at', operator: 'gte', value: '2024-01-01T00:00:00Z' }
    ],
    sort: [
      { field: 'created_at', order: 'desc' }
    ],
    page: 1,
    per_page: 20
  }
});

// Full-text search across resources
const textSearch = await client.callTool({
  name: 'stateset_full_text_search',
  arguments: {
    query: 'laptop',
    resources: ['products', 'orders'],
    limit: 50
  }
});

// Search products with inventory
const productsInStock = await client.callTool({
  name: 'stateset_search_products_with_inventory',
  arguments: {
    min_quantity: 10,
    location: 'warehouse-1'
  }
});

Batch Operations

// Batch create multiple orders
const batchResult = await client.callTool({
  name: 'stateset_batch_create_orders',
  arguments: {
    orders: [
      { customer_id: 'CUST-1', items: [...] },
      { customer_id: 'CUST-2', items: [...] },
      { customer_id: 'CUST-3', items: [...] }
    ],
    options: {
      parallel: true,
      stopOnError: false,
      chunkSize: 10
    }
  }
});

console.log(`Success: ${batchResult.success}, Failed: ${batchResult.failed}`);

// Bulk inventory update
await client.callTool({
  name: 'stateset_batch_update_inventory',
  arguments: {
    updates: [
      { product_id: 'PROD-1', quantity_change: -5, reason: 'sale' },
      { product_id: 'PROD-2', quantity_change: 100, reason: 'restock' },
      { product_id: 'PROD-3', quantity_change: -2, reason: 'damaged' }
    ]
  }
});

// Generic batch operations
await client.callTool({
  name: 'stateset_batch_operations',
  arguments: {
    operations: [
      { type: 'create', resource: 'product', data: {...} },
      { type: 'update', resource: 'inventory', data: {...} },
      { type: 'create', resource: 'customer', data: {...} }
    ],
    options: { parallel: false, stopOnError: true }
  }
});

Return Processing Workflow

// Customer initiates return
const rma = await client.callTool({
  name: 'stateset_create_rma',
  arguments: {
    order_id: 'ORD-12345',
    items: [
      { product_id: 'PROD-001', quantity: 1, reason: 'defective' }
    ],
    reason: 'Product arrived damaged'
  }
});

// Approve the return
await client.callTool({
  name: 'stateset_approve_return',
  arguments: { rma_id: rma.id }
});

// After receiving returned items, restock
await client.callTool({
  name: 'stateset_restock_return',
  arguments: { rma_id: rma.id }
});

// Issue refund
await client.callTool({
  name: 'stateset_create_payment',
  arguments: {
    order_id: 'ORD-12345',
    amount: -29.99,
    payment_method: 'refund',
    notes: `Refund for RMA ${rma.id}`
  }
});

Manufacturing Workflow

// Create bill of materials
const bom = await client.callTool({
  name: 'stateset_create_bill_of_materials',
  arguments: {
    product_id: 'PROD-WIDGET',
    components: [
      { part_id: 'PART-001', quantity: 2, cost: 5.00 },
      { part_id: 'PART-002', quantity: 1, cost: 10.00 },
      { part_id: 'PART-003', quantity: 4, cost: 2.50 }
    ]
  }
});

// Create work order
const workOrder = await client.callTool({
  name: 'stateset_create_work_order',
  arguments: {
    product_id: 'PROD-WIDGET',
    quantity: 100,
    bom_id: bom.id,
    due_date: '2024-12-31'
  }
});

// Create purchase order for raw materials
const po = await client.callTool({
  name: 'stateset_create_purchase_order',
  arguments: {
    vendor_id: 'VENDOR-001',
    items: [
      { part_id: 'PART-001', quantity: 200, unit_price: 5.00 },
      { part_id: 'PART-002', quantity: 100, unit_price: 10.00 }
    ],
    delivery_date: '2024-12-15'
  }
});

Resource Access

// Read resource by URI
const orderResource = await client.readResource({
  uri: 'stateset-order:///ORD-12345'
});

const productResource = await client.readResource({
  uri: 'stateset-product:///PROD-001'
});

const customerResource = await client.readResource({
  uri: 'stateset-customer:///CUST-456'
});

🏗️ Architecture

Directory Structure

src/
├── auth/               # Authentication templates and types
├── config/             # Configuration management and timeouts
├── core/              # Core infrastructure
│   ├── adaptive-cache.ts        # Adaptive TTL and cache warming
│   ├── advanced-metrics.ts      # Detailed performance metrics
│   ├── batch-processor.ts       # Batch operation processing
│   ├── cache.ts                 # In-memory caching layer
│   ├── circuit-breaker.ts       # Circuit breaker pattern
│   ├── connection-pool.ts       # Connection pooling
│   ├── graceful-degradation.ts  # Fallback and degradation patterns
│   ├── health.ts                # Health check implementation
│   ├── hybrid-cache.ts          # Hybrid memory/Redis caching
│   ├── intelligent-cache.ts     # Advanced caching strategies
│   ├── metrics.ts               # Metrics collection
│   ├── openapi-converter.ts     # OpenAPI to MCP conversion
│   ├── performance-optimizer.ts # Performance tuning
│   ├── rate-limiter.ts          # Rate limiting logic
│   ├── realtime-manager.ts      # Real-time event management
│   ├── redis-cache.ts           # Redis distributed caching
│   ├── request-context.ts       # Correlation ID and request tracking
│   ├── resource-registry.ts     # Resource handler registry
│   ├── retry-strategy.ts        # Retry with exponential backoff
│   ├── tool-metrics.ts          # Per-tool metrics collection
│   ├── server-rate-limiter.ts   # Server-level rate limiting
│   ├── telemetry.ts             # OpenTelemetry integration
│   └── websocket.ts             # WebSocket server
├── middleware/        # Request/response middleware
│   ├── api-docs.ts              # API documentation
│   ├── error-handler.ts         # Error handling and formatting
│   └── security.ts              # Security middleware
├── services/          # Business logic and API clients
│   ├── enhanced-stateset-client.ts  # Enhanced API client
│   ├── mcp-client.ts                # MCP client wrapper
│   └── stateset-client.ts           # Base StateSet API client
├── tools/             # MCP tool implementations
│   ├── ai-insights.ts           # AI-powered analytics
│   ├── batch-operations.ts      # Batch operation tools
│   ├── definitions.ts           # Tool definitions
│   ├── dispatcher.ts            # Tool request dispatcher
│   ├── enhanced-tools.ts        # Enhanced tool capabilities
│   ├── openapi-tools.ts         # OpenAPI-based tools
│   ├── registry.ts              # Tool registry
│   ├── schemas.ts               # Zod validation schemas
│   └── search-tools.ts          # Advanced search tools
├── types/             # TypeScript type definitions
│   ├── api.ts                   # API types
│   ├── common.ts                # Common types
│   ├── index.ts                 # Type exports
│   ├── mcp-api.ts               # MCP API types
│   ├── resources.ts             # Resource types
│   └── tools.ts                 # Tool types
├── utils/             # Utility functions
│   ├── broadcast.ts             # Broadcasting utilities
│   ├── logger.ts                # Structured logging
│   ├── shutdown.ts              # Graceful shutdown
│   └── validation.ts            # Input validation
├── index.ts           # Entry point
└── server.ts          # Main server implementation

Key Components

• MCP Server: Stdio-based MCP protocol server with tool, resource, and prompt handlers
• StateSet API Client: Axios-based client with rate limiting, retries, and circuit breaker
• Tool Dispatcher: Routes tool calls to appropriate handlers with validation
• Resource Registry: Manages URI-based resource access (e.g., stateset-order:///ORD-123)
• Intelligent Cache: Multi-strategy caching (LRU/LFU/FIFO) with automatic invalidation
• Circuit Breaker: Prevents cascade failures with automatic recovery
• WebSocket Manager: Real-time event streaming and subscription management
• Batch Processor: Parallel and sequential batch operation execution
• Metrics Collector: Prometheus-compatible metrics with request tracking
• Error Handler: Consistent error formatting with context and request IDs

📚 API Reference

Tools

The server exposes 166 MCP tools organized by domain:

Orders & Returns (RMA)

• Create: stateset_create_order, stateset_create_rma
• Update: stateset_update_order, stateset_update_order_status
• Get: stateset_get_order, stateset_get_rma, stateset_get_order_items
• List: stateset_list_orders, stateset_list_rmas
• Delete: stateset_delete_order
• Workflows: stateset_approve_return, stateset_restock_return, stateset_cancel_order, stateset_archive_order, stateset_add_order_item

Inventory & Products

• Products: stateset_create_product, stateset_update_product, stateset_get_product, stateset_list_products, stateset_delete_product
• Product Variants: stateset_get_product_variants, stateset_create_product_variant, stateset_update_product_variant_price, stateset_delete_product_variant
• Inventory: stateset_create_inventory, stateset_update_inventory, stateset_get_inventory, stateset_list_inventories, stateset_delete_inventory
• Inventory Workflows: stateset_reserve_inventory, stateset_release_inventory, stateset_get_low_stock

Fulfillment & Shipping

• Shipments: stateset_create_shipment, stateset_get_shipment, stateset_list_shipments
• Workflows: stateset_mark_shipment_shipped, stateset_mark_shipment_delivered, stateset_track_shipment
• Fulfillment Orders: stateset_create_fulfillment_order, stateset_update_fulfillment_order, stateset_list_fulfillment_orders

Shopping Cart & Checkout

• Carts: stateset_create_cart, stateset_get_cart, stateset_delete_cart, stateset_list_carts
• Cart Items: stateset_add_cart_item, stateset_update_cart_item, stateset_remove_cart_item, stateset_clear_cart
• Checkout: stateset_create_checkout, stateset_get_checkout, stateset_update_checkout, stateset_complete_checkout, stateset_cancel_checkout

Manufacturing & Supply Chain

• Work Orders: stateset_create_work_order, stateset_update_work_order, stateset_get_work_order, stateset_list_work_orders
• Work Order Workflows: stateset_assign_work_order, stateset_start_work_order, stateset_complete_work_order, stateset_hold_work_order, stateset_cancel_work_order
• Bill of Materials: stateset_create_bill_of_materials, stateset_update_bill_of_materials, stateset_get_bill_of_materials, stateset_list_bill_of_materials
• BOM Components: stateset_get_bom_components, stateset_add_bom_component, stateset_remove_bom_component
• Purchase Orders: stateset_create_purchase_order, stateset_update_purchase_order, stateset_get_purchase_order, stateset_list_purchase_orders
• PO Workflows: stateset_approve_purchase_order, stateset_cancel_purchase_order, stateset_receive_purchase_order
• Manufacturer Orders: stateset_create_manufacturer_order, stateset_update_manufacturer_order, stateset_get_manufacturer_order, stateset_list_manufacturer_orders
• ASN: stateset_create_asn, stateset_update_asn, stateset_get_asn, stateset_list_asns
• ASN Workflows: stateset_mark_asn_in_transit, stateset_mark_asn_delivered, stateset_cancel_asn
• Item Receipts: stateset_create_item_receipt, stateset_update_item_receipt, stateset_get_item_receipt, stateset_list_item_receipts
• Suppliers: stateset_create_supplier, stateset_update_supplier, stateset_get_supplier, stateset_delete_supplier, stateset_list_suppliers

Financial Operations

• Invoices: stateset_create_invoice, stateset_update_invoice, stateset_get_invoice, stateset_list_invoices, stateset_delete_invoice
• Payments: stateset_create_payment, stateset_update_payment, stateset_get_payment, stateset_list_payments, stateset_delete_payment
• Payment Workflows: stateset_refund_payment, stateset_get_payments_by_order
• Sales Orders: stateset_create_sales_order, stateset_update_sales_order, stateset_get_sales_order, stateset_list_sales_orders
• Cash Sales: stateset_create_cash_sale, stateset_update_cash_sale, stateset_get_cash_sale, stateset_list_cash_sales

Customer Management

• stateset_create_customer - Create a new customer
• stateset_update_customer - Update customer information
• stateset_get_customer - Get customer details
• stateset_list_customers - List all customers
• stateset_delete_customer - Delete a customer
• stateset_get_customer_addresses - Get customer addresses
• stateset_add_customer_address - Add address to customer

Warranties

• stateset_create_warranty - Create warranty record
• stateset_update_warranty - Update warranty details
• stateset_get_warranty - Get warranty information
• stateset_list_warranties - List all warranties
• stateset_extend_warranty - Extend warranty period
• stateset_create_warranty_claim - Create warranty claim
• stateset_approve_warranty_claim - Approve warranty claim

Analytics & Reporting

• stateset_get_dashboard_metrics - Get key dashboard metrics
• stateset_get_sales_trends - Get sales trends over time
• stateset_get_sales_metrics - Get sales performance metrics
• stateset_get_inventory_metrics - Get inventory metrics
• stateset_get_shipment_metrics - Get shipment metrics
• stateset_get_cart_metrics - Get cart abandonment metrics

Advanced Search

• stateset_advanced_search - Multi-filter search with sorting, pagination, and aggregations
• stateset_search_orders_by_date - Find orders within date ranges
• stateset_search_products_with_inventory - Search products by stock levels
• stateset_search_customer_analytics - Analyze customer segments
• stateset_full_text_search - Full-text search across all resources

Batch Operations

• stateset_batch_operations - Execute multiple operations atomically
• stateset_batch_create_orders - Create multiple orders at once
• stateset_batch_update_inventory - Bulk inventory adjustments
• stateset_csv_import - Import data from CSV files

Monitoring & Admin

• stateset_health_check - Check server and API health
• stateset_get_api_metrics - View request metrics and performance
• stateset_tool_rate_limits - Get per-tool rate limit status
• stateset_timeout_config - View timeout configuration
• stateset_cache_stats - Get cache performance statistics
• stateset_clear_cache - Clear cached data
• stateset_websocket_stats - View WebSocket connection statistics

Resources

Access StateSet resources through URI templates. Resources provide direct access to specific records by ID:

stateset-rma:///RMA-12345
stateset-order:///ORD-123
stateset-warranty:///WAR-123
stateset-shipment:///SHIP-123
stateset-product:///PROD-789
stateset-inventory:///INV-456
stateset-customer:///CUST-789
stateset-sales-order:///SO-123
stateset-purchase-order:///PO-456
stateset-invoice:///INV-789
stateset-payment:///PAY-123

Example usage:

// Read a specific order
const response = await client.readResource({
  uri: 'stateset-order:///ORD-12345'
});

Prompts

The server provides a comprehensive prompt that includes:

• Tool Catalog: Detailed descriptions of all 166 tools organized by category
• Best Practices: Guidelines for input validation, rate limiting, error handling, search/filtering, and batch processing
• Workflow Guidance: Common patterns for orders, returns, fulfillment, manufacturing, inventory, and financial operations
• API Usage Tips: Rate limit management, caching strategies, and performance optimization

🛠️ Development

Prerequisites

• Node.js >= 18.0.0
• npm >= 8.0.0
• TypeScript >= 5.0.0

Setup

# Install dependencies
npm install

# Run in development mode
npm run dev

# Run linting
npm run lint

# Format code
npm run format

# Type check
npm run typecheck

Project Scripts

🧪 Testing

Running Tests

# Run all tests (297 passing tests)
npm test

# Run tests in watch mode
npm run test:watch

# Generate coverage report
npm run test:coverage

# Run E2E tests
npm run test:e2e

Test Results

Test Suites: 14 passed, 14 total
Tests:       203 passed, 203 total

Test Structure

tests/
├── unit/                           # Unit tests for individual components
│   ├── batch-processor.test.ts    # Batch operation processing
│   ├── cache.test.ts              # Cache functionality
│   ├── circuit-breaker.test.ts    # Circuit breaker logic
│   ├── connection-pool.test.ts    # Connection pooling
│   ├── definitions.test.ts        # Tool definitions
│   ├── dispatcher.test.ts         # Tool dispatcher
│   ├── error-handler.test.ts      # Error handling
│   ├── handlers.test.ts           # Request handlers
│   ├── health.test.ts             # Health check functionality
│   ├── intelligent-cache.test.ts  # Advanced caching
│   ├── mcp-client.test.ts         # MCP client wrapper
│   ├── metrics.test.ts            # Metrics collection
│   ├── openapi-converter.test.ts  # OpenAPI conversion
│   ├── rate-limiter.test.ts       # Rate limiting core
│   ├── redis-cache.test.ts        # Redis cache integration
│   ├── registry.test.ts           # Tool registry
│   ├── schemas.test.ts            # Zod schema validation
│   ├── server.test.ts             # Server initialization
│   ├── stateset-client.test.ts    # API client
│   ├── telemetry.test.ts          # Telemetry integration
│   ├── tool-rate-limiter.test.ts  # Tool-level rate limiting
│   ├── validation.test.ts         # Input validation
│   └── websocket.test.ts          # WebSocket functionality
├── e2e/                            # End-to-end tests
│   ├── mcp-server.e2e.test.ts     # MCP server integration
│   └── workflow.e2e.test.ts       # Business workflow tests
├── setup.ts                        # Test setup and configuration
└── teardown.ts                     # Test cleanup

Coverage

The test suite provides comprehensive coverage of:

• ✅ Core MCP server functionality
• ✅ Rate limiting and circuit breaker logic
• ✅ Caching strategies (LRU/LFU/FIFO) and Redis integration
• ✅ Input validation and sanitization
• ✅ Error handling and formatting
• ✅ WebSocket connections
• ✅ Metrics collection
• ✅ Connection pooling
• ✅ OpenAPI conversion
• ✅ Tool dispatcher and registry
• ✅ Batch processor operations
• ✅ Health check endpoints

Writing Tests

import { StateSetClient } from '../src/services/stateset-client';

describe('StateSet Client', () => {
  it('should create order successfully', async () => {
    const client = new StateSetClient(mockConfig);
    const order = await client.createOrder({
      customer_email: 'test@example.com',
      items: [{ product_id: 'PROD-1', quantity: 1, price: 10.00 }]
    });
    expect(order.id).toBeDefined();
  });
});

🚀 Deployment

Docker Deployment

The server includes a multi-stage Dockerfile optimized for production:

# Build image
docker build -t stateset-mcp-server .

# Run container
docker run -d \
  --name stateset-mcp \
  --env-file .env \
  -p 9464:9464 \
  -p 8081:8081 \
  stateset-mcp-server

The Dockerfile includes:

• Multi-stage build for smaller image size
• Non-root user for security
• dumb-init for proper signal handling
• Health checks for container orchestration
• Production-optimized dependencies

Kubernetes Deployment

apiVersion: apps/v1
kind: Deployment
metadata:
  name: stateset-mcp-server
spec:
  replicas: 3
  selector:
    matchLabels:
      app: stateset-mcp
  template:
    metadata:
      labels:
        app: stateset-mcp
    spec:
      containers:
      - name: server
        image: stateset/mcp-server:latest
        envFrom:
        - secretRef:
            name: stateset-secrets
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"

Cloud Deployment

• AWS: Use ECS or EKS with the provided Docker image
• Google Cloud: Deploy to Cloud Run or GKE
• Azure: Use Container Instances or AKS

📊 Monitoring

Health Checks

Use the MCP tool for health monitoring:

// Check overall server health
await client.callTool({
  name: 'stateset_health_check',
  arguments: { include_details: true }
});

// Returns:
// - API connection status
// - Rate limiter state
// - Circuit breaker state (open/closed/half-open)
// - Memory usage
// - Cache statistics
// - WebSocket connections

Metrics

Access detailed metrics through MCP tools:

// Get API metrics
await client.callTool({
  name: 'stateset_get_api_metrics',
  arguments: {}
});

// Get cache statistics
await client.callTool({
  name: 'stateset_cache_stats',
  arguments: { namespace: 'orders' }
});

// Get rate limit status
await client.callTool({
  name: 'stateset_tool_rate_limits',
  arguments: { category: 'read' }
});

// Get WebSocket statistics
await client.callTool({
  name: 'stateset_websocket_stats',
  arguments: {}
});

Key metrics tracked:

• totalRequests - Total API requests made
• requestsInLastHour - Recent request count
• averageRequestTime - Mean response time in ms
• queueLength - Current rate limit queue size
• cacheHitRate - Cache effectiveness percentage
• circuitBreakerState - Protection status
• activeConnections - WebSocket connections

Logging

Structured JSON logs with configurable levels:

{
  "level": "info",
  "time": "2024-01-01T12:00:00.000Z",
  "context": "api",
  "method": "POST",
  "url": "/orders",
  "duration": 123,
  "status": 200,
  "msg": "API request completed"
}

🤝 Contributing

We welcome contributions! Please see our Contributing Guide for details.

Development Workflow

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Code Standards

• Follow TypeScript best practices
• Maintain 80%+ test coverage
• Use conventional commits
• Document all public APIs
• Add JSDoc comments for complex functions

📄 License

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

🙏 Acknowledgments

• Model Context Protocol for the MCP specification
• StateSet for the comprehensive e-commerce API
• All our contributors and users

🔧 Troubleshooting

Common Issues

Server Won't Start

# Check if API key is set
echo $STATESET_API_KEY

# Verify environment file
cat .env

# Check for port conflicts
lsof -i :8081

Rate Limit Errors

// Check rate limit status
await client.callTool({
  name: 'stateset_tool_rate_limits',
  arguments: {}
});

// Increase limits in .env
REQUESTS_PER_HOUR=2000
REQUESTS_PER_MINUTE=100

Circuit Breaker Open

// Check health status
await client.callTool({
  name: 'stateset_health_check',
  arguments: { include_details: true }
});

// Circuit breaker will automatically reset after timeout
// Or disable in .env for testing:
CIRCUIT_BREAKER_ENABLED=false

Cache Issues

// Clear cache if data seems stale
await client.callTool({
  name: 'stateset_clear_cache',
  arguments: { namespace: 'orders' }
});

// Check cache statistics
await client.callTool({
  name: 'stateset_cache_stats',
  arguments: {}
});

WebSocket Connection Fails

# Check if WebSocket port is available
lsof -i :8081

# Verify WebSocket is enabled
grep FEATURE_WEBSOCKET .env

# Check firewall rules
sudo ufw status

Debug Mode

Enable detailed logging for troubleshooting:

LOG_LEVEL=debug npm run dev

🚀 Performance Tips

Optimize for High Throughput

1. Enable Caching

   CACHE_ENABLED=true
   CACHE_TTL=600  # Increase TTL for less volatile data
   CACHE_MAX_SIZE=5000
   

2. Adjust Rate Limits

   REQUESTS_PER_HOUR=5000
   REQUESTS_PER_MINUTE=200
   BURST_SIZE=50
   

3. Use Batch Operations

   // Instead of multiple single calls
   await client.callTool({
     name: 'stateset_batch_create_orders',
     arguments: { orders: [...], options: { parallel: true } }
   });
   

4. Connection Pooling

   # Already enabled by default
   # Adjust pool size if needed in code
   

5. Circuit Breaker Tuning

   CIRCUIT_BREAKER_THRESHOLD=10  # Allow more failures
   CIRCUIT_BREAKER_TIMEOUT=30000  # Faster recovery
   

📞 Support

• 📧 Email: support@stateset.io
• 💬 Discord: Join our community
• 📚 Documentation: docs.stateset.io
• 🐛 Issues: GitHub Issues
• 🌐 Website: stateset.io

🗺️ Roadmap

Recently Completed

• Redis-based distributed caching
• Hybrid memory/Redis cache with automatic fallback
• Request correlation IDs for distributed tracing
• Retry strategies with exponential backoff and jitter
• Adaptive cache with automatic TTL tuning and cache warming
• Graceful degradation with automatic fallbacks
• Per-tool metrics collection with duration histograms
• Enhanced input validation (XSS, command injection, path traversal protection)
• Sensitive data masking in logs

Coming Soon

• GraphQL API support
• Webhook event delivery
• Multi-tenant support
• Enhanced AI insights and predictions
• Integration with popular e-commerce platforms
• Real-time analytics dashboard
• Audit logging and compliance features

Under Consideration

• HTTP/REST transport alongside stdio
• gRPC support for high-performance scenarios
• Plugin system for custom tools
• Multi-region deployment support
• Advanced workflow automation

🙏 Credits

Built with:

• Model Context Protocol SDK - MCP implementation
• TypeScript - Type-safe development
• Zod - Schema validation
• Axios - HTTP client
• Pino - High-performance logging
• Jest - Testing framework
• WebSocket (ws) - Real-time communication