# iiko-mcp

[![build](https://github.com/steamn/iiko-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/steamn/iiko-mcp/actions/workflows/ci.yml)
[![license: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](./LICENSE)

MCP-сервер для **ручной отладки запросов** к iikoTransport API
(`api-ru.iiko.services`). Подключается к любому MCP-клиенту (Cursor, Claude
Desktop, Claude Code) и даёт инструменты, чтобы дёргать эндпоинты iiko и смотреть
сырые ответы — со своими кредами.

> **EN:** An MCP server for debugging iikoTransport API requests. Bring your own
> credentials, plug it into any MCP client, and call iiko endpoints interactively.

Авторизация — **v2** (`POST /api/v2/access_token` с `apiKey/appId/clientSecret`,
JWT на 1 час, кэшируется в памяти). Старый `/api/1/access_token` отключается iiko.

## Быстрый старт

```bash
git clone https://github.com/steamn/iiko-mcp.git
cd iiko-mcp
npm install
npm run build
```

Дальше — задать креды (см. ниже) и подключить в MCP-клиенте.

## Креды

Получаются один раз:

1. Зарегистрируй приложение на портале разработчика iiko — https://public-api.iikoweb.ru/portal.
   Получишь `appId` и одноразовый `clientSecret`.
2. В iikoWeb → **Интеграции → API-ключи** сгенерируй API-ключ (`apiKey`).

| Переменная окружения | Значение |
|---|---|
| `IIKO_API_LOGIN` | `apiKey` из iikoWeb |
| `IIKO_APP_ID` | `appId` с портала разработчика |
| `IIKO_CLIENT_SECRET` | `clientSecret` с портала (показывается один раз) |
| `IIKO_BASE_URL` | необязательно, по умолчанию `https://api-ru.iiko.services` |
| `IIKO_TIMEOUT_MS` | необязательно, по умолчанию `30000` |

Есть два способа передать креды:

- **через MCP-клиент** — в блоке `env` конфига (примеры ниже);
- **через `.env`-файл** — скопируй `.env.example` в `.env`, заполни и запускай
  `node --env-file=.env dist/index.js`.

`.env` в `.gitignore` — секреты в репозиторий не попадут.

## Инструменты

| Инструмент | Назначение |
|---|---|
| **`iiko_request`** | Универсальный: любой метод + путь + тело, авто-авторизация → статус, correlationId, тело |
| `iiko_access_token` | Получить/обновить токен (для отладки авторизации) |
| `iiko_organizations` | `POST /api/1/organizations` |
| `iiko_nomenclature` | `POST /api/1/nomenclature` |
| `iiko_stop_lists` | `POST /api/1/stop_lists` |
| `iiko_deliveries_by_id` | `POST /api/1/deliveries/by_id` |

`iiko_request` — главный: им можно вызвать любой эндпоинт из
[документации iiko](https://api-ru.iiko.services/docs), даже если готового шортката нет.

## Подключение

### Cursor — `.cursor/mcp.json`

```json
{
  "mcpServers": {
    "iiko": {
      "command": "node",
      "args": ["/absolute/path/to/iiko-mcp/dist/index.js"],
      "env": {
        "IIKO_API_LOGIN": "your-api-key",
        "IIKO_APP_ID": "your-app-id",
        "IIKO_CLIENT_SECRET": "your-client-secret"
      }
    }
  }
}
```

### Claude Desktop — `claude_desktop_config.json`

Тот же блок `mcpServers`. После правки конфига перезапусти клиент — инструменты
`iiko_*` появятся в списке.

## Безопасность

- Никогда не коммить реальные `clientSecret`/`apiKey`. Держи их в `.env` (он в
  `.gitignore`) или в конфиге MCP-клиента вне репозитория.
- Если секрет утёк — перевыпусти его на портале разработчика, старый отзовётся.

## Разработка

```bash
npm run dev   # tsc --watch
```

PR и issue приветствуются.

## Лицензия

[MIT](./LICENSE) © steamn