Home Assistant Admin MCP

Сервер Model Context Protocol (MCP), ориентированный на безопасность, для проверки, управления, диагностики и выборочного администрирования экземпляра Home Assistant. Он объединяет REST и WebSocket API Home Assistant с опциональным, ограниченным монтированием конфигурации Home Assistant.

Сервер не включает LLM. Клиент MCP выбирает инструменты; этот сервер проверяет входные данные, обеспечивает соблюдение политики развертывания, взаимодействует с Home Assistant и возвращает структурированные результаты.

[!NOTE] Этот проект создан с использованием инструментов разработки с поддержкой ИИ.

[!WARNING] Режим admin может изменять устройства, реестры, помощников, автоматизации, сценарии, сцены, интеграции и YAML-конфигурацию, а также перезапускать Home Assistant. Начинайте в режиме read_only, используйте выделенную учетную запись Home Assistant, проверяйте пробные запуски и предоставляйте доступ к HTTP-конечной точке только доверенным клиентам.

Область применения и границы

Реализованные возможности включают:

• Проверка состояния выполнения, сервисов/действий, событий, истории, журнала, статистики и журнала текущей сессии с сокращенным резервным вариантом system_log.

• Обнаружение реестров и интеграций с перекрестными ссылками на зоны, устройства, объекты и записи конфигурации.

• Проверенные вызовы сервисов с явными целями и актуальными определениями сервисов Home Assistant.

• Чтение и изменение автоматизаций, сценариев и сцен, управляемых редактором.

• Изменения помощников на основе хранилища и выбранных записей реестра/конфигурации через внутренние API Home Assistant.

• Диагностика, анализ зависимостей, поиск по реестрам/ресурсам редактора/разрешенному YAML, трассировки, различия конфигурации, контрольные точки и ограниченная история Git.

• Структурные исправления YAML в рамках явного списка разрешенных файловых систем.

Явные нецели и ограничения:

• Нет API Supervisor Home Assistant, управления дополнениями, управления хостом или API резервного копирования Home Assistant.

• Нет Docker API, Docker-сокета, жизненного цикла контейнеров, управления образами или доступа к журналам контейнеров. Развертывание не монтирует /var/run/docker.sock.

• Нет произвольного выполнения команд оболочки или произвольного доступа к файловой системе.

• Нет общей реализации config-flow/options-flow и нет механизма отправки произвольных учетных данных интеграции. Инструменты интеграции только читают записи конфигурации, изменяют реализованные настройки, включают/отключают или запрашивают перезагрузку.

• Нет предположения, что каждый пользователь Home Assistant может вызывать любую конечную точку. Долгоживущий токен наследует разрешения и статус администратора своего пользователя Home Assistant.

Related MCP server: hass-mcp-server

Архитектура

flowchart LR
    Client["MCP client"] -->|"Streamable HTTP + MCP bearer token"| HTTP["HTTP transport /mcp"]
    Client -->|"stdio"| Stdio["stdio transport"]
    HTTP --> Policy["MCP tools, schemas, mode, risk and confirmation policy"]
    Stdio --> Policy
    Policy --> REST["Home Assistant REST client"]
    Policy --> WS["Home Assistant WebSocket client"]
    REST --> HA["Home Assistant Core"]
    WS --> HA
    Policy --> TX["Filesystem transaction layer"]
    TX --> Mount["/ha-config allowlisted read-write mount"]
    TX --> Checkpoints[".ha-mcp/backups"]
    TX --> Git["Optional local Git commits"]
    TX -->|"check config, reload, health"| REST
    NoDocker["No Supervisor or Docker socket access"]

HTTP-транспорт не имеет состояния на уровне обработчика MCP. Процесс приложения по-прежнему разделяет свое соединение/кэш Home Assistant и сериализует транзакции файловой системы.

Матрица API Home Assistant

Проверено 2026-08-20 по текущей документации Home Assistant и исходникам home-assistant/core ветки dev. Ссылка на исходник показывает, что внутренняя команда в настоящее время существует; это не гарантия стабильности.

API Home Assistant требует Authorization: Bearer <HA token>. См. официальный authentication API. HTTP-конечная точка MCP имеет отдельный bearer-токен.

Совместимость внутренних API

• Внутренние конечные точки могут быть переименованы, ограничены или иметь изменённые схемы без периода устаревания публичного API. Перед включением admin в производственной среде тестируйте работу с точной версией Home Assistant.

• Операции с реестром, помощниками, трассировкой, системным здоровьем, WebSocket logbook, метаданными recorder, config-entry и редактором могут возвращать HA_WS_UNSUPPORTED, HA_INTERNAL_API_UNAVAILABLE, HELPER_STORAGE_API_UNAVAILABLE, ошибки разрешений или ошибки проверки ответов на несовместимых версиях.

• Текущее ядро Home Assistant помечает многие мутации реестра и чтения трассировки как доступные только администратору. Используйте токен, принадлежащий администратору, когда требуются эти инструменты; токен не-администратора может подойти для развёртывания только с чтением/управлением, если разрешений Home Assistant достаточно.

• Мутации редактора ограничены ресурсами automations.yaml, scripts.yaml и scenes.yaml, управляемыми редактором. Запущенный YAML-ресурс без пригодного идентификатора редактора сообщается как недоступный для редактирования.

• Поддерживаемые помощники: input_boolean, input_button, input_text, input_number, input_datetime, input_select, counter, timer и schedule. Их принимаемые поля определяются установленной версией Home Assistant.

