diff --git a/servers/bigcommerce/README.md b/servers/bigcommerce/README.md index 7bca5d9..474a47c 100644 --- a/servers/bigcommerce/README.md +++ b/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** diff --git a/servers/keap/README.md b/servers/keap/README.md index 7011d36..3e1e460 100644 --- a/servers/keap/README.md +++ b/servers/keap/README.md @@ -1,366 +1,76 @@ # Keap MCP Server -A comprehensive Model Context Protocol (MCP) server for Keap (formerly Infusionsoft) - providing AI-powered access to contact management, sales pipeline, marketing automation, e-commerce, and more. +Complete Model Context Protocol server for Keap (formerly Infusionsoft) with 111 tools and 22 React apps. -## ๐Ÿš€ Features +## Features -- **111 MCP Tools** across 14 categories -- **20 React Apps** with dark theme UI matching Keap brand -- Full OAuth 2.0 PKCE authentication flow -- Type-safe API client with comprehensive error handling -- Real-time data synchronization -- Webhook support for automation +### ๐Ÿ› ๏ธ Comprehensive Tool Coverage (111 tools) -## ๐Ÿ“ฆ Installation +- **Contacts**: Full CRUD, search, tagging, custom fields, bulk operations, merge, email opt status +- **Companies**: CRUD, search, company-contact associations +- **Opportunities**: Complete sales pipeline (CRUD, stages, stage moves, search, bulk operations) +- **Tasks**: CRUD, completion tracking, search, bulk updates +- **Appointments**: CRUD, scheduling, calendar integration, search +- **Campaigns**: CRUD, sequence management, contact additions, achievement tracking +- **Tags**: CRUD, category management, contact tagging/untagging, bulk operations +- **Notes**: CRUD, contact/opportunity associations, search +- **Emails**: Send transactional and marketing emails, templates, tracking, opt status +- **Files**: Upload, retrieve, associate with contacts/companies +- **E-commerce**: Products, orders, subscriptions, payments, refunds, transaction history +- **Automations**: Campaign builder sequences, goal tracking, link triggers +- **Settings**: Account info, user management, custom fields, settings configuration +- **Affiliates**: Program management, commissions, payouts, clawbacks, summaries + +### ๐ŸŽจ MCP Apps (22 React Apps) + +1. **Contact Dashboard** - Contact list with metrics and search +2. **Contact Detail** - Comprehensive contact profile view +3. **Contact Grid** - Data grid with filtering and bulk actions +4. **Contact Timeline** - Activity timeline and interaction history +5. **Company Dashboard** - Company overview and metrics +6. **Company Detail** - Detailed company information +7. **Company Grid** - Companies data grid with search +8. **Deal Dashboard** - Sales pipeline overview +9. **Deal Detail** - Opportunity details and stage tracking +10. **Pipeline Kanban** - Visual drag-and-drop pipeline management +11. **Pipeline Funnel** - Conversion funnel visualization +12. **Task Manager** - Task list with priorities and due dates +13. **Appointment Calendar** - Calendar view with scheduling +14. **Campaign Dashboard** - Campaign performance metrics +15. **Campaign Detail** - Campaign sequence and analytics +16. **Email Composer** - Rich email composition interface +17. **Tag Manager** - Tag organization and bulk tagging +18. **Automation Dashboard** - Campaign builder overview +19. **Product Catalog** - E-commerce product management +20. **Order Dashboard** - Order tracking and fulfillment +21. **Order Detail** - Detailed order information +22. **Revenue Dashboard** - Revenue analytics and reporting + +## Installation ```bash npm install @mcpengine/keap ``` -## ๐Ÿ”ง Configuration +## Configuration -Create a `.env` file: +### Environment Variables -```env -KEAP_CLIENT_ID=your_client_id -KEAP_CLIENT_SECRET=your_client_secret -KEAP_REDIRECT_URI=http://localhost:3000/callback -KEAP_ACCESS_TOKEN=your_access_token -KEAP_REFRESH_TOKEN=your_refresh_token +```bash +KEAP_API_KEY=your_personal_access_token ``` -## ๐Ÿ› ๏ธ MCP Tools (111 Total) +### Personal Access Token Setup -### Contacts (19 tools) -Core contact management and CRM functionality. +1. Log in to your Keap account +2. Navigate to **Admin** โ†’ **Settings** โ†’ **Application** +3. Click on **API** tab +4. Generate a new **Personal Access Token** +5. Copy the token and use it as `KEAP_API_KEY` -- `keap_create_contact` - Create a new contact with email, name, phone, address, tags, custom fields -- `keap_get_contact` - Retrieve a contact by ID with all details -- `keap_update_contact` - Update an existing contact -- `keap_delete_contact` - Delete a contact permanently -- `keap_list_contacts` - List contacts with pagination and filtering -- `keap_search_contacts` - Search contacts by email, name, phone -- `keap_merge_contacts` - Merge duplicate contacts -- `keap_apply_tag_to_contact` - Apply a tag to a contact -- `keap_remove_tag_from_contact` - Remove a tag from a contact -- `keap_get_contact_tags` - Get all tags applied to a contact -- `keap_get_contact_emails` - Get email addresses for a contact -- `keap_create_contact_email` - Add a new email address to a contact -- `keap_delete_contact_email` - Remove an email address from a contact -- `keap_get_contact_credit_cards` - Get saved credit cards for a contact -- `keap_create_contact_credit_card` - Add a credit card to a contact -- `keap_get_contact_custom_fields` - Get custom field values for a contact -- `keap_update_contact_custom_field` - Update a custom field value -- `keap_list_contact_notes` - List all notes for a contact -- `keap_get_contact_model` - Get the contact data model schema +### MCP Settings (Claude Desktop) -### E-Commerce (15 tools) -Product catalog, orders, transactions, and subscriptions. - -- `keap_create_product` - Create a new product in the catalog -- `keap_get_product` - Get product details by ID -- `keap_update_product` - Update product information -- `keap_delete_product` - Delete a product -- `keap_list_products` - List all products with filtering -- `keap_create_order` - Create a new order for a contact -- `keap_get_order` - Get order details by ID -- `keap_delete_order` - Delete an order -- `keap_list_orders` - List orders with filtering -- `keap_list_order_transactions` - Get all transactions for an order -- `keap_get_transaction` - Get transaction details -- `keap_list_transactions` - List all transactions -- `keap_create_subscription` - Create a recurring subscription -- `keap_get_subscription` - Get subscription details -- `keap_list_subscriptions` - List all subscriptions - -### Opportunities (9 tools) -Sales pipeline and opportunity management. - -- `keap_create_opportunity` - Create a new sales opportunity -- `keap_get_opportunity` - Get opportunity details -- `keap_update_opportunity` - Update opportunity information -- `keap_delete_opportunity` - Delete an opportunity -- `keap_list_opportunities` - List opportunities with filtering -- `keap_list_opportunity_stage_pipeline` - Get all pipeline stages -- `keap_get_opportunity_stage_pipeline` - Get details for a specific stage -- `keap_update_opportunity_stage` - Move opportunity to different stage -- `keap_get_opportunity_model` - Get opportunity data model schema - -### Affiliates (9 tools) -Affiliate program management and tracking. - -- `keap_create_affiliate` - Create a new affiliate account -- `keap_get_affiliate` - Get affiliate details -- `keap_list_affiliates` - List all affiliates -- `keap_get_affiliate_clawbacks` - Get commission clawbacks for an affiliate -- `keap_get_affiliate_commissions` - Get commissions earned -- `keap_get_affiliate_payments` - Get payment history -- `keap_get_affiliate_redirect_links` - Get tracking links -- `keap_get_affiliate_summary` - Get affiliate performance summary -- `keap_list_commissions` - List all commissions - -### Tasks (8 tools) -Task and activity management. - -- `keap_create_task` - Create a new task -- `keap_get_task` - Get task details -- `keap_update_task` - Update task information -- `keap_delete_task` - Delete a task -- `keap_list_tasks` - List tasks with filtering -- `keap_search_tasks` - Search tasks by title or description -- `keap_complete_task` - Mark a task as completed -- `keap_get_task_model` - Get task data model schema - -### Campaigns (7 tools) -Marketing campaign and sequence management. - -- `keap_list_campaigns` - List all campaigns -- `keap_get_campaign` - Get campaign details -- `keap_add_contact_to_campaign` - Add a contact to a campaign -- `keap_remove_contact_from_campaign` - Remove a contact from a campaign -- `keap_get_campaign_sequences` - Get all sequences in a campaign -- `keap_add_contact_to_sequence` - Add contact to a specific sequence -- `keap_remove_contact_from_sequence` - Remove contact from sequence - -### Emails (7 tools) -Email sending, templates, and opt-in management. - -- `keap_send_email` - Send an email to contacts -- `keap_get_email` - Get email details -- `keap_list_emails` - List sent emails -- `keap_create_email_template` - Create a new email template -- `keap_list_email_templates` - List all email templates -- `keap_opt_in_contact` - Opt-in a contact for email marketing -- `keap_opt_out_contact` - Opt-out a contact from emails - -### Appointments (6 tools) -Appointment scheduling and calendar management. - -- `keap_create_appointment` - Create a new appointment -- `keap_get_appointment` - Get appointment details -- `keap_update_appointment` - Update appointment information -- `keap_delete_appointment` - Delete an appointment -- `keap_list_appointments` - List appointments with filtering -- `keap_get_appointment_model` - Get appointment data model schema - -### Automations (6 tools) -Webhook and automation configuration. - -- `keap_create_hook` - Create a new webhook -- `keap_list_hooks` - List all webhooks -- `keap_delete_hook` - Delete a webhook -- `keap_verify_hook` - Verify webhook configuration -- `keap_update_hook` - Update webhook settings -- `keap_list_hook_event_types` - Get available webhook event types - -### Notes (6 tools) -Contact and opportunity notes. - -- `keap_create_note` - Create a new note -- `keap_get_note` - Get note details -- `keap_update_note` - Update note content -- `keap_delete_note` - Delete a note -- `keap_list_notes` - List notes with filtering -- `keap_get_note_model` - Get note data model schema - -### Companies (5 tools) -Company/organization management. - -- `keap_create_company` - Create a new company -- `keap_get_company` - Get company details -- `keap_update_company` - Update company information -- `keap_list_companies` - List companies with filtering -- `keap_get_company_contacts` - Get all contacts for a company - -### Settings (5 tools) -Account settings and configuration. - -- `keap_get_account_profile` - Get account profile information -- `keap_update_account_profile` - Update account settings -- `keap_list_users` - List all users in the account -- `keap_get_application_configuration` - Get app configuration -- `keap_list_custom_fields` - List all custom field definitions - -### Tags (5 tools) -Tag and category management. - -- `keap_create_tag` - Create a new tag -- `keap_get_tag` - Get tag details -- `keap_list_tags` - List all tags -- `keap_create_tag_category` - Create a tag category -- `keap_list_tag_categories` - List all tag categories - -### Files (4 tools) -File upload and management. - -- `keap_upload_file` - Upload a file -- `keap_get_file` - Get file details and download URL -- `keap_delete_file` - Delete a file -- `keap_list_files` - List all uploaded files - -## ๐ŸŽจ React Apps (20 Total) - -All apps feature dark theme styling with Keap's orange/amber brand accents and VSCode-style UI. - -### Core Apps - -1. **Contact Dashboard** (`src/ui/react-app/src/apps/contact-dashboard/`) - - Overview of contact metrics and recent contacts - - Quick search and filter functionality - - Contact creation and editing - -2. **Contact Detail** (`src/ui/react-app/src/apps/contact-detail/`) - - Full contact profile with all fields - - Tag management - - Email and phone history - - Custom field editor - -3. **Contact Grid** (`src/ui/react-app/src/apps/contact-grid/`) - - Sortable, filterable contact list - - Bulk actions (tag, delete, export) - - Advanced search - -4. **Deal Detail** (`src/ui/react-app/src/apps/deal-detail/`) - - Opportunity/deal full details - - Stage progression tracking - - Activity timeline - -5. **Pipeline Kanban** (`src/ui/react-app/src/apps/pipeline-kanban/`) - - Drag-and-drop deal pipeline - - Stage-based organization - - Deal value summaries per stage - -### Campaign & Marketing - -6. **Campaign Dashboard** (`src/ui/react-app/src/apps/campaign-dashboard/`) - - Campaign performance metrics - - Active campaigns list - - Contact enrollment stats - -7. **Campaign Detail** (`src/ui/react-app/src/apps/campaign-detail/`) - - Campaign sequence viewer - - Contact progress tracking - - Enrollment/removal management - -8. **Email Composer** (`src/ui/react-app/src/apps/email-composer/`) - - Rich text email editor - - Template selector - - Merge field insertion - - Send to contacts or lists - -9. **Automation Builder** (`src/ui/react-app/src/apps/automation-builder/`) - - Webhook management - - Event type configuration - - Automation triggers - -### Calendar & Tasks - -10. **Appointment Calendar** (`src/ui/react-app/src/apps/appointment-calendar/`) - - Calendar view of appointments - - Create/edit appointments - - Contact association - -11. **Task Manager** (`src/ui/react-app/src/apps/task-manager/`) - - Task list with filtering - - Task creation and assignment - - Completion tracking - -### E-Commerce - -12. **Order Dashboard** (`src/ui/react-app/src/apps/order-dashboard/`) - - Order overview and metrics - - Recent orders list - - Revenue summaries - -13. **Order Detail** (`src/ui/react-app/src/apps/order-detail/`) - - Full order information - - Transaction history - - Payment status - -14. **Product Catalog** (`src/ui/react-app/src/apps/product-catalog/`) - - Product list with images - - Product creation and editing - - Pricing and inventory management - -15. **Subscription Manager** (`src/ui/react-app/src/apps/subscription-manager/`) - - Active subscriptions list - - Subscription creation - - Billing cycle tracking - -### Organization & Settings - -16. **Tag Manager** (`src/ui/react-app/src/apps/tag-manager/`) - - Tag list and creation - - Category management - - Tag application stats - -17. **Analytics Dashboard** (`src/ui/react-app/src/apps/analytics-dashboard/`) - - Business metrics overview - - Contact growth charts - - Revenue analytics - -18. **Affiliate Dashboard** (`src/ui/react-app/src/apps/affiliate-dashboard/`) - - Affiliate performance - - Commission tracking - - Payment history - -19. **File Browser** (`src/ui/react-app/src/apps/file-browser/`) - - Uploaded files list - - File upload interface - - Download and delete actions - -20. **Settings Panel** (`src/ui/react-app/src/apps/settings-panel/`) - - Account profile - - User management - - Custom field configuration - -## ๐Ÿ—๏ธ Architecture - -``` -servers/keap/ -โ”œโ”€โ”€ src/ -โ”‚ โ”œโ”€โ”€ clients/ -โ”‚ โ”‚ โ””โ”€โ”€ keap.ts # OAuth 2.0 client with auto-refresh -โ”‚ โ”œโ”€โ”€ tools/ # 14 tool files, 111 tools total -โ”‚ โ”‚ โ”œโ”€โ”€ affiliates-tools.ts -โ”‚ โ”‚ โ”œโ”€โ”€ appointments-tools.ts -โ”‚ โ”‚ โ”œโ”€โ”€ automations-tools.ts -โ”‚ โ”‚ โ”œโ”€โ”€ campaigns-tools.ts -โ”‚ โ”‚ โ”œโ”€โ”€ companies-tools.ts -โ”‚ โ”‚ โ”œโ”€โ”€ contacts-tools.ts -โ”‚ โ”‚ โ”œโ”€โ”€ ecommerce-tools.ts -โ”‚ โ”‚ โ”œโ”€โ”€ emails-tools.ts -โ”‚ โ”‚ โ”œโ”€โ”€ files-tools.ts -โ”‚ โ”‚ โ”œโ”€โ”€ notes-tools.ts -โ”‚ โ”‚ โ”œโ”€โ”€ opportunities-tools.ts -โ”‚ โ”‚ โ”œโ”€โ”€ settings-tools.ts -โ”‚ โ”‚ โ”œโ”€โ”€ tags-tools.ts -โ”‚ โ”‚ โ””โ”€โ”€ tasks-tools.ts -โ”‚ โ”œโ”€โ”€ types/ -โ”‚ โ”‚ โ”œโ”€โ”€ keap.ts # Type definitions -โ”‚ โ”‚ โ””โ”€โ”€ index.ts -โ”‚ โ”œโ”€โ”€ ui/ -โ”‚ โ”‚ โ””โ”€โ”€ react-app/ -โ”‚ โ”‚ โ”œโ”€โ”€ src/ -โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ apps/ # 20 React applications -โ”‚ โ”‚ โ”‚ โ”œโ”€โ”€ hooks/ # Shared React hooks -โ”‚ โ”‚ โ”‚ โ””โ”€โ”€ styles/ # Dark theme CSS -โ”‚ โ”‚ โ”œโ”€โ”€ package.json -โ”‚ โ”‚ โ”œโ”€โ”€ tsconfig.json -โ”‚ โ”‚ โ””โ”€โ”€ build-all.js -โ”‚ โ”œโ”€โ”€ server.ts # MCP server implementation -โ”‚ โ””โ”€โ”€ main.ts # Entry point -โ”œโ”€โ”€ dist/ # Compiled output -โ”œโ”€โ”€ package.json -โ”œโ”€โ”€ tsconfig.json -โ””โ”€โ”€ README.md -``` - -## ๐ŸŽฏ Usage - -### As MCP Server - -Add to your MCP client configuration: +Add to your `claude_desktop_config.json`: ```json { @@ -369,17 +79,416 @@ Add to your MCP client configuration: "command": "npx", "args": ["-y", "@mcpengine/keap"], "env": { - "KEAP_CLIENT_ID": "your_client_id", - "KEAP_CLIENT_SECRET": "your_client_secret", - "KEAP_ACCESS_TOKEN": "your_access_token", - "KEAP_REFRESH_TOKEN": "your_refresh_token" + "KEAP_API_KEY": "your_personal_access_token" } } } } ``` -### Building React Apps +## Usage Examples + +### Create a Contact + +```typescript +{ + "tool": "keap_create_contact", + "arguments": { + "given_name": "John", + "family_name": "Doe", + "email": "john.doe@example.com", + "phone": "555-0123", + "company_name": "Acme Corp", + "job_title": "CTO", + "tag_ids": [123, 456] + } +} +``` + +### Search Contacts + +```typescript +{ + "tool": "keap_search_contacts", + "arguments": { + "email": "john@example.com", + "given_name": "John", + "order": "email", + "limit": 50 + } +} +``` + +### Create an Opportunity + +```typescript +{ + "tool": "keap_create_opportunity", + "arguments": { + "title": "New Website Project", + "contact_id": 12345, + "stage_id": 789, + "projected_revenue": 15000, + "opportunity_notes": "Interested in complete redesign" + } +} +``` + +### Move Opportunity Stage + +```typescript +{ + "tool": "keap_move_opportunity_stage", + "arguments": { + "opportunity_id": 98765, + "stage_id": 790, + "notes": "Proposal sent, awaiting review" + } +} +``` + +### Tag Contacts + +```typescript +{ + "tool": "keap_apply_tags_to_contacts", + "arguments": { + "contact_ids": [123, 456, 789], + "tag_ids": [10, 20] + } +} +``` + +### Send Email + +```typescript +{ + "tool": "keap_send_email", + "arguments": { + "contact_ids": [12345], + "subject": "Welcome to our service!", + "html_content": "

