ha-mcp-dev 7.5.0.dev559__tar.gz → 7.5.0.dev561__tar.gz

{ha_mcp_dev-7.5.0.dev559/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.5.0.dev561}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.5.0.dev559
+Version: 7.5.0.dev561
 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.5.0.dev559 → ha_mcp_dev-7.5.0.dev561}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.5.0.dev559"
+version = "7.5.0.dev561"
 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.5.0.dev559 → ha_mcp_dev-7.5.0.dev561}/src/ha_mcp/client/rest_client.py

@@ -782,6 +782,9 @@ class HomeAssistantClient:
             else:
                 return False, "Invalid response from Home Assistant"
         except Exception as e:
+            # Intentional broad-catch: is_connected() contract maps any failure
+            # to (False, error_msg); styleguide § "broad except at top-level
+            # setup/teardown handlers" applies (connection probe is the analog).
             logger.error(f"Failed to connect to Home Assistant: {e}")
             return False, str(e)
 
@@ -823,7 +826,7 @@ class HomeAssistantClient:
                     f"Converted entity_id {identifier} to unique_id {unique_id}"
                 )
                 return str(unique_id)
-            except Exception as e:
+            except HomeAssistantError as e:
                 raise HomeAssistantAPIError(
                     f"Failed to resolve automation {identifier}: {str(e)}",
                     status_code=404,
@@ -853,8 +856,8 @@ class HomeAssistantClient:
                 "GET", f"/config/automation/config/{unique_id}"
             )
             return response
-        except Exception as e:
-            if "404" in str(e):
+        except HomeAssistantAPIError as e:
+            if e.status_code == 404:
                 raise HomeAssistantAPIError(
                     f"Automation not found: {identifier} (unique_id: {unique_id})",
                     status_code=404,
@@ -915,18 +918,22 @@ class HomeAssistantClient:
             if entity_not_verified:
                 result["entity_not_verified"] = True
             return result
-        except Exception as e:
-            if "400" in str(e):
+        except HomeAssistantAPIError as e:
+            if e.status_code == 400:
                 raise HomeAssistantAPIError(
                     f"Invalid automation configuration: {str(e)}", status_code=400
                 ) from e
             raise
 
+    # 3-attempt × 6s upper-bound budget; first poll 0.1s catches the
+    # typical sub-1s entity-publish window.
+    _POLL_CADENCE: tuple[float, ...] = (0.1, 1.0, 4.9)
+
     async def _poll_for_automation_entity(self, unique_id: str) -> str | None:
         """Poll HA state to find the entity_id assigned to a newly created automation."""
         try:
-            for attempt in range(3):
-                await asyncio.sleep(1 * (attempt + 1))
+            for sleep_time in self._POLL_CADENCE:
+                await asyncio.sleep(sleep_time)
                 states = await self.get_states()
                 for state in states:
                     if not state.get("entity_id", "").startswith("automation."):
@@ -937,9 +944,14 @@ class HomeAssistantClient:
                             f"Found actual entity_id for unique_id {unique_id}: {entity_id}"
                         )
                         return entity_id
-        except Exception as e:
+        except HomeAssistantError as e:
+            # Narrow catch: programming bugs (TypeError/KeyError/etc.) propagate.
+            # Mirrors test-side _POLLING_TRANSIENT_ERRORS in
+            # tests/src/e2e/utilities/wait_helpers.py and styleguide §
+            # "Exception Handling in Test Polling Loops".
             logger.warning(
-                f"Failed to query actual entity_id for unique_id {unique_id}: {e}"
+                f"Failed to query actual entity_id for unique_id {unique_id}: {e}",
+                exc_info=True,
             )
             return None
 
@@ -1127,6 +1139,73 @@ class HomeAssistantClient:
             "DELETE", f"/config/config_entries/options/flow/{flow_id}"
         )
 