• Операции config-entry не запускают config flows, options flows, повторную аутентификацию, ремонт, OAuth или ввод учётных данных. Для этих операций используйте интерфейс Home Assistant.

• Просмотры dry-run для помощников, реестров, областей, устройств, сущностей и config-entry не вызывают валидаторы мутаций Home Assistant. Их результат включает ограничения, описывающие этот факт.

Производственное развёртывание

Предварительные требования

• Docker Engine с Compose v2 и BuildKit.

• Доступный экземпляр Home Assistant Core с включённым API. Обычно его предоставляет фронтенд Home Assistant; установкам только с API нужна интеграция api.

• Долгоживущий токен доступа Home Assistant.

• Путь на хосте, содержащий конфигурацию Home Assistant, если нужны функции файловой системы, контрольных точек, безопасности мутаций редактора или Git.

• Права владельца/доступа на хосте, позволяющие настроенному не-root UID/GID читать и записывать этот путь.

Релизы GitHub публикуют многоплатформенные образы в docker.io/lemanjo/hac-mcp. Для воспроизводимых развёртываний используйте точный тег релиза, а не latest. Локальные сборки по-прежнему поддерживаются.

Создание токена Home Assistant

1. Войдите в Home Assistant как пользователь, от имени которого должен действовать этот сервис.

2. Откройте Профиль пользователя, затем вкладку Безопасность.

3. В разделе Долгоживущие токены доступа выберите Создать токен и назовите его для этого развёртывания.

4. Запишите токен при отображении; Home Assistant не сохраняет строку токена для последующего показа.

5. Используйте учётную запись администратора только тогда, когда требуются внутренние инструменты администратора.

Home Assistant документирует управление профилем здесь и долгоживущие токены здесь. Долгоживущие токены — это ценные учётные данные, которые не следует коммитить, помещать в config.example.yaml или раскрывать MCP-клиенту.

Настройка Compose

cp .env.example .env
cp config.example.yaml config.yaml
install -d -m 700 secrets
openssl rand -hex 32 > secrets/mcp_auth_token
read -rsp "Home Assistant token: " HA_TOKEN
printf '%s' "$HA_TOKEN" > secrets/home_assistant_token
unset HA_TOKEN
chmod 600 secrets/home_assistant_token secrets/mcp_auth_token

Задайте эти значения в .env:

• HOME_ASSISTANT_URL: доступен из контейнера. http://host.docker.internal:8123 обращается к порту Home Assistant, опубликованному хостом Linux Docker, поскольку Compose устанавливает запись host-gateway. URL Home Assistant в локальной сети также работает.

• HA_CONFIG_PATH: существующий каталог конфигурации Home Assistant на хосте. Он монтируется для чтения и записи в /ha-config; Compose отказывается создавать отсутствующий исходный путь.

• MCP_SETTINGS_FILE: используйте ./config.yaml после внесения изменений, специфичных для развёртывания.

• PUID и PGID: не-root идентификаторы с доступом к HA_CONFIG_PATH.

• MCP_ALLOWED_HOSTS: каждое DNS-имя или IP-адрес, которые клиенты помещают в HTTP-заголовок Host.

• MCP_BIND_IP: оставьте 127.0.0.1 для локального обратного прокси/клиента; используйте 0.0.0.0 только для намеренного доступа из локальной сети.

Проверьте, соберите и запустите:

docker compose config
docker compose build --pull
docker compose up -d
docker compose ps
docker compose logs -f hac-mcp

Чтобы использовать опубликованный релиз вместо локальной сборки, задайте точный тег образа и отключите сборки:

MCP_IMAGE=docker.io/lemanjo/hac-mcp:0.1.0 docker compose pull hac-mcp
MCP_IMAGE=docker.io/lemanjo/hac-mcp:0.1.0 docker compose up -d --no-build hac-mcp

Конечные точки здоровья:

curl --fail http://127.0.0.1:3000/livez
curl --fail http://127.0.0.1:3000/readyz

/livez сообщает, что HTTP-процесс обслуживает запросы. /readyz выполняет аутентифицированный запрос /api/ к Home Assistant и возвращает 503, когда Home Assistant недоступен. Ни одна из конечных точек не требует MCP bearer-токена. Образ и проверка здоровья Compose используют /livez, чтобы временный сбой Home Assistant не вызывал цикл перезапуска.

Файловая система времени выполнения доступна только для чтения, кроме /tmp, монтирований Docker secret и /ha-config. Образ работает как не-root пользователь и использует tini как PID 1; SIGTERM/SIGINT достигают Node, который закрывает HTTP-обработчик и WebSocket-соединение Home Assistant. Git и сертификаты CA установлены, но инструмент MCP для выполнения команд оболочки не реализован.

Сетевое размещение

Предоставленная сеть Compose — это изолированный bridge с одним опубликованным портом MCP. Она никогда не использует host-сеть и никогда не монтирует Docker-сокет.

Для подключения к Home Assistant:

• Home Assistant на хосте Docker с опубликованным портом: используйте http://host.docker.internal:8123.

• Home Assistant в локальной сети или в сети macvlan/ipvlan: используйте его LAN DNS-имя или IP-адрес.

• Home Assistant в другой пользовательской bridge-сети: подключите hac-mcp к этой внешней сети и используйте DNS-имя контейнера Home Assistant. Замените нижнее объявление сети на сеть с external: true или добавьте вторую внешнюю сеть к сервису.

Для подключения MCP-клиента:

• Оставьте MCP_BIND_IP=127.0.0.1 для клиентов на том же хосте или локального обратного прокси.

