# Clover MCP Server

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

- **118 MCP Tools** across 18 functional categories
- **18 React Applications** for visual management and reporting
- **Full CRUD Operations** for all major Clover entities
- **Real-time Data** via Clover REST API v3
- **Environment Support** for both sandbox and production
- **TypeScript** for type safety and developer experience
- **MCP Resources** for serving interactive React apps

## Installation

```bash
npm install @mcpengine/clover-server
```

Or install from source:

```bash
git clone <repo-url>
cd servers/clover
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 (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
{
  "mcpServers": {
    "clover": {
      "command": "clover-mcp",
      "env": {
        "CLOVER_MERCHANT_ID": "your-merchant-id",
        "CLOVER_API_KEY": "your-api-key",
        "CLOVER_ENVIRONMENT": "sandbox"
      }
    }
  }
}
```

### Programmatic Usage

```typescript
import { CloverServer } from '@mcpengine/clover-server';

const server = new CloverServer({
  merchantId: 'your-merchant-id',
  apiKey: 'your-api-key',
  environment: 'sandbox'
});

await server.run();
```

## MCP Tools (118 Total)

### Apps Tools (4)

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

### Cash Tools (2)

- `clover_get_cash_drawer` - Get cash drawer status and details
- `clover_list_cash_events` - List cash drawer events (opens, deposits, etc.)

### Categories Tools (8)

- `clover_add_item_to_category` - Add an item to a category
- `clover_create_category` - Create a new category
- `clover_delete_category` - Delete a category
- `clover_get_category` - Get category details
- `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

```
clover/
├── src/
│   ├── clients/
│   │   └── clover.ts           # Clover API client with auth and pagination
│   ├── tools/                  # 18 tool modules (118 tools total)
│   │   ├── apps-tools.ts
│   │   ├── cash-tools.ts
│   │   ├── categories-tools.ts
│   │   ├── customers-tools.ts
│   │   ├── devices-tools.ts
│   │   ├── discounts-tools.ts
│   │   ├── employees-tools.ts
│   │   ├── inventory-tools.ts
│   │   ├── line-items-tools.ts
│   │   ├── merchants-tools.ts
│   │   ├── modifiers-tools.ts
│   │   ├── orders-tools.ts
│   │   ├── payments-tools.ts
│   │   ├── refunds-tools.ts
│   │   ├── reports-tools.ts
│   │   ├── shifts-tools.ts
│   │   ├── taxes-tools.ts
│   │   └── tips-tools.ts
│   ├── ui/
│   │   └── react-app/          # 18 React applications
│   │       ├── cash-drawer.tsx
│   │       ├── category-manager.tsx
│   │       ├── customer-detail.tsx
│   │       ├── customer-grid.tsx
│   │       ├── 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
```

## Development

### Build

```bash
npm run build
```

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
npx tsc --noEmit
```

Verifies all TypeScript code compiles without errors.

## Error Handling

The server includes comprehensive error handling:

- **Authentication Errors** - Clear messages for missing or invalid credentials
- **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

Use Clover's sandbox environment for testing:

```bash
export CLOVER_ENVIRONMENT="sandbox"
export CLOVER_MERCHANT_ID="<sandbox-merchant-id>"
export CLOVER_API_KEY="<sandbox-api-key>"
```

The sandbox environment provides:
- Isolated test data
- Safe testing of all operations
- No impact on production data
- Realistic API responses

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

MIT

## Support

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/

## Related Projects

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

---

**Built with ❤️ for the MCP and Clover communities**