ha-mcp-dev 9.1.0.dev3258__tar.gz → 9.1.0.dev3265__tar.gz

{ha_mcp_dev-9.1.0.dev3258 → ha_mcp_dev-9.1.0.dev3265}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 9.1.0.dev3258
+Version: 9.1.0.dev3265
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien

{ha_mcp_dev-9.1.0.dev3258 → ha_mcp_dev-9.1.0.dev3265}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.0.dev3258"
+version = "9.1.0.dev3265"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"

{ha_mcp_dev-9.1.0.dev3258 → ha_mcp_dev-9.1.0.dev3265}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.0.dev3258"
+version = "9.1.0.dev3265"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's

{ha_mcp_dev-9.1.0.dev3258 → ha_mcp_dev-9.1.0.dev3265}/src/ha_mcp/settings_ui/locales/az.json

@@ -883,7 +883,7 @@
     },
     "ha_remove_todo_item": {
       "title": "Tapşırığı çıxar",
-      "description": "Home Assistant tapşırıq siyahısından tapşırığı çıxarın."
+      "description": "Home Assistant-ın etməkli siyahısından elementləri silin."
     },
     "ha_remove_zone": {
       "title": "Zonanı çıxar",
@@ -919,7 +919,7 @@
     },
     "ha_set_todo_item": {
       "title": "Tapşırığı təyin et",
-      "description": "Home Assistant-da tapşırıq yaradın və ya yeniləyin."
+      "description": "Home Assistant-da etməkli siyahısı elementini yaradın, yeniləyin və ya yenidən sıralayın."
     },
     "ha_set_zone": {
       "title": "Zonanı təyin et",

{ha_mcp_dev-9.1.0.dev3258 → ha_mcp_dev-9.1.0.dev3265}/src/ha_mcp/settings_ui/locales/cs.json

@@ -852,7 +852,7 @@
     },
     "ha_remove_todo_item": {
       "title": "Odebrat položku úkolu",
-      "description": "Odebrat položku ze seznamu úkolů Home Assistant."
+      "description": "Odstranit položky z úkolového seznamu v Home Assistant."
     },
     "ha_remove_zone": {
       "title": "Odebrat zónu",
@@ -888,7 +888,7 @@
     },
     "ha_set_todo_item": {
       "title": "Nastavit položku úkolu",
-      "description": "Vytvořit nebo aktualizovat položku úkolu v Home Assistant."
+      "description": "Vytvořit, aktualizovat nebo změnit pořadí položky úkolu v Home Assistant."
     },
     "ha_set_zone": {
       "title": "Nastavit zónu",

{ha_mcp_dev-9.1.0.dev3258 → ha_mcp_dev-9.1.0.dev3265}/src/ha_mcp/settings_ui/locales/de.json

@@ -883,7 +883,7 @@
     },
     "ha_remove_todo_item": {
       "title": "To-do-Element entfernen",
-      "description": "Entfernt eine Aufgabe aus einer Home-Assistant-To-do-Liste."
+      "description": "Entferne Einträge aus einer Home Assistant-Todo-Liste."
     },
     "ha_remove_zone": {
       "title": "Zone entfernen",
@@ -919,7 +919,7 @@
     },
     "ha_set_todo_item": {
       "title": "To-do-Element erstellen/aktualisieren",
-      "description": "Erstellt oder aktualisiert eine Aufgabe in einer To-do-Liste."
+      "description": "Erstelle, aktualisiere oder sortiere einen Todo-Eintrag in Home Assistant neu."
     },
     "ha_set_zone": {
       "title": "Zone erstellen/aktualisieren",

{ha_mcp_dev-9.1.0.dev3258 → ha_mcp_dev-9.1.0.dev3265}/src/ha_mcp/settings_ui/locales/eo.json

@@ -852,7 +852,7 @@
     },
     "ha_remove_todo_item": {
       "title": "Forigi Farendaĵon",
-      "description": "Forigi eron el farendaĵa listo de Home Assistant."
+      "description": "Forigi erojn el taskolisto de Home Assistant."
     },
     "ha_remove_zone": {
       "title": "Forigi Zonon",
@@ -888,7 +888,7 @@
     },
     "ha_set_todo_item": {
       "title": "Agordi Farendaĵon",
-      "description": "Krei aŭ ĝisdatigi farendaĵon en Home Assistant."
+      "description": "Krei, ĝisdatigi aŭ reordigi taskeron en Home Assistant."
     },
     "ha_set_zone": {
       "title": "Agordi Zonon",

{ha_mcp_dev-9.1.0.dev3258 → ha_mcp_dev-9.1.0.dev3265}/src/ha_mcp/settings_ui/locales/es.json

@@ -883,7 +883,7 @@
     },
     "ha_remove_todo_item": {
       "title": "Eliminar tarea",
-      "description": "Elimina un elemento de una lista de tareas de Home Assistant."
+      "description": "Eliminar elementos de una lista de tareas pendientes de Home Assistant."
     },
     "ha_remove_zone": {
       "title": "Eliminar zona",
@@ -919,7 +919,7 @@
     },
     "ha_set_todo_item": {
       "title": "Definir tarea",
-      "description": "Crea o actualiza un elemento de una lista de tareas de Home Assistant."
+      "description": "Crear, actualizar o reordenar un elemento de una lista de tareas pendientes en Home Assistant."
     },
     "ha_set_zone": {
       "title": "Crear o actualizar zona",

{ha_mcp_dev-9.1.0.dev3258 → ha_mcp_dev-9.1.0.dev3265}/src/ha_mcp/settings_ui/locales/fr.json

@@ -883,7 +883,7 @@
     },
     "ha_remove_todo_item": {
       "title": "Supprimer un élément de tâche",
-      "description": "Supprime une tâche d'une liste de tâches Home Assistant."
+      "description": "Supprimer des éléments d'une liste de tâches Home Assistant."
     },
     "ha_remove_zone": {
       "title": "Supprimer la zone",
@@ -919,7 +919,7 @@
     },
     "ha_set_todo_item": {
       "title": "Créer/mettre à jour un élément de tâche",
-      "description": "Crée ou met à jour une tâche dans une liste de tâches."
+      "description": "Créer, mettre à jour ou réordonner un élément de liste de tâches dans Home Assistant."
     },
     "ha_set_zone": {
       "title": "Créer/mettre à jour la zone",

{ha_mcp_dev-9.1.0.dev3258 → ha_mcp_dev-9.1.0.dev3265}/src/ha_mcp/settings_ui/locales/it.json

@@ -883,7 +883,7 @@
     },
     "ha_remove_todo_item": {
       "title": "Rimuovi una voce dalle cose da fare",
-      "description": "Rimuove una voce da una lista delle cose da fare di Home Assistant."
+      "description": "Rimuovi elementi da un elenco di cose da fare di Home Assistant."
     },
     "ha_remove_zone": {
       "title": "Rimuovi una zona",
@@ -919,7 +919,7 @@
     },
     "ha_set_todo_item": {
       "title": "Imposta una voce delle cose da fare",
-      "description": "Crea o aggiorna una voce delle cose da fare in Home Assistant."
+      "description": "Crea, aggiorna o riordina un elemento di un elenco di cose da fare in Home Assistant."
     },
     "ha_set_zone": {
       "title": "Imposta una zona",

{ha_mcp_dev-9.1.0.dev3258 → ha_mcp_dev-9.1.0.dev3265}/src/ha_mcp/settings_ui/locales/ko.json

@@ -919,7 +919,7 @@
     },
     "ha_set_todo_item": {
       "title": "할 일 항목 설정",
-      "description": "Home Assistant에서 할 일 항목을 만들거나 수정합니다."
+      "description": "Home Assistant의 할 일 항목을 생성, 업데이트 또는 재정렬합니다."
     },
     "ha_set_zone": {
       "title": "구역 생성·수정",

{ha_mcp_dev-9.1.0.dev3258 → ha_mcp_dev-9.1.0.dev3265}/src/ha_mcp/settings_ui/locales/nl.json

@@ -852,7 +852,7 @@
     },
     "ha_remove_todo_item": {
       "title": "To-do Item Verwijderen",
-      "description": "Verwijder een item uit een Home Assistant to-do lijst."
+      "description": "Items verwijderen van een Home Assistant takenlijst."
     },
     "ha_remove_zone": {
       "title": "Zone Verwijderen",
@@ -888,7 +888,7 @@
     },
     "ha_set_todo_item": {
       "title": "To-do Item Instellen",
-      "description": "Maak een to-do item aan of werk deze bij in Home Assistant."
+      "description": "Een taak maken, bijwerken of herordenen in Home Assistant."
     },
     "ha_set_zone": {
       "title": "Zone Instellen",

{ha_mcp_dev-9.1.0.dev3258 → ha_mcp_dev-9.1.0.dev3265}/src/ha_mcp/settings_ui/locales/pl.json

@@ -852,7 +852,7 @@
     },
     "ha_remove_todo_item": {
       "title": "Usuń element listy zadań",
-      "description": "Usuń element z listy zadań Home Assistant."
+      "description": "Usuń pozycje z listy zadań Home Assistant."
     },
     "ha_remove_zone": {
       "title": "Usuń strefę",
@@ -888,7 +888,7 @@
     },
     "ha_set_todo_item": {
       "title": "Ustaw element listy zadań",
-      "description": "Utwórz lub zaktualizuj element listy zadań w Home Assistant."
+      "description": "Utwórz, zaktualizuj lub zmień kolejność pozycji na liście zadań w Home Assistant."
     },
     "ha_set_zone": {
       "title": "Ustaw strefę",

{ha_mcp_dev-9.1.0.dev3258 → ha_mcp_dev-9.1.0.dev3265}/src/ha_mcp/settings_ui/locales/ru.json

@@ -883,7 +883,7 @@
     },
     "ha_remove_todo_item": {
       "title": "Удалить задачу",
-      "description": "Удалить задачу из списка дел Home Assistant."
+      "description": "Удаление элементов из списка задач Home Assistant."
     },
     "ha_remove_zone": {
       "title": "Удалить зону",
@@ -919,7 +919,7 @@
     },
     "ha_set_todo_item": {
       "title": "Создать или изменить задачу",
-      "description": "Создать новую или обновить задачу в списке дел."
+      "description": "Создание, обновление или изменение порядка элементов списка задач в Home Assistant."
     },
     "ha_set_zone": {
       "title": "Создать или изменить зону",

{ha_mcp_dev-9.1.0.dev3258 → ha_mcp_dev-9.1.0.dev3265}/src/ha_mcp/settings_ui/locales/sv.json

@@ -852,7 +852,7 @@
     },
     "ha_remove_todo_item": {
       "title": "Ta bort att-göra-objekt",
-      "description": "Ta bort ett objekt från en Home Assistant-att-göra-lista."
+      "description": "Ta bort objekt från en att göra-lista i Home Assistant."
     },
     "ha_remove_zone": {
       "title": "Ta bort zon",
@@ -888,7 +888,7 @@
     },
     "ha_set_todo_item": {
       "title": "Ställ in att-göra-objekt",
-      "description": "Skapa eller uppdatera ett att-göra-objekt i Home Assistant."
+      "description": "Skapa, uppdatera eller ändra ordning på ett att göra-objekt i Home Assistant."
     },
     "ha_set_zone": {
       "title": "Ställ in zon",

{ha_mcp_dev-9.1.0.dev3258 → ha_mcp_dev-9.1.0.dev3265}/src/ha_mcp/settings_ui/locales/zh-Hans.json

@@ -883,7 +883,7 @@
     },
     "ha_remove_todo_item": {
       "title": "删除待办条目",
-      "description": "从 Home Assistant 待办清单中删除条目。"
+      "description": "从 Home Assistant 待办事项列表中删除项目。"
     },
     "ha_remove_zone": {
       "title": "删除区域",
@@ -919,7 +919,7 @@
     },
     "ha_set_todo_item": {
       "title": "设置待办条目",
-      "description": "在 Home Assistant 中创建或更新待办条目。"
+      "description": "在 Home Assistant 中创建、更新或重新排序待办事项。"
     },
     "ha_set_zone": {
       "title": "设置区域",

{ha_mcp_dev-9.1.0.dev3258 → ha_mcp_dev-9.1.0.dev3265}/src/ha_mcp/settings_ui/locales/zh-Hant.json

@@ -888,7 +888,7 @@
     },
     "ha_set_todo_item": {
       "title": "設定待辦事項",
-      "description": "在 Home Assistant 中建立或更新待辦事項。"
+      "description": "在 Home Assistant 中建立、更新或重新排序待辦事項項目。"
     },
     "ha_set_zone": {
       "title": "設定區域",

{ha_mcp_dev-9.1.0.dev3258 → ha_mcp_dev-9.1.0.dev3265}/src/ha_mcp/tools/backup_access.py

@@ -1,8 +1,6 @@
 """Argument validation and access checks for explicit backup tool actions."""
 
 import json
-import posixpath
-import urllib.parse
 from typing import Any
 
 from ha_mcp._vendor.fastmcp.exceptions import ToolError
@@ -10,6 +8,7 @@ from ha_mcp._vendor.fastmcp.exceptions import ToolError
 from ..config import Settings, get_global_settings
 from ..errors import ErrorCode, create_error_response
 from .helpers import raise_tool_error
+from .util_helpers import normalized_path, supervisor_path
 
 _VALID_COMBOS: set[tuple[str, str]] = {
     ("snapshot", "create"),
@@ -145,22 +144,11 @@ _SNAPSHOT_WS_ACTIONS: dict[str, str] = {
 }
 
 
-def _normalized_path(path: str) -> str:
-    """Fold percent-escapes, ``//``, ``.`` and ``..`` so an equivalent spelling
-    cannot slip past (HTTP clients decode ``%62ackups`` to ``backups``).
-
-    Leading slashes are stripped first: POSIX normpath keeps exactly two.
-    """
-    decoded = urllib.parse.unquote(path.split("?", 1)[0])
-    stripped = decoded.strip().lower().lstrip("/")
-    return posixpath.normpath("/" + stripped)
-
-
 def _supervisor_backup_action(endpoint: Any, method: Any) -> str | None:
     """Classify a request against Supervisor's ``/backups`` API."""
     if not isinstance(endpoint, str):
         return None
-    path = _normalized_path(endpoint)
+    path = supervisor_path(endpoint)
     if path != "/backups" and not path.startswith("/backups/"):
         return None
     verb = str(method).strip().lower()
@@ -184,7 +172,7 @@ def _snapshot_route_action(
     rest_path: str | None,
 ) -> str | None:
     if rest_path is not None:
-        parts = _normalized_path(rest_path).split("/")
+        parts = normalized_path(rest_path).split("/")
         if len(parts) == 4 and parts[1] == "services":
             return _service_action(parts[2], parts[3])
         if len(parts) > 2 and parts[1] == "hassio":

{ha_mcp_dev-9.1.0.dev3258 → ha_mcp_dev-9.1.0.dev3265}/src/ha_mcp/tools/tools_code.py

@@ -44,7 +44,7 @@ from ..errors import ErrorCode, create_error_response
 from .backup_access import snapshot_route_refusal
 from .helpers import log_tool_usage, raise_tool_error
 from .tool_hints import write_hints
-from .util_helpers import BLOCKED_WS_WRITE_COMMANDS
+from .util_helpers import raw_ws_refusal
 
 logger = logging.getLogger(__name__)
 
@@ -835,10 +835,10 @@ class _SandboxBridge:
         code is dynamic and may pass non-dict values; the runtime guard
         below converts that into an error dict.
 
-        Commands in ``BLOCKED_WS_WRITE_COMMANDS`` are rejected: they rewrite
-        state with no sandbox use case (``config/core/update``) or skip their
-        wrapping tool's validation (dashboard collision, registry invariants).
-        Full-snapshot backup commands follow the backup controls.
+        Commands that ``raw_ws_refusal`` refuses are rejected: writes with no
+        sandbox use case or that skip their wrapping tool's validation, and
+        credential, user and host SSH-key management. Full-snapshot backup
+        commands follow the backup controls.
         """
         if self._over_invocation_limit():
             return {
@@ -849,17 +849,9 @@ class _SandboxBridge:
         msg_type = message.get("type")
         if not isinstance(msg_type, str):
             return {"error": "ws_send(message) requires a 'type' field"}
-        if msg_type in BLOCKED_WS_WRITE_COMMANDS:
+        if ws_refusal := raw_ws_refusal(msg_type, message, sandbox=True):
             logger.info("sandbox.ws_send.blocked type=%r", msg_type)
-            return {
-                "error": (
-                    f"WebSocket command {msg_type!r} is blocked from the "
-                    "sandbox. Use the corresponding wrapping tool via "
-                    "call_tool (e.g. ha_config_set_dashboard, "
-                    "ha_set_area_or_floor, ha_set_device, ha_set_entity) "
-                    "so validation runs."
-                )
-            }
+            return {"error": ws_refusal.as_text()}
         if refusal := snapshot_route_refusal(ws_command=msg_type, ws_params=message):
             return {"error": refusal}
         logger.debug("sandbox.ws_send type=%r", msg_type)

{ha_mcp_dev-9.1.0.dev3258 → ha_mcp_dev-9.1.0.dev3265}/src/ha_mcp/tools/tools_service.py

@@ -60,8 +60,8 @@ from .response_helpers import compact_service_result, project_entity_record
 from .tool_hints import read_only_hints, write_hints
 from .util_helpers import (
     _SERVICE_TO_STATE,
-    BLOCKED_WS_WRITE_COMMANDS,
     is_single_entity_target,
+    raw_ws_refusal,
 )
 from .ws_waiters import wait_for_state_change
 
@@ -1320,16 +1320,6 @@ class ServiceTools:
                     parameter="ws_command",
                 )
             )
-        if command_type.lower() in BLOCKED_WS_WRITE_COMMANDS:
-            raise_tool_error(
-                create_validation_error(
-                    f"ws_command '{command_type}' mutates persistent state that a "
-                    "dedicated tool guards with backups and conflict checks. Use "
-                    "the corresponding ha-mcp tool (e.g. ha_config_set_dashboard, "
-                    "ha_set_area_or_floor, ha_remove_entity) instead.",
-                    parameter="ws_command",
-                )
-            )
         command_params = (
             _parse_json_dict_param(
                 data, type_error_message="ws_command data must be a JSON object"
@@ -1346,6 +1336,14 @@ class ServiceTools:
                     parameter="data",
                 )
             )
+        if refusal := raw_ws_refusal(command_type, command_params):
+            raise_tool_error(
+                create_validation_error(
+                    refusal.message,
+                    parameter="ws_command",
+                    suggestions=refusal.suggestions,
+                )
+            )
         # send_websocket_message returns a {"success": ...} dict for anything
         # HA answered with, which the result-shape check below turns into a
         # structured error. A dead transport raises instead (#1947), and this

{ha_mcp_dev-9.1.0.dev3258 → ha_mcp_dev-9.1.0.dev3265}/src/ha_mcp/tools/util_helpers.py

@@ -5,7 +5,10 @@ This module provides common helper functions used across multiple tool registrat
 """
 
 import logging
-from typing import Any
+import posixpath
+import urllib.parse
+from collections.abc import Mapping
+from typing import Any, NamedTuple
 
 from ..client.rest_client import (
     HomeAssistantAPIError,
@@ -107,9 +110,8 @@ def unwrap_service_response(result: dict[str, Any]) -> dict[str, Any]:
 # wrapping MCP tool's validation (auto-backup, config-hash optimistic locking,
 # registry invariant checks), or that have no escape-hatch-appropriate use case
 # (`config/core/update` rewrites the installation's location/timezone/currency/
-# lat-long). Shared by the code sandbox's `ws_send` bridge (tools_code.py) and
-# ha_call_service's `ws_command` escape hatch (tools_service.py) so the two raw
-# WebSocket surfaces stay in lockstep. Registry deletion command names differ on
+# lat-long). Both raw WebSocket surfaces enforce it through `raw_ws_refusal()`
+# below, so they stay in lockstep. Registry deletion command names differ on
 # HA Core: device deletion is `remove_config_entry` and entity deletion is
 # `remove` (not `delete`) -- ha_remove_device / ha_remove_entity emit those.
 BLOCKED_WS_WRITE_COMMANDS: frozenset[str] = frozenset(
@@ -151,6 +153,135 @@ BLOCKED_WS_WRITE_COMMANDS: frozenset[str] = frozenset(
 )
 
 
+# WebSocket commands that mint, list or revoke credentials, or manage users and
+# their passwords (`auth/long_lived_access_token` answers with a brand-new
+# long-lived token in plain text). A raw escape hatch has no use case that
+# needs them, and their replies would land verbatim in the model context and its
+# transcript. Matched by prefix so a credential command added to HA Core later
+# is refused by default; `auth/current_user` (whoami) is the one read that stays
+# open.
+_CREDENTIAL_WS_PREFIXES: tuple[str, ...] = (
+    "auth/",
+    "config/auth/",
+    "config/auth_provider/",
+)
+_CREDENTIAL_WS_ALLOWED: frozenset[str] = frozenset({"auth/current_user"})
+# Supervisor endpoints reachable through Core's `supervisor/api` relay with the
+# same effect: `/auth/*` lists users and resets their passwords, and
+# `/os/ssh/authorized_keys` adds a host SSH key. Each covers its subtree.
+_CREDENTIAL_SUPERVISOR_ENDPOINTS: tuple[str, ...] = (
+    "/auth",
+    "/os/ssh/authorized_keys",
+)
+
+
+def normalized_path(path: str) -> str:
+    """Fold percent-escapes, ``//``, ``.`` and ``..`` so an equivalent spelling
+    cannot slip past (HTTP clients decode ``%62ackups`` to ``backups``).
+
+    Leading slashes are stripped first: POSIX normpath keeps exactly two.
+    """
+    decoded = urllib.parse.unquote(path.split("?", 1)[0])
+    stripped = decoded.strip().lower().lstrip("/")
+    return posixpath.normpath("/" + stripped)
+
+
+def supervisor_path(endpoint: str) -> str:
+    """``normalized_path`` of a Supervisor endpoint, with the ``/v2`` mount folded off.
+
+    Supervisor mounts the same handlers again under ``/v2`` when its
+    supervisor_v2_api feature flag is on (its own security middleware matches
+    both with ``^(?:/v2)?``), and the flag itself can be switched on through
+    ``supervisor/api``. Every guard on a Supervisor path classifies this form.
+    """
+    path = normalized_path(endpoint)
+    if path == "/v2" or path.startswith("/v2/"):
+        path = path[3:] or "/"
+    return path
+
+
+def is_credential_ws_command(
+    command: str, params: Mapping[str, Any] | None = None
+) -> bool:
+    """True when ``command`` (with its message ``params``) mints, lists or
+    revokes credentials, manages users, or adds host SSH keys."""
+    normalized = command.strip().lower()
+    if normalized == "supervisor/api":
+        endpoint = (params or {}).get("endpoint")
+        if not isinstance(endpoint, str):
+            return False
+        path = supervisor_path(endpoint)
+        return any(
+            path == root or path.startswith(root + "/")
+            for root in _CREDENTIAL_SUPERVISOR_ENDPOINTS
+        )
+    if normalized in _CREDENTIAL_WS_ALLOWED:
+        return False
+    return normalized.startswith(_CREDENTIAL_WS_PREFIXES)
+
+
+class WsRefusal(NamedTuple):
+    """Why a raw WebSocket surface refuses a command, and what to do instead."""
+
+    message: str
+    suggestions: list[str]
+
+    def as_text(self) -> str:
+        return " ".join([self.message, *self.suggestions])
+
+
+_POLICY_REFUSAL_SUGGESTIONS: list[str] = [
+    (
+        "This is a fixed policy refusal, not an input error: no other spelling, "
+        "parameter or ha-mcp tool sends it."
+    ),
+    (
+        "Ask the user to make the change in the Home Assistant UI (Profile > "
+        "Security for tokens, Settings > People for users and passwords)."
+    ),
+]
+
+
+def raw_ws_refusal(
+    command: str,
+    params: Mapping[str, Any] | None = None,
+    *,
+    sandbox: bool = False,
+) -> WsRefusal | None:
+    """Why a raw WebSocket surface refuses ``command``, or ``None`` to send it.
+
+    One rule set for ha_call_service's ``ws_command`` (``sandbox=False``) and the
+    Code Mode ``ws_send`` bridge (``sandbox=True``), worded for each surface.
+    ``params`` are the message fields besides ``type``; ``supervisor/api`` is
+    judged by its ``endpoint``.
+    """
+    if command.strip().lower() in BLOCKED_WS_WRITE_COMMANDS:
+        if sandbox:
+            return WsRefusal(
+                f"WebSocket command {command!r} is blocked from the sandbox.",
+                [
+                    "Use the corresponding wrapping tool via call_tool (e.g. "
+                    "ha_config_set_dashboard, ha_set_area_or_floor, "
+                    "ha_set_device, ha_set_entity) so validation runs."
+                ],
+            )
+        return WsRefusal(
+            f"ws_command '{command}' mutates persistent state that a "
+            "dedicated tool guards with backups and conflict checks.",
+            [
+                "Use the corresponding ha-mcp tool (e.g. ha_config_set_dashboard, "
+                "ha_set_area_or_floor, ha_remove_entity) instead."
+            ],
+        )
+    if is_credential_ws_command(command, params):
+        return WsRefusal(
+            f"WebSocket command {command!r} is refused by policy: it mints, "
+            "lists or revokes credentials, manages users, or adds host SSH keys.",
+            list(_POLICY_REFUSAL_SUGGESTIONS),
+        )
+    return None
+
+
 # Fields surfaced from each repair issue. Includes `ignored` / `dismissed_version`
 # so callers can distinguish active vs. user-dismissed repairs when both are
 # returned (e.g., `include_dismissed_repairs=True`).