• Установите MCP_BIND_IP=0.0.0.0 для доверенных клиентов в локальной сети, добавьте LAN IP/DNS-имена сервера в MCP_ALLOWED_HOSTS и ограничьте порт правилами брандмауэра хоста.

• Этот сервер не завершает TLS. Используйте доверенный обратный прокси для трафика через недоверенную сеть, сохраняйте заголовок Authorization и настройте разрешённые имена хостов источника, если браузерный клиент отправляет Origin.

Разрешённые хосты и имена хостов источника смягчают DNS-rebinding/междоменный доступ; они не заменяют bearer-аутентификацию или сетевые средства контроля. Рекомендации по безопасности Streamable HTTP MCP приведены в спецификации транспорта.

Unraid

Unraid предоставляет пользовательские общие папки в /mnt/user; см. официальную документацию по общим папкам. Типичная структура — /mnt/user/appdata/hac-mcp для этого репозитория/секретов и фактический каталог appdata Home Assistant для HA_CONFIG_PATH.

1. Поместите файлы проекта и секреты в приватное расположение appdata. Где практично, храните секретные файлы с режимом 0600, а каталог — с режимом 0700.

2. Установите HA_CONFIG_PATH на точный каталог конфигурации Home Assistant, например /mnt/user/appdata/home-assistant. Не монтируйте весь /mnt/user.

3. Устанавливайте PUID=99 и PGID=100 только если файлы Home Assistant принадлежат обычной учётной записи Unraid nobody:users; в противном случае используйте фактического не-root владельца. Подтвердите, что эта учётная запись может создавать /ha-config/.ha-mcp/backups и атомарно заменять разрешённые YAML-файлы.

4. Если установлен плагин сообщества Docker Compose Manager или CLI Compose v2, запустите описанную выше настройку Compose из каталога проекта. Секреты Compose отображаются как файлы в /run/secrets; Docker документирует это поведение здесь.

5. Без Compose соберите home-assistant-admin-mcp:local и создайте контейнер в Docker UI Unraid, используя Advanced View. Отразите настройки окружения, порта и пути из docker-compose.yml. Привяжите два файла токенов только для чтения к /run/secrets/home_assistant_token и /run/secrets/mcp_auth_token; эти привязки монтирования в UI предоставляют файловый интерфейс, ожидаемый приложением, но не являются объектами секретов Compose.

6. По умолчанию используйте bridge-сеть. Если Home Assistant использует host-сеть, укажите HOME_ASSISTANT_URL на LAN IP Unraid и порт Home Assistant или добавьте host.docker.internal:host-gateway. Если Home Assistant имеет собственный LAN IP br0, используйте этот IP. Если оба контейнера используют общую пользовательскую сеть Docker, используйте сетевой псевдоним Home Assistant.

7. Для доступа MCP из локальной сети опубликуйте порт контейнера 3000, привяжите его намеренно и включите IP/DNS-имя Unraid в MCP_ALLOWED_HOSTS. Держите bearer-токен и ограничения брандмауэра даже в доверенной локальной сети.

8. Не добавляйте путь Docker-сокета. Администрирование супервизора/контейнеров не требуется и не поддерживается.

Mover Unraid или настройки общих папок могут изменить физическое расположение файла пользовательской общей папки без изменения /mnt/user/...; используйте один стабильный путь пользовательской общей папки и не смешивайте эквивалентные пути /mnt/user и /mnt/diskX.

MCP-клиенты

Streamable HTTP

Примеры ниже предполагают, что MCP-клиент работает на том же хосте, что и Docker, и настройки Compose по умолчанию не изменены. Укажите клиенту:

http://127.0.0.1:3000/mcp

Каждый запрос к /mcp должен содержать отдельный MCP-токен:

Authorization: Bearer <contents of secrets/mcp_auth_token>

Загрузите MCP-токен в окружение процесса клиента, не помещая его в файл конфигурации клиента. Этот токен аутентифицирует только MCP-клиента; никогда не используйте здесь токен Home Assistant.

export HAC_MCP_TOKEN="$(tr -d '\r\n' < /absolute/path/to/secrets/mcp_auth_token)"

Для клиента на другом хосте замените 127.0.0.1 на адрес хоста MCP, настройте MCP_BIND_IP, MCP_ALLOWED_HOSTS, правила брандмауэра и TLS, как описано в разделе Сетевое размещение. Из другого контейнера 127.0.0.1 означает этот контейнер клиента; вместо этого используйте псевдоним общей сети или адрес хоста.

Codex

Добавьте это в пользовательский ~/.codex/config.toml или в .codex/config.toml доверенного проекта:

[mcp_servers.home-assistant-admin]
url = "http://127.0.0.1:3000/mcp"
bearer_token_env_var = "HAC_MCP_TOKEN"
enabled = true
default_tools_approval_mode = "writes"
tool_timeout_sec = 150

Перезапустите Codex после установки HAC_MCP_TOKEN, затем проверьте соединение с помощью codex mcp list или /mcp в TUI Codex. Режим одобрения writes добавляет запрос на стороне клиента для инструментов, не помеченных как только для чтения; серверный режим, риск и политика подтверждения по-прежнему применяются независимо. См. документацию Codex MCP.

OpenCode

Объедините это в проектном opencode.json или в глобальной конфигурации OpenCode:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "home-assistant-admin": {
      "type": "remote",
      "url": "http://127.0.0.1:3000/mcp",
      "enabled": true,
      "oauth": false,
      "headers": {
        "Authorization": "Bearer {env:HAC_MCP_TOKEN}"
      },
      "timeout": 150000
    }
  }
}

