ha-mcp-dev 7.2.0.dev362__tar.gz → 7.2.0.dev363__tar.gz

{ha_mcp_dev-7.2.0.dev362/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.2.0.dev363}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.2.0.dev362
+Version: 7.2.0.dev363
 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.2.0.dev362 → ha_mcp_dev-7.2.0.dev363}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.2.0.dev362"
+version = "7.2.0.dev363"
 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.2.0.dev362 → ha_mcp_dev-7.2.0.dev363}/src/ha_mcp/tools/tools_history.py

@@ -28,6 +28,7 @@ from .helpers import (
 )
 from .util_helpers import (
     add_timezone_metadata,
+    build_pagination_metadata,
     coerce_int_param,
     parse_string_list_param,
 )
@@ -178,7 +179,14 @@ class HistoryTools:
         limit: Annotated[
             int | str | None,
             Field(
-                description='Max state changes per entity. Default: 100, Max: 1000. Ignored when source="statistics"',
+                description='Max entries per entity. Default: 100, Max: 1000. For source="history": state changes. For source="statistics": aggregated rows. With multiple entity_ids, offset must be 0 and total rows returned can reach limit × len(entity_ids).',
+                default=None,
+            ),
+        ] = None,
+        offset: Annotated[
+            int | str | None,
+            Field(
+                description="Number of entries to skip per entity for pagination. Default: 0. Offset > 0 requires a single entity_id. Use with limit and has_more/next_offset in the response.",
                 default=None,
             ),
         ] = None,
@@ -205,9 +213,9 @@ class HistoryTools:
         - "history" (default): Raw state changes, ~10 day retention, full resolution
         - "statistics": Pre-aggregated data, permanent retention, requires state_class
 
-        **Shared params:** entity_ids, start_time, end_time
-        **History params:** minimal_response, significant_changes_only, limit (ignored for statistics)
-        **Statistics params:** period, statistic_types (ignored for history)
+        **Shared params:** entity_ids, start_time, end_time, limit, offset
+        **History params:** minimal_response, significant_changes_only
+        **Statistics params:** period, statistic_types
 
         **Default time range:** 24h for history, 30 days for statistics
 
@@ -221,10 +229,16 @@ class HistoryTools:
         - Computing period averages ("Average living room temperature over 6 months?")
         - Entities must have state_class (measurement, total, total_increasing)
 
+        **WARNING:** limit and offset apply per entity (not globally across all entities).
+        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 offset > 0.
+        Use has_more and next_offset from the response to paginate.
+
         **Example -- history (default):**
         ```python
         ha_get_history(entity_ids="sensor.bedroom_temperature", start_time="24h")
         ha_get_history(entity_ids=["sensor.temperature", "sensor.humidity"], start_time="7d", limit=500)
+        ha_get_history(entity_ids="sensor.temperature", start_time="7d", limit=100, offset=100)
         ```
 
         **Example -- statistics:**
@@ -232,12 +246,42 @@ class HistoryTools:
         ha_get_history(source="statistics", entity_ids="sensor.total_energy_kwh", start_time="30d", period="day")
         ha_get_history(source="statistics", entity_ids="sensor.living_room_temperature",
                        start_time="6m", period="month", statistic_types=["mean", "min", "max"])
