ha-mcp-dev 7.12.3.dev1940__tar.gz → 7.12.3.dev1942__tar.gz

{ha_mcp_dev-7.12.3.dev1940/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.12.3.dev1942}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.12.3.dev1940
+Version: 7.12.3.dev1942
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -41,7 +41,7 @@ Dynamic: license-file
   <!-- mcp-name: io.github.homeassistant-ai/ha-mcp -->
 
   <p align="center">
-    <img src="https://img.shields.io/badge/tools-88-blue" alt="95+ Tools">
+    <img src="https://img.shields.io/badge/tools-87-blue" alt="95+ Tools">
     <a href="https://github.com/homeassistant-ai/ha-mcp/releases"><img src="https://img.shields.io/github/v/release/homeassistant-ai/ha-mcp" alt="Release"></a>
     <a href="https://github.com/homeassistant-ai/ha-mcp/actions/workflows/e2e-tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/homeassistant-ai/ha-mcp/e2e-tests.yml?branch=master&label=E2E%20Tests" alt="E2E Tests"></a>
     <a href="LICENSE.md"><img src="https://img.shields.io/github/license/homeassistant-ai/ha-mcp.svg" alt="License"></a>
@@ -247,7 +247,7 @@ Spend less time configuring, more time enjoying your smart home.
 <details>
 <!-- TOOLS_TABLE_START -->
 
-<summary><b>Complete Tool List (88 tools)</b></summary>
+<summary><b>Complete Tool List (87 tools)</b></summary>
 
 | Category | Tools |
 |----------|-------|
@@ -278,7 +278,7 @@ Spend less time configuring, more time enjoying your smart home.
 | **Service & Device Control** | `ha_bulk_control`, `ha_call_event`, `ha_call_service`, `ha_get_operation_status`, `ha_list_services` |
 | **System** | `ha_config_get_yaml` *(beta)*, `ha_config_set_yaml` *(beta)*, `ha_manage_backup`, `ha_manage_custom_tool` *(beta)*, `ha_manage_theme`, `ha_manage_updates`, `ha_reload_core`, `ha_restart` |
 | **Todo Lists** | `ha_get_todo`, `ha_remove_todo_item`, `ha_set_todo_item` |
-| **Utilities** | `ha_eval_template`, `ha_install_mcp_tools` *(beta)*, `ha_report_issue` |
+| **Utilities** | `ha_eval_template`, `ha_report_issue` |
 | **Zones** | `ha_get_zone`, `ha_remove_zone`, `ha_set_zone` |
 
 <!-- TOOLS_TABLE_END -->

{ha_mcp_dev-7.12.3.dev1940 → ha_mcp_dev-7.12.3.dev1942}/README.md

@@ -8,7 +8,7 @@
   <!-- mcp-name: io.github.homeassistant-ai/ha-mcp -->
 
   <p align="center">
-    <img src="https://img.shields.io/badge/tools-88-blue" alt="95+ Tools">
+    <img src="https://img.shields.io/badge/tools-87-blue" alt="95+ Tools">
     <a href="https://github.com/homeassistant-ai/ha-mcp/releases"><img src="https://img.shields.io/github/v/release/homeassistant-ai/ha-mcp" alt="Release"></a>
     <a href="https://github.com/homeassistant-ai/ha-mcp/actions/workflows/e2e-tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/homeassistant-ai/ha-mcp/e2e-tests.yml?branch=master&label=E2E%20Tests" alt="E2E Tests"></a>
     <a href="LICENSE.md"><img src="https://img.shields.io/github/license/homeassistant-ai/ha-mcp.svg" alt="License"></a>
@@ -214,7 +214,7 @@ Spend less time configuring, more time enjoying your smart home.
 <details>
 <!-- TOOLS_TABLE_START -->
 
-<summary><b>Complete Tool List (88 tools)</b></summary>
+<summary><b>Complete Tool List (87 tools)</b></summary>
 
 | Category | Tools |
 |----------|-------|
