jake/mcpengine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
mcpengine/servers/bigcommerce/README.md

229 lines
7.0 KiB
Markdown
Raw Blame History

# 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)
Reference in New Issue View Git Blame Copy Permalink