alice-notify

Мост для управления умным домом Яндекса из кода и из LLM. Позволяет программно: озвучивать произвольный текст на колонках с Алисой (TTS), ставить напоминания пачками, управлять устройствами и полностью работать со сценариями (создавать / читать / изменять / удалять / запускать). Доступно тремя способами: MCP-сервер (для нейросетей/Claude), REST API (FastAPI) и CLI-скрипты.

⚠️ Проект использует неофициальный внутренний API Яндекса (iot.quasar.yandex.ru) — тот же, что и приложение «Дом с Алисой». Это серая зона относительно ToS Яндекса, интерфейс может измениться без предупреждения. Проект не аффилирован с Яндексом. Используйте на свой риск, только со своим аккаунтом.

Возможности

• TTS — Алиса произносит любой переданный текст на выбранной колонке. Отправляется прямой командой phrase_action (до ~550 символов на фразу); длинный текст автоматически режется на части и читается подряд.

• Напоминания пачками (гибрид):

  • на конкретные даты → нативные напоминания Алисы (голосовая команда, привязка к дате);

  • повторяющиеся по дням недели → беззвучный сценарий с TTS по расписанию.

• Устройства — список и управление умениями (свет, розетки, климат). Цвет ламп — через палитру Яндекса (именованные id: red, cold_white, …); есть высокоуровневые тулы для цвета.

• Сценарии — полный CRUD: список, чтение, создание, изменение, удаление, запуск.

• Гео-ассистент по Яндекс.Картам (через ту же сессию):

  • поиск мест рядом с рейтингами — по запросу («кофейня», «раковарня»), центр по координатам ИЛИ по адресу/названию (геокодинг); фильтры: радиус, минимальный рейтинг, «открыто сейчас»; результат отсортирован по близости;

  • атрибуты места — рейтинг и число отзывов, открыто ли сейчас и часы работы, категории, адрес, расстояние, телефон, сайт, features (Wi-Fi, кухня, доставка…);

  • отзывы + саммари — тональность по аспектам и тексты отзывов для вывода «стоит ли идти»;

  • ссылки — карточка места (по oid) и маршрут-deeplink (по координатам);

  • «Мои места» — чтение списков/категорий пользователя и добавление места в нужный список.

  • Поиск обходит анти-бот Карт через встроенный headless-браузер (см. ниже).

• Три интерфейса поверх одного ядра: MCP (stdio и удалённый HTTP с авторизацией), FastAPI, CLI.

Related MCP server: yandex-station-mcp

Как это устроено

• Бэкенд — неофициальный API https://iot.quasar.yandex.ru/m. Авторизация по x-token (долгоживущий токен Яндекса), из него выводятся cookie-сессии и x-csrf-token; сессия кэшируется и автоматически обновляется.

• TTS/команды — прямой device-action quasar.server_action на колонку: phrase_action (озвучка, лимит ~550) и text_action (голосовая команда, лимит 100). Длинный текст режется на несколько фраз подряд с паузой, чтобы не накладывались.

• Цвет ламп — только через палитру (color_setting, instance color, id строкой); hsv/rgb/scene/temperature_k облако не принимает (400).

• Ядро — QuasarClient (src/alice_notify/quasar/), над ним тонкие обёртки: mcp_server.py (stdio), mcp_remote.py (HTTP + bearer-auth), api/app.py (FastAPI).

Требования

• Python 3.11+

• Аккаунт Яндекса с привязанными к «Дому с Алисой» устройствами (колонка с Алисой).

• Для удалённого MCP: Docker + (желательно) реверс-прокси с HTTPS.

Быстрый старт (локально)

python -m venv .venv
# Windows: .venv\Scripts\Activate.ps1   |   Linux/macOS: source .venv/bin/activate
pip install -e ".[all]"

cp .env.example .env     # заполнить по ходу (см. ниже)

1. Авторизация (x-token по QR, один раз)

python scripts/get_token.py

