ha-mcp-dev 8.6.0.dev2962__tar.gz → 8.6.0.dev2968__tar.gz

{ha_mcp_dev-8.6.0.dev2962 → ha_mcp_dev-8.6.0.dev2968}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.6.0.dev2962
+Version: 8.6.0.dev2968
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien

{ha_mcp_dev-8.6.0.dev2962 → ha_mcp_dev-8.6.0.dev2968}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev2962"
+version = "8.6.0.dev2968"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"

{ha_mcp_dev-8.6.0.dev2962 → ha_mcp_dev-8.6.0.dev2968}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.6.0.dev2962"
+version = "8.6.0.dev2968"
 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-8.6.0.dev2968/src/ha_mcp/tools/energy_statistics.py

@@ -0,0 +1,147 @@
+"""Read the recorder statistics referenced by native Energy Dashboard preferences."""
+
+from typing import Any, Literal
+
+from ha_mcp._vendor.fastmcp.exceptions import ToolError
+
+from ..errors import ErrorCode, create_error_response
+from ..utils.config_hash import compute_config_hash
+from .helpers import exception_to_structured_error, raise_tool_error
+from .statistics_helpers import fetch_statistics_metadata, statistics_unit
+
+
+def _statistic_ids(value: Any) -> set[str]:
+    """Collect statistic references across Core's source and device structures."""
+    found: set[str] = set()
+    if isinstance(value, list):
+        for item in value:
+            found.update(_statistic_ids(item))
+    elif isinstance(value, dict):
+        for key, item in value.items():
+            if (
+                (key.startswith("stat_") or key == "included_in_stat")
+                and isinstance(item, str)
+                and item
+            ):
+                found.add(item)
+            elif isinstance(item, (dict, list)):
+                found.update(_statistic_ids(item))
+    return found
+
+
+async def include_energy_statistics(
+    client: Any, result: dict[str, Any]
+) -> dict[str, Any]:
+    """Enrich the read response without including metadata in config or its hash."""
+    ids = sorted(_statistic_ids(result["config"]))
+    metadata, failure = await fetch_statistics_metadata(client, ids)
+    result["statistics_metadata"] = [
+        {
+            **(metadata.get(statistic_id) or {"statistic_id": statistic_id}),
+            **statistics_unit(metadata.get(statistic_id), failure),
+        }
+        for statistic_id in ids
+    ]
+    warnings = [
+        f"{row['statistic_id']}: {row['unit_reason']}"
+        for row in result["statistics_metadata"]
+        if row["unit_source"] == "unknown"
+    ]
+    if warnings:
+        result.setdefault("warnings", []).extend(warnings)
+    return result
+
+
+_PrefsKey = Literal["energy_sources", "device_consumption", "device_consumption_water"]
+_PREFS_TOP_LEVEL_KEYS: tuple[_PrefsKey, ...] = (
+    "energy_sources",
+    "device_consumption",
+    "device_consumption_water",
+)
+
+
+def _default_prefs() -> dict[str, Any]:
+    """Return the default empty prefs structure used by HA Core.
+
+    Mirrors ``EnergyManager.default_preferences()`` in
+    ``homeassistant/components/energy/data.py``. A Home Assistant instance
+    that has never had the Energy Dashboard configured returns
+    ``ERR_NOT_FOUND "No prefs"`` from ``energy/get_prefs``; this helper
+    provides the canonical empty structure so the tool can transparently
+    treat the two cases (never-configured vs. configured-but-empty) the
+    same way.
+    """
+    return {
+        "energy_sources": [],
+        "device_consumption": [],
+        "device_consumption_water": [],
+    }
+
+
+def _compute_per_key_hashes(prefs: dict[str, Any]) -> dict[_PrefsKey, str]:
+    """Per-top-level-key hashes for partial-update optimistic locking.
+
+    Each top-level key is wrapped in its own single-key dict before hashing,
+    so the per-key hash captures both the key name and its value — an agent
+    cannot accidentally use, say, an ``energy_sources`` hash to authorise a
+    ``device_consumption`` write. ``prefs.get(key, [])`` mirrors the
+    "missing top-level key = empty list" semantics codified by
+    ``_default_prefs``.
+    """
+    return {
+        key: compute_config_hash({key: prefs.get(key, [])})
+        for key in _PREFS_TOP_LEVEL_KEYS
+    }
+
+
+def _is_no_prefs_error(error_msg: str) -> bool:
+    """Return True if an error string from send_websocket_message indicates
+    ``ERR_NOT_FOUND "No prefs"`` from HA Core's energy/get_prefs handler.
+
+    HA Core wraps the error as ``f"Command failed: {message}"``; the
+    underlying sentinel we key on is the literal ``"No prefs"`` message
+    emitted by ``ws_get_prefs`` when ``manager.data is None``.
+    """
+    return error_msg.endswith("No prefs")
+
+
+async def get_energy_prefs(client: Any) -> dict[str, Any]:
+    """Read preferences, mapping Core's never-configured response to empty prefs."""
+    try:
+        result = await client.send_websocket_message({"type": "energy/get_prefs"})
+        note = None
+        if not result.get("success"):
+            if not _is_no_prefs_error(str(result.get("error", ""))):
+                raise_tool_error(
+                    create_error_response(
+                        ErrorCode.SERVICE_CALL_FAILED,
+                        f"Failed to get energy prefs: {result.get('error', 'Unknown error')}",
+                        context={"mode": "get"},
+                    )
+                )
+            prefs = _default_prefs()
+            note = "Energy Dashboard has never been configured on this instance; returning empty default."
+        else:
+            prefs = result.get("result") or _default_prefs()
+        response = {
+            "success": True,
+            "mode": "get",
+            "config": prefs,
+            "config_hash": compute_config_hash(prefs),
+            "config_hash_per_key": _compute_per_key_hashes(prefs),
+        }
+        if note:
+            response["note"] = note
+        return response
+    except ToolError:
+        raise
+    except Exception as e:  # noqa: BLE001
+        exception_to_structured_error(
+            e,
+            context={"mode": "get"},
+            suggestions=[
+                "Check Home Assistant connection",
+                "Verify WebSocket connection is active",
+            ],
+        )
+        return None  # unreachable: exception_to_structured_error always raises

