ha-mcp-dev 8.5.0.dev2757__tar.gz → 8.5.0.dev2759__tar.gz

{ha_mcp_dev-8.5.0.dev2757/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.5.0.dev2759}/PKG-INFO

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

{ha_mcp_dev-8.5.0.dev2757 → ha_mcp_dev-8.5.0.dev2759}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.5.0.dev2757"
+version = "8.5.0.dev2759"
 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.5.0.dev2757 → ha_mcp_dev-8.5.0.dev2759}/src/ha_mcp/backup_manager.py

@@ -3061,8 +3061,10 @@ async def _fetch_file(client: Any, entity_id: str) -> Any:
 
     ``entity_id`` is the file path. Returns the content string, or None
     when the file does not exist — a brand-new write has no prior content
-    to snapshot, so capture skips (same as creating a new entity). Other
-    read failures raise so the capture pipeline logs them at WARNING.
+    to snapshot, so capture skips (same as creating a new entity). A
+    binary file also returns None: snapshots store text only, so capture
+    skips it instead of blocking the write or delete. Other read failures
+    raise so the capture pipeline logs them at WARNING.
     """
     from .tools.tools_filesystem import call_mcp_tools_service
     from .tools.util_helpers import unwrap_service_response
@@ -3075,7 +3077,11 @@ async def _fetch_file(client: Any, entity_id: str) -> Any:
         content = result.get("content")
         return content if isinstance(content, str) else None
     error = str(result.get("error", ""))
-    if "does not exist" in error or "not a file" in error:
+    if (
+        "does not exist" in error
+        or "not a file" in error
+        or "Cannot read binary file" in error
+    ):
         return None
     raise HomeAssistantError(f"read_file failed for {entity_id!r}: {error}")
 

{ha_mcp_dev-8.5.0.dev2757 → ha_mcp_dev-8.5.0.dev2759}/src/ha_mcp/server.py

@@ -873,8 +873,8 @@ class HomeAssistantSmartMCPServer:
             "see ha_get_skill_guide."
         ),
         "ha_config_set_yaml": (
-            "Update raw YAML in configuration.yaml or packages/*.yaml "
-            "via add / replace / remove on a single top-level key "
+            "Update raw YAML in configuration.yaml, packages/*.yaml or "
+            "themes/*.yaml via add / replace / remove on a single top-level key "
             "(LAST RESORT). By default the first call returns a diff "
             "preview plus confirm_token; repeat with confirm_token to "
             "apply.\n\n"
@@ -884,8 +884,9 @@ class HomeAssistantSmartMCPServer:
             "should be preferred. Use this only for YAML-only "
             "integrations (command_line, rest, shell_command, notify), "
             "YAML-heavy integrations like knx (in packages/*.yaml), "
-            "or registering YAML-mode dashboards via "
-            "`lovelace.dashboards.<url_path>`. Most edits require a "
+            "registering YAML-mode dashboards via "
+            "`lovelace.dashboards.<url_path>`, or editing theme files in "
+            "themes/*.yaml (reloaded automatically). Most edits require a "
             "full HA restart; template, mqtt, and group support "
             "reload.\n\n"
             "For routing guidance and the full allowlist, see "

{ha_mcp_dev-8.5.0.dev2757 → ha_mcp_dev-8.5.0.dev2759}/src/ha_mcp/tools/device_control.py

@@ -137,7 +137,7 @@ class DeviceControlTools:
                         f"Invalid entity ID format: {entity_id}",
                         suggestions=[
                             "Entity ID must be in format 'domain.entity_name'",
-                            "Use smart_entity_search to find correct entity ID",
+                            "Use ha_search to find the correct entity ID",
                         ],
                         context={"entity_id": entity_id, "action": action},
                     )
@@ -211,12 +211,12 @@ class DeviceControlTools:
                     "command_sent": True,
                     "operation_id": operation_id,
                     "status": "pending_verification",
-                    "message": f"Command sent to {entity_id}. Use get_device_operation_status() to verify completion.",
+                    "message": f"Command sent to {entity_id}. Use ha_get_operation_status to verify completion.",
                     "service_call": service_call,
                     "expected_state": expected_state,
                     "timeout_seconds": timeout_seconds,
                     "follow_up": {
-                        "tool": "get_device_operation_status",
+                        "tool": "ha_get_operation_status",
                         "parameters": {
                             "operation_id": operation_id,
                             "timeout_seconds": timeout_seconds,
@@ -292,7 +292,7 @@ class DeviceControlTools:
                         ErrorCode.ENTITY_NOT_FOUND,
                         f"Entity not found: {entity_id}",
                         suggestions=[
-                            "Use smart_entity_search to find the correct entity",
+                            "Use ha_search to find the correct entity",
                             "Check entity is not disabled in Home Assistant",
                         ],
                         context={"entity_id": entity_id, "action": action},
@@ -509,7 +509,7 @@ class DeviceControlTools:
                     suggestions=[
                         "Operation may have been cleaned up after completion",
                         "Check operation ID spelling",
-                        "Use control_device_smart to start new operation",
+                        "Use ha_bulk_control to start a new operation",
                     ],
                     context={"operation_id": operation_id},
                 )
@@ -535,7 +535,7 @@ class DeviceControlTools:
                             suggestions=[
                                 "Operation may have completed and been purged before "
                                 + "verification finished",
-                                "Use control_device_smart to start new operation",
+                                "Use ha_bulk_control to start a new operation",
                             ],
                             context={"operation_id": operation_id},
                         )
@@ -620,7 +620,7 @@ class DeviceControlTools:
                 "tips": [
                     "Operation will auto-complete when device state changes",
                     "Physical devices may take 1-3 seconds to respond",
-                    "Call this function again to check for updates",
+                    "Call ha_get_operation_status again to check for updates",
                 ],
             }
 
@@ -935,7 +935,7 @@ class DeviceControlTools:
                 total=len(valid_operations),
                 message=(
                     f"dispatched {len(operation_ids)} op(s); "
-                    "use get_bulk_operation_status to verify completion"
+                    "use ha_get_operation_status to verify completion"
                 ),
             )
 
@@ -1539,7 +1539,7 @@ class DeviceControlTools:
             "follow_up": (
                 {
                     "message": (
-                        f"Use get_bulk_operation_status() to check all "
+                        f"Use ha_get_operation_status(operation_id=[...]) to check all "
                         f"{len(operation_ids)} operations"
                     ),
                     "operation_ids": operation_ids,
@@ -1587,7 +1587,7 @@ class DeviceControlTools:
                     ErrorCode.VALIDATION_MISSING_PARAMETER,
                     "No operation IDs provided",
                     suggestions=[
-                        "Provide a list of operation IDs from control_device_smart"
+                        "Provide the operation_ids that ha_bulk_control returned"
                     ],
                 )
             )

{ha_mcp_dev-8.5.0.dev2757 → ha_mcp_dev-8.5.0.dev2759}/src/ha_mcp/tools/smart_search/_entities.py

@@ -601,8 +601,7 @@ class EntitySearchMixin(_SearchBase):
                 e,
                 suggestions=[
                     "Check Home Assistant connection",
-                    "Try common room names: salon, chambre, cuisine",
-                    "Use smart_entity_search to find entities first",
+                    "Use ha_search to find entities first",
                 ],
                 context={"area_query": area_query},
             )

{ha_mcp_dev-8.5.0.dev2757 → ha_mcp_dev-8.5.0.dev2759}/src/ha_mcp/tools/tools_calendar.py

@@ -182,7 +182,8 @@ class CalendarTools:
         end: Annotated[
             str | None,
             Field(
-                description="End datetime in ISO format (default: 7 days from start)",
+                description="End datetime in ISO format (default: 7 days from now, "
+                "not from start; pass end whenever you pass start)",
                 default=None,
             ),
         ] = None,
@@ -193,8 +194,10 @@ class CalendarTools:
     ) -> dict[str, Any]:
         """Get calendar events from a calendar entity within a time range.
 