Скрипт покажет QR-код — отсканируйте приложением Яндекс и подтвердите вход. Пароль нигде не вводится. Полученный x-token скрипт запишет в .env (YANDEX_X_TOKEN). Сессия кэшируется в .session.json и обновляется автоматически.

2. Найти устройства

python scripts/discover.py

Выведет устройства, сценарии и подскажет STATION_DEVICE_ID (колонка по умолчанию) — впишите его в .env.

3. Проверить озвучку

python scripts/say_probe.py "Привет из alice-notify"

MCP-сервер

Локально (stdio, для Claude Code):

claude mcp add alice-notify -- python -m alice_notify.mcp_server

Удалённо (HTTP + пароль), см. раздел «Docker-деплой».

Для LLM/агента: быстрый старт

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

• Локально (stdio): claude mcp add alice-notify -- python -m alice_notify.mcp_server

• Удалённо (HTTP): claude mcp add --transport http alice --header "Authorization: Bearer <MCP_AUTH_TOKEN>" https://<host>/mcp

После добавления перезапусти/переподключи клиент, чтобы подтянулись инструменты alice_*. Сервер отдаёт подробную памятку в своём instructions — прочитай её первой.

Ключевые правила (частые ошибки агентов):

• Цвет ламп — только палитрой: alice_set_light_color(device_id, color_id) (id из alice_list_colors / alice_get_light_colors). НЕ используй hsv/rgb/scene/temperature_k.

• Лимиты текста: команда/напоминание ≤100 символов; alice_say длинный текст режет сам (~550/фраза).

• Гео-поиск: «найди X рядом» → alice_find_places_rated(text, lat+lon | near, radius_m?, min_rating?, open_now?) (сортировка по близости, с рейтингами/атрибутами). Открыть место → его map_url; маршрут → его lat/lon в alice_build_route (НЕ по названию!); «стоит ли идти» → alice_place_details(oid).

• «Мои места»: сперва alice_my_lists(oid) (увидеть категории), затем alice_add_place_to_list(oid, list_name) (идемпотентно, не удаляет).

• Проверка эффекта: status:"ok" не всегда значит «сделано»; где в ответе есть action_result.status — убедись, что там "DONE".

Инструменты: alice_say, alice_command, alice_set_date_reminders, alice_set_recurring_reminder, alice_list_devices, alice_device_action, alice_list_colors, alice_get_light_colors, alice_set_light_color, alice_set_lights, alice_list_scenarios, alice_get_scenario, alice_create_scenario, alice_update_scenario, alice_delete_scenario, alice_run_scenario, alice_find_places, alice_find_places_rated, alice_place_details, alice_place_url, alice_build_route, alice_my_lists, alice_add_place_to_list.

Гео-тулы:

• alice_find_places_rated(text, lat+lon | near, radius_m?, min_rating?, open_now?) — главный поиск: места рядом с рейтингами и атрибутами (открыто ли, часы, features, тональность отзывов), центр по координатам или адресу, фильтры, сортировка по близости. Через headless-браузер (обходит анти-бот Карт: сам считает подпись s).

• alice_find_places(text, lat, lon) — быстрые подсказки (без браузера, без рейтингов).

• alice_place_details(oid) — отзывы места: аспекты/тональность + тексты («стоит ли идти»).

• alice_place_url(oid) — ссылка на карточку места; alice_build_route(points, mode) — маршрут-deeplink.

• alice_my_lists(oid) / alice_add_place_to_list(oid, list_name) — «Мои места»: списки и добавление.

alice_find_places_rated требует Chromium в образе (extra geo + playwright install --with-deps chromium, см. Dockerfile). Первый вызов поднимает браузер (~10–20 c), далее переиспользуется. Медленнее и тяжелее обычного поиска, но даёт рейтинги.

REST API (FastAPI)

uvicorn alice_notify.api.app:app --port 8000
curl -X POST localhost:8000/say \
  -H "Authorization: Bearer $API_AUTH_TOKEN" -H "Content-Type: application/json" \
  -d '{"text":"проверка"}'

