# SprutHubCTL

[![MIT License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](pyproject.toml)

Высокоуровневая интеграция **SprutHub** для LLM-ассистентов (Antigravity, Claude Desktop, Cursor, Claude Code, Cline и др.) и системных администраторов.

Предоставляет два формата работы в одном пакете:
1. **On-Demand CLI (`spruthubctl` / `sprut`) + Skill** — ультралегковесный запуск по требованию для терминала и AI-агентов (Antigravity, Claude Code) с нулевым оверхедом по RAM и контекстному окну (~80 мс на запрос, 0 байт RAM в простое).
2. **MCP Server (`spruthub-mcp`)** — стандартный сервер Model Context Protocol (для клиентов без доступа к терминалу, например Claude Desktop).

---

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

* ⚡ **Прямой локальный WebSocket:** прямое подключение к хабу в локальной сети (`ws://<IP>/spruthub`), нулевые задержки (< 5 мс), полная автономность без зависимости от облака.
* 🧠 **Семантический фасад вместо сырого RPC:** сервер берет на себя нормализацию данных, фильтрацию служебного мусора и разрешение сервисов, позволяя LLM работать за 1 шаг.
* 🛡️ **Автоматическая нормализация типов:** упаковка базовых типов (`bool`, `int`, `float`, `str`) в структуры SprutHub (`boolValue`, `intValue` и др.).
* 💡 **Умное переключение (`switch`):** вам не нужно знать точный `service_id` или `characteristic_id` реле — система автоматически найдёт целевую службу `Switch`/`Lightbulb`/`Outlet`.
* 🔒 **Безопасная аутентификация:** работа по локальному паролю (токену) без необходимости хранить мастер-пароль от аккаунта.
* 🚀 **Нулевой оверхед (Hybrid Architecture):** поддержка работы как в виде фонового MCP-сервера, так и через легковесный CLI.

---

## ⚡ Быстрая установка (Prompt-ready)

### Если вы используете AI-агента (Antigravity, Claude Code, Cursor, Cline):
Просто отправьте вашему ассистенту сообщение со ссылкой на репозиторий:
> «Установи SprutHub из https://github.com/pikerr/spruthubctl. Мой хост: `192.168.1.100`, локальный пароль: `ВАШ_ПАРОЛЬ`»

Агент прочитает [AGENTS.md](AGENTS.md) и выполнит всё сам за один шаг.

### Установка вручную в терминале:
```bash
uvx --from git+https://github.com/pikerr/spruthubctl spruthubctl install --host 192.168.1.100 --token ВАШ_ПАРОЛЬ
```
*(Для регистрации MCP-сервера в Claude Desktop / Cursor добавьте флаг `--mcp`)*.

Команда автоматически:
1. Сохраняет конфигурацию в `~/.config/spruthubctl/config.json` (chmod 600).
2. Устанавливает готовый Agent Skill в директории `~/.gemini/` и `~/.claude/`.
3. Проверяет связь с вашим контроллером SprutHub.

---

## Архитектура: Двойной интерфейс (CLI + MCP)

```mermaid
flowchart TD
    subgraph Clients["Клиенты и Ассистенты"]
        Claude["Claude Desktop / Cursor<br/>(клиенты без терминала)"]
        Terminal["Antigravity / Claude Code / Терминал<br/>(on-demand агенты)"]
    end

    subgraph Package["Пакет spruthubctl"]
        CLI["CLI & Skill (cli.py)<br/>spruthubctl / sprut<br/>On-Demand (80ms, 0 RAM)"]
        MCP["MCP Server (server.py)<br/>spruthub-mcp<br/>Stdio JSON-RPC daemon"]
        Core["SprutHubClient<br/>Семантический фасад & нормализация типов"]
    end

    Hub[("SprutHub Controller<br/>ws://IP/spruthub")]

    Terminal -->|uvx / CLI| CLI
    Claude -->|MCP Protocol| MCP
    CLI --> Core
    MCP --> Core
    Core -->|Локальный WebSocket| Hub
```

---

## Инструменты и команды

*(Команда `spruthubctl` также доступна по короткому алиасу `sprut` и совместимому `spruthub-cli`)*.

| Категория | Команда CLI | MCP Tool | Описание |
|---|---|---|---|
| **Хаб и система** | `spruthubctl summary` | `sprut_get_summary` | Комплексная сводка: статус хаба, аккаунт, комнаты с устройствами, расширения, статистика. |
| | `spruthubctl info` | `sprut_get_hub_info` | Краткая информация о контроллере (имя, модель, серийник, версия ПО, онлайн-статус). |
| | `spruthubctl restart [--yes]` | `sprut_restart_hub` | Перезагрузка контроллера / службы SprutHub. |
| **Комнаты** | `spruthubctl rooms` | `sprut_list_rooms` | Список комнат со сводкой датчиков в реальном времени. |
| | `spruthubctl room create <name>` | `sprut_create_room` | Создание новой комнаты. |
| | `spruthubctl room rename <id> <name>` | `sprut_update_room` | Переименование существующей комнаты. |
| | `spruthubctl room delete <id> [--yes]`| `sprut_delete_room` | Удаление комнаты (с подтверждением). |
| **Устройства** | `spruthubctl devices [--room ID] [-s query]` | `sprut_list_devices` | Список устройств и их текущих состояний (с фильтрацией). |
| | `spruthubctl device <ID>` | `sprut_get_device` | Полная развернутая структура аксессуара (сервисы, характеристики, метаданные). |
| | `spruthubctl switch <ID> <on/off>` | `sprut_set_switch` | Быстрое включение/выключение любого реле, выключателя, розетки или лампы. |
| | `spruthubctl set <aId> <sId> <cId> <val>` | `sprut_set_characteristic` | Установка любого значения характеристики (яркость, температура, режим). |
| **История и датчики** | `spruthubctl history <ID> [char] [--days N]` | `sprut_get_history` | Выгрузка временных рядов, расчет аналитики (min/max/avg/delta) и дневных сводок. |
| **Сценарии** | `spruthubctl scenarios [-s query]` | `sprut_list_scenarios` | Список настроенных сценариев автоматизации и их статус. |
| | `spruthubctl scenario run <name_or_idx>` | `sprut_run_scenario` | Запуск сценария автоматизации по имени или индексу. |
| **Диагностика** | `spruthubctl logs [--count N] [--level LVL]` | `sprut_get_logs` | Просмотр системных логов контроллера и ошибок драйверов. |
| | `spruthubctl extensions` | `sprut_list_extensions` | Статус всех протокольных расширений (Zigbee, BLE, HomeKit, MQTT и др.). |
| **Каталог шаблонов**| `spruthubctl catalog list [-s query]` | `sprut_list_catalog` | Поиск и просмотр шаблонов поддерживаемых устройств в каталоге. |
| | `spruthubctl catalog get <model_or_file>` | `sprut_get_catalog_template` | Получение схемы и маппинга сервисов конкретного шаблона оборудования. |

> 📖 **Полная документация низкоуровневого протокола:** [docs/SPRUTHUB_API.md](docs/SPRUTHUB_API.md) — карта всех 18 модулей и 62 RPC-методов ядра SprutHub.

---

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

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

1. В браузере откройте веб-интерфейс хаба (`http://<IP_ХАБА>`).
2. Перейдите в **Настройки** → **Пользователи** → откройте карточку вашего пользователя (Владелец).
3. Скопируйте значение из поля **«Локальный пароль»** (при необходимости можно сгенерировать новый кнопкой *«Сгенерировать новый пароль»*).

---

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

Для работы требуется всего два параметра: **IP-адрес (или хост) хаба** и **локальный пароль**.

Конфигурация автоматически определяется по цепочке:
1. Переменные окружения (`SPRUTHUBCTL_HOST` / `SPRUTHUB_HOST` и `SPRUTHUBCTL_TOKEN` / `SPRUTHUB_TOKEN`).
2. Системный файл конфигурации:
   * Linux / macOS: `~/.config/spruthubctl/config.json` (или `~/.config/spruthub/config.json`)
   * Windows: `%APPDATA%\spruthubctl\config.json` (или `%APPDATA%\spruthub\config.json`)
3. Локальный файл `./config.json` в рабочей директории.

Пример `config.json`:
```json
{
  "host": "192.168.1.100",
  "token": "ВАШ_ЛОКАЛЬНЫЙ_ПАРОЛЬ"
}
```
*(Также поддерживается указание домена, например `"host": "spruthub.local"` или полного WebSocket URL, если у вас нестандартный порт или реверс-прокси).*

---

## Варианты использования

### Режим 1: Skill для Antigravity / Claude Code (Рекомендуется)

Идеальный режим: **0 байт RAM в простое, 0 лишних токенов в контексте**.

Ничего вручную копировать не нужно:
```bash
uvx --from git+https://github.com/pikerr/spruthubctl spruthubctl install --host 192.168.1.100 --token ВАШ_ПАРОЛЬ
```
Команда автоматически:
1. Сохранит данные в `~/.config/spruthubctl/config.json` с правами доступа `600`.
2. Установит скилл в `~/.gemini/config/skills/spruthub/` (и `~/.claude/skills/`).
3. Проверит соединение с вашим хабом.

После этого агент готов к управлению («выключи свет в спальне», «какая температура в кабинете»).

---

### Режим 2: MCP Server (для Claude Desktop / Cursor)

#### Автоматическая регистрация (Рекомендуется):
Одной командой зарегистрирует сервер в Claude Desktop и/или Cursor (с сохранением резервной копии старого конфига):
```bash
uvx --from git+https://github.com/pikerr/spruthubctl spruthubctl install-mcp --host 192.168.1.100 --token ВАШ_ПАРОЛЬ
```
*(Либо передайте флаг `--mcp` при первой установке: `spruthubctl install --mcp`, и утилита настроит и Skill, и Claude Desktop сразу)*.

#### Ручная настройка:
Если вы предпочитаете прописать конфиг вручную в `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "spruthub": {
      "command": "uvx",
      "args": ["--from", "git+https://github.com/pikerr/spruthubctl[mcp]", "spruthub-mcp"],
      "env": {
        "SPRUTHUB_HOST": "192.168.1.100",
        "SPRUTHUB_TOKEN": "ВАШ_ЛОКАЛЬНЫЙ_ПАРОЛЬ"
      }
    }
  }
}
```

---

## Лицензия

[MIT](LICENSE)