Maple Cart MCP - E-Commerce Shopping Assistant

A comprehensive Model Context Protocol (MCP) server that provides a complete e-commerce solution with product search, shopping cart management, secure payment processing, and order fulfillment.

🎯 Features

• 🔍 Product Search: Search Google Shopping (Canada) for products using SerpAPI
• 🛒 Shopping Cart Management: Add, view, remove, and clear cart items with mandatory pricing validation
• 💳 Secure Payment Processing: Complete Stripe integration with payment intents and hosted checkout
• 📦 Order Management: Order status tracking and webhook automation
• 🔒 Payment Security: Strict payment enforcement - orders only created after successful payment

🚀 Quick Start

Prerequisites

• Node.js 18+ (ES Modules required)
• API Keys: SerpAPI (product search) + Stripe (payments)
• MCP Client: ChatGPT MCP App Connector , Claude Desktop, VS Code with MCP extension, or custom client

Installation

1. Clone and Install

   git clone <repository-url>
   cd maple-cart-mcp
   npm install
   

2. Environment Configuration

   # Create environment file
   cp .env.example .env
   
   # Required environment variables:
   SERPAPI_KEY=your_serpapi_key_here
   STRIPE_SECRET_KEY=sk_test_or_live_your_stripe_key
   STRIPE_WEBHOOK_SECRET=whsec_your_webhook_secret
   
   # Optional configuration:
   NODE_ENV=development
   PORT=3000
   

3. Start the Server

   # For MCP integration (recommended)
   npm run start:stdio
   
   # For HTTP testing and development
   npm start
   
   # Development mode with auto-restart
   npm run dev
   

MCP Client Integration

Add to your MCP client configuration (e.g., Claude Desktop):

{
  "mcpServers": {
    "maple-cart": {
      "command": "node",
      "args": ["server.js", "--stdio"],
      "cwd": "/path/to/maple-cart-mcp"
    }
  }
}

🛠️ MCP Tools Reference

Core Shopping Tools

search_products

Search for products on Google Shopping (Canada)

{
  query: string;           // Search query (e.g., "iPhone 15")
  intent?: string;         // Shopping intent/purpose
  budget?: number;         // Budget limit
}

cart_add

Add products to cart with mandatory pricing validation

{
  query?: string;          // Search for lowest-priced product
  product?: {              // OR add specific product
    title: string;
    price: string;         // REQUIRED - must include price
    description?: string;
    thumbnail?: string;
    quantity?: number;
  };
  sessionId?: string;      // Optional session ID
}

cart_view

View current cart contents

{
  sessionId?: string;      // Optional session ID
}

cart_remove

Remove specific item from cart

{
  index: number;           // Item index to remove
  sessionId?: string;      // Optional session ID
}

cart_clear

Clear all items from cart

{
  sessionId?: string;      // Optional session ID
}

Enhanced Checkout Tools

checkout_create_payment_intent

Initialize payment and create pending order

{
  sessionId?: string;      // Optional session ID
  shipping?: string;       // Shipping preference
}

checkout_create_payment_url

Generate hosted Stripe checkout URL

{
  sessionId?: string;      // Optional session ID
  returnUrl?: string;      // Success return URL
  cancelUrl?: string;      // Cancel return URL
  shipping?: string;       // Shipping preference
}

checkout_order_status

Monitor order and payment status

{
  sessionId?: string;          // Optional session ID
  paymentIntentId?: string;    // Optional payment intent ID
}

checkout_complete_flow

Complete one-step checkout process

{
  sessionId?: string;      // Optional session ID
  shipping?: string;       // Shipping preference
  returnUrl?: string;      // Success return URL
  cancelUrl?: string;      // Cancel return URL
}

Order Management Tools

orders_view

View all confirmed orders

{
  sessionId?: string;      // Optional session ID
}

validate_payment_enforcement

Verify payment security and system integrity

{} // No parameters required

🛠️ Setup

1. Install Dependencies

   npm install
   

2. Environment Setup

   cp .env.example .env
   # Edit .env with your API keys:
   # SERPAPI_KEY=your_serpapi_key
   # STRIPE_SECRET_KEY=your_stripe_secret_key  
   # STRIPE_WEBHOOK_SECRET=your_webhook_secret
   