ha_mcp_dev-8.6.0.dev2968/src/ha_mcp/tools/statistics_helpers.py

@@ -0,0 +1,101 @@
+"""Recorder metadata and output units, using the running Core's display rules."""
+
+import logging
+from typing import Any
+
+from .response_helpers import build_pagination_metadata
+
+logger = logging.getLogger(__name__)
+
+
+async def fetch_statistics_metadata(
+    client: Any, statistic_ids: list[str]
+) -> tuple[dict[str, dict[str, Any]], str | None]:
+    """Read native metadata without making the values query depend on its availability."""
+    if not statistic_ids:
+        return {}, None
+    try:
+        response = await client.send_websocket_message(
+            {"type": "recorder/get_statistics_metadata", "statistic_ids": statistic_ids}
+        )
+        if not response.get("success"):
+            return {}, "statistics_metadata_unavailable"
+        records = response.get("result")
+        if not isinstance(records, list):
+            return {}, "statistics_metadata_unavailable"
+        return {
+            record["statistic_id"]: record
+            for record in records
+            if isinstance(record, dict) and isinstance(record.get("statistic_id"), str)
+        }, None
+    except Exception:
+        # Metadata is supplementary: preserve usable rows and explicitly leave
+        # their units unresolved. Never silently substitute current state units.
+        logger.warning("Recorder statistics metadata lookup failed", exc_info=True)
+        return {}, "statistics_metadata_unavailable"
+
+
+def statistics_unit(
+    metadata: dict[str, Any] | None, failure: str | None = None
+) -> dict[str, Any]:
+    """Label default statistics output with Core's resolved display unit.
+
+    Core's statistics_during_period converts stored values to display units
+    when no explicit units are requested. get_statistics_metadata calls Core's
+    get_display_unit, including its handling of missing entities and invalid
+    state units. Stored units alone cannot establish the output unit.
+    """
+    unknown = {"unit_of_measurement": None, "unit_source": "unknown"}
+    if failure or metadata is None:
+        return {**unknown, "unit_reason": failure or "statistics_metadata_missing"}
+    if "display_unit_of_measurement" not in metadata:
+        return {**unknown, "unit_reason": "display_unit_not_reported"}
+    unit = metadata["display_unit_of_measurement"]
+    if unit is not None and not isinstance(unit, str):
+        return {**unknown, "unit_reason": "invalid_display_unit_metadata"}
+    result = {"unit_of_measurement": unit, "unit_source": "recorder_metadata"}
+    if unit is None:
+        if metadata.get("statistics_unit_of_measurement") is not None:
+            return {**unknown, "unit_reason": "display_unit_not_reported"}
+        result["unit_reason"] = "statistics_are_unitless"
+    return result
+
+
+def format_entity_statistics(
+    result_data: dict[str, Any],
+    entity_ids: list[str],
+    period: str,
+    offset: int,
+    limit: int,
+    metadata: dict[str, dict[str, Any]],
+    metadata_failure: str | None,
+) -> list[dict[str, Any]]:
+    """Preserve Core's row fields and attach units independently of pagination."""
+    entities = []
+    for entity_id in entity_ids:
+        rows = result_data.get(entity_id, [])
+        page = rows[offset : offset + limit]
+        record = metadata.get(entity_id)
+        entities.append(
+            {
+                "entity_id": entity_id,
+                "period": period,
+                "statistics": page,
+                **statistics_unit(record, metadata_failure),
+                "statistics_metadata": record,
+                **build_pagination_metadata(
+                    total_count=len(rows), offset=offset, limit=limit, count=len(page)
+                ),
+            }
+        )
+    return entities
+
+
+def statistics_warnings(entities: list[dict[str, Any]]) -> list[str]:
+    """Make unresolved units visible to callers without discarding numeric data."""
+    return [
+        f"{entity['entity_id']}: statistics output unit is unknown "
+        f"({entity['unit_reason']}); do not infer it from current state attributes."
+        for entity in entities
+        if entity["unit_source"] == "unknown"
+    ]

