Ambient Home Assistant MCP

Ambient Home Assistant MCP는 ChatGPT 및 기타 MCP 클라이언트에 Home Assistant에 대한 목적에 맞는 접근을 제공하는 안전하고 의미론적인 브리지입니다. 향후 사용자 대상 Ambient Home Assistant 애플리케이션의 서버 기반이 됩니다.

2단계 상태: 로컬/비공개 및 읽기 전용입니다. 이 릴리스는 의미론적 엔티티 검색, 현재 상태, 영역, 층 및 도메인 요약을 추가합니다. 기기를 제어하거나 Home Assistant를 변경할 수 없습니다.

그것이 무엇인지—그리고 무엇이 아닌지

이 브리지는 추상화 및 보안 계층입니다. 시간이 지남에 따라 Home Assistant REST, WebSocket 및 네이티브 MCP/Assist 인터페이스 중에서 선택하면서 모델에 작고 의미론적인 도구를 제공할 수 있습니다.

그것은 아닙니다:

• Home Assistant의 대체재;

• 제한 없는 Home Assistant 관리자 API;

• LLM에 노출된 일반 API 래퍼; 또는

• Home Assistant의 /api/mcp 엔드포인트를 위한 리버스 프록시.

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, 카메라 소스, 토큰, 자격 증명, 좌표 및 위치 관련 메타데이터를 제외합니다.

• 현재 상태는 캐시되지 않습니다. 레지스트리 메타데이터는 반복적인 WebSocket 인증 및 레지스트리 읽기를 피하기 위해 제한된 60초 TTL 캐시 하나를 사용합니다.

• MCP 전송 Host 및 Origin 허용 목록은 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는 호스트 루프백에만 게시합니다.

Docker 상태 확인 프로브는 애플리케이션 활성 상태를 테스트합니다. 일시적인 Home Assistant 중단은 /health를 status: degraded로 변경하지만 HTTP 상태 200을 유지하므로 오케스트레이터가 정상적인 브리지를 반복적으로 재시작하지 않습니다.

문서

• 아키텍처

• 보안

• 도구 계약

• 개발

• ChatGPT 설정 및 현재 제한 사항

라이선스

MIT. LICENSE를 참조하세요.