mcpengine/servers/clover/README.md

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

## Features

### 🛠️ 50+ MCP Tools

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

#### Inventory Management
- **inventory-dashboard** - Inventory metrics and quick actions
- **inventory-detail** - Item management with search
- **category-manager** - Category organization

#### Customer Management
- **customer-detail** - Detailed customer profile
- **customer-grid** - Customer directory with search

#### Employee Management
- **employee-dashboard** - Employee metrics and performance
- **employee-schedule** - Shift management and time tracking

#### Payments
- **payment-history** - Payment transactions and refunds

#### Reports & Analytics
- **sales-dashboard** - Sales metrics and trends
- **revenue-by-item** - Top performing items
- **revenue-by-category** - Category performance

#### Configuration
- **discount-manager** - Discount creation and management
- **tax-manager** - Tax rate configuration
- **device-manager** - POS device inventory

#### Cash Management
- **cash-drawer** - Cash drawer tracking and events

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

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

## API Reference

### Tool Usage Examples

#### List Orders
```typescript
// List all open orders
await mcp.callTool('clover_list_orders', {
  filter: 'state=open',
  expand: 'lineItems,customers'
});
```

#### Create Order with Items
```typescript
// Create order
const order = await mcp.callTool('clover_create_order', {
  state: 'open',
  title: 'Table 5'
});

// Add items
await mcp.callTool('clover_add_line_item', {
  orderId: order.id,
  itemId: 'ITEM_ID',
  unitQty: 2
});
```

#### 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()
});
```

### React App Resources

Apps are available as MCP resources:

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

## Architecture

```
src/
├── clients/
│   └── clover.ts          # Clover API client with 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
├── types/
│   └── index.ts           # TypeScript type definitions
├── server.ts              # MCP server implementation
└── main.ts                # Entry point
```

## Development

### Build
```bash
npm run build
```

### Watch Mode
```bash
npm run dev
```

## API Coverage

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

## License

MIT

## Contributing

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

## Support

For issues related to:
- **This MCP server**: Open a GitHub issue
- **Clover API**: Check https://docs.clover.com/
- **MCP Protocol**: See https://modelcontextprotocol.io/

---

Built with ❤️ for the MCPEngine ecosystem