SmartKasa MCP Server

# SmartKasa MCP Server

> MCP server for SmartKasa Ukrainian POS/fiscal system API

## Quick Start for LLMs

When user wants to work with SmartKasa, follow this flow:

1. **Check authentication status** first:
   ```
   smartkasa_get_status
   ```

2. **If not authenticated**, either:
   - Credentials are in env vars → call `smartkasa_authenticate`
   - No credentials → ask user, then call `smartkasa_set_credentials` + `smartkasa_authenticate`

3. **Use tools** to fulfill user requests

## Authentication Tools

| Tool | When to Use |
|------|-------------|
| `smartkasa_set_credentials` | User provides API key, phone, password |
| `smartkasa_authenticate` | Get access token (auto-refreshes) |
| `smartkasa_get_status` | Check if authenticated, token expiry |
| `smartkasa_logout` | Clear session (rarely needed) |

## Core Business Tools

### Shops (Магазини)
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `smartkasa_shops_list` | List all shops | `page`, `per_page` |
| `smartkasa_shops_get` | Get shop details | `id` (required) |
| `smartkasa_shops_create` | Create shop | `title`, `address`, `schedule` |
| `smartkasa_shops_update` | Update shop | `id`, fields to update |
| `smartkasa_shops_delete` | Delete shop | `id` |
| `smartkasa_shops_employees` | List shop staff | `id` |

### Products (Товари)
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `smartkasa_products_list` | Search products | `q` (search), `category_id`, `page`, `per_page` |
| `smartkasa_products_get` | Get by UUID | `id` (UUID) |
| `smartkasa_products_create` | Create product | `title`, `price`, `unit_type_id`, `tax_group_id` |
| `smartkasa_products_update` | Update product | `id`, fields to update |
| `smartkasa_products_delete` | Delete product | `id` |
| `smartkasa_products_batch_create` | Bulk create | `products` (array) |
| `smartkasa_products_batch_delete` | Bulk delete | `ids` (array) |

### Categories (Категорії)
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `smartkasa_categories_list` | List categories | `page`, `per_page` |
| `smartkasa_categories_create` | Create category | `title`, `parent_id` (optional) |
| `smartkasa_categories_update` | Update category | `id`, `title` |
| `smartkasa_categories_delete` | Delete category | `id` |
| `smartkasa_categories_batch_create` | Bulk create | `categories` (array) |
| `smartkasa_categories_batch_delete` | Bulk delete | `ids` (array) |

### Employees (Працівники)
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `smartkasa_employees_list` | List employees | `shop_id`, `page`, `per_page` |
| `smartkasa_employees_get` | Get employee | `id` |
| `smartkasa_employees_create` | Create employee | `first_name`, `last_name`, `role`, `shop_id` |
| `smartkasa_employees_update` | Update employee | `id`, fields to update |
| `smartkasa_employees_delete` | Delete employee | `id` |

### Receipts (Чеки)
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `smartkasa_receipts_list` | List receipts | `shop_id`, `terminal_id`, `from`, `to`, `page` |
| `smartkasa_receipts_get` | Get receipt | `id` (UUID) |
| `smartkasa_receipts_create` | Create receipt | `items`, `payments`, `terminal_id` |
| `smartkasa_receipts_update` | Update receipt | `id`, fields |
| `smartkasa_receipts_delete` | Delete receipt | `id` |
| `smartkasa_receipts_batch_create` | Bulk create | `receipts` (array) |
| `smartkasa_receipts_batch_delete` | Bulk delete | `ids` (array) |

### Terminals (Термінали/Каси)
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `smartkasa_terminals_list` | List POS terminals | `shop_id`, `page` |
| `smartkasa_terminals_get` | Get terminal | `id` |
| `smartkasa_terminals_update` | Update terminal | `id`, fields |
| `smartkasa_terminals_delete` | Delete terminal | `id` |

### Inventory Cards (Складські картки)
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `smartkasa_cards_list` | List inventory | `shop_id`, `product_id`, `page` |
| `smartkasa_cards_get` | Get card | `id` |
| `smartkasa_cards_create` | Create card | `product_id`, `shop_id`, `quantity` |
| `smartkasa_cards_update` | Update stock | `id`, `quantity` |
| `smartkasa_cards_delete` | Delete card | `id` |

### Reports (Звіти)
| Tool | Purpose | Key Parameters |
|------|---------|----------------|
| `smartkasa_reports_z_reports` | Z-reports (fiscal) | `shop_id`, `terminal_id`, `from`, `to` |
| `smartkasa_reports_product_sales` | Sales statistics | `shop_id`, `from`, `to`, `group_by` |

### Other Tools
| Tool | Purpose |
|------|---------|
| `smartkasa_unit_types_list` | List unit types (штуки, кг, л) |
| `smartkasa_subgroups_list` | Product subgroups |
| `smartkasa_subgroups_create` | Create subgroup |
| `smartkasa_subgroups_update` | Update subgroup |
| `smartkasa_subgroups_delete` | Delete subgroup |
| `smartkasa_import_start` | Start product import |
| `smartkasa_import_status` | Check import status |
| `smartkasa_import_confirm` | Confirm import |
| `smartkasa_shifts_list` | Fiscal shifts |
| `smartkasa_shifts_get` | Get shift details |
| `smartkasa_transactions_get` | Payment transaction |

## Common Patterns

### List all products
```
smartkasa_products_list with per_page=100
```

### Search products by name
```
smartkasa_products_list with q="кава"
```

### Create product with VAT
```
smartkasa_products_create with:
  title="Еспресо"
  price=45.00
  unit_type_id=0  (pieces)
  tax_group_id=1  (20% VAT)
```

### Get sales report for period
```
smartkasa_reports_product_sales with:
  shop_id=123
  from="2024-01-01"
  to="2024-01-31"
```

### Check inventory in shop
```
smartkasa_cards_list with shop_id=123
```

## Important Notes

1. **Always check auth first** - most tools require authentication
2. **Use UUIDs** - products, receipts use UUID, not numeric ID
3. **Pagination** - use `page` and `per_page` for large lists
4. **Date format** - ISO 8601: "2024-01-15" or "2024-01-15T10:30:00"
5. **Tax groups** - 1=20% VAT, 2=7% VAT, 3=0% VAT, 4=exempt
6. **Unit types** - 0=pieces, 1=kg, 2=liters

## Error Handling

- **401** - Re-authenticate (token expired)
- **404** - Resource not found
- **422** - Validation error (check parameters)
- **429** - Rate limited (automatic retry)

## Example Conversation Flow

User: "Покажи всі товари категорії Напої"
1. Call `smartkasa_get_status` → check auth
2. If not auth → `smartkasa_authenticate`
3. Call `smartkasa_categories_list` → find "Напої" category ID
4. Call `smartkasa_products_list` with `category_id`
5. Present results to user

User: "Створи новий товар Лате за 55 грн"
1. Check auth status
2. Call `smartkasa_products_create` with title="Лате", price=55.00, unit_type_id=0, tax_group_id=1
3. Confirm creation to user