393 lines
12 KiB
Markdown
393 lines
12 KiB
Markdown
# TouchBistro MCP Server
|
|
|
|
A comprehensive Model Context Protocol (MCP) server for TouchBistro restaurant management platform, providing **190 tools** across 12 domains and **15 React MCP Apps** for visual management.
|
|
|
|
## Features
|
|
|
|
### 🍽️ Core Restaurant Management
|
|
|
|
- **Orders Management** (15 tools)
|
|
- Create, update, track orders with full CRUD operations
|
|
- Send to kitchen, manage modifications, void/cancel orders
|
|
- Table orders, open orders, customer order history
|
|
|
|
- **Menu Management** (21 tools)
|
|
- Menu items, categories, modifiers with full CRUD
|
|
- Bulk updates, availability control
|
|
- Modifier groups and custom modifiers
|
|
|
|
- **Customer Management** (12 tools)
|
|
- Customer profiles with preferences and allergens
|
|
- VIP tracking, tagging, address management
|
|
- Customer statistics and analytics
|
|
|
|
- **Employee Management** (19 tools)
|
|
- Employee profiles and permissions
|
|
- Shift scheduling and time clock
|
|
- Performance tracking and labor management
|
|
|
|
- **Table Management** (17 tools)
|
|
- Floor plans and table layouts
|
|
- Table status tracking (available, occupied, reserved)
|
|
- Table merging/splitting, server assignments
|
|
|
|
### 💰 Financial Operations
|
|
|
|
- **Payment Processing** (13 tools)
|
|
- Multiple payment methods (cash, card, mobile, gift cards)
|
|
- Authorization, capture, void, refund operations
|
|
- Split payments and tip management
|
|
|
|
- **Reservations** (15 tools)
|
|
- Create, confirm, seat, and track reservations
|
|
- Availability checking and reminders
|
|
- No-show tracking
|
|
|
|
- **Loyalty Programs** (10 tools)
|
|
- Points earning and redemption
|
|
- Birthday bonuses and rewards
|
|
- Member analytics and tier management
|
|
|
|
- **Gift Cards** (13 tools)
|
|
- Purchase, reload, redeem gift cards
|
|
- Balance checking and email delivery
|
|
- Transaction history and sales tracking
|
|
|
|
### 📊 Inventory & Analytics
|
|
|
|
- **Inventory Management** (17 tools)
|
|
- Stock tracking with par levels
|
|
- Purchase orders and receiving
|
|
- Low stock alerts and reorder management
|
|
|
|
- **Reports & Analytics** (24 tools)
|
|
- Sales reports (daily, hourly, by category)
|
|
- Employee performance and labor costs
|
|
- Customer acquisition and retention
|
|
- Menu performance and profitability
|
|
- Real-time dashboard
|
|
|
|
- **Discounts & Promotions** (14 tools)
|
|
- Create and manage discounts
|
|
- Happy hour and daily specials
|
|
- Promotion scheduling and tracking
|
|
|
|
## Installation
|
|
|
|
```bash
|
|
npm install touchbistro-mcp-server
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Set the following environment variables:
|
|
|
|
```bash
|
|
TOUCHBISTRO_API_KEY=your_api_key
|
|
TOUCHBISTRO_RESTAURANT_ID=your_restaurant_id
|
|
TOUCHBISTRO_BASE_URL=https://api.touchbistro.com/v1 # Optional
|
|
```
|
|
|
|
## Usage
|
|
|
|
### As an MCP Server
|
|
|
|
Add to your Claude Desktop or other MCP client configuration:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"touchbistro": {
|
|
"command": "touchbistro-mcp-server",
|
|
"env": {
|
|
"TOUCHBISTRO_API_KEY": "your_api_key",
|
|
"TOUCHBISTRO_RESTAURANT_ID": "your_restaurant_id"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Direct Usage
|
|
|
|
```bash
|
|
touchbistro-mcp-server
|
|
```
|
|
|
|
## React MCP Apps (15 Apps)
|
|
|
|
This server includes 15 standalone React applications for visual management:
|
|
|
|
1. **Orders Dashboard** - Real-time order tracking and management
|
|
2. **Menu Manager** - Visual menu builder with drag-and-drop
|
|
3. **Reservations Calendar** - Interactive reservation scheduling
|
|
4. **Table Layout** - Visual floor plan editor
|
|
5. **Customer Directory** - Customer profiles and history
|
|
6. **Employee Scheduler** - Shift scheduling and time tracking
|
|
7. **Payments Dashboard** - Payment processing and reconciliation
|
|
8. **Loyalty Manager** - Loyalty program administration
|
|
9. **Gift Card Manager** - Gift card sales and tracking
|
|
10. **Inventory Tracker** - Stock levels and purchase orders
|
|
11. **Sales Reports** - Interactive sales analytics
|
|
12. **Analytics Dashboard** - Business intelligence and KPIs
|
|
13. **Discounts Manager** - Promotion creation and tracking
|
|
14. **Settings Panel** - Restaurant configuration
|
|
15. **Real-time Dashboard** - Live business overview
|
|
|
|
Each app is:
|
|
- Dark theme optimized
|
|
- Fully responsive
|
|
- Built with React 18 + TypeScript
|
|
- Vite-powered for fast development
|
|
- Standalone deployable
|
|
|
|
### Building Apps
|
|
|
|
```bash
|
|
# Build all apps
|
|
npm run build
|
|
|
|
# Build specific app
|
|
npm run build:orders-app
|
|
npm run build:menu-app
|
|
# ... etc
|
|
```
|
|
|
|
## API Structure
|
|
|
|
### Orders
|
|
|
|
```typescript
|
|
// Create an order
|
|
{
|
|
"name": "create_order",
|
|
"arguments": {
|
|
"tableId": "table-123",
|
|
"employeeId": "emp-456",
|
|
"orderType": "dine_in",
|
|
"items": [
|
|
{
|
|
"menuItemId": "item-789",
|
|
"quantity": 2,
|
|
"modifiers": [{ "modifierId": "mod-123" }]
|
|
}
|
|
]
|
|
}
|
|
}
|
|
```
|
|
|
|
### Menu Management
|
|
|
|
```typescript
|
|
// Create menu item
|
|
{
|
|
"name": "create_menu_item",
|
|
"arguments": {
|
|
"name": "Margherita Pizza",
|
|
"categoryId": "cat-pizza",
|
|
"price": 14.99,
|
|
"description": "Classic Italian pizza",
|
|
"allergens": ["gluten", "dairy"]
|
|
}
|
|
}
|
|
```
|
|
|
|
### Reservations
|
|
|
|
```typescript
|
|
// Create reservation
|
|
{
|
|
"name": "create_reservation",
|
|
"arguments": {
|
|
"customerName": "John Doe",
|
|
"customerPhone": "555-0123",
|
|
"partySize": 4,
|
|
"date": "2024-12-25",
|
|
"time": "19:00"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Reports
|
|
|
|
```typescript
|
|
// Get sales report
|
|
{
|
|
"name": "get_sales_report",
|
|
"arguments": {
|
|
"startDate": "2024-01-01",
|
|
"endDate": "2024-01-31"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Tool Categories
|
|
|
|
### Orders (15 tools)
|
|
- list_orders, get_order, create_order, update_order
|
|
- add_order_items, remove_order_item, update_order_item
|
|
- send_to_kitchen, complete_order, cancel_order, void_order
|
|
- get_table_orders, get_open_orders, search_orders, get_customer_orders
|
|
|
|
### Menu (21 tools)
|
|
- **Items**: list_menu_items, get_menu_item, create_menu_item, update_menu_item, delete_menu_item, bulk_update_menu_items, set_item_availability
|
|
- **Categories**: list_menu_categories, get_menu_category, create_menu_category, update_menu_category, delete_menu_category, reorder_menu_categories
|
|
- **Modifiers**: list_modifier_groups, get_modifier_group, create_modifier_group, update_modifier_group, delete_modifier_group, add_modifier, update_modifier, delete_modifier
|
|
|
|
### Customers (12 tools)
|
|
- list_customers, get_customer, create_customer, update_customer, delete_customer
|
|
- search_customers, add_customer_address, update_customer_preferences
|
|
- get_customer_stats, get_vip_customers, tag_customer, untag_customer
|
|
|
|
### Employees (19 tools)
|
|
- **Staff**: list_employees, get_employee, create_employee, update_employee, delete_employee, deactivate_employee, update_employee_permissions
|
|
- **Shifts**: list_shifts, get_shift, create_shift, start_shift, end_shift, get_current_shifts
|
|
- **Time Clock**: clock_in, clock_out, start_break, end_break, get_time_clock_entries, get_employee_hours
|
|
|
|
### Tables (17 tools)
|
|
- **Tables**: list_tables, get_table, create_table, update_table, delete_table, set_table_status, assign_server, get_available_tables, get_occupied_tables, merge_tables, split_tables
|
|
- **Floors**: list_floors, get_floor, create_floor, update_floor, delete_floor, get_floor_layout
|
|
|
|
### Payments (13 tools)
|
|
- list_payments, get_payment, process_payment, authorize_payment, capture_payment
|
|
- void_payment, refund_payment, get_payment_refunds, list_refunds
|
|
- split_payment, add_tip, get_payment_summary, get_payment_methods_summary
|
|
|
|
### Reservations (15 tools)
|
|
- list_reservations, get_reservation, create_reservation, update_reservation, delete_reservation
|
|
- confirm_reservation, cancel_reservation, seat_reservation, mark_no_show, complete_reservation
|
|
- get_reservations_by_date, get_upcoming_reservations, search_reservations, send_reminder, get_available_slots
|
|
|
|
### Loyalty (10 tools)
|
|
- get_loyalty_program, update_loyalty_program, get_customer_points
|
|
- add_loyalty_points, redeem_loyalty_points, get_loyalty_transactions
|
|
- get_loyalty_members, get_top_loyalty_members, award_birthday_points, get_loyalty_analytics
|
|
|
|
### Gift Cards (13 tools)
|
|
- list_gift_cards, get_gift_card, get_gift_card_by_number, create_gift_card
|
|
- purchase_gift_card, reload_gift_card, redeem_gift_card, void_gift_card
|
|
- activate_gift_card, check_balance, get_gift_card_transactions, send_gift_card_email, get_gift_card_sales
|
|
|
|
### Inventory (17 tools)
|
|
- **Items**: list_inventory_items, get_inventory_item, create_inventory_item, update_inventory_item, delete_inventory_item, adjust_stock, get_stock_adjustments, get_low_stock_items, get_items_to_reorder, get_inventory_valuation
|
|
- **Purchase Orders**: list_purchase_orders, get_purchase_order, create_purchase_order, update_purchase_order, send_purchase_order, receive_purchase_order, cancel_purchase_order
|
|
|
|
### Reports (24 tools)
|
|
- **Sales**: get_sales_report, get_daily_sales, get_sales_by_hour, get_sales_by_day, get_sales_by_category, get_sales_by_payment_method
|
|
- **Menu**: get_top_selling_items, get_menu_performance, get_menu_item_analytics
|
|
- **Staff**: get_employee_performance, get_employee_sales, get_labor_cost_report
|
|
- **Customers**: get_customer_analytics, get_customer_acquisition, get_customer_retention
|
|
- **Other**: get_tax_report, get_discount_usage, get_tip_report, get_order_type_distribution, get_table_turnover, get_average_order_value, export_report_csv, get_realtime_dashboard, get_profit_loss_report
|
|
|
|
### Discounts (14 tools)
|
|
- **Discounts**: list_discounts, get_discount, create_discount, update_discount, delete_discount, validate_discount_code, apply_discount, remove_discount
|
|
- **Promotions**: list_promotions, get_promotion, create_promotion, update_promotion, delete_promotion, get_active_promotions
|
|
|
|
## Resources
|
|
|
|
- `touchbistro://config` - View current API configuration
|
|
- `touchbistro://docs` - Complete documentation
|
|
|
|
## Architecture
|
|
|
|
```
|
|
touchbistro/
|
|
├── src/
|
|
│ ├── clients/
|
|
│ │ └── touchbistro.ts # API client with auth & error handling
|
|
│ ├── types/
|
|
│ │ └── index.ts # TypeScript type definitions
|
|
│ ├── tools/
|
|
│ │ ├── orders.ts # Order management tools
|
|
│ │ ├── menus.ts # Menu management tools
|
|
│ │ ├── customers.ts # Customer management tools
|
|
│ │ ├── employees.ts # Employee management tools
|
|
│ │ ├── tables.ts # Table management tools
|
|
│ │ ├── payments.ts # Payment processing tools
|
|
│ │ ├── reservations.ts # Reservation tools
|
|
│ │ ├── loyalty.ts # Loyalty program tools
|
|
│ │ ├── giftcards.ts # Gift card tools
|
|
│ │ ├── inventory.ts # Inventory management tools
|
|
│ │ ├── reports.ts # Reporting tools
|
|
│ │ └── discounts.ts # Discount & promotion tools
|
|
│ ├── ui/ # 15 React MCP Apps
|
|
│ │ ├── orders-app/
|
|
│ │ ├── menu-app/
|
|
│ │ ├── reservations-app/
|
|
│ │ ├── tables-app/
|
|
│ │ ├── customers-app/
|
|
│ │ ├── employees-app/
|
|
│ │ ├── payments-app/
|
|
│ │ ├── loyalty-app/
|
|
│ │ ├── giftcards-app/
|
|
│ │ ├── inventory-app/
|
|
│ │ ├── reports-app/
|
|
│ │ ├── analytics-app/
|
|
│ │ ├── discounts-app/
|
|
│ │ ├── settings-app/
|
|
│ │ └── dashboard-app/
|
|
│ ├── server.ts # MCP server implementation
|
|
│ └── main.ts # Entry point
|
|
├── package.json
|
|
├── tsconfig.json
|
|
└── README.md
|
|
```
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Build TypeScript
|
|
npm run build
|
|
|
|
# Watch mode for development
|
|
npm run dev
|
|
|
|
# Run the server
|
|
npm start
|
|
```
|
|
|
|
## Testing
|
|
|
|
```bash
|
|
# Test connection
|
|
echo '{"method":"tools/list"}' | touchbistro-mcp-server
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|
|
|
|
## Support
|
|
|
|
For issues and questions, please visit the [GitHub repository](https://github.com/BusyBee3333/mcpengine).
|
|
|
|
## TouchBistro API
|
|
|
|
This server implements the TouchBistro REST API v1. For API documentation, contact TouchBistro or visit their developer portal.
|
|
|
|
### API Authentication
|
|
|
|
TouchBistro uses API key authentication:
|
|
- Header: `Authorization: Bearer {api_key}`
|
|
- Header: `X-Restaurant-ID: {restaurant_id}`
|
|
|
|
### Rate Limiting
|
|
|
|
Please be aware of TouchBistro's API rate limits. This server implements automatic retry with exponential backoff for rate-limited requests.
|
|
|
|
## Contributing
|
|
|
|
Contributions welcome! Please submit pull requests to the main repository.
|
|
|
|
## Changelog
|
|
|
|
### v1.0.0 (2024)
|
|
- Initial release
|
|
- 190 tools across 12 domains
|
|
- 15 React MCP Apps
|
|
- Full CRUD operations for all resources
|
|
- Comprehensive reporting and analytics
|