Ambient Home Assistant MCP

Ambient Home Assistant MCP — это безопасный семантический мост, который предоставляет ChatGPT и другим MCP-клиентам специализированный доступ к Home Assistant. Он является серверной основой для будущего пользовательского приложения Ambient Home Assistant.

Статус фазы 2: локальный/частный и только для чтения. Этот выпуск добавляет семантическое обнаружение сущностей, текущее состояние, зоны, этажи и сводки по доменам. Он не может управлять устройствами или изменять Home Assistant.

Что это такое — и чем оно не является

Мост — это уровень абстракции и безопасности. Со временем он сможет выбирать между REST, WebSocket и нативными интерфейсами MCP/Assist Home Assistant, предоставляя модели небольшие семантические инструменты.

Он не является:

• заменой Home Assistant;

• неограниченным администраторским API Home Assistant;

• универсальной обёрткой API, доступной LLM; или

• обратным прокси для конечной точки /api/mcp Home Assistant.

Related MCP server: ha-ai-learner

Архитектура

flowchart TD
    C[ChatGPT or MCP client] -->|MCP| A[Ambient Home Assistant MCP]
    A --> T[Semantic tools]
    A --> P[Policy and security]
    A --> N[Normalized data and diagnostics]
    T --> H[Home Assistant client facade]
    P --> H
    N --> H
    H --> R[REST state API]
    H --> W[WebSocket registries]
    H -. selective future use .-> M[HA MCP or Assist API]

Инструменты MCP никогда не выполняют прямых HTTP-запросов. Они зависят от HomeAssistantClient, который отвечает за выбор интерфейса и немедленно нормализует ответы вышестоящих систем. См. запись о решении по архитектуре.

Возможности

Никакие вызовы служб, изменения состояния или административные конечные точки не реализованы.

Модель безопасности

• Токены Home Assistant поступают только из конфигурации времени выполнения и используют секретные типы Pydantic.

• Журналы структурированы и скрывают токены носителя и общие поля учётных данных.

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

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

• Текущие состояния никогда не кэшируются. Метаданные реестра используют один ограниченный кэш TTL на 60 секунд, чтобы избежать повторной аутентификации WebSocket и чтения реестра.

• Белые списки Host и Origin транспорта MCP защищают от DNS-ребендинга.

• Политический движок разрешает чтение и закрывается при сбое для каждого класса управления.

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

Никогда не коммитьте .env, токены Home Assistant, учётные данные, частные URL-адреса или сертификаты. См. Безопасность перед любой работой по развёртыванию.

Быстрый старт

Требования: Python 3.12+ и uv.

cp .env.example .env
# Edit .env and provide HOME_ASSISTANT_URL and HOME_ASSISTANT_TOKEN.
uv sync --all-extras
uv run ambient-ha-mcp

Конечная точка Streamable HTTP MCP: http://127.0.0.1:8000/mcp; состояние доступно по адресу http://127.0.0.1:8000/health.

Проверьте инструменты локально:

npx @modelcontextprotocol/inspector@latest

Затем подключите Inspector к http://127.0.0.1:8000/mcp.

Команды разработки

uv sync --all-extras          # install
uv run ambient-ha-mcp         # run locally
uv run pytest                 # unit tests; real HA tests skip by default
uv run ruff check .           # lint
uv run ruff format --check .  # formatting check
uv run mypy                   # type check
docker build -t ambient-ha-mcp .
docker compose up --build

Перегенерируйте блокировку зависимостей после намеренного изменения зависимостей:

uv lock

Docker Compose

Скопируйте .env.example в .env, укажите два обязательных параметра Home Assistant и выполните docker compose up --build. Compose публикует только на loopback хоста.

Проверка работоспособности Docker проверяет работоспособность приложения. Временный сбой Home Assistant меняет /health на status: degraded, но оставляет HTTP-статус 200, чтобы оркестратор не перезапускал здоровый мост в цикле.

Документация

• Архитектура

• Безопасность

• Контракты инструментов

• Разработка

• Настройка ChatGPT и текущие ограничения

Лицензия

MIT. См. LICENSE.