mcpengine/servers/bigcommerce/README.md

# BigCommerce MCP Server

Complete Model Context Protocol (MCP) server for BigCommerce API with **148 production-ready tools** and **24 interactive React apps** covering the entire e-commerce platform.

## 🚀 Features

- ✅ **148 MCP Tools** - Complete coverage of BigCommerce Catalog, Orders, Customers, Marketing, Shipping, and Store Configuration APIs
- ✅ **24 Interactive Apps** - React-based UIs for product management, order fulfillment, customer engagement, analytics, and more
- ✅ **Full TypeScript** - End-to-end type safety with comprehensive BigCommerce type definitions
- ✅ **Dual API Support** - Seamless integration with both v2 (legacy) and v3 (modern) BigCommerce APIs
- ✅ **Production Ready** - Built-in rate limiting, error handling, retry logic, and connection pooling
- ✅ **Zero Config** - Works out of the box with environment variables

---

## 📦 Installation

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

Or clone and build locally:

```bash
git clone https://github.com/BusyBee3333/mcpengine.git
cd mcpengine/servers/bigcommerce
npm install
npm run build
```

---

## ⚙️ Configuration

### Environment Variables

Set the following required 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. Navigate to **Settings** → **API** → **Store-level API accounts**
3. Click **Create API Account** → **Create V2/V3 API Token**
4. Select OAuth scopes (Products, Orders, Customers, Carts, Marketing, etc.)
5. Copy your **Store Hash** and **Access Token**
6. **Store Hash** format: `abc123def` (found in your store URL: `store-{hash}.mybigcommerce.com`)

### Claude Desktop Configuration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "bigcommerce": {
      "command": "npx",
      "args": ["-y", "@mcpengine/bigcommerce"],
      "env": {
        "BIGCOMMERCE_STORE_HASH": "your-store-hash",
        "BIGCOMMERCE_ACCESS_TOKEN": "your-access-token"
      }
    }
  }
}
```

---

## 🛠️ Usage

### Stdio Transport (Claude Desktop, Cline, 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' for legacy endpoints
});

// Fetch products
const products = await client.get('/catalog/products?limit=50');
console.log(products);
```

---

## 🔧 MCP Tools (148 Total)

### Products (22 tools)
Full product lifecycle management with variants, images, custom fields, and bulk pricing.

| Tool | Description |
|------|-------------|
| `bigcommerce_list_products` | List products with filters (name, SKU, price, category, brand, inventory) |
| `bigcommerce_get_product` | Get product details with variants, images, custom fields |
| `bigcommerce_create_product` | Create new product with complete configuration |
| `bigcommerce_update_product` | Update existing product properties |
| `bigcommerce_delete_product` | Delete product from catalog |
| `bigcommerce_list_product_variants` | List all variants for a product |
| `bigcommerce_get_product_variant` | Get variant details (SKU, price, inventory) |
| `bigcommerce_create_product_variant` | Create new product variant |
| `bigcommerce_update_product_variant` | Update variant properties |
| `bigcommerce_delete_product_variant` | Delete variant |
| `bigcommerce_list_product_images` | List product images |
| `bigcommerce_create_product_image` | Upload product image |
| `bigcommerce_update_product_image` | Update image properties (sort order, description) |
| `bigcommerce_delete_product_image` | Delete product image |
| `bigcommerce_list_product_custom_fields` | List custom fields for a product |
| `bigcommerce_create_product_custom_field` | Add custom field to product |
| `bigcommerce_update_product_custom_field` | Update custom field value |
| `bigcommerce_delete_product_custom_field` | Remove custom field |
| `bigcommerce_list_product_bulk_pricing` | List bulk pricing rules |
| `bigcommerce_create_product_bulk_pricing` | Create bulk pricing rule |
| `bigcommerce_update_product_bulk_pricing` | Update bulk pricing rule |
| `bigcommerce_delete_product_bulk_pricing` | Delete bulk pricing rule |

### Orders (17 tools)
Complete order management, fulfillment, shipping, and refund processing.

