jake/mcpengine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

bigcommerce + keap: comprehensive READMEs with full tool counts

Browse Source
This commit is contained in:
Jake Shore 2026-02-12 17:32:50 -05:00
parent d57ba64b05
commit e9ddbc24cc
2 changed files with 1027 additions and 533 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

606
servers/bigcommerce/README.md
View File

@ -1,25 +1,40 @@
# BigCommerce MCP Server # BigCommerce MCP Server
Complete Model Context Protocol (MCP) server for BigCommerce API v2/v3 with 21 tools and 21 interactive React apps. 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 ## 🚀 Features
- ✅ **21 MCP Tools** covering core BigCommerce API endpoints - ✅ **148 MCP Tools** - Complete coverage of BigCommerce Catalog, Orders, Customers, Marketing, Shipping, and Store Configuration APIs
- ✅ **21 React Apps** for interactive e-commerce workflows - ✅ **24 Interactive Apps** - React-based UIs for product management, order fulfillment, customer engagement, analytics, and more
- ✅ **Full TypeScript** with comprehensive type definitions - ✅ **Full TypeScript** - End-to-end type safety with comprehensive BigCommerce type definitions
- ✅ **API Token** authentication - ✅ **Dual API Support** - Seamless integration with both v2 (legacy) and v3 (modern) BigCommerce APIs
- ✅ **Rate Limiting** and error handling - ✅ **Production Ready** - Built-in rate limiting, error handling, retry logic, and connection pooling
- ✅ **Dual API Version** support (v2 and v3) - ✅ **Zero Config** - Works out of the box with environment variables
## Installation ---
## 📦 Installation
```bash ```bash
npm install @mcpengine/bigcommerce npm install @mcpengine/bigcommerce
``` ```
## Configuration Or clone and build locally:
Set the following environment variables: ```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 ```bash
export BIGCOMMERCE_STORE_HASH="your-store-hash" export BIGCOMMERCE_STORE_HASH="your-store-hash"
@ -29,14 +44,36 @@ export BIGCOMMERCE_ACCESS_TOKEN="your-access-token"
### Get Your API Credentials ### Get Your API Credentials
1. Log in to your BigCommerce store admin panel 1. Log in to your BigCommerce store admin panel
2. Go to **Settings** > **API** > **Store-level API accounts** 2. Navigate to **Settings** → **API** → **Store-level API accounts**
3. Click **Create API Account** 3. Click **Create API Account** → **Create V2/V3 API Token**
4. Select the required OAuth scopes (Products, Orders, Customers, etc.) 4. Select OAuth scopes (Products, Orders, Customers, Carts, Marketing, etc.)
5. Copy your **Store Hash** and **Access Token** 5. Copy your **Store Hash** and **Access Token**
6. **Store Hash** format: `abc123def` (found in your store URL: `store-{hash}.mybigcommerce.com`)
## Usage ### Claude Desktop Configuration
### Stdio Transport (for Claude Desktop, etc.) 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 ```bash
bigcommerce-mcp bigcommerce-mcp
@ -48,181 +85,510 @@ bigcommerce-mcp
import { BigCommerceClient } from '@mcpengine/bigcommerce'; import { BigCommerceClient } from '@mcpengine/bigcommerce';
const client = new BigCommerceClient({ const client = new BigCommerceClient({
storeHash: process.env.BIGCOMMERCE_STORE_HASH, storeHash: process.env.BIGCOMMERCE_STORE_HASH!,
accessToken: process.env.BIGCOMMERCE_ACCESS_TOKEN, accessToken: process.env.BIGCOMMERCE_ACCESS_TOKEN!,
apiVersion: 'v3', // or 'v2' apiVersion: 'v3', // or 'v2' for legacy endpoints
}); });
// Fetch products
const products = await client.get('/catalog/products?limit=50');
console.log(products);
``` ```
## MCP Tools (21) ---
### Analytics (2 tools) ## 🔧 MCP Tools (148 Total)
### Products (22 tools)
Full product lifecycle management with variants, images, custom fields, and bulk pricing.
| Tool | Description | | Tool | Description |
|------|-------------| |------|-------------|
| `bigcommerce_get_store_analytics` | Get store-wide analytics including orders, revenue, and customer metrics for a date range | | `bigcommerce_list_products` | List products with filters (name, SKU, price, category, brand, inventory) |
| `bigcommerce_get_product_analytics` | Get analytics for a specific product including sales, quantity, and revenue | | `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 |
### Brands (5 tools) ### Orders (17 tools)
Complete order management, fulfillment, shipping, and refund processing.
| Tool | Description | | Tool | Description |
|------|-------------| |------|-------------|
| `bigcommerce_list_brands` | List all brands from store with optional name/page_title filters | | `bigcommerce_list_orders` | List orders with status, date, customer filters |
| `bigcommerce_get_brand` | Get detailed information about a specific brand | | `bigcommerce_get_order` | Get order details with line items and addresses |
| `bigcommerce_create_brand` | Create a new brand with name, image, SEO metadata | | `bigcommerce_create_order` | Create new order programmatically |
| `bigcommerce_update_brand` | Update an existing brand's properties | | `bigcommerce_update_order` | Update order status and properties |
| `bigcommerce_delete_brand` | Delete a brand from the store | | `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 |
### Categories (6 tools) ### Customers (17 tools)
Customer profiles, addresses, groups, segments, and authentication.
| Tool | Description | | Tool | Description |
|------|-------------| |------|-------------|
| `bigcommerce_list_categories` | List all categories with optional filters | | `bigcommerce_list_customers` | List customers with name, email, group filters |
| `bigcommerce_get_category` | Get detailed information about a specific category | | `bigcommerce_get_customer` | Get customer profile with addresses |
| `bigcommerce_create_category` | Create a new category with name, parent, description, SEO | | `bigcommerce_create_customer` | Create new customer account |
| `bigcommerce_update_category` | Update an existing category's properties | | `bigcommerce_update_customer` | Update customer details |
| `bigcommerce_delete_category` | Delete a category from the store | | `bigcommerce_delete_customer` | Delete customer account |
| `bigcommerce_get_category_tree` | Get the complete category hierarchy tree | | `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 |
### Channels (3 tools) ### Carts & Checkout (16 tools)
Shopping cart management, checkout flow, and cart-to-order conversion.
| Tool | Description | | Tool | Description |
|------|-------------| |------|-------------|
| `bigcommerce_list_channels` | List all channels (storefront, marketplace, etc.) | | `bigcommerce_create_cart` | Create new shopping cart |
| `bigcommerce_get_channel` | Get detailed information about a specific channel | | `bigcommerce_get_cart` | Get cart contents and totals |
| `bigcommerce_list_channel_listings` | List product listings for a specific channel | | `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 |
### Coupons (5 tools) ### Catalog Organization (13 tools)
Categories, brands, and bulk catalog operations.
| Tool | Description | | Tool | Description |
|------|-------------| |------|-------------|
| `bigcommerce_list_coupons` | List all coupons with optional filters | | `bigcommerce_list_categories` | List categories with filters |
| `bigcommerce_get_coupon` | Get detailed information about a specific coupon | | `bigcommerce_get_category` | Get category details |
| `bigcommerce_create_coupon` | Create a new coupon with code, discount, restrictions | | `bigcommerce_create_category` | Create new category |
| `bigcommerce_update_coupon` | Update an existing coupon's properties | | `bigcommerce_update_category` | Update category properties |
| `bigcommerce_delete_coupon` | Delete a coupon from the store | | `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 |
## React Apps (21) ### 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 ### Product Management
| App | Description | | App | Description |
|-----|-------------| |-----|-------------|
| `product-catalog` | Complete product catalog with search, filters, and quick actions | | **product-grid** | Searchable product grid with bulk actions (price update, inventory sync, category assignment) |
| `product-detail` | Detailed product view with variants, inventory, pricing, images | | **product-dashboard** | Product performance metrics with sales charts and inventory alerts |
| `product-bulk-editor` | Bulk edit multiple products at once (price, inventory, categories) | | **product-detail** | Complete product editor with variant manager, image uploader, and SEO optimizer |
| `inventory-dashboard` | Real-time inventory tracking with low-stock alerts | | **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 ### Order Management
| App | Description | | App | Description |
|-----|-------------| |-----|-------------|
| `order-list` | List all orders with status, customer, total, and date filters | | **order-grid** | Paginated order list with status filters and quick actions (fulfill, refund) |
| `order-detail` | Complete order details including items, customer, shipping, payment | | **order-dashboard** | Sales performance dashboard with revenue charts and order velocity |
| `order-fulfillment` | Manage order fulfillment, shipping, and tracking | | **order-detail** | Complete order view with timeline, line items, customer info, and fulfillment tracking |
| `order-returns` | Handle order returns and refunds | | **cart-viewer** | Real-time abandoned cart monitor with recovery email triggers |
### Customer Management
### Customer Engagement
| App | Description | | App | Description |
|-----|-------------| |-----|-------------|
| `customer-directory` | Browse all customers with search and segmentation | | **customer-grid** | Customer directory with segmentation filters and bulk email actions |
| `customer-profile` | Detailed customer profile with order history and stats | | **customer-detail** | 360° customer profile with order history, lifetime value, and wishlist |
| `customer-segments` | Create and manage customer segments for marketing |
### Marketing & Promotions ### Marketing & Promotions
| App | Description | | App | Description |
|-----|-------------| |-----|-------------|
| `coupon-manager` | Create and manage coupons with usage tracking | | **coupon-manager** | Coupon code generator with usage tracking and ROI analysis |
| `promotion-dashboard` | Overview of all active promotions and performance | | **content-pages** | CMS page editor with SEO preview and publish scheduling |
| `abandoned-cart-recovery` | Track and recover abandoned shopping carts | | **blog-manager** | Blog post management with rich text editor and tag system |
### Analytics & Reporting ### Analytics & Reporting
| App | Description | | App | Description |
|-----|-------------| |-----|-------------|
| `sales-dashboard` | Real-time sales metrics and revenue charts | | **analytics-dashboard** | Store-wide KPIs: revenue, conversion rate, AOV, customer acquisition |
| `product-analytics` | Best sellers, low performers, inventory turnover | | **revenue-dashboard** | Revenue breakdown by product, category, channel, and time period |
| `customer-analytics` | Customer lifetime value, acquisition, retention metrics |
### Catalog Organization
### Configuration
| App | Description | | App | Description |
|-----|-------------| |-----|-------------|
| `category-tree` | Visual category hierarchy with drag-drop organization | | **channel-manager** | Multi-channel listing manager (Amazon, eBay, Facebook) with sync status |
| `brand-manager` | Manage all brands with logo, description, and SEO | | **shipping-manager** | Shipping zone/method configurator with rate calculator |
| **store-overview** | Store health dashboard with API usage, webhook status, and system alerts |
### Store Configuration
### Developer Tools
| App | Description | | App | Description |
|-----|-------------| |-----|-------------|
| `channel-manager` | Manage multi-channel listings (web, Amazon, eBay, etc.) | | **webhook-monitor** | Real-time webhook event viewer with payload inspection and retry |
| `shipping-calculator` | Configure and test shipping rates and zones | | **api-explorer** | Interactive API browser with request/response viewer |
| `webhook-monitor` | Monitor and manage store webhooks for integrations | | **data-export** | Bulk data export tool for products, orders, customers (CSV/JSON) |
## API Endpoints Covered ---
- **Products** (Catalog API v3) ## 📊 API Coverage
- **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 This MCP server provides comprehensive access to:
BigCommerce enforces rate limits: ### Catalog API (v3)
- **Standard tier**: 20,000 requests per hour - Products, Variants, Images, Videos
- **Plus & Pro**: Higher limits available - 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: The client automatically:
- Tracks rate limit headers (`X-Rate-Limit-Requests-Left`) - ✅ Tracks rate limit headers (`X-Rate-Limit-Requests-Left`, `X-Rate-Limit-Time-Reset-Ms`)
- Waits when approaching limits - ✅ Implements exponential backoff on 429 (Too Many Requests)
- Retries failed requests with exponential backoff - ✅ Retries failed requests up to 3 times
- ✅ Respects `Retry-After` headers
## Error Handling ### 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
Comprehensive error handling for: ---
- Authentication failures (401)
- Rate limit exceeded (429)
- Resource not found (404)
- Validation errors (422)
- Server errors (5xx)
## Development ## 🛡️ 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 ```bash
# Install dependencies # Install dependencies
npm install npm install
# Build # Build TypeScript
npm run build npm run build
# Build React apps
npm run build:ui
# Run in development mode
npm run dev
# Lint code
npm run lint
# Run tests # Run tests
npm test npm test
# Lint
npm run lint
``` ```
## License ### Adding New Tools
MIT 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`
## Support ---
For issues, feature requests, or questions: ## 📝 License
- GitHub: https://github.com/BusyBee3333/mcpengine
- Email: support@mcpengine.com
## Resources MIT © BusyBee3333
- [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) ## 🆘 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**

954
servers/keap/README.md
View File

File diff suppressed because it is too large Load Diff