@@ -245,7 +245,7 @@ Spend less time configuring, more time enjoying your smart home.
 | **Service & Device Control** | `ha_bulk_control`, `ha_call_event`, `ha_call_service`, `ha_get_operation_status`, `ha_list_services` |
 | **System** | `ha_config_get_yaml` *(beta)*, `ha_config_set_yaml` *(beta)*, `ha_manage_backup`, `ha_manage_custom_tool` *(beta)*, `ha_manage_theme`, `ha_manage_updates`, `ha_reload_core`, `ha_restart` |
 | **Todo Lists** | `ha_get_todo`, `ha_remove_todo_item`, `ha_set_todo_item` |
-| **Utilities** | `ha_eval_template`, `ha_install_mcp_tools` *(beta)*, `ha_report_issue` |
+| **Utilities** | `ha_eval_template`, `ha_report_issue` |
 | **Zones** | `ha_get_zone`, `ha_remove_zone`, `ha_set_zone` |
 
 <!-- TOOLS_TABLE_END -->

{ha_mcp_dev-7.12.3.dev1940 → ha_mcp_dev-7.12.3.dev1942}/pyproject.toml

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

@@ -632,9 +632,8 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
             "Create or update a Home Assistant script.\n\n"
             "Supports two modes: full `config` replacement, or surgical "
             "`python_transform` on an existing script (requires "
-            "`identifier` and `config_hash` from "
-            "ha_config_get_script). Omit `identifier` to create a new "
-            "script.\n\n"
+            "`config_hash` from ha_config_get_script). `script_id` names "
+            "the script in both modes.\n\n"
             "For schema details and examples, see "
             "ha_get_skill_guide."
         ),
@@ -650,19 +649,20 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
             "Create or update a Home Assistant scene.\n\n"
             "Supports two modes: full `config` replacement, or surgical "
             "`python_transform` on an existing scene (requires "
-            "`identifier` and `config_hash`).\n\n"
+            "`config_hash`). `scene_id` names the scene in both modes.\n\n"
             "For schema details and examples, see "
             "ha_get_skill_guide."
         ),
         "ha_config_list_helpers": (
-            "List Home Assistant helpers of a given simple type. "
-            "Accepts the 12 storage-backed helper types only: "
-            "input_button, input_boolean, input_select, input_number, "
+            "List Home Assistant helpers of a given type, one page per "
+            "call (`limit`/`offset`; `total_count` and `has_more` "
+            "describe the full set). The 12 storage-backed types "
+            "(input_button, input_boolean, input_select, input_number, "
             "input_text, input_datetime, counter, timer, schedule, "
-            "zone, person, tag. Flow-based helpers (template, group, "
-            "utility_meter, derivative, statistics, trend, threshold, "
-            "filter, switch_as_x, etc.) cannot be listed through this "
-            "tool — use ha_search.\n\n"
+            "zone, person, tag) are listed on every install. Flow-based "
+            "types (template, group, utility_meter, derivative, and the "
+            "rest) and `helper_type='all'` are served only through the "
+            "ha_mcp_tools custom component.\n\n"
             "For per-type schemas and decision guidance, see "
             "ha_get_skill_guide."
         ),

{ha_mcp_dev-7.12.3.dev1940 → ha_mcp_dev-7.12.3.dev1942}/src/ha_mcp/tools/tools_config_helpers.py