| Tool | Description |
|------|-------------|
| `bigcommerce_list_orders` | List orders with status, date, customer filters |
| `bigcommerce_get_order` | Get order details with line items and addresses |
| `bigcommerce_create_order` | Create new order programmatically |
| `bigcommerce_update_order` | Update order status and properties |
| `bigcommerce_delete_order` | Archive order |
| `bigcommerce_list_order_products` | List products in an order |
| `bigcommerce_get_order_product` | Get order line item details |
| `bigcommerce_list_order_shipping_addresses` | List shipping addresses for order |
| `bigcommerce_get_order_shipping_address` | Get shipping address details |
| `bigcommerce_update_order_shipping_address` | Update shipping address |
| `bigcommerce_list_order_shipments` | List shipments for order |
| `bigcommerce_create_order_shipment` | Create shipment with tracking |
| `bigcommerce_update_order_shipment` | Update shipment tracking |
| `bigcommerce_delete_order_shipment` | Remove shipment |
| `bigcommerce_list_order_coupons` | List coupons applied to order |
| `bigcommerce_create_order_refund` | Process full or partial refund |
| `bigcommerce_get_order_count` | Get total order count with filters |

### Customers (17 tools)
Customer profiles, addresses, groups, segments, and authentication.

| Tool | Description |
|------|-------------|
| `bigcommerce_list_customers` | List customers with name, email, group filters |
| `bigcommerce_get_customer` | Get customer profile with addresses |
| `bigcommerce_create_customer` | Create new customer account |
| `bigcommerce_update_customer` | Update customer details |
| `bigcommerce_delete_customer` | Delete customer account |
| `bigcommerce_list_customer_addresses` | List customer addresses |
| `bigcommerce_get_customer_address` | Get address details |
| `bigcommerce_create_customer_address` | Add new address |
| `bigcommerce_update_customer_address` | Update address |
| `bigcommerce_delete_customer_address` | Remove address |
| `bigcommerce_list_customer_groups` | List customer groups |
| `bigcommerce_get_customer_group` | Get group details |
| `bigcommerce_create_customer_group` | Create customer group |
| `bigcommerce_update_customer_group` | Update group properties |
| `bigcommerce_delete_customer_group` | Delete group |
| `bigcommerce_list_customer_segments` | List dynamic customer segments |
| `bigcommerce_validate_customer_password` | Validate password strength |

### Carts & Checkout (16 tools)
Shopping cart management, checkout flow, and cart-to-order conversion.

| Tool | Description |
|------|-------------|
| `bigcommerce_create_cart` | Create new shopping cart |
| `bigcommerce_get_cart` | Get cart contents and totals |
| `bigcommerce_update_cart` | Update cart properties |
| `bigcommerce_delete_cart` | Delete cart |
| `bigcommerce_add_cart_items` | Add products to cart |
| `bigcommerce_update_cart_item` | Update cart item quantity/options |
| `bigcommerce_delete_cart_item` | Remove item from cart |
| `bigcommerce_create_checkout` | Convert cart to checkout |
| `bigcommerce_get_checkout` | Get checkout details |
| `bigcommerce_update_checkout` | Update checkout properties |
| `bigcommerce_add_checkout_billing_address` | Add billing address to checkout |
| `bigcommerce_add_checkout_consignment` | Add shipping consignment |
| `bigcommerce_update_checkout_consignment` | Update consignment |
| `bigcommerce_delete_checkout_consignment` | Remove consignment |
| `bigcommerce_create_checkout_order` | Finalize checkout and create order |
| `bigcommerce_create_cart_redirect_url` | Generate checkout redirect URL |

### Catalog Organization (13 tools)
Categories, brands, and bulk catalog operations.

| Tool | Description |
|------|-------------|
| `bigcommerce_list_categories` | List categories with filters |
| `bigcommerce_get_category` | Get category details |
| `bigcommerce_create_category` | Create new category |
| `bigcommerce_update_category` | Update category properties |
| `bigcommerce_delete_category` | Delete category |
| `bigcommerce_get_category_tree` | Get complete category hierarchy |
| `bigcommerce_list_brands` | List brands with filters |
| `bigcommerce_get_brand` | Get brand details |
| `bigcommerce_create_brand` | Create new brand |
| `bigcommerce_update_brand` | Update brand properties |
| `bigcommerce_delete_brand` | Delete brand |
| `bigcommerce_bulk_update_product_prices` | Bulk price update across products |
| `bigcommerce_bulk_delete_products` | Bulk product deletion |

### Promotions & Marketing (19 tools)
Coupons, promotions, gift certificates, and wishlists.

