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

{ha_mcp_dev-7.3.0.dev398/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.dev398
+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.dev398 → 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.dev398"
+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.dev398 → ha_mcp_dev-7.3.0.dev400}/src/ha_mcp/__init__.py

@@ -5,7 +5,9 @@ A Model Context Protocol server that provides complete control over Home Assista
 through REST API and WebSocket integration with 20+ enhanced tools.
 """
 
-__version__ = "7.3.0"
+from ._version import get_version
+
+__version__ = get_version()
 __author__ = "Julien"
 __license__ = "MIT"
 

{ha_mcp_dev-7.3.0.dev398 → ha_mcp_dev-7.3.0.dev400}/src/ha_mcp/__main__.py

@@ -283,6 +283,7 @@ def _setup_standard_mode() -> None:
     settings = get_settings()
     _validate_standard_credentials(settings)
     _setup_logging(settings.log_level)
+    _log_startup_version()
 
 
 def _http_run_kwargs(transport: str, port: int, path: str) -> dict:
@@ -411,6 +412,25 @@ def _setup_logging(log_level_str: str, force: bool = False) -> None:
     logging.getLogger("fastmcp.server.server").addFilter(ToolValidationLogFilter())
 
 
+def _log_startup_version() -> None:
+    """Log ha-mcp version at startup, plus a dev-channel banner when relevant.
+
+    The dev banner only fires for standalone dev installs (Docker ``:dev`` /
+    ``:latest``, or ``pip install ha-mcp-dev``). It is suppressed under the HA
+    Supervisor because add-on users already pick dev vs stable in the HAOS UI.
+    """
+    from ha_mcp._version import get_version, is_dev_version, is_running_in_addon
+
+    version = get_version()
+    logger.info(f"ha-mcp {version}")
+    if is_dev_version(version) and not is_running_in_addon():
+        logger.warning(
+            "This is the dev channel. For the stable release use the "
+            "'ghcr.io/homeassistant-ai/ha-mcp:stable' Docker tag "
+            "(or 'pip install ha-mcp' on PyPI)."
+        )
+
+
 def _get_timestamped_uvicorn_log_config() -> dict:
     """Return a Uvicorn log config with human-readable timestamps added."""
     from uvicorn.config import LOGGING_CONFIG
@@ -580,9 +600,9 @@ def main() -> None:
     """Run server via CLI using FastMCP's stdio transport."""
     # Handle --version flag early, before server creation requires config
     if "--version" in sys.argv or "-V" in sys.argv:
-        from importlib.metadata import version
+        from ha_mcp._version import get_version
 
-        print(f"ha-mcp {version('ha-mcp-dev')}")
+        print(f"ha-mcp {get_version()}")
         sys.exit(0)
 
     # Check for smoke test flag
@@ -605,6 +625,7 @@ def main() -> None:
         sys.exit(1)
 
     _setup_logging(settings.log_level)
+    _log_startup_version()
 
     _run_entrypoint(_run_with_graceful_shutdown(), "Server")
 
@@ -780,6 +801,7 @@ def main_oauth() -> None:
     for logger_name in ["ha_mcp", "ha_mcp.auth", "ha_mcp.auth.provider"]:
         logging.getLogger(logger_name).setLevel(getattr(logging, log_level))
     logger.info(f"OAuth mode logging configured at {log_level} level")
+    _log_startup_version()
 
     port, path = _get_http_runtime(default_port=8086)
     base_url = os.getenv("MCP_BASE_URL")

ha_mcp_dev-7.3.0.dev400/src/ha_mcp/_version.py

@@ -0,0 +1,58 @@
+"""Version resolution for the ha-mcp package.
+
+Kept as a standalone module (no other ``ha_mcp`` imports) so it can be used from
+``__init__.py`` and ``config.py`` without circular-import risk.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import logging
+import os
+
+logger = logging.getLogger(__name__)
+
+
+def get_version() -> str:
+    """Return the installed ha-mcp version.
+
+    Resolution order:
+    1. ``HA_MCP_BUILD_VERSION`` env var — set by Docker/add-on builds that can't
+       rewrite ``pyproject.toml`` before install, so the dev suffix still reaches
+       the running process. Stable builds leave it unset.
+    2. ``ha-mcp`` package metadata — stable PyPI + stable Docker.
+    3. ``ha-mcp-dev`` package metadata — PyPI dev channel (renamed package).
+
+    If none of the above resolve, logs a warning and returns ``"unknown"``.
+    The "unknown" string is itself diagnostic in bug reports and startup logs
+    — it tells triagers the install didn't register package metadata (e.g. a
+    source checkout without ``pip install -e .``, or a broken Docker layer).
+    """
+    if override := os.environ.get("HA_MCP_BUILD_VERSION"):
+        return override
+    for pkg_name in ("ha-mcp", "ha-mcp-dev"):
+        try:
+            return importlib.metadata.version(pkg_name)
+        except importlib.metadata.PackageNotFoundError:
+            continue
+    logger.warning(
+        "ha-mcp package metadata not found and HA_MCP_BUILD_VERSION unset — "
+        "version will be reported as 'unknown'. Reinstall the package or set "
+        "HA_MCP_BUILD_VERSION if this is an intentional source-tree run."
+    )
+    return "unknown"
+
+
+def is_dev_version(version: str) -> bool:
+    """Return True when the version string contains a PEP 440 ``.dev`` suffix."""
+    return ".dev" in version
+
+
+def is_running_in_addon() -> bool:
+    """Return True when running inside a Home Assistant add-on container.
+
+    The HA Supervisor injects ``SUPERVISOR_TOKEN`` into every add-on's env.
+    Checked so the standalone-Docker ``:stable`` banner isn't shown to add-on
+    users, who already see the dev/stable distinction in the HAOS add-on UI.
+    """
+    return bool(os.environ.get("SUPERVISOR_TOKEN"))

{ha_mcp_dev-7.3.0.dev398 → ha_mcp_dev-7.3.0.dev400}/src/ha_mcp/config.py

@@ -2,22 +2,20 @@
 Configuration management for Home Assistant MCP Server.
 """
 
-import importlib.metadata
 import os
 
 # Load environment variables from .env file with HAMCP_ENV_FILE support
 # Use absolute path to ensure .env is found regardless of cwd
 from pathlib import Path
 
-try:
-    _PACKAGE_VERSION = importlib.metadata.version("ha-mcp")
-except importlib.metadata.PackageNotFoundError:
-    _PACKAGE_VERSION = "unknown"
-
 from dotenv import load_dotenv
 from pydantic import Field, field_validator, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
+from ha_mcp._version import get_version
+
+_PACKAGE_VERSION = get_version()
+
 project_root = Path(__file__).parent.parent.parent
 
 # Demo environment token - use HOMEASSISTANT_TOKEN="demo" to connect to the public demo

{ha_mcp_dev-7.3.0.dev398 → 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.dev398 → 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.dev398 → 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.dev398 → 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.dev398 → 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.dev398 → 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.dev398 → 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.dev398
+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.dev398 → ha_mcp_dev-7.3.0.dev400}/src/ha_mcp_dev.egg-info/SOURCES.txt

@@ -5,6 +5,7 @@ pyproject.toml
 src/ha_mcp/__init__.py
 src/ha_mcp/__main__.py
 src/ha_mcp/_pypi_marker
+src/ha_mcp/_version.py
 src/ha_mcp/config.py
 src/ha_mcp/errors.py
 src/ha_mcp/py.typed