From 37c9aa1ae06eadc917695cb7ab7466180f49cbc9 Mon Sep 17 00:00:00 2001 From: Jake Shore Date: Mon, 2 Feb 2026 06:58:51 -0500 Subject: [PATCH] Rebrand to MCPEngage and customize Lightspeed README with retail POS power moves --- .env.example | 6 ++- README.md | 130 +++++++++++++++++++++++++++++++++++++++------------ package.json | 2 +- 3 files changed, 104 insertions(+), 34 deletions(-) diff --git a/.env.example b/.env.example index 252d04b..8ce3a38 100644 --- a/.env.example +++ b/.env.example @@ -1,2 +1,4 @@ -# Lightspeed API Credentials -LIGHTSPEED_API_KEY=your-api-key-here +# Lightspeed Retail API Credentials +# Get these from: Account Settings → API Settings → Generate Token +LIGHTSPEED_ACCESS_TOKEN=your-access-token-here +LIGHTSPEED_ACCOUNT_ID=your-account-id diff --git a/README.md b/README.md index b44b6ea..cbd7b97 100644 --- a/README.md +++ b/README.md @@ -8,28 +8,38 @@ ## 💡 What This Unlocks -**This MCP server gives AI direct access to your entire Lightspeed workspace.** Instead of clicking through interfaces, you just *tell* it what you need. +**This MCP server gives AI direct access to your Lightspeed Retail POS system.** Instead of manually managing sales, inventory, and customer data through the POS interface, you just *tell* the AI what you need — in plain English. -### 🎯 Lightspeed-Native Power Moves +### 🎯 Retail POS Power Moves -The AI can directly control your Lightspeed account with natural language: +The AI can directly control your Lightspeed Retail system with natural language: -- **Smart automation** — Complex workflows in plain English -- **Data intelligence** — Query, analyze, and export your Lightspeed data -- **Rapid operations** — Bulk actions that would take hours manually -- **Cross-platform integration** — Combine Lightspeed with other tools seamlessly +1. **Sales Analytics** — "Show me all sales from the last 24 hours broken down by employee and location" +2. **Inventory Tracking** — "List all items with stock below reorder point and generate a purchase order list" +3. **Product Management** — "Find all items in the 'Electronics' category and show their current stock levels" +4. **Customer Intelligence** — "Get all customers who made purchases over $500 in the last month" +5. **Register Operations** — "Show me register status for all locations and today's cash counts" ### 🔗 The Real Power: Combining Tools -AI can chain multiple Lightspeed operations together: +AI can chain multiple Lightspeed operations together in one conversation: -- Query data → Filter results → Generate reports -- Search records → Update fields → Notify team -- Analyze metrics → Create tasks → Schedule follow-ups +- Query sales data → Filter by employee → Generate performance report +- Check inventory levels → Identify low stock → Create reorder workflow +- Pull customer data → Match with purchase history → Generate loyalty insights +- Analyze category performance → Adjust pricing → Update inventory levels ## 📦 What's Inside -**86 API tools** covering the entire Lightspeed platform (Restaurant & POS). +**8 powerful API tools** covering Lightspeed Retail POS operations: +- `list_sales` — Browse completed transactions with filters +- `get_sale` — Get complete sale details with line items and payments +- `list_items` — Query inventory catalog with advanced filters +- `get_item` — Get full item details including pricing and stock +- `update_inventory` — Adjust stock levels for items at specific locations +- `list_customers` — Browse customer database +- `list_categories` — View product category hierarchy +- `get_register` — Get POS terminal information and status All with proper error handling, automatic authentication, and TypeScript types. @@ -45,7 +55,11 @@ All with proper error handling, automatic authentication, and TypeScript types. npm run build ``` -2. **Get your Lightspeed API credentials** (see Authentication section below) +2. **Get your Lightspeed API credentials:** + - Log in to Lightspeed Back Office + - Go to **Account Settings → API Settings → Generate Token** + - Complete OAuth authorization flow + - Copy your **Access Token** and **Account ID** 3. **Configure Claude Desktop:** @@ -58,9 +72,10 @@ All with proper error handling, automatic authentication, and TypeScript types. "mcpServers": { "lightspeed": { "command": "node", - "args": ["/ABSOLUTE/PATH/TO/lightspeed-mcp/dist/index.js"], + "args": ["/ABSOLUTE/PATH/TO/lightspeed-mcp-2026-complete/dist/index.js"], "env": { - "LIGHTSPEED_API_KEY": "your-api-key-here" + "LIGHTSPEED_ACCESS_TOKEN": "your-access-token-here", + "LIGHTSPEED_ACCOUNT_ID": "your-account-id" } } } @@ -82,32 +97,73 @@ All with proper error handling, automatic authentication, and TypeScript types. ```bash docker build -t lightspeed-mcp . docker run -p 3000:3000 \ - -e LIGHTSPEED_API_KEY=your-key \ + -e LIGHTSPEED_ACCESS_TOKEN=your-token \ + -e LIGHTSPEED_ACCOUNT_ID=your-account-id \ lightspeed-mcp ``` ## 🔐 Authentication -See the official [Lightspeed API documentation](https://docs.lightspeed.com) for authentication details. +**Lightspeed uses OAuth2 authentication with Access Tokens and Account IDs.** -The MCP server handles token refresh automatically. +**Setup Steps:** +1. In Lightspeed Back Office: **Account Settings → API Settings** +2. Click **Generate Token** or create an OAuth application +3. Complete the OAuth authorization flow +4. Save these credentials: + - **Access Token** — Your OAuth bearer token + - **Account ID** — Your Lightspeed account identifier (found in URL: `/Account/{ID}/`) + +**API Documentation:** https://developers.lightspeedhq.com/retail/introduction/authentication + +**Token Management:** +- Access tokens expire after 1 hour +- Use refresh tokens to obtain new access tokens +- This MCP server requires a valid access token + +The MCP server handles all API requests automatically using your credentials. ## 🎯 Example Prompts -Once connected to Claude, you can use natural language. Examples: +Once connected to Claude, you can use natural language for retail POS operations: -- *"Show me recent activity in Lightspeed"* -- *"Create a new record with these details..."* -- *"Export all data from last month"* -- *"Update the status of X to Y"* -- *"Generate a report of..."* +**Sales Tracking:** +- *"Show me all completed sales from today"* +- *"Get sales for employee ID 5 from the last week"* +- *"List sales over $100 from location 'Downtown Store'"* + +**Inventory Management:** +- *"Show me all items with quantity on hand below 10"* +- *"Update inventory for item shop ID 12345 to 50 units"* +- *"List all items in category 'Apparel' with their stock levels"* + +**Product Catalog:** +- *"Get all items with UPC barcode '012345678901'"* +- *"Show me items from manufacturer 'Apple' with inventory details"* +- *"List all items that need reordering based on reorder point"* + +**Customer Management:** +- *"Find all customers with last name 'Smith'"* +- *"Get customers who joined in the last 30 days"* +- *"List customers with email containing '@gmail.com'"* + +**Register Operations:** +- *"Show me all register terminals at location 'Main St Store'"* +- *"Get register status and cash count for register ID 3"* +- *"List all active registers across all locations"* + +**Analytics & Reporting:** +- *"Generate a sales report for the last 7 days grouped by category"* +- *"Show me top-selling items from this month"* +- *"Export all customer purchase data from Q4 2024"* ## 🛠️ Development ### Prerequisites - Node.js 18+ - npm or yarn -- Lightspeed account with API access +- Lightspeed Retail account with API access +- Valid OAuth access token and account ID ### Setup @@ -132,18 +188,30 @@ 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 **Access Token** is current (tokens expire after 1 hour) +- Check that your **Account ID** matches your Lightspeed account +- Regenerate your access token if needed ### "Tools not appearing in Claude" - Restart Claude Desktop after updating config -- Check that the path in `claude_desktop_config.json` is absolute +- Check that the path in `claude_desktop_config.json` is **absolute** (not relative) - Verify the build completed successfully (`dist/index.js` exists) +### "401 Unauthorized" errors +- Your access token has likely expired (1-hour lifetime) +- Use your refresh token to obtain a new access token +- Update your `.env` or Claude config with the new token + +### "Rate limit exceeded" +- Lightspeed has rate limits: 10 requests/second (burst), 600 requests/minute +- The server respects rate limits automatically +- Space out large batch operations + ## 📖 Resources -- [Lightspeed API Documentation](https://docs.lightspeed.com) +- [Lightspeed Retail API Documentation](https://developers.lightspeedhq.com/retail/) +- [Lightspeed API Reference](https://developers.lightspeedhq.com/retail/endpoints/) +- [OAuth Authentication Guide](https://developers.lightspeedhq.com/retail/introduction/authentication/) - [MCP Protocol Specification](https://modelcontextprotocol.io/) - [Claude Desktop Documentation](https://claude.ai/desktop) @@ -163,7 +231,7 @@ 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. diff --git a/package.json b/package.json index d1e4ad6..5369400 100644 --- a/package.json +++ b/package.json @@ -4,7 +4,7 @@ "description": "MCP server for Lightspeed API - 2026 Complete Version", "type": "module", "main": "dist/index.js", - "author": "MCPEngine ", + "author": "MCPEngage ", "license": "MIT", "repository": { "type": "git",