@@ -53,6 +53,7 @@ from .util_helpers import (
     attach_skill_content,
     augment_error_dict_with_skill_content,
     augment_tool_error_with_skill_content,
+    build_pagination_metadata,
     parse_json_param,
     parse_string_list_param,
     wait_for_entity_registered,
@@ -1356,21 +1357,36 @@ def _flatten_helper_list_result(result: Any) -> list[Any]:
     """Flatten a {type}/list WS response into a flat list of helper dicts.
 
     Handles the person/list shape ({"storage": [...], "config": [...]}) and
-    the standard list shape ([...]).
+    the standard list shape ([...]). An unrecognised shape yields an empty
+    list, which downstream is indistinguishable from a helper type that has no
+    entries, so it is logged rather than dropped in silence.
     """
     if isinstance(result, dict):
         inner = result.get("result", [])
         if isinstance(inner, dict):
             items: list[Any] = []
+            matched = False
             for key in ("storage", "config"):
                 sub = inner.get(key)
                 if isinstance(sub, list):
+                    matched = True
                     items.extend(sub)
+            if not matched:
+                logger.warning(
+                    "Helper listing has neither a 'storage' nor a 'config' list "
+                    "(keys: %s); treating it as empty",
+                    sorted(inner),
+                )
             return items
         if isinstance(inner, list):
             return inner
     if isinstance(result, list):
         return result
+    logger.warning(
+        "Cannot flatten a helper listing: expected a list or a storage/config "
+        "split, got %s; treating it as empty",
+        type(result).__name__,
+    )
     return []
 
 
@@ -3508,6 +3524,53 @@ def _shape_flow_helper_record(rec: dict[str, Any]) -> dict[str, Any]:
     return out
 
 
+def _paginate_helpers_response(
+    response: dict[str, Any], offset: int, limit: int
+) -> dict[str, Any]:
+    """Slice a helper listing envelope down to one page.
+
+    The single normalization point for every ``ha_config_list_helpers`` route
+    (all-types, component, legacy): each builds the same
+    ``success``/``helper_type``/``count``/``helpers``/``message`` envelope, so
+    the slice is applied once here instead of in each builder. ``count`` becomes
+    the page size and ``total_count`` carries the full size, matching
+    ``ha_list_services``.
+    """
+    helpers = response.get("helpers")
+    if not isinstance(helpers, list):
+        # Every builder owes this function a flat list; anything else is a bug in
+        # the caller (a {type}/list shape that escaped _flatten_helper_list_result).
+        # The records are still usable, so return them unpaginated rather than
+        # raising -- but say so in warnings[], not just the log: the caller is an
+        # agent that never sees server logs, and absent metadata otherwise reads
+        # as "the collection fits on one page".
+        shape = type(helpers).__name__
+        logger.warning(
+            "Cannot paginate %r listing: expected a list of helpers, got %s; "
+            "returning the envelope unpaginated",
+            response.get("helper_type"),
+            shape,
+        )
+        warning = (
+            f"Listing could not be paginated (expected a list of helpers, got "
+            f"{shape}); returned in full, without pagination metadata."
+        )
+        existing = response.get("warnings")
+        return {
+            **response,
+            "warnings": [*existing, warning]
+            if isinstance(existing, list)
+            else [warning],
+        }
+    total_count = len(helpers)
+    page = helpers[offset : offset + limit]
+    return {
+        **response,
+        "helpers": page,
+        **build_pagination_metadata(total_count, offset, limit, len(page)),
+    }
+
+
 def _shape_component_helpers_response(
     helper_type: str, result: dict[str, Any]
 ) -> dict[str, Any]:
@@ -3643,11 +3706,30 @@ class HelperConfigTools:
                 )
             ),
         ],
