Upload 10 files

.dockerignore

@@ -0,0 +1,7 @@
+.venv
+**/__pycache__
+.pytest_cache
+.git
+tests
+.env
+*.zip

Dockerfile

@@ -2,7 +2,7 @@ FROM ghcr.io/home-assistant/home-assistant:stable
 
 USER root
 
-RUN apk add --no-cache git bash \
+RUN apk add --no-cache git bash nginx \
     && git clone --depth 1 https://github.com/al-one/hass-xiaomi-miot.git /tmp/hass-xiaomi-miot \
     && mkdir -p /opt/ha-custom-components \
     && cp -a /tmp/hass-xiaomi-miot/custom_components/xiaomi_miot /opt/ha-custom-components/xiaomi_miot \
@@ -10,6 +10,19 @@ RUN apk add --no-cache git bash \
     && python3 -m pip install --no-cache-dir --disable-pip-version-check huggingface_hub \
     && mkdir -p /data/home-assistant /config
 
+# Pre-install the China-region Haier Smart Home custom integration.
+RUN git clone --depth 1 https://github.com/sfairy/ha_haier.git /tmp/ha_haier \
+    && mkdir -p /opt/ha-custom-components \
+    && cp -a /tmp/ha_haier/custom_components/haier /opt/ha-custom-components/haier \
+    && rm -rf /tmp/ha_haier
+
+COPY mcp_server/requirements.txt /opt/mcp-server/requirements.txt
+RUN python3 -m venv /opt/mcp-venv \
+    && /opt/mcp-venv/bin/pip install --no-cache-dir -r /opt/mcp-server/requirements.txt
+COPY mcp_server/server.py /opt/mcp-server/server.py
+COPY nginx.conf /etc/nginx/nginx.conf
+COPY mcp-proxy.conf /etc/nginx/mcp-proxy.conf
+COPY scripts/run-space.py /usr/local/bin/run-space.py
 COPY scripts/start-homeassistant /usr/local/bin/start-homeassistant
 COPY scripts/backup-homeassistant.py /usr/local/bin/backup-homeassistant.py
 RUN chmod +x /usr/local/bin/start-homeassistant

README.md

@@ -10,7 +10,7 @@ suggested_hardware: cpu-basic
 
 # Home Assistant on Hugging Face Spaces
 
-This Space runs Home Assistant with the Xiaomi Miot custom integration pre-installed.
+This Space runs Home Assistant with Xiaomi Miot and the China-region Haier Smart Home custom integrations pre-installed.
 
 ## Required Space secrets
 
@@ -34,4 +34,61 @@ Home account. This integration generally requires the Xiaomi cloud region that o
  the devices; it does not require the Home Assistant container to be on the same LAN.
 
 Do not put `HF_TOKEN` in this repository or in `README.md`; use Space Settings ->
