bigcommerce + keap: comprehensive READMEs with full tool counts

servers/bigcommerce/README.md

@@ -1,25 +1,40 @@
 # 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
-- ✅ **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)
+- ✅ **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
+---
+
+## 📦 Installation
 
 ```bash
 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
 export BIGCOMMERCE_STORE_HASH="your-store-hash"
@@ -29,14 +44,36 @@ 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.)
+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`)
 
-## 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
 bigcommerce-mcp
@@ -48,181 +85,510 @@ bigcommerce-mcp
 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'
+  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 (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 |
 |------|-------------|
-| `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 |
+| `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 |
 
-### Brands (5 tools)
+### Orders (17 tools)
+Complete order management, fulfillment, shipping, and refund processing.
 
 | 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 |
+| `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 |
 
-### Categories (6 tools)
+### Customers (17 tools)
+Customer profiles, addresses, groups, segments, and authentication.
 
 | 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 |
+| `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 |
 
-### Channels (3 tools)
+### Carts & Checkout (16 tools)
+Shopping cart management, checkout flow, and cart-to-order conversion.
 
 | 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 |
+| `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 |
 
-### Coupons (5 tools)
+### Catalog Organization (13 tools)
+Categories, brands, and bulk catalog operations.
 
 | 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 |
+| `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 |
 
-## 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
-
 | 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 |
+| **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-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
+| **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-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 |
+| **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` | 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 |
+| **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 |
 |-----|-------------|
-| `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
+| **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 |
 |-----|-------------|
-| `category-tree` | Visual category hierarchy with drag-drop organization |
-| `brand-manager` | Manage all brands with logo, description, and SEO |
-
-### Store Configuration
+| **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 |
 |-----|-------------|
-| `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 |
+| **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 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)
+## 📊 API Coverage
 
-## Rate Limits
+This MCP server provides comprehensive access to:
 
-BigCommerce enforces rate limits:
-- **Standard tier**: 20,000 requests per hour
-- **Plus & Pro**: Higher limits available
+### 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`)
-- Waits when approaching limits
-- Retries failed requests with exponential backoff
+- ✅ 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
 
-## 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
 # Install dependencies
 npm install
 
-# Build
+# 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
-
-# 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:
-- GitHub: https://github.com/BusyBee3333/mcpengine
-- Email: support@mcpengine.com
+## 📝 License
 
-## 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**