# kronos-mcp

MCP-сервер для **Кронос 2.0** — российской системы онлайн-записи и управления расписанием
(вендор ООО «Генезис», [crns.io](https://crns.io)), которая работает как приложение внутри amoCRM.

Даёт языковой модели прямой доступ к бронированиям: свободные слоты, ресурсы, услуги,
создание и перенос записей, привязка сделки amoCRM к брони, подписка на вебхуки.

> **In short:** an MCP server for Kronos 2.0, a Russian booking/scheduling SaaS used by quest
> rooms, kids' entertainment venues and similar businesses. 13 tools over its Public API v1.

---

## Зачем

Кронос закрывает расписание и брони, но его API не самый очевидный: документации в публичном
поиске нет, ключ выдают по запросу, а половина важных деталей не описана в спецификации вовсе.
Этот сервер убирает эту возню — модель просто вызывает инструменты с понятными именами и
получает данные, а все заголовки, обязательные параметры и обработка ошибок уже внутри.

Подойдёт, если вы делаете бота-администратора, ассистента для менеджеров или любую
автоматизацию поверх записи клиентов.

## Установка

```bash
git clone https://github.com/RealSatanyan/kronos-mcp.git
cd kronos-mcp
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
```

Нужен Python 3.10+.

## Настройка

Ключ API запрашивается у вендора — он не выдаётся самообслуживанием:
[t.me/gnzs_bot](https://t.me/gnzs_bot), hello@gnzs.ru.

```bash
cp .env.example .env   # для локального запуска
```

| Переменная | Обязательна | Что это |
|---|---|---|
| `KRONOS_API_KEY` | да | Ключ от вендора, уходит в заголовке `X-API-KEY` |
| `KRONOS_BASE_URL` | нет | По умолчанию `https://genezis-platform-api.gnzs.ru` |
| `KRONOS_DEFAULT_FILIAL_ID` | нет | Филиал по умолчанию. В сети из нескольких площадок лучше не задавать — см. ниже |

Подключение к MCP-клиенту (Claude Code, Claude Desktop, Cursor):

```json
{
  "mcpServers": {
    "kronos": {
      "command": "/путь/до/kronos-mcp/.venv/bin/kronos-mcp",
      "env": { "KRONOS_API_KEY": "ваш-ключ" }
    }
  }
}
```

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

Все требуют `filial_id` — Кронос привязывает каждый запрос к конкретному филиалу.

**Чтение**

| Инструмент | Что делает |
|---|---|
| `kronos_get_available_slots` | Свободные слоты — то, что показывают клиенту |
| `kronos_get_time_slots` | Все слоты, включая занятые |
| `kronos_get_time_slots_by_resource_type` | Слоты по типу ресурса, а не по конкретному |
| `kronos_list_resources` | Ресурсы филиала (залы, аниматоры и т.п.) |
| `kronos_list_services` | Услуги и товары филиала |
| `kronos_get_event` | Одна запись по id |
| `kronos_list_events` | Список записей с фильтрами и пагинацией |
| `kronos_get_custom_fields` | Кастомные поля, заведённые в аккаунте |

**Изменение**

| Инструмент | Что делает |
|---|---|
| `kronos_create_event` | Создать запись: обычную, групповое событие или дочернюю запись в группу |
| `kronos_update_event` | Перенести, отменить (`status_id=0`) или поправить кастомные поля |
| `kronos_delete_event` | Удалить безвозвратно — обычно лучше отмена через `update` |
| `kronos_bind_lead` | Связать сделку amoCRM с бронью |
| `kronos_subscribe_webhook` | Подписаться на `create_event` / `update_event` / `delete_event` |

## Что стоит знать про API Кроноса

Это то, что выяснилось на практике и чего нет в спецификации — ради этих абзацев репозиторий
и стоит читать:

- **`filial_id` обязателен везде.** Поэтому он сделан обязательным параметром, а не берётся
  из настроек молча: перепутанный филиал — это чужие цены и чужой адрес в ответе клиенту.
- **Платёжных методов в API нет вообще.** Встроенный модуль «Платежи» живёт в интерфейсе
  Кроноса внутри amoCRM и здесь недоступен. Приём денег придётся делать отдельным слоем, а
  результат записывать в бронь через `kronos_update_event`.
- **Минимальный размер группы Кронос не знает.** У группового события есть только `max_count` —
  верхняя граница. Правило «не меньше N человек» проверяет ваш код, не API.
- **Форматы ответов не описаны.** В спецификации вендора у всех эндпоинтов пустые схемы ответов,
  поэтому инструменты возвращают JSON как есть.
- **Отмена лучше удаления.** `kronos_update_event` со `status_id=0` сохраняет историю, а
  `kronos_delete_event` стирает запись совсем. Есть и причины отказа: `loss_reason_id` 1 —
  нет оплаты, 2 — не пришёл.
- **Групповые события трёхуровневые.** Родительское событие (`is_group=true`) — это сам сеанс,
  дочерние записи цепляются к нему через `parent_id` и несут своих клиентов и свой заказ.

## Статус

Написан по реальной OpenAPI-спецификации вендора (зеркало — [`reference/openapi.json`](reference/openapi.json)),
покрывает все 13 операций Public API v1. Структурно проверен: сервер поднимается, инструменты
регистрируются, ошибки долетают читаемым текстом.

Против живого аккаунта **не тестировался** — на момент публикации у автора не было выданного
ключа. Если протестируете, issue и PR приветствуются: особенно интересны реальные формы ответов
и поведение групповых событий.

## Лицензия

MIT