Эндпоинты: POST /say, POST /command, POST /reminders/dates, POST /reminders/recurring, GET /devices, POST /devices/{id}/action, GET|POST /scenarios, GET|PUT|DELETE /scenarios/{id}, POST /scenarios/{id}/run, GET /health.

Гео (для приложений): POST /geo/find_rated {text, lat/lon | near, radius_m?, min_rating?, open_now?} → места с рейтингами/атрибутами/тональностью отзывов, сортировка по близости; POST /geo/find (быстрые подсказки); POST /geo/route {points, mode}; GET /geo/place/{oid} (отзывы/тональность/тексты); GET /geo/place_url/{oid}; GET /geo/lists?oid=… и POST /geo/lists/add («Мои места»: списки и добавление). В деплое REST поднят отдельным сервисом alice-api (порт 8000). Swagger: /docs, /openapi.json.

«Мои места» работают через залогиненный (куки из x-token) headless-браузер: get_lists читает названия списков, add_place_to_list добавляет место в список (идемпотентно — не удаляет).

Docker-деплой (удалённый MCP с авторизацией)

mcp_remote.py поднимает MCP по HTTP (streamable-http) и требует общий пароль: каждый клиент шлёт заголовок Authorization: Bearer <MCP_AUTH_TOKEN>, без него — 401.

# 1. Заполнить .env: YANDEX_X_TOKEN, STATION_DEVICE_ID, MCP_AUTH_TOKEN (длинная случайная строка)
# 2. Собрать и запустить
docker compose up -d --build

Сервис слушает порт 8848 (том ./data хранит кэш сессии). Подключение клиента:

claude mcp add --transport http alice --header "Authorization: Bearer <MCP_AUTH_TOKEN>" \
  https://<your-host>/mcp

HTTPS обязателен при выставлении наружу — иначе пароль идёт открытым текстом. Поставьте перед контейнером реверс-прокси с TLS (Caddy / nginx / Nginx Proxy Manager). Для потоковых ответов (SSE) на прокси отключите буферизацию, например для nginx:

proxy_buffering off;
proxy_read_timeout 3600s;
proxy_http_version 1.1;

Переменные окружения (.env)

Ограничения и безопасность

• Лимиты длины: озвучка (alice_say) — ~550 символов на фразу, длинный текст режется сам; команды (alice_command) и напоминания — 100 символов (валидируются с понятной ошибкой).

• Цвет — только палитрой (instance=color, id строкой); hsv/rgb/scene/temperature_k облако не принимает (400). Палитра у ламп разная — точную даёт alice_get_light_colors.

• Пакетные напоминания на даты Алиса вслух подтверждает на каждое.

• Секреты (.env, .session.json) — в .gitignore, не коммитить. При утечке x-token выйдите из устройств в настройках Яндекс ID (это отзовёт токен).

• Неофициальный API может измениться; форматы ответов не гарантированы.

Структура

src/alice_notify/
  config.py            # настройки (.env, pydantic-settings)
  quasar/auth.py       # x-token → cookie → csrf, кэш сессии
  quasar/client.py     # QuasarClient: устройства, TTS/чанкинг, сценарии, будильники
  reminders.py         # напоминания пачками (гибрид)
  service.py           # общий клиент + представление устройств
  mcp_server.py        # MCP через stdio
  mcp_remote.py        # MCP через HTTP + bearer-auth (для Docker)
  api/app.py           # FastAPI
scripts/               # get_token, discover, say_probe, alarms_probe, scenario_dump
Dockerfile, docker-compose.yml

Благодарности

Механику неофициального API (авторизация по x-token, работа с колонкой и сценариями) удалось разобрать благодаря открытым проектам сообщества, в частности AlexxIT/YandexStation.

Лицензия

Добавьте по своему усмотрению (например, MIT). Использование неофициального API — на ваш риск.