ha-mcp-dev 7.2.0.dev320__tar.gz → 7.2.0.dev322__tar.gz

{ha_mcp_dev-7.2.0.dev320/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.2.0.dev322}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.2.0.dev320"
+version = "7.2.0.dev322"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.14"
@@ -175,6 +175,7 @@ dev = [
     "pytest-xdist>=3.8.0",
     "requests>=2.25.0",
     "lefthook>=1.10.0",
+    "ruamel.yaml>=0.18.0",
     "ruff>=0.12.12",
     "testcontainers>=4.13.0",
     "ast-grep-cli>=0.42.0",

{ha_mcp_dev-7.2.0.dev320 → ha_mcp_dev-7.2.0.dev322}/src/ha_mcp/tools/tools_integrations.py

@@ -13,7 +13,7 @@ from pydantic import Field
 
 from ..errors import ErrorCode, create_error_response
 from .helpers import exception_to_structured_error, log_tool_usage, raise_tool_error
-from .util_helpers import coerce_bool_param
+from .util_helpers import build_pagination_metadata, coerce_bool_param, coerce_int_param
 
 logger = logging.getLogger(__name__)
 
@@ -26,8 +26,8 @@ def register_integration_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         annotations={
             "idempotentHint": True,
             "readOnlyHint": True,
-            "title": "Get Integration"
-        }
+            "title": "Get Integration",
+        },
     )
     @log_tool_usage
     async def ha_get_integration(
@@ -83,35 +83,36 @@ def register_integration_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 default=True,
             ),
         ] = True,
+        limit: Annotated[
+            int | str,
+            Field(
+                default=50,
+                description="Max entries to return per page in list mode (default: 50)",
+            ),
+        ] = 50,
+        offset: Annotated[
+            int | str,
+            Field(
+                default=0,
+                description="Number of entries to skip for pagination (default: 0)",
+            ),
+        ] = 0,
     ) -> dict[str, Any]:
-        """
-        Get integration (config entry) information - list all or get a specific one.
+        """Get integration (config entry) information with pagination.
 
         Without an entry_id: Lists all configured integrations with optional filters.
         With an entry_id: Returns detailed information including full options/configuration.
 
-        Use this to audit existing configurations (e.g. template sensor Jinja code).
-        When creating new functionality, prefer UI-based helpers over templates when possible.
-
         EXAMPLES:
         - List all integrations: ha_get_integration()
-        - Search integrations: ha_get_integration(query="zigbee")
+        - Paginate: ha_get_integration(offset=50)
+        - Search: ha_get_integration(query="zigbee")
         - Get specific entry: ha_get_integration(entry_id="abc123")
         - Get entry with editable fields: ha_get_integration(entry_id="abc123", include_schema=True)
-        - List template entries with definitions: ha_get_integration(domain="template")
-        - List all with options: ha_get_integration(include_options=True)
+        - List template entries: ha_get_integration(domain="template")
 
-        STATES: 'loaded' (running), 'setup_error', 'setup_retry', 'not_loaded',
+        STATES: 'loaded', 'setup_error', 'setup_retry', 'not_loaded',
         'failed_unload', 'migration_error'.