{ha_mcp_dev-8.6.0.dev2962 → ha_mcp_dev-8.6.0.dev2968}/src/ha_mcp/tools/tools_energy.py

@@ -38,6 +38,15 @@ from ha_mcp._vendor.fastmcp.tools import tool
 from ..errors import ErrorCode, create_error_response
 from ..utils.config_hash import compute_config_hash
 from .coercion import JSON_STRING_COERCION
+from .energy_statistics import (
+    _PREFS_TOP_LEVEL_KEYS,
+    _compute_per_key_hashes,
+    _default_prefs,
+    _is_no_prefs_error,
+    _PrefsKey,
+    get_energy_prefs,
+    include_energy_statistics,
+)
 from .helpers import (
     exception_to_structured_error,
     log_tool_usage,
@@ -55,12 +64,6 @@ logger = logging.getLogger(__name__)
 # corresponding ``Literal`` alias so MCP-wire callers (Pydantic-validated)
 # get typo-rejection at the boundary; runtime guards in `_set_prefs` cover
 # the unit-test path that bypasses Pydantic.
-_PrefsKey = Literal["energy_sources", "device_consumption", "device_consumption_water"]
-_PREFS_TOP_LEVEL_KEYS: tuple[_PrefsKey, ...] = (
-    "energy_sources",
-    "device_consumption",
-    "device_consumption_water",
-)
 
 # Energy source ``type`` values accepted by HA Core's ``SourceType`` union
 # (homeassistant/components/energy/data.py). ``_EnergySourceType`` names the
@@ -90,40 +93,6 @@ _STAT_FROM_SOURCE_TYPES: frozenset[str] = frozenset(
 )
 
 
-def _default_prefs() -> dict[str, Any]:
-    """Return the default empty prefs structure used by HA Core.
-
-    Mirrors ``EnergyManager.default_preferences()`` in
-    ``homeassistant/components/energy/data.py``. A Home Assistant instance
-    that has never had the Energy Dashboard configured returns
-    ``ERR_NOT_FOUND "No prefs"`` from ``energy/get_prefs``; this helper
-    provides the canonical empty structure so the tool can transparently
-    treat the two cases (never-configured vs. configured-but-empty) the
-    same way.
-    """
-    return {
-        "energy_sources": [],
-        "device_consumption": [],
-        "device_consumption_water": [],
-    }
-
-
-def _compute_per_key_hashes(prefs: dict[str, Any]) -> dict[_PrefsKey, str]:
-    """Per-top-level-key hashes for partial-update optimistic locking.
-
-    Each top-level key is wrapped in its own single-key dict before hashing,
-    so the per-key hash captures both the key name and its value — an agent
-    cannot accidentally use, say, an ``energy_sources`` hash to authorise a
-    ``device_consumption`` write. ``prefs.get(key, [])`` mirrors the
-    "missing top-level key = empty list" semantics codified by
-    ``_default_prefs``.
-    """
-    return {
-        key: compute_config_hash({key: prefs.get(key, [])})
-        for key in _PREFS_TOP_LEVEL_KEYS
-    }
-
-
 def _merge_submitted_keys(
     base: dict[str, Any], config: dict[str, Any]
 ) -> dict[str, Any]:
@@ -143,17 +112,6 @@ def _merge_submitted_keys(
     return merged
 
 
-def _is_no_prefs_error(error_msg: str) -> bool:
-    """Return True if an error string from send_websocket_message indicates
-    ``ERR_NOT_FOUND "No prefs"`` from HA Core's energy/get_prefs handler.
-
-    HA Core wraps the error as ``f"Command failed: {message}"``; the
-    underlying sentinel we key on is the literal ``"No prefs"`` message
-    emitted by ``ws_get_prefs`` when ``manager.data is None``.
-    """
-    return error_msg.endswith("No prefs")
-
-
 def _flatten_validation_errors(raw: Any) -> list[dict[str, str]]:
     """Convert the raw ``energy/validate`` response into a flat error list.
 
@@ -504,6 +462,12 @@ class EnergyTools:
                 default=None,
             ),
         ] = None,
+        include_statistics: Annotated[
+            bool,
+            Field(
+                description="With mode='get', include native recorder metadata and resolved output units for all configured statistic references. Ignored for other modes."
+            ),
+        ] = False,
     ) -> dict[str, Any]:
         """Manage the Home Assistant Energy Dashboard preferences: grid / solar /
         battery / gas / water energy sources, device consumption sensors for
@@ -519,6 +483,10 @@ class EnergyTools:
         - mode='add_source': append a single entry to ``energy_sources``.
           Same atomic read-modify-write semantics.
 
+        RELATED TOOLS: Use ha_get_history(source="statistics") with the returned
+        statistic IDs for consumption, totals, and trends. Metadata comes directly
+        from the running Core, including stored and display units.
+
         WHEN NOT TO USE:
         - To create the underlying statistics themselves — they must already
           exist as HA entities before being referenced here; create them via
@@ -549,7 +517,12 @@ class EnergyTools:
           de-duplicates grid sources.
         """
         if mode == "get":
-            return await self._get_prefs()
+            result = await self._get_prefs()
+            return (
+                await include_energy_statistics(self._client, result)
+                if include_statistics
+                else result
+            )
 
         if mode == "add_device":
             return await self._add_device(
@@ -606,66 +579,7 @@ class EnergyTools:
     # ------------------------------------------------------------------
 
     async def _get_prefs(self) -> dict[str, Any]:
-        """Fetch current prefs and return them with a config_hash.
-
-        On a Home Assistant instance that has never had the Energy Dashboard
-        configured, ``energy/get_prefs`` returns ``ERR_NOT_FOUND "No prefs"``
-        rather than an empty default. This method maps that case to the
-        documented default preferences structure so the tool works uniformly
-        on fresh installations.
-        """
-        try:
-            result = await self._client.send_websocket_message(
-                {
-                    "type": "energy/get_prefs",
-                }
-            )
-
-            if not result.get("success"):
-                error_msg = str(result.get("error", ""))
-                if _is_no_prefs_error(error_msg):
-                    prefs = _default_prefs()
-                    return {
-                        "success": True,
-                        "mode": "get",
-                        "config": prefs,
-                        "config_hash": compute_config_hash(prefs),
-                        "config_hash_per_key": _compute_per_key_hashes(prefs),
-                        "note": (
-                            "Energy Dashboard has never been configured on "
-                            "this instance; returning empty default."
-                        ),
-                    }
-                raise_tool_error(
-                    create_error_response(
-                        ErrorCode.SERVICE_CALL_FAILED,
-                        f"Failed to get energy prefs: {result.get('error', 'Unknown error')}",
-                        context={"mode": "get"},
-                    )
-                )
-
-            prefs = result.get("result") or _default_prefs()
-            return {
-                "success": True,
-                "mode": "get",
-                "config": prefs,
-                "config_hash": compute_config_hash(prefs),
-                "config_hash_per_key": _compute_per_key_hashes(prefs),
-            }
-
-        except ToolError:
-            raise
-        except Exception as e:  # noqa: BLE001
-            logger.error(f"Error getting energy prefs: {e}")
-            exception_to_structured_error(
-                e,
-                context={"mode": "get"},
-                suggestions=[
-                    "Check Home Assistant connection",
-                    "Verify WebSocket connection is active",
-                ],
-            )
-            return None  # unreachable: exception_to_structured_error always raises
+        return await get_energy_prefs(self._client)
 
     async def _dry_run(self, config: dict[str, Any]) -> dict[str, Any]:
         """Shape-check the proposed config and fetch current-state validate.

{ha_mcp_dev-8.6.0.dev2962 → ha_mcp_dev-8.6.0.dev2968}/src/ha_mcp/tools/tools_history.py

@@ -38,6 +38,11 @@ from .response_helpers import (
     project_fields,
     resolve_local_timezone,
 )
+from .statistics_helpers import (
+    fetch_statistics_metadata,
+    format_entity_statistics,
+    statistics_warnings,
+)
 from .tool_hints import read_only_hints
 from .util_helpers import is_connection_error_message
 
@@ -335,7 +340,11 @@ class HistoryTools:
         total_increasing).
 
         History-only params: minimal_response, significant_changes_only.
-        Statistics-only params: period, statistic_types.
+        Statistics-only params: period, statistic_types. Output units come from
+        Core recorder metadata and reflect its display-unit conversion; unresolved
+        units include a reason. statistics_metadata preserves Core's native fields.
+        Use ha_manage_energy_prefs(mode="get", include_statistics=True) to
+        discover the statistics configured in the Energy Dashboard.
 
         All data is fetched from HA before slicing; limit/offset are client-side.
         With multiple entity_ids, offset must be 0 — use a single entity_id for
@@ -427,8 +436,7 @@ class HistoryTools:
             )
 
             # Route through the shared pooled WebSocket (issue #1813) instead of