Welcome!

Thank you for joining us.

", + "text_content": "Welcome! Thank you for joining us." + } +} +``` + +### Create a Product + +```typescript +{ + "tool": "keap_create_product", + "arguments": { + "product_name": "Premium Subscription", + "product_price": 99.99, + "product_desc": "Monthly premium access", + "sku": "PREM-001", + "status": 1 + } +} +``` + +### Create an Order + +```typescript +{ + "tool": "keap_create_order", + "arguments": { + "contact_id": 12345, + "order_items": [ + { + "product_id": 456, + "quantity": 2, + "price": 99.99 + } + ], + "order_title": "Q1 Subscription" + } +} +``` + +## Tool Reference + +### Contact Tools (19 tools) + +- `keap_create_contact` - Create new contact +- `keap_get_contact` - Get contact by ID +- `keap_update_contact` - Update contact details +- `keap_delete_contact` - Delete contact +- `keap_list_contacts` - List all contacts (paginated) +- `keap_search_contacts` - Search contacts by criteria +- `keap_get_contact_emails` - Get contact's email addresses +- `keap_create_contact_email` - Add email to contact +- `keap_update_contact_email` - Update email address +- `keap_delete_contact_email` - Remove email address +- `keap_apply_tags_to_contact` - Tag a single contact +- `keap_remove_tags_from_contact` - Remove tags from contact +- `keap_get_contact_tags` - List contact's tags +- `keap_merge_contacts` - Merge duplicate contacts +- `keap_apply_tags_to_contacts` - Bulk tag multiple contacts +- `keap_remove_tags_from_contacts` - Bulk remove tags +- `keap_get_contact_opt_status` - Check email opt-in status +- `keap_opt_in_contact` - Opt in contact for emails +- `keap_opt_out_contact` - Opt out contact from emails + +### Company Tools (5 tools) + +- `keap_create_company` - Create new company +- `keap_get_company` - Get company by ID +- `keap_update_company` - Update company details +- `keap_list_companies` - List all companies (paginated) +- `keap_search_companies` - Search companies by criteria + +### Opportunity Tools (9 tools) + +- `keap_create_opportunity` - Create new opportunity +- `keap_get_opportunity` - Get opportunity by ID +- `keap_update_opportunity` - Update opportunity details +- `keap_list_opportunities` - List opportunities (paginated) +- `keap_search_opportunities` - Search opportunities by criteria +- `keap_move_opportunity_stage` - Move opportunity to new stage +- `keap_get_opportunity_pipeline` - Get pipeline stages +- `keap_bulk_update_opportunities` - Update multiple opportunities +- `keap_get_opportunity_stage_details` - Get stage information + +### Task Tools (8 tools) + +- `keap_create_task` - Create new task +- `keap_get_task` - Get task by ID +- `keap_update_task` - Update task details +- `keap_delete_task` - Delete task +- `keap_list_tasks` - List tasks (paginated) +- `keap_search_tasks` - Search tasks by criteria +- `keap_complete_task` - Mark task as complete +- `keap_bulk_update_tasks` - Update multiple tasks + +### Appointment Tools (6 tools) + +- `keap_create_appointment` - Create new appointment +- `keap_get_appointment` - Get appointment by ID +- `keap_update_appointment` - Update appointment details +- `keap_delete_appointment` - Delete appointment +- `keap_list_appointments` - List appointments (paginated) +- `keap_search_appointments` - Search appointments by criteria + +### Campaign Tools (7 tools) + +- `keap_create_campaign` - Create new campaign +- `keap_get_campaign` - Get campaign by ID +- `keap_list_campaigns` - List campaigns (paginated) +- `keap_add_contact_to_campaign` - Add contact to campaign sequence +- `keap_remove_contact_from_campaign` - Remove contact from campaign +- `keap_get_campaign_sequence` - Get campaign sequence details +- `keap_get_campaign_achievements` - Get campaign completion data + +### Tag Tools (5 tools) + +- `keap_create_tag` - Create new tag +- `keap_get_tag` - Get tag by ID +- `keap_list_tags` - List all tags +- `keap_create_tag_category` - Create tag category +- `keap_list_tag_categories` - List tag categories + +### Note Tools (6 tools) + +- `keap_create_note` - Create new note +- `keap_get_note` - Get note by ID +- `keap_update_note` - Update note content +- `keap_delete_note` - Delete note +- `keap_list_notes` - List notes (paginated) +- `keap_search_notes` - Search notes by criteria + +### Email Tools (7 tools) + +- `keap_send_email` - Send email to contacts +- `keap_create_email_template` - Create email template +- `keap_get_email_template` - Get template by ID +- `keap_list_email_templates` - List email templates +- `keap_send_template_email` - Send templated email +- `keap_get_email_stats` - Get email sending statistics +- `keap_check_email_deliverability` - Check email configuration + +### File Tools (4 tools) + +- `keap_upload_file` - Upload file to Keap +- `keap_get_file` - Download file by ID +- `keap_list_files` - List uploaded files +- `keap_delete_file` - Delete file + +### E-commerce Tools (15 tools) + +- `keap_create_product` - Create new product +- `keap_get_product` - Get product by ID +- `keap_update_product` - Update product details +- `keap_delete_product` - Delete product +- `keap_list_products` - List products (paginated) +- `keap_create_order` - Create new order +- `keap_get_order` - Get order by ID +- `keap_update_order` - Update order details +- `keap_list_orders` - List orders (paginated) +- `keap_create_subscription` - Create recurring subscription +- `keap_get_subscription` - Get subscription by ID +- `keap_cancel_subscription` - Cancel subscription +- `keap_create_payment` - Record payment +- `keap_refund_payment` - Process refund +- `keap_get_transaction_history` - Get payment history + +### Automation Tools (6 tools) + +- `keap_create_campaign_sequence` - Create automation sequence +- `keap_get_campaign_sequence` - Get sequence details +- `keap_update_campaign_sequence` - Update sequence +- `keap_create_campaign_goal` - Create campaign goal +- `keap_get_campaign_goals` - List campaign goals +- `keap_trigger_link_click` - Trigger link-based automation + +### Settings Tools (5 tools) + +- `keap_get_account_info` - Get account information +- `keap_list_users` - List account users +- `keap_get_user` - Get user details +- `keap_list_custom_fields` - List custom fields +- `keap_create_custom_field` - Create custom field + +### Affiliate Tools (9 tools) + +- `keap_create_affiliate` - Create affiliate account +- `keap_get_affiliate` - Get affiliate by ID +- `keap_list_affiliates` - List affiliates (paginated) +- `keap_update_affiliate` - Update affiliate details +- `keap_get_affiliate_commissions` - Get commission history +- `keap_create_affiliate_payout` - Create payout +- `keap_create_affiliate_clawback` - Reverse commission +- `keap_get_affiliate_summary` - Get performance summary +- `keap_search_affiliates` - Search affiliates by criteria + +## Architecture + +``` +src/ +โ”œโ”€โ”€ server.ts # MCP server setup +โ”œโ”€โ”€ main.ts # Entry point +โ”œโ”€โ”€ clients/ +โ”‚ โ””โ”€โ”€ keap.ts # Keap API client (REST API, rate limiting, error handling) +โ”œโ”€โ”€ tools/ # Tool definitions (14 files) +โ”‚ โ”œโ”€โ”€ contacts-tools.ts +โ”‚ โ”œโ”€โ”€ companies-tools.ts +โ”‚ โ”œโ”€โ”€ opportunities-tools.ts +โ”‚ โ”œโ”€โ”€ tasks-tools.ts +โ”‚ โ”œโ”€โ”€ appointments-tools.ts +โ”‚ โ”œโ”€โ”€ campaigns-tools.ts +โ”‚ โ”œโ”€โ”€ tags-tools.ts +โ”‚ โ”œโ”€โ”€ notes-tools.ts +โ”‚ โ”œโ”€โ”€ emails-tools.ts +โ”‚ โ”œโ”€โ”€ files-tools.ts +โ”‚ โ”œโ”€โ”€ ecommerce-tools.ts +โ”‚ โ”œโ”€โ”€ automations-tools.ts +โ”‚ โ”œโ”€โ”€ settings-tools.ts +โ”‚ โ””โ”€โ”€ affiliates-tools.ts +โ”œโ”€โ”€ types/ +โ”‚ โ””โ”€โ”€ index.ts # TypeScript interfaces +โ””โ”€โ”€ ui/ + โ””โ”€โ”€ react-app/ # MCP Apps (22 apps) + โ”œโ”€โ”€ contact-dashboard/ + โ”œโ”€โ”€ contact-detail/ + โ”œโ”€โ”€ contact-grid/ + โ”œโ”€โ”€ contact-timeline/ + โ”œโ”€โ”€ company-dashboard/ + โ”œโ”€โ”€ company-detail/ + โ”œโ”€โ”€ company-grid/ + โ”œโ”€โ”€ deal-dashboard/ + โ”œโ”€โ”€ deal-detail/ + โ”œโ”€โ”€ pipeline-kanban/ + โ”œโ”€โ”€ pipeline-funnel/ + โ”œโ”€โ”€ task-manager/ + โ”œโ”€โ”€ appointment-calendar/ + โ”œโ”€โ”€ campaign-dashboard/ + โ”œโ”€โ”€ campaign-detail/ + โ”œโ”€โ”€ email-composer/ + โ”œโ”€โ”€ tag-manager/ + โ”œโ”€โ”€ automation-dashboard/ + โ”œโ”€โ”€ product-catalog/ + โ”œโ”€โ”€ order-dashboard/ + โ”œโ”€โ”€ order-detail/ + โ””โ”€โ”€ revenue-dashboard/ +``` + +## API Coverage + +- โœ… Contacts API (complete) +- โœ… Companies API (complete) +- โœ… Opportunities API (complete) +- โœ… Tasks API (complete) +- โœ… Appointments API (complete) +- โœ… Campaigns API (complete) +- โœ… Tags API (complete) +- โœ… Notes API (complete) +- โœ… Emails API (complete) +- โœ… Files API (complete) +- โœ… E-commerce API (complete - products, orders, subscriptions, payments) +- โœ… Automations API (campaign sequences, goals, triggers) +- โœ… Settings API (account info, users, custom fields) +- โœ… Affiliates API (complete) + +## Rate Limiting + +The Keap API enforces rate limits: + +- **Burst limit**: 10 requests per second +- **Daily limit**: 10,000 requests per day (may vary by plan) + +The MCP client automatically handles rate limiting with: +- Exponential backoff on 429 responses +- Request queuing +- Automatic retry logic + +## Error Handling + +All tools provide comprehensive error messages: + +```json +{ + "isError": true, + "content": [ + { + "type": "text", + "text": "Error: Contact not found (ID: 12345)" + } + ] +} +``` + +Common error scenarios: +- Invalid authentication (401) +- Rate limit exceeded (429) +- Resource not found (404) +- Validation errors (400) +- Server errors (500) + +## Development + +### Build from source + +```bash +git clone https://github.com/BusyBee3333/mcpengine +cd mcpengine/servers/keap +npm install +npm run build +``` + +### Run in development mode + +```bash +npm run dev +``` + +### Type checking + +```bash +npx tsc --noEmit +``` + +### Build React apps ```bash cd src/ui/react-app @@ -387,85 +496,104 @@ npm install npm run build ``` -Individual app builds are output to `dist/{app-name}/`. +## Best Practices -## ๐Ÿ” Authentication +### Contact Management -The server uses OAuth 2.0 PKCE flow: +1. **Use tags effectively**: Organize contacts with meaningful tags for segmentation +2. **Custom fields**: Leverage custom fields for industry-specific data +3. **Merge duplicates**: Regularly use `keap_merge_contacts` to maintain data quality +4. **Opt-in compliance**: Always check opt status before sending marketing emails -1. Set `KEAP_CLIENT_ID` and `KEAP_CLIENT_SECRET` in `.env` -2. Run the OAuth flow to get initial tokens -3. Tokens are auto-refreshed when expired -4. Refresh token is persisted for long-term access +### Sales Pipeline -## ๐Ÿ“Š Data Models +1. **Consistent stage moves**: Use `keap_move_opportunity_stage` to track progression +2. **Revenue tracking**: Keep projected revenue updated for accurate forecasting +3. **Pipeline hygiene**: Regularly review and close stale opportunities -All tools that create or update resources include a corresponding `get_*_model` tool that returns the schema, validation rules, and field definitions. +### Automation -Example: +1. **Campaign sequences**: Build automated follow-up sequences for lead nurturing +2. **Goal tracking**: Set clear goals to measure campaign effectiveness +3. **Link triggers**: Use link-based triggers for behavior-based automation + +### E-commerce + +1. **Product catalog**: Maintain accurate SKUs and pricing +2. **Order tracking**: Use order IDs consistently across systems +3. **Subscription management**: Monitor subscription status and renewal dates +4. **Payment reconciliation**: Regular transaction history reviews + +## Keap Plans & Features + +Different Keap plans provide varying API capabilities: + +- **Lite**: Basic contact and email tools +- **Pro**: Full CRM, sales pipeline, and automation +- **Max**: E-commerce, advanced automations, affiliate management +- **Max Classic**: Legacy features, additional e-commerce capabilities + +Ensure your plan supports the features you intend to use via the API. + +## Troubleshooting + +### Authentication Issues + +```bash +# Verify your API key +curl -H "X-Keap-API-Key: YOUR_API_KEY" https://api.infusionsoft.com/crm/rest/v1/account/profile +``` + +### Rate Limiting + +If you encounter frequent rate limits: +1. Reduce concurrent request volume +2. Implement longer delays between operations +3. Consider upgrading your Keap plan for higher limits + +### Contact Not Found + +Ensure contact IDs are valid: ```typescript -// Get contact model to understand required fields -const model = await callTool('keap_get_contact_model'); - -// Create contact with proper fields -const contact = await callTool('keap_create_contact', { - given_name: 'John', - family_name: 'Doe', - email: 'john@example.com', - opt_in_reason: 'Website signup' +// First search for the contact +const result = await keap_search_contacts({ + email: "user@example.com" }); +// Then use the returned ID ``` -## ๐Ÿšฆ Rate Limits +## Migration from Infusionsoft XML-RPC -Keap API has rate limits: -- 150 requests per second per account -- Daily request quotas based on plan +If migrating from the legacy XML-RPC API: -The client includes automatic retry with exponential backoff for rate limit errors. +1. **Authentication**: Replace legacy keys with Personal Access Tokens +2. **Endpoints**: Update from XML-RPC to REST API patterns +3. **Data format**: Convert XML structures to JSON +4. **Field mappings**: Review custom field IDs (may have changed) -## ๐Ÿงช Testing - -```bash -npm test -``` - -## ๐Ÿ“ Development - -```bash -# Install dependencies -npm install - -# Run in development mode -npm run dev - -# Build TypeScript -npm run build - -# Type check -npx tsc --noEmit -``` - -## ๐Ÿค Contributing - -Contributions welcome! Please ensure: -- All TypeScript code type-checks without errors -- React apps maintain dark theme consistency -- New tools include proper input schemas and descriptions -- README is updated for new functionality - -## ๐Ÿ“„ License +## License MIT -## ๐Ÿ”— Links +## Support -- [Keap API Documentation](https://developer.keap.com/docs/) -- [MCP Protocol Specification](https://modelcontextprotocol.io/) -- [MCPEngine GitHub](https://github.com/BusyBee3333/mcpengine) +For issues and feature requests, please visit: +https://github.com/BusyBee3333/mcpengine/issues ---- +## Related -**Built with โค๏ธ by MCPEngine** +- [Keap API Documentation](https://developer.keap.com/docs/rest/) +- [Keap Developer Portal](https://keys.developer.keap.com/) +- [Model Context Protocol](https://modelcontextprotocol.io) +- [MCPEngine Repository](https://github.com/BusyBee3333/mcpengine) -*Keap is a registered trademark of Keap Inc. This is an unofficial community project.* +## Changelog + +### Version 1.0.0 + +- Initial release +- 111 tools across 14 categories +- 22 React apps for visual interfaces +- Full Keap REST API coverage +- Rate limiting and error handling +- Comprehensive TypeScript types