-
-        RETURNS (when listing):
-        - entries: List of integrations with domain, title, state, capabilities
-        - state_summary: Count of entries in each state
-        - When domain filter or include_options is set, each entry includes the 'options' object
-
-        RETURNS (when getting specific entry):
-        - entry: Full config entry details including options/configuration
-        - options_schema: Options flow schema when include_schema=True and supports_options=true
         """
         try:
             include_opts = coerce_bool_param(
@@ -123,6 +124,10 @@ def register_integration_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
             exact_match_bool = coerce_bool_param(
                 exact_match, "exact_match", default=True
             )
+            limit_int = coerce_int_param(
+                limit, "limit", default=50, min_value=1, max_value=200
+            )
+            offset_int = coerce_int_param(offset, "offset", default=0, min_value=0)
             # Auto-enable options when domain filter is set
             if domain is not None:
                 include_opts = True
@@ -266,16 +271,22 @@ def register_integration_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 matches.sort(key=lambda x: x[0], reverse=True)
                 formatted_entries = [match[1] for match in matches]
 
-            # Group by state for summary
+            # Group by state for summary (computed before pagination for full picture)
             state_summary: dict[str, int] = {}
             for entry in formatted_entries:
                 state = entry.get("state", "unknown")
                 state_summary[state] = state_summary.get(state, 0) + 1
 
+            # Apply pagination
+            total_entries = len(formatted_entries)
+            paginated_entries = formatted_entries[offset_int : offset_int + limit_int]
+
             result_data: dict[str, Any] = {
                 "success": True,
-                "total": len(formatted_entries),
-                "entries": formatted_entries,
+                **build_pagination_metadata(
+                    total_entries, offset_int, limit_int, len(paginated_entries)
+                ),
+                "entries": paginated_entries,
                 "state_summary": state_summary,
                 "query": query if query else None,
             }
@@ -298,10 +309,7 @@ def register_integration_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
 
     @mcp.tool(
         tags={"Integrations"},
-        annotations={
-            "destructiveHint": True,
-            "title": "Set Integration Enabled"
-        }
+        annotations={"destructiveHint": True, "title": "Set Integration Enabled"},
     )
     @log_tool_usage
     async def ha_set_integration_enabled(
@@ -365,10 +373,7 @@ def register_integration_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
 
     @mcp.tool(
         tags={"Integrations"},
-        annotations={
-            "destructiveHint": True,
-            "title": "Delete Config Entry"
-        }
+        annotations={"destructiveHint": True, "title": "Delete Config Entry"},
     )
     @log_tool_usage
     async def ha_delete_config_entry(

{ha_mcp_dev-7.2.0.dev320 → ha_mcp_dev-7.2.0.dev322}/src/ha_mcp/tools/tools_registry.py

@@ -11,7 +11,7 @@ Important: Device renaming does NOT cascade to entities - they are independent r
 
 import logging
 import re
-from typing import Annotated, Any
+from typing import Annotated, Any, Literal
 
 from fastmcp.exceptions import ToolError
 from pydantic import Field
@@ -24,7 +24,12 @@ from .helpers import (
     log_tool_usage,
     raise_tool_error,
 )
-from .util_helpers import coerce_bool_param, parse_string_list_param
+from .util_helpers import (
+    build_pagination_metadata,
+    coerce_bool_param,
+    coerce_int_param,
+    parse_string_list_param,
+)
 
 # Known voice assistant identifiers
 KNOWN_ASSISTANTS = ["conversation", "cloud.alexa", "cloud.google_assistant"]
@@ -341,7 +346,10 @@ def register_registry_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 context={"device_id": device_id},
             )
 
-    @mcp.tool(tags={"Device Registry"}, annotations={"destructiveHint": True, "title": "Rename Entity"})
+    @mcp.tool(
+        tags={"Device Registry"},
+        annotations={"destructiveHint": True, "title": "Rename Entity"},
+    )
     @log_tool_usage
     async def ha_rename_entity(
         entity_id: Annotated[
@@ -504,7 +512,11 @@ def register_registry_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 results["device_rename"] = {
                     "skipped": True,
                     "reason": reason,
-                    **({"warning": "Registry query failed; retry may succeed"} if registry_lookup_failed else {}),
+                    **(
+                        {"warning": "Registry query failed; retry may succeed"}
+                        if registry_lookup_failed
+                        else {}
+                    ),
                 }
 
             # Build success response
@@ -568,8 +580,8 @@ def register_registry_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         annotations={
             "idempotentHint": True,
             "readOnlyHint": True,
-            "title": "Get Device (incl. Zigbee/ZHA/Z2M and Z-Wave)"
-        }
+            "title": "Get Device (incl. Zigbee/ZHA/Z2M and Z-Wave)",
+        },
     )
     @log_tool_usage
     async def ha_get_device(
@@ -608,42 +620,58 @@ def register_registry_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 default=None,
             ),
         ] = None,
+        limit: Annotated[
+            int | str,
+            Field(
+                default=50,
+                description="Max devices to return per page in list mode (default: 50)",
+            ),
+        ] = 50,
+        offset: Annotated[
+            int | str,
+            Field(
+                default=0,
+                description="Number of devices to skip for pagination (default: 0)",
+            ),
+        ] = 0,
+        detail_level: Annotated[
+            Literal["summary", "full"],
+            Field(
+                default="summary",
+                description=(
+                    "'summary': basic device info and protocol identifiers (default for list mode). "
+                    "'full': include entities and all integration details. "
+                    "Single device lookups always return full detail."
+                ),
+            ),
+        ] = "summary",
     ) -> dict[str, Any]:
-        """
-        Get device information, including Zigbee (ZHA/Z2M) and Z-Wave JS devices with protocol-specific details.
+        """Get device information with pagination, including Zigbee (ZHA/Z2M) and Z-Wave JS devices.
 
-        Without device_id/entity_id: Lists all devices with optional filters.
-        With device_id or entity_id: Returns detailed info for that specific device.
+        Without device_id/entity_id: Lists devices with optional filters and pagination.
+        With device_id or entity_id: Returns full detail for that specific device.
 
-        **List all devices:**
-        - All devices: ha_get_device()
+        **List devices (paginated):**
+        - First page: ha_get_device()
+        - Next page: ha_get_device(offset=50)
         - By area: ha_get_device(area_id="living_room")
-        - By manufacturer: ha_get_device(manufacturer="Philips")
         - By integration: ha_get_device(integration="zigbee2mqtt")
-        - Combined filters: ha_get_device(integration="zha", area_id="kitchen")
+        - Full details in list: ha_get_device(detail_level="full", limit=10)
 
-        **Single device lookup:**
+        **Single device lookup (always full detail):**
         - By device_id: ha_get_device(device_id="abc123")
         - By entity_id: ha_get_device(entity_id="light.living_room")
 
-        **Zigbee device support:**
-        - Use integration="zha" or integration="zigbee2mqtt" to list Zigbee devices
-        - Returns ieee_address, integration_type, and radio metrics (LQI/RSSI) for ZHA devices
-        - ZHA triggers: Use `ieee_address` for zha_event triggers
-        - Z2M triggers: Use `friendly_name` for MQTT topics (zigbee2mqtt/{friendly_name}/action)
-
-        **Z-Wave JS device support:**
-        - Use integration="zwave_js" to list Z-Wave devices
-        - Returns node_id extracted from device identifiers
-        - Single device lookup includes node_status (security class, routing, Z-Wave+ version)
-
-        **Returns (list mode):**
-        - List of devices with device_id, name, manufacturer, model, area_id
-
-        **Returns (single device):**
-        - Full device details including integration_type, ieee_address/node_id, radio_metrics/node_status, entities
+        **Zigbee:** integration="zha" or "zigbee2mqtt". Returns ieee_address, radio metrics.
+        **Z-Wave:** integration="zwave_js". Returns node_id, node_status.
         """
         try:
+            limit_int = coerce_int_param(
+                limit, "limit", default=50, min_value=1, max_value=200
+            )
+            offset_int = coerce_int_param(offset, "offset", default=0, min_value=0)
+            effective_detail = detail_level
+
             # Get device registry
             list_message: dict[str, Any] = {"type": "config/device_registry/list"}
             list_result = await client.send_websocket_message(list_message)
@@ -665,7 +693,9 @@ def register_registry_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 entity_result.get("result", []) if entity_result.get("success") else []
             )
 
-            # Build entity -> device_id map
+            # Build entity -> device_id map (always needed for entity_id param lookup)
+            # Build device -> entities map only when needed (single device lookup or full detail)
+            need_entity_details = device_id or entity_id or effective_detail == "full"
             entity_to_device: dict[str, str] = {}
             device_to_entities: dict[str, list[dict[str, Any]]] = {}
             for e in all_entities:
@@ -673,15 +703,16 @@ def register_registry_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 did = e.get("device_id")
                 if eid and did:
                     entity_to_device[eid] = did
-                    if did not in device_to_entities:
-                        device_to_entities[did] = []
-                    device_to_entities[did].append(
-                        {
-                            "entity_id": eid,
-                            "name": e.get("name") or e.get("original_name"),
-                            "platform": e.get("platform"),
-                        }
-                    )
+                    if need_entity_details:
+                        if did not in device_to_entities:
+                            device_to_entities[did] = []
+                        device_to_entities[did].append(
+                            {
+                                "entity_id": eid,
+                                "name": e.get("name") or e.get("original_name"),
+                                "platform": e.get("platform"),
+                            }
+                        )
 
             # If entity_id provided, find the device_id
             if entity_id and not device_id:
