381 lines
9.1 KiB
Markdown
381 lines
9.1 KiB
Markdown
# Toast MCP Server
|
|
|
|
A complete Model Context Protocol (MCP) server for Toast POS integration, providing comprehensive access to orders, menus, employees, labor, payments, inventory, customers, and reporting.
|
|
|
|
## Features
|
|
|
|
### 🔧 50+ MCP Tools
|
|
|
|
#### Orders (9 tools)
|
|
- `toast_list_orders` - List orders with date range filtering
|
|
- `toast_get_order` - Get order details
|
|
- `toast_create_order` - Create new orders
|
|
- `toast_update_order` - Update order details
|
|
- `toast_add_order_item` - Add items to orders
|
|
- `toast_remove_order_item` - Remove items from orders
|
|
- `toast_apply_discount` - Apply discounts
|
|
- `toast_void_order` - Void orders
|
|
- `toast_list_order_checks` - List order checks
|
|
|
|
#### Menus (8 tools)
|
|
- `toast_list_menus` - List all menus
|
|
- `toast_get_menu` - Get menu details
|
|
- `toast_list_menu_groups` - List menu groups
|
|
- `toast_get_menu_group` - Get group details
|
|
- `toast_list_menu_items` - List menu items
|
|
- `toast_get_menu_item` - Get item details
|
|
- `toast_list_item_modifiers` - List item modifiers
|
|
- `toast_update_item_price` - Update item pricing
|
|
|
|
#### Employees (10 tools)
|
|
- `toast_list_employees` - List all employees
|
|
- `toast_get_employee` - Get employee details
|
|
- `toast_create_employee` - Create new employees
|
|
- `toast_update_employee` - Update employee info
|
|
- `toast_delete_employee` - Delete employees
|
|
- `toast_list_employee_jobs` - List employee jobs
|
|
- `toast_list_employee_shifts` - List employee shifts
|
|
- `toast_clock_in` - Clock in employees
|
|
- `toast_clock_out` - Clock out employees
|
|
- `toast_list_time_entries` - List time entries
|
|
|
|
#### Labor (5 tools)
|
|
- `toast_list_shifts` - List all shifts
|
|
- `toast_get_shift` - Get shift details
|
|
- `toast_list_shift_breaks` - List shift breaks
|
|
- `toast_get_labor_cost` - Get labor cost reports
|
|
- `toast_list_jobs` - List job positions
|
|
|
|
#### Restaurant (5 tools)
|
|
- `toast_get_restaurant_info` - Get restaurant info
|
|
- `toast_list_revenue_centers` - List revenue centers
|
|
- `toast_list_dining_options` - List dining options
|
|
- `toast_list_service_areas` - List service areas
|
|
- `toast_list_tables` - List tables
|
|
|
|
#### Payments (5 tools)
|
|
- `toast_list_payments` - List payments
|
|
- `toast_get_payment` - Get payment details
|
|
- `toast_void_payment` - Void payments
|
|
- `toast_refund_payment` - Process refunds
|
|
- `toast_list_tips` - List tips
|
|
|
|
#### Inventory (5 tools)
|
|
- `toast_list_inventory_items` - List inventory
|
|
- `toast_get_inventory_item` - Get item details
|
|
- `toast_update_inventory_count` - Update counts
|
|
- `toast_list_vendors` - List vendors
|
|
- `toast_create_purchase_order` - Create POs
|
|
|
|
#### Customers (6 tools)
|
|
- `toast_list_customers` - List customers
|
|
- `toast_get_customer` - Get customer details
|
|
- `toast_create_customer` - Create customers
|
|
- `toast_update_customer` - Update customer info
|
|
- `toast_list_customer_loyalty` - List loyalty info
|
|
- `toast_add_loyalty_points` - Add loyalty points
|
|
|
|
#### Reporting (5 tools)
|
|
- `toast_sales_summary` - Sales summary reports
|
|
- `toast_labor_cost_report` - Labor cost analysis
|
|
- `toast_menu_item_performance` - Menu performance
|
|
- `toast_revenue_by_hour` - Hourly revenue
|
|
- `toast_tip_summary` - Tip summaries
|
|
|
|
#### Cash Management (2 tools)
|
|
- `toast_list_cash_entries` - List cash entries
|
|
- `toast_get_drawer_status` - Get drawer status
|
|
|
|
### 📊 18 MCP Apps
|
|
|
|
1. **order-dashboard** - Real-time order monitoring
|
|
2. **order-detail** - Detailed order view
|
|
3. **order-grid** - Searchable order grid
|
|
4. **menu-manager** - Menu management interface
|
|
5. **menu-item-detail** - Item detail view
|
|
6. **employee-dashboard** - Employee management
|
|
7. **employee-schedule** - Schedule planning
|
|
8. **labor-dashboard** - Labor analytics
|
|
9. **restaurant-overview** - Restaurant config
|
|
10. **table-map** - Interactive floor plan
|
|
11. **payment-history** - Payment tracking
|
|
12. **inventory-tracker** - Inventory management
|
|
13. **customer-detail** - Customer profiles
|
|
14. **customer-loyalty** - Loyalty program
|
|
15. **sales-dashboard** - Sales analytics
|
|
16. **menu-performance** - Menu analytics
|
|
17. **tip-summary** - Tip tracking
|
|
18. **revenue-by-hour** - Hourly revenue analysis
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install
|
|
npm run build
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Set the following environment variables:
|
|
|
|
```bash
|
|
export TOAST_API_TOKEN="your-toast-api-token"
|
|
export TOAST_RESTAURANT_GUID="your-restaurant-guid"
|
|
export TOAST_BASE_URL="https://ws-api.toasttab.com" # Optional, defaults to production
|
|
```
|
|
|
|
### Getting Toast API Credentials
|
|
|
|
1. Log in to Toast Web Admin
|
|
2. Navigate to Integrations → API
|
|
3. Create a new API token
|
|
4. Copy your Restaurant GUID from Settings → Restaurant Info
|
|
|
|
## Usage
|
|
|
|
### As MCP Server
|
|
|
|
Add to your MCP client configuration:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"toast": {
|
|
"command": "node",
|
|
"args": ["/path/to/toast/dist/main.js"],
|
|
"env": {
|
|
"TOAST_API_TOKEN": "your-token",
|
|
"TOAST_RESTAURANT_GUID": "your-guid"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Direct Execution
|
|
|
|
```bash
|
|
npm start
|
|
```
|
|
|
|
## API Client Features
|
|
|
|
- ✅ Bearer token authentication
|
|
- ✅ Restaurant GUID injection
|
|
- ✅ Automatic pagination handling
|
|
- ✅ Comprehensive error handling
|
|
- ✅ Rate limit awareness
|
|
- ✅ Retry logic
|
|
- ✅ Request/response logging
|
|
|
|
## Tool Examples
|
|
|
|
### List Today's Orders
|
|
|
|
```typescript
|
|
{
|
|
"name": "toast_list_orders",
|
|
"arguments": {
|
|
"startDate": "2025-01-28T00:00:00Z",
|
|
"endDate": "2025-01-28T23:59:59Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Create New Order
|
|
|
|
```typescript
|
|
{
|
|
"name": "toast_create_order",
|
|
"arguments": {
|
|
"diningOptionGuid": "abc-123",
|
|
"tableGuid": "table-5",
|
|
"numberOfGuests": 4
|
|
}
|
|
}
|
|
```
|
|
|
|
### Add Item to Order
|
|
|
|
```typescript
|
|
{
|
|
"name": "toast_add_order_item",
|
|
"arguments": {
|
|
"orderId": "order-123",
|
|
"checkGuid": "check-456",
|
|
"itemGuid": "item-789",
|
|
"quantity": 2,
|
|
"modifiers": [
|
|
{ "guid": "mod-1", "quantity": 1 }
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
### Clock In Employee
|
|
|
|
```typescript
|
|
{
|
|
"name": "toast_clock_in",
|
|
"arguments": {
|
|
"employeeGuid": "emp-123",
|
|
"jobGuid": "job-server"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Get Sales Summary
|
|
|
|
```typescript
|
|
{
|
|
"name": "toast_sales_summary",
|
|
"arguments": {
|
|
"startDate": "2025-01-28T00:00:00Z",
|
|
"endDate": "2025-01-28T23:59:59Z"
|
|
}
|
|
}
|
|
```
|
|
|
|
## MCP App Access
|
|
|
|
Access apps via MCP resources:
|
|
|
|
```
|
|
toast://apps/order-dashboard
|
|
toast://apps/sales-dashboard
|
|
toast://apps/menu-manager
|
|
toast://apps/employee-schedule
|
|
toast://apps/table-map
|
|
```
|
|
|
|
## Architecture
|
|
|
|
```
|
|
toast/
|
|
├── src/
|
|
│ ├── api-client.ts # Toast API client with auth & pagination
|
|
│ ├── server.ts # MCP server implementation
|
|
│ ├── main.ts # Entry point
|
|
│ ├── types/
|
|
│ │ └── index.ts # TypeScript type definitions
|
|
│ ├── tools/
|
|
│ │ ├── orders-tools.ts # Order management tools
|
|
│ │ ├── menus-tools.ts # Menu management tools
|
|
│ │ ├── employees-tools.ts # Employee management tools
|
|
│ │ ├── labor-tools.ts # Labor tracking tools
|
|
│ │ ├── restaurant-tools.ts # Restaurant config tools
|
|
│ │ ├── payments-tools.ts # Payment processing tools
|
|
│ │ ├── inventory-tools.ts # Inventory management tools
|
|
│ │ ├── customers-tools.ts # Customer management tools
|
|
│ │ ├── reporting-tools.ts # Reporting & analytics tools
|
|
│ │ └── cash-tools.ts # Cash management tools
|
|
│ └── apps/
|
|
│ └── index.ts # MCP app definitions
|
|
├── package.json
|
|
├── tsconfig.json
|
|
└── README.md
|
|
```
|
|
|
|
## Error Handling
|
|
|
|
All tools return structured error responses:
|
|
|
|
```json
|
|
{
|
|
"content": [{
|
|
"type": "text",
|
|
"text": "Error: Order not found (404)"
|
|
}],
|
|
"isError": true
|
|
}
|
|
```
|
|
|
|
## Pagination
|
|
|
|
Tools support automatic pagination:
|
|
|
|
```typescript
|
|
{
|
|
"name": "toast_list_orders",
|
|
"arguments": {
|
|
"page": 2,
|
|
"pageSize": 50
|
|
}
|
|
}
|
|
```
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Build TypeScript
|
|
npm run build
|
|
|
|
# Watch mode for development
|
|
npm run dev
|
|
|
|
# Start server
|
|
npm start
|
|
```
|
|
|
|
## API Documentation
|
|
|
|
Toast API documentation: https://doc.toasttab.com/
|
|
|
|
### Key Endpoints
|
|
|
|
- **Orders**: `/orders/v2/orders`
|
|
- **Menus**: `/menus/v2/menus`
|
|
- **Labor**: `/labor/v1/employees`
|
|
- **Payments**: `/payments/v1/payments`
|
|
- **Restaurant**: `/restaurants/v1/restaurants`
|
|
|
|
## Security
|
|
|
|
- API tokens stored in environment variables
|
|
- No credentials in code or logs
|
|
- Bearer token authentication
|
|
- HTTPS-only communication
|
|
- Restaurant GUID scoping
|
|
|
|
## Support
|
|
|
|
For Toast API support: https://central.toasttab.com/s/support
|
|
|
|
## License
|
|
|
|
MIT
|
|
|
|
## Contributing
|
|
|
|
1. Fork the repository
|
|
2. Create a feature branch
|
|
3. Commit your changes
|
|
4. Push to the branch
|
|
5. Create a Pull Request
|
|
|
|
## Roadmap
|
|
|
|
- [ ] WebSocket support for real-time updates
|
|
- [ ] Advanced reporting with custom date ranges
|
|
- [ ] Menu optimization recommendations
|
|
- [ ] Labor cost forecasting
|
|
- [ ] Inventory auto-reordering
|
|
- [ ] Customer segmentation
|
|
- [ ] A/B testing for menu items
|
|
- [ ] Integration with third-party delivery platforms
|
|
- [ ] Multi-location support
|
|
- [ ] Advanced analytics dashboards
|
|
|
|
## Version History
|
|
|
|
### 1.0.0 (2025-01-28)
|
|
- Initial release
|
|
- 50+ MCP tools
|
|
- 18 MCP apps
|
|
- Complete Toast API integration
|
|
- Comprehensive type definitions
|
|
- Error handling and pagination
|