# 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**
   ```bash
   git clone <repository-url>
   cd maple-cart-mcp
   npm install
   ```

2. **Environment Configuration**
   ```bash
   # 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**
   ```bash
   # 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):

```json
{
  "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)
```typescript
{
  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
```typescript
{
  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
```typescript
{
  sessionId?: string;      // Optional session ID
}
```

#### `cart_remove`
Remove specific item from cart
```typescript
{
  index: number;           // Item index to remove
  sessionId?: string;      // Optional session ID
}
```

#### `cart_clear`
Clear all items from cart
```typescript
{
  sessionId?: string;      // Optional session ID
}
```

### Enhanced Checkout Tools

#### `checkout_create_payment_intent`
Initialize payment and create pending order
```typescript
{
  sessionId?: string;      // Optional session ID
  shipping?: string;       // Shipping preference
}
```

#### `checkout_create_payment_url`
Generate hosted Stripe checkout URL
```typescript
{
  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
```typescript
{
  sessionId?: string;          // Optional session ID
  paymentIntentId?: string;    // Optional payment intent ID
}
```

#### `checkout_complete_flow`
Complete one-step checkout process
```typescript
{
  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
```typescript
{
  sessionId?: string;      // Optional session ID
}
```

#### `validate_payment_enforcement`
Verify payment security and system integrity
```typescript
{} // No parameters required
```

## 🛠️ Setup

1. **Install Dependencies**
   ```bash
   npm install
   ```

2. **Environment Setup**
   ```bash
   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**
   ```bash
   # For MCP integration (stdio)
   node server.js --stdio
   
   # For HTTP testing
   node server.js
   ```

## � Usage Examples

### Complete Shopping Flow
```javascript
// 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
```javascript
// 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
```javascript
// 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
```bash
# 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 🍁🛒