Rebrand to MCPEngage and customize Lightspeed README with retail POS power moves

2026-02-02 06:58:51 -05:00 · 2026-02-02 06:58:51 -05:00 · 37c9aa1ae0
commit 37c9aa1ae0
parent 00fa4aae63
3 changed files with 104 additions and 34 deletions
--- 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
--- 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.

--- 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 <hello@mcpengage.com>",
+  "author": "MCPEngage <hello@mcpengage.com>",
  "license": "MIT",
  "repository": {
    "type": "git",