MCP-сервер и skill для умного дома на SprutHub. Ставится в Claude Code, Codex, Grok, OpenClaw, Hermes, Pi или любой другой MCP-клиент. После установки агент читает дом, отвечает на вопросы про устройства и сценарии, по просьбе создаёт простые автоматизации на самом хабе и умеет откатывать свои изменения. Логин и пароль от SprutHub лежат в локальном файле и в чат не попадают.
Что можно спросить · Установка · Подключение дома · Что умеет · Как устроено · Разработка
- Какая температура в спальне?
- Что сейчас включено в доме?
- Какие сценарии трогают свет в коридоре и почему он включился ночью?
- Когда датчик движения в прихожей срабатывает, включай там свет.
- С 23:00 до 7:00 пусть свет в коридоре включается на 20 %, днём на полную.
- Сделай общий выключатель для трёх ламп в гостиной.
- Перенеси торшер в гостиную и переименуй его.
- Запомни, как сейчас настроен бризер, потом покажешь, что изменилось.
- Верни всё как было до последнего изменения.
Для чтения агент ничего не меняет. Изменение он сначала готовит и показывает, что именно будет записано, и только потом применяет; каждое записано локально и его можно вернуть. Созданные сценарии видны в интерфейсе SprutHub как обычные, их можно править руками.
Нужны Node.js 24.11 или новее и аккаунт SprutHub. Во всех вариантах ставится
один комплект: MCP-сервер sprut-agent и skill spruthub-master.
Проще всего дать агенту ссылку https://github.com/xor777/sprut-agent и
попросить: «Установи sprut-agent и подключи мой дом. Пароль в чат не
спрашивай». Ниже те же шаги для ручной установки.
claude plugin marketplace add xor777/sprut-agent
claude plugin install sprut-agent@sprut-agentНачни новый диалог. /mcp покажет сервер sprut-agent, skill доступен как
/sprut-agent:spruthub-master. Плагин использует путь своей установленной
копии, поэтому папка, из которой запущен диалог, не важна.
codex plugin marketplace add https://github.com/xor777/sprut-agent.git --ref main
codex plugin add sprut-agent@sprut-agentЕсли после этого сервер не появился, запусти проверку из установленной копии:
codex plugin add sprut-agent@sprut-agent --json печатает installedPath,
а node <installedPath>/check-install.mjs <installedPath> объясняет, что
мешает. Чаще всего это уже занятое имя MCP sprut-agent или отключённый
прежний ручной skill; проверка печатает точную команду для каждого случая.
grok plugin install xor777/sprut-agent#dist/plugin --trustgrok inspect покажет skill spruthub-master и MCP-сервер sprut-agent.
git clone https://github.com/xor777/sprut-agent.git ~/sprut-agent
openclaw mcp add sprut-agent --command node --arg "$HOME/sprut-agent/dist/plugin/dist/server.mjs"
openclaw skills install ~/sprut-agent/skills/spruthub-masterНачни новую сессию командой /new. Gateway запускает сервер сам, поэтому
node должен быть виден его процессу.
git clone https://github.com/xor777/sprut-agent.git ~/sprut-agent
hermes mcp add sprut-agent --command node --args "$HOME/sprut-agent/dist/plugin/dist/server.mjs"
hermes skills install xor777/sprut-agent/skills/spruthub-masterНачни новую сессию. Инструменты появятся как mcp__sprut_agent__….
У Pi нет встроенного MCP, его добавляет пакет pi-mcp-adapter. Он умеет
читать Claude-плагины, поэтому комплект подключается одной записью:
pi install npm:pi-mcp-adapter
git clone https://github.com/xor777/sprut-agent.git ~/sprut-agentВ ~/.pi/agent/mcp.json:
{
"claudePlugins": [
{ "path": "/полный/путь/sprut-agent/dist/plugin", "mcp": true, "skills": true }
],
"mcpServers": {}
}Перезапусти Pi. Инструменты sprut-agent вызываются через общий инструмент
mcp адаптера.
Склонируй репозиторий и укажи клиенту команду запуска сервера. Собранный
комплект в dist/plugin не требует npm install:
{
"mcpServers": {
"sprut-agent": {
"command": "node",
"args": ["/полный/путь/sprut-agent/dist/plugin/dist/server.mjs"]
}
}
}Если клиент понимает skills в формате SKILL.md, укажи ему папку
skills/spruthub-master.
Скажи агенту: «Подключи мой SprutHub». Пока реквизитов нет, сервер на любой
вызов отвечает точным путём к файлу и списком полей, агент передаст их тебе.
На macOS и Linux это ~/.config/sprut-agent/connection.env. Впиши туда логин
и пароль от аккаунта SprutHub:
SPRUTHUB_LOGIN=логин
SPRUTHUB_PASSWORD=парольФайл должен быть доступен только тебе (chmod 600). Начни новый диалог: MCP
перезапустится, войдёт в аккаунт и сохранит сессию рядом с файлом, поэтому
пароль больше не понадобится. Если в аккаунте несколько домов, агент попросит
выбрать один; выбор можно закрепить строкой SPRUTHUB_SERIAL=серийный_номер в
том же файле. Ошибка authentication_failed означает неверные реквизиты,
connection_failed означает, что облако SprutHub недоступно. В обоих случаях
достаточно поправить файл и начать новый диалог.
Дополнительные настройки в connection.env
SPRUTHUB_URLменяет адрес подключения; по умолчанию используется облако SprutHub.SPRUTHUB_TOKEN,SPRUTHUB_CIDиSPRUTHUB_URLвместе заменяют логин и пароль готовой сессией.SPRUTHUB_TIMEOUT_MSзадаёт время ожидания входа и обычного запроса, по умолчанию 10 секунд.- Те же переменные можно передать окружением процесса MCP; тогда и менять их
нужно там же. Если несколько домов и
SPRUTHUB_SERIALне задан, ответhome_selection_requiredсодержит точное значение для каждого дома и место, где его закрепить.
Файл с реквизитами, сессия и журнал изменений лежат вне кэша плагина и переживают переустановку.
| Область | Что делает агент |
|---|---|
| Чтение дома | Обзор дома и комнат, устройства с показаниями и единицами, сценарии и их связи с устройствами, настройки и журнал устройства, часы и пояс хаба |
| Размещение | Переименовать устройство, перенести его в другую комнату, создать недостающую комнату |
| Автоматизации | Правило «если A, то B» по двум переключаемым характеристикам; дневной и ночной режим по времени хаба; сохранённая команда сразу нескольким устройствам; назначение logic устройству; целевые температура и режим климата; временная пауза действия |
| Группа света | Виртуальная группа с общими включением и яркостью для нескольких ламп |
| Точки конфигурации | Запомнить текущие настройки выбранных устройств и правил, потом сравнить с тем, что стало |
| Возврат | Каждое изменение записано локально; агент возвращает прежнее состояние или удаляет то, что создал |
| Наблюдение | Временное наблюдение за событиями выбранных характеристик и журналом одного сценария |
| Своё приложение | Read-only API для Node.js: createSprutHubReader из dist/plugin/dist/read.mjs читает выбранные характеристики с единицами и свежестью |
Не поддерживаются сопряжение устройств, резервные копии хаба, GLOBAL-сценарии и произвольная запись вне опубликованного контракта.
Полный список операций, их поля и ограничения возврата описаны в контракте SprutHub. Как агент выбирает решение и разбирает сбои, описано в skill и порядке диагностики.
ИИ-агент → MCP по stdio → sprut-agent → JSON-RPC по WebSocket → облако SprutHub
Один пакет на Node.js, сервер запускается одним процессом. Агент начинает с
list_homes, берёт компактный обзор через inspect_home, находит устройства
через read_services и раскрывает детали выбранной сущности через
get_entity. Изменение проходит через get_native_change_contract,
prepare_native_change и apply_native_change; история и возврат доступны
через list_native_changes и restore_native_change. Ответы содержат
устойчивые ссылки, единицы, свежесть и признаки полноты; текст устройств и
сценариев агент считает данными, а не инструкциями.
Сценарии исполняются на хабе и остаются видимыми в его интерфейсе. Изменение протокола хаба может потребовать обновления клиента; датированные наблюдения лежат в research/protocol/.
| Документ | Содержание |
|---|---|
| DEVELOPMENT.md | Запуск из checkout, проверки, исследование протокола |
| AGENTS.md | Правила работы с кодом, тестами, ревью и Git |
| Продукт | Целевой опыт и архитектурные границы |
| Рабочая стратегия | Текущий шаг, приоритеты и условия пересмотра |
| SPRUT в Plan | Задачи, результаты, ревью и решения о приёмке |
MIT · Copyright (c) 2026 Dmitry Ukhanov.
sprut-agent — независимый проект интеграции со SprutHub.