+        limit: Annotated[
+            int,
+            Field(
+                default=100,
+                ge=1,
+                le=500,
+                description="Max helpers to return per page (default: 100)",
+            ),
+        ] = 100,
+        offset: Annotated[
+            int,
+            Field(
+                default=0,
+                ge=0,
+                description="Number of helpers to skip for pagination (default: 0)",
+            ),
+        ] = 0,
     ) -> dict[str, Any]:
         """
-        List all Home Assistant helpers of a specific type with their configurations.
+        List Home Assistant helpers of a specific type with their configurations.
 
-        Returns complete configuration for all helpers of the specified type including:
+        Returns one page of helpers; `total_count` and `has_more` report the full
+        set. Each record carries the complete configuration for its helper,
+        including:
         - id (immutable storage key), entity_id (current — address the helper by
           this, where available), name (current display name), original_name
           (creation-time name), icon
@@ -3682,8 +3764,12 @@ class HelperConfigTools:
         - List all persons: ha_config_list_helpers("person")
         - List all tags: ha_config_list_helpers("tag")
         - List every helper type at once: ha_config_list_helpers("all")
+        - Next page: ha_config_list_helpers("input_boolean", offset=100)
 
-        **NOTE:** This only returns storage-based helpers (created via UI/API), not YAML-defined helpers.
+        **NOTE:** Storage types list what HA's ``{type}/list`` command returns:
+        the storage-backed helpers (created via UI/API), not the YAML-defined
+        ones. ``person`` is the exception — HA lists its YAML-configured persons
+        alongside the storage ones, so both appear here.
 
         Flow-based types (template / group / utility_meter / derivative / etc.)
         require the ha_mcp_tools custom component (>= 1.1.0) and are served only
@@ -3702,7 +3788,9 @@ class HelperConfigTools:
         # No legacy equivalent exists (no single WS command enumerates all
         # types), so it is component-only — see ``_list_all_helpers``.
         if helper_type == "all":
-            return await self._list_all_helpers()
+            return _paginate_helpers_response(
+                await self._list_all_helpers(), offset, limit
+            )
 
         # Flow-based helper types have no ``{type}/list`` command, so only the
         # component's ``helpers_list`` can enumerate them: they are served
@@ -3723,7 +3811,7 @@ class HelperConfigTools:
                 helper_type, is_flow=is_flow
             )
             if component_response is not None:
-                return component_response
+                return _paginate_helpers_response(component_response, offset, limit)
         if is_flow:
             # No usable component path and the legacy body cannot serve flow
             # helpers: hard error rather than an empty or misleading list.
@@ -3751,7 +3839,7 @@ class HelperConfigTools:
                 }
                 if warnings:
                     response["warnings"] = warnings
-                return response
+                return _paginate_helpers_response(response, offset, limit)
             raise_tool_error(
                 create_error_response(
                     ErrorCode.SERVICE_CALL_FAILED,
@@ -3880,7 +3968,11 @@ class HelperConfigTools:
                     context={"helper_type": helper_type},
                 )
             )
-        items = result.get("result", [])
+        # Flatten like the inline body: person/list returns {"storage": [...],
+        # "config": [...]} rather than a flat list, so a raw result["result"]
+        # would be a dict here — breaking count, the pagination slice and the
+        # all-types merge, which all expect a list of records.
+        items = _flatten_helper_list_result(result)
         return {
             "success": True,
             "helper_type": helper_type,
@@ -4005,11 +4097,23 @@ class HelperConfigTools:
             )
         for helper_type in sorted(SIMPLE_HELPER_TYPES - covered_set):
             legacy = await self._legacy_helper_list(helper_type)
+            skipped = 0
             for item in legacy.get("helpers", []):
                 if isinstance(item, dict):
                     row = dict(item)
                     row.setdefault("helper_type", helper_type)
                     helpers.append(row)
+                else:
+                    skipped += 1
+            if skipped:
+                # This is how the unflattened person/list dict used to vanish:
+                # iterating it yielded its keys, and each failed the check here.
+                logger.warning(
+                    "Dropped %d unrecognised item(s) from the %s listing while "
+                    "merging all types; the merged listing is incomplete",
+                    skipped,
+                    helper_type,
+                )
 
         return {
             "success": True,

{ha_mcp_dev-7.12.3.dev1940 → ha_mcp_dev-7.12.3.dev1942}/src/ha_mcp/tools/tools_groups.py

@@ -27,6 +27,7 @@ from .helpers import (
 )
 from .util_helpers import (
     JSON_STRING_COERCION,
+    build_pagination_metadata,
     wait_for_entity_registered,
     wait_for_entity_removed,
 )
@@ -143,12 +144,32 @@ class GroupTools:
         },
     )
     @log_tool_usage
-    async def ha_config_list_groups(self) -> dict[str, Any]:
+    async def ha_config_list_groups(
+        self,
+        limit: Annotated[
+            int,
+            Field(
+                default=100,
+                ge=1,
+                le=500,
+                description="Max groups to return per page (default: 100)",
+            ),
+        ] = 100,
+        offset: Annotated[
+            int,
+            Field(
+                default=0,
+                ge=0,
+                description="Number of groups to skip for pagination (default: 0)",
+            ),
+        ] = 0,
+    ) -> dict[str, Any]:
         """