| Tool | Description |
|------|-------------|
| `bigcommerce_list_promotions` | List active promotions |
| `bigcommerce_get_promotion` | Get promotion details |
| `bigcommerce_create_promotion` | Create new promotion |
| `bigcommerce_update_promotion` | Update promotion rules |
| `bigcommerce_delete_promotion` | Delete promotion |
| `bigcommerce_list_coupons` | List coupon codes |
| `bigcommerce_get_coupon` | Get coupon details |
| `bigcommerce_create_coupon` | Create coupon code |
| `bigcommerce_update_coupon` | Update coupon properties |
| `bigcommerce_delete_coupon` | Delete coupon |
| `bigcommerce_list_gift_certificates` | List gift certificates |
| `bigcommerce_get_gift_certificate` | Get gift certificate details |
| `bigcommerce_create_gift_certificate` | Issue gift certificate |
| `bigcommerce_update_gift_certificate` | Update gift certificate |
| `bigcommerce_delete_gift_certificate` | Void gift certificate |
| `bigcommerce_list_wishlists` | List customer wishlists |
| `bigcommerce_get_wishlist` | Get wishlist items |
| `bigcommerce_add_wishlist_item` | Add product to wishlist |
| `bigcommerce_delete_wishlist_item` | Remove wishlist item |

### Shipping & Fulfillment (17 tools)
Shipping zones, methods, tax classes, payment methods, and currencies.

| Tool | Description |
|------|-------------|
| `bigcommerce_list_shipping_zones` | List shipping zones |
| `bigcommerce_get_shipping_zone` | Get zone details |
| `bigcommerce_create_shipping_zone` | Create shipping zone |
| `bigcommerce_update_shipping_zone` | Update zone properties |
| `bigcommerce_delete_shipping_zone` | Delete zone |
| `bigcommerce_list_shipping_methods` | List methods for zone |
| `bigcommerce_create_shipping_method` | Create shipping method |
| `bigcommerce_update_shipping_method` | Update method rates |
| `bigcommerce_delete_shipping_method` | Remove method |
| `bigcommerce_list_tax_classes` | List tax classes |
| `bigcommerce_get_tax_class` | Get tax class details |
| `bigcommerce_list_payment_methods` | List enabled payment gateways |
| `bigcommerce_list_currencies` | List store currencies |
| `bigcommerce_get_currency` | Get currency details |
| `bigcommerce_create_currency` | Add new currency |
| `bigcommerce_update_currency` | Update currency settings |
| `bigcommerce_delete_currency` | Remove currency |

### Store Management (11 tools)
Store information, channels, sites, and timezone configuration.

| Tool | Description |
|------|-------------|
| `bigcommerce_get_store_information` | Get store profile and settings |
| `bigcommerce_list_channels` | List sales channels (web, marketplace) |
| `bigcommerce_get_channel` | Get channel details |
| `bigcommerce_create_channel` | Create new channel |
| `bigcommerce_update_channel` | Update channel settings |
| `bigcommerce_list_sites` | List channel sites |
| `bigcommerce_get_site` | Get site configuration |
| `bigcommerce_create_site` | Create new site |
| `bigcommerce_update_site` | Update site settings |
| `bigcommerce_delete_site` | Remove site |
| `bigcommerce_get_time_zone` | Get store timezone |

### Content Management (10 tools)
Scripts (analytics, tracking) and CMS pages.

| Tool | Description |
|------|-------------|
| `bigcommerce_list_scripts` | List store scripts (Google Analytics, etc.) |
| `bigcommerce_get_script` | Get script details |
| `bigcommerce_create_script` | Add new script to store |
| `bigcommerce_update_script` | Update script properties |
| `bigcommerce_delete_script` | Remove script |
| `bigcommerce_list_pages` | List CMS pages |
| `bigcommerce_get_page` | Get page content |
| `bigcommerce_create_page` | Create CMS page |
| `bigcommerce_update_page` | Update page content/SEO |
| `bigcommerce_delete_page` | Delete CMS page |

### Webhooks (6 tools)
Event-driven integration with external systems.

| Tool | Description |
|------|-------------|
| `bigcommerce_list_webhooks` | List active webhooks |
| `bigcommerce_get_webhook` | Get webhook configuration |
| `bigcommerce_create_webhook` | Register webhook for events |
| `bigcommerce_update_webhook` | Update webhook URL/events |
| `bigcommerce_delete_webhook` | Remove webhook |
| `bigcommerce_list_webhook_scopes` | List available webhook events |

---

## 🎨 React Apps (24 Total)

