# 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