clover: Add comprehensive 545-line README documenting 118 tools and 18 React apps
This commit is contained in:
Jake Shore
parent
dfd9620d30
commit
049d1fa718
@ -1,190 +1,74 @@
|
|||||||
# Clover POS MCP Server
|
# Clover MCP Server
|
||||||
|
|
||||||
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.
|
A comprehensive Model Context Protocol (MCP) server for the Clover POS platform, providing 118 tools across 18 categories and 18 interactive React applications for managing all aspects of a Clover merchant account.
|
||||||
|
|
||||||
|
## Overview
|
||||||
|
|
||||||
|
The Clover MCP Server enables AI assistants to interact with Clover POS systems through a standardized interface. It provides complete access to orders, inventory, customers, employees, payments, reporting, and more — all through MCP tools and rich web-based UIs.
|
||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
### 🛠️ Tools (50+)
|
- **118 MCP Tools** across 18 functional categories
|
||||||
|
- **18 React Applications** for visual management and reporting
|
||||||
Complete API coverage across all Clover POS domains:
|
- **Full CRUD Operations** for all major Clover entities
|
||||||
|
- **Real-time Data** via Clover REST API v3
|
||||||
#### Orders Management
|
- **Environment Support** for both sandbox and production
|
||||||
- `clover_list_orders` - List all orders with filtering
|
- **TypeScript** for type safety and developer experience
|
||||||
- `clover_get_order` - Get order details
|
- **MCP Resources** for serving interactive React apps
|
||||||
- `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
|
|
||||||
|
|
||||||
#### 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
|
|
||||||
- `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
|
|
||||||
|
|
||||||
#### 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
|
|
||||||
|
|
||||||
#### 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
|
|
||||||
|
|
||||||
#### 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
|
|
||||||
|
|
||||||
#### 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
|
|
||||||
|
|
||||||
#### 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
|
|
||||||
- `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
|
## Installation
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
npm install @mcpengine/clover-server
|
||||||
|
```
|
||||||
|
|
||||||
|
Or install from source:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
git clone <repo-url>
|
||||||
|
cd servers/clover
|
||||||
npm install
|
npm install
|
||||||
|
npm run build
|
||||||
```
|
```
|
||||||
|
|
||||||
## Configuration
|
## Configuration
|
||||||
|
|
||||||
Set environment variables or configure via MCP client:
|
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 (defaults to sandbox)
|
||||||
|
export CLOVER_ENVIRONMENT="sandbox" # or "production"
|
||||||
|
```
|
||||||
|
|
||||||
|
### Getting Clover Credentials
|
||||||
|
|
||||||
|
1. **Merchant ID**: Found in your Clover dashboard under Account & Setup
|
||||||
|
2. **API Key**: Generate from the Clover developer dashboard for your app
|
||||||
|
3. **Access Token**: OAuth token obtained through Clover's OAuth flow
|
||||||
|
4. **Environment**: Use `sandbox` for testing, `production` for live data
|
||||||
|
|
||||||
|
## Usage
|
||||||
|
|
||||||
|
### As an MCP Server
|
||||||
|
|
||||||
|
Add to your MCP client configuration (e.g., Claude Desktop):
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"mcpServers": {
|
"mcpServers": {
|
||||||
"clover": {
|
"clover": {
|
||||||
"command": "node",
|
"command": "clover-mcp",
|
||||||
"args": ["/path/to/clover/dist/main.js"],
|
|
||||||
"env": {
|
"env": {
|
||||||
"CLOVER_API_KEY": "your_api_key",
|
"CLOVER_MERCHANT_ID": "your-merchant-id",
|
||||||
"CLOVER_ACCESS_TOKEN": "your_access_token",
|
"CLOVER_API_KEY": "your-api-key",
|
||||||
"CLOVER_MERCHANT_ID": "your_merchant_id",
|
|
||||||
"CLOVER_ENVIRONMENT": "sandbox"
|
"CLOVER_ENVIRONMENT": "sandbox"
|
||||||
}
|
}
|
||||||
}
|
}
|
||||||
@ -192,100 +76,380 @@ Set environment variables or configure via MCP client:
|
|||||||
}
|
}
|
||||||
```
|
```
|
||||||
|
|
||||||
### Configuration Options
|
### Programmatic Usage
|
||||||
|
|
||||||
- `CLOVER_API_KEY` - API key for authentication (optional if using access token)
|
```typescript
|
||||||
- `CLOVER_ACCESS_TOKEN` - OAuth bearer token (recommended)
|
import { CloverServer } from '@mcpengine/clover-server';
|
||||||
- `CLOVER_MERCHANT_ID` - Your Clover merchant ID (required)
|
|
||||||
- `CLOVER_ENVIRONMENT` - `sandbox` or `production` (default: sandbox)
|
|
||||||
|
|
||||||
## Usage
|
const server = new CloverServer({
|
||||||
|
merchantId: 'your-merchant-id',
|
||||||
|
apiKey: 'your-api-key',
|
||||||
|
environment: 'sandbox'
|
||||||
|
});
|
||||||
|
|
||||||
### With Claude Desktop
|
await server.run();
|
||||||
|
|
||||||
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"
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Direct Usage
|
## MCP Tools (118 Total)
|
||||||
|
|
||||||
```bash
|
### Apps Tools (4)
|
||||||
npm run build
|
|
||||||
npm start
|
|
||||||
```
|
|
||||||
|
|
||||||
### Development
|
- `clover_get_app` - Get details for a specific app
|
||||||
|
- `clover_get_app_metered_events` - Get metered events for an app
|
||||||
|
- `clover_list_app_notifications` - List app notifications
|
||||||
|
- `clover_list_apps` - List all installed apps
|
||||||
|
|
||||||
```bash
|
### Cash Tools (2)
|
||||||
npm run dev
|
|
||||||
```
|
|
||||||
|
|
||||||
## API Client
|
- `clover_get_cash_drawer` - Get cash drawer status and details
|
||||||
|
- `clover_list_cash_events` - List cash drawer events (opens, deposits, etc.)
|
||||||
|
|
||||||
The `CloverClient` class provides:
|
### Categories Tools (8)
|
||||||
|
|
||||||
- **OAuth Bearer Authentication** - Secure token-based auth
|
- `clover_add_item_to_category` - Add an item to a category
|
||||||
- **Merchant ID Path Integration** - All endpoints include merchant ID
|
- `clover_create_category` - Create a new category
|
||||||
- **Automatic Pagination** - Fetch large datasets seamlessly
|
- `clover_delete_category` - Delete a category
|
||||||
- **Error Handling** - Comprehensive error messages
|
- `clover_get_category` - Get category details
|
||||||
- **TypeScript Types** - Full type safety
|
- `clover_list_categories` - List all categories
|
||||||
|
- `clover_list_category_items` - List items in a category
|
||||||
|
- `clover_remove_item_from_category` - Remove an item from a category
|
||||||
|
- `clover_update_category` - Update category details
|
||||||
|
|
||||||
|
### Customers Tools (9)
|
||||||
|
|
||||||
|
- `clover_add_customer_address` - Add an address to a customer
|
||||||
|
- `clover_create_customer` - Create a new customer
|
||||||
|
- `clover_delete_customer` - Delete a customer
|
||||||
|
- `clover_get_customer` - Get customer details
|
||||||
|
- `clover_list_customer_addresses` - List customer addresses
|
||||||
|
- `clover_list_customer_cards` - List customer payment cards
|
||||||
|
- `clover_list_customers` - List all customers
|
||||||
|
- `clover_search_customers` - Search customers by various criteria
|
||||||
|
- `clover_update_customer` - Update customer information
|
||||||
|
|
||||||
|
### Devices Tools (6)
|
||||||
|
|
||||||
|
- `clover_get_device` - Get device details by ID
|
||||||
|
- `clover_get_device_by_serial` - Get device by serial number
|
||||||
|
- `clover_list_device_payments` - List payments processed by a device
|
||||||
|
- `clover_list_devices` - List all merchant devices
|
||||||
|
- `clover_open_cash_drawer` - Open a device's cash drawer remotely
|
||||||
|
- `clover_print_receipt` - Print a receipt on a device
|
||||||
|
|
||||||
|
### Discounts Tools (5)
|
||||||
|
|
||||||
|
- `clover_create_discount` - Create a new discount
|
||||||
|
- `clover_delete_discount` - Delete a discount
|
||||||
|
- `clover_get_discount` - Get discount details
|
||||||
|
- `clover_list_discounts` - List all discounts
|
||||||
|
- `clover_update_discount` - Update discount settings
|
||||||
|
|
||||||
|
### Employees Tools (10)
|
||||||
|
|
||||||
|
- `clover_clock_in_employee` - Clock in an employee
|
||||||
|
- `clover_clock_out_employee` - Clock out an employee
|
||||||
|
- `clover_create_employee` - Create a new employee
|
||||||
|
- `clover_create_shift` - Create a new shift
|
||||||
|
- `clover_delete_employee` - Delete an employee
|
||||||
|
- `clover_get_employee` - Get employee details
|
||||||
|
- `clover_list_employee_roles` - List employee roles
|
||||||
|
- `clover_list_employee_shifts` - List shifts for an employee
|
||||||
|
- `clover_list_employees` - List all employees
|
||||||
|
- `clover_update_employee` - Update employee information
|
||||||
|
|
||||||
|
### Inventory Tools (11)
|
||||||
|
|
||||||
|
- `clover_create_category` - Create an inventory category
|
||||||
|
- `clover_create_item` - Create a new inventory item
|
||||||
|
- `clover_create_modifier` - Create a modifier for items
|
||||||
|
- `clover_delete_item` - Delete an inventory item
|
||||||
|
- `clover_get_item` - Get item details
|
||||||
|
- `clover_list_categories` - List inventory categories
|
||||||
|
- `clover_list_item_stocks` - List stock levels for items
|
||||||
|
- `clover_list_items` - List all inventory items
|
||||||
|
- `clover_list_modifier_groups` - List modifier groups
|
||||||
|
- `clover_update_item` - Update item details
|
||||||
|
- `clover_update_item_stock` - Update item stock levels
|
||||||
|
|
||||||
|
### Line Items Tools (7)
|
||||||
|
|
||||||
|
- `clover_add_line_item_discount` - Add a discount to a line item
|
||||||
|
- `clover_add_line_item_modification` - Add a modification to a line item
|
||||||
|
- `clover_exchange_line_item` - Exchange a line item
|
||||||
|
- `clover_get_line_item` - Get line item details
|
||||||
|
- `clover_remove_line_item_discount` - Remove a line item discount
|
||||||
|
- `clover_remove_line_item_modification` - Remove a line item modification
|
||||||
|
- `clover_update_line_item` - Update line item details
|
||||||
|
|
||||||
|
### Merchants Tools (5)
|
||||||
|
|
||||||
|
- `clover_get_device` - Get merchant device information
|
||||||
|
- `clover_get_merchant` - Get merchant account details
|
||||||
|
- `clover_list_devices` - List all merchant devices
|
||||||
|
- `clover_list_tender_types` - List accepted tender types
|
||||||
|
- `clover_update_merchant` - Update merchant settings
|
||||||
|
|
||||||
|
### Modifiers Tools (10)
|
||||||
|
|
||||||
|
- `clover_create_modifier` - Create a new modifier
|
||||||
|
- `clover_create_modifier_group` - Create a modifier group
|
||||||
|
- `clover_delete_modifier` - Delete a modifier
|
||||||
|
- `clover_delete_modifier_group` - Delete a modifier group
|
||||||
|
- `clover_get_modifier` - Get modifier details
|
||||||
|
- `clover_get_modifier_group` - Get modifier group details
|
||||||
|
- `clover_list_modifier_groups` - List all modifier groups
|
||||||
|
- `clover_list_modifiers` - List modifiers in a group
|
||||||
|
- `clover_update_modifier` - Update a modifier
|
||||||
|
- `clover_update_modifier_group` - Update a modifier group
|
||||||
|
|
||||||
|
### Orders Tools (10)
|
||||||
|
|
||||||
|
- `clover_add_line_item` - Add a line item to an order
|
||||||
|
- `clover_add_order_discount` - Add a discount to an order
|
||||||
|
- `clover_create_order` - Create a new order
|
||||||
|
- `clover_delete_order` - Delete an order
|
||||||
|
- `clover_fire_order` - Fire an order to the kitchen
|
||||||
|
- `clover_get_order` - Get order details
|
||||||
|
- `clover_list_order_payments` - List payments for an order
|
||||||
|
- `clover_list_orders` - List all orders
|
||||||
|
- `clover_remove_line_item` - Remove a line item from an order
|
||||||
|
- `clover_update_order` - Update order details
|
||||||
|
|
||||||
|
### Payments Tools (4)
|
||||||
|
|
||||||
|
- `clover_create_refund` - Create a payment refund
|
||||||
|
- `clover_get_payment` - Get payment details
|
||||||
|
- `clover_list_payments` - List all payments
|
||||||
|
- `clover_list_refunds` - List all refunds
|
||||||
|
|
||||||
|
### Refunds Tools (5)
|
||||||
|
|
||||||
|
- `clover_create_refund` - Create a refund
|
||||||
|
- `clover_get_refund` - Get refund details
|
||||||
|
- `clover_list_order_refunds` - List refunds for an order
|
||||||
|
- `clover_list_payment_refunds` - List refunds for a payment
|
||||||
|
- `clover_list_refunds` - List all refunds
|
||||||
|
|
||||||
|
### Reports Tools (4)
|
||||||
|
|
||||||
|
- `clover_employee_performance` - Get employee performance report
|
||||||
|
- `clover_revenue_by_category` - Get revenue breakdown by category
|
||||||
|
- `clover_revenue_by_item` - Get revenue breakdown by item
|
||||||
|
- `clover_sales_summary` - Get overall sales summary
|
||||||
|
|
||||||
|
### Shifts Tools (8)
|
||||||
|
|
||||||
|
- `clover_clock_out` - Clock out of a shift
|
||||||
|
- `clover_create_shift` - Create a new shift
|
||||||
|
- `clover_delete_shift` - Delete a shift
|
||||||
|
- `clover_get_active_shifts` - Get all active shifts
|
||||||
|
- `clover_get_shift` - Get shift details
|
||||||
|
- `clover_list_employee_shifts` - List shifts for an employee
|
||||||
|
- `clover_list_shifts` - List all shifts
|
||||||
|
- `clover_update_shift` - Update shift details
|
||||||
|
|
||||||
|
### Taxes Tools (5)
|
||||||
|
|
||||||
|
- `clover_create_tax_rate` - Create a new tax rate
|
||||||
|
- `clover_delete_tax_rate` - Delete a tax rate
|
||||||
|
- `clover_get_tax_rate` - Get tax rate details
|
||||||
|
- `clover_list_tax_rates` - List all tax rates
|
||||||
|
- `clover_update_tax_rate` - Update tax rate settings
|
||||||
|
|
||||||
|
### Tips Tools (5)
|
||||||
|
|
||||||
|
- `clover_add_cash_tip_to_shift` - Add cash tip to a shift
|
||||||
|
- `clover_get_employee_tips` - Get tips for an employee
|
||||||
|
- `clover_get_payment_tip` - Get tip for a payment
|
||||||
|
- `clover_get_shift_tips` - Get all tips for a shift
|
||||||
|
- `clover_update_payment_tip` - Update a payment tip
|
||||||
|
|
||||||
|
## React Applications (18 Total)
|
||||||
|
|
||||||
|
All React apps are available as MCP resources at `clover://app/<app-name>`.
|
||||||
|
|
||||||
|
### Inventory & Catalog Management
|
||||||
|
|
||||||
|
1. **inventory-dashboard** (141 lines)
|
||||||
|
- Overview of all inventory items with stock levels
|
||||||
|
- Quick search and filtering
|
||||||
|
- Low stock alerts and indicators
|
||||||
|
|
||||||
|
2. **inventory-detail** (131 lines)
|
||||||
|
- Detailed view for individual items
|
||||||
|
- Price, cost, and margin tracking
|
||||||
|
- Modifier and category associations
|
||||||
|
|
||||||
|
3. **category-manager** (88 lines)
|
||||||
|
- Create and organize item categories
|
||||||
|
- Drag-and-drop category management
|
||||||
|
- Item assignment to categories
|
||||||
|
|
||||||
|
### Customer Management
|
||||||
|
|
||||||
|
4. **customer-grid** (148 lines)
|
||||||
|
- Browse all customers in a data grid
|
||||||
|
- Search by name, email, or phone
|
||||||
|
- Quick access to customer details
|
||||||
|
|
||||||
|
5. **customer-detail** (153 lines)
|
||||||
|
- Complete customer profile view
|
||||||
|
- Purchase history and lifetime value
|
||||||
|
- Contact information and addresses
|
||||||
|
- Saved payment methods
|
||||||
|
|
||||||
|
### Order Management
|
||||||
|
|
||||||
|
6. **order-dashboard** (159 lines)
|
||||||
|
- Real-time order monitoring
|
||||||
|
- Order status tracking (pending, paid, refunded)
|
||||||
|
- Quick filters for today, week, month
|
||||||
|
|
||||||
|
7. **order-detail** (181 lines)
|
||||||
|
- Detailed order breakdown
|
||||||
|
- Line items with modifiers
|
||||||
|
- Payment and refund history
|
||||||
|
- Customer information
|
||||||
|
|
||||||
|
8. **order-grid** (150 lines)
|
||||||
|
- Searchable order history
|
||||||
|
- Multi-column sorting and filtering
|
||||||
|
- Export capabilities
|
||||||
|
|
||||||
|
### Employee Management
|
||||||
|
|
||||||
|
9. **employee-dashboard** (184 lines)
|
||||||
|
- Employee roster and roles
|
||||||
|
- Clock-in/out status
|
||||||
|
- Permission management
|
||||||
|
- Performance metrics
|
||||||
|
|
||||||
|
10. **employee-schedule** (100 lines)
|
||||||
|
- Shift scheduling interface
|
||||||
|
- Weekly/monthly calendar view
|
||||||
|
- Conflict detection
|
||||||
|
- Time-off requests
|
||||||
|
|
||||||
|
### Financial & Reporting
|
||||||
|
|
||||||
|
11. **sales-dashboard** (120 lines)
|
||||||
|
- Overall sales performance
|
||||||
|
- Revenue trends and charts
|
||||||
|
- Top items and categories
|
||||||
|
- Payment method breakdown
|
||||||
|
|
||||||
|
12. **revenue-by-category** (105 lines)
|
||||||
|
- Category-level revenue analysis
|
||||||
|
- Pie charts and trend graphs
|
||||||
|
- Comparison periods
|
||||||
|
|
||||||
|
13. **revenue-by-item** (96 lines)
|
||||||
|
- Item-level revenue tracking
|
||||||
|
- Best and worst performers
|
||||||
|
- Margin analysis
|
||||||
|
|
||||||
|
14. **payment-history** (102 lines)
|
||||||
|
- Complete payment transaction log
|
||||||
|
- Filter by date, amount, type
|
||||||
|
- Refund tracking
|
||||||
|
|
||||||
|
### Discounts & Pricing
|
||||||
|
|
||||||
|
15. **discount-manager** (120 lines)
|
||||||
|
- Create and edit discounts
|
||||||
|
- Percentage or fixed amount
|
||||||
|
- Auto-apply rules
|
||||||
|
- Active/inactive status
|
||||||
|
|
||||||
|
16. **tax-manager** (108 lines)
|
||||||
|
- Configure tax rates
|
||||||
|
- Apply to categories or items
|
||||||
|
- Default tax settings
|
||||||
|
|
||||||
|
### Device & Operations
|
||||||
|
|
||||||
|
17. **device-manager** (64 lines)
|
||||||
|
- List all Clover devices
|
||||||
|
- Device status and health
|
||||||
|
- Remote cash drawer control
|
||||||
|
- Print test receipts
|
||||||
|
|
||||||
|
18. **cash-drawer** (116 lines)
|
||||||
|
- Cash drawer event log
|
||||||
|
- Opening/closing counts
|
||||||
|
- Deposit tracking
|
||||||
|
- Cash management reports
|
||||||
|
|
||||||
|
## API Coverage
|
||||||
|
|
||||||
|
This server covers the following Clover API endpoints:
|
||||||
|
|
||||||
|
- **Orders API** - Full CRUD, line items, discounts, payments
|
||||||
|
- **Inventory API** - Items, categories, modifiers, stock management
|
||||||
|
- **Customers API** - Profiles, addresses, cards, search
|
||||||
|
- **Employees API** - Management, roles, shifts, time tracking
|
||||||
|
- **Payments API** - Transactions, refunds, tips
|
||||||
|
- **Merchants API** - Settings, devices, tender types
|
||||||
|
- **Reports API** - Sales, revenue, performance analytics
|
||||||
|
- **Devices API** - Hardware control, printing, cash drawer
|
||||||
|
|
||||||
## Architecture
|
## Architecture
|
||||||
|
|
||||||
```
|
```
|
||||||
src/
|
clover/
|
||||||
├── clients/
|
├── src/
|
||||||
│ └── clover.ts # API client with auth & pagination
|
│ ├── clients/
|
||||||
├── tools/
|
│ │ └── clover.ts # Clover API client with auth and pagination
|
||||||
│ ├── orders-tools.ts
|
│ ├── tools/ # 18 tool modules (118 tools total)
|
||||||
│ ├── inventory-tools.ts
|
│ │ ├── apps-tools.ts
|
||||||
│ ├── customers-tools.ts
|
│ │ ├── cash-tools.ts
|
||||||
│ ├── employees-tools.ts
|
│ │ ├── categories-tools.ts
|
||||||
│ ├── payments-tools.ts
|
│ │ ├── customers-tools.ts
|
||||||
│ ├── refunds-tools.ts
|
│ │ ├── devices-tools.ts
|
||||||
│ ├── line-items-tools.ts
|
│ │ ├── discounts-tools.ts
|
||||||
│ ├── categories-tools.ts
|
│ │ ├── employees-tools.ts
|
||||||
│ ├── modifiers-tools.ts
|
│ │ ├── inventory-tools.ts
|
||||||
│ ├── discounts-tools.ts
|
│ │ ├── line-items-tools.ts
|
||||||
│ ├── taxes-tools.ts
|
│ │ ├── merchants-tools.ts
|
||||||
│ ├── tips-tools.ts
|
│ │ ├── modifiers-tools.ts
|
||||||
│ ├── shifts-tools.ts
|
│ │ ├── orders-tools.ts
|
||||||
│ ├── cash-tools.ts
|
│ │ ├── payments-tools.ts
|
||||||
│ ├── devices-tools.ts
|
│ │ ├── refunds-tools.ts
|
||||||
│ ├── apps-tools.ts
|
│ │ ├── reports-tools.ts
|
||||||
│ ├── reports-tools.ts
|
│ │ ├── shifts-tools.ts
|
||||||
│ └── merchants-tools.ts
|
│ │ ├── taxes-tools.ts
|
||||||
├── types/
|
│ │ └── tips-tools.ts
|
||||||
│ └── index.ts # TypeScript type definitions
|
│ ├── ui/
|
||||||
├── ui/
|
│ │ └── react-app/ # 18 React applications
|
||||||
│ └── react-app/
|
│ │ ├── cash-drawer.tsx
|
||||||
│ └── src/
|
│ │ ├── category-manager.tsx
|
||||||
│ └── apps/ # 15 React applications
|
│ │ ├── customer-detail.tsx
|
||||||
├── server.ts # MCP server implementation
|
│ │ ├── customer-grid.tsx
|
||||||
└── main.ts # Entry point
|
│ │ ├── device-manager.tsx
|
||||||
|
│ │ ├── discount-manager.tsx
|
||||||
|
│ │ ├── employee-dashboard.tsx
|
||||||
|
│ │ ├── employee-schedule.tsx
|
||||||
|
│ │ ├── inventory-dashboard.tsx
|
||||||
|
│ │ ├── inventory-detail.tsx
|
||||||
|
│ │ ├── order-dashboard.tsx
|
||||||
|
│ │ ├── order-detail.tsx
|
||||||
|
│ │ ├── order-grid.tsx
|
||||||
|
│ │ ├── payment-history.tsx
|
||||||
|
│ │ ├── revenue-by-category.tsx
|
||||||
|
│ │ ├── revenue-by-item.tsx
|
||||||
|
│ │ ├── sales-dashboard.tsx
|
||||||
|
│ │ └── tax-manager.tsx
|
||||||
|
│ ├── types/
|
||||||
|
│ │ └── index.ts # TypeScript type definitions
|
||||||
|
│ ├── server.ts # MCP server implementation
|
||||||
|
│ └── main.ts # CLI entry point
|
||||||
|
├── scripts/
|
||||||
|
│ └── copy-assets.js # Build script for React apps
|
||||||
|
├── package.json
|
||||||
|
├── tsconfig.json
|
||||||
|
└── README.md
|
||||||
```
|
```
|
||||||
|
|
||||||
## TypeScript Configuration
|
|
||||||
|
|
||||||
- **Target**: ES2022
|
|
||||||
- **Module**: Node16 with ESM
|
|
||||||
- **Strict Mode**: Enabled
|
|
||||||
- **JSX**: react-jsx for React apps
|
|
||||||
- **Libraries**: ES2022 + DOM
|
|
||||||
|
|
||||||
## Development
|
## Development
|
||||||
|
|
||||||
### Build
|
### Build
|
||||||
@ -294,56 +458,101 @@ src/
|
|||||||
npm run build
|
npm run build
|
||||||
```
|
```
|
||||||
|
|
||||||
### Type Check
|
Compiles TypeScript and copies React app assets to `dist/`.
|
||||||
|
|
||||||
|
### Watch Mode
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run dev
|
||||||
|
```
|
||||||
|
|
||||||
|
Runs TypeScript compiler in watch mode for development.
|
||||||
|
|
||||||
|
### Type Checking
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
npx tsc --noEmit
|
npx tsc --noEmit
|
||||||
```
|
```
|
||||||
|
|
||||||
### Running React Apps
|
Verifies all TypeScript code compiles without errors.
|
||||||
|
|
||||||
Each React app can be run independently:
|
## Error Handling
|
||||||
|
|
||||||
```bash
|
The server includes comprehensive error handling:
|
||||||
cd src/ui/react-app/src/apps/order-dashboard
|
|
||||||
npm install
|
- **Authentication Errors** - Clear messages for missing or invalid credentials
|
||||||
npm run dev
|
- **API Errors** - Clover API errors are propagated with full context
|
||||||
```
|
- **Validation Errors** - Input validation before API calls
|
||||||
|
- **Network Errors** - Retry logic and timeout handling
|
||||||
|
|
||||||
|
All errors are returned in the MCP error format with descriptive messages.
|
||||||
|
|
||||||
|
## Security
|
||||||
|
|
||||||
|
- API keys and tokens are read from environment variables only
|
||||||
|
- No credentials are logged or exposed in responses
|
||||||
|
- TLS/HTTPS for all Clover API communication
|
||||||
|
- Follows Clover's OAuth best practices
|
||||||
|
|
||||||
## Testing
|
## Testing
|
||||||
|
|
||||||
Test tools via MCP client or programmatically:
|
Use Clover's sandbox environment for testing:
|
||||||
|
|
||||||
```typescript
|
```bash
|
||||||
import { CloverClient } from './clients/clover.js';
|
export CLOVER_ENVIRONMENT="sandbox"
|
||||||
|
export CLOVER_MERCHANT_ID="<sandbox-merchant-id>"
|
||||||
const client = new CloverClient({
|
export CLOVER_API_KEY="<sandbox-api-key>"
|
||||||
accessToken: 'your_token',
|
|
||||||
merchantId: 'your_merchant_id',
|
|
||||||
environment: 'sandbox'
|
|
||||||
});
|
|
||||||
|
|
||||||
// List orders
|
|
||||||
const orders = await client.fetchPaginated('/orders', {}, 100);
|
|
||||||
console.log(orders);
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## API Documentation
|
The sandbox environment provides:
|
||||||
|
- Isolated test data
|
||||||
|
- Safe testing of all operations
|
||||||
|
- No impact on production data
|
||||||
|
- Realistic API responses
|
||||||
|
|
||||||
Full Clover API documentation: https://docs.clover.com/reference
|
## Limitations
|
||||||
|
|
||||||
|
- Requires Clover merchant account with API access
|
||||||
|
- Rate limits apply based on Clover API tier
|
||||||
|
- Some operations require specific permissions
|
||||||
|
- Webhook subscriptions not currently supported
|
||||||
|
|
||||||
|
## Contributing
|
||||||
|
|
||||||
|
Contributions are welcome! Please:
|
||||||
|
|
||||||
|
1. Follow the existing code structure
|
||||||
|
2. Add tests for new tools
|
||||||
|
3. Update this README with new features
|
||||||
|
4. Ensure TypeScript compiles without errors
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
MIT
|
MIT
|
||||||
|
|
||||||
## Author
|
## Support
|
||||||
|
|
||||||
MCPEngine - Complete MCP Server Solutions
|
For issues or questions:
|
||||||
|
- GitHub Issues: [Report a bug](https://github.com/your-org/mcpengine/issues)
|
||||||
|
- Clover Documentation: https://docs.clover.com/
|
||||||
|
- MCP Specification: https://modelcontextprotocol.io/
|
||||||
|
|
||||||
## Version
|
## Related Projects
|
||||||
|
|
||||||
1.0.0
|
- **MCPEngine** - Framework for building MCP servers
|
||||||
|
- **Clover SDK** - Official Clover developer tools
|
||||||
|
- **MCP Clients** - Claude Desktop, Continue, and others
|
||||||
|
|
||||||
|
## Version History
|
||||||
|
|
||||||
|
### 1.0.0 (Current)
|
||||||
|
- Initial release
|
||||||
|
- 118 MCP tools across 18 categories
|
||||||
|
- 18 React applications
|
||||||
|
- Full TypeScript support
|
||||||
|
- Sandbox and production environments
|
||||||
|
- Comprehensive error handling
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
**50+ Tools | 15 React Apps | Production Ready**
|
**Built with ❤️ for the MCP and Clover communities**
|
||||||
|
|||||||
File diff suppressed because it is too large
Load Diff
@ -10,7 +10,8 @@
|
|||||||
"scripts": {
|
"scripts": {
|
||||||
"build": "tsc && chmod +x dist/index.js",
|
"build": "tsc && chmod +x dist/index.js",
|
||||||
"dev": "tsc --watch",
|
"dev": "tsc --watch",
|
||||||
"prepare": "npm run build"
|
"prepare": "npm run build",
|
||||||
|
"prepublishOnly": "npm run build"
|
||||||
},
|
},
|
||||||
"keywords": ["mcp", "jobber", "field-service", "graphql"],
|
"keywords": ["mcp", "jobber", "field-service", "graphql"],
|
||||||
"author": "MCPEngine",
|
"author": "MCPEngine",
|
||||||
|
|||||||
Loading…
x
Reference in New Issue
Block a user