### Product Management
| App | Description |
|-----|-------------|
| **product-grid** | Searchable product grid with bulk actions (price update, inventory sync, category assignment) |
| **product-dashboard** | Product performance metrics with sales charts and inventory alerts |
| **product-detail** | Complete product editor with variant manager, image uploader, and SEO optimizer |
| **inventory-tracker** | Real-time inventory tracking with low-stock alerts and reorder suggestions |
| **category-tree** | Drag-and-drop category hierarchy editor with product assignment |
| **brand-manager** | Brand library with logo upload, description editor, and product count |

### Order Management
| App | Description |
|-----|-------------|
| **order-grid** | Paginated order list with status filters and quick actions (fulfill, refund) |
| **order-dashboard** | Sales performance dashboard with revenue charts and order velocity |
| **order-detail** | Complete order view with timeline, line items, customer info, and fulfillment tracking |
| **cart-viewer** | Real-time abandoned cart monitor with recovery email triggers |

### Customer Engagement
| App | Description |
|-----|-------------|
| **customer-grid** | Customer directory with segmentation filters and bulk email actions |
| **customer-detail** | 360° customer profile with order history, lifetime value, and wishlist |

### Marketing & Promotions
| App | Description |
|-----|-------------|
| **coupon-manager** | Coupon code generator with usage tracking and ROI analysis |
| **content-pages** | CMS page editor with SEO preview and publish scheduling |
| **blog-manager** | Blog post management with rich text editor and tag system |

### Analytics & Reporting
| App | Description |
|-----|-------------|
| **analytics-dashboard** | Store-wide KPIs: revenue, conversion rate, AOV, customer acquisition |
| **revenue-dashboard** | Revenue breakdown by product, category, channel, and time period |

### Configuration
| App | Description |
|-----|-------------|
| **channel-manager** | Multi-channel listing manager (Amazon, eBay, Facebook) with sync status |
| **shipping-manager** | Shipping zone/method configurator with rate calculator |
| **store-overview** | Store health dashboard with API usage, webhook status, and system alerts |

### Developer Tools
| App | Description |
|-----|-------------|
| **webhook-monitor** | Real-time webhook event viewer with payload inspection and retry |
| **api-explorer** | Interactive API browser with request/response viewer |
| **data-export** | Bulk data export tool for products, orders, customers (CSV/JSON) |

---

## 📊 API Coverage

This MCP server provides comprehensive access to:

### Catalog API (v3)
- Products, Variants, Images, Videos
- Categories, Category Trees
- Brands
- Product Modifiers, Custom Fields
- Bulk Pricing Rules

### Orders API (v2)
- Orders, Order Products
- Shipments, Tracking
- Order Statuses
- Refunds

### Customers API (v3)
- Customers, Addresses
- Customer Groups, Segments
- Customer Attributes
- Authentication & Passwords

### Carts API (v3)
- Server-to-Server Carts
- Cart Items, Line Items
- Checkout, Billing Address
- Consignments (Shipping)

### Marketing API (v2/v3)
- Promotions
- Coupons
- Gift Certificates
- Wishlists

### Channels API (v3)
- Sales Channels
- Channel Listings
- Sites & Routes

### Store Information API (v2)
- Store Profile
- Store Time Zone
- Store Features

### Shipping API (v2)
- Shipping Zones
- Shipping Methods
- Custom Shipping Carriers

### Payment Processing API (v3)
- Payment Methods
- Stored Instruments

### Webhooks API (v3)
- Webhook Management
- Event Subscriptions

### Content API (v3)
- Scripts (Analytics, Tracking)
- Pages (CMS)

---

## 🔐 Rate Limits & Best Practices

### BigCommerce Rate Limits
- **Standard Plan**: 20,000 requests/hour
- **Plus/Pro Plans**: Higher limits (contact BigCommerce)
- **Burst Limit**: 150 requests/30 seconds

### Built-in Handling
The client automatically:
- ✅ Tracks rate limit headers (`X-Rate-Limit-Requests-Left`, `X-Rate-Limit-Time-Reset-Ms`)
- ✅ Implements exponential backoff on 429 (Too Many Requests)
- ✅ Retries failed requests up to 3 times
- ✅ Respects `Retry-After` headers

### Optimization Tips
1. Use pagination (`limit=250`) for large datasets
2. Use field filters (`include=variants,images`) to reduce payload size
3. Cache frequently accessed data (store info, categories)
4. Batch operations where possible (bulk price updates)
5. Use webhooks instead of polling for real-time events

---

## 🛡️ Error Handling

Comprehensive error handling for all failure scenarios:

