# BigCommerce MCP Server

Complete Model Context Protocol (MCP) server for BigCommerce API v2/v3 with 21 tools and 21 interactive React apps.

## Features

- ✅ **21 MCP Tools** covering core BigCommerce API endpoints
- ✅ **21 React Apps** for interactive e-commerce workflows
- ✅ **Full TypeScript** with comprehensive type definitions
- ✅ **API Token** authentication
- ✅ **Rate Limiting** and error handling
- ✅ **Dual API Version** support (v2 and v3)

## Installation

```bash
npm install @mcpengine/bigcommerce
```

## Configuration

Set the following environment variables:

```bash
export BIGCOMMERCE_STORE_HASH="your-store-hash"
export BIGCOMMERCE_ACCESS_TOKEN="your-access-token"
```

### Get Your API Credentials

1. Log in to your BigCommerce store admin panel
2. Go to **Settings** > **API** > **Store-level API accounts**
3. Click **Create API Account**
4. Select the required OAuth scopes (Products, Orders, Customers, etc.)
5. Copy your **Store Hash** and **Access Token**

## Usage

### Stdio Transport (for Claude Desktop, etc.)

```bash
bigcommerce-mcp
```

### Programmatic Usage

```typescript
import { BigCommerceClient } from '@mcpengine/bigcommerce';

const client = new BigCommerceClient({
  storeHash: process.env.BIGCOMMERCE_STORE_HASH,
  accessToken: process.env.BIGCOMMERCE_ACCESS_TOKEN,
  apiVersion: 'v3', // or 'v2'
});
```

## MCP Tools (21)

### Analytics (2 tools)

| Tool | Description |
|------|-------------|
| `bigcommerce_get_store_analytics` | Get store-wide analytics including orders, revenue, and customer metrics for a date range |
| `bigcommerce_get_product_analytics` | Get analytics for a specific product including sales, quantity, and revenue |

### Brands (5 tools)

| Tool | Description |
|------|-------------|
| `bigcommerce_list_brands` | List all brands from store with optional name/page_title filters |
| `bigcommerce_get_brand` | Get detailed information about a specific brand |
| `bigcommerce_create_brand` | Create a new brand with name, image, SEO metadata |
| `bigcommerce_update_brand` | Update an existing brand's properties |
| `bigcommerce_delete_brand` | Delete a brand from the store |

### Categories (6 tools)

| Tool | Description |
|------|-------------|
| `bigcommerce_list_categories` | List all categories with optional filters |
| `bigcommerce_get_category` | Get detailed information about a specific category |
| `bigcommerce_create_category` | Create a new category with name, parent, description, SEO |
| `bigcommerce_update_category` | Update an existing category's properties |
| `bigcommerce_delete_category` | Delete a category from the store |
| `bigcommerce_get_category_tree` | Get the complete category hierarchy tree |

### Channels (3 tools)

| Tool | Description |
|------|-------------|
| `bigcommerce_list_channels` | List all channels (storefront, marketplace, etc.) |
| `bigcommerce_get_channel` | Get detailed information about a specific channel |
| `bigcommerce_list_channel_listings` | List product listings for a specific channel |

### Coupons (5 tools)

| Tool | Description |
|------|-------------|
| `bigcommerce_list_coupons` | List all coupons with optional filters |
| `bigcommerce_get_coupon` | Get detailed information about a specific coupon |
| `bigcommerce_create_coupon` | Create a new coupon with code, discount, restrictions |
| `bigcommerce_update_coupon` | Update an existing coupon's properties |
| `bigcommerce_delete_coupon` | Delete a coupon from the store |

## React Apps (21)

### Product Management

| App | Description |
|-----|-------------|
| `product-catalog` | Complete product catalog with search, filters, and quick actions |
| `product-detail` | Detailed product view with variants, inventory, pricing, images |
| `product-bulk-editor` | Bulk edit multiple products at once (price, inventory, categories) |
| `inventory-dashboard` | Real-time inventory tracking with low-stock alerts |

### Order Management

| App | Description |
|-----|-------------|
| `order-list` | List all orders with status, customer, total, and date filters |
| `order-detail` | Complete order details including items, customer, shipping, payment |
| `order-fulfillment` | Manage order fulfillment, shipping, and tracking |
| `order-returns` | Handle order returns and refunds |

### Customer Management

| App | Description |
|-----|-------------|
| `customer-directory` | Browse all customers with search and segmentation |
| `customer-profile` | Detailed customer profile with order history and stats |
| `customer-segments` | Create and manage customer segments for marketing |

### Marketing & Promotions

| App | Description |
|-----|-------------|
| `coupon-manager` | Create and manage coupons with usage tracking |
| `promotion-dashboard` | Overview of all active promotions and performance |
| `abandoned-cart-recovery` | Track and recover abandoned shopping carts |

### Analytics & Reporting

| App | Description |
|-----|-------------|
| `sales-dashboard` | Real-time sales metrics and revenue charts |
| `product-analytics` | Best sellers, low performers, inventory turnover |
| `customer-analytics` | Customer lifetime value, acquisition, retention metrics |

### Catalog Organization

| App | Description |
|-----|-------------|
| `category-tree` | Visual category hierarchy with drag-drop organization |
| `brand-manager` | Manage all brands with logo, description, and SEO |

### Store Configuration

| App | Description |
|-----|-------------|
| `channel-manager` | Manage multi-channel listings (web, Amazon, eBay, etc.) |
| `shipping-calculator` | Configure and test shipping rates and zones |
| `webhook-monitor` | Monitor and manage store webhooks for integrations |

## API Endpoints Covered

- **Products** (Catalog API v3)
- **Categories** (Catalog API v3)
- **Brands** (Catalog API v3)
- **Orders** (Orders API v2)
- **Customers** (Customers API v3)
- **Coupons** (Marketing API v2)
- **Channels** (Channels API v3)
- **Webhooks** (Webhooks API v3)
- **Store Info** (Store Information API v2)
- **Shipping** (Shipping API v2)
- **Carts** (Carts API v3)

## Rate Limits

BigCommerce enforces rate limits:
- **Standard tier**: 20,000 requests per hour
- **Plus & Pro**: Higher limits available

The client automatically:
- Tracks rate limit headers (`X-Rate-Limit-Requests-Left`)
- Waits when approaching limits
- Retries failed requests with exponential backoff

## Error Handling

Comprehensive error handling for:
- Authentication failures (401)
- Rate limit exceeded (429)
- Resource not found (404)
- Validation errors (422)
- Server errors (5xx)

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Lint
npm run lint
```

## License

MIT

## Support

For issues, feature requests, or questions:
- GitHub: https://github.com/BusyBee3333/mcpengine
- Email: support@mcpengine.com

## Resources

- [BigCommerce API Documentation](https://developer.bigcommerce.com/docs/rest-catalog)
- [BigCommerce OAuth Guide](https://developer.bigcommerce.com/api-docs/getting-started/authentication)
- [Model Context Protocol](https://modelcontextprotocol.io)