ha-mcp-dev 7.6.0.dev650__tar.gz → 7.6.0.dev652__tar.gz

{ha_mcp_dev-7.6.0.dev650/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.6.0.dev652}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.6.0.dev650
+Version: 7.6.0.dev652
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -269,7 +269,9 @@ These tools also require feature flags: `HAMCP_ENABLE_FILESYSTEM_TOOLS=true` (fi
 
 To add manually: open **HACS** > **Integrations** > three-dot menu > **Custom repositories** > add `https://github.com/homeassistant-ai/ha-mcp` (category: Integration) > **Download**.
 
-After installing, restart Home Assistant. Then open **Settings** > **Devices & Services** > **Add Integration** and search for **HA MCP Tools**.
+After installing, restart Home Assistant. Then open **Settings** > **Devices & Services** > **Add Integration** and search for **Home Assistant MCP Server Custom Component**.
+
+On **Home Assistant OS / Supervised**, the integration offers to add the add-on repository and install and start the **Home Assistant MCP Server** add-on for you — no need to add the add-on repository by hand. On **Container / Core** installs (no Supervisor) there is no add-on; run the server via Docker or pip and the integration just sets up the file/YAML services.
 
 ### Install manually
 

{ha_mcp_dev-7.6.0.dev650 → ha_mcp_dev-7.6.0.dev652}/README.md

@@ -239,7 +239,9 @@ These tools also require feature flags: `HAMCP_ENABLE_FILESYSTEM_TOOLS=true` (fi
 
 To add manually: open **HACS** > **Integrations** > three-dot menu > **Custom repositories** > add `https://github.com/homeassistant-ai/ha-mcp` (category: Integration) > **Download**.
 
-After installing, restart Home Assistant. Then open **Settings** > **Devices & Services** > **Add Integration** and search for **HA MCP Tools**.
+After installing, restart Home Assistant. Then open **Settings** > **Devices & Services** > **Add Integration** and search for **Home Assistant MCP Server Custom Component**.
+
+On **Home Assistant OS / Supervised**, the integration offers to add the add-on repository and install and start the **Home Assistant MCP Server** add-on for you — no need to add the add-on repository by hand. On **Container / Core** installs (no Supervisor) there is no add-on; run the server via Docker or pip and the integration just sets up the file/YAML services.
 
 ### Install manually
 

{ha_mcp_dev-7.6.0.dev650 → ha_mcp_dev-7.6.0.dev652}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.6.0.dev650"
+version = "7.6.0.dev652"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"
@@ -132,7 +132,6 @@ ignore = [
     "RUF001",  # ambiguous unicode — HA entity names use degree symbols etc
     "RUF003",  # ambiguous unicode in comments
     "RUF010",  # explicit f-string type conversion — str(x) is clearer than !s
-    "F841",    # unused variable — too many to fix now
     "RUF059",  # unused unpacked variable
     "SIM118",  # in-dict-keys — style preference
     "PIE810",  # multiple-starts-ends-with — style preference

{ha_mcp_dev-7.6.0.dev650 → ha_mcp_dev-7.6.0.dev652}/src/ha_mcp/__main__.py

@@ -3,14 +3,15 @@
 import sys
 
 if sys.version_info < (3, 13):  # noqa: UP036 — uvx can bypass requires-python and run on 3.12
-    print(
+    # Write directly to stderr (not print) so this import-time version gate
+    # fires before any 3.13-only syntax in the rest of the module is parsed.
+    sys.stderr.write(
         f"ERROR: ha-mcp requires Python 3.13+, but you are running Python "
         f"{sys.version_info.major}.{sys.version_info.minor}.\n"
         "If using uvx, add '--python 3.13' to your config args:\n"
         '  "args": ["--python", "3.13", "--refresh", "ha-mcp@latest"]\n'
         "Or install Python 3.13: brew install python@3.13 (macOS) / "
-        "sudo apt install python3.13 (Linux)",
-        file=sys.stderr,
+        "sudo apt install python3.13 (Linux)\n"
     )
     sys.exit(1)
 
@@ -496,6 +497,8 @@ async def _cancel_tasks(*tasks: asyncio.Task) -> None:
             try:
                 await task
             except asyncio.CancelledError:
+                # Expected: we just cancelled this task, swallow its
+                # CancelledError so remaining tasks still get awaited.
                 pass
 
 
@@ -525,6 +528,8 @@ async def _run_with_shutdown(server_coro: Coroutine[Any, Any, Any]) -> None:
             except TimeoutError:
                 logger.warning("Server did not stop within timeout")
             except asyncio.CancelledError:
+                # Expected: we just cancelled server_task above; swallow its
+                # CancelledError so shutdown can proceed to cleanup.
                 pass
 
     except asyncio.CancelledError:

{ha_mcp_dev-7.6.0.dev650 → ha_mcp_dev-7.6.0.dev652}/src/ha_mcp/client/rest_client.py

@@ -711,6 +711,7 @@ class HomeAssistantClient:
                     if isinstance(msg, str) and msg:
                         message = msg
             except json.JSONDecodeError:
+                # Body wasn't a JSON envelope; fall back to raw text below.
                 pass
             if not message:
                 message = text_body.strip() or response.reason_phrase or "<empty body>"

{ha_mcp_dev-7.6.0.dev650 → ha_mcp_dev-7.6.0.dev652}/src/ha_mcp/client/websocket_client.py

@@ -352,6 +352,8 @@ class HomeAssistantWebSocketClient:
             try:
                 await self.background_task
             except asyncio.CancelledError:
+                # Expected: we just cancelled the task above; swallow the
+                # propagated CancelledError so disconnect can finish cleanly.
                 pass
             finally:
                 self.background_task = None

{ha_mcp_dev-7.6.0.dev650 → ha_mcp_dev-7.6.0.dev652}/src/ha_mcp/client/websocket_listener.py

@@ -87,6 +87,7 @@ class WebSocketListenerService:
             try:
                 await self.listener_task
             except asyncio.CancelledError:
+                # Expected: awaiting a cancelled task re-raises CancelledError.
                 pass
 
         if self.cleanup_task and not self.cleanup_task.done():
@@ -94,6 +95,7 @@ class WebSocketListenerService:
             try:
                 await self.cleanup_task
             except asyncio.CancelledError:
+                # Expected: awaiting a cancelled task re-raises CancelledError.
                 pass
 
         # Remove event handler if WebSocket client exists
@@ -164,7 +166,9 @@ class WebSocketListenerService:
             if updated_ops:
                 operations_updated = self.stats["operations_updated"]
                 if isinstance(operations_updated, int):
-                    self.stats["operations_updated"] = operations_updated + len(updated_ops)
+                    self.stats["operations_updated"] = operations_updated + len(
+                        updated_ops
+                    )
                 logger.info(f"Updated {len(updated_ops)} operations for {entity_id}")
 
         except (RuntimeError, ConnectionError, OSError) as e:
@@ -307,7 +311,6 @@ _listener_lock: asyncio.Lock | None = None
 async def get_listener_service() -> WebSocketListenerService:
     """Get the global WebSocket listener service instance."""
     global _listener_service, _listener_lock
-    import asyncio
 
     current_loop = asyncio.get_event_loop()
 
@@ -373,7 +376,12 @@ class WebSocketContextManager:
         self.service = service
         return service
 
-    async def __aexit__(self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: object) -> None:
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_val: BaseException | None,
+        exc_tb: object,
+    ) -> None:
         """Stop WebSocket listener."""
         if self.service:
             await self.service.stop()

{ha_mcp_dev-7.6.0.dev650 → ha_mcp_dev-7.6.0.dev652}/src/ha_mcp/dashboard_screenshot/capture.py

@@ -142,14 +142,14 @@ async def capture_dashboard_png(
                 context={"engine_url": engine},
                 suggestions=[
                     "Ensure the Puppet screenshot add-on (or sidecar) is "
-                    "installed and running",
+                    + "installed and running",
                     # Puppet restarts itself when navigation fails, so a
                     # missing/invalid token shows up as a dropped connection
                     # rather than an HTTP error.
                     f"If it is running, its access token is likely missing or "
                     f"invalid — {TOKEN_HINT}",
                     "Check HAMCP_DASHBOARD_SCREENSHOT_ENGINE_URL on "
-                    "Docker/Container deployments",
+                    + "Docker/Container deployments",
                 ],
             )
         )

{ha_mcp_dev-7.6.0.dev650 → ha_mcp_dev-7.6.0.dev652}/src/ha_mcp/dashboard_screenshot/provision.py

@@ -96,10 +96,11 @@ async def resolve_engine_url() -> str:
             suggestions=[
                 "Use HA OS / Supervised and install the screenshot engine add-on",
                 "Or run the engine as a sidecar and set "
-                "HAMCP_DASHBOARD_SCREENSHOT_ENGINE_URL",
+                + "HAMCP_DASHBOARD_SCREENSHOT_ENGINE_URL",
             ],
         )
     )
