ha-mcp-dev 7.3.0.dev399__tar.gz → 7.3.0.dev400__tar.gz

{ha_mcp_dev-7.3.0.dev399/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.3.0.dev400}/PKG-INFO

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

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

@@ -222,8 +222,15 @@ class AreaTools:
         """
         Create or update a Home Assistant area (room).
 
-        Provide name only to create a new area. Provide area_id to update existing.
         Areas organize entities by physical location for room-based control.
+
+        Create: provide name only.
+        Update: provide area_id (from ha_config_list_areas) plus any fields to change.
+
+        EXAMPLES:
+        ha_config_set_area(name="Kitchen")
+        ha_config_set_area(name="Living Room", icon="mdi:sofa")
+        ha_config_set_area(area_id="kitchen", name="Kitchen Renamed", floor_id="ground_floor")
         """
         try:
             # Parse aliases if provided as string

{ha_mcp_dev-7.3.0.dev399 → ha_mcp_dev-7.3.0.dev400}/src/ha_mcp/tools/tools_config_automations.py

@@ -41,6 +41,7 @@ from .reference_validator import validate_config_references
 from .util_helpers import (
     apply_entity_category,
     coerce_bool_param,
+    coerce_to_list,
     fetch_entity_category,
     merge_validation_meta,
     parse_json_param,
@@ -413,7 +414,7 @@ class AutomationConfigTools:
         BASIC EXAMPLES:
 
         Simple time-based automation:
-        ha_config_set_automation({
+        ha_config_set_automation(config={
             "alias": "Morning Lights",
             "description": "Turn on bedroom lights at 7 AM to help wake up",
             "trigger": [{"platform": "time", "at": "07:00:00"}],
@@ -421,7 +422,7 @@ class AutomationConfigTools:
         })
 
         Motion-activated lighting with condition:
-        ha_config_set_automation({
+        ha_config_set_automation(config={
             "alias": "Motion Light",
             "trigger": [{"platform": "state", "entity_id": "binary_sensor.motion", "to": "on"}],
             "condition": [{"condition": "sun", "after": "sunset"}],
@@ -449,7 +450,7 @@ class AutomationConfigTools:
         BLUEPRINT AUTOMATION EXAMPLES:
 
         Create automation from blueprint:
-        ha_config_set_automation({
+        ha_config_set_automation(config={
             "alias": "Motion Light Kitchen",
             "use_blueprint": {
                 "path": "homeassistant/motion_light.yaml",
@@ -757,10 +758,14 @@ class AutomationConfigTools:
         try:
             parsed_config = parse_json_param(config, "config")
         except ValueError as e:
-            raise_tool_error(create_validation_error(
-                f"Invalid config parameter: {e}",
-                parameter="config",
-                invalid_json=True,
+            raise_tool_error(create_error_response(
+                code=ErrorCode.VALIDATION_INVALID_JSON,
+                message=f"Invalid config parameter: {e}",
+                suggestions=[
+                    "Pass 'config' as a dict, not a JSON string, to avoid escaping issues.",
+                    "Check for JSON syntax errors: unquoted keys, trailing commas, or invalid escape sequences.",
+                ],
+                context={"parameter": "config"},
             ))
 
         if parsed_config is None or not isinstance(parsed_config, dict):
@@ -788,12 +793,54 @@ class AutomationConfigTools:
 
         missing_fields = [f for f in required_fields if f not in config_dict]
         if missing_fields:
+            # If the caller supplied a 'sequence' key, the config looks like a
+            # script — point them at ha_config_set_script instead of the generic
+            # missing-fields error.
+            if "sequence" in config_dict and (
+                "trigger" in missing_fields or "action" in missing_fields
+            ):
+                context: dict[str, Any] = {"missing_fields": missing_fields}
+                if identifier:
+                    context["identifier"] = identifier
+                raise_tool_error(create_error_response(
+                    code=ErrorCode.CONFIG_MISSING_REQUIRED_FIELDS,
+                    message=f"Missing required fields: {', '.join(missing_fields)}",
+                    details=(
+                        "Config contains 'sequence', which belongs to scripts. "
+                        "Automations use 'trigger' and 'action'; scripts use 'sequence'."
+                    ),
+                    suggestions=[
+                        "Did you mean ha_config_set_script? Scripts use 'sequence' directly.",
+                        "For an automation, replace 'sequence' with 'action' and add a 'trigger'.",
+                    ],
+                    context=context,
+                ))
             raise_tool_error(create_config_error(
                 f"Missing required fields: {', '.join(missing_fields)}",
                 identifier=identifier,
                 missing_fields=missing_fields,
             ))
 
+        # HA accepts conditions with 'platform' (trigger syntax) but then crashes
+        # with an unhelpful 500 rather than a 400 validation error.
+        for idx, cond in enumerate(coerce_to_list(config_dict.get("condition"))):
+            if not isinstance(cond, dict):
+                continue
+            if "platform" in cond and "condition" not in cond:
+                raise_tool_error(create_error_response(
+                    code=ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    message=(
+                        f"Condition at index {idx} uses 'platform' (trigger syntax). "
+                        "Conditions use 'condition', not 'platform'."
+                    ),
+                    suggestions=[
+                        f"Replace 'platform' with 'condition': "
+                        f"{{'condition': '{cond['platform']}', ...}}",
+                        "Triggers use 'platform'; conditions use 'condition'.",
+                    ],
+                    context={"condition_index": idx, "found_key": "platform"},
+                ))
+
         # Prevent duplicate creation when config contains an existing automation id
         if identifier is None and "id" in config_dict:
             existing_id = config_dict["id"]

{ha_mcp_dev-7.3.0.dev399 → ha_mcp_dev-7.3.0.dev400}/src/ha_mcp/tools/tools_config_helpers.py

@@ -801,16 +801,16 @@ def register_config_helper_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
 
         EXAMPLES (menu-based types + tod, where first-call payload is non-obvious):
         - template sensor:
-            ha_config_set_helper("template", "Room Temp",
+            ha_config_set_helper(helper_type="template", name="Room Temp",
                 config={"next_step_id": "sensor",
                         "state": "{{ states('sensor.x')|float }}",
                         "unit_of_measurement": "°C"})
         - group (light):
-            ha_config_set_helper("group", "Kitchen Lights",
+            ha_config_set_helper(helper_type="group", name="Kitchen Lights",
                 config={"group_type": "light",
                         "entities": ["light.a", "light.b"]})
         - tod (time-of-day indicator, cross-midnight OK):
-            ha_config_set_helper("tod", "Quiet Hours",
+            ha_config_set_helper(helper_type="tod", name="Quiet Hours",
                 config={"after_time": "22:00:00", "before_time": "07:00:00"})
 
         For complex schemas and per-type parameter details, use ha_get_helper_schema.

{ha_mcp_dev-7.3.0.dev399 → ha_mcp_dev-7.3.0.dev400}/src/ha_mcp/tools/tools_config_scripts.py

@@ -313,19 +313,20 @@ class ConfigScriptTools:
             - max: Maximum concurrent executions (for queued/parallel modes)
             - fields: Input parameters for the script
 
-        IMPORTANT: The 'config' parameter must be passed as a proper dictionary/object.
+        SCRIPTS vs AUTOMATIONS: Scripts use 'sequence', NOT 'trigger' or 'action'.
+        If you need trigger-based execution, use ha_config_set_automation instead.
 
         EXAMPLES:
 
         Create basic delay script:
-        ha_config_set_script("wait_script", {
+        ha_config_set_script(script_id="wait_script", config={
             "sequence": [{"delay": {"seconds": 5}}],
             "alias": "Wait 5 Seconds",
             "description": "Simple delay script"
         })
 
         Create service call script:
-        ha_config_set_script("blink_light", {
+        ha_config_set_script(script_id="blink_light", config={
             "sequence": [
                 {"service": "light.turn_on", "target": {"entity_id": "light.living_room"}},
                 {"delay": {"seconds": 2}},
@@ -336,7 +337,7 @@ class ConfigScriptTools:
         })
 
         Create script with parameters:
-        ha_config_set_script("backup_script", {
+        ha_config_set_script(script_id="backup_script", config={
             "alias": "Backup with Reference",
             "description": "Create backup with optional reference parameter",
             "fields": {
@@ -360,7 +361,7 @@ class ConfigScriptTools:
         })
 
         Update script:
-        ha_config_set_script("morning_routine", {
+        ha_config_set_script(script_id="morning_routine", config={
             "sequence": [
                 {"service": "light.turn_on", "target": {"area_id": "bedroom"}},
                 {"service": "climate.set_temperature", "target": {"entity_id": "climate.bedroom"}, "data": {"temperature": 22}}
@@ -369,7 +370,7 @@ class ConfigScriptTools:
         })
 
         Create blueprint-based script:
-        ha_config_set_script("notification_script", {
+        ha_config_set_script(script_id="notification_script", config={
             "alias": "My Notification Script",
             "use_blueprint": {
                 "path": "notification_script.yaml",
@@ -381,7 +382,7 @@ class ConfigScriptTools:
         })
 
         Update blueprint script inputs:
-        ha_config_set_script("notification_script", {
+        ha_config_set_script(script_id="notification_script", config={
             "alias": "My Notification Script",
             "use_blueprint": {
                 "path": "notification_script.yaml",

{ha_mcp_dev-7.3.0.dev399 → ha_mcp_dev-7.3.0.dev400}/src/ha_mcp/tools/util_helpers.py

@@ -532,6 +532,13 @@ async def apply_entity_category(
         )
 
 
+def coerce_to_list(value: Any) -> list[Any]:
+    """Return value as a list: list → as-is, dict/other → [value], None/falsy → []."""
+    if isinstance(value, list):
+        return value
+    return [value] if value else []
+
+
 def merge_validation_meta(
     result: dict[str, Any], validation_meta: dict[str, Any]
 ) -> None:

{ha_mcp_dev-7.3.0.dev399 → ha_mcp_dev-7.3.0.dev400}/src/ha_mcp/transforms/categorized_search.py

@@ -111,19 +111,22 @@ def _build_proxy_descriptions(search_tool_name: str) -> dict[str, str]:
         "read": (
             f"Execute a read-only tool discovered via {search_tool_name}. "
             f"Safe — does not modify any data or state.\n"
-            f"{_PROXY_PARAMS_SUFFIX}"
+            f"{_PROXY_PARAMS_SUFFIX}\n"
+            f'EXAMPLE: ha_call_read_tool(name="ha_get_history", arguments={{"entity_ids": "light.x", "start_time": "24h"}})'
         ),
         "write": (
             f"Execute a write tool discovered via {search_tool_name}. "
             f"Creates or updates data. Use for any tool that modifies "
             f"state but does not delete/remove resources.\n"
-            f"{_PROXY_PARAMS_SUFFIX}"
+            f"{_PROXY_PARAMS_SUFFIX}\n"
+            f'EXAMPLE: ha_call_write_tool(name="ha_config_set_area", arguments={{"name": "Kitchen"}})'
         ),
         "delete": (
             f"Execute a delete/remove tool discovered via {search_tool_name}. "
             f"Permanently removes data. Use for tools that delete or "
             f"remove resources (areas, automations, devices, etc.).\n"
-            f"{_PROXY_PARAMS_SUFFIX}"
+            f"{_PROXY_PARAMS_SUFFIX}\n"
+            f'EXAMPLE: ha_call_delete_tool(name="ha_config_remove_area", arguments={{"area_id": "old_area"}})'
         ),
     }
 
@@ -254,13 +257,47 @@ class CategorizedSearchTransform(BM25SearchTransform):
         async def categorized_call(
             name: Annotated[str, "The name of the tool to call"],
             arguments: Annotated[
-                dict[str, Any] | None, "Arguments to pass to the tool"
+                dict[str, Any] | str | None, "Arguments to pass to the tool"
             ] = None,
             ctx: Context = None,  # type: ignore[assignment]
         ) -> Any:
             # Rebuild category cache if catalog has changed
             await transform._rebuild_category_cache(ctx)
 
+            # Tolerate `arguments` passed as a JSON string — small models
+            # sometimes serialize it before sending. Parse once up front so
+            # downstream logic can assume a dict (or None).
+            if isinstance(arguments, str):
+                try:
+                    parsed = json.loads(arguments)
+                except json.JSONDecodeError as e:
+                    raise ToolError(json.dumps(create_error_response(
+                        code=ErrorCode.VALIDATION_INVALID_JSON,
+                        message=f"'arguments' is a string but not valid JSON: {e}",
+                        suggestions=[
+                            "Pass 'arguments' as an object, not a JSON string.",
+                        ],
+                        context={"proxy_used": proxy_name, "tool_name": name},
+                    ))) from e
+                if not isinstance(parsed, dict):
+                    raise ToolError(json.dumps(create_error_response(
+                        code=ErrorCode.VALIDATION_INVALID_PARAMETER,
+                        message=(
+                            "'arguments' must be a JSON object "
+                            f"(got {type(parsed).__name__})."
+                        ),
+                        suggestions=[
+                            "Pass 'arguments' as an object (dict), not a list or scalar.",
+                        ],
+                        context={"proxy_used": proxy_name, "tool_name": name},
+                    )))
+                logger.warning(
+                    "Proxy %s received 'arguments' as a JSON string for tool %s — parsed as fallback",
+                    proxy_name,
+                    name,
+                )
+                arguments = parsed
+
             # Determine which category set to check
             if category == "read":
                 allowed = transform._read_tools

{ha_mcp_dev-7.3.0.dev399 → ha_mcp_dev-7.3.0.dev400/src/ha_mcp_dev.egg-info}/PKG-INFO

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