Перезапустите OpenCode после установки HAC_MCP_TOKEN. Выполните opencode mcp list для проверки статуса или opencode mcp debug home-assistant-admin для диагностики соединения. В запросах при необходимости ссылайтесь на сервер по имени, например: Use home-assistant-admin to list unavailable entities. См. документацию OpenCode MCP.

Claude Code

Создайте или объедините этот .mcp.json в проекте, где вы запускаете Claude Code:

{
  "mcpServers": {
    "home-assistant-admin": {
      "type": "http",
      "url": "http://127.0.0.1:3000/mcp",
      "headers": {
        "Authorization": "Bearer ${HAC_MCP_TOKEN}"
      },
      "timeout": 150000
    }
  }
}

Ссылку на переменную окружения можно безопасно распространять; не заменяйте её буквальным токеном в закоммиченном файле. После установки HAC_MCP_TOKEN выполните claude mcp list, запустите claude, одобрите сервер с областью проекта при запросе и используйте /mcp для проверки его статуса. См. документацию Claude Code MCP.

Проверка и использование

Низкоуровневый зонд инициализации полезен для диагностики сбоев конечных точек, прокси и аутентификации независимо от клиента:

curl --fail-with-body http://127.0.0.1:3000/mcp \
  -H "Authorization: Bearer ${HAC_MCP_TOKEN}" \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json, text/event-stream' \
  --data '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl-probe","version":"1.0.0"}}}'

Для обычной работы используйте реальный MCP-клиент; он корректно выполняет инициализацию, согласование версии протокола, уведомления и вызовы инструментов. Сервер принимает ответы JSON или SSE в режиме ответа auto и использует обработчик HTTP без состояния. Полезные первые запросы:

• Use home-assistant-admin to summarize the Home Assistant instance and list unavailable entities. Do not make changes.

• Use home-assistant-admin to diagnose why <entity> is unavailable. Read configuration and recent logs only.

• В режиме control: Turn on <explicit entity_id>. Do not target an area or device.

• В режиме admin: Dry-run the requested configuration change, show the diff and validation result, and wait for confirmation before applying it.

Клиент не может повысить сконфигурированный режим сервера. Запускайте в режиме read_only; измените MCP_MODE в .env и пересоздайте сервис Compose только после проверки прав доступа и экспозиции развёртывания.

stdio

Сначала соберите проект командой pnpm build, затем настройте локальный MCP-клиент для запуска сервера. HTTP-аутентификация не используется в режиме stdio, потому что MCP-клиент владеет дочерним процессом и каналом.

{
  "mcpServers": {
    "home-assistant-admin": {
      "command": "node",
      "args": ["/workspaces/hac-mcp/dist/index.js"],
      "env": {
        "MCP_CONFIG_FILE": "/workspaces/hac-mcp/config.example.yaml",
        "MCP_TRANSPORT": "stdio",
        "MCP_MODE": "read_only",
        "HOME_ASSISTANT_URL": "http://homeassistant.local:8123",
        "HOME_ASSISTANT_TOKEN_FILE": "/absolute/private/path/home_assistant_token",
        "HA_CONFIG_PATH": "/absolute/path/to/home-assistant/config"
      }
    }
  }
}

В режиме stdio сервер пишет логи только в stderr. Docker healthcheck специфичен для HTTP, поэтому не используйте стандартный Docker healthcheck, если намеренно запускаете образ как дочерний процесс stdio.

Аутентификация и конфигурация

Существуют два независимых учётных данных:

Для обоих токенов переменная *_FILE имеет приоритет над прямой переменной окружения, а окружающие пробелы обрезаются:

• HOME_ASSISTANT_TOKEN_FILE имеет приоритет над HOME_ASSISTANT_TOKEN.

• MCP_AUTH_TOKEN_FILE имеет приоритет над MCP_AUTH_TOKEN.

MCP_AUTH_TOKEN или его файл обязателен для HTTP и не требуется для stdio. Сравнение Bearer-токенов выполняется с использованием SHA-256-дайджестов и сравнения, безопасного по времени. TLS по-прежнему требуется, когда сеть не является доверенной, поскольку Bearer-токены можно воспроизводить.

Конфигурация загружается из MCP_CONFIG_FILE, затем значения из окружения переопределяют файл. Поддерживаемые переопределения из окружения:

Переменные, разделённые запятыми, обрезаются. Только присутствующие переменные окружения переопределяют значения YAML. Лимиты, права доступа, TTL кэша, политика метаданных секретов, каталог резервных копий и личность автора Git в остальном берутся из YAML-значений по умолчанию или из файла конфигурации.

Режимы, риск и подтверждение

Каждый инструмент зарегистрирован с уровнем риска и остаётся видимым для клиентов. Политика снова применяется при вызове.

call_service имеет базовый уровень CONTROL, но повышает известные административные аргументы перед авторизацией: действия перезапуска/остановки, резервного копирования и очистки recorder становятся HIGH_IMPACT; действия перезагрузки, logger и config становятся CONFIG. Эффективный риск возвращается в каждом результате, а пользовательские MCP-метаданные помечают инструмент как динамически классифицированный.

permissions.requireConfirmationFor по умолчанию равен HIGH_IMPACT. Соответствующий инструмент должен получить confirm: true; в противном случае он возвращает CONFIRMATION_REQUIRED с метаданными для повторной попытки. Добавьте CONTROL и/или CONFIG, чтобы требовать подтверждение в более широком диапазоне.