-        List all Home Assistant entity groups with their member entities.
+        List Home Assistant entity groups with their member entities.
 
-        Returns all groups created via group.set service or YAML configuration,
-        including:
+        Returns one page of groups created via group.set service or YAML
+        configuration; `total_count` and `has_more` report the full set. Each
+        group includes:
         - Entity ID (group.xxx)
         - Friendly name
         - State (on/off based on member states)
@@ -157,7 +178,8 @@ class GroupTools:
         - All mode (if all entities must be on)
 
         EXAMPLES:
-        - List all groups: ha_config_list_groups()
+        - First page of groups: ha_config_list_groups()
+        - Next page: ha_config_list_groups(offset=100)
 
         **NOTE:** This returns old-style groups (created via group.set or YAML).
         Platform-specific groups (light groups, cover groups) are separate entities.
@@ -184,16 +206,26 @@ class GroupTools:
                         }
                     )
 
-            # Sort by friendly name or entity_id
+            # Sort by friendly name, then entity_id: the unique tiebreaker keeps
+            # groups with the same name in a stable order, so a page boundary
+            # cannot duplicate or skip one when get_states() order shifts.
             groups.sort(
-                key=lambda g: (g.get("friendly_name") or g.get("entity_id", "")).lower()
+                key=lambda g: (
+                    (g.get("friendly_name") or g.get("entity_id", "")).lower(),
+                    g.get("entity_id", ""),
+                )
             )
 
+            total_count = len(groups)
+            paginated_groups = groups[offset : offset + limit]
+
             return {
                 "success": True,
-                "count": len(groups),
-                "groups": groups,
-                "message": f"Found {len(groups)} group(s)",
+                "groups": paginated_groups,
+                **build_pagination_metadata(
+                    total_count, offset, limit, len(paginated_groups)
+                ),
+                "message": f"Found {total_count} group(s)",
             }
 
         except Exception as e:

{ha_mcp_dev-7.12.3.dev1940 → ha_mcp_dev-7.12.3.dev1942}/src/ha_mcp/tools/tools_resources.py

@@ -25,6 +25,7 @@ from .helpers import (
     register_tool_methods,
     validate_identifier_not_empty,
 )
+from .util_helpers import build_pagination_metadata
 
 logger = logging.getLogger(__name__)
 
@@ -162,14 +163,34 @@ class ResourceTools:
                 "Default False to save tokens (shows 150-char preview instead)."
             ),
         ] = False,
