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

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

npm install

Configuration

Set environment variables or configure via MCP client:

{
  "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:

{
  "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

npm run build
npm start

Development

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

npm run build

Type Check

npx tsc --noEmit

Running React Apps

Each React app can be run independently:

cd src/ui/react-app/src/apps/order-dashboard
npm install
npm run dev

Testing

Test tools via MCP client or programmatically:

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