Политика чувствительных доменов не зависит от режима:

• allow: применяется обычная политика режима/риска.

• confirm: требуется явный confirm: true.

• deny: операция отклоняется даже в режиме admin.

По умолчанию требуется подтверждение для lock, alarm_control_panel и siren. Явные идентификаторы сущностей cover, содержащие garage или gate, также требуют подтверждения. Политика оценивает каждую явную сущность в цели с несколькими сущностями. Цели областей/устройств нельзя безопасно расширить во время авторизации, поэтому запретите или требуйте подтверждение для всего домена сервиса, когда это различие имеет значение.

Пробные запуски (dry runs)

dry_run: true реализован для инструментов постоянных ресурсов, помощников, реестра, областей, устройств, сущностей, записей конфигурации, YAML-патчей, административного жизненного цикла, отката и универсальных вызовов сервисов. Удобные инструменты физического управления не имитируют действия.

• YAML-патчи разбирают и проверяют результирующий YAML и возвращают отредактированный структурированный diff без записи, создания контрольной точки, перезагрузки, проверки полной конфигурации Home Assistant или коммита.

• Локальный разбор YAML отклоняет синтаксические ошибки, дублирующиеся ключи сопоставления, неразрешённые алиасы и чрезмерное расширение алиасов. Последующее применение без dry run запускает полную проверку конфигурации Home Assistant и пытается выполнить откат при отклонении; локальная валидация не заменяет валидацию доменов Home Assistant.

• Пробные запуски автоматизаций/скриптов/сцен читают текущий ресурс редактора, создают JSON-diff и вызывают реализованную валидацию фрагментов, где она доступна, но не записывают и не создают контрольную точку.

• Пробные запуски помощников, реестра, областей, устройств, сущностей и записей конфигурации читают текущие данные и формируют предварительный просмотр. Они не вызывают внутреннюю конечную точку мутации и не выполняют серверную валидацию мутаций Home Assistant.

• Пробный запуск перезагрузки записи конфигурации сообщает о предлагаемой перезагрузке, но не может предсказать эффекты во время выполнения.

• Пробные запуски перезагрузки, перезапуска, отката контрольной точки и отката Git, принадлежащего сервису, проверяют доступные идентификаторы/текущие метаданные и описывают предлагаемое действие с высоким воздействием без его применения.

• Универсальный call_service поддерживает пробную валидацию по живому определению сервиса; сервис не вызывается. Удобные инструменты физического управления намеренно не имитируют действия.

• Успешный пробный запуск доказывает только те валидации, которые описаны в его результате. Он не гарантирует, что состояние, права доступа, внутренние API, файлы или поведение интеграции останутся неизменными на момент применения.

Безопасность файловой системы

Доступ к файловой системе отключается целиком с помощью HA_FILESYSTEM_ENABLED=false. При включении запросы канонизируются в filesystem.root, каждый сегмент пути проверяется, а символические ссылки отклоняются.

Разрешённые пути:

• Любой файл .yaml или .yml непосредственно в корне конфигурации.

• YAML ниже сконфигурированных allowedDirectories, по умолчанию packages и themes, рекурсивно до глубины сканирования 32.

• Выбранные .json, .py, .pyi, .yaml и .yml в custom_components/<integration>/... только при включённой политике пользовательских компонентов. Специализированные инструменты обеспечивают ограниченное чтение исходников; инструмент записи исходников или путь выполнения/валидации Python не предоставляется.

Всегда защищено или запрещено:

• .storage, .git, форматы баз данных Home Assistant, форматы/имена закрытых ключей и имена путей, соответствующие реализованным шаблонам auth, credential, token или backup-key.

• Пути вне корня, недопустимые сегменты пути, отсутствующие родительские каталоги для записи, нерегулярные файлы и все символические ссылки.

• Значения secrets.yaml и secrets.yml по умолчанию. С allowSecretsMetadata: true инструменты могут возвращать отсортированные имена ключей секретов верхнего уровня, количество байт и временные метки без значений.

С allowSecretValues: false чувствительные ключи в snake_case, camelCase и через дефис, такие как password, clientSecret, token, apiKey, private-key, credential, authorization и cookie, нормализуются и редактируются рекурсивно. Значения !secret/!env_var и соответствующие строки diff также редактируются.

Эти проверки основаны на шаблонах, а не на сканере содержимого, поэтому необычные имена секретов могут не соответствовать каждой защите. Храните фактические значения в защищённом корневом secrets.yaml, не храните учётные данные в других разрешённых YAML-файлах и проверяйте отредактированный вывод перед передачей его недоверенной модели. Установка HA_ALLOW_SECRET_VALUES=true явно разрешает чтение и изменение YAML, содержащего секреты, включая корневой secrets.yaml; используйте этот исключительный вариант восстановления только с полностью доверенными клиентами.

Записи используют временные файлы, O_NOFOLLOW, fsync, атомарное переименование, сохранённые режимы, проверки оптимистичной конкурентности SHA-256 и синхронизацию родительского каталога, где это поддерживается.

Контрольные точки, транзакции и откат

Рабочий процесс patch_yaml_file без dry run:

1. Разрешите пути из списка разрешённых, прочитайте текущие хеши, примените структурные операции YAML и проверьте синтаксис.

2. Создайте контрольную точку с сохранением режима в /ha-config/.ha-mcp/backups по умолчанию.

3. Повторно проверьте хеши и атомарно запишите каждый файл. На процесс сервера выполняется только одна транзакция конфигурации.

4. Попросите Home Assistant проверить полную конфигурацию.