+        limit: Annotated[
+            int,
+            Field(
+                default=100,
+                ge=1,
+                le=500,
+                description="Max resources to return per page (default: 100)",
+            ),
+        ] = 100,
+        offset: Annotated[
+            int,
+            Field(
+                default=0,
+                ge=0,
+                description="Number of resources to skip for pagination (default: 0)",
+            ),
+        ] = 0,
     ) -> dict[str, Any]:
         """
-        List all Lovelace dashboard resources (custom cards, themes, CSS/JS).
+        List Lovelace dashboard resources (custom cards, themes, CSS/JS).
 
-        Returns all registered resources. For inline resources (created with
+        Returns one page of registered resources; `total_count` and `has_more`
+        report the full set. For inline resources (created with
         ha_config_set_dashboard_resource(content=...)), shows a preview of the content
         instead of the full encoded URL to save tokens.
 
+        `inline_count` and `by_type` summarise every resource, not just this page.
+
         Args:
             include_content: If True, includes full decoded content for inline
                 resources in "_content" field. Default False (150-char preview only).
@@ -182,7 +203,8 @@ class ResourceTools:
         Each resource has a unique ID for update/delete operations.
 
         EXAMPLES:
-        - List all resources: ha_config_list_dashboard_resources()
+        - First page of resources: ha_config_list_dashboard_resources()
+        - Next page: ha_config_list_dashboard_resources(offset=100)
         - List with full content: ha_config_list_dashboard_resources(include_content=True)
 
         Note: Home Assistant 2026.6+ exposes resource management in the UI by
@@ -214,11 +236,14 @@ class ResourceTools:
                 if res.get("_inline"):
                     inline_count += 1
 
+            total_count = len(processed)
+            paginated = processed[offset : offset + limit]
+
             return {
                 "success": True,
                 "action": "list",
-                "resources": processed,
-                "count": len(processed),
+                "resources": paginated,
+                **build_pagination_metadata(total_count, offset, limit, len(paginated)),
                 "inline_count": inline_count,
                 "by_type": {
                     "module": len(categorized["module"]),

{ha_mcp_dev-7.12.3.dev1940 → ha_mcp_dev-7.12.3.dev1942/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.12.3.dev1940
+Version: 7.12.3.dev1942
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -41,7 +41,7 @@ Dynamic: license-file
   <!-- mcp-name: io.github.homeassistant-ai/ha-mcp -->
 
   <p align="center">
-    <img src="https://img.shields.io/badge/tools-88-blue" alt="95+ Tools">
+    <img src="https://img.shields.io/badge/tools-87-blue" alt="95+ Tools">
     <a href="https://github.com/homeassistant-ai/ha-mcp/releases"><img src="https://img.shields.io/github/v/release/homeassistant-ai/ha-mcp" alt="Release"></a>
     <a href="https://github.com/homeassistant-ai/ha-mcp/actions/workflows/e2e-tests.yml"><img src="https://img.shields.io/github/actions/workflow/status/homeassistant-ai/ha-mcp/e2e-tests.yml?branch=master&label=E2E%20Tests" alt="E2E Tests"></a>
     <a href="LICENSE.md"><img src="https://img.shields.io/github/license/homeassistant-ai/ha-mcp.svg" alt="License"></a>
@@ -247,7 +247,7 @@ Spend less time configuring, more time enjoying your smart home.
 <details>
 <!-- TOOLS_TABLE_START -->
 
-<summary><b>Complete Tool List (88 tools)</b></summary>
+<summary><b>Complete Tool List (87 tools)</b></summary>
 
 | Category | Tools |
 |----------|-------|
@@ -278,7 +278,7 @@ Spend less time configuring, more time enjoying your smart home.
 | **Service & Device Control** | `ha_bulk_control`, `ha_call_event`, `ha_call_service`, `ha_get_operation_status`, `ha_list_services` |
 | **System** | `ha_config_get_yaml` *(beta)*, `ha_config_set_yaml` *(beta)*, `ha_manage_backup`, `ha_manage_custom_tool` *(beta)*, `ha_manage_theme`, `ha_manage_updates`, `ha_reload_core`, `ha_restart` |
 | **Todo Lists** | `ha_get_todo`, `ha_remove_todo_item`, `ha_set_todo_item` |
-| **Utilities** | `ha_eval_template`, `ha_install_mcp_tools` *(beta)*, `ha_report_issue` |
+| **Utilities** | `ha_eval_template`, `ha_report_issue` |
 | **Zones** | `ha_get_zone`, `ha_remove_zone`, `ha_set_zone` |
 
 <!-- TOOLS_TABLE_END -->