SprutHubCTL

Высокоуровневая интеграция 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.

Related MCP server: MCP-HASS

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

Если вы используете AI-агента (Antigravity, Claude Code, Cursor, Cline):

Просто отправьте вашему ассистенту сообщение со ссылкой на репозиторий:

«Установи SprutHub из https://github.com/pikerr/spruthubctl. Мой хост: 192.168.1.100, локальный пароль: ВАШ_ПАРОЛЬ»

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

Установка вручную в терминале:

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)

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).

📖 Полная документация низкоуровневого протокола: 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:

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

(Также поддерживается указание домена, например "host": "spruthub.local" или полного WebSocket URL, если у вас нестандартный порт или реверс-прокси).

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

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

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

Ничего вручную копировать не нужно:

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 (с сохранением резервной копии старого конфига):

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:

{
  "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