Smart Home MCP API

OAuth2 авторизация для MCP API

Для доступа к MCP REST API используйте обычный OAuth2 Authorization Code flow. Bearer token затем передаётся в Authorization: Bearer <access_token> при вызовах /api/v1/*.

1. Перенаправьте пользователя на /oauth/authorize?client_id=...&redirect_uri=...&response_type=code&scope=....
2. После подтверждения доступа обменяйте полученный code на токены через POST /oauth/token.
3. Используйте access_token как bearer для вызовов MCP API.
4. Когда access_token истечёт, обновите его через POST /oauth/token с grant_type=refresh_token.
5. Для отзыва текущего набора токенов вызовите POST /oauth/revoke с текущим bearer token.

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&redirect_uri=https://example.com/callback
&code=AUTHORIZATION_CODE

POST /oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=refresh_token
&refresh_token=REFRESH_TOKEN
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET

Доступные MCP scopes сейчас включают smarthome.profile.read, smarthome.structure.read, smarthome.scenes.manage, smarthome.schedules.manage и smarthome.mqtt.connect.

В ответах /api/v1/devices/* и списках устройств теперь есть блок mqtt и список exposes. Используйте mqtt.status_topic для чтения состояния устройства, mqtt.command_topic для publish-команд и exposes для понимания допустимых действий, MQTT payload keys, единиц измерения и допустимых диапазонов значений. Поле topic сохранено как совместимый alias для mqtt.status_topic.

Каждый expose может содержать блоки transport и normalized. Блок transport описывает реальные raw-значения MQTT payload (например, brightness 0..254), а normalized — человеко-понятные значения для UI (например, brightness 0..100%). Если driver-specific override отсутствует, transport будет null, а normalized заполнен из общих metadata.

Поля устройства в ответе API

Ниже — как использовать поля объекта устройства при интеграции (MQTT-агент, сценарии, дашборды).

• id, room_id — идентификаторы для ссылок в API и привязки к комнате/локации.
• type, title, description — тип шаблона устройства и отображаемое имя.
• custom_data — служебные данные интеграции: как минимум driver (zigbee2mqtt, amethyst, и т.д.) и идентификаторы для топика (friendly_name, при необходимости tag). От них зависят mqtt.* и наличие exposes.
• capabilities — что на устройстве настроено как «управляемое» (яркость, вкл/выкл и т.д.). Поле capability_function_name совпадает с exposes[].name для записей с kind: capability.
• properties — только чтение (датчики, статусы). property_function_name совпадает с exposes[].name при kind: property.
• topic — то же, что mqtt.status_topic (алиас для старых клиентов).
• mqtt.driver — какой бэкенд формирует топики и семантику payload.
• mqtt.status_topic — подписка на JSON-состояние устройства.
• mqtt.command_topic — публикация команд; обычно это status_topic + /set. Тело — JSON, ключи из capability-exposes (mqtt_keys).
• exposes — сводная «контрактная» карта: для каждой функции указаны MQTT-ключи, типы, при необходимости transport (как в брокере) и normalized (удобно для UI). Корневые value_range / enum_values — совместимый слой; при ненулевом transport для команд ориентируйтесь на transport.min/max/value_type.
• privileged, is_hidden — флаги доступа и видимости в интерфейсах.

Поток для агента: получить JWT через GET /api/v1/token → подключиться к MQTT → подписаться на status_topic → по exposes сопоставить ключи JSON с именами свойств → для управления публиковать в command_topic объект с ключами из mqtt_keys и значениями в шкале transport (если задана), иначе по value_range/enum.