mcpengine/servers/lightspeed/README.md

# Lightspeed Retail MCP Server

Complete Model Context Protocol (MCP) server for Lightspeed Retail (X-Series/R-Series). Provides comprehensive point-of-sale, inventory management, and retail analytics capabilities for Claude Desktop and other MCP clients.

## Features

### 🛍️ Products & Inventory
- List, create, update, and delete products
- Manage product variants and images
- Track inventory levels across shops
- Handle stock transfers and adjustments
- Purchase order management
- Supplier/vendor management

### 💰 Sales & Transactions
- Create and manage sales transactions
- Add line items to sales
- Process payments and refunds
- Track completed and pending sales
- Register/till management (open/close)

### 👥 Customers
- Customer database management
- Search and filter customers
- Track purchase history
- Loyalty program integration
- Contact information management

### 👔 Employees
- Employee roster management
- Time clock functionality (clock in/out)
- Employee sales performance tracking
- Role-based access control

### 📊 Reporting
- Sales summary reports
- Inventory valuation
- Product performance analysis
- Employee sales reports
- Custom date range filtering

### ⚙️ Configuration
- Product categories and hierarchies
- Discount and promotion management
- Tax class configuration
- Multi-location support

## Installation

```bash
npm install @mcpengine/lightspeed-mcp-server
```

## Configuration

### Environment Variables

```bash
export LIGHTSPEED_ACCOUNT_ID=your_account_id
export LIGHTSPEED_ACCESS_TOKEN=your_oauth_token
# Optional: Custom API URL (defaults to official Lightspeed API)
export LIGHTSPEED_API_URL=https://api.lightspeedapp.com/API/V3/Account/YOUR_ACCOUNT
```

### Claude Desktop Configuration

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "lightspeed": {
      "command": "npx",
      "args": ["-y", "@mcpengine/lightspeed-mcp-server"],
      "env": {
        "LIGHTSPEED_ACCOUNT_ID": "your_account_id",
        "LIGHTSPEED_ACCESS_TOKEN": "your_oauth_token"
      }
    }
  }
}
```

## OAuth Setup

Lightspeed uses OAuth2 for authentication. To get your access token:

1. **Create Lightspeed API Application**
   - Go to Lightspeed Developer Portal
   - Register a new application
   - Note your Client ID and Client Secret

2. **Generate Access Token**
   ```bash
   curl -X POST https://cloud.lightspeedapp.com/oauth/access_token.php \
     -d "client_id=YOUR_CLIENT_ID" \
     -d "client_secret=YOUR_CLIENT_SECRET" \
     -d "code=AUTHORIZATION_CODE" \
     -d "grant_type=authorization_code"
   ```

3. **Get Account ID**
   - Available in Lightspeed admin panel
   - Or via API: `GET https://api.lightspeedapp.com/API/Account.json`

## Tools (54 Total)

### Products (8 tools)
- `lightspeed_list_products` - List all products
- `lightspeed_get_product` - Get product details
- `lightspeed_create_product` - Create new product
- `lightspeed_update_product` - Update product
- `lightspeed_delete_product` - Delete/archive product
- `lightspeed_list_product_variants` - List product variants
- `lightspeed_list_product_images` - List product images
- `lightspeed_update_product_inventory` - Update inventory quantity

### Sales (8 tools)
- `lightspeed_list_sales` - List sales transactions
- `lightspeed_get_sale` - Get sale details
- `lightspeed_create_sale` - Create new sale
- `lightspeed_add_sale_line_item` - Add item to sale
- `lightspeed_list_sale_payments` - List sale payments
- `lightspeed_process_payment` - Process payment
- `lightspeed_refund_sale` - Create refund
- `lightspeed_complete_sale` - Mark sale as complete

### Customers (7 tools)
- `lightspeed_list_customers` - List all customers
- `lightspeed_get_customer` - Get customer details
- `lightspeed_create_customer` - Create new customer
- `lightspeed_update_customer` - Update customer
- `lightspeed_delete_customer` - Delete customer
- `lightspeed_search_customers` - Search customers
- `lightspeed_get_customer_loyalty` - Get loyalty info

### Inventory (8 tools)
- `lightspeed_list_inventory` - List inventory counts
- `lightspeed_get_item_inventory` - Get item inventory
- `lightspeed_update_inventory_count` - Update inventory
- `lightspeed_transfer_stock` - Transfer between shops
- `lightspeed_list_inventory_adjustments` - List adjustments
- `lightspeed_list_suppliers` - List suppliers/vendors
- `lightspeed_create_purchase_order` - Create PO
- `lightspeed_list_purchase_orders` - List POs