-        Returns each event's summary, start, end, description and location. To
-        find calendar entities, use ha_search(domain_filter='calendar').
+        Returns each event's summary, start, end, description and location,
+        plus the uid, recurrence_id and rrule when the calendar provides them
+        (the edit and remove tools use uid and recurrence_id). To find calendar
+        entities, use ha_search(domain_filter='calendar').
 
         EXAMPLES:
         - Next week (defaults): ha_config_get_calendar_events("calendar.family")

{ha_mcp_dev-8.5.0.dev2757 → ha_mcp_dev-8.5.0.dev2759}/src/ha_mcp/tools/tools_config_automations.py

@@ -562,7 +562,7 @@ class AutomationConfigTools:
 
         Returns the complete configuration including triggers, conditions, actions, and mode settings.
 
-        The returned `config_hash` is stable across consecutive reads of an unchanged config — `compute_config_hash` documents the underlying contract.
+        The returned `config_hash` stays the same across consecutive reads of an unchanged config.
 
         The returned `automation_id` is the resolved entity_id (canonical
         form, e.g. `automation.morning_routine`) when the registry lookup

{ha_mcp_dev-8.5.0.dev2757 → ha_mcp_dev-8.5.0.dev2759}/src/ha_mcp/tools/tools_config_dashboards.py

