ha-mcp-dev 7.3.0.dev380__tar.gz → 7.3.0.dev382__tar.gz

{ha_mcp_dev-7.3.0.dev380/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.3.0.dev382}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.3.0.dev380"
+version = "7.3.0.dev382"
 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.3.0.dev380 → ha_mcp_dev-7.3.0.dev382}/src/ha_mcp/tools/tools_search.py

@@ -157,9 +157,31 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
     )
     @log_tool_usage
     async def ha_search_entities(
-        query: str,
-        domain_filter: str | None = None,
-        area_filter: str | None = None,
+        query: Annotated[
+            str | None,
+            Field(
+                default=None,
+                description=(
+                    "Entity name to search for (fuzzy or exact match). "
+                    "Omit to list entities; `domain_filter` or `area_filter` "
+                    "must be set in that mode."
+                ),
+            ),
+        ] = None,
+        domain_filter: Annotated[
+            str | None,
+            Field(
+                default=None,
+                description="Limit to a single domain (e.g. 'light', 'sensor', 'calendar').",
+            ),
+        ] = None,
+        area_filter: Annotated[
+            str | None,
+            Field(
+                default=None,
+                description="Limit to entities in a specific area (area ID or name).",
+            ),
+        ] = None,
         limit: int = 10,
         offset: Annotated[
             int | str,
@@ -181,26 +203,25 @@ def register_search_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
             ),
         ] = True,
     ) -> dict[str, Any]:
-        """PRIMARY tool for finding entities (lights, sensors, switches, etc.) by name, area, or domain. Use this first when looking up any entity ID.
-
-        For searching *inside* automation/script/helper configurations, use ha_deep_search instead.
-
-        **Listing Entities by Domain:**
-        Use domain_filter with an empty query to list all entities of a specific type:
-        - ha_search_entities(query="", domain_filter="calendar") - List all calendars
-        - ha_search_entities(query="", domain_filter="todo") - List all todo lists
-        - ha_search_entities(query="", domain_filter="scene") - List all scenes
-        - ha_search_entities(query="", domain_filter="zone") - List all zones (as entities)
-
-        **BEST PRACTICE:** Before performing searches, call ha_get_overview() first to understand:
-        - Smart home size and scale (total entities, domains, areas)
-        - Language used in entity naming (French/English/mixed)
-        - Available areas/rooms and their entity distribution
-
-        Choose overview detail level based on task:
-        - 'minimal': Quick orientation (10 entities per domain sample) - RECOMMENDED for searches
-        - 'standard': Complete picture (all entities, friendly names only) - for comprehensive tasks
-        - 'full': Maximum detail (includes states, device types, services) - for deep analysis"""
+        """Find or list entities (lights, sensors, switches, etc.) by name, domain, or area.
+
+        When NOT to use: for searching inside automation, script, helper, or dashboard
+        *configurations* (e.g. which automations call a service or reference an entity),
+        use `ha_deep_search`.
+
+        To enumerate all entities of a domain, omit `query` and pass `domain_filter`. For
+        example, `ha_search_entities(domain_filter="calendar")` lists all calendars. At
+        least one of `query`, `domain_filter`, or `area_filter` must be set.
+        """
+        # Normalize omitted/None query to empty string so downstream logic is unchanged
+        query = query or ""
+        if not query.strip() and not domain_filter and not area_filter:
+            raise_tool_error(
+                create_validation_error(
+                    "At least one of 'query', 'domain_filter', or 'area_filter' must be set.",
+                    parameter="query",
+                )
+            )
         # Coerce boolean parameter that may come as string from XML-style calls
         group_by_domain_bool = (
             coerce_bool_param(group_by_domain, "group_by_domain", default=False)

{ha_mcp_dev-7.3.0.dev380 → ha_mcp_dev-7.3.0.dev382/src/ha_mcp_dev.egg-info}/PKG-INFO

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