-Repository secrets.
+Repository secrets.
+## Agent MCP 接入（同一个 Space）
+
+网页继续使用 Space 的直接应用地址；MCP 地址为该地址后加 /mcp。采用 Streamable HTTP，非旧版 SSE。
+
+### 你需要完成的步骤
+
+1. 在当前 Home Assistant 中确认配置已备份成功，再上传本项目文件。Dockerfile 已包含米家和海尔智家集成安装命令，无需手动合并。不要上传 .venv、tests、__pycache__ 或任何令牌。
+2. 创建专用于 Agent 的 Home Assistant 用户，以该用户登录，进入个人资料 → 长期访问令牌，生成令牌。非管理员用户权限仍可能涵盖大量设备；本项目按要求不设置设备或服务白名单。
+3. 在 Space Settings → Variables and secrets → Secrets 中设置 HA_TOKEN 为该长期令牌，MCP_API_KEY 为你生成的随机密钥（建议至少 32 字节随机值）。密钥不要包含换行。保留 HF_TOKEN 与 BACKUP_REPO_ID。可以先部署再创建 HA 令牌；未配置密钥时 MCP 默认拒绝请求，网页仍可使用。
+4. 等待重新构建完成，再在 Agent 中添加远程 MCP，URL 为 https://你的实际应用域名.hf.space/mcp，传输方式 Streamable HTTP，Header 为 Authorization: Bearer 你的MCP_API_KEY。Agent 不需要 HA_TOKEN。
+5. 使用 Agent 的连接测试，然后先调用 list_entities 或 list_services，再控制设备。
+
+通用配置示例（具体字段取决于 Agent 平台）：
+
+```json
+{
+  "mcpServers": {
+    "home-assistant": {
+      "url": "https://YOUR-SPACE.hf.space/mcp",
+      "headers": {"Authorization": "Bearer YOUR_MCP_API_KEY"}
+    }
+  }
+}
+```
+
+可用工具：list_entities(domain 可选)、get_entity_state(entity_id)、list_services()、call_service(domain, service, service_data)。call_service 可以调用该 HA 用户有权执行的服务，包括自动化与脚本；没有实体白名单。它不提供任意路径的 HTTP 代理。服务失败会返回工具错误，不返回 HA 令牌。
+
+MCP 采用独立 Bearer 密钥，不实现 OAuth；Agent 必须支持自定义 Authorization header。如果仅支持 OAuth 自动登录或旧版 HTTP+SSE，此配置不能直接接入。公开 Space 使用应用直接域名；私有 Space 还有 Hugging Face 平台鉴权，不能仅靠 MCP 密钥访问。
+
+### 运行与配置迁移
+
+Nginx 对外监听 7860；HA 改为内部 8123；MCP 仅监听 127.0.0.1:8000。Nginx 支持 HA WebSocket 和 MCP 请求转发。启动时修改 configuration.yaml 中 inline http 配置的端口与代理信任列表，保留其他 YAML，包括 !include；http: !include 形式需要先手工改为内联映射。代理信任列表改为 loopback 和 10.0.0.0/8。
+
+首次无快照会继续初始化；Hub 恢复遇到权限或网络错误时停止，防止新空配置覆盖原备份。首次定时备份在启动约 60 秒后，此后每 10 分钟，正常停止时会尝试最后一次备份。强制终止仍可能丢失未上传配置。免费 Space 休眠时 MCP 和 HA 均不可用。
+
+排查：401 表示 MCP 密钥未匹配；503 表示 MCP_API_KEY 未配置；工具报 HA HTTP 401 表示 HA_TOKEN 无效；工具报连接错误或代理 502 可能是 HA 尚未就绪。浏览器直接打开 /mcp 没带鉴权时返回 401 属正常现象。
+
+## 直接上传文件到 Space
+
+一次提交上传以下文件，保留相对路径，不需要部署压缩包：
+
+```text
+Dockerfile
+README.md
+.dockerignore
+nginx.conf
+mcp-proxy.conf
+mcp_server/requirements.txt
+mcp_server/server.py
+scripts/start-homeassistant
+scripts/run-space.py
+scripts/backup-homeassistant.py
+```
+
+在 Space 的 Files 页面通过 Add file → Upload files 上传；请核对 scripts 与 mcp_server 下的文件未被放在仓库根目录。所有文件准备好后在同一次提交中保存，Space 将自动重新构建。不要上传 .venv、tests、__pycache__、.pytest_cache、.env 或旧压缩包。
+
+构建时安装海尔智家（sfairy/ha_haier），启动脚本会将镜像中缺少的集成复制到配置目录的 custom_components 中。启动后进入 设置 → 设备与服务 → 添加集成 → 搜索海尔智家，使用中国区海尔智家账号登录。已经恢复的同名集成目录会保留，不会强制覆盖其代码或账号配置。

mcp-proxy.conf

@@ -0,0 +1,8 @@
+proxy_http_version 1.1;
+proxy_set_header Host $http_host;
+proxy_set_header Authorization $http_authorization;
+proxy_set_header Connection "";
+proxy_buffering off;
+proxy_cache off;
+proxy_read_timeout 3600s;
+proxy_send_timeout 3600s;

mcp_server/requirements.txt

@@ -0,0 +1,3 @@
+mcp==1.30.0
+uvicorn>=0.30,<1
+httpx>=0.27,<1

mcp_server/server.py

