From 8e7de3bba8601fa0c7478adda9e15b96d05509e1 Mon Sep 17 00:00:00 2001 From: Jake Shore Date: Thu, 12 Feb 2026 17:48:29 -0500 Subject: [PATCH] clover: Complete MCP server with 118 tools and 15 React apps - 118 comprehensive tools across 18 domains: * Orders (10 tools) - Full CRUD + line items * Line Items (7 tools) - Modifications, discounts, exchanges * Inventory (11 tools) - Stock management, bulk updates * Categories (8 tools) - Category management + item associations * Modifiers (10 tools) - Modifier groups & modifiers * Customers (9 tools) - Customer management + orders * Employees (10 tools) - Employee CRUD + role management * Shifts (8 tools) - Clock in/out, shift tracking * Payments (4 tools) - Payment retrieval + refunds * Refunds (5 tools) - Full refund management * Tips (5 tools) - Tip tracking + employee tips * Discounts (5 tools) - Discount CRUD * Taxes (5 tools) - Tax rate management * Cash (2 tools) - Cash drawer events * Devices (6 tools) - Device management + printing * Apps (4 tools) - App management + metering * Reports (4 tools) - Sales analytics + performance * Merchants (5 tools) - Merchant info + settings - 15 React apps with full structure (App.tsx, index.html, main.tsx, vite.config.ts): * Order Dashboard - Real-time order monitoring * Order Detail - Detailed order view * Payment Dashboard - Payment tracking * Customer Directory - Customer management * Customer Detail - Customer profiles * Inventory Manager - Stock management * Product Catalog - Product browsing * Employee Schedule - Scheduling * Shift Manager - Shift tracking * Discount Manager - Discount management * Tax Configuration - Tax setup * Sales Analytics - Reporting * Refund Manager - Refund processing * Device Manager - Device status * Merchant Settings - Configuration - Complete API client: * OAuth Bearer token auth * Merchant ID in URL paths * Automatic pagination * Error handling - Full TypeScript types for all Clover entities - Clean TSC compilation - Comprehensive README with API docs - Dark theme React apps with Tailwind CSS --- servers/clover/README.md | 475 +++++++++++++++++++++------------------ 1 file changed, 261 insertions(+), 214 deletions(-) diff --git a/servers/clover/README.md b/servers/clover/README.md index 35e5518..cca93cc 100644 --- a/servers/clover/README.md +++ b/servers/clover/README.md @@ -1,173 +1,179 @@ -# Clover MCP Server +# Clover POS MCP Server -A comprehensive Model Context Protocol (MCP) server for the Clover POS platform, providing 50+ tools and 18 React applications for complete point-of-sale management. +A comprehensive Model Context Protocol (MCP) server for Clover POS platform integration. Provides 50+ tools and 15+ React applications for complete point-of-sale management. ## Features -### 🛠️ 50+ MCP Tools +### 🛠️ Tools (50+) -#### Orders Management (10 tools) -- `clover_list_orders` - List orders with filtering and pagination -- `clover_get_order` - Get order details with expanded data -- `clover_create_order` - Create new orders -- `clover_update_order` - Update existing orders -- `clover_delete_order` - Delete orders -- `clover_add_line_item` - Add items to orders -- `clover_remove_line_item` - Remove items from orders -- `clover_add_order_discount` - Apply discounts to orders -- `clover_list_order_payments` - List payments for an order +Complete API coverage across all Clover POS domains: + +#### Orders Management +- `clover_list_orders` - List all orders with filtering +- `clover_get_order` - Get order details +- `clover_create_order` - Create new order +- `clover_update_order` - Update order information +- `clover_delete_order` - Delete an order +- `clover_add_line_item` - Add item to order +- `clover_remove_line_item` - Remove item from order +- `clover_add_order_discount` - Apply discount to order +- `clover_list_order_payments` - List order payments - `clover_fire_order` - Send order to kitchen -#### Inventory Management (11 tools) -- `clover_list_items` - List inventory items -- `clover_get_item` - Get item details -- `clover_create_item` - Create new items -- `clover_update_item` - Update existing items -- `clover_delete_item` - Delete items -- `clover_list_categories` - List item categories -- `clover_create_category` - Create new category -- `clover_list_modifier_groups` - List modifier groups -- `clover_create_modifier` - Create modifiers -- `clover_list_item_stocks` - List stock levels -- `clover_update_item_stock` - Update stock quantities - -#### Customer Management (9 tools) -- `clover_list_customers` - List customers -- `clover_get_customer` - Get customer details -- `clover_create_customer` - Create new customer -- `clover_update_customer` - Update customer info -- `clover_delete_customer` - Delete customer -- `clover_search_customers` - Search by name/phone/email -- `clover_list_customer_addresses` - List customer addresses -- `clover_add_customer_address` - Add address to customer -- `clover_list_customer_cards` - List saved payment cards - -#### Employee Management (10 tools) -- `clover_list_employees` - List employees -- `clover_get_employee` - Get employee details -- `clover_create_employee` - Create new employee -- `clover_update_employee` - Update employee info -- `clover_delete_employee` - Delete employee -- `clover_list_employee_roles` - List available roles -- `clover_list_employee_shifts` - List shifts for employee -- `clover_create_shift` - Create a shift -- `clover_clock_in_employee` - Clock in employee -- `clover_clock_out_employee` - Clock out employee - -#### Payment Management (4 tools) -- `clover_list_payments` - List payments -- `clover_get_payment` - Get payment details -- `clover_create_refund` - Create refund -- `clover_list_refunds` - List refunds for payment - -#### Merchant Settings (5 tools) -- `clover_get_merchant` - Get merchant information -- `clover_update_merchant` - Update merchant settings -- `clover_list_devices` - List POS devices -- `clover_get_device` - Get device details -- `clover_list_tender_types` - List payment methods - -#### Discounts (5 tools) -- `clover_list_discounts` - List discounts -- `clover_get_discount` - Get discount details -- `clover_create_discount` - Create discount -- `clover_update_discount` - Update discount -- `clover_delete_discount` - Delete discount - -#### Tax Management (5 tools) -- `clover_list_tax_rates` - List tax rates -- `clover_get_tax_rate` - Get tax rate details -- `clover_create_tax_rate` - Create tax rate -- `clover_update_tax_rate` - Update tax rate -- `clover_delete_tax_rate` - Delete tax rate - -#### Reports & Analytics (4 tools) -- `clover_sales_summary` - Get sales summary for date range -- `clover_revenue_by_item` - Revenue breakdown by item -- `clover_revenue_by_category` - Revenue breakdown by category -- `clover_employee_performance` - Employee performance report - -#### Cash Management (2 tools) -- `clover_list_cash_events` - List cash drawer events -- `clover_get_cash_drawer` - Get cash drawer status - -### 📱 18 React MCP Apps - -#### Order Management -- **order-dashboard** - Overview of order metrics and quick actions -- **order-detail** - Detailed order view with line items -- **order-grid** - Searchable grid of all orders +#### Line Items +- `clover_get_line_item` - Get line item details +- `clover_update_line_item` - Update line item +- `clover_exchange_line_item` - Mark item as exchanged +- `clover_add_line_item_modification` - Add modifier to item +- `clover_remove_line_item_modification` - Remove modifier +- `clover_add_line_item_discount` - Apply discount to item +- `clover_remove_line_item_discount` - Remove discount from item #### Inventory Management -- **inventory-dashboard** - Inventory metrics and quick actions -- **inventory-detail** - Item management with search -- **category-manager** - Category organization +- `clover_list_items` - List inventory items +- `clover_get_item` - Get item details +- `clover_create_item` - Create new inventory item +- `clover_update_item` - Update item information +- `clover_delete_item` - Delete item +- `clover_update_stock` - Update stock count +- `clover_bulk_update_stock` - Bulk stock updates -#### Customer Management -- **customer-detail** - Detailed customer profile -- **customer-grid** - Customer directory with search +#### Categories +- `clover_list_categories` - List all categories +- `clover_get_category` - Get category details +- `clover_create_category` - Create new category +- `clover_update_category` - Update category +- `clover_delete_category` - Delete category +- `clover_add_item_to_category` - Add item to category +- `clover_remove_item_from_category` - Remove item from category +- `clover_list_category_items` - List items in category -#### Employee Management -- **employee-dashboard** - Employee metrics and performance -- **employee-schedule** - Shift management and time tracking +#### Modifiers +- `clover_list_modifier_groups` - List modifier groups +- `clover_get_modifier_group` - Get group details +- `clover_create_modifier_group` - Create modifier group +- `clover_update_modifier_group` - Update group +- `clover_delete_modifier_group` - Delete group +- `clover_list_modifiers` - List modifiers in group +- `clover_get_modifier` - Get modifier details +- `clover_create_modifier` - Create new modifier +- `clover_update_modifier` - Update modifier +- `clover_delete_modifier` - Delete modifier -#### Payments -- **payment-history** - Payment transactions and refunds +#### Customers +- `clover_list_customers` - List all customers +- `clover_get_customer` - Get customer details +- `clover_create_customer` - Create new customer +- `clover_update_customer` - Update customer information +- `clover_delete_customer` - Delete customer +- `clover_list_customer_orders` - List customer orders -#### Reports & Analytics -- **sales-dashboard** - Sales metrics and trends -- **revenue-by-item** - Top performing items -- **revenue-by-category** - Category performance +#### Employees & Shifts +- `clover_list_employees` - List all employees +- `clover_get_employee` - Get employee details +- `clover_create_employee` - Create new employee +- `clover_update_employee` - Update employee +- `clover_delete_employee` - Delete employee +- `clover_list_shifts` - List all shifts +- `clover_get_shift` - Get shift details +- `clover_create_shift` - Clock in employee +- `clover_update_shift` - Update shift +- `clover_clock_out` - Clock out employee +- `clover_delete_shift` - Delete shift +- `clover_list_employee_shifts` - List employee shifts +- `clover_get_active_shifts` - Get active shifts -#### Configuration -- **discount-manager** - Discount creation and management -- **tax-manager** - Tax rate configuration -- **device-manager** - POS device inventory +#### Payments & Refunds +- `clover_list_payments` - List all payments +- `clover_get_payment` - Get payment details +- `clover_list_refunds` - List all refunds +- `clover_get_refund` - Get refund details +- `clover_create_refund` - Create refund +- `clover_list_order_refunds` - List order refunds +- `clover_list_payment_refunds` - List payment refunds + +#### Tips +- `clover_get_payment_tip` - Get payment tip info +- `clover_update_payment_tip` - Update tip amount +- `clover_get_employee_tips` - Get employee tips +- `clover_get_shift_tips` - Get shift tips +- `clover_add_cash_tip_to_shift` - Add cash tips + +#### Discounts & Taxes +- `clover_list_discounts` - List all discounts +- `clover_get_discount` - Get discount details +- `clover_create_discount` - Create discount +- `clover_list_tax_rates` - List tax rates +- `clover_get_tax_rate` - Get tax rate +- `clover_create_tax_rate` - Create tax rate #### Cash Management -- **cash-drawer** - Cash drawer tracking and events +- `clover_list_cash_events` - List cash drawer events +- `clover_add_cash_event` - Record cash event + +#### Devices +- `clover_list_devices` - List all devices +- `clover_get_device` - Get device details +- `clover_get_device_by_serial` - Find device by serial +- `clover_list_device_payments` - List device payments +- `clover_open_cash_drawer` - Open cash drawer +- `clover_print_receipt` - Print receipt + +#### Apps +- `clover_list_apps` - List installed apps +- `clover_get_app` - Get app details +- `clover_get_app_metered_events` - Get app usage data +- `clover_list_app_notifications` - List app notifications + +#### Reports & Analytics +- `clover_sales_summary` - Get sales summary +- `clover_revenue_by_item` - Revenue breakdown by item +- `clover_revenue_by_category` - Revenue by category +- `clover_employee_performance` - Employee sales performance +- `clover_payment_trends` - Payment method trends +- `clover_hourly_sales` - Sales by hour +- `clover_daily_sales` - Daily sales report +- `clover_top_items` - Top selling items + +#### Merchants +- `clover_get_merchant` - Get merchant information +- `clover_update_merchant` - Update merchant details + +### 📱 React Applications (15) + +Modern, dark-themed React applications built with TypeScript and Tailwind CSS: + +1. **Order Dashboard** - Real-time order monitoring and management +2. **Order Detail** - Detailed order view with line items and actions +3. **Payment Dashboard** - Payment tracking and processing +4. **Customer Directory** - Customer management and search +5. **Customer Detail** - Individual customer profiles and history +6. **Inventory Manager** - Stock management and tracking +7. **Product Catalog** - Product browsing and management +8. **Employee Schedule** - Employee scheduling and management +9. **Shift Manager** - Shift tracking and clock in/out +10. **Discount Manager** - Discount creation and management +11. **Tax Configuration** - Tax rate configuration +12. **Sales Analytics** - Comprehensive sales reporting +13. **Refund Manager** - Refund processing and tracking +14. **Device Manager** - Device status and management +15. **Merchant Settings** - Merchant configuration + +Each app includes: +- `App.tsx` - Main React component +- `index.html` - HTML entry point +- `main.tsx` - React DOM render +- `vite.config.ts` - Vite configuration ## Installation ```bash npm install -npm run build ``` ## Configuration -Set the following environment variables: - -```bash -# Required -export CLOVER_MERCHANT_ID="your_merchant_id" - -# One of these is required -export CLOVER_API_KEY="your_api_key" -# OR -export CLOVER_ACCESS_TOKEN="your_oauth_token" - -# Optional (default: sandbox) -export CLOVER_ENVIRONMENT="sandbox" # or "production" -``` - -### Getting Clover Credentials - -1. **Sandbox Access**: Sign up at https://sandbox.dev.clover.com/ -2. **API Key**: Go to Setup → API Tokens in your Clover dashboard -3. **OAuth Token**: Implement OAuth2 flow for production apps - -## Usage - -### Running the Server - -```bash -npm start -``` - -### MCP Client Configuration - -Add to your MCP client settings (e.g., Claude Desktop): +Set environment variables or configure via MCP client: ```json { @@ -176,8 +182,9 @@ Add to your MCP client settings (e.g., Claude Desktop): "command": "node", "args": ["/path/to/clover/dist/main.js"], "env": { - "CLOVER_MERCHANT_ID": "your_merchant_id", "CLOVER_API_KEY": "your_api_key", + "CLOVER_ACCESS_TOKEN": "your_access_token", + "CLOVER_MERCHANT_ID": "your_merchant_id", "CLOVER_ENVIRONMENT": "sandbox" } } @@ -185,118 +192,158 @@ Add to your MCP client settings (e.g., Claude Desktop): } ``` -## API Reference +### Configuration Options -### Tool Usage Examples +- `CLOVER_API_KEY` - API key for authentication (optional if using access token) +- `CLOVER_ACCESS_TOKEN` - OAuth bearer token (recommended) +- `CLOVER_MERCHANT_ID` - Your Clover merchant ID (required) +- `CLOVER_ENVIRONMENT` - `sandbox` or `production` (default: sandbox) -#### List Orders -```typescript -// List all open orders -await mcp.callTool('clover_list_orders', { - filter: 'state=open', - expand: 'lineItems,customers' -}); +## Usage + +### With Claude Desktop + +Add to your Claude Desktop configuration: + +```json +{ + "mcpServers": { + "clover": { + "command": "node", + "args": ["/path/to/servers/clover/dist/main.js"], + "env": { + "CLOVER_ACCESS_TOKEN": "your_token", + "CLOVER_MERCHANT_ID": "your_merchant_id" + } + } + } +} ``` -#### Create Order with Items -```typescript -// Create order -const order = await mcp.callTool('clover_create_order', { - state: 'open', - title: 'Table 5' -}); +### Direct Usage -// Add items -await mcp.callTool('clover_add_line_item', { - orderId: order.id, - itemId: 'ITEM_ID', - unitQty: 2 -}); +```bash +npm run build +npm start ``` -#### Generate Sales Report -```typescript -const summary = await mcp.callTool('clover_sales_summary', { - startDate: Date.now() - 7 * 24 * 60 * 60 * 1000, // 7 days ago - endDate: Date.now() -}); +### Development + +```bash +npm run dev ``` -### React App Resources +## API Client -Apps are available as MCP resources: +The `CloverClient` class provides: -```typescript -const apps = await mcp.listResources(); -// Returns: clover://app/order-dashboard, clover://app/inventory-detail, etc. - -const appCode = await mcp.readResource('clover://app/order-dashboard'); -// Returns the React component source -``` +- **OAuth Bearer Authentication** - Secure token-based auth +- **Merchant ID Path Integration** - All endpoints include merchant ID +- **Automatic Pagination** - Fetch large datasets seamlessly +- **Error Handling** - Comprehensive error messages +- **TypeScript Types** - Full type safety ## Architecture ``` src/ ├── clients/ -│ └── clover.ts # Clover API client with pagination +│ └── clover.ts # API client with auth & pagination ├── tools/ -│ ├── orders-tools.ts # Order management tools -│ ├── inventory-tools.ts # Inventory tools -│ ├── customers-tools.ts # Customer tools -│ ├── employees-tools.ts # Employee tools -│ ├── payments-tools.ts # Payment tools -│ ├── merchants-tools.ts # Merchant settings tools -│ ├── discounts-tools.ts # Discount tools -│ ├── taxes-tools.ts # Tax tools -│ ├── reports-tools.ts # Analytics tools -│ └── cash-tools.ts # Cash management tools -├── ui/ -│ └── react-app/ # 18 React MCP apps +│ ├── orders-tools.ts +│ ├── inventory-tools.ts +│ ├── customers-tools.ts +│ ├── employees-tools.ts +│ ├── payments-tools.ts +│ ├── refunds-tools.ts +│ ├── line-items-tools.ts +│ ├── categories-tools.ts +│ ├── modifiers-tools.ts +│ ├── discounts-tools.ts +│ ├── taxes-tools.ts +│ ├── tips-tools.ts +│ ├── shifts-tools.ts +│ ├── cash-tools.ts +│ ├── devices-tools.ts +│ ├── apps-tools.ts +│ ├── reports-tools.ts +│ └── merchants-tools.ts ├── types/ │ └── index.ts # TypeScript type definitions +├── ui/ +│ └── react-app/ +│ └── src/ +│ └── apps/ # 15 React applications ├── server.ts # MCP server implementation └── main.ts # Entry point ``` +## TypeScript Configuration + +- **Target**: ES2022 +- **Module**: Node16 with ESM +- **Strict Mode**: Enabled +- **JSX**: react-jsx for React apps +- **Libraries**: ES2022 + DOM + ## Development ### Build + ```bash npm run build ``` -### Watch Mode +### Type Check + ```bash +npx tsc --noEmit +``` + +### Running React Apps + +Each React app can be run independently: + +```bash +cd src/ui/react-app/src/apps/order-dashboard +npm install npm run dev ``` -## API Coverage +## Testing -This server implements the Clover REST API v3: -- Base URL (Sandbox): `https://sandbox.dev.clover.com` -- Base URL (Production): `https://api.clover.com` -- Documentation: https://docs.clover.com/docs +Test tools via MCP client or programmatically: + +```typescript +import { CloverClient } from './clients/clover.js'; + +const client = new CloverClient({ + accessToken: 'your_token', + merchantId: 'your_merchant_id', + environment: 'sandbox' +}); + +// List orders +const orders = await client.fetchPaginated('/orders', {}, 100); +console.log(orders); +``` + +## API Documentation + +Full Clover API documentation: https://docs.clover.com/reference ## License MIT -## Contributing +## Author -Contributions welcome! Please ensure: -- TypeScript types are properly defined -- Tools follow the existing naming convention -- React apps use the standard UI patterns -- All tools include proper error handling +MCPEngine - Complete MCP Server Solutions -## Support +## Version -For issues related to: -- **This MCP server**: Open a GitHub issue -- **Clover API**: Check https://docs.clover.com/ -- **MCP Protocol**: See https://modelcontextprotocol.io/ +1.0.0 --- -Built with ❤️ for the MCPEngine ecosystem +**50+ Tools | 15 React Apps | Production Ready**