5. Перезагрузите затронутый домен автоматизаций/скриптов/сцен или вызовите homeassistant.reload_all для других/нескольких путей, если не указано reload: false.

6. Прочитайте конфигурацию Home Assistant как проверку работоспособности.

7. При сбое после начала записи восстановите только применённые файлы, если их хеши всё ещё соответствуют выводу транзакции, затем попробуйте перезагрузку и проверки работоспособности.

8. При необходимости закоммитьте только изменённые пути в Git. Сбой Git становится предупреждением после успешного изменения Home Assistant; он не откатывает изменение.

Мутации автоматизаций/скриптов/сцен, управляемые редактором, создают контрольную точку файловой системы перед вызовом внутренней конечной точки редактора, требуют монтирования конфигурации для изменений без dry run, проверяют конфигурацию редактора и наличие/отсутствие во время выполнения с ограниченными повторными попытками, выполняют валидацию конфигурации Home Assistant и пытаются выполнить откат на уровне редактора, если применение или проверка завершаются неудачей.

rollback_change сначала создаёт контрольную точку безопасности текущих файлов, восстанавливает выбранную контрольную точку с проверками конфликтов по текущим хешам, проверяет конфигурацию Home Assistant и перезагружается. Если проверка/перезагрузка завершается неудачей, он пытается восстановить контрольную точку безопасности и сообщает о любом сбое восстановления. Контрольные точки — это локальные снимки файлов, а не резервные копии Home Assistant Supervisor, и автоматическая очистка хранения не выполняется.

Поведение и лимиты Git

Git является необязательным и работает только когда /ha-config находится внутри обнаруженного репозитория. В образ включён CLI Git.

• Статус, история и диффы ограничены путями, принимаемыми политикой путей конфигурации.

• Коммиты добавляют в индекс и фиксируют только выбранные разрешённые пути. Хуки отключены, подпись отключена, а личность автора/коммиттера берётся из конфигурации.

• Сервер не выполняет инициализацию, клонирование, fetch, pull, push, merge, rebase, не управляет удалёнными репозиториями, учётными данными, ветками, тегами или подмодулями.

• Целевые пути проверяются перед изменением. Если в затронутом файле уже есть изменения в индексе или рабочем дереве, операция Home Assistant может продолжиться со своей контрольной точкой, но автоматический Git-коммит пропускается, чтобы ранее внесённые человеком правки не попали в MCP-коммит. Несвязанные пути остаются нетронутыми.

• rollback_to_commit принимает только текущий HEAD, только коммит, чей email автора совпадает с настроенным служебным email, не начальный коммит, и только когда в затронутых путях нет незакоммиченных изменений.

• Git-откат записывает новый компенсирующий коммит, а не сбрасывает историю. Если проверка Home Assistant не удаётся, предпринимается ещё один откат, принадлежащий службе, для восстановления предыдущего состояния.

• Git-команды завершаются по таймауту через 30 секунд. Обычный вывод ограничен 4 МиБ; диффы ограничены четырёхкратным значением maxReadBytes с верхним пределом 16 МиБ.

Инструменты

Названия ниже получены из src/mcp/tools. Видимые клиенту схемы, описания, аннотации, риск, источник и метаданные стабильности возвращаются механизмом обнаружения MCP.

Обнаружение

• Экземпляр: get_home_assistant_info, get_system_health, get_config.

• Интеграции: list_integrations, get_integration.

• Зоны: list_areas, get_area.

• Устройства: list_devices, get_device, search_devices.

• Сущности: list_entities, get_entity, search_entities.

• Межреестровый поиск: search_home_assistant_registry.

Среда выполнения и история

• Службы/события: list_services, list_event_types, get_events, subscribe_events.

• Состояния: get_state, get_states, get_states_by_area, get_states_by_device.

• Данные регистратора: get_history, get_logbook, get_statistics, get_recorder_statistics.

Управление

• Общее/стандартное управление: call_service, turn_on, turn_off, toggle, set_value, set_temperature.

• Выполнение: activate_scene, run_script.

Автоматизации, скрипты, сцены и трассировки

• Автоматизации: list_automations, get_automation, create_automation, update_automation, delete_automation, enable_automation, disable_automation, trigger_automation, reload_automations, validate_automation.

• Скрипты: list_scripts, get_script, create_script, update_script, delete_script, run_script_by_id, reload_scripts, validate_script.

• Сцены: list_scenes, get_scene, create_scene, update_scene, delete_scene, activate_scene_resource, reload_scenes.

• Трассировки автоматизаций: get_automation_traces, get_automation_trace, explain_automation_failure, get_last_automation_run.

• Общие трассировки: get_trace, list_traces, explain_trace, get_last_trace.

Вспомогательные элементы и реестры

• Вспомогательные элементы: list_helpers, get_helper, create_helper, update_helper, delete_helper.

• Реестр сущностей: update_entity_registry, disable_entity, enable_entity, rename_entity, move_entity_to_area.

• Реестр устройств: update_device, rename_device, move_device_to_area, disable_device, enable_device.

• Реестр зон: create_area, update_area, delete_area, assign_device_to_area, assign_entity_to_area.

• Записи конфигурации: get_config_entries, get_config_entry, reload_config_entry, update_integration, enable_integration, disable_integration.

Конфигурация и восстановление

• Чтение/список: read_configuration, list_configuration_files, read_yaml_file, list_custom_component_files, read_custom_component_source.

• Патч/проверка: patch_yaml_file, validate_configuration, validate_home_assistant_configuration.