@@ -836,7 +867,12 @@ def register_registry_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                                     "lqi": zha_dev.get("lqi"),
                                     "rssi": zha_dev.get("rssi"),
                                 }
-                    except (HomeAssistantConnectionError, HomeAssistantAPIError, TimeoutError, OSError) as e:
+                    except (
+                        HomeAssistantConnectionError,
+                        HomeAssistantAPIError,
+                        TimeoutError,
+                        OSError,
+                    ) as e:
                         logger.warning(
                             "Could not fetch ZHA radio metrics for device %s: %s",
                             device_info.get("device_id"),
@@ -844,9 +880,9 @@ def register_registry_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                         )
 
                 # Enrich Z-Wave JS devices with node status
-                if device_info.get("integration_type") == "zwave_js" and device_info.get(
-                    "node_id"
-                ):
+                if device_info.get(
+                    "integration_type"
+                ) == "zwave_js" and device_info.get("node_id"):
                     try:
                         zwave_result = await client.send_websocket_message(
                             {"type": "zwave_js/node_status", "device_id": device_id}
@@ -868,7 +904,12 @@ def register_registry_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                                     "is_controller_node"
                                 ),
                             }
-                    except (HomeAssistantConnectionError, HomeAssistantAPIError, TimeoutError, OSError) as e:
+                    except (
+                        HomeAssistantConnectionError,
+                        HomeAssistantAPIError,
+                        TimeoutError,
+                        OSError,
+                    ) as e:
                         logger.warning(
                             "Could not fetch Z-Wave node status for device %s: %s",
                             device_info.get("device_id"),
@@ -911,21 +952,31 @@ def register_registry_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                     if integration_lower in named_types:
                         if device_info["integration_type"] != integration_lower:
                             continue
-                    elif (
-                        integration_lower
-                        not in device_info.get("integration_sources", [])
+                    elif integration_lower not in device_info.get(
+                        "integration_sources", []
                     ):
                         continue
 
-                device_info["entities"] = device_to_entities.get(device.get("id"), [])
+                # In summary mode, omit entity lists to reduce response size
+                if effective_detail == "full":
+                    device_info["entities"] = device_to_entities.get(
+                        device.get("id"), []
+                    )
                 matched_devices.append(device_info)
 
+            # Apply pagination
+            total_matched = len(matched_devices)
+            paginated_devices = matched_devices[offset_int : offset_int + limit_int]
+
             # Build result
             result: dict[str, Any] = {
                 "success": True,
-                "count": len(matched_devices),
+                **build_pagination_metadata(
+                    total_matched, offset_int, limit_int, len(paginated_devices)
+                ),
                 "total_devices": len(all_devices),
-                "devices": matched_devices,
+                "devices": paginated_devices,
+                "detail_level": effective_detail,
             }
 
             # Add filter info
@@ -982,10 +1033,7 @@ def register_registry_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
 
     @mcp.tool(
         tags={"Device Registry"},
-        annotations={
-            "destructiveHint": True,
-            "title": "Update Device"
-        }
+        annotations={"destructiveHint": True, "title": "Update Device"},
     )
     @log_tool_usage
     async def ha_update_device(
@@ -1072,8 +1120,8 @@ def register_registry_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         annotations={
             "destructiveHint": True,
             "idempotentHint": True,
-            "title": "Remove Device"
-        }
+            "title": "Remove Device",
+        },
     )
     @log_tool_usage
     async def ha_remove_device(

{ha_mcp_dev-7.2.0.dev320 → ha_mcp_dev-7.2.0.dev322}/src/ha_mcp/tools/tools_search.py

@@ -17,6 +17,7 @@ from ..transforms.categorized_search import DEFAULT_PINNED_TOOLS
 from .helpers import exception_to_structured_error, log_tool_usage
 from .util_helpers import (
     add_timezone_metadata,
+    build_pagination_metadata,
     coerce_bool_param,
     coerce_int_param,
     parse_string_list_param,
@@ -28,15 +29,22 @@ logger = logging.getLogger(__name__)
 def _build_pagination_metadata(
     total_matches: int, offset: int, limit: int, results: list[dict[str, Any]]
 ) -> dict[str, Any]:
-    """Build standardized pagination metadata for search responses."""
-    has_more = (offset + len(results)) < total_matches
+    """Build standardized pagination metadata for search responses.
+
+    Thin wrapper around the shared ``build_pagination_metadata`` helper that
+    keeps the existing call-site signature (accepts a *results* list and uses
+    ``total_matches`` as the key name expected by search tools).
+    """
+    meta = build_pagination_metadata(total_matches, offset, limit, len(results))
+    # Search tools use "total_matches" instead of "total_count" —
+    # construct explicitly to avoid fragile dependency on shared helper's key names
     return {
-        "total_matches": total_matches,
-        "offset": offset,
-        "limit": limit,
-        "count": len(results),
-        "has_more": has_more,
-        "next_offset": offset + limit if has_more else None,
+        "total_matches": meta["total_count"],
+        "offset": meta["offset"],
+        "limit": meta["limit"],
+        "count": meta["count"],
+        "has_more": meta["has_more"],
+        "next_offset": meta["next_offset"],
     }
 
 
@@ -144,8 +152,8 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         annotations={
             "idempotentHint": True,
             "readOnlyHint": True,
-            "title": "Search Entities"
-        }
+            "title": "Search Entities",
+        },
     )
     @log_tool_usage
     async def ha_search_entities(
@@ -498,8 +506,8 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         annotations={
             "idempotentHint": True,
             "readOnlyHint": True,
-            "title": "Get System Overview"
-        }
+            "title": "Get System Overview",
+        },
     )
     @log_tool_usage
     async def ha_get_overview(
@@ -721,8 +729,8 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         annotations={
             "idempotentHint": True,
             "readOnlyHint": True,
-            "title": "Deep Search"
-        }
+            "title": "Deep Search",
+        },
     )
     @log_tool_usage
     async def ha_deep_search(
@@ -829,8 +837,8 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         annotations={
             "idempotentHint": True,
             "readOnlyHint": True,
-            "title": "Get Entity State"
-        }
+            "title": "Get Entity State",
+        },
     )
     @log_tool_usage
     async def ha_get_state(entity_id: str) -> dict[str, Any]:
@@ -856,8 +864,8 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         annotations={
             "idempotentHint": True,
             "readOnlyHint": True,
-            "title": "Get Multiple Entity States"
-        }
+            "title": "Get Multiple Entity States",
+        },
     )
     @log_tool_usage
     async def ha_get_states(