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

559 lines
17 KiB
Markdown
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
```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**
Reference in New Issue View Git Blame Copy Permalink