-            # a dedicated connect/auth handshake per call. Each source issues a
-            # single request/response WS command; the pooled client owns the
+            # a dedicated connect/auth handshake per call. Statistics also fetches native recorder metadata; the pooled client owns the
             # connection lifecycle, so there is no per-call connect/disconnect.
             if source == "statistics":
                 inner = await _fetch_statistics(
@@ -1048,51 +1056,6 @@ def _parse_statistic_types(
     return stat_types_list
 
 
-def _format_entity_statistics(
-    result_data: dict[str, Any],
-    entity_id_list: list[str],
-    all_stat_types: list[str],
-    period: str,
-    effective_offset: int,
-    effective_limit: int,
-) -> list[dict[str, Any]]:
-    """Format the per-entity statistics rows from a statistics_during_period result."""
-    entities_statistics = []
-    for entity_id in entity_id_list:
-        entity_stats = result_data.get(entity_id, [])
-        paged_stats = entity_stats[
-            effective_offset : effective_offset + effective_limit
-        ]
-        formatted_stats = []
-        unit = None
-
-        for stat in paged_stats:
-            stat_entry: dict[str, Any] = {"start": stat.get("start")}
-            for stat_type in all_stat_types:
-                if stat_type in stat:
-                    stat_entry[stat_type] = stat[stat_type]
-            if unit is None and "unit_of_measurement" in stat:
-                unit = stat["unit_of_measurement"]
-            formatted_stats.append(stat_entry)
-
-        pagination = build_pagination_metadata(
-            total_count=len(entity_stats),
-            offset=effective_offset,
-            limit=effective_limit,
-            count=len(formatted_stats),
-        )
-        entities_statistics.append(
-            {
-                "entity_id": entity_id,
-                "period": period,
-                "statistics": formatted_stats,
-                "unit_of_measurement": unit,
-                **pagination,
-            }
-        )
-    return entities_statistics
-
-
 async def _fetch_statistics(
     client: Any,
     entity_id_list: list[str],
@@ -1134,6 +1097,7 @@ async def _fetch_statistics(
     if stat_types_list is not None:
         command_params["types"] = stat_types_list
 
+    metadata, metadata_failure = await fetch_statistics_metadata(client, entity_id_list)
     response = await client.send_websocket_message(
         {"type": "recorder/statistics_during_period", **command_params}
     )
@@ -1152,13 +1116,14 @@ async def _fetch_statistics(
 
     result_data = response.get("result", {})
     all_stat_types = stat_types_list or ["mean", "min", "max", "sum", "state", "change"]
-    entities_statistics = _format_entity_statistics(
+    entities_statistics = format_entity_statistics(
         result_data,
         entity_id_list,
-        all_stat_types,
         period,
         effective_offset,
         effective_limit,
+        metadata,
+        metadata_failure,
     )
 
     empty_entities: list[str] = [
@@ -1182,10 +1147,13 @@ async def _fetch_statistics(
         },
     }
 
+    warnings = statistics_warnings(entities_statistics)
     if empty_entities:
-        statistics_data["warnings"] = [
+        warnings += [
             f"No statistics found for: {', '.join(empty_entities)}. "
             "These entities may not have state_class attribute or may not have recorded data yet."
         ]
 
+    if warnings:
+        statistics_data["warnings"] = warnings
     return statistics_data