+    raise AssertionError("unreachable: raise_tool_error always raises")
 
 
 async def _discover_engine_url_via_supervisor() -> str:

{ha_mcp_dev-7.6.0.dev650 → ha_mcp_dev-7.6.0.dev652}/src/ha_mcp/policy/middleware.py

@@ -5,7 +5,7 @@ from __future__ import annotations
 import logging
 from collections.abc import Callable
 from datetime import UTC, datetime
-from typing import Any
+from typing import Any, NoReturn
 
 import anyio
 from anyio.to_thread import run_sync as run_in_thread
@@ -149,6 +149,7 @@ class PolicyMiddleware(Middleware):
                 name,
             )
         self._raise_pending_error(pending, rule)
+        return None  # py/mixed-returns: explicit terminal; error handlers above always raise (NoReturn), unreachable
 
     async def _wait_for_decision(
         self,
@@ -176,7 +177,7 @@ class PolicyMiddleware(Middleware):
                 await pending.wait()
 
     @staticmethod
-    def _raise_denied_error() -> None:
+    def _raise_denied_error() -> NoReturn:
         raise_tool_error(
             create_error_response(
                 ErrorCode.USER_DENIED,
@@ -189,7 +190,7 @@ class PolicyMiddleware(Middleware):
 
     def _raise_pending_error(
         self, pending: PendingApproval, rule: Rule | None = None
-    ) -> None:
+    ) -> NoReturn:
         # Time-remaining, not total TTL: an LLM that re-calls a minute
         # before expiry should see "~60s left", not the original 300s.
         remaining = max(
@@ -216,9 +217,9 @@ class PolicyMiddleware(Middleware):
                 "with the same arguments after the user approves.",
                 suggestions=[
                     "Tell the user to open the Tool Security Policies tab in "
-                    "the ha-mcp settings UI and approve the pending request.",
+                    + "the ha-mcp settings UI and approve the pending request.",
                     "Re-call this tool with the same arguments after the user "
-                    "approves.",
+                    + "approves.",
                 ],
                 context=context,
             )

{ha_mcp_dev-7.6.0.dev650 → ha_mcp_dev-7.6.0.dev652}/src/ha_mcp/server.py

@@ -47,6 +47,20 @@ _OLD_SKILL_TOOL_ALIASES = (
     "If you were going to call any of those, call this instead."
 )
 
+# Hint shipped at the top of ha_get_skill_guide responses that deliver
+# best-practice skill content directly. Smart clients that fetch the reference
+# files proactively via this tool would otherwise still receive duplicate
+# canonical content from the per-call write-tool attach — this hint tells them
+# to opt out so the same body doesn't ride along again on every subsequent
+# write. Defined here (its only consumer) rather than in util_helpers.
+_SKILL_GUIDE_MANDATORYBPS_HINT = (
+    "You now have this best-practice reference in your context. "
+    "Pass `MandatoryBPS=false` on subsequent write-tool calls in this "
+    "session (ha_config_set_automation / _script / _scene / _helper / "
+    "_dashboard / _yaml) to avoid re-receiving the canonical reference "
+    "files inline."
+)
+
 
 # Server icon configuration using GitHub-hosted images
 # These icons are bundled in packaging/mcpb/ and also available via GitHub raw URLs
@@ -1447,10 +1461,7 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
         # parsing the (potentially large) content body. Scoped to the
         # best-practice skill because that's the one the write-tool
         # MandatoryBPS param gates; other skills (if any) are unrelated.
-        from .tools.util_helpers import (
-            _HA_BEST_PRACTICES_SKILL_NAME,
-            _SKILL_GUIDE_MANDATORYBPS_HINT,
-        )
+        from .tools.util_helpers import _HA_BEST_PRACTICES_SKILL_NAME
 
         response: dict[str, Any] = {}
         if skill == _HA_BEST_PRACTICES_SKILL_NAME:

{ha_mcp_dev-7.6.0.dev650 → ha_mcp_dev-7.6.0.dev652}/src/ha_mcp/settings_ui.py

@@ -1703,9 +1703,9 @@ def build_settings_handlers(
                     ),
                     suggestions=[
                         "Include enable_beta_features=true in the same save "
-                        "payload as the sub-flag(s).",
+                        + "payload as the sub-flag(s).",
                         "Or turn on the master 'Enable beta features' toggle "
-                        "first, then enable the sub-flag(s).",
+                        + "first, then enable the sub-flag(s).",
                     ],
                     context={"rejected": beta_sub_writes},
                 ),
@@ -1874,10 +1874,10 @@ def build_settings_handlers(
                             "Supervisor helper returned ok=False with no error",
                             suggestions=[
                                 "Check the Home Assistant Supervisor logs and "
-                                "the add-on logs for the underlying failure.",
+                                + "the add-on logs for the underlying failure.",
                                 "Report this at "
-                                "https://github.com/homeassistant-ai/ha-mcp/issues "
-                                "if it persists — this indicates an internal bug.",
+                                + "https://github.com/homeassistant-ai/ha-mcp/issues "
+                                + "if it persists — this indicates an internal bug.",
                             ],
                         ),
                         status_code=500,
@@ -2575,10 +2575,10 @@ def build_settings_handlers(
                             "Supervisor helper returned ok=False with no error",
                             suggestions=[
                                 "Check the Home Assistant Supervisor logs and "
-                                "the add-on logs for the underlying failure.",
+                                + "the add-on logs for the underlying failure.",
                                 "Report this at "
-                                "https://github.com/homeassistant-ai/ha-mcp/issues "
-                                "if it persists — this indicates an internal bug.",
+                                + "https://github.com/homeassistant-ai/ha-mcp/issues "
+                                + "if it persists — this indicates an internal bug.",
                             ],
                         ),
                         status_code=500,

{ha_mcp_dev-7.6.0.dev650 → ha_mcp_dev-7.6.0.dev652}/src/ha_mcp/tools/backup.py

@@ -517,6 +517,7 @@ async def create_backup(
             context={"tool": "create_backup"},
             suggestions=["Check Home Assistant connection and backup configuration"],
         )
+        return None  # unreachable: exception_to_structured_error always raises
     finally:
         # Always disconnect WebSocket — narrow to transport errors; a
         # programming error during cleanup should still surface.
@@ -714,6 +715,7 @@ async def restore_backup(
             context={"tool": "restore_backup", "backup_id": backup_id},
             suggestions=["Check Home Assistant connection and backup availability"],
         )
+        return None  # unreachable: exception_to_structured_error always raises
     finally:
         # Always disconnect WebSocket — narrow to transport errors; a
         # programming error during cleanup should still surface.
@@ -726,6 +728,7 @@ async def restore_backup(
                     type(err).__name__,
                     err,
                 )
+    return None  # py/mixed-returns: explicit terminal; error handlers above always raise (NoReturn), unreachable
 
 
 # Valid (scope, action) combinations. Anything outside this set is
@@ -953,13 +956,13 @@ def register_backup_tools(
                     create_error_response(
                         ErrorCode.RESOURCE_NOT_FOUND,
                         f"Could not snapshot {dom}:{eid} — entity not found "
-                        "or fetch returned no config",
+                        + "or fetch returned no config",
                         context={"domain": dom, "entity_id": eid},
                         suggestions=[
                             "Verify the entity exists via the matching "
-                            "ha_config_get_* tool first",
+                            + "ha_config_get_* tool first",
                             "For helpers, pass domain='helper_<helper_type>' "
-                            "(e.g. 'helper_input_boolean')",
+                            + "(e.g. 'helper_input_boolean')",
                         ],
                     )
                 )
@@ -1053,13 +1056,13 @@ def register_backup_tools(
                     context={"backup_name": bname, "action": "restore"},
                     suggestions=[
                         "Verify the entity referenced by the backup still "
-                        "exists; restore re-POSTs to its current registry "
-                        "key",
+                        + "exists; restore re-POSTs to its current registry "
+                        + "key",
                         "Compare the captured schema vs current HA — HA "
-                        "minor versions occasionally drop/rename fields",
+                        + "minor versions occasionally drop/rename fields",
                         "Inspect the snapshot YAML via "
-                        "ha_manage_backup(scope='edits', action='view', "
-                        "backup_name=...)",
+                        + "ha_manage_backup(scope='edits', action='view', "
+                        + "backup_name=...)",
                     ],
                 )
             return {