+    async def start_config_subentry_flow(
+        self,
+        entry_id: str,
+        subentry_type: str,
+        *,
+        subentry_id: str | None = None,
+        show_advanced_options: bool | None = None,
+    ) -> dict[str, Any]:
+        """Start a config subentry create or reconfigure flow."""
+        # HA requires the handler as [parent_entry_id, subentry_type].
+        payload: dict[str, Any] = {"handler": [entry_id, subentry_type]}
+        if subentry_id is not None:
+            payload["subentry_id"] = subentry_id
+        if show_advanced_options is not None:
+            payload["show_advanced_options"] = show_advanced_options
+
+        logger.debug(
+            "Starting config subentry flow for entry %s and type %s",
+            entry_id,
+            subentry_type,
+        )
+        return await self._request(
+            "POST",
+            "/config/config_entries/subentries/flow",
+            json=payload,
+        )
+
+    async def submit_config_subentry_flow_step(
+        self, flow_id: str, user_input: dict[str, Any]
+    ) -> dict[str, Any]:
+        """Submit data for a config subentry flow step."""
+        logger.debug("Submitting config subentry flow step for flow_id: %s", flow_id)
+        return await self._request(
+            "POST",
+            f"/config/config_entries/subentries/flow/{flow_id}",
+            json=user_input,
+        )
+
+    async def abort_config_subentry_flow(self, flow_id: str) -> dict[str, Any]:
+        """Abort an in-progress config subentry flow."""
+        logger.debug("Aborting config subentry flow: %s", flow_id)
+        return await self._request(
+            "DELETE", f"/config/config_entries/subentries/flow/{flow_id}"
+        )
+
+    async def list_config_subentries(self, entry_id: str) -> dict[str, Any]:
+        """List subentries for a config entry."""
+        logger.debug("Listing config subentries for entry: %s", entry_id)
+        return await self.send_websocket_message(
+            {"type": "config_entries/subentries/list", "entry_id": entry_id}
+        )
+
+    async def delete_config_subentry(
+        self,
+        entry_id: str,
+        subentry_id: str,
+    ) -> dict[str, Any]:
+        """Delete a config subentry."""
+        logger.debug("Deleting config subentry %s for entry %s", subentry_id, entry_id)
+        return await self.send_websocket_message(
+            {
+                "type": "config_entries/subentries/delete",
+                "entry_id": entry_id,
+                "subentry_id": subentry_id,
+            }
+        )
+
     async def get_config_entry(self, entry_id: str) -> dict[str, Any]:
         """
         Get config entry details.

{ha_mcp_dev-7.5.0.dev559 → ha_mcp_dev-7.5.0.dev561}/src/ha_mcp/tools/tools_config_entry_flow.py

@@ -62,6 +62,10 @@ FLOW_HELPER_TYPES: frozenset[str] = frozenset({
 
 # Keys used to specify a menu selection — stripped before submitting form data.
 _MENU_SELECTION_KEYS = frozenset({"group_type", "next_step_id", "menu_option"})
+_RECONFIGURE_SUCCESS_REASONS = frozenset({
+    "reauth_successful",
+    "reconfigure_successful",
+})
 
 
 class _FlowType(StrEnum):
@@ -364,9 +368,15 @@ async def _raise_flow_api_error(
     suggestions: list[str] = []
     message: str
 
+    current_schema = None
+    if current_step is not None:
+        step_schema = current_step.get("data_schema")
+        if isinstance(step_schema, list):
+            current_schema = step_schema
+
     # Single introspection round-trip — used by both branches below.
     info = await fetch_helper_flow_info(client, helper_type, menu_choice)
-    schema = info.get("schema")
+    schema = info.get("schema") or current_schema
 
     if field_errors:
         # Structured field errors — tell the caller which fields failed.
@@ -526,6 +536,197 @@ async def _handle_flow_steps(
     ))
 
 
+async def _handle_config_subentry_flow_steps(
+    client: Any,
+    flow_id: str,
+    initial_step: dict[str, Any],
+    config: dict[str, Any],
+    *,
+    is_reconfigure: bool,
+) -> dict[str, Any]:
+    """Walk a config subentry flow and accept HA's reconfigure-success abort."""
+    remaining_config = dict(config)
+    current_step = initial_step
+    last_menu_choice: str | None = None
+    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,
+                "operation": "created",
+                "flow_result": current_step,
+            }
+
+        if result_type == _FlowType.ABORT:
+            reason = current_step.get("reason")
+            if is_reconfigure and reason in _RECONFIGURE_SUCCESS_REASONS:
+                return {
+                    "success": True,
+                    "operation": "reconfigured",
+                    "flow_result": current_step,
+                }
+            raise_tool_error(create_error_response(
+                ErrorCode.SERVICE_CALL_FAILED,
+                f"Config subentry flow aborted: {reason}",
+                context={"flow_id": flow_id, "details": current_step},
+            ))
+
+        if result_type == _FlowType.MENU:
+            menu_choice = _handle_menu_step(flow_id, current_step, remaining_config)
+            last_menu_choice = menu_choice
+            logger.debug(
+                "Config subentry flow step %s: menu %s (step_id=%s)",
+                step_num,
+                menu_choice,
+                current_step.get("step_id"),
+            )
+            menu_payload = {"next_step_id": menu_choice}
+            try:
+                current_step = await asyncio.wait_for(
+                    client.submit_config_subentry_flow_step(flow_id, menu_payload),
+                    timeout=20.0,
+                )
+            except HomeAssistantAPIError as api_err:
+                if api_err.status_code in (400, 422):
+                    await _raise_flow_api_error(
+                        api_err,
+                        client=client,
+                        flow_id=flow_id,
+                        helper_type=None,
+                        menu_choice=last_menu_choice,
+                        current_step=current_step,
+                        submitted=menu_payload,
+                    )
+                raise
+            continue
+
+        if result_type == _FlowType.FORM:
+            form_data = _handle_form_step(flow_id, current_step, remaining_config)
+            logger.debug(
+                "Config subentry flow step %s: form submit "
+                "(step_id=%s, keys=%s)",
+                step_num,
+                current_step.get("step_id"),
+                sorted(form_data.keys()),
+            )
+            try:
+                current_step = await asyncio.wait_for(
+                    client.submit_config_subentry_flow_step(flow_id, form_data),
+                    timeout=20.0,
+                )
+            except HomeAssistantAPIError as api_err:
+                if api_err.status_code in (400, 422):
+                    await _raise_flow_api_error(
+                        api_err,
+                        client=client,
+                        flow_id=flow_id,
+                        helper_type=None,
+                        menu_choice=last_menu_choice,
+                        current_step=current_step,
+                        submitted=form_data,
+                    )
+                raise
+            continue
+
+        if result_type in {"progress", "progress_done"}:
+            raise_tool_error(create_error_response(
+                ErrorCode.SERVICE_CALL_FAILED,
+                "Config subentry flow requires an asynchronous progress step",
+                suggestions=[
+                    "Complete the provider setup in Home Assistant so the "
+                    "external resource is available.",
+                    "Retry the same ha_config_set_helper call after the "
+                    "resource is ready.",
+                ],
+                context={"flow_id": flow_id, "details": current_step},
+            ))
+
+        raise_tool_error(create_error_response(
+            ErrorCode.INTERNAL_UNEXPECTED,
+            f"Unexpected config subentry flow result type: {result_type}",
+            context={"flow_id": flow_id, "details": current_step},
+        ))
+
+    raise_tool_error(create_error_response(
+        ErrorCode.TIMEOUT_OPERATION,
+        f"Config subentry flow exceeded {max_steps} steps",
+        context={"flow_id": flow_id, "max_steps": max_steps},
+    ))
+
+
+async def set_config_subentry(
+    client: Any,
+    entry_id: str,
+    subentry_type: str,
+    config_dict: dict[str, Any],
+    *,
+    subentry_id: str | None = None,
+    show_advanced_options: bool | None = None,
+) -> dict[str, Any]:
+    """Create or reconfigure a config subentry via its flow.
+
+    Presence of ``subentry_id`` is the discriminator: omitted creates a new
+    subentry, provided reconfigures that existing subentry.
+    """
+    flow_result = await client.start_config_subentry_flow(
+        entry_id,
+        subentry_type,
+        subentry_id=subentry_id,
+        show_advanced_options=show_advanced_options,
+    )
+    flow_id = flow_result.get("flow_id")
+
+    if not flow_id:
+        raise_tool_error(create_error_response(
+            ErrorCode.SERVICE_CALL_FAILED,
+            "Failed to start config subentry flow",
+            suggestions=[
+                "Use ha_get_integration(include_subentries=True) to confirm "
+                "the parent entry and available subentry metadata.",
+            ],
+            context={
+                "entry_id": entry_id,
+                "subentry_type": subentry_type,
+                "subentry_id": subentry_id,
+                "details": flow_result,
+            },
+        ))
+
+    try:
+        result = await _handle_config_subentry_flow_steps(
+            client,
+            flow_id,
+            flow_result,
+            config_dict,
+            is_reconfigure=subentry_id is not None,
+        )
+    except Exception:
+        try:
+            await asyncio.wait_for(
+                client.abort_config_subentry_flow(flow_id), timeout=5.0
+            )
+        except Exception as abort_err:
+            logger.warning(
+                "Failed to abort config subentry flow %s after error: %s",
+                flow_id,
+                abort_err,
+            )
+        raise
+
+    return {
+        "success": True,
+        "entry_id": entry_id,
+        "subentry_type": subentry_type,
+        "subentry_id": subentry_id,
+        "operation": result["operation"],
+        "flow_result": result["flow_result"],
+        "message": f"Config subentry {result['operation']} successfully",
+    }
+
+
 async def get_user_step_field_names(
     client: Any, helper_type: str
 ) -> set[str] | None:
@@ -666,4 +867,3 @@ async def create_flow_helper(
         "domain": helper_type,
         "message": f"{helper_type} helper created successfully",
     }
-

{ha_mcp_dev-7.5.0.dev559 → ha_mcp_dev-7.5.0.dev561}/src/ha_mcp/tools/tools_config_helpers.py

@@ -27,6 +27,7 @@ from .tools_config_entry_flow import (
     create_flow_helper,
     fetch_helper_flow_info,
     get_user_step_field_names,
+    set_config_subentry,
     update_flow_helper,
 )
 from .util_helpers import (
@@ -1978,6 +1979,7 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         helper_type: Annotated[
             Literal[
                 "counter",
+                "config_subentry",
                 "derivative",
                 "filter",
                 "generic_hygrostat",
@@ -2011,12 +2013,13 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
             str | None,
             Field(
                 description=(
-                    "REQUIRED when creating (no helper_id provided). Display name "
-                    "for the helper. Optional on update — pass helper_id instead. "
-                    "For flow-based helper types on update (template, group, "
-                    "utility_meter, ...), this is typically ignored — options flows "
-                    "don't expose renaming. Rename a flow helper by deleting and "
-                    "recreating instead."
+                    "Display name for simple/flow helper creation. Required when "
+                    "creating a helper without helper_id. Optional on helper update. "
+                    "Ignored for helper_type='config_subentry', which uses "
+                    "entry_id/subentry_type/subentry_id instead. For flow-based "
+                    "helper updates (template, group, utility_meter, ...), this is "
+                    "typically ignored because options flows don't expose renaming. "
+                    "Rename a flow helper by deleting and recreating instead."
                 ),
                 default=None,
             ),
@@ -2028,6 +2031,46 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 default=None,
             ),
         ] = None,
+        entry_id: Annotated[
+            str | None,
+            Field(
+                description=(
+                    "Parent config entry ID when helper_type='config_subentry'. "
+                    "Use ha_get_integration() to find entry IDs."
+                ),
+                default=None,
+            ),
+        ] = None,
+        subentry_type: Annotated[
+            str | None,
+            Field(
+                description=(
+                    "Integration-defined subentry type when "
+                    "helper_type='config_subentry'."
+                ),
+                default=None,
+            ),
+        ] = None,
+        subentry_id: Annotated[
+            str | None,
+            Field(
+                description=(
+                    "Existing config subentry ID to reconfigure when "
+                    "helper_type='config_subentry'. Omit to create."
+                ),
+                default=None,
+            ),
+        ] = None,
+        show_advanced_options: Annotated[
+            bool | str,
+            Field(
+                description=(
+                    "When helper_type='config_subentry', ask Home Assistant "
+                    "to expose advanced flow options."
+                ),
+                default=False,
+            ),
+        ] = False,
         icon: Annotated[
             str | None,
             Field(
@@ -2249,7 +2292,8 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
             str | dict | None,
             Field(
                 description=(
-                    "Config dict for flow-based helper types "
+                    "Config dict for flow-based helper types and "
+                    "helper_type='config_subentry' "
                     "(template, group, utility_meter, derivative, min_max, threshold, "
                     "integration, statistics, trend, random, filter, tod, "
                     "generic_thermostat, switch_as_x, generic_hygrostat). "
@@ -2281,9 +2325,12 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         ] = None,
     ) -> dict[str, Any]:
         """
-        Create or update Home Assistant helper entities (27 types, unified interface).
+        Create or update Home Assistant helper entities and config subentries
+        (28 types, unified interface).
 
-        Create requires `name`; update requires `helper_id`.
+        SIMPLE/FLOW helper create requires `name`; SIMPLE/FLOW helper update
+        requires `helper_id`. Config subentry create requires `entry_id` and
+        `subentry_type`; config subentry update also requires `subentry_id`.
 
         SIMPLE types (structured params, WebSocket API): input_boolean, input_button,
         input_select, input_number, input_text, input_datetime, counter, timer, schedule,
@@ -2295,15 +2342,20 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         Note: `tod` is the purpose-built "is-current-time-in-range" indicator
         (supports cross-midnight ranges, unlike `schedule`).
 
+        CONFIG_SUBENTRY type (Config Subentry Flow API): config_subentry.
+        Pass `entry_id`, `subentry_type`, and `config`. Pass `subentry_id` to
+        reconfigure an existing subentry; omit it to create a new subentry.
+
         For flow-type updates, pass the existing entry_id as `helper_id`. Options flows
         reject the `name` key on update — to rename a flow helper, delete and recreate.
 
         Behavior notes:
         - UPDATE preserves type-specific fields not re-passed (rename never wipes
           initial/icon/etc. for any simple helper).
-        - Pass `action="create"` or `action="update"` to disambiguate intent —
-          without it the tool falls back to the implicit `helper_id`-presence
-          discriminator.
+        - Pass `action="create"` or `action="update"` to disambiguate intent.
+          For SIMPLE/FLOW helpers, omitted action falls back to the implicit
+          `helper_id`-presence discriminator. For config subentries, omitted
+          action falls back to the `subentry_id`-presence discriminator.
         - For flow-based helpers, config keys not declared by any step's
           data_schema are silently ignored by HA; submit once and the
           validation error returns the `data_schema` for that helper so
@@ -2327,13 +2379,110 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         - tod (time-of-day indicator, cross-midnight OK):
             ha_config_set_helper(helper_type="tod", name="Quiet Hours",
                 config={"after_time": "22:00:00", "before_time": "07:00:00"})
+        - config subentry (create under an existing integration):
+            ha_config_set_helper(helper_type="config_subentry",
+                entry_id="01HXYZ...", subentry_type="conversation",
+                config={"name": "Local agent", "model": "gemma3:27b"})
 
         For helper-design guidance (when to pick which helper type, YAML
         examples, per-type field tables), use ha_get_skill_guide — the
-        skill's `helper-selection.md` reference covers all 27 helper types
+        skill's `helper-selection.md` reference covers helper types
         with worked examples and a decision matrix.
         """
         try:
+            if helper_type == "config_subentry":
+                if action is not None:
+                    if action == "create" and subentry_id is not None:
+                        raise_tool_error(
+                            create_error_response(
+                                ErrorCode.VALIDATION_INVALID_PARAMETER,
+                                "action='create' was passed with subentry_id. "
+                                "Omit subentry_id to create a new subentry.",
+                                context={
+                                    "helper_type": helper_type,
+                                    "action": action,
+                                    "subentry_id": subentry_id,
+                                },
+                            )
+                        )
+                    if action == "update" and subentry_id is None:
+                        raise_tool_error(
+                            create_error_response(
+                                ErrorCode.VALIDATION_INVALID_PARAMETER,
+                                "action='update' requires subentry_id.",
+                                context={
+                                    "helper_type": helper_type,
+                                    "action": action,
+                                },
+                            )
+                        )
+                else:
+                    action = "update" if subentry_id else "create"
+
+                entry_id = validate_identifier_not_empty(
+                    entry_id,
+                    "entry_id",
+                    suggestions=[
+                        "Use ha_get_integration() to find the parent config entry ID",
+                    ],
+                    context={"helper_type": helper_type, "action": action},
+                )
+                subentry_type = validate_identifier_not_empty(
+                    subentry_type,
+                    "subentry_type",
+                    suggestions=[
+                        "Use ha_get_integration(entry_id=..., "
+                        "include_subentries=True, include_subentry_schema=True) "
+                        "to inspect available subentry metadata.",
+                    ],
+                    context={"helper_type": helper_type, "action": action},
+                )
+                if subentry_id is not None:
+                    subentry_id = validate_identifier_not_empty(
+                        subentry_id,
+                        "subentry_id",
+                        context={"helper_type": helper_type, "action": action},
+                    )
+                if not isinstance(config, dict):
+                    try:
+                        config_dict = (
+                            parse_json_param(config, "config") if config else {}
+                        )
+                    except ValueError as err:
+                        raise_tool_error(
+                            create_error_response(
+                                ErrorCode.VALIDATION_INVALID_PARAMETER,
+                                str(err),
+                                context={
+                                    "helper_type": helper_type,
+                                    "action": action,
+                                    "parameter": "config",
+                                },
+                            )
+                        )
+                else:
+                    config_dict = config
+                if not isinstance(config_dict, dict):
+                    raise_tool_error(
+                        create_error_response(
+                            ErrorCode.VALIDATION_INVALID_PARAMETER,
+                            "config must be an object for config_subentry",
+                            context={"helper_type": helper_type, "action": action},
+                        )
+                    )
+                return await set_config_subentry(
+                    client,
+                    entry_id,
+                    subentry_type,
+                    config_dict,
+                    subentry_id=subentry_id,
+                    show_advanced_options=coerce_bool_param(
+                        show_advanced_options,
+                        "show_advanced_options",
+                        default=False,
+                    ),
+                )
+
             # Determine if this is a create or update — set early so the
             # outer exception handler's context dict can reference it even
             # if an exception bubbles out of the flow-helper branch below.