@@ -0,0 +1,75 @@
+"""Authenticated Streamable HTTP bridge to Home Assistant."""
+import os
+import secrets
+from typing import Any
+
+import httpx
+from mcp.server.fastmcp import FastMCP
+from mcp.server.transport_security import TransportSecuritySettings
+from starlette.responses import JSONResponse
+
+HA_URL = os.getenv("HA_URL", "http://127.0.0.1:8123").rstrip("/")
+HA_TOKEN = os.getenv("HA_TOKEN", "")
+MCP_API_KEY = os.getenv("MCP_API_KEY", "")
+mcp = FastMCP("Home Assistant", stateless_http=True, json_response=True,
+    transport_security=TransportSecuritySettings(enable_dns_rebinding_protection=False))
+
+async def ha_request(method: str, path: str, data: dict | None = None) -> Any:
+    if not HA_TOKEN:
+        raise ValueError("Set the HA_TOKEN Space secret to a Home Assistant long-lived token.")
+    async with httpx.AsyncClient(timeout=45, trust_env=False) as client:
+        response = await client.request(method, HA_URL + "/api/" + path,
+            headers={"Authorization": "Bearer " + HA_TOKEN}, json=data)
+    if response.is_error:
+        raise ValueError(f"Home Assistant returned HTTP {response.status_code}.")
+    return response.json()
+
+@mcp.tool()
+async def list_entities(domain: str | None = None) -> list[dict]:
+    """List actual entity IDs, states and attributes. Optionally filter by domain (light, climate, etc.)."""
+    states = await ha_request("GET", "states")
+    return [s for s in states if domain is None or s["entity_id"].startswith(domain + ".")]
+
+@mcp.tool()
+async def get_entity_state(entity_id: str) -> dict:
+    """Read an entity's current state and attributes using its actual entity ID."""
+    validate_name(entity_id, dotted=True)
+    return await ha_request("GET", "states/" + entity_id)
+
+@mcp.tool()
+async def list_services() -> list[dict]:
+    """Discover available HA services and their parameters before controlling devices."""
+    return await ha_request("GET", "services")
+
+@mcp.tool()
+async def call_service(domain: str, service: str, service_data: dict[str, Any] | None = None) -> Any:
+    """Execute a Home Assistant service. This changes devices or automations. Use actual service names and entity IDs discovered by the read tools; service_data is the HA JSON body, e.g. {"entity_id":"light.room"}. No device whitelist is applied."""
+    validate_name(domain)
+    validate_name(service)
+    return await ha_request("POST", f"services/{domain}/{service}", service_data or {})
+
+def validate_name(value: str, dotted: bool = False):
+    import re
+    pattern = r"[a-z0-9_]+\.[a-z0-9_]+" if dotted else r"[a-z0-9_]+"
+    if not re.fullmatch(pattern, value):
+        raise ValueError("Invalid Home Assistant identifier.")
+
+class BearerAuth:
+    def __init__(self, app):
+        self.app = app
+
+    async def __call__(self, scope, receive, send):
+        if scope["type"] == "http":
+            if not MCP_API_KEY:
+                response = JSONResponse({"error": "MCP is disabled until MCP_API_KEY is configured"}, status_code=503)
+                return await response(scope, receive, send)
+            headers = dict(scope["headers"])
+            actual = headers.get(b"authorization", b"")
+            expected = ("Bearer " + MCP_API_KEY).encode()
+            if not secrets.compare_digest(actual, expected):
+                response = JSONResponse({"error": "Unauthorized"}, status_code=401,
+                    headers={"WWW-Authenticate": "Bearer"})
+                return await response(scope, receive, send)
+        await self.app(scope, receive, send)
+
+app = BearerAuth(mcp.streamable_http_app())

nginx.conf