3. Run Server

   # For MCP integration (stdio)
   node server.js --stdio
   
   # For HTTP testing
   node server.js
   

� Usage Examples

Complete Shopping Flow

// 1. Search for products
search_products({ 
  query: "iPhone 15 128GB", 
  intent: "personal use",
  budget: 1200 
});

// 2. Add lowest-priced product to cart (automatic pricing)
cart_add({ query: "iPhone 15 128GB" });

// OR: Add specific product with manual pricing
cart_add({ 
  product: {
    title: "iPhone 15 128GB - Blue",
    price: "$999.99",
    description: "Latest iPhone model with 128GB storage"
  }
});

// 3. Review cart
cart_view();

// 4. Complete checkout in one step
checkout_complete_flow({
  shipping: "express",
  returnUrl: "https://mystore.com/success",
  cancelUrl: "https://mystore.com/cancel"
});

// 5. Monitor order status
checkout_order_status({ paymentIntentId: "pi_1234..." });

Step-by-Step Checkout

// Step 1: Create payment intent
checkout_create_payment_intent({ shipping: "standard" });

// Step 2: Generate payment URL
checkout_create_payment_url({
  returnUrl: "https://mystore.com/success",
  cancelUrl: "https://mystore.com/cancel"
});

// Step 3: Customer completes payment via URL
// Step 4: Check payment and order status
checkout_order_status({ paymentIntentId: "pi_1234..." });

// Step 5: View confirmed orders
orders_view();

Cart Management

// Add multiple products
cart_add({ query: "wireless headphones" });
cart_add({ query: "phone case iPhone 15" });

// Remove specific item (by index)
cart_remove({ index: 0 });

// Clear entire cart
cart_clear();

// View cart anytime
cart_view();

� Project Architecture

maple-cart-mcp/
├── server.js                    # Main MCP server with all tools and HTTP endpoints
├── package.json                 # Dependencies and scripts
├── mcp.json                    # MCP configuration
├── .env.example                # Environment template
├── 
├── src/                        # Core modules
│   ├── cart.js                 # Shopping cart management (in-memory store)
│   ├── order.js                # Order lifecycle and status tracking
│   ├── payment.js              # Stripe payment processing integration
│   ├── search.js               # Product search via SerpAPI/Google Shopping
│   └── webhook.js              # Stripe webhook handling for order automation
├── 
├── README.md                   # This documentation

🧪 Testing & Development

Available Scripts

# Start MCP server (stdio mode)
npm run start:stdio

# Start HTTP server (development/testing)
npm start

# Development mode with auto-restart
npm run dev

# Production mode
npm run prod

# Validate JavaScript syntax
npm run validate

# Debug with MCP Inspector
npm run inspect

## � Configuration

### Required API Keys

| Service | Purpose | Format | Where to Get |
|---------|---------|--------|-------------|
| **SerpAPI** | Product search on Google Shopping | `your_serpapi_key_here` | [serpapi.com](https://serpapi.com) |
| **Stripe Secret** | Payment processing | `sk_test_...` or `sk_live_...` | [Stripe Dashboard](https://dashboard.stripe.com/apikeys) |
| **Stripe Webhook** | Order automation | `whsec_...` | [Stripe Webhooks](https://dashboard.stripe.com/webhooks) |

### Environment Variables
```bash
# Required
SERPAPI_KEY=your_serpapi_key_here
STRIPE_SECRET_KEY=sk_test_51ABC...
STRIPE_WEBHOOK_SECRET=whsec_123...

# Optional
NODE_ENV=development          # development | production
PORT=4000                    # HTTP server port
CORS_ORIGIN=*               # CORS allowed origins
RATE_LIMIT_WINDOW=900000    # Rate limit window (15 min)
RATE_LIMIT_MAX=100          # Max requests per window

Stripe Webhook Configuration

1. Create Webhook Endpoint in Stripe Dashboard
2. Endpoint URL: https://yourdomain.com/webhook
3. Listen to Events:
   • payment_intent.succeeded
   • payment_intent.payment_failed
4. Copy Webhook Secret to STRIPE_WEBHOOK_SECRET

Maple Cart MCP - Bringing AI-powered e-commerce to Model Context Protocol 🍁🛒