+        ha_get_history(source="statistics", entity_ids="sensor.energy_kwh",
+                       start_time="30d", period="5minute", limit=100, offset=200)
         ```
         """
         try:
             # Parse entity_ids
             entity_id_list = _parse_entity_ids(entity_ids)
 
+            # Offset > 0 is only supported for single-entity requests.
+            # build_pagination_metadata applies per entity — limit=100 across
+            # 5 entities returns up to 500 rows with no top-level has_more signal.
+            # Coerce and validate offset before the multi-entity guard so that
+            # invalid strings (e.g. "garbage") produce VALIDATION_INVALID_PARAMETER
+            # instead of a bare ValueError swallowed by the outer except.
+            try:
+                _effective_offset_check = coerce_int_param(
+                    offset,
+                    param_name="offset",
+                    default=0,
+                    min_value=0,
+                )
+            except ValueError as e:
+                raise_tool_error(create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    str(e),
+                    context={"parameter": "offset"},
+                    suggestions=["Provide offset as a non-negative integer (e.g., 0)"],
+                ))
+            if _effective_offset_check > 0 and len(entity_id_list) > 1:
+                raise_tool_error(create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    "offset > 0 requires a single entity_id",
+                    context={"offset": offset, "entity_count": len(entity_id_list)},
+                    suggestions=["Use a single entity_id when offset > 0, or use offset=0 for multi-entity requests."],
+                ))
+
             # Source-dependent default hours
             default_hours = _DEFAULT_START_HOURS_BY_SOURCE[source]
 
@@ -259,12 +303,13 @@ class HistoryTools:
                     return await _fetch_statistics(
                         ws_client, self._client, entity_id_list,
                         start_dt, end_dt, period, statistic_types,
+                        limit, offset,
                     )
                 else:
                     return await _fetch_history(
                         ws_client, self._client, entity_id_list,
                         start_dt, end_dt, minimal_response,
-                        significant_changes_only, limit,
+                        significant_changes_only, limit, offset,
                         _DEFAULT_HISTORY_LIMIT, _MAX_HISTORY_LIMIT,
                     )
             finally:
@@ -371,6 +416,7 @@ async def _fetch_history(
     minimal_response: bool,
     significant_changes_only: bool,
     limit: int | str | None,
+    offset: int | str | None,
     default_limit: int,
     max_limit: int,
 ) -> dict[str, Any]:
@@ -382,7 +428,7 @@ async def _fetch_history(
             default=default_limit,
             min_value=1,
             max_value=max_limit,
-        ) or default_limit
+        )
     except ValueError as e:
         raise_tool_error(create_error_response(
             ErrorCode.VALIDATION_INVALID_PARAMETER,
@@ -391,6 +437,21 @@ async def _fetch_history(
             suggestions=["Provide limit as an integer (e.g., 100)"],
         ))
 
+    try:
+        effective_offset = coerce_int_param(
+            offset,
+            param_name="offset",
+            default=0,
+            min_value=0,
+        )
+    except ValueError as e:
+        raise_tool_error(create_error_response(
+            ErrorCode.VALIDATION_INVALID_PARAMETER,
+            str(e),
+            context={"parameter": "offset"},
+            suggestions=["Provide offset as a non-negative integer (e.g., 0)"],
+        ))
+
     command_params = {
         "start_time": start_dt.isoformat(),
         "end_time": end_dt.isoformat(),
@@ -422,10 +483,10 @@ async def _fetch_history(
 
     for entity_id in entity_id_list:
         entity_states = result_data.get(entity_id, [])
-        limited_states = entity_states[:effective_limit]
+        paged_states = entity_states[effective_offset : effective_offset + effective_limit]
 
         formatted_states = []
-        for state in limited_states:
+        for state in paged_states:
             last_updated_raw = state.get("lu", state.get("last_updated"))
             last_changed_raw = state.get("lc", state.get("last_changed"))
             if last_changed_raw is None and last_updated_raw is not None:
@@ -440,6 +501,12 @@ async def _fetch_history(
                 state_entry["attributes"] = state.get("a", state.get("attributes", {}))
             formatted_states.append(state_entry)
 
+        pagination = build_pagination_metadata(
+            total_count=len(entity_states),
+            offset=effective_offset,
+            limit=effective_limit,
+            count=len(formatted_states),
+        )
         entities_history.append({
             "entity_id": entity_id,
             "period": {
@@ -447,9 +514,7 @@ async def _fetch_history(
                 "end": end_dt.isoformat(),
             },
             "states": formatted_states,
-            "count": len(formatted_states),
-            "total_available": len(entity_states),
-            "truncated": len(entity_states) > effective_limit,
+            **pagination,
         })
 
     history_data = {
@@ -464,6 +529,7 @@ async def _fetch_history(
             "minimal_response": minimal_response,
             "significant_changes_only": significant_changes_only,
             "limit": effective_limit,
+            "offset": effective_offset,
         },
     }
 
@@ -478,8 +544,41 @@ async def _fetch_statistics(
     end_dt: datetime,
     period: str,
     statistic_types: str | list[str] | None,
+    limit: int | str | None,
+    offset: int | str | None,
 ) -> dict[str, Any]:
     """Execute the recorder/statistics_during_period WebSocket call."""
+    try:
+        effective_limit = coerce_int_param(
+            limit,
+            param_name="limit",
+            default=_DEFAULT_HISTORY_LIMIT,
+            min_value=1,
+            max_value=_MAX_HISTORY_LIMIT,
+        )
+    except ValueError as e:
+        raise_tool_error(create_error_response(
+            ErrorCode.VALIDATION_INVALID_PARAMETER,
+            str(e),
+            context={"parameter": "limit"},
+            suggestions=["Provide limit as an integer (e.g., 100)"],
+        ))
+
+    try:
+        effective_offset = coerce_int_param(
+            offset,
+            param_name="offset",
+            default=0,
+            min_value=0,
+        )
+    except ValueError as e:
+        raise_tool_error(create_error_response(
+            ErrorCode.VALIDATION_INVALID_PARAMETER,
+            str(e),
+            context={"parameter": "offset"},
+            suggestions=["Provide offset as a non-negative integer (e.g., 0)"],
+        ))
+
     # Validate period
     valid_periods = ["5minute", "hour", "day", "week", "month"]
     if period not in valid_periods:
@@ -547,10 +646,11 @@ async def _fetch_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 entity_stats:
+        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:
@@ -559,12 +659,18 @@ async def _fetch_statistics(
                 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,
-            "count": len(formatted_stats),
             "unit_of_measurement": unit,
+            **pagination,
         })
 
     empty_entities: list[str] = [

{ha_mcp_dev-7.2.0.dev362 → ha_mcp_dev-7.2.0.dev363/src/ha_mcp_dev.egg-info}/PKG-INFO

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