@@ -1922,7 +1922,7 @@ class DashboardConfigTools:
           On installs without the ha_mcp_tools component, the default (unnamed)
           dashboard is also not searched — only dashboards with a url_path are.
 
-        Return a stable `config_hash` (Get and Search modes only; not present in list_only mode) across consecutive reads of an unchanged config — `compute_config_hash` documents the underlying contract.
+        MODE 2 (Search) and MODE 3 (Get) return a `config_hash` that stays the same across consecutive reads of an unchanged config; MODE 1 and MODE 4 do not return one.
 
         EXAMPLES:
         - List all dashboards: ha_config_get_dashboard(list_only=True)
@@ -2852,8 +2852,8 @@ class DashboardConfigTools:
 
         Use ha_config_get_dashboard(entity_id=...) to get the path of any card,
         and ha_search / ha_get_overview to find entity IDs — never guess them.
-        For visual re-checks after the write use ha_get_dashboard_screenshot
-        instead of re-sending config.
+        For visual re-checks after the write, use ha_get_dashboard_screenshot
+        (when available) instead of re-sending config.
 
         title/icon/require_admin/show_in_sidebar can be updated in a
         metadata-only call or alongside a full config replacement; with

{ha_mcp_dev-8.5.0.dev2757 → ha_mcp_dev-8.5.0.dev2759}/src/ha_mcp/tools/tools_config_helpers.py

@@ -4422,8 +4422,8 @@ class HelperConfigTools:
                     "Ignored for helper_type='config_subentry', which uses "
                     "entry_id/subentry_type/subentry_id instead. For flow-based "
                     "helper updates (template, group, utility_meter, ...), this is "
-                    "typically ignored because options flows don't expose renaming. "
-                    "Rename a flow helper by deleting and recreating instead."
+                    "ignored because options flows don't expose renaming; change the "
+                    "resulting entity's display name with ha_set_entity(name=...)."
                 ),
                 default=None,
             ),

{ha_mcp_dev-8.5.0.dev2757 → ha_mcp_dev-8.5.0.dev2759}/src/ha_mcp/tools/tools_config_scenes.py

