# iikoServer MCP Server

MCP (Model Context Protocol) server exposing the [iiko](https://iiko.ru) restaurant management system REST API as 42+ LLM-callable tools over stdio.

## Features

- **42+ tools** — products, employees, orders, payments, OLAP reports, assembly charts
- **Auto-auth** — SHA1 password hashing + session cookie, re-authenticates on 401
- **Graceful shutdown** — sends logout to release iiko license slot
- **Self-signed cert support** — `IIKO_VERIFY_SSL=false` by default
- **Venue mapping** — optional `IIKO_VENUE_MAP` to tag cash register numbers with names
- **Business-level helpers** — `get_checks`, `get_venues_revenue`, `get_staff_meals`, `get_top_dishes`, `compare_revenue`
- **Docker-ready** — Python 3.12-slim, stdio protocol

## Quick Start

### Local (pip)

```bash
git clone https://github.com/your-org/iiko-server-mcp.git
cd iiko-server-mcp
pip install -r requirements.txt
```

```bash
IIKO_URL=https://your-restaurant.iiko.it:443 \
IIKO_LOGIN=your_login \
IIKO_PASS=your_password \
python3 server.py
```

### Docker

```bash
docker build -t iiko-server-mcp .
docker run -i --rm \
  -e IIKO_URL=https://your-restaurant.iiko.it:443 \
  -e IIKO_LOGIN=your_login \
  -e IIKO_PASS=your_password \
  iiko-server-mcp
```

**Important:** MCP servers use **stdio** (not HTTP). The container must run with `-i` (interactive) so the MCP client can communicate via stdin/stdout. Do not use `-d` (detached).

## Configuration

Copy `.env.example` to `.env` and fill in real values:

| Variable | Required | Default | Description |
|---|---|---|---|
| `IIKO_URL` | **yes** | — | iikoServer base URL, e.g. `https://my-restaurant.iiko.it:443` |
| `IIKO_LOGIN` | **yes** | — | Login username |
| `IIKO_PASS` | **yes** | — | Plain password (SHA1-hashed before sending) |
| `IIKO_VENUE_MAP` | no | — | `"Venue A=4,Venue B=5"` — names for cash register numbers |
| `IIKO_VERIFY_SSL` | no | `false` | Set to `true` if using a CA-signed certificate |

## MCP Client Configuration

### Hermes Agent

```yaml
# ~/.hermes/config.yaml
mcp_servers:
  iiko-server:
    command: python3
    args: ["/path/to/iiko-server-mcp/server.py"]
    env:
      IIKO_URL: "https://your-restaurant.iiko.it:443"
      IIKO_LOGIN: "your_login"
      IIKO_PASS: "your_password"
      IIKO_VENUE_MAP: "Cafe A=4,Cafe B=5"
```

For Docker:

```yaml
mcp_servers:
  iiko-server:
    command: docker
    args: ["run", "-i", "--rm",
           "-e", "IIKO_URL=https://your-restaurant.iiko.it:443",
           "-e", "IIKO_LOGIN=your_login",
           "-e", "IIKO_PASS=your_password",
           "iiko-server-mcp"]
```

### Claude Desktop

```json
{
  "mcpServers": {
    "iiko-server": {
      "command": "python3",
      "args": ["/path/to/iiko-server-mcp/server.py"],
      "env": {
        "IIKO_URL": "https://your-restaurant.iiko.it:443",
        "IIKO_LOGIN": "your_login",
        "IIKO_PASS": "your_password"
      }
    }
  }
}
```

### Cursor

```json
{
  "mcpServers": {
    "iiko-server": {
      "command": "python3",
      "args": ["/path/to/iiko-server-mcp/server.py"],
      "env": {
        "IIKO_URL": "https://your-restaurant.iiko.it:443",
        "IIKO_LOGIN": "your_login",
        "IIKO_PASS": "your_password"
      }
    }
  }
}
```

## Available Tools

### System
- **ping** — Health check, server URL + auth state
- **list_endpoints** — All 42 tools with descriptions

### Products / Nomenclature
- **get_products** / **get_nomenclature** — All products
- **get_product_groups** — Product categories with hierarchy
- **get_product_sizes** — Sizes/units
- **get_corporate_structure** — Departments structure
- **get_corporate_groups** — Corporate groups
- **search_products** — Substring search by name

### Employees
- **get_employees** / **get_employee** / **get_employee_roles** / **get_persons**

### Entities
- **get_entity_types** / **get_entities** / **get_entity_by_id**
- **get_stores** — Warehouses
- **get_contractors** — Suppliers

### Documents
- **get_incoming_invoices** / **get_outgoing_invoices** — by date range (DD.MM.YYYY)
- **get_incoming_invoice_by_id** / **get_outgoing_invoice_by_id**
- **get_waste_documents** — Write-off documents
- **get_menu_changes** / **get_menu_change_by_id**

### Recipes (Assembly Charts)
- **get_assembly_charts** — All tech cards
- **get_assembly_chart_by_id** — Single chart
- **save_assembly_chart** — Create/update (⚠️ modifies production data)

### Cash & Payments
- **get_payment_types**
- **get_cash_shifts** / **get_cash_shift** — by session UUID
- **get_payments** / **get_payment** — per session
- **create_encashment** — Cash in/out (⚠️ modifies production data)

### Prices
- **get_price_categories** / **get_price_category**

### Reports & OLAP
- **get_olap_columns** — Schema for a report type (e.g. `SALES`)
- **run_olap_report** — Raw OLAP with custom columns/filters (DD.MM.YYYY)
- **get_olap_presets** / **run_olap_by_preset** — Saved presets
- **run_custom_report** — Named custom reports (DD.MM.YYYY)
- **get_venues_revenue** — Daily revenue by venue (YYYY-MM-DD)
- **get_staff_meals** — Free staff meals per venue (YYYY-MM-DD)
- **get_top_dishes** — Top N dishes by revenue (YYYY-MM-DD)
- **compare_revenue** — Day-over-day revenue comparison
- **get_checks** — Individual orders with payment type & masked card (YYYY-MM-DD)

### Raw
- **raw_request** — Direct authenticated HTTP call to any iikoServer endpoint

## Date Format

| Tool Group | Format | Example |
|---|---|---|
| Business helpers (`get_venues_revenue`, `get_checks`, etc.) | **YYYY-MM-DD** | `2026-07-17` |
| Legacy OLAP (`run_olap_report`, `run_olap_by_preset`) | **DD.MM.YYYY** | `17.07.2026` |

All business tools default to **Moscow time** (UTC+3) if no date is provided.

## Known Limitations

- **`get_cash_shifts`** — requires a date parameter; currently returns 409 if called without one
- **`get_payment_types`** — returns 404 on some iikoServer versions (endpoint may not exist)
- **Staff meal detection** — filters by `"(без оплаты)"` payment type label; verify this matches your iiko configuration
- **`CardTypeName`** — may return `"(нет карты)"` depending on acquirer integration
- **Self-signed certs** — default `verify=False`; set `IIKO_VERIFY_SSL=true` for CA-signed certificates

## Development

```bash
# Syntax check
python3 -m py_compile server.py

# Run locally with test env
IIKO_URL=... IIKO_LOGIN=... IIKO_PASS=... python3 server.py

# Build Docker
docker build -t iiko-server-mcp .
```

### Adding a Tool

1. Write a handler with the `@tool("name", "description", input_schema)` decorator
2. Add `"name"` to the appropriate category in `ENDPOINT_CATALOG`
3. Python will auto-register it — no other wiring needed

## License

MIT — see [LICENSE](LICENSE)