ha-mcp-dev 7.12.3.dev1858__tar.gz → 7.12.3.dev1861__tar.gz

{ha_mcp_dev-7.12.3.dev1858/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.12.3.dev1861}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.12.3.dev1858
+Version: 7.12.3.dev1861
 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.12.3.dev1858 → ha_mcp_dev-7.12.3.dev1861}/pyproject.toml

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

@@ -83,6 +83,22 @@ class Settings(BaseSettings):
         20.0, alias="HAMCP_SCENE_CONFIG_TIME_BUDGET"
     )
 
+    # Per-request timeout and concurrency of the smart-search per-id
+    # config-fetch fallback (Attempt C). On HA servers that serve
+    # /config/<domain>/config/<id> serially, a full batch of concurrent
+    # requests queues behind one another and the tail of each batch can
+    # exceed the per-request timeout even though every request would
+    # succeed — lowering the batch size (toward 1) and/or raising the
+    # timeout lets such instances scan exhaustively (issue #1784). Same
+    # consumption model as the budgets above: import-time constants in
+    # tools/smart_search/_config.py, restart required.
+    individual_config_timeout: float = Field(
+        5.0, alias="HAMCP_INDIVIDUAL_CONFIG_TIMEOUT"
+    )
+    individual_fetch_batch_size: int = Field(
+        10, alias="HAMCP_INDIVIDUAL_FETCH_BATCH_SIZE"
+    )
+
     # Backup tool configuration
     backup_hint: str = Field("normal", alias="BACKUP_HINT")
 
@@ -350,21 +366,26 @@ class Settings(BaseSettings):
         "automation_config_time_budget",
         "script_config_time_budget",
         "scene_config_time_budget",
+        "individual_config_timeout",
+        "individual_fetch_batch_size",
         mode="before",
     )
     @classmethod
     def _lenient_time_budget(cls, v: object, info: ValidationInfo) -> object:
-        """Coerce the three smart-search time budgets, falling back to the
-        field default (with a warning) instead of crashing startup.
+        """Coerce the smart-search Attempt-C knobs (the three time budgets,
+        the per-request timeout, and the fetch batch size), falling back to
+        the field default (with a warning) instead of crashing startup.
 
         Preserves the parse-tolerance of the removed ``_env_float`` helper
         (empty / unparseable -> default) and additionally enforces the same
         ``_ADVANCED_SETTINGS_BOUNDS`` range as the override-file / UI-POST
         path, so the env-var path can't smuggle in an out-of-range or
-        non-finite budget. A ``<= 0`` budget would silently disable the
-        per-id config-fetch scan, and ``inf`` / ``nan`` would uncap it; the
-        ``lo <= val <= hi`` test rejects all three (NaN comparisons are
-        False), keeping the env and override-file paths consistent."""
+        non-finite value. A ``<= 0`` budget or timeout would silently
+        disable the per-id config-fetch scan, and ``inf`` / ``nan`` would
+        uncap it; the ``lo <= val <= hi`` test rejects all three (NaN
+        comparisons are False), keeping the env and override-file paths
+        consistent. Int fields (batch size) additionally reject fractional
+        values rather than truncating them."""
         field_name = info.field_name
         if field_name is None:  # always set for field_validator; defensive
             return v
@@ -389,6 +410,17 @@ class Settings(BaseSettings):
                 default,
             )
             return default
+        if isinstance(default, int) and not isinstance(default, bool):
+            if val != int(val):
+                logger.warning(
+                    "Invalid value for %s=%r (must be a whole number); "
+                    "using default %s",
+                    field_name,
+                    v,
+                    default,
+                )
+                return default
+            return int(val)
         return val
 
     @property
@@ -759,6 +791,22 @@ ADVANCED_SETTINGS_FIELDS: tuple[AdvancedField, ...] = (
         "search",
         True,
     ),