@@ -313,7 +313,11 @@ class ConfigSceneTools:
         self,
         scene_id: Annotated[
             str | None,
-            Field(description="Scene identifier"),
+            Field(
+                description="Scene storage ID from listing (e.g. 'movie_night') "
+                "or the scene's entity_id; an entity_id is resolved to the "
+                "storage ID."
+            ),
         ] = None,
         query: Annotated[
             str | None, Field(description="Filter scene names or IDs")

{ha_mcp_dev-8.5.0.dev2757 → ha_mcp_dev-8.5.0.dev2759}/src/ha_mcp/tools/tools_config_scripts.py

@@ -133,7 +133,7 @@ class ConfigScriptTools:
 
         Returns the complete configuration for a script, including sequence, mode, fields, and other settings.
 
-        The returned `config_hash` is stable across consecutive reads of an unchanged config — `compute_config_hash` documents the underlying contract.
+        The returned `config_hash` stays the same across consecutive reads of an unchanged config.
 
         The returned `script_id` is the canonical bare storage key resolved by the REST client (matching what `ha_config_set_script` / `ha_config_remove_script` expect), falling back to the input identifier on the rare path where the REST envelope omits it. Prefix handling matches `ha_config_get_automation` in behavior (mechanism differs: automations resolve via state lookup; scripts strip the prefix).
 

{ha_mcp_dev-8.5.0.dev2757 → ha_mcp_dev-8.5.0.dev2759}/src/ha_mcp/tools/tools_filesystem.py

@@ -582,8 +582,8 @@ class FilesystemTools:
         - `custom_templates/` - Jinja2 template files
         - `dashboards/` - YAML-mode dashboard files
         - `blueprints/` - Automation/script blueprint sources (read-only)
-        - Your configured `packages/` folder, when `homeassistant: packages:` is
-          set (the folder name you bound, default `packages/`)
+        - `packages/`, plus the folder bound by `homeassistant: packages:` when
+          it has another name
         - Plus any custom directories OR HAOS sibling volumes (`/share`,
           `/media`, `/ssl`, `/backup`) configured in the ha-mcp settings UI
         Path traversal (../) is blocked.
@@ -699,7 +699,8 @@ class FilesystemTools:
         **Allowed Read Paths:**
         - `configuration.yaml`, `automations.yaml`, `scripts.yaml`, `scenes.yaml`
         - `secrets.yaml` (values masked)
-        - `packages/*.yaml`
+        - `*.yaml` at any depth under `packages/` and under the folder bound by
+          `homeassistant: packages:`
         - `home-assistant.log`, `home-assistant.log.fault` (tail only)
         - `www/**`, `themes/**`, `custom_templates/**`, `dashboards/**`, `blueprints/**`
         - `custom_components/**/*.py` (read-only)
@@ -895,7 +896,9 @@ class FilesystemTools:
     ) -> dict[str, Any]:
         """Delete a file from allowed directories in the Home Assistant config.
 
-        Permanently removes a file; this cannot be undone. Allowed directories:
+        ha_manage_backup(scope="edits") can restore a text file from its most
+        recent auto-backup snapshot; a binary file has no snapshot and its
+        deletion is permanent. Allowed directories:
         `www/`, `themes/`, `custom_templates/`, `dashboards/`, plus any custom
         directories OR HAOS sibling volumes (`/share`, `/media`, `/ssl`,
         `/backup`) configured in the ha-mcp settings UI. Configuration files

{ha_mcp_dev-8.5.0.dev2757 → ha_mcp_dev-8.5.0.dev2759}/src/ha_mcp/tools/tools_registry.py

@@ -1052,7 +1052,10 @@ class RegistryTools:
         disabled_by: Annotated[
             str | None,
             Field(
-                description="Set to 'user' to disable, or None/empty string to enable",
+                description=(
+                    "Set to 'user' to disable the device, or '' (empty string) "
+                    "to enable it. Omit to leave the disabled state unchanged."
+                ),
                 default=None,
             ),
         ] = None,
@@ -1139,8 +1142,7 @@ class RegistryTools:
         - Active devices will typically be re-added by their integration
         - Associated entities may also be removed
 
-        This uses the config entry removal which is the safe way to remove devices.
-        If the device has multiple config entries, they must all be removed.
+        Works only when the integration supports removing devices.
 
         EXAMPLES:
         - Remove orphaned device: ha_remove_device("abc123def456")

{ha_mcp_dev-8.5.0.dev2757 → ha_mcp_dev-8.5.0.dev2759}/src/ha_mcp/tools/tools_service.py

@@ -2145,17 +2145,26 @@ class ServiceTools:
                 ),
             ),
         ],
-        timeout_seconds: Annotated[float, Field(ge=0, allow_inf_nan=False)] = 10,
+        timeout_seconds: Annotated[
+            float,
+            Field(
+                ge=0,
+                allow_inf_nan=False,
+                description=(
+                    "Seconds to wait for a pending operation to finish before "
+                    "returning its status. 0 returns the current status at once."
+                ),
+            ),
+        ] = 10,
     ) -> dict[str, Any]:
         """
         Get the status of one or more device operations with real-time WebSocket verification.
 
-        The timeout_seconds wait window bounds single and bulk checks. Bulk checks poll
-        all operations concurrently under one shared window and report
-        per-item failures inside detailed_results instead of aborting the
-        batch.
+        Bulk checks poll all operations concurrently under one shared
+        timeout_seconds window and report per-item failures inside
+        detailed_results instead of aborting the batch.
 
-        Use this to track operations initiated by ha_bulk_control or ha_call_service.
+        Use this to track the operation_ids that ha_bulk_control returns.
         For current entity states, use ha_get_state instead.
         """
         try:
@@ -2211,7 +2220,15 @@ class ServiceTools:
             # supplies the runtime default without a `| None` mypy would then
             # require type-narrowing for at every use below `selector is None`.
         ] = cast(Any, None),
-        parallel: bool = True,
+        parallel: Annotated[
+            bool,
+            Field(
+                description=(
+                    "Dispatch operations concurrently (default) or one at a "
+                    "time when False."
+                ),
+            ),
+        ] = True,
         ctx: Context | None = None,
         selector: Annotated[
             SkipValidation[BulkControlSelector] | None,
@@ -2234,10 +2251,38 @@ class ServiceTools:
         ] = None,
         timeout_seconds: Annotated[
             float | None,
-            Field(ge=0, le=60, allow_inf_nan=False, strict=True),
+            Field(
+                ge=0,
+                le=60,
+                allow_inf_nan=False,
+                strict=True,
+                description=(
+                    "Selector mode only: confirmation wait in seconds for every "
+                    "resolved entity. In operations mode set timeout_seconds on "
+                    "each operation instead; a top-level value is rejected in "
+                    "operations mode."
+                ),
+            ),
         ] = None,
-        validate_first: Annotated[bool, Field(strict=True)] = True,
-        dry_run: Annotated[bool, Field(strict=True)] = False,
+        validate_first: Annotated[
+            bool,
+            Field(
+                strict=True,
+                description=(
+                    "Selector mode only: report ENTITY_NOT_FOUND for a target "
+                    "that does not exist. In operations mode set "
+                    "validate_first on each operation instead; a top-level "
+                    "False is rejected in operations mode."
+                ),
+            ),
+        ] = True,
+        dry_run: Annotated[
+            bool,
+            Field(
+                strict=True,
+                description="Selector mode only; True is rejected in operations mode.",
+            ),
+        ] = False,
     ) -> dict[str, Any]:
         """Manage explicit operations or one deterministic structural bulk action.
 
