ha-mcp-dev 7.4.1.dev443__tar.gz → 7.4.1.dev444__tar.gz

{ha_mcp_dev-7.4.1.dev443/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.4.1.dev444}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.4.1.dev443
+Version: 7.4.1.dev444
 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.4.1.dev443 → ha_mcp_dev-7.4.1.dev444}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.4.1.dev443"
+version = "7.4.1.dev444"
 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.4.1.dev443 → ha_mcp_dev-7.4.1.dev444}/src/ha_mcp/tools/tools_config_entry_flow.py

@@ -19,6 +19,7 @@ from fastmcp.exceptions import ToolError
 from fastmcp.tools import tool
 from pydantic import Field
 
+from ..client.rest_client import HomeAssistantAPIError
 from ..errors import ErrorCode, create_error_response
 from .helpers import (
     exception_to_structured_error,
@@ -126,6 +127,25 @@ def _handle_menu_step(
     return str(menu_choice)
 
 
+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.
+    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.
+    """
+    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)
+    return names
+
+
 def _handle_form_step(
     flow_id: str,
     current_step: dict[str, Any],
@@ -133,8 +153,16 @@ def _handle_form_step(
 ) -> dict[str, Any]:
     """Validate a form step and return form data to submit.
 
-    Raises ToolError on validation errors. Returns the filtered form data
-    (menu selection keys stripped).
+    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.
+
+    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
+    keeps single-step flows working when HA omits the schema.
+
+    Raises ToolError on validation errors.
     """
     if current_step.get("errors"):
         raise_tool_error(create_error_response(
@@ -149,19 +177,220 @@ def _handle_form_step(
             },
         ))
 
+    schema_fields = _extract_schema_field_names(current_step.get("data_schema"))
+
+    form_data: dict[str, Any] = {}
+    if schema_fields is None:
+        # 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.
+        for key in list(remaining_config.keys()):
+            if key in _MENU_SELECTION_KEYS:
+                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)
+
+    return form_data
+
+
+def _parse_flow_api_error(
+    api_error: HomeAssistantAPIError,
+) -> dict[str, Any]:
+    """Extract structured field-level info from an HA flow 4xx response.
+
+    Home Assistant returns voluptuous validation failures during flow
+    submission as either:
+
+    - ``{"message": "User input malformed: extra keys not allowed @ data['name']"}``
+      (raised before form validation, e.g. unknown field in payload)
+    - ``{"errors": {"base": "..."}, "description_placeholders": {...}}``
+      (per-field errors after voluptuous validation succeeds)
+    - Free-form text (when the body isn't JSON).
+
+    Returns a dict with at least:
+      - ``message``: the most informative human-readable string we found.
+      - ``field_errors``: dict of field-name -> error code/message, when
+        the body contained an ``errors`` map. Empty dict otherwise.
+      - ``raw``: the response_data dict (or ``None``) for diagnostics.
+    """
+    body = api_error.response_data or {}
+    field_errors: dict[str, Any] = {}
+    message_parts: list[str] = []
+
+    if isinstance(body, dict):
+        errors_field = body.get("errors")
+        if isinstance(errors_field, dict):
+            field_errors = {
+                key: val
+                for key, val in errors_field.items()
+                if isinstance(key, str)
+            }
+
+        # HA's stock 400 carries a `message` key with the voluptuous detail.
+        msg = body.get("message")
+        if isinstance(msg, str) and msg.strip():
+            message_parts.append(msg.strip())
+
+        # description_placeholders sometimes carry the human-readable error.
+        placeholders = body.get("description_placeholders")
+        if isinstance(placeholders, dict):
+            for key, val in placeholders.items():
+                if isinstance(val, str) and val.strip():
+                    message_parts.append(f"{key}: {val.strip()}")
+
+    if not message_parts:
+        # Fall back to the wrapper exception message ("API error: 400 - ...").
+        message_parts.append(str(api_error))
+
     return {
-        k: v
-        for k, v in remaining_config.items()
-        if k not in _MENU_SELECTION_KEYS
+        "message": " | ".join(dict.fromkeys(message_parts)),  # de-dupe, preserve order
+        "field_errors": field_errors,
+        "raw": body if isinstance(body, dict) else None,
     }
 
 
+async def _fetch_data_schema_for_error_context(
+    client: Any,
+    helper_type: str | None,
+    menu_choice: str | None,
+) -> list[Any] | None:
+    """Best-effort fetch of the helper's data_schema for error context.
+
+    Starts a fresh introspection flow (always aborted), and returns the
+    user step's ``data_schema`` so the LLM has something concrete to react
+    to when HA's error body is unstructured. Returns ``None`` on any
+    failure or when the helper is menu-based without a chosen branch.
+    """
+    if not helper_type or client is None:
+        return None
+    intro_flow_id: str | None = None
+    try:
+        flow_result = await client.start_config_flow(helper_type)
+        intro_flow_id = flow_result.get("flow_id")
+        flow_type = flow_result.get("type")
+
+        if flow_type == _FlowType.FORM:
+            schema = flow_result.get("data_schema")
+            return schema if isinstance(schema, list) else None
+
+        if flow_type == _FlowType.MENU and menu_choice and intro_flow_id:
+            try:
+                step = await asyncio.wait_for(
+                    client.submit_config_flow_step(
+                        intro_flow_id, {"next_step_id": menu_choice}
+                    ),
+                    timeout=10.0,
+                )
+            except Exception:
+                return None
+            if step.get("type") == _FlowType.FORM:
+                schema = step.get("data_schema")
+                return schema if isinstance(schema, list) else None
+        return None
+    except Exception:
+        return None
+    finally:
+        if intro_flow_id:
+            try:
+                await asyncio.wait_for(
+                    client.abort_config_flow(intro_flow_id), timeout=5.0
+                )
+            except Exception as abort_err:
+                logger.debug(
+                    f"Failed to abort introspection flow {intro_flow_id}: {abort_err}"
+                )
+
+
+async def _raise_flow_api_error(
+    api_error: HomeAssistantAPIError,
+    *,
+    client: Any,
+    flow_id: str,
+    helper_type: str | None,
+    menu_choice: str | None,
+    current_step: dict[str, Any] | None,
+    submitted: dict[str, Any] | None,
+) -> None:
+    """Translate an HA 4xx during a flow submit into a structured ToolError.
+
+    For 400/422 responses, parses ``response_data`` for field-level info
+    via ``_parse_flow_api_error``. When the body is unstructured (no
+    ``errors`` map), attaches the helper's ``data_schema`` (if it can be
+    fetched) so the caller has actionable information.
+
+    Always raises ``ToolError`` — never returns.
+    """
+    parsed = _parse_flow_api_error(api_error)
+    field_errors = parsed["field_errors"]
+    status_code = api_error.status_code or 0
+
+    context: dict[str, Any] = {
+        "flow_id": flow_id,
+        "status_code": status_code,
+    }
+    if helper_type:
+        context["helper_type"] = helper_type
+    if menu_choice:
+        context["menu_choice"] = menu_choice
+    if current_step is not None:
+        context["step_id"] = current_step.get("step_id")
+    if submitted is not None:
+        context["submitted_keys"] = sorted(submitted.keys())
+    if parsed["raw"] is not None:
+        context["response_body"] = parsed["raw"]
+
+    suggestions: list[str] = []
+    message: str
+
+    if field_errors:
+        # Structured field errors — tell the caller which fields failed.
+        context["field_errors"] = field_errors
+        readable = ", ".join(f"{k}: {v}" for k, v in field_errors.items())
+        message = f"Helper validation failed — {readable}"
+        suggestions.append(
+            "Fix the field(s) listed in 'field_errors' and retry the call."
+        )
+    else:
+        # Unstructured — attach the data_schema so the LLM has something to use.
+        message = (
+            f"Home Assistant rejected the {helper_type or 'flow'} request "
+            f"({status_code}): {parsed['message']}"
+        )
+        schema = await _fetch_data_schema_for_error_context(
+            client, helper_type, menu_choice
+        )
+        if schema is not None:
+            context["data_schema"] = schema
+            suggestions.append(
+                "Inspect 'data_schema' in this error to see the fields HA expects, "
+                "then retry with a corrected config."
+            )
+        suggestions.append(
+            f"Call ha_get_helper_schema(helper_type='{helper_type}') for the "
+            f"full field list and selectors." if helper_type else
+            "Call ha_get_helper_schema for this helper to see required fields."
+        )
+
+    raise_tool_error(create_error_response(
+        ErrorCode.SERVICE_CALL_FAILED,
+        message,
+        suggestions=suggestions,
+        context=context,
+    ))
+
+
 async def _handle_flow_steps(
     client: Any,
     flow_id: str,
     initial_step: dict[str, Any],
     config: dict[str, Any],
     submit_fn: Any = None,
+    helper_type: str | None = None,
 ) -> dict[str, Any]:
     """Walk a multi-step config flow handling menu and form steps (max 10 steps).
 
@@ -181,6 +410,9 @@ async def _handle_flow_steps(
         submit_fn: Async function to submit a step. Defaults to
             client.submit_config_flow_step (create). Pass
             client.submit_options_flow_step for options (update) flows.
+        helper_type: Optional helper type (e.g. ``"statistics"``). When
+            provided, surfaces the helper's data_schema in error context
+            for unstructured HA 4xx responses so the caller can react.
 
     Returns:
         ``{"success": True, "entry": result}`` on success.
@@ -190,6 +422,7 @@ async def _handle_flow_steps(
         submit_fn = client.submit_config_flow_step
     remaining_config = dict(config)
     current_step = initial_step
+    last_menu_choice: str | None = None
     max_steps = 10
 
     for step_num in range(max_steps):
@@ -207,27 +440,57 @@ async def _handle_flow_steps(
 
         if result_type == _FlowType.MENU:
             menu_choice = _handle_menu_step(flow_id, current_step, remaining_config)
+            last_menu_choice = menu_choice
             logger.debug(
                 f"Flow step {step_num}: menu '{menu_choice}' "
                 f"(step_id={current_step.get('step_id')})"
             )
-            current_step = await asyncio.wait_for(
-                submit_fn(flow_id, {"next_step_id": menu_choice}),
-                timeout=20.0,
-            )
+            menu_payload = {"next_step_id": menu_choice}
+            try:
+                current_step = await asyncio.wait_for(
+                    submit_fn(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=helper_type,
+                        menu_choice=last_menu_choice,
+                        current_step=current_step,
+                        submitted=menu_payload,
+                    )
+                raise
 
         elif result_type == _FlowType.FORM:
+            # _handle_form_step pops only the keys declared in the current
+            # 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)
             logger.debug(
                 f"Flow step {step_num}: form submit "
                 f"(step_id={current_step.get('step_id')}, keys={list(form_data.keys())})"
             )
-            current_step = await asyncio.wait_for(
-                submit_fn(flow_id, form_data),
-                timeout=20.0,
-            )
-            # Clear so subsequent steps don't re-submit the same data.
-            remaining_config = {}
+            try:
+                current_step = await asyncio.wait_for(
+                    submit_fn(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=helper_type,
+                        menu_choice=last_menu_choice,
+                        current_step=current_step,
+                        submitted=form_data,
+                    )
+                raise
 
         else:
             raise_tool_error(create_error_response(
@@ -243,6 +506,47 @@ async def _handle_flow_steps(
     ))
 
 
+async def get_user_step_field_names(
+    client: Any, helper_type: str
+) -> set[str] | None:
+    """Return field names in the user-step form schema for ``helper_type``.
+
+    Starts a config flow, peeks at the initial step's ``data_schema``,
+    and immediately aborts the flow. Used to decide whether to fold the
+    top-level ``name`` parameter into the form payload — some helpers
+    (e.g. ``switch_as_x``) take their entity name from the source switch
+    and reject ``name`` as an extra key.
+
+    Returns:
+        A set of field names if the initial step is a form. ``None`` if
+        the flow type is not introspectable from the top step (menu or
+        unexpected) — callers should fall back to the legacy behaviour
+        in that case to avoid regressing menu helpers (template, group).
+        Also returns ``None`` if the introspection itself fails; the
+        subsequent real flow will surface the error in context.
+    """
+    flow_id = None
+    try:
+        flow_result = await client.start_config_flow(helper_type)
+        flow_id = flow_result.get("flow_id")
+        if flow_result.get("type") != _FlowType.FORM:
+            return None
+        return _extract_schema_field_names(flow_result.get("data_schema"))
+    except Exception as e:
+        logger.debug(f"Schema introspection failed for {helper_type}: {e}")
+        return None
+    finally:
+        if flow_id:
+            try:
+                await asyncio.wait_for(
+                    client.abort_config_flow(flow_id), timeout=5.0
+                )
+            except Exception as abort_err:
+                logger.warning(
+                    f"Failed to abort introspection flow {flow_id}: {abort_err}"
+                )
+
+
 async def update_flow_helper(
     client: Any,
     helper_type: str,
@@ -281,6 +585,7 @@ async def update_flow_helper(
         result = await _handle_flow_steps(
             client, flow_id, flow_result, config_dict,
             submit_fn=client.submit_options_flow_step,
+            helper_type=helper_type,
         )
     except Exception:
         try:
@@ -322,7 +627,10 @@ async def create_flow_helper(
         ))
 
     try:
-        result = await _handle_flow_steps(client, flow_id, flow_result, config_dict)
+        result = await _handle_flow_steps(
+            client, flow_id, flow_result, config_dict,
+            helper_type=helper_type,
+        )
     except Exception:
         try:
             await asyncio.wait_for(client.abort_config_flow(flow_id), timeout=5.0)