### Registers (5 tools)
- `lightspeed_list_registers` - List all registers
- `lightspeed_get_register` - Get register details
- `lightspeed_open_register` - Open register (till)
- `lightspeed_close_register` - Close register
- `lightspeed_get_cash_counts` - Get cash counts

### Employees (6 tools)
- `lightspeed_list_employees` - List all employees
- `lightspeed_get_employee` - Get employee details
- `lightspeed_create_employee` - Create employee
- `lightspeed_update_employee` - Update employee
- `lightspeed_list_time_entries` - List time entries
- `lightspeed_clock_in` - Clock in employee
- `lightspeed_clock_out` - Clock out employee

### Categories (5 tools)
- `lightspeed_list_categories` - List categories
- `lightspeed_get_category` - Get category details
- `lightspeed_create_category` - Create category
- `lightspeed_update_category` - Update category
- `lightspeed_delete_category` - Delete category

### Discounts (5 tools)
- `lightspeed_list_discounts` - List discounts
- `lightspeed_get_discount` - Get discount details
- `lightspeed_create_discount` - Create discount
- `lightspeed_update_discount` - Update discount
- `lightspeed_delete_discount` - Delete discount

### Taxes (4 tools)
- `lightspeed_list_taxes` - List tax classes
- `lightspeed_get_tax` - Get tax details
- `lightspeed_create_tax` - Create tax class
- `lightspeed_update_tax` - Update tax class

### Reporting (4 tools)
- `lightspeed_sales_summary` - Sales summary report
- `lightspeed_inventory_value` - Inventory valuation
- `lightspeed_product_performance` - Product performance
- `lightspeed_employee_sales` - Employee sales report

## MCP Apps (17 Apps)

Pre-built UI applications accessible via MCP prompts:

### Products
- `product-dashboard` - Inventory overview
- `product-detail` - Detailed product view
- `product-grid` - Filterable product list
- `category-manager` - Category management

### Sales
- `sales-dashboard` - Sales overview
- `sales-detail` - Transaction details
- `sales-report` - Sales analytics

### Customers
- `customer-detail` - Customer profile
- `customer-grid` - Customer list

### Inventory
- `inventory-tracker` - Stock levels
- `inventory-adjustments` - Adjustment tracking
- `purchase-orders` - PO management

### Operations
- `register-manager` - Register management
- `employee-dashboard` - Employee overview
- `discount-manager` - Discount configuration
- `tax-settings` - Tax configuration
- `product-performance` - Performance analytics

## Example Usage

```typescript
// In Claude Desktop, you can now use natural language:

"Show me the product dashboard"
"Create a new customer named John Doe with email john@example.com"
"List all sales from yesterday"
"What are the top 10 selling products this month?"
"Transfer 50 units of item #123 from shop 1 to shop 2"
"Generate a sales summary report for last week"
"Clock in employee #456"
"Show me inventory levels for shop 1"
```

## API Reference

### Lightspeed API Documentation
- [Official API Docs](https://developers.lightspeedhq.com/retail/introduction/introduction/)
- [Authentication](https://developers.lightspeedhq.com/retail/authentication/authentication/)
- [Rate Limits](https://developers.lightspeedhq.com/retail/introduction/rate-limiting/)

### Rate Limiting
- Default: 10 requests/second per account
- Burst: up to 60 requests
- This server includes automatic rate limit handling and retry logic

## Development

```bash
# Clone repository
git clone https://github.com/BusyBee3333/mcpengine.git
cd mcpengine/servers/lightspeed

# Install dependencies
npm install

# Build
npm run build

# Run locally
export LIGHTSPEED_ACCOUNT_ID=your_account_id
export LIGHTSPEED_ACCESS_TOKEN=your_token
npm start
```

## Troubleshooting

### Authentication Errors
- Verify your Account ID and Access Token are correct
- Check if your OAuth token has expired (Lightspeed tokens expire)
- Ensure your API application has the required scopes

### API Errors
- Check Lightspeed API status page
- Verify rate limits haven't been exceeded
- Ensure your account has access to the requested resources

### Connection Issues
- Verify network connectivity
- Check firewall settings
- Ensure API URL is correct (if using custom URL)

## License

MIT

## Support

- GitHub Issues: [mcpengine/issues](https://github.com/BusyBee3333/mcpengine/issues)
- Lightspeed Support: [support.lightspeedhq.com](https://support.lightspeedhq.com)

## Related Resources

- [Lightspeed Developer Portal](https://developers.lightspeedhq.com/)
- [MCP Protocol Specification](https://modelcontextprotocol.io)
- [Claude Desktop Documentation](https://claude.ai/desktop)