@@ -2449,8 +2494,22 @@ class ServiceTools:
     @log_tool_usage
     async def ha_call_event(
         self,
-        event_type: str,
-        data: Annotated[dict[str, Any] | None, JSON_STRING_COERCION] = None,
+        event_type: Annotated[
+            str,
+            Field(
+                description="Event type to fire, e.g. 'my_custom_event'.",
+            ),
+        ],
+        data: Annotated[
+            dict[str, Any] | None,
+            JSON_STRING_COERCION,
+            Field(
+                description=(
+                    "Optional event payload, delivered to subscribers as the "
+                    "event's data (trigger.event.data in an automation)."
+                ),
+            ),
+        ] = None,
     ) -> dict[str, Any]:
         """Execute a custom event on the Home Assistant event bus.
 

{ha_mcp_dev-8.5.0.dev2757 → ha_mcp_dev-8.5.0.dev2759}/src/ha_mcp/tools/tools_system.py

@@ -644,13 +644,9 @@ class SystemTools:
         connectivity; available information varies by installation type and
         loaded integrations. Optional sections are selected with `include`.
 
-        The result also carries ``ha_mcp_update`` ``{current, latest,
-        update_available}``, reporting whether a newer ha-mcp release is
-        available (PyPI for pip/Docker, the Supervisor store for the app) —
-        proactively tell the user to upgrade. Present on every install type
-        including the HA app; omitted for the ``unknown`` version, when
-        ``HA_MCP_DISABLE_UPDATE_CHECK`` is set, or when the update check itself
-        failed.
+        The result may include ``ha_mcp_update`` ``{current, latest,
+        update_available}``. When update_available is true, tell the user a
+        newer ha-mcp release is available.
 
         EXAMPLES:
         - ha_get_system_health(include="repairs,zha_network,zwave_network,config_check")

{ha_mcp_dev-8.5.0.dev2757 → ha_mcp_dev-8.5.0.dev2759}/src/ha_mcp/tools/tools_traces.py

@@ -118,9 +118,10 @@ class TraceTools:
 
         Traces show what triggered a run, which conditions passed or failed,
         which actions executed (for 'choose', which branch was taken), any
-        errors, and variable values during execution. Traces are stored for a
-        limited time by Home Assistant. The 'state' field shows 'stopped'
-        (completed), 'running', or an error state.
+        errors, and variable values during execution. Home Assistant keeps
+        only the most recent runs of each automation or script (its
+        stored_traces setting), so older runs are not available. The 'state'
+        field shows 'stopped' (completed), 'running', or an error state.
 
         USAGE MODES:
         1. List recent traces (omit run_id): returns a summary of recent runs

{ha_mcp_dev-8.5.0.dev2757 → ha_mcp_dev-8.5.0.dev2759}/src/ha_mcp/tools/tools_yaml_config.py

@@ -397,9 +397,10 @@ class YamlConfigTools:
         configuration.yaml carries the ``frontend: themes:`` include (e.g.
         ``!include_dir_merge_named themes``); this tool cannot add that include
         (``frontend`` is not an allowed key). ``automation``, ``script`` and
-        ``scene`` keys are accepted only when ``file`` is a ``packages/*.yaml``;
-        writes of those keys to ``configuration.yaml`` are rejected — use the
-        storage-mode tools.
+        ``scene`` keys are accepted only when ``file`` is a ``packages/*.yaml``
+        and the operator has turned on that key's packages setting (each is
+        off by default); writes of those keys to ``configuration.yaml`` are
+        rejected; use the storage-mode tools.
 
         Check ``post_action`` in the response: most keys need a full HA
         restart. For ``themes/*.yaml`` this tool *performs* the reload itself

{ha_mcp_dev-8.5.0.dev2757 → ha_mcp_dev-8.5.0.dev2759/src/ha_mcp_dev.egg-info}/PKG-INFO

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