ha-mcp-dev 7.8.0.dev713__tar.gz → 7.8.0.dev714__tar.gz

{ha_mcp_dev-7.8.0.dev713/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.8.0.dev714}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.8.0.dev713
+Version: 7.8.0.dev714
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-7.8.0.dev713 → ha_mcp_dev-7.8.0.dev714}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.8.0.dev713"
+version = "7.8.0.dev714"
 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.8.0.dev713 → ha_mcp_dev-7.8.0.dev714}/src/ha_mcp/config.py

@@ -89,6 +89,13 @@ class Settings(BaseSettings):
     # WebSocket configuration (essential for async operations)
     enable_websocket: bool = Field(True, alias="ENABLE_WEBSOCKET")
 
+    # Settings UI sidecar (stdio mode only, #1587). 0 = pick a free
+    # ephemeral port at every spawn (default); 1024-65535 pins the sidecar
+    # to a fixed port so the settings URL/origin stays stable across
+    # restarts (bookmarks, browser localStorage). Read by run_main() in
+    # stdio_settings_sidecar.py.
+    sidecar_pin_port: int = Field(0, alias="HA_MCP_SIDECAR_PORT")
+
     # Development/Debug configuration
     debug: bool = Field(False, alias="DEBUG")
     log_level: str = Field("INFO", alias="LOG_LEVEL")
@@ -437,6 +444,37 @@ class Settings(BaseSettings):
             raise ValueError(f"Backup hint must be one of {valid_hints}")
         return v.lower()
 
+    @field_validator("sidecar_pin_port", mode="before")
+    @classmethod
+    def _lenient_sidecar_pin_port(cls, v: object) -> int:
+        """0 (default) = ephemeral port; otherwise a non-privileged port.
+
+        Lenient like the time-budget validators: an empty / unparseable /
+        out-of-range value falls back to 0 (ephemeral) with a warning rather
+        than raising, so a bad ``HA_MCP_SIDECAR_PORT`` can never crash the MCP
+        server or the best-effort settings sidecar.
+        """
+        if isinstance(v, str):
+            v = v.strip()
+            if not v:
+                return 0
+        # bool is an int subclass but never a meaningful port; reject it
+        # along with anything that isn't int/str-parseable.
+        if v is None or isinstance(v, bool) or not isinstance(v, int | str):
+            logger.warning("Invalid HA_MCP_SIDECAR_PORT=%r; using ephemeral port", v)
+            return 0
+        try:
+            port = int(v)
+        except (ValueError, TypeError):
+            logger.warning("Invalid HA_MCP_SIDECAR_PORT=%r; using ephemeral port", v)
+            return 0
+        if port != 0 and not 1024 <= port <= 65535:
+            logger.warning(
+                "HA_MCP_SIDECAR_PORT=%r outside 1024-65535; using ephemeral port", v
+            )
+            return 0
+        return port
+
     model_config = SettingsConfigDict(
         env_file=".env", env_file_encoding="utf-8", case_sensitive=False, extra="allow"
     )
@@ -505,6 +543,7 @@ AdvancedSection = Literal[
     "operations",
     "diagnostics",
     "tools_surface",
+    "sidecar",
     "beta_codemode",
 ]
 