@@ -0,0 +1,27 @@
+worker_processes 1;
+pid /tmp/nginx.pid;
+error_log /dev/stderr warn;
+events { worker_connections 1024; }
+http {
+    access_log off;
+    client_max_body_size 100m;
+    map $http_upgrade $connection_upgrade {
+        default upgrade;
+        '' close;
+    }
+    server {
+        listen 7860;
+        location = /mcp { proxy_pass http://127.0.0.1:8000; include /etc/nginx/mcp-proxy.conf; }
+        location /mcp/ { proxy_pass http://127.0.0.1:8000; include /etc/nginx/mcp-proxy.conf; }
+        location / {
+            proxy_pass http://127.0.0.1:8123;
+            proxy_http_version 1.1;
+            proxy_set_header Host $http_host;
+            proxy_set_header Upgrade $http_upgrade;
+            proxy_set_header Connection $connection_upgrade;
+            proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+            proxy_set_header X-Forwarded-Proto https;
+            proxy_read_timeout 3600s;
+        }
+    }
+}

scripts/backup-homeassistant.py

@@ -48,21 +48,24 @@ def backup(config: Path) -> None:
 
 
 def restore(config: Path) -> None:
+    from huggingface_hub.errors import EntryNotFoundError
     try:
         _, repo_id, repo_type, token = hub_api()
         from huggingface_hub import hf_hub_download
         archive = hf_hub_download(repo_id=repo_id, filename=ARCHIVE_NAME,
                                   repo_type=repo_type, token=token, force_download=True)
-    except Exception as exc:
-        print(f"No Hub backup restored: {exc}", file=sys.stderr, flush=True)
+    except EntryNotFoundError:
+        print("No existing Hub snapshot; starting a new configuration.", flush=True)
         return
+    except Exception as exc:
+        raise RuntimeError("Hub restore failed; refusing to overwrite the remote backup with a fresh configuration.") from exc
     config.mkdir(parents=True, exist_ok=True)
     with tarfile.open(archive, "r:gz") as tar:
         root = config.resolve()
         for member in tar.getmembers():
             target = (config / member.name).resolve()
             if root not in target.parents: raise RuntimeError(f"Unsafe backup path: {member.name}")
-        tar.extractall(config)
+        tar.extractall(config, filter="data")
     print(f"Restored {ARCHIVE_NAME} into {config}", flush=True)
 
 

scripts/run-space.py

@@ -0,0 +1,96 @@
+"""Prepare HA configuration and supervise the three Space services."""
+import os
+from pathlib import Path
+import re
+import shutil
+import signal
+import subprocess
+import time
+
+CONFIG = Path(os.getenv("HOME_ASSISTANT_CONFIG", "/data/home-assistant"))
+BACKUP = "/usr/local/bin/backup-homeassistant.py"
+
+
+def prepare_http(text):
+    # Change only the inline http mapping, preserving !include and other YAML elsewhere.
+    match = re.search(r"(?m)^http:[^\n]*(?:\n(?:[ \t]+[^\n]*|#[^\n]*|[ \t]*))*", text)
+    block = match.group(0) if match else "http:"
+    if block.splitlines()[0].strip() != "http:":
+        raise ValueError("http must be an inline YAML mapping in configuration.yaml; move its settings there before deployment.")
+    block = re.sub(r"(?m)^  (server_port|use_x_forwarded_for):[^\n]*\n?", "", block)
+    block = re.sub(r"(?m)^  trusted_proxies:[^\n]*(?:\n[ \t]{4,}[^\n]*)*\n?", "", block)
+    block = block.rstrip() + "\n  server_port: 8123\n  use_x_forwarded_for: true\n  trusted_proxies:\n    - 127.0.0.1\n    - ::1\n    - 10.0.0.0/8\n"
+    if match:
+        return text[:match.start()] + block + text[match.end():]
+    return text.rstrip() + "\n\n" + block
+
+
+def backup(action):
+    result = subprocess.run(["python3", BACKUP, action, "--config", str(CONFIG)], timeout=120)
+    if result.returncode:
+        print(f"Backup operation {action} failed; check Hub secrets and permissions.", flush=True)
+
+
+def main():
+    CONFIG.mkdir(parents=True, exist_ok=True)
+    config_file = CONFIG / "configuration.yaml"
+    if not config_file.exists():
+        backup("restore")
+    text = config_file.read_text() if config_file.exists() else "default_config:\n"
+    config_file.write_text(prepare_http(text))
+    components = CONFIG / "custom_components"
+    components.mkdir(exist_ok=True)
+    for source in Path("/opt/ha-custom-components").iterdir():
+        if not (components / source.name).exists():
+            shutil.copytree(source, components / source.name)
+
+    stopping = False
+    def stop(signum, frame):
+        nonlocal stopping
+        stopping = True
+    signal.signal(signal.SIGTERM, stop)
+    signal.signal(signal.SIGINT, stop)
+    processes = []
+    exit_code = 0
+    try:
+        for command in (
+            ["hass", "--config", str(CONFIG)],
+            ["/opt/mcp-venv/bin/python", "-m", "uvicorn", "server:app", "--app-dir", "/opt/mcp-server", "--host", "127.0.0.1", "--port", "8000", "--no-access-log"],
+            ["nginx", "-g", "daemon off;"],
+        ):
+            processes.append(subprocess.Popen(command, start_new_session=True))
+        next_backup = time.monotonic() + 60
+        enabled = bool(os.getenv("HF_TOKEN") and os.getenv("BACKUP_REPO_ID"))
+        while not stopping:
+            for process in processes:
+                if process.poll() is not None:
+                    print(f"Service exited with code {process.returncode}; stopping container.", flush=True)
+                    exit_code = process.returncode or 1
+                    stopping = True
+                    break
+            if enabled and not stopping and time.monotonic() >= next_backup:
+                try:
+                    backup("backup")
+                except Exception as exc:
+                    print(f"Periodic backup failed: {type(exc).__name__}", flush=True)
+                next_backup = time.monotonic() + 600
+            time.sleep(1)
+    finally:
+        for process in reversed(processes):
+            if process.poll() is None:
+                os.killpg(process.pid, signal.SIGTERM)
+        for process in processes:
+            try:
+                process.wait(timeout=25)
+            except subprocess.TimeoutExpired:
+                os.killpg(process.pid, signal.SIGKILL)
+                process.wait()
+        if os.getenv("HF_TOKEN") and os.getenv("BACKUP_REPO_ID"):
+            try:
+                backup("backup")
+            except Exception as exc:
+                print(f"Shutdown backup failed: {type(exc).__name__}", flush=True)
+    return exit_code
+
+if __name__ == "__main__":
+    raise SystemExit(main())

scripts/start-homeassistant

@@ -1,63 +1,3 @@
 #!/bin/sh
 set -eu
-
-CONFIG_DIR="${HOME_ASSISTANT_CONFIG:-/data/home-assistant}"
-CUSTOM_COMPONENT="/opt/ha-custom-components/xiaomi_miot"
-CONFIG_FILE="$CONFIG_DIR/configuration.yaml"
-
-mkdir -p "$CONFIG_DIR/custom_components"
-if [ ! -f "$CONFIG_FILE" ]; then
-  python3 /usr/local/bin/backup-homeassistant.py restore --config "$CONFIG_DIR" || true
-fi
-
-if [ ! -d "$CONFIG_DIR/custom_components/xiaomi_miot" ]; then
-  cp -a "$CUSTOM_COMPONENT" "$CONFIG_DIR/custom_components/xiaomi_miot"
-fi
-
-if [ ! -f "$CONFIG_FILE" ]; then
-  cat > "$CONFIG_FILE" <<'YAML'
-default_config:
-
-http:
-  server_port: 7860
-  use_x_forwarded_for: true
-  trusted_proxies:
-    - 10.0.0.0/8
-YAML
-elif ! grep -q 'use_x_forwarded_for:' "$CONFIG_FILE"; then
-  if grep -q '^  server_port: 7860' "$CONFIG_FILE"; then
-    sed -i '/^  server_port: 7860/a\  use_x_forwarded_for: true\n  trusted_proxies:\n    - 10.0.0.0/8' "$CONFIG_FILE"
-  else
-    cat >> "$CONFIG_FILE" <<'YAML'
-
-http:
-  server_port: 7860
-  use_x_forwarded_for: true
-  trusted_proxies:
-    - 10.0.0.0/8
-YAML
-  fi
-fi
-
-if [ -n "${HF_TOKEN:-}" ] && [ -n "${BACKUP_REPO_ID:-}" ]; then
-  (
-    while sleep 600; do
-      python3 /usr/local/bin/backup-homeassistant.py backup --config "$CONFIG_DIR" || true
-    done
-  ) &
-  BACKUP_PID=$!
-else
-  BACKUP_PID=""
-fi
-
-cleanup() {
-  if [ -n "$BACKUP_PID" ]; then
-    kill "$BACKUP_PID" 2>/dev/null || true
-  fi
-  if [ -n "${HF_TOKEN:-}" ] && [ -n "${BACKUP_REPO_ID:-}" ]; then
-    python3 /usr/local/bin/backup-homeassistant.py backup --config "$CONFIG_DIR" || true
-  fi
-}
-trap cleanup EXIT TERM INT
-
-exec hass --config "$CONFIG_DIR"
+exec python3 /usr/local/bin/run-space.py