Stateset MCP Server

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

Variable	Description	Default
STATESET_API_KEY	Your StateSet API key	Required
STATESET_BASE_URL	StateSet API base URL	https://api.stateset.io/v1
STATESET_API_VERSION	API version	v1

Rate Limiting

Variable	Description	Default
REQUESTS_PER_HOUR	Maximum API requests per hour	1000
REQUESTS_PER_MINUTE	Maximum API requests per minute	50
BURST_SIZE	Extra requests allowed in short bursts	10
RETRY_ATTEMPTS	Number of retry attempts for failed requests	3
RETRY_DELAY	Initial retry delay in milliseconds	1000

Caching

Variable	Description	Default
CACHE_ENABLED	Enable/disable caching	true
CACHE_TTL	Cache time-to-live in seconds	300
CACHE_MAX_SIZE	Maximum number of items to cache	1000
CACHE_STRATEGY	Cache eviction strategy (lru/lfu/fifo)	lru

Redis Configuration (Optional)

Variable	Description	Default
REDIS_HOST	Redis server hostname	localhost
REDIS_PORT	Redis server port	6379
REDIS_PASSWORD	Redis authentication password	(none)
REDIS_DB	Redis database number	0

Circuit Breaker

Variable	Description	Default
CIRCUIT_BREAKER_ENABLED	Enable circuit breaker protection	true
CIRCUIT_BREAKER_THRESHOLD	Failures before circuit opens	5
CIRCUIT_BREAKER_TIMEOUT	Time circuit stays open (ms)	60000
CIRCUIT_BREAKER_RESET_TIMEOUT	Time before reset attempt (ms)	30000

Feature Flags

Variable	Description	Default
FEATURE_CACHING	Enable API response caching	true
FEATURE_METRICS	Enable Prometheus metrics	true
FEATURE_HEALTH_CHECK	Enable health check endpoints	true
FEATURE_WEBSOCKET	Enable WebSocket real-time updates	true
FEATURE_CIRCUIT_BREAKER	Enable circuit breaker	true
FEATURE_COMPRESSION	Enable response compression	true
FEATURE_OPEN_API_CONVERTER	Enable OpenAPI conversion	false
FEATURE_ENABLE_TELEMETRY	Enable OpenTelemetry tracing	false

Server Configuration

Variable	Description	Default
NODE_ENV	Environment (development/staging/production/test)	production
LOG_LEVEL	Logging level (trace/debug/info/warn/error/fatal)	info
API_TIMEOUT_MS	Request timeout in milliseconds	10000
WEBSOCKET_PORT	WebSocket server port	8081
METRICS_INTERVAL	Metrics collection interval (ms)	60000
HEALTH_CHECK_INTERVAL	Health check interval (ms)	30000

💡 Usage Examples

Basic Operations

// Create a customer
const customer = await client.callTool({
  name: 'stateset_create_customer',
  arguments: {
    email: '[email protected]',
    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

Script	Description
npm run dev	Start development server with hot reload
npm run build	Build production bundle
npm run test	Run all tests
npm run test:watch	Run tests in watch mode
npm run test:coverage	Generate coverage report
npm run lint	Run ESLint
npm run format	Format code with Prettier
npm run docs	Generate API documentation

🧪 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: '[email protected]',
      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: [email protected]
• 💬 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