@@ -728,6 +767,10 @@ ADVANCED_SETTINGS_FIELDS: tuple[AdvancedField, ...] = (
     AdvancedField("environment", "ENVIRONMENT", str, "diagnostics", True),
     AdvancedField("log_level", "LOG_LEVEL", str, "diagnostics", True),
     AdvancedField("debug", "DEBUG", bool, "diagnostics", True),
+    # Settings UI sidecar (stdio-only). Pin the sidecar's port so the
+    # settings URL/origin is stable across restarts; 0 = ephemeral
+    # (default). #1587.
+    AdvancedField("sidecar_pin_port", "HA_MCP_SIDECAR_PORT", int, "sidecar", True),
     # NOTE: ``auto_backup_dir`` and ``auto_backup_calendar_lookahead_days``
     # are NOT in this tuple. They are in ``BACKUP_OVERRIDE_FIELDS`` (defined
     # below) so they persist to ``backup_settings.json`` alongside the
@@ -778,6 +821,18 @@ _ADVANCED_SETTINGS_BOUNDS: dict[str, tuple[float, float]] = {
     "code_mode_max_memory": (1_048_576, 268_435_456),
     "code_mode_max_recursion": (1, 10_000),
     "code_mode_max_invocations": (1, 10_000),
+    # 0 is the "off" sentinel (ephemeral); the range below is the valid
+    # PINNED range. See _ADVANCED_SETTINGS_SENTINELS.
+    "sidecar_pin_port": (1024, 65535),
+}
+
+
+# Fields where a specific value is a valid "off" sentinel that bypasses the
+# _ADVANCED_SETTINGS_BOUNDS range (sidecar_pin_port: 0 = ephemeral). The UI
+# emits min=sentinel so the number input can still express "off"; the
+# override-apply and UI-POST paths accept the sentinel OR the bounded range.
+_ADVANCED_SETTINGS_SENTINELS: dict[str, int] = {
+    "sidecar_pin_port": 0,
 }
 
 
@@ -1159,7 +1214,12 @@ def _apply_advanced_overrides(settings: "Settings") -> None:
             continue
 
         bounds = _ADVANCED_SETTINGS_BOUNDS.get(fname)
-        if bounds is not None and not (bounds[0] <= coerced <= bounds[1]):
+        sentinel = _ADVANCED_SETTINGS_SENTINELS.get(fname)
+        if (
+            bounds is not None
+            and coerced != sentinel
+            and not (bounds[0] <= coerced <= bounds[1])
+        ):
             logger.warning(
                 "Advanced override for %r is %s, outside %s-%s — ignoring.",
                 fname,

{ha_mcp_dev-7.8.0.dev713 → ha_mcp_dev-7.8.0.dev714}/src/ha_mcp/settings.css

@@ -284,6 +284,13 @@
   .adv-save-btn:disabled { opacity: 0.55; cursor: not-allowed;
     box-shadow: none; }
   .adv-section { border-top: 1px solid var(--border); }
+  /* Sidecar section greys out in non-stdio deployments (no sidecar to pin),
+     mirroring the .feature-row.*-sub.dimmed treatment. */
+  .adv-section.dimmed { opacity: 0.55; }
+  .adv-section.dimmed input, .adv-section.dimmed select { cursor: not-allowed; }
+  .adv-section-title.dimmed { opacity: 0.55; }
+  .adv-section-note { font-size: 0.72rem; color: var(--text-secondary);
+    margin: 4px 0 8px; line-height: 1.4; }
   .adv-row { display: flex; align-items: flex-start; justify-content: space-between;
     gap: 12px; padding: 10px 0; border-top: 1px solid var(--border); }
   .adv-row:first-child { border-top: none; }

{ha_mcp_dev-7.8.0.dev713 → ha_mcp_dev-7.8.0.dev714}/src/ha_mcp/settings.js

@@ -2740,6 +2740,7 @@ const ADVANCED_FIELD_META = {
   code_mode_max_recursion:   { label: "Code-mode max recursion",      help: "Recursion-depth cap per sandbox run. Restart required." },
   code_mode_max_invocations: { label: "Code-mode max invocations",    help: "API/tool-call cap per sandbox run. Restart required." },
   code_mode_saved_tools_path:{ label: "Saved-tools path",              help: "JSON file where ha_manage_custom_tool persists saved tools across restarts. Restart required." },
+  sidecar_pin_port:    { label: "Settings UI sidecar port",    help: "0 = a new free port each restart (default); set 1024–65535 to pin a fixed port so the settings URL stays stable across restarts. Falls back to a free port if the pinned one is busy. Restart required." },
 };
 
 // Fields that require an MCP-host restart to take effect when changed
@@ -2765,6 +2766,9 @@ const ADVANCED_RESTART_REQUIRED = new Set([
   "code_mode_max_duration", "code_mode_max_memory",
   "code_mode_max_recursion", "code_mode_max_invocations",
   "code_mode_saved_tools_path",
+  // The sidecar binds its port once at spawn (run_main), so changing the
+  // pin needs a restart to respawn the sidecar on the new port.
+  "sidecar_pin_port",
 ]);
 
 let _advancedFields = [];
@@ -2825,6 +2829,8 @@ async function loadAdvancedSettings() {
   renderAdvancedSection('advOperations', bySection.operations || []);
   renderAdvancedSection('advToolsSurface', bySection.tools_surface || []);
   renderAdvancedSection('advDiagnostics', bySection.diagnostics || []);
+  renderAdvancedSection('advSidecar', bySection.sidecar || []);
+  applySidecarAvailability(data.is_stdio !== false);
   document.getElementById('advSaveRow').style.display = '';
   const topRow = document.getElementById('advSaveRowTop');
   if (topRow) topRow.style.display = '';
@@ -2840,6 +2846,36 @@ async function loadAdvancedSettings() {
   }
 }
 
+function applySidecarAvailability(isStdio) {
+  // The sidecar-port setting only applies when this settings page is served
+  // by the stdio settings-UI sidecar. In HTTP/SSE/OAuth/addon deployments
+  // there is no sidecar, so dim + disable the section and explain why, rather
+  // than letting a user save a value that does nothing.
+  // Remove any note from a prior load first, so the <h3> title is once again
+  // the section's previousElementSibling (an injected note would otherwise
+  // shadow it on a re-render).
+  const prevNote = document.getElementById('advSidecarNote');
+  if (prevNote) prevNote.remove();
+  const section = document.getElementById('advSidecar');
+  if (!section) return;
+  const title = section.previousElementSibling;
+  if (isStdio) {
+    section.classList.remove('dimmed');
+    if (title) title.classList.remove('dimmed');
+    return;
+  }
+  section.classList.add('dimmed');
+  if (title) title.classList.add('dimmed');
+  section.querySelectorAll('input, select').forEach((el) => { el.disabled = true; });
+  const note = document.createElement('div');
+  note.id = 'advSidecarNote';
+  note.className = 'adv-section-note';
+  note.textContent =
+    'Available in stdio mode only. This server runs over HTTP, which has '
+    + 'no settings-UI sidecar to pin.';
+  section.parentNode.insertBefore(note, section);
+}
+
 function renderAdvancedSection(containerId, fields) {
   const el = document.getElementById(containerId);
   if (!el) return;

{ha_mcp_dev-7.8.0.dev713 → ha_mcp_dev-7.8.0.dev714}/src/ha_mcp/settings_ui.py

@@ -902,6 +902,8 @@ _SETTINGS_HTML = (
   <div id="advToolsSurface" class="adv-section"></div>
   <h3 class="adv-section-title">Diagnostics</h3>
   <div id="advDiagnostics" class="adv-section"></div>
+  <h3 class="adv-section-title">Settings UI sidecar</h3>
+  <div id="advSidecar" class="adv-section"></div>
 
   <!-- Beta features sit at the bottom of the panel — these can damage
        the HA system, so they come last and the user sees safer
@@ -2650,6 +2652,7 @@ def build_settings_handlers(
         from .config import (
             _ADVANCED_SETTINGS_BOUNDS,
             _ADVANCED_SETTINGS_CHOICES,
+            _ADVANCED_SETTINGS_SENTINELS,
             ADVANCED_SETTINGS_FIELDS,
             OAUTH_MODE_TOKEN,
             _read_feature_flag_override_file,
@@ -2692,11 +2695,26 @@ def build_settings_handlers(
             bounds = _ADVANCED_SETTINGS_BOUNDS.get(fname)
             if bounds is not None:
                 row["min"], row["max"] = bounds
+                # Sentinel fields (e.g. sidecar_pin_port: 0 = off) need the
+                # number input to reach below the bounded range, so expose
+                # the sentinel as the UI minimum.
+                sentinel = _ADVANCED_SETTINGS_SENTINELS.get(fname)
+                if sentinel is not None:
+                    row["min"] = sentinel
             choices = _ADVANCED_SETTINGS_CHOICES.get(fname)
             if choices is not None:
                 row["choices"] = list(choices)
             fields.append(row)
-        return JSONResponse({"fields": fields, "is_addon": is_running_in_addon()})
+        # is_stdio: the sidecar-port field only applies when this settings
+        # page is served by the stdio settings-UI sidecar. In HTTP/SSE/OAuth
+        # /addon deployments there is no sidecar, so the UI greys the section.
+        return JSONResponse(
+            {
+                "fields": fields,
+                "is_addon": is_running_in_addon(),
+                "is_stdio": get_http_settings_prefix() is None,
+            }
+        )
 
     def _origin_for_advanced_field(
         env_name: str, overrides: dict[str, Any] | None = None
@@ -2770,6 +2788,7 @@ def build_settings_handlers(
         from .config import (
             _ADVANCED_SETTINGS_BOUNDS,
             _ADVANCED_SETTINGS_CHOICES,
+            _ADVANCED_SETTINGS_SENTINELS,
             _FEATURE_FLAG_OVERRIDE_FILENAME,
             ADVANCED_SETTINGS_FIELDS,
         )
@@ -2890,7 +2909,12 @@ def build_settings_handlers(
                 return _bad_advanced_type(fname, ftype, raw)
 
             bounds = _ADVANCED_SETTINGS_BOUNDS.get(fname)
-            if bounds is not None and not (bounds[0] <= coerced <= bounds[1]):
+            sentinel = _ADVANCED_SETTINGS_SENTINELS.get(fname)
+            if (
+                bounds is not None
+                and coerced != sentinel
+                and not (bounds[0] <= coerced <= bounds[1])
+            ):
                 return JSONResponse(
                     create_error_response(
                         ErrorCode.VALIDATION_INVALID_PARAMETER,

{ha_mcp_dev-7.8.0.dev713 → ha_mcp_dev-7.8.0.dev714}/src/ha_mcp/stdio_settings_sidecar.py

@@ -266,19 +266,40 @@ def _spawn_lock() -> Iterator[bool]:
         os.close(fd)
 
 
-def _pick_free_port() -> int:
-    """Bind a transient socket to an ephemeral port and return it.
-
-    The socket is closed before the sidecar opens its own listener.
-    The OS may hand out the same port again to the sidecar; if another
-    process snatches it in the gap, the sidecar startup will fail and
-    log to ``sidecar.log`` — the parent moves on (settings UI is
-    advisory, not required for MCP operation).
+def _pick_free_port(pinned: int = 0) -> int:
+    """Return the port the sidecar listener should bind.
+
+    ``pinned == 0`` (default): bind a transient socket to an ephemeral
+    port and return it. The socket is closed before the sidecar opens its
+    own listener. The OS may hand out the same port again; if another
+    process snatches it in the gap, the sidecar startup will fail and log
+    to ``sidecar.log`` — the parent moves on (settings UI is advisory, not
+    required for MCP operation).
+
+    ``pinned != 0``: try to reserve the requested fixed port with
+    ``SO_REUSEADDR`` so the settings URL/origin survives restarts (#1587).
+    ``SO_REUSEADDR`` lets the bind succeed even if a crashed sidecar left
+    the port in ``TIME_WAIT``. If the port is genuinely unavailable (in
+    use by another process), log a warning and fall back to an ephemeral
+    port rather than failing the sidecar.
     """
+    if pinned:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+            sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+            try:
+                sock.bind(("127.0.0.1", pinned))
+                return int(sock.getsockname()[1])
+            except OSError as exc:
+                logger.warning(
+                    "Sidecar pin port %d unavailable (%s); "
+                    "falling back to an ephemeral port",
+                    pinned,
+                    exc,
+                )
+        return _pick_free_port(0)
     with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
         sock.bind(("127.0.0.1", 0))
-        port: int = sock.getsockname()[1]
-        return port
+        return int(sock.getsockname()[1])
 
 
 def maybe_spawn() -> None:
@@ -795,7 +816,13 @@ def run_main() -> int:
         format="%(asctime)s %(levelname)s %(name)s: %(message)s",
     )
 
-    port = _pick_free_port()
+    # Effective pin port honours both the env var (HA_MCP_SIDECAR_PORT) and
+    # a value set via the settings UI Advanced tab (persisted to the override
+    # file and applied by get_global_settings). 0 = ephemeral. The lenient
+    # validator in config.Settings has already clamped any bad value to 0.
+    from .config import get_global_settings
+
+    port = _pick_free_port(get_global_settings().sidecar_pin_port)
     secret_token = secrets.token_urlsafe(16)
     secret_path = f"/private_{secret_token}"
     url = f"http://127.0.0.1:{port}{secret_path}/settings"

{ha_mcp_dev-7.8.0.dev713 → ha_mcp_dev-7.8.0.dev714/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.8.0.dev713
+Version: 7.8.0.dev714
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT