jake/mcpengine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
mcpengine/servers/clover/README.md

17 KiB
Raw Blame History

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

npm install @mcpengine/clover-server

Or install from source:

git clone <repo-url>
cd servers/clover
npm install
npm run build

Configuration

Set the following environment variables:

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

{
  "mcpServers": {
    "clover": {
      "command": "clover-mcp",
      "env": {
        "CLOVER_MERCHANT_ID": "your-merchant-id",
        "CLOVER_API_KEY": "your-api-key",
        "CLOVER_ENVIRONMENT": "sandbox"
      }
    }
  }
}

Programmatic Usage

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

  1. customer-grid (148 lines)

    • Browse all customers in a data grid
    • Search by name, email, or phone
    • Quick access to customer details

  2. customer-detail (153 lines)

    • Complete customer profile view
    • Purchase history and lifetime value
    • Contact information and addresses
    • Saved payment methods

Order Management

  1. order-dashboard (159 lines)

    • Real-time order monitoring
    • Order status tracking (pending, paid, refunded)
    • Quick filters for today, week, month

  2. order-detail (181 lines)

    • Detailed order breakdown
    • Line items with modifiers
    • Payment and refund history
    • Customer information

  3. order-grid (150 lines)

    • Searchable order history
    • Multi-column sorting and filtering
    • Export capabilities

Employee Management

  1. employee-dashboard (184 lines)

    • Employee roster and roles
    • Clock-in/out status
    • Permission management
    • Performance metrics

  2. employee-schedule (100 lines)

    • Shift scheduling interface
    • Weekly/monthly calendar view
    • Conflict detection
    • Time-off requests

Financial & Reporting

  1. sales-dashboard (120 lines)

    • Overall sales performance
    • Revenue trends and charts
    • Top items and categories
    • Payment method breakdown

  2. revenue-by-category (105 lines)

    • Category-level revenue analysis
    • Pie charts and trend graphs
    • Comparison periods

  3. revenue-by-item (96 lines)

    • Item-level revenue tracking
    • Best and worst performers
    • Margin analysis

  4. payment-history (102 lines)

    • Complete payment transaction log
    • Filter by date, amount, type
    • Refund tracking

Discounts & Pricing

  1. discount-manager (120 lines)

    • Create and edit discounts
    • Percentage or fixed amount
    • Auto-apply rules
    • Active/inactive status

  2. tax-manager (108 lines)

    • Configure tax rates
    • Apply to categories or items
    • Default tax settings

Device & Operations

  1. device-manager (64 lines)

    • List all Clover devices
    • Device status and health
    • Remote cash drawer control
    • Print test receipts

  2. 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

npm run build

Compiles TypeScript and copies React app assets to dist/.

Watch Mode

npm run dev

Runs TypeScript compiler in watch mode for development.

Type Checking

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:

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:

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