ha-mcp-dev 7.6.0.dev642__tar.gz → 7.6.0.dev644__tar.gz

{ha_mcp_dev-7.6.0.dev642/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.6.0.dev644}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.6.0.dev642
+Version: 7.6.0.dev644
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -69,7 +69,7 @@ Dynamic: license-file
 *No paid subscription required.* Click on your operating system:
 
 <p>
-<a href="https://homeassistant-ai.github.io/ha-mcp/guide-macos/"><img src="https://img.shields.io/badge/Setup_Guide_for_macOS-000000?style=for-the-badge&logo=apple&logoColor=white" alt="Setup Guide for macOS" height="120"></a>&nbsp;&nbsp;&nbsp;&nbsp;<a href="https://homeassistant-ai.github.io/ha-mcp/guide-windows/"><img src="https://img.shields.io/badge/Setup_Guide_for_Windows-0078D6?style=for-the-badge&logo=windows&logoColor=white" alt="Setup Guide for Windows" height="120"></a>
+<a href="https://homeassistant-ai.github.io/ha-mcp/guide-macos/"><img src="https://img.shields.io/badge/Setup_Guide_for_macOS-000000?style=for-the-badge&logo=apple&logoColor=white" alt="Setup Guide for macOS" height="120"></a>&nbsp;&nbsp;&nbsp;&nbsp;<a href="https://homeassistant-ai.github.io/ha-mcp/guide-linux/"><img src="https://img.shields.io/badge/Setup_Guide_for_Linux-FCC624?style=for-the-badge&logo=linux&logoColor=black" alt="Setup Guide for Linux" height="120"></a>&nbsp;&nbsp;&nbsp;&nbsp;<a href="https://homeassistant-ai.github.io/ha-mcp/guide-windows/"><img src="https://img.shields.io/badge/Setup_Guide_for_Windows-0078D6?style=for-the-badge&logo=windows&logoColor=white" alt="Setup Guide for Windows" height="120"></a>
 </p>
 
 ### Quick install (~5 min)
@@ -89,6 +89,33 @@ You're now connected to the demo environment! [Connect your own Home Assistant
 
 </details>
 
