mcpengine/servers/clover/README.md

# Clover POS 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.

## Features

### 🛠️ Tools (50+)

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

#### 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

```bash
npm install
```

## Configuration

Set environment variables or configure via MCP client:

```json
{
  "mcpServers": {
    "clover": {
      "command": "node",
      "args": ["/path/to/clover/dist/main.js"],
      "env": {
        "CLOVER_API_KEY": "your_api_key",
        "CLOVER_ACCESS_TOKEN": "your_access_token",
        "CLOVER_MERCHANT_ID": "your_merchant_id",
        "CLOVER_ENVIRONMENT": "sandbox"
      }
    }
  }
}
```

### Configuration Options

- `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)

## 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"
      }
    }
  }
}
```

### Direct Usage

```bash
npm run build
npm start
```

### Development

```bash
npm run dev
```

## API Client

The `CloverClient` class provides:

- **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          # API client with auth & pagination
├── tools/
│   ├── 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
```

### 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
```

## Testing

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

## Author

MCPEngine - Complete MCP Server Solutions

## Version

1.0.0

---

**50+ Tools | 15 React Apps | Production Ready**