+    # Attempt-C per-request timeout + batch size (#1784). Restart-required
+    # (same import-time consumption as the budgets above).
+    AdvancedField(
+        "individual_config_timeout",
+        "HAMCP_INDIVIDUAL_CONFIG_TIMEOUT",
+        float,
+        "search",
+        True,
+    ),
+    AdvancedField(
+        "individual_fetch_batch_size",
+        "HAMCP_INDIVIDUAL_FETCH_BATCH_SIZE",
+        int,
+        "search",
+        True,
+    ),
     # Operations.
     AdvancedField("backup_hint", "BACKUP_HINT", str, "operations", True),
     AdvancedField("enable_websocket", "ENABLE_WEBSOCKET", bool, "operations", True),
@@ -846,6 +894,8 @@ _ADVANCED_SETTINGS_BOUNDS: dict[str, tuple[float, float]] = {
     "automation_config_time_budget": (1.0, 600.0),
     "script_config_time_budget": (1.0, 600.0),
     "scene_config_time_budget": (1.0, 600.0),
+    "individual_config_timeout": (1.0, 600.0),
+    "individual_fetch_batch_size": (1, 100),
     "code_mode_max_duration": (1.0, 300.0),
     "code_mode_max_memory": (1_048_576, 268_435_456),
     "code_mode_max_recursion": (1, 10_000),

{ha_mcp_dev-7.12.3.dev1858 → ha_mcp_dev-7.12.3.dev1861}/src/ha_mcp/settings_ui/settings.js

@@ -2946,6 +2946,8 @@ const ADVANCED_FIELD_META = {
   automation_config_time_budget: { label: "Automation config time budget (s)", help: "Max seconds ha_search/ha_deep_search spends fetching automation configs before returning a partial result. Raise on instances with many automations. Range 1–600. Restart required." },
   script_config_time_budget:     { label: "Script config time budget (s)",     help: "Max seconds ha_search/ha_deep_search spends fetching script configs before returning a partial result. Range 1–600. Restart required." },
   scene_config_time_budget:      { label: "Scene config time budget (s)",      help: "Max seconds ha_search/ha_deep_search spends fetching scene configs before returning a partial result. Range 1–600. Restart required." },
+  individual_config_timeout:     { label: "Per-request config fetch timeout (s)", help: "Timeout for each individual automation/script/scene config fetch during deep search. On HA servers that serve config reads serially, raise this and/or lower the batch size so queued requests don't time out. Values above the HA request timeout (HA_TIMEOUT, default 30) have no extra effect — the HTTP client gives up first. Range 1–600. Restart required." },
+  individual_fetch_batch_size:   { label: "Config fetch batch size",          help: "How many per-id config fetches deep search issues concurrently. Lower toward 1 on HA servers that serve config reads serially (symptom: 'timed out' partial-result warnings). Range 1–100. Restart required." },
   backup_hint:         { label: "Backup-hint level",           help: "Tunes how strongly the LLM is prompted to take a full-HA snapshot before risky writes." },
   dashboard_screenshot_engine_url: { label: "Dashboard screenshot engine URL", help: "Base URL of the screenshot engine (e.g. http://puppet:10000). Leave blank to auto-discover the Puppet App (add-on) via the Supervisor (HA OS / Supervised). Only used when the Dashboard Screenshot beta feature is enabled. Takes effect without a restart." },
   enable_websocket:    { label: "Enable WebSocket",            help: "WebSocket-based state monitoring. Disabling falls back to polling; many tools degrade. Restart required." },
@@ -2985,6 +2987,9 @@ const ADVANCED_RESTART_REQUIRED = new Set([
   // it is resolved live per capture, so it takes effect immediately.
   "automation_config_time_budget", "script_config_time_budget",
   "scene_config_time_budget",
+  // The Attempt-C per-request timeout and batch size (#1784) share the
+  // budgets' import-time consumption, so they need a restart too.
+  "individual_config_timeout", "individual_fetch_batch_size",
   "code_mode_max_duration", "code_mode_max_memory",
   "code_mode_max_recursion", "code_mode_max_invocations",
   "code_mode_saved_tools_path",

{ha_mcp_dev-7.12.3.dev1858 → ha_mcp_dev-7.12.3.dev1861}/src/ha_mcp/tools/config_entry_flow.py

@@ -12,6 +12,7 @@ for the 15 helper types listed in FLOW_HELPER_TYPES.
 
 import asyncio
 import logging
+from collections.abc import Iterator
 from enum import StrEnum
 from typing import Any, Literal
 
@@ -128,10 +129,125 @@ def _handle_menu_step(
     return str(menu_choice)
 
 
+def iter_schema_fields(data_schema: Any) -> Iterator[dict[str, Any]]:
+    """Yield leaf field definitions from a flow schema, descending into sections."""
+    if not isinstance(data_schema, list):
+        return
+    for field in data_schema:
+        if not isinstance(field, dict):
+            continue
+        nested_schema = field.get("schema")
+        if isinstance(nested_schema, list):
+            yield from iter_schema_fields(nested_schema)
+            continue
+        yield field
+
+
+def _section_path(path_prefix: str, name: Any) -> str:
+    """Return the dotted config path for a named or anonymous section."""
+    if not isinstance(name, str):
+        return path_prefix
+    return f"{path_prefix}.{name}" if path_prefix else name
+
+
+def _record_ignored_section_keys(
+    ignored_config_keys: set[str] | None,
+    remaining_config: dict[str, Any],
+    section_path: str,
+) -> None:
+    """Record undeclared keys remaining inside an explicit section dict."""
+    if ignored_config_keys is None:
+        return
+    ignored_config_keys.update(
+        f"{section_path}.{key}" if section_path else key
+        for key in remaining_config
+        if key not in _MENU_SELECTION_KEYS
+    )
+
+
+def _consume_form_schema(
+    data_schema: list[Any],
+    remaining_config: dict[str, Any],
+    ignored_config_keys: set[str] | None = None,
+    path_prefix: str = "",
+) -> dict[str, Any]:
+    """Consume matching config values and shape nested flow sections.
+
+    Mutates ``remaining_config`` by removing every consumed key. Flat child
+    values override the same value inside an explicitly supplied section dict.
+    Unknown keys inside explicit section dicts are added to
+    ``ignored_config_keys`` with their dotted section path.
+    """
+    form_data: dict[str, Any] = {}
+    missing = object()
+
+    for field in data_schema:
+        if not isinstance(field, dict):
+            continue
+
+        name = field.get("name")
+        nested_schema = field.get("schema")
+        if isinstance(nested_schema, list):
+            section_path = _section_path(path_prefix, name)
+            explicit_section = (
+                remaining_config.pop(name, missing)
+                if isinstance(name, str)
+                else missing
+            )
+            if explicit_section is not missing and not isinstance(
+                explicit_section, dict
+            ):
+                if isinstance(name, str):
+                    form_data[name] = explicit_section
+                continue
+
+            nested_data: dict[str, Any] = {}
+            if isinstance(explicit_section, dict):
+                explicit_remaining = dict(explicit_section)
+                nested_data.update(
+                    _consume_form_schema(
+                        nested_schema,
+                        explicit_remaining,
+                        ignored_config_keys,
+                        section_path,
+                    )
+                )
+                _record_ignored_section_keys(
+                    ignored_config_keys,
+                    explicit_remaining,
+                    section_path,
+                )
+            nested_data.update(
+                _consume_form_schema(
+                    nested_schema,
+                    remaining_config,
+                    ignored_config_keys,
+                    section_path,
+                )
+            )
+
+            if nested_data:
+                if isinstance(name, str):
+                    form_data[name] = nested_data
+                else:
+                    form_data.update(nested_data)
+            continue
+
+        if (
+            isinstance(name, str)
+            and name not in _MENU_SELECTION_KEYS
+            and name in remaining_config
+        ):
+            form_data[name] = remaining_config.pop(name)
+
+    return form_data
+
+
 def _extract_schema_field_names(data_schema: Any) -> set[str] | None:
     """Extract the set of field names declared by a step's data_schema.
 
     HA returns data_schema as a list of {name, selector, required, ...} dicts.
+    Nested leaf names are included; section-container names are omitted.
     Returns ``None`` when the schema is absent or not a list (signalling
     the caller to fall back to legacy submit-all behaviour). Returns a
     (possibly empty) set when the schema is present and parseable.
@@ -139,11 +255,10 @@ def _extract_schema_field_names(data_schema: Any) -> set[str] | None:
     if not isinstance(data_schema, list):
         return None
     names: set[str] = set()
-    for field in data_schema:
-        if isinstance(field, dict):
-            name = field.get("name")
-            if isinstance(name, str):
-                names.add(name)
+    for field in iter_schema_fields(data_schema):
+        name = field.get("name")
+        if isinstance(name, str):
+            names.add(name)
     return names
 
 
@@ -151,13 +266,15 @@ def _handle_form_step(
     flow_id: str,
     current_step: dict[str, Any],
     remaining_config: dict[str, Any],
+    ignored_config_keys: set[str] | None = None,
 ) -> dict[str, Any]:
     """Validate a form step and return form data to submit.
 
     When the step's ``data_schema`` is provided, pops ONLY the keys declared
     in that schema from ``remaining_config`` (mutating it) so any unconsumed
     keys remain available for subsequent steps. Menu selection keys are never
-    submitted.
+    submitted. Fields declared inside a section are grouped under the section
+    key; callers may provide them flat or inside an explicit section dict.
 
     When ``data_schema`` is absent (HA didn't tell us field names), falls
     back to legacy behaviour: submit all non-menu keys and clear them. This
@@ -180,10 +297,10 @@ def _handle_form_step(
             )
         )
 
-    schema_fields = _extract_schema_field_names(current_step.get("data_schema"))
+    data_schema = current_step.get("data_schema")
 
     form_data: dict[str, Any] = {}
-    if schema_fields is None:
+    if not isinstance(data_schema, list):
         # Legacy fallback: no schema info — dump every non-menu key and
         # consume them all so a follow-up step (rare without schema) won't
         # re-submit the same data.
@@ -192,11 +309,9 @@ def _handle_form_step(
                 continue
             form_data[key] = remaining_config.pop(key)
     else:
-        for key in list(remaining_config.keys()):
-            if key in _MENU_SELECTION_KEYS:
-                continue
-            if key in schema_fields:
-                form_data[key] = remaining_config.pop(key)
+        form_data = _consume_form_schema(
+            data_schema, remaining_config, ignored_config_keys
+        )
 
     return form_data
 
@@ -512,7 +627,8 @@ async def _handle_flow_steps(
             for unstructured HA 4xx responses so the caller can react.
 
     Returns:
-        ``{"success": True, "entry": result}`` on success.
+        ``{"success": True, "entry": result}`` on success, plus ``warnings``
+        when caller-supplied config keys were not declared by any flow step.
         Raises ToolError on any failure.
     """
     if submit_fn is None:
@@ -520,13 +636,23 @@ async def _handle_flow_steps(
     remaining_config = dict(config)
     current_step = initial_step
     last_menu_choice: str | None = None
+    ignored_config_keys: set[str] = set()
     max_steps = 10
 
     for step_num in range(max_steps):
         result_type = current_step.get("type")
 
         if result_type == _FlowType.CREATE_ENTRY:
-            return {"success": True, "entry": current_step}
+            ignored_config_keys.update(
+                key for key in remaining_config if key not in _MENU_SELECTION_KEYS
+            )
+            response: dict[str, Any] = {"success": True, "entry": current_step}
+            if ignored_config_keys:
+                response["warnings"] = [
+                    "Ignored config keys not declared by the Home Assistant flow "
+                    f"schema: {', '.join(sorted(ignored_config_keys))}"
+                ]
+            return response
 
         if result_type == _FlowType.ABORT:
             raise_tool_error(
@@ -559,7 +685,12 @@ async def _handle_flow_steps(
             # step's data_schema, leaving any other keys in remaining_config
             # for subsequent steps (HA can present multi-step forms, e.g.
             # statistics: user step then pick-characteristic step).
-            form_data = _handle_form_step(flow_id, current_step, remaining_config)
+            form_data = _handle_form_step(
+                flow_id,
+                current_step,
+                remaining_config,
+                ignored_config_keys,
+            )
             logger.debug(
                 f"Flow step {step_num}: form submit "
                 f"(step_id={current_step.get('step_id')}, keys={list(form_data.keys())})"
@@ -875,7 +1006,7 @@ async def update_flow_helper(
         raise
 
     entry = result["entry"].get("result", {})
-    return {
+    response = {
         "success": True,
         "entry_id": entry_id,
         "title": entry.get("title"),
@@ -883,6 +1014,9 @@ async def update_flow_helper(
         "message": f"{helper_type} helper updated successfully",
         "updated": True,
     }
+    if result.get("warnings"):
+        response["warnings"] = result["warnings"]
+    return response
 
 
 async def create_flow_helper(
@@ -928,10 +1062,13 @@ async def create_flow_helper(
         raise
 
     entry = result["entry"].get("result", {})
-    return {
+    response = {
         "success": True,
         "entry_id": entry.get("entry_id"),
         "title": entry.get("title"),
         "domain": helper_type,
         "message": f"{helper_type} helper created successfully",
     }
+    if result.get("warnings"):
+        response["warnings"] = result["warnings"]
+    return response

{ha_mcp_dev-7.12.3.dev1858 → ha_mcp_dev-7.12.3.dev1861}/src/ha_mcp/tools/smart_search/_config.py

@@ -13,23 +13,29 @@ DEFAULT_CONCURRENCY_LIMIT = 20
 # Bulk fetch timeouts (in seconds)
 BULK_REST_TIMEOUT = 5.0  # Timeout for bulk REST endpoint calls
 BULK_WEBSOCKET_TIMEOUT = 3.0  # Timeout for bulk WebSocket calls
-INDIVIDUAL_CONFIG_TIMEOUT = 5.0  # Timeout for individual config fetches
 
 
-# Time budgets for fallback individual fetching (in seconds). Sourced from
-# the resolved Settings (issue #1538) so the env var, the web Settings UI
+# Attempt-C (per-id fallback) tuning knobs. Sourced from the resolved
+# Settings (issues #1538 / #1784) so the env var, the web Settings UI
 # override file, and the field defaults all flow through one precedence path
 # — and so add-on users (who cannot set raw env vars) can tune them from the
 # Advanced panel. Read once at import as module-level constants; a change
 # takes effect on the next MCP-host restart (advanced settings already
 # carry a restart-required notice in the UI).
 _settings = get_global_settings()
+
+# Time budgets for fallback individual fetching (in seconds).
 AUTOMATION_CONFIG_TIME_BUDGET = _settings.automation_config_time_budget
 SCRIPT_CONFIG_TIME_BUDGET = _settings.script_config_time_budget
 SCENE_CONFIG_TIME_BUDGET = _settings.scene_config_time_budget
 
-# Batch size for parallel individual config fetches (Attempt C fallback)
-INDIVIDUAL_FETCH_BATCH_SIZE = 10
+# Per-request timeout (seconds) and batch size for the parallel individual
+# config fetches. On HA servers that serve the per-id config endpoint
+# serially, a batch's tail requests queue behind its head and can exceed
+# the per-request timeout despite being perfectly healthy — tune batch
+# size toward 1 and/or raise the timeout on such instances (issue #1784).
+INDIVIDUAL_CONFIG_TIMEOUT = _settings.individual_config_timeout
+INDIVIDUAL_FETCH_BATCH_SIZE = _settings.individual_fetch_batch_size
 
 
 def _simplify_states_summary(