| HTTP Status | Meaning | Client Behavior |
|------------|---------|-----------------|
| **400** | Bad Request | Returns validation error details |
| **401** | Unauthorized | Check `BIGCOMMERCE_ACCESS_TOKEN` |
| **403** | Forbidden | Token missing required OAuth scope |
| **404** | Not Found | Resource doesn't exist |
| **409** | Conflict | Duplicate SKU or unique constraint violation |
| **422** | Unprocessable Entity | Validation failed (returns field errors) |
| **429** | Too Many Requests | Auto-retry with exponential backoff |
| **500** | Server Error | Retry up to 3 times |
| **503** | Service Unavailable | BigCommerce maintenance mode |

All errors include:
- Human-readable error message
- HTTP status code
- Request ID (for BigCommerce support)
- Field-level validation errors (when applicable)

---

## 🏗️ Architecture

```
bigcommerce-mcp/
├── src/
│   ├── clients/
│   │   └── bigcommerce.ts          # HTTP client with rate limiting
│   ├── tools/
│   │   ├── products-tools.ts       # 22 product tools
│   │   ├── orders-tools.ts         # 17 order tools
│   │   ├── customers-tools.ts      # 17 customer tools
│   │   ├── carts-tools.ts          # 16 cart/checkout tools
│   │   ├── catalog-tools.ts        # 13 catalog tools
│   │   ├── promotions-tools.ts     # 19 marketing tools
│   │   ├── shipping-tools.ts       # 17 shipping/fulfillment tools
│   │   ├── store-tools.ts          # 11 store management tools
│   │   ├── content-tools.ts        # 10 CMS tools
│   │   └── webhooks-tools.ts       # 6 webhook tools
│   ├── types/
│   │   └── index.ts                # BigCommerce type definitions
│   ├── ui/
│   │   └── react-app/              # 24 React apps
│   ├── server.ts                   # MCP server implementation
│   └── main.ts                     # CLI entry point
├── package.json
├── tsconfig.json
└── README.md
```

### Type Safety
All tools use TypeScript interfaces matching BigCommerce API schemas:
- `Product`, `ProductVariant`, `ProductImage`
- `Order`, `OrderProduct`, `Shipment`
- `Customer`, `CustomerAddress`, `CustomerGroup`
- `Cart`, `Checkout`, `LineItem`
- And 40+ more types

---

## 🚀 Development

```bash
# Install dependencies
npm install

# Build TypeScript
npm run build

# Build React apps
npm run build:ui

# Run in development mode
npm run dev

# Lint code
npm run lint

# Run tests
npm test
```

### Adding New Tools

1. Create tool file in `src/tools/` (e.g., `my-tools.ts`)
2. Export `registerMyTools(client)` function
3. Import and register in `src/server.ts`
4. Add TypeScript types in `src/types/`
5. Rebuild: `npm run build`

---

## 📝 License

MIT © BusyBee3333

---

## 🆘 Support & Resources

- **GitHub**: https://github.com/BusyBee3333/mcpengine
- **Issues**: https://github.com/BusyBee3333/mcpengine/issues
- **BigCommerce API Docs**: https://developer.bigcommerce.com/docs/rest
- **BigCommerce Dev Center**: https://developer.bigcommerce.com
- **MCP Specification**: https://modelcontextprotocol.io

### Common Issues

**❌ "Missing required environment variables"**
→ Set `BIGCOMMERCE_STORE_HASH` and `BIGCOMMERCE_ACCESS_TOKEN` environment variables.

**❌ "401 Unauthorized"**
→ Check your access token is valid and not expired. Regenerate in BigCommerce admin if needed.

**❌ "403 Forbidden"**
→ Your API token is missing required OAuth scopes. Edit the API account and grant additional permissions.

**❌ "429 Too Many Requests"**
→ You've hit BigCommerce rate limits. The client will auto-retry with backoff. Consider upgrading your plan for higher limits.

**❌ "SSL certificate verification failed"**
→ Your store hash or domain is incorrect. Verify the store hash matches your store URL.

---

## 🎯 Roadmap

- [ ] Add GraphQL Storefront API support
- [ ] Implement bulk import/export (CSV)
- [ ] Add product recommendation engine tools
- [ ] Create customer segmentation wizard
- [ ] Add A/B testing tools for promotions
- [ ] Implement multi-currency conversion tools
- [ ] Add headless commerce tools (Next.js integration)

---

**Built with ❤️ by BusyBee3333 | Powered by Model Context Protocol**