+<details>
+<summary><b>🐧 Linux</b></summary>
+
+Anthropic doesn't ship Claude Desktop for Linux, so pick one path:
+
+**Claude Desktop** — free, via the community build:
+
+1. Install the community [Claude Desktop for Linux](https://github.com/aaddrick/claude-desktop-debian) build and sign in with a free [claude.ai](https://claude.ai) account
+2. Open **Terminal** and run:
+   ```sh
+   curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-linux.sh | sh
+   ```
+3. Restart Claude Desktop, then ask: **"Can you see my Home Assistant?"**
+
+**Claude Code** — official CLI, requires a paid Claude plan:
+
+1. Install Claude Code: `curl -fsSL https://claude.ai/install.sh | bash`
+2. Configure ha-mcp, then run `claude`:
+   ```sh
+   curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install.sh | sh -s -- --claude-code
+   ```
+3. Start `claude`, run `/mcp` to confirm, then ask: **"Can you see my Home Assistant?"**
+
+[Full Linux guide →](https://homeassistant-ai.github.io/ha-mcp/guide-linux/)
+
+</details>
+
 <details>
 <summary><b>🪟 Windows</b></summary>
 

{ha_mcp_dev-7.6.0.dev642 → ha_mcp_dev-7.6.0.dev644}/README.md

@@ -39,7 +39,7 @@
 *No paid subscription required.* Click on your operating system:
 
 <p>
-<a href="https://homeassistant-ai.github.io/ha-mcp/guide-macos/"><img src="https://img.shields.io/badge/Setup_Guide_for_macOS-000000?style=for-the-badge&logo=apple&logoColor=white" alt="Setup Guide for macOS" height="120"></a>&nbsp;&nbsp;&nbsp;&nbsp;<a href="https://homeassistant-ai.github.io/ha-mcp/guide-windows/"><img src="https://img.shields.io/badge/Setup_Guide_for_Windows-0078D6?style=for-the-badge&logo=windows&logoColor=white" alt="Setup Guide for Windows" height="120"></a>
+<a href="https://homeassistant-ai.github.io/ha-mcp/guide-macos/"><img src="https://img.shields.io/badge/Setup_Guide_for_macOS-000000?style=for-the-badge&logo=apple&logoColor=white" alt="Setup Guide for macOS" height="120"></a>&nbsp;&nbsp;&nbsp;&nbsp;<a href="https://homeassistant-ai.github.io/ha-mcp/guide-linux/"><img src="https://img.shields.io/badge/Setup_Guide_for_Linux-FCC624?style=for-the-badge&logo=linux&logoColor=black" alt="Setup Guide for Linux" height="120"></a>&nbsp;&nbsp;&nbsp;&nbsp;<a href="https://homeassistant-ai.github.io/ha-mcp/guide-windows/"><img src="https://img.shields.io/badge/Setup_Guide_for_Windows-0078D6?style=for-the-badge&logo=windows&logoColor=white" alt="Setup Guide for Windows" height="120"></a>
 </p>
 
 ### Quick install (~5 min)
@@ -59,6 +59,33 @@ You're now connected to the demo environment! [Connect your own Home Assistant
 
 </details>
 
+<details>
+<summary><b>🐧 Linux</b></summary>
+
+Anthropic doesn't ship Claude Desktop for Linux, so pick one path:
+
+**Claude Desktop** — free, via the community build:
+
+1. Install the community [Claude Desktop for Linux](https://github.com/aaddrick/claude-desktop-debian) build and sign in with a free [claude.ai](https://claude.ai) account
+2. Open **Terminal** and run:
+   ```sh
+   curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-linux.sh | sh
+   ```
+3. Restart Claude Desktop, then ask: **"Can you see my Home Assistant?"**
+
+**Claude Code** — official CLI, requires a paid Claude plan:
+
+1. Install Claude Code: `curl -fsSL https://claude.ai/install.sh | bash`
+2. Configure ha-mcp, then run `claude`:
+   ```sh
+   curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install.sh | sh -s -- --claude-code
+   ```
+3. Start `claude`, run `/mcp` to confirm, then ask: **"Can you see my Home Assistant?"**
+
+[Full Linux guide →](https://homeassistant-ai.github.io/ha-mcp/guide-linux/)
+
+</details>
+
 <details>
 <summary><b>🪟 Windows</b></summary>
 

{ha_mcp_dev-7.6.0.dev642 → ha_mcp_dev-7.6.0.dev644}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.6.0.dev642"
+version = "7.6.0.dev644"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"

{ha_mcp_dev-7.6.0.dev642 → ha_mcp_dev-7.6.0.dev644}/src/ha_mcp/__main__.py

@@ -825,6 +825,27 @@ def register_browser_landing(mcp_instance: "FastMCP | _DeferredMCP", path: str)
         )
 
 
+def _log_settings_url(host: str, port: int, path: str) -> None:
+    """Log the web settings-UI URL at HTTP startup.
+
+    Non-add-on operators (Docker / standalone) otherwise have no easy way to
+    discover the settings page or its secret-path URL (issue #1458). When the
+    bind host is the wildcard (``0.0.0.0`` / ``::``) the process can't know its
+    externally reachable address, so we log a ``<host>`` placeholder.
+    """
+    is_wildcard = host in ("0.0.0.0", "::")
+    if is_wildcard:
+        display_host = "<host>"
+    elif ":" in host:
+        # IPv6 literal (e.g. ::1, 2001:db8::1) needs brackets in a URL.
+        display_host = f"[{host}]"
+    else:
+        display_host = host
+    url = f"http://{display_host}:{port}{path.rstrip('/')}/settings"
+    note = "  (substitute this server's address for <host>)" if is_wildcard else ""
+    logger.info(f"Settings UI available at: {url}{note}")
+
+
 def _run_http_server(transport: str, default_port: int = 8086) -> None:
     """Common runner for HTTP-based transports.
 
@@ -837,6 +858,7 @@ def _run_http_server(transport: str, default_port: int = 8086) -> None:
     host, port, path = _get_http_runtime(default_port)
     register_browser_landing(_get_mcp(), path)
     register_settings_routes(_get_mcp(), _get_server(), secret_path=path)
+    _log_settings_url(host, port, path)
 
     _run_entrypoint(
         _run_http_with_graceful_shutdown(transport, host, port, path),
@@ -984,6 +1006,7 @@ async def _run_oauth_server(
     from ha_mcp.settings_ui import register_settings_routes
 
     register_settings_routes(mcp, _server, secret_path=path)
+    _log_settings_url(host, port, path)
 
     tools = await mcp.list_tools()
     logger.info(

{ha_mcp_dev-7.6.0.dev642 → ha_mcp_dev-7.6.0.dev644}/src/ha_mcp/settings_ui.py

@@ -3017,6 +3017,25 @@ def _ingress_only(handler: _SettingsRoute) -> _SettingsRoute:
     return _guarded
 
 
+# Mount prefix the settings UI is served under in long-lived HTTP transports
+# (Docker / standalone ha-mcp-web / OAuth / the add-on's secret-path mount).
+# Recorded by register_settings_routes so ha_get_overview can point users at
+# the settings page in modes that have no stdio sidecar URL file to surface
+# (issue #1458). Stays None in pure stdio mode, where the sidecar writes
+# ~/.ha-mcp/ui.url instead.
+_http_settings_prefix: str | None = None
+
+
+def get_http_settings_prefix() -> str | None:
+    """Return the settings-UI mount prefix for HTTP transports, or None.
+
+    Set by :func:`register_settings_routes` when the page is mounted on a
+    long-lived HTTP server. ``ha_get_overview`` reads it to hint at the
+    settings page when there is no stdio sidecar URL to hand the user.
+    """
+    return _http_settings_prefix
+
+
 def register_settings_routes(
     mcp: FastMCP,
     server: HomeAssistantSmartMCPServer,
@@ -3117,3 +3136,7 @@ def register_settings_routes(
         # need the same secret to reach the UI as they do for the MCP
         # endpoint.
         _mount(secret_prefix)
+        # Record the mount so ha_get_overview can point users at the settings
+        # page in HTTP transports that have no stdio sidecar URL file (#1458).
+        global _http_settings_prefix
+        _http_settings_prefix = secret_prefix

{ha_mcp_dev-7.6.0.dev642 → ha_mcp_dev-7.6.0.dev644}/src/ha_mcp/tools/tools_search.py

@@ -1136,10 +1136,11 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                     "device_types, service_availability, system_info, "
                     "notification_count, notifications, repair_count, "
                     "dismissed_repair_count, repairs, repairs_error, "
-                    "tool_discovery, settings_url. Note: ``settings_url`` "
-                    "(stdio mode only, see tool description) is emitted "
-                    "regardless of ``fields=`` projection — it is always "
-                    "included when the settings-UI sidecar is running."
+                    "tool_discovery, settings_url, settings_url_hint. Note: "
+                    "``settings_url`` (stdio mode) and ``settings_url_hint`` "
+                    "(HTTP/Docker/OAuth mode) are emitted regardless of "
+                    "``fields=`` projection so the settings page stays "
+                    "discoverable; see the tool description."
                 ),
             ),
         ] = None,
@@ -1167,6 +1168,12 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         projection (so it stays discoverable even when callers
         minimize the response) but only when the sidecar URL file
         actually exists.
+
+        In HTTP / Docker / OAuth modes there is no sidecar URL file and the
+        server can't know its externally reachable host, so the response
+        instead carries a ``settings_url_hint`` string telling the user where
+        the page is mounted and to read the full URL from the startup logs.
+        Hand whichever of the two fields is present to the user.
         """
         # Validate fields= early so a malformed value returns VALIDATION_FAILED
         # with parameter="fields" (ha_get_overview has no outer try/except, so
@@ -1368,6 +1375,24 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         sidecar_url = read_sidecar_url()
         if sidecar_url:
             projected["settings_url"] = sidecar_url
+        else:
+            # No stdio sidecar URL file. In HTTP / Docker / OAuth modes the
+            # settings page is mounted on this server, but the process binds
+            # 0.0.0.0 and can't know its externally reachable host — so hint
+            # at the page (and the startup-log URL) instead of guessing a
+            # wrong absolute URL (issue #1458).
+            from ..settings_ui import get_http_settings_prefix
+
+            http_prefix = get_http_settings_prefix()
+            if http_prefix:
+                settings_path = f"{http_prefix.rstrip('/')}/settings"
+                projected["settings_url_hint"] = (
+                    "The settings page (enable/disable/pin tools, feature "
+                    "flags, advanced settings, backups, tool-approval) is "
+                    f"served at '{settings_path}' on this MCP server. Find the "
+                    "full URL in the ha-mcp startup logs, or append it to the "
+                    "base URL your client connects to."
+                )
 
         return projected
 

{ha_mcp_dev-7.6.0.dev642 → ha_mcp_dev-7.6.0.dev644/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.6.0.dev642
+Version: 7.6.0.dev644
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -69,7 +69,7 @@ Dynamic: license-file
 *No paid subscription required.* Click on your operating system:
 
 <p>
-<a href="https://homeassistant-ai.github.io/ha-mcp/guide-macos/"><img src="https://img.shields.io/badge/Setup_Guide_for_macOS-000000?style=for-the-badge&logo=apple&logoColor=white" alt="Setup Guide for macOS" height="120"></a>&nbsp;&nbsp;&nbsp;&nbsp;<a href="https://homeassistant-ai.github.io/ha-mcp/guide-windows/"><img src="https://img.shields.io/badge/Setup_Guide_for_Windows-0078D6?style=for-the-badge&logo=windows&logoColor=white" alt="Setup Guide for Windows" height="120"></a>
+<a href="https://homeassistant-ai.github.io/ha-mcp/guide-macos/"><img src="https://img.shields.io/badge/Setup_Guide_for_macOS-000000?style=for-the-badge&logo=apple&logoColor=white" alt="Setup Guide for macOS" height="120"></a>&nbsp;&nbsp;&nbsp;&nbsp;<a href="https://homeassistant-ai.github.io/ha-mcp/guide-linux/"><img src="https://img.shields.io/badge/Setup_Guide_for_Linux-FCC624?style=for-the-badge&logo=linux&logoColor=black" alt="Setup Guide for Linux" height="120"></a>&nbsp;&nbsp;&nbsp;&nbsp;<a href="https://homeassistant-ai.github.io/ha-mcp/guide-windows/"><img src="https://img.shields.io/badge/Setup_Guide_for_Windows-0078D6?style=for-the-badge&logo=windows&logoColor=white" alt="Setup Guide for Windows" height="120"></a>
 </p>
 
 ### Quick install (~5 min)
@@ -89,6 +89,33 @@ You're now connected to the demo environment! [Connect your own Home Assistant
 
 </details>
 
+<details>
+<summary><b>🐧 Linux</b></summary>
+
+Anthropic doesn't ship Claude Desktop for Linux, so pick one path:
+
+**Claude Desktop** — free, via the community build:
+
+1. Install the community [Claude Desktop for Linux](https://github.com/aaddrick/claude-desktop-debian) build and sign in with a free [claude.ai](https://claude.ai) account
+2. Open **Terminal** and run:
+   ```sh
+   curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install-linux.sh | sh
+   ```
+3. Restart Claude Desktop, then ask: **"Can you see my Home Assistant?"**
+
+**Claude Code** — official CLI, requires a paid Claude plan:
+
+1. Install Claude Code: `curl -fsSL https://claude.ai/install.sh | bash`
+2. Configure ha-mcp, then run `claude`:
+   ```sh
+   curl -LsSf https://raw.githubusercontent.com/homeassistant-ai/ha-mcp/master/scripts/install.sh | sh -s -- --claude-code
+   ```
+3. Start `claude`, run `/mcp` to confirm, then ask: **"Can you see my Home Assistant?"**
+
+[Full Linux guide →](https://homeassistant-ai.github.io/ha-mcp/guide-linux/)
+
+</details>
+
 <details>
 <summary><b>🪟 Windows</b></summary>