• Перезагрузка/перезапуск: reload_configuration, reload_yaml_configuration, restart_home_assistant.

• История/дифф: get_config_history, get_config_diff, get_recent_changes.

• Откат: rollback_change, rollback_to_commit.

Журналы, диагностика, зависимости и поиск

• Журналы: get_home_assistant_logs, search_logs, get_errors, get_warnings, get_recent_errors, get_integration_errors.

• Находки по сущностям/устройствам: find_unavailable_entities, find_disabled_entities, find_orphaned_entities, find_orphaned_devices, find_duplicate_entities, find_entities_without_area, find_devices_without_area, find_stale_sensors.

• Находки по автоматизациям/вспомогательным элементам: find_unused_helpers, find_broken_automations, find_automation_errors, find_automations_referencing_missing_entities.

• Зависимости/поиск: get_entity_dependencies, get_automation_dependencies, search_home_assistant.

Примеры пользовательских запросов

• «Перечислить недоступные сущности на кухне и включить их связи с устройствами и интеграциями».

• «Показать записи журнала ERROR и CRITICAL для интеграции zha за последний час».

• «Объяснить самый последний неудачный запуск автоматизации с ID garage_arrival».

• «Найти автоматизации, ссылающиеся на отсутствующие сущности, затем показать зависимости каждой автоматизации».

• «Выполнить пробный прогон структурного YAML-патча, изменяющего packages/lighting.yaml; показать только редактированный дифф».

• «Выключить light.office, но не targeting другие сущности».

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

• «Удалить сцену с ID old_evening с явным подтверждением, затем сообщить о контрольной точке, проверке конфигурации, верификации, откате и результатах Git».

Модель/клиент должен перевести запрос в точную схему инструмента. Естественно-языковой запрос не обходит проверки режима, риска, подтверждения, путей или авторизации Home Assistant.

Производительность и ограничения

Значения по умолчанию и жёсткие границы предназначены для того, чтобы вызов MCP не превращался в неограниченный запрос к Home Assistant или файловой системе.

Длинные окна истории/журнала событий и полная диагностика всё ещё могут быть дорогостоящими внутри регистратора Home Assistant. По возможности фильтруйте по сущности, устройству, интеграции, временному диапазону и странице.

Разработка

Требуются Node.js 22.23.1 и pnpm 11.21.0.

corepack enable
pnpm --version
pnpm install --frozen-lockfile
pnpm build

Цепочка поставок зависимостей

• Прямые зависимости используют точные версии; lockfile фиксирует полный граф с хэшами целостности реестра.

• pnpm отклоняет релизы младше 10 080 минут (семи дней), пакеты без времени публикации, понижения доверия к издателю, экзотические транзитивные источники и неодобренные сценарии сборки зависимостей. Он также повторно проверяет данные разрешения lockfile на соответствие закреплённому npm-реестру при каждой установке.

• Установки по умолчанию используют замороженный lockfile. Изменение зависимостей требует явного, проверенного pnpm install --no-frozen-lockfile, за которым следуют pnpm supply-chain:check, обычный набор проверок и закоммиченный дифф lockfile.

• Транзитивные переопределения закрепляют подходящие релизы content-type и hono, пока более новые версии остаются в карантинном окне, и закрепляют undici-types на засвидетельствованный релиз, который не понижает доверие к издателю. Повторно оценивайте, но не удаляйте автоматически эти переопределения во время проверенного обновления зависимостей.

• Действия CI и базовые образы контейнеров используют неизменяемые коммиты или дайджесты содержимого. Пакеты Debian для среды выполнения берутся из датированного снимка, поэтому пересборка не обновляет их незаметно.

• Не добавляйте исключение minimumReleaseAgeExclude. Для срочного релиза безопасности подождите, пока ему исполнится семь дней, или получите явное одобрение на изменение этой политики в проверенном изменении.

Публикация релизов

Публикация GitHub-релиза с SemVer-тегом, таким как v0.1.0, запускает .github/workflows/release-docker.yml. Он собирает образы linux/amd64 и linux/arm64, отправляет тег версии в docker.io/lemanjo/hac-mcp и прикрепляет атрибуты SBOM и происхождения. Стабильные релизы также обновляют latest; пререлизы — нет.

Репозиторию требуются следующие секреты GitHub Actions:

• DOCKERHUB_USERNAME: имя учётной записи Docker Hub, в настоящее время lemanjo.

• DOCKERHUB_TOKEN: персональный токен доступа Docker Hub с разрешением чтения/записи для lemanjo/hac-mcp. Не используйте пароль учётной записи.

Добавьте их в разделе GitHub repository > Settings > Secrets and variables > Actions > New repository secret или с помощью GitHub CLI:

gh secret set DOCKERHUB_USERNAME --repo lemanjo/hac-mcp --body lemanjo
gh secret set DOCKERHUB_TOKEN --repo lemanjo/hac-mcp

Вторая команда безопасно запрашивает значение токена. Не храните токен в .env, YAML-файлах рабочих процессов, истории оболочки или в репозитории.

Каждый push в main, включая объединённый pull request, запускает .github/workflows/nightly-docker.yml. Он использует отдельный секрет DOCKERHUB_NIGHTLY_TOKEN и публикует тег nightly, а также неизменяемый тег nightly-<full-commit-sha>. Workflow также можно запустить вручную из GitHub Actions. Используйте тег с полным SHA, когда важна воспроизводимость.

gh secret set DOCKERHUB_NIGHTLY_TOKEN --repo lemanjo/hac-mcp

HTTP-разработка:

