SprutHub MCP Server

Высокоуровневый Model Context Protocol (MCP) сервер для управления умным домом SprutHub с помощью LLM-ассистентов (Antigravity, Claude Desktop, Cursor, Cline и др.).

Ключевые особенности

• ⚡ Прямой локальный WebSocket: прямое подключение к хабу в локальной сети (ws://<IP>/spruthub), нулевые задержки (< 5 мс), полная автономность без зависимости от внешнего облака.

• 🧠 Семантический фасад вместо сырого RPC: сервер берёт на себя нормализацию данных, фильтрацию служебного мусора и разрешение сервисов, предоставляя LLM простые и надежные инструменты для работы за 1 шаг.

• 🛡️ Автоматическая нормализация типов: автоматическая упаковка базовых типов (bool, int, float, str) в protobuf-подобные структуры SprutHub (boolValue, intValue и др.).

• 💡 Умное переключение (sprut_set_switch): вам не нужно знать точный service_id или characteristic_id реле — сервер автоматически найдёт целевую службу Switch/Lightbulb/Outlet.

• 🔒 Безопасная аутентификация: работа по сессионному токену без необходимости хранить постоянный пароль от аккаунта в открытом виде.

Архитектурный подход: Семантический фасад vs Generic RPC-шлюз

При интеграции SprutHub с большими языковыми моделями возможны два подхода:

1. Сырой generic-прокси (Raw RPC Gateway): когда все методы контроллера транслируются в MCP «как есть», а LLM сначала ищет метод через list_methods, затем запрашивает его схему и пытается вручную собрать сложный JSON-RPC payload.
   Недостатки: на каждое действие уходит 3–4 шага диалога, сотни килобайт сырых схем забивают контекст LLM, а сложная вложенность структур SprutHub приводит к частым галлюцинациям модели.

2. Семантический фасад (подход данного сервера): сервер агрегирует рутинную логику внутри себя. Он очищает списки устройств от сервисных метаданных (AccessoryInformation, Identify, C_Online), распаковывает типизированные структуры и предоставляет компактные, понятные функции.
   Результат: модель решает задачу пользователя за один шаг, не тратит лишние токены и работает стабильно даже на лёгких и быстрых моделях.

Предоставляемые инструменты (Tools)

Где взять токен (локальный пароль)?

Всё настраивается за 10 секунд прямо из веб-интерфейса SprutHub:

1. Токен / Локальный пароль (token):

   • В веб-интерфейсе (http://<IP_ХАБА>) перейдите в Настройки → Пользователи → откройте карточку вашего пользователя (Владелец).

   • Скопируйте значение из поля «Локальный пароль» (при необходимости можно сгенерировать новый кнопкой «Сгенерировать новый пароль»).

2. Серийный номер (serial — опционально):

   • Указывать не обязательно: сервер автоматически определяет подключенный хаб и его серийный номер через API.

   • Если у вас несколько хабов или вы хотите зафиксировать конкретный, серийник можно посмотреть в URL браузера: http://<IP_ХАБА>/hubs/<СЕРИЙНЫЙ_НОМЕР>/... либо в Настройки → Основные.

Конфигурация

Создайте файл config.json в корне проекта (на основе config.example.json):

{
  "ws_url": "ws://192.168.1.100/spruthub",
  "token": "ВАШ_ЛОКАЛЬНЫЙ_ПАРОЛЬ"
}

Также параметры можно передавать через переменные окружения:

• SPRUTHUB_WS_URL — WebSocket-адрес хаба (по умолчанию ws://127.0.0.1/spruthub)

• SPRUTHUB_TOKEN — локальный пароль (токен)

• SPRUTHUB_SERIAL — (опционально) серийный номер контроллера (если не указан, определяется автоматически)

Подключение к клиентам

Вариант 1. Запуск через uvx (Рекомендуется)

Если установлен менеджер пакетов uv:

{
  "mcpServers": {
    "spruthub": {
      "command": "uvx",
      "args": ["--from", ".", "spruthub-mcp"],
      "env": {
        "SPRUTHUB_WS_URL": "ws://192.168.1.100/spruthub",
        "SPRUTHUB_TOKEN": "ВАШ_ЛОКАЛЬНЫЙ_ПАРОЛЬ"
      }
    }
  }
}

Вариант 2. Запуск через локальный Python

{
  "mcpServers": {
    "spruthub": {
      "command": "python",
      "args": ["/путь/к/папке/spruthub-mcp/server.py"],
      "env": {
        "SPRUTHUB_WS_URL": "ws://192.168.1.100/spruthub",
        "SPRUTHUB_TOKEN": "ВАШ_ЛОКАЛЬНЫЙ_ПАРОЛЬ"
      }
    }
  }
}

Лицензия

MIT