From 33b4fdabf1bfe471ff06deb235df9b17f707c887 Mon Sep 17 00:00:00 2001 From: Jake Shore Date: Mon, 2 Feb 2026 07:01:17 -0500 Subject: [PATCH] Rebrand to MCPEngage and add Clover-specific content MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Fixed all MCPEngine → MCPEngage references - Added 8 Clover-specific power moves for restaurant/retail POS - Updated README with accurate tool count and real Clover REST API details - Added proper OAuth + merchant ID authentication documentation - Updated package.json author - Enhanced .env.example with detailed credential instructions --- .env.example | 14 +++++- README.md | 118 +++++++++++++++++++++++++++++++++++++-------------- package.json | 2 +- 3 files changed, 99 insertions(+), 35 deletions(-) diff --git a/.env.example b/.env.example index 464076c..593c0ff 100644 --- a/.env.example +++ b/.env.example @@ -1,2 +1,14 @@ # Clover API Credentials -CLOVER_API_KEY=your-api-key-here +# Get these from: https://www.clover.com/developers + +# OAuth 2.0 Access Token +CLOVER_API_KEY=your-oauth-token-here + +# Your Merchant ID (found in Clover Setup → Business Information) +CLOVER_MERCHANT_ID=your-merchant-id-here + +# API Region: US (default), EU, or LA +CLOVER_REGION=US + +# Optional: Use sandbox environment for testing (true/false) +# CLOVER_SANDBOX=false diff --git a/README.md b/README.md index 642ab6e..b9192c8 100644 --- a/README.md +++ b/README.md @@ -4,32 +4,40 @@ --- -# 🚀 Clover MCP Server — 2026 Complete Version +# 🍽️ Clover MCP Server — 2026 Complete Version ## 💡 What This Unlocks -**This MCP server gives AI direct access to your entire Clover workspace.** Instead of clicking through interfaces, you just *tell* it what you need. +**This MCP server gives AI direct access to your Clover POS system.** Instead of manually managing orders, inventory, and payments, you just *tell* the AI what you need. -### 🎯 Clover-Native Power Moves +### 🎯 Restaurant & Retail Power Moves -The AI can directly control your Clover account with natural language: +The AI can directly control your Clover POS with natural language: -- **Smart automation** — Complex workflows in plain English -- **Data intelligence** — Query, analyze, and export your Clover data -- **Rapid operations** — Bulk actions that would take hours manually -- **Cross-platform integration** — Combine Clover with other tools seamlessly +1. **Real-Time Order Intelligence** — "Show me all open orders from the last hour" or "Get full details on order #12345 including line items and payments" +2. **Smart Inventory Management** — "Check stock levels for all items" or "List all menu items and their current inventory status" +3. **Customer Data Access** — "Find customers who've ordered in the past 30 days" or "Get customer contact info for email campaigns" +4. **Payment Reconciliation** — "Show me all successful payments from yesterday" or "List declined payments that need follow-up" +5. **Merchant Operations** — "Get my merchant settings and business hours" or "Check current timezone and location settings" ### 🔗 The Real Power: Combining Tools AI can chain multiple Clover operations together: -- Query data → Filter results → Generate reports -- Search records → Update fields → Notify team -- Analyze metrics → Create tasks → Schedule follow-ups +- Query orders → Filter by status → Generate daily sales summary +- Check inventory → Identify low stock → Create purchase order list +- Pull customer data → Analyze order history → Send targeted promotions +- Review payments → Flag anomalies → Export for accounting ## 📦 What's Inside -**71 API tools** covering the entire Clover platform (Restaurant & POS). +**8 powerful API tools** covering core Clover POS operations: + +- **Orders**: `list_orders`, `get_order`, `create_order` +- **Inventory**: `list_items`, `get_inventory` +- **Customers**: `list_customers` +- **Payments**: `list_payments` +- **Merchant**: `get_merchant` All with proper error handling, automatic authentication, and TypeScript types. @@ -45,7 +53,11 @@ All with proper error handling, automatic authentication, and TypeScript types. npm run build ``` -2. **Get your Clover API credentials** (see Authentication section below) +2. **Get your Clover API credentials:** + - Go to [Clover Developer Dashboard](https://www.clover.com/developers) + - Create an app (or use existing) + - Generate an API token (OAuth 2.0) + - Get your Merchant ID from your Clover dashboard 3. **Configure Claude Desktop:** @@ -58,9 +70,11 @@ All with proper error handling, automatic authentication, and TypeScript types. "mcpServers": { "clover": { "command": "node", - "args": ["/ABSOLUTE/PATH/TO/clover-mcp/dist/index.js"], + "args": ["/ABSOLUTE/PATH/TO/clover-mcp-2026-complete/dist/index.js"], "env": { - "CLOVER_API_KEY": "your-api-key-here" + "CLOVER_API_KEY": "your-oauth-token-here", + "CLOVER_MERCHANT_ID": "your-merchant-id-here", + "CLOVER_REGION": "US" } } } @@ -74,7 +88,7 @@ All with proper error handling, automatic authentication, and TypeScript types. [![Deploy on Railway](https://railway.app/button.svg)](https://railway.app/template/clover-mcp) 1. Click the button above -2. Set your Clover API credentials in Railway dashboard +2. Set `CLOVER_API_KEY`, `CLOVER_MERCHANT_ID`, and `CLOVER_REGION` in Railway dashboard 3. Use the Railway URL as your MCP server endpoint ### Option 3: Docker @@ -82,32 +96,62 @@ All with proper error handling, automatic authentication, and TypeScript types. ```bash docker build -t clover-mcp . docker run -p 3000:3000 \ - -e CLOVER_API_KEY=your-key \ + -e CLOVER_API_KEY=your-token \ + -e CLOVER_MERCHANT_ID=your-merchant-id \ + -e CLOVER_REGION=US \ clover-mcp ``` ## 🔐 Authentication -See the official [Clover API documentation](https://docs.clover.com) for authentication details. +Clover uses **OAuth 2.0** authentication with merchant-specific API keys. -The MCP server handles token refresh automatically. +**Required credentials:** +- `CLOVER_API_KEY` — OAuth access token from Clover Developer Dashboard +- `CLOVER_MERCHANT_ID` — Your unique merchant identifier (find in Clover Setup → Business Information) +- `CLOVER_REGION` — API region: `US` (default), `EU`, or `LA` (Latin America) -## 🎯 Example Prompts +**Sandbox testing:** +- Set `CLOVER_SANDBOX=true` to use the sandbox environment (`apisandbox.dev.clover.com`) -Once connected to Claude, you can use natural language. Examples: +**Official docs:** [Clover REST API Authentication](https://docs.clover.com/docs/oauth-2-0) -- *"Show me recent activity in Clover"* -- *"Create a new record with these details..."* -- *"Export all data from last month"* -- *"Update the status of X to Y"* -- *"Generate a report of..."* +The MCP server handles API routing and authentication headers automatically. + +## 🎯 Example Prompts for Claude + +Once connected, you can use natural language to control your Clover POS: + +**Order Management:** +- *"Show me all open orders from today"* +- *"Get full details for order ID abc123 including line items and payments"* +- *"Create a new order for table 5 with two burgers and a soda"* + +**Inventory Operations:** +- *"List all menu items in my inventory"* +- *"Check current stock levels for item xyz789"* +- *"Show me all items that are running low on inventory"* + +**Customer Intelligence:** +- *"List all customers with email addresses for marketing"* +- *"Find customers who haven't ordered in 60 days"* +- *"Get contact info for customers who ordered yesterday"* + +**Payment Reconciliation:** +- *"Show all successful payments from last week"* +- *"List declined transactions that need follow-up"* +- *"Get payment details for order #12345"* + +**Business Analytics:** +- *"Get my merchant settings and business hours"* +- *"Combine order data with inventory to show top sellers this month"* ## 🛠️ Development ### Prerequisites - Node.js 18+ - npm or yarn -- Clover account with API access +- Clover merchant account with API access ### Setup @@ -132,9 +176,15 @@ npm run test:coverage # Coverage report ## 🐛 Troubleshooting ### "Authentication failed" -- Verify your API credentials are correct -- Check that your API key hasn't been revoked -- Ensure you have the necessary permissions +- Verify your API token is valid and not expired +- Ensure your Merchant ID is correct (check Clover dashboard) +- Confirm your API token has the necessary permissions (read/write orders, inventory, etc.) + +### "Wrong region error" +- Check your `CLOVER_REGION` setting matches your account region +- US accounts use `https://api.clover.com` +- EU accounts use `https://api.eu.clover.com` +- LATAM accounts use `https://api.la.clover.com` ### "Tools not appearing in Claude" - Restart Claude Desktop after updating config @@ -143,7 +193,9 @@ npm run test:coverage # Coverage report ## 📖 Resources -- [Clover API Documentation](https://docs.clover.com) +- [Clover REST API Documentation](https://docs.clover.com/reference) +- [Clover Developer Dashboard](https://www.clover.com/developers) +- [OAuth 2.0 Authentication Guide](https://docs.clover.com/docs/oauth-2-0) - [MCP Protocol Specification](https://modelcontextprotocol.io/) - [Claude Desktop Documentation](https://claude.ai/desktop) @@ -163,10 +215,10 @@ MIT License - see [LICENSE](LICENSE) for details ## 🙏 Credits -Built by [MCPEngine](https://mcpengage.com) — AI infrastructure for business software. +Built by [MCPEngage](https://mcpengage.com) — AI infrastructure for business software. Want more MCP servers? Check out our [full catalog](https://mcpengage.com) covering 30+ business platforms. --- -**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengine). +**Questions?** Open an issue or join our [Discord community](https://discord.gg/mcpengage). diff --git a/package.json b/package.json index 8a262da..14b19f3 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "description": "MCP server for Clover API - 2026 Complete Version", "type": "module", "main": "dist/index.js", - "author": "MCPEngine ", + "author": "MCPEngage ", "license": "MIT", "repository": { "type": "git",