HOME_ASSISTANT_URL=http://homeassistant.local:8123 \
HOME_ASSISTANT_TOKEN_FILE=/absolute/private/path/home_assistant_token \
MCP_AUTH_TOKEN_FILE=/absolute/private/path/mcp_auth_token \
MCP_CONFIG_FILE=./config.example.yaml \
MCP_TRANSPORT=http \
MCP_HOST=127.0.0.1 \
MCP_ALLOWED_HOSTS=localhost,127.0.0.1 \
HA_CONFIG_PATH=/absolute/path/to/home-assistant/config \
pnpm dev

Для разработки только через API установите HA_FILESYSTEM_ENABLED=false и HA_GIT_ENABLED=false; мутации ресурсов редактора, требующие контрольных точек, тогда будут недоступны по замыслу.

Тестирование и валидация

Запустите проверки репозитория:

pnpm supply-chain:check
pnpm audit --prod --audit-level high
pnpm typecheck
pnpm lint
pnpm format:check
pnpm test
pnpm build

Проверьте файлы развёртывания там, где доступен Docker:

docker compose config
docker build --check -t home-assistant-admin-mcp:check .
docker build -t home-assistant-admin-mcp:local .

Затем протестируйте /livez, /readyz, запрос инициализации MCP и репрезентативные инструменты только для чтения против непродакшн-инстанса Home Assistant. Перед включением admin протестируйте внутренние чтения API, пробные запуски, одноразовую мутацию, откат контрольной точки и поведение Git на той же версии Home Assistant и файловой системе, которые используются в продакшене.

Устранение неполадок

Сервер не запускается

• INVALID_CONFIGURATION: разберите config.yaml, проверьте точные ключи в camelCase, числовые диапазоны, URL, формат email и детали валидации в stderr.

• MCP_AUTH_REQUIRED: для HTTP требуется MCP_AUTH_TOKEN или MCP_AUTH_TOKEN_FILE, не менее 16 символов после обрезки.

• ENOENT для секрета: пути к исходным файлам секретов в Compose — это пути хоста относительно проекта Compose. Проверьте .env и права на файлы.

• Проверка работоспособности Docker не проходит в режиме stdio: /livez существует только в режиме HTTP; удалите или переопределите проверку для намеренных stdio-контейнеров.

MCP HTTP 401, 403 или 413

• 401: bearer-токен MCP отсутствует, повреждён или неверен. Схема аутентификации нечувствительна к регистру и должна быть Bearer.

• 403 до вызова инструмента: добавьте фактическое имя хоста запроса в MCP_ALLOWED_HOSTS, а для браузерных клиентов — имя хоста источника без схемы и порта в MCP_ALLOWED_ORIGINS. Не добавляйте произвольные подстановочные знаки.

• 413 или отклонение JSON-парсинга: уменьшите запрос или увеличьте mcp.maxRequestBytes в пределах 10 МиБ.

• Сбои обратного прокси: сохраняйте Authorization, Host, Origin, Accept, Content-Type, MCP-Protocol-Version, HTTP-стриминг и поведение SSE.

/readyz возвращает 503 или вызовы Home Assistant не работают

• Изнутри контейнера моста localhost — это контейнер MCP, а не Home Assistant. Используйте host.docker.internal, адрес в локальной сети или псевдоним общей сети.

• HA_AUTH_FAILED/HA_WS_AUTH_FAILED: замените или пересоздайте долгоживущий токен Home Assistant.

• HA_PERMISSION_DENIED: пользователю токена не хватает прав или статуса администратора для запрошенной внутренней команды.

• HA_TLS_ERROR/HA_WS_TLS_ERROR: установите доверенную цепочку сертификатов или, только в контролируемой частной сети, установите HA_VERIFY_TLS=false с полным осознанием того, что личность сервера больше не проверяется.

• Ошибки истории, журнала или статистики: проверьте, что интеграция recorder/logbook загружена и запрошенные ID и диапазоны времени существуют.

Сбои файловой системы или Git

• CONFIG_ROOT_UNAVAILABLE/отказ в доступе: сделайте HA_CONFIG_PATH корректным и доступным для записи через PUID:PGID; контейнер намеренно не запускается от root.

• CONFIG_PATH_NOT_ALLOWED: используйте корневой YAML или разрешённый каталог; защищённые пути, символические ссылки, произвольные расширения и отсутствующие родительские каталоги отклоняются.

• CONFIG_CONCURRENT_MODIFICATION/ROLLBACK_CONFLICT: другой процесс изменил файл. Перечитайте, просмотрите и повторите попытку, а не принудительно перезаписывайте.

• Git is enabled but no repository was detected: инициализируйте/управляйте репозиторием вне MCP или установите HA_GIT_ENABLED=false.

• Git сообщает о сомнительном владении: согласуйте UID/GID контейнера с владельцем репозитория. Не решайте это запуском контейнера как root.

• Контрольные точки занимают место: проверьте и примените политику хранения, определённую оператором, к .ha-mcp/backups; автоматического инструмента удаления нет.

Внутренние инструменты не работают после обновления Home Assistant

• Убедитесь, что команда всё ещё существует в связанном текущем исходном коде ядра, и сравните поля запроса и ответа.

• Сначала повторите операцию только для чтения. Не повторяйте мутацию многократно, если статус проверки или отката неясен.

• Используйте интерфейс Home Assistant для помощников, интеграций или ресурсов, чей внутренний endpoint изменился.

• Держите MCP_MODE=read_only, пока совместимость не будет протестирована и проверена.

Лицензия

MIT