ha-mcp-dev 7.6.0.dev622__tar.gz → 7.6.0.dev624__tar.gz

{ha_mcp_dev-7.6.0.dev622/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.6.0.dev624}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.6.0.dev622"
+version = "7.6.0.dev624"
 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.6.0.dev622 → ha_mcp_dev-7.6.0.dev624}/src/ha_mcp/config.py

@@ -110,7 +110,7 @@ class Settings(BaseSettings):
 
     # Master beta-features toggle. UI-only — intentionally not in any
     # addon config.yaml schema. Consumed by the master gate in
-    # ``_apply_feature_flag_overrides``, which force-sets the five
+    # ``_apply_feature_flag_overrides``, which force-sets the
     # ``BETA_FEATURE_FIELDS`` sub-flags to False whenever this master is
     # off. Dev addon ``start.py`` auto-writes ``ENABLE_BETA_FEATURES=true``
     # whenever any beta sub-flag key is present in ``/data/options.json``
@@ -122,6 +122,27 @@ class Settings(BaseSettings):
     # files. Disabled by default; only for YAML-only features with no UI/API path.
     enable_yaml_config_editing: bool = Field(False, alias="ENABLE_YAML_CONFIG_EDITING")
 
+    # Per-key gates for ``automation`` / ``script`` / ``scene`` under
+    # ``packages/*.yaml``. The custom component accepts these three
+    # PACKAGES_ONLY_YAML_KEYS unconditionally; ha-mcp's UI exposes a
+    # toggle per key so an operator who wants YAML-managed
+    # automations/scripts/scenes in packages but not the others can
+    # narrow the surface. ha_config_set_yaml rejects packages/*.yaml
+    # writes for a disabled key client-side, and passes the disabled set
+    # to the custom component so the underlying service rejects too
+    # (writes of these keys to configuration.yaml are rejected
+    # independently of these flags). Each
+    # toggle is meaningful only when ``enable_yaml_config_editing`` is
+    # on; the UI nests these rows under that parent and dims them when
+    # the parent is off.
+    enable_yaml_packages_automation: bool = Field(
+        False, alias="ENABLE_YAML_PACKAGES_AUTOMATION"
+    )
+    enable_yaml_packages_script: bool = Field(
+        False, alias="ENABLE_YAML_PACKAGES_SCRIPT"
+    )
+    enable_yaml_packages_scene: bool = Field(False, alias="ENABLE_YAML_PACKAGES_SCENE")
+
     # Seed values for tool visibility (comma-separated tool names).
     # Used as initial config when no tool_config.json exists.
     # The web settings UI (/settings) is the primary interface for managing these.
@@ -431,6 +452,21 @@ FEATURE_FLAG_FIELDS: tuple[FeatureFlagField, ...] = (
     # are name-disjoint per _validate_registries()).
     FeatureFlagField("enable_mandatory_bps", "ENABLE_MANDATORY_BPS", bool),
     FeatureFlagField("enable_yaml_config_editing", "ENABLE_YAML_CONFIG_EDITING", bool),
+    # Per-key sub-gates beneath enable_yaml_config_editing. Nested in
+    # the UI, dimmed when the parent is off. Also listed in
+    # BETA_FEATURE_FIELDS so they follow the same master-gate +
+    # addon-mode override path as the other beta flags — that is what
+    # makes the web-UI toggle take effect on the stable add-on (where
+    # they are not in config.yaml). See that tuple for the rationale.
+    FeatureFlagField(
+        "enable_yaml_packages_automation",
+        "ENABLE_YAML_PACKAGES_AUTOMATION",
+        bool,
+    ),
+    FeatureFlagField(
+        "enable_yaml_packages_script", "ENABLE_YAML_PACKAGES_SCRIPT", bool
+    ),
+    FeatureFlagField("enable_yaml_packages_scene", "ENABLE_YAML_PACKAGES_SCENE", bool),
     FeatureFlagField("enable_lite_docstrings", "ENABLE_LITE_DOCSTRINGS", bool),
     FeatureFlagField("enable_filesystem_tools", "HAMCP_ENABLE_FILESYSTEM_TOOLS", bool),
     FeatureFlagField(
@@ -467,6 +503,16 @@ _FEATURE_FLAG_INT_BOUNDS: dict[str, tuple[int, int]] = {
 # gate, never by the per-field iteration.
 BETA_FEATURE_FIELDS: tuple[str, ...] = (
     "enable_yaml_config_editing",
+    # Per-key sub-gates of enable_yaml_config_editing. Included here so
+    # they ride the same master gate + addon-mode override path as the
+    # other beta flags. Without this, the addon-mode short-circuit in
+    # ``_apply_feature_flag_overrides`` (and the ``get_feature_flag_origin``
+    # logic) would leave them dead on the stable add-on — reachable only
+    # via the dev add-on's config.yaml options. They still render NESTED
+    # under their parent in the web UI (not as separate beta-sub rows).
+    "enable_yaml_packages_automation",
+    "enable_yaml_packages_script",
+    "enable_yaml_packages_scene",
     "enable_filesystem_tools",
     "enable_custom_component_integration",
     "enable_code_mode",
@@ -479,8 +525,9 @@ BETA_FEATURE_FIELDS: tuple[str, ...] = (
 #
 # - ``section`` groups fields in the Advanced section of the Server Settings
 #   tab: "connection", "search", "operations", "diagnostics", "tools_surface".
-#   The 5 beta sub-flags + the master live in a separate "beta" section that
-#   the UI renders below the Advanced section.
+#   The beta sub-flags + the master live in a separate "beta" section that
+#   the UI renders below the Advanced section (the per-key yaml-packages
+#   sub-flags render nested under enable_yaml_config_editing within it).
 # - ``editable=False`` marks display-only rows. Connection fields are
 #   non-editable from the running server (chicken-and-egg footgun);
 #   ``MCP_SERVER_VERSION`` is editable (it has an env alias) but the UI
@@ -631,7 +678,7 @@ def get_feature_flag_origin(env_name: str) -> str:
       schema, ``start.py`` doesn't write the env var, and the master
       falls through to env / file / default precedence so the
       standalone web UI master path remains the gate.
-    - The five ``BETA_FEATURE_FIELDS`` (sub-flags) follow the same
+    - The ``BETA_FEATURE_FIELDS`` (sub-flags) follow the same
       shape — present in dev addon schema, absent from stable. Same
       env-var-presence signal distinguishes them at runtime.
     """
@@ -650,8 +697,8 @@ def get_feature_flag_origin(env_name: str) -> str:
             # Stable addon: env var never written → fall through to
             # file/default. The master moved from "never schema-bound"
             # to "schema-bound on dev only"; the same env-var-presence
-            # signal now distinguishes both for the master and the 5
-            # sub-flags.
+            # signal now distinguishes both for the master and the
+            # beta sub-flags.
             if os.environ.get(env_name) is not None:
                 return "addon"
             # else: stable / legacy-dev-no-master-key, fall through.
@@ -748,7 +795,7 @@ def _apply_feature_flag_overrides(settings: "Settings") -> None:
 
        EXCEPTION: the beta-master + beta-sub-flag fields skip the
        addon-mode short-circuit. The master isn't in any addon schema;
-       the five sub-flags are in the dev-addon schema (where ``start.py``
+       the sub-flags are in the dev-addon schema (where ``start.py``
        writes the env var from options.json — env-var-wins skips the
        file read here, leaving Supervisor authoritative) but NOT in the
        stable schema (where the env var is never written, so the file
@@ -756,7 +803,7 @@ def _apply_feature_flag_overrides(settings: "Settings") -> None:
 
     2. **Beta master gate**: after the per-field pass, if
        ``enable_beta_features`` is False on the resolved Settings,
-       force-set the five BETA_FEATURE_FIELDS to False regardless of
+       force-set the BETA_FEATURE_FIELDS to False regardless of
        how they currently look. This is the "master toggle" semantics —
        even a power user who sets ENABLE_YAML_CONFIG_EDITING=true via
        env var still needs to flip the master before the flag takes

{ha_mcp_dev-7.6.0.dev622 → ha_mcp_dev-7.6.0.dev624}/src/ha_mcp/server.py

@@ -190,6 +190,12 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
         # the skill guide tool are registered so it can wrap everything)
         self._apply_tool_search()
 
+        # Convert Pydantic type-validation errors to structured ToolErrors so
+        # models get actionable guidance instead of raw Pydantic messages.
+        from .tools.validation_middleware import ValidationErrorMiddleware
+
+        self.mcp.add_middleware(ValidationErrorMiddleware())
+
         # Wire tool security policies middleware (#966) — opt-in via
         # ENABLE_TOOL_SECURITY_POLICIES. Must come last so the middleware
         # wraps the final tool surface (including the search proxies).

{ha_mcp_dev-7.6.0.dev622 → ha_mcp_dev-7.6.0.dev624}/src/ha_mcp/settings_ui.py

@@ -814,6 +814,15 @@ _SETTINGS_HTML = (
     left: 36px; top: 0; bottom: 0; width: 2px; background: var(--border); }
   .feature-row.codemode-sub.dimmed { opacity: 0.55; }
   .feature-row.codemode-sub.dimmed input { cursor: not-allowed; }
+  /* YAML packages per-key sub-rows — second-level nested under
+     enable_yaml_config_editing. Same dimming logic as codemode-sub
+     but gated by enable_yaml_config_editing (the parent flag) rather
+     than enable_code_mode. */
+  .feature-row.yaml-packages-sub { padding-left: 56px; position: relative; }
+  .feature-row.yaml-packages-sub::before { content: ""; position: absolute;
+    left: 36px; top: 0; bottom: 0; width: 2px; background: var(--border); }
+  .feature-row.yaml-packages-sub.dimmed { opacity: 0.55; }
+  .feature-row.yaml-packages-sub.dimmed input { cursor: not-allowed; }
   /* Advanced settings sections — one row per
      ADVANCED_SETTINGS_FIELDS entry, grouped by section. Visually
      matches the .feature-row treatment so the Server Settings tab
@@ -2180,6 +2189,18 @@ const FEATURE_META = {
     label: "Enable YAML config editing (beta)",
     help: "Beta feature — disabled by default. Allows AI assistants to add, replace, or remove top-level keys in configuration.yaml and packages/*.yaml. Only whitelisted keys are allowed (e.g., template, sensor, command_line, mqtt, knx); core keys like homeassistant, http, and recorder are blocked. Each edit validates YAML syntax, runs a config check, and creates an automatic backup. Changes to most keys require a full HA restart to take effect. See docs/beta.md for known limitations. Dedicated tools (automations, scripts, scenes, helpers, template sensors) should be preferred when available.",
   },
+  enable_yaml_packages_automation: {
+    label: "Allow automation in packages/*.yaml",
+    help: "Sub-toggle of YAML config editing. When on, ha_config_set_yaml accepts yaml_path='automation' inside packages/*.yaml. When off, the wrapper rejects the call client-side AND the custom component rejects it server-side. Storage-mode tools (ha_config_set_automation) cover the UI-managed path and are unaffected. Disabled by default.",
+  },
+  enable_yaml_packages_script: {
+    label: "Allow script in packages/*.yaml",
+    help: "Sub-toggle of YAML config editing. When on, ha_config_set_yaml accepts yaml_path='script' inside packages/*.yaml. When off, the wrapper rejects the call client-side AND the custom component rejects it server-side. Storage-mode tools (ha_config_set_script) cover the UI-managed path and are unaffected. Disabled by default.",
+  },
+  enable_yaml_packages_scene: {
+    label: "Allow scene in packages/*.yaml",
+    help: "Sub-toggle of YAML config editing. When on, ha_config_set_yaml accepts yaml_path='scene' inside packages/*.yaml. When off, the wrapper rejects the call client-side AND the custom component rejects it server-side. Storage-mode tools (ha_config_set_scene) cover the UI-managed path and are unaffected. Disabled by default.",
+  },
   enable_filesystem_tools: {
     label: "Enable filesystem tools (beta)",
     help: "Sets HAMCP_ENABLE_FILESYSTEM_TOOLS=true. Enables direct file read/write access to your Home Assistant filesystem. WARNING: This gives the MCP server sensitive direct file access to your system. Only enable if you trust the AI assistant with file operations. Requires restart to take effect.",
@@ -2204,6 +2225,16 @@ const FEATURE_META = {
 // ``config.BETA_FEATURE_FIELDS`` without duplicating the name list here.
 let BETA_SUB_FLAGS = new Set();
 
+// Sub-flags of ``enable_yaml_config_editing``. Rendered nested beneath
+// the parent in renderFeatureFlags so the dependency is visually
+// obvious. They are NOT in BETA_SUB_FLAGS — the parent is the gate,
+// and the master-off → parent-off cascade transitively covers them.
+const YAML_PACKAGES_SUB_FLAGS = [
+  'enable_yaml_packages_automation',
+  'enable_yaml_packages_script',
+  'enable_yaml_packages_scene',
+];
+
 // Cached add-on flag. Each settings endpoint (/api/settings/features,
 // /api/settings/advanced, /api/settings/backup-config) returns
 // ``is_addon`` so the env-locked banner copy can adapt — the addon
@@ -2313,6 +2344,10 @@ function renderFeatureFlags(flags) {
   Object.keys(FEATURE_META).forEach(fieldName => {
     const f = flags[fieldName];
     if (!f) return;
+    // Skip yaml-packages sub-rows in the main pass — they're rendered
+    // by renderYamlPackagesSubRows below right after their parent so
+    // the nesting reads in source order.
+    if (YAML_PACKAGES_SUB_FLAGS.includes(fieldName)) return;
     const meta = FEATURE_META[fieldName];
     const isMaster = fieldName === 'enable_beta_features';
     const isBetaSub = BETA_SUB_FLAGS.has(fieldName);
@@ -2381,6 +2416,20 @@ function renderFeatureFlags(flags) {
             renderFeatureFlags(_lastFeatureFlags);
           }
         }
+        // Re-render on enable_yaml_config_editing flip so the 3
+        // packages sub-rows dim/undim immediately. Same pattern as the
+        // master flip above — value is mutated in the live cache and
+        // the panel re-renders synchronously while the save POST runs
+        // in the background.
+        if (fieldName === 'enable_yaml_config_editing') {
+          if (_lastFeatureFlags[fieldName]) {
+            _lastFeatureFlags[fieldName] = {
+              ..._lastFeatureFlags[fieldName],
+              value: input.checked,
+            };
+            renderFeatureFlags(_lastFeatureFlags);
+          }
+        }
         saveFeatureFlag(fieldName, input.checked);
       });
       const slider = document.createElement('span');
@@ -2417,6 +2466,74 @@ function renderFeatureFlags(flags) {
       const codeModeOn = !!f.value;
       renderCodeModeSubRows(targetBody, masterOn, codeModeOn);
     }
+    // After rendering the enable_yaml_config_editing parent, inject
+    // its 3 per-key sub-rows (automation/script/scene). Dimmed when
+    // either the master beta is off (parent forced off) or the parent
+    // itself is off.
+    if (fieldName === 'enable_yaml_config_editing') {
+      const parentOn = !!f.value;
+      renderYamlPackagesSubRows(flags, targetBody, masterOn, parentOn);
+    }
+  });
+}
+
+function renderYamlPackagesSubRows(flags, parentEl, masterOn, parentOn) {
+  YAML_PACKAGES_SUB_FLAGS.forEach(fieldName => {
+    const f = flags[fieldName];
+    if (!f) return;
+    const meta = FEATURE_META[fieldName] || { label: fieldName, help: '' };
+    const lockedByGate = !masterOn || !parentOn;
+    const row = document.createElement('div');
+    row.className = 'feature-row yaml-packages-sub' + (lockedByGate ? ' dimmed' : '');
+
+    const info = document.createElement('div');
+    info.className = 'feature-info';
+    const lockedNote = !f.editable
+      ? `<div class="feature-locked-note">` +
+        (f.origin === 'env'
+          ? envLockedNoteHtml(f.env_var, fieldName)
+          : escapeHtml(ORIGIN_LOCKED_NOTE[f.origin] || '')) +
+        `</div>`
+      : '';
+    const infoNote = f.editable && ORIGIN_INFO_NOTE[f.origin]
+      ? `<div class="feature-locked-note">` +
+        `${escapeHtml(ORIGIN_INFO_NOTE[f.origin])}</div>`
+      : '';
+    info.innerHTML =
+      `<div class="feature-name">${escapeHtml(meta.label)}</div>` +
+      `<div class="feature-help">${escapeHtml(meta.help)}</div>` +
+      lockedNote + infoNote;
+
+    const control = document.createElement('div');
+    control.className = 'feature-control';
+    const label = document.createElement('label');
+    label.className = 'switch';
+    const input = document.createElement('input');
+    input.type = 'checkbox';
+    input.checked = !!f.value;
+    input.disabled = !f.editable || lockedByGate;
+    input.addEventListener('change', () => {
+      // Keep the cached flag value in sync (parity with the parent/master
+      // row handlers) so a later parent flip — which re-renders from
+      // _lastFeatureFlags — reflects this sub-row's current state rather
+      // than a stale value.
+      if (_lastFeatureFlags[fieldName]) {
+        _lastFeatureFlags[fieldName] = {
+          ..._lastFeatureFlags[fieldName],
+          value: input.checked,
+        };
+      }
+      saveFeatureFlag(fieldName, input.checked);
+    });
+    const slider = document.createElement('span');
+    slider.className = 'slider';
+    label.appendChild(input);
+    label.appendChild(slider);
+    control.appendChild(label);
+
+    row.appendChild(info);
+    row.appendChild(control);
+    parentEl.appendChild(row);
   });
 }
 
@@ -4190,6 +4307,11 @@ def build_settings_handlers(
                     ErrorCode.VALIDATION_INVALID_PARAMETER,
                     f"Refusing to flip env-pinned tools: {', '.join(rejected)}. "
                     "Unset DISABLED_TOOLS / PINNED_TOOLS first.",
+                    suggestions=[
+                        "Unset the DISABLED_TOOLS / PINNED_TOOLS environment "
+                        "variables (or remove them from your addon/Docker "
+                        "config), then restart to edit these tools from the UI.",
+                    ],
                     context={"rejected": rejected},
                 ),
                 status_code=409,
@@ -4543,6 +4665,12 @@ def build_settings_handlers(
                         "enable_beta_features=true in the same save, or "
                         "flip the master on first."
                     ),
+                    suggestions=[
+                        "Include enable_beta_features=true in the same save "
+                        "payload as the sub-flag(s).",
+                        "Or turn on the master 'Enable beta features' toggle "
+                        "first, then enable the sub-flag(s).",
+                    ],
                     context={"rejected": beta_sub_writes},
                 ),
                 status_code=409,
@@ -4708,6 +4836,13 @@ def build_settings_handlers(
                         create_error_response(
                             ErrorCode.INTERNAL_ERROR,
                             "Supervisor helper returned ok=False with no error",
+                            suggestions=[
+                                "Check the Home Assistant Supervisor logs and "
+                                "the add-on logs for the underlying failure.",
+                                "Report this at "
+                                "https://github.com/homeassistant-ai/ha-mcp/issues "
+                                "if it persists — this indicates an internal bug.",
+                            ],
                         ),
                         status_code=500,
                     )
@@ -5243,6 +5378,11 @@ def build_settings_handlers(
                         ErrorCode.VALIDATION_INVALID_PARAMETER,
                         f"{fname!r} is set via {env_name} env var — "
                         "unset it to edit here.",
+                        suggestions=[
+                            f"Unset the {env_name} environment variable (or "
+                            "remove it from your addon/Docker config), then "
+                            "restart to edit this setting from the UI.",
+                        ],
                         context={"env_var": env_name},
                     ),
                     status_code=409,
@@ -5283,6 +5423,10 @@ def build_settings_handlers(
                         ErrorCode.VALIDATION_INVALID_PARAMETER,
                         f"{fname!r} must be between {bounds[0]} and "
                         f"{bounds[1]} (got {coerced}).",
+                        suggestions=[
+                            f"Provide a value for {fname} within the range "
+                            f"{bounds[0]}–{bounds[1]}.",
+                        ],
                     ),
                     status_code=400,
                 )
@@ -5292,6 +5436,9 @@ def build_settings_handlers(
                     create_error_response(
                         ErrorCode.VALIDATION_INVALID_PARAMETER,
                         f"{fname!r} must be one of {list(choices)} (got {coerced!r}).",
+                        suggestions=[
+                            f"Set {fname} to one of: {', '.join(map(str, choices))}.",
+                        ],
                     ),
                     status_code=400,
                 )
@@ -5342,6 +5489,11 @@ def build_settings_handlers(
                             "writes in one batch; the UI should split these "
                             f"into separate POSTs ({sorted(file_only)})."
                         ),
+                        suggestions=[
+                            "Submit addon-synced fields (e.g. backup_hint, "
+                            "verify_ssl) and override-file fields in separate "
+                            "save requests.",
+                        ],
                     ),
                     status_code=500,
                 )
@@ -5367,6 +5519,13 @@ def build_settings_handlers(
                         create_error_response(
                             ErrorCode.INTERNAL_ERROR,
                             "Supervisor helper returned ok=False with no error",
+                            suggestions=[
+                                "Check the Home Assistant Supervisor logs and "
+                                "the add-on logs for the underlying failure.",
+                                "Report this at "
+                                "https://github.com/homeassistant-ai/ha-mcp/issues "
+                                "if it persists — this indicates an internal bug.",
+                            ],
                         ),
                         status_code=500,
                     )
@@ -5466,6 +5625,9 @@ def build_settings_handlers(
             create_error_response(
                 ErrorCode.VALIDATION_INVALID_PARAMETER,
                 f"{fname!r} expects {ftype.__name__}, got {type(raw).__name__}.",
+                suggestions=[
+                    f"Send {fname} as a {ftype.__name__} value.",
+                ],
             ),
             status_code=400,
         )

{ha_mcp_dev-7.6.0.dev622 → ha_mcp_dev-7.6.0.dev624}/src/ha_mcp/tools/tools_filesystem.py

@@ -53,7 +53,7 @@ CALLER_TOKEN_BOOTSTRAP_SERVICE = "get_caller_token"
 # server-side behavior change requires it. Older components (no
 # ``version`` in the get_caller_token response, or a version below this)
 # get an actionable "update via HACS" error.
-MIN_COMPONENT_VERSION = "0.5.1"
+MIN_COMPONENT_VERSION = "0.5.2"
 
 
 def _version_tuple(version: str) -> tuple[int, ...]:

{ha_mcp_dev-7.6.0.dev622 → ha_mcp_dev-7.6.0.dev624}/src/ha_mcp/tools/tools_yaml_config.py

@@ -11,7 +11,9 @@ The tools will gracefully fail with installation instructions if the component i
 Feature Flag: Set ENABLE_YAML_CONFIG_EDITING=true to enable.
 """
 
+import fnmatch
 import logging
+import os
 from typing import Annotated, Any
 
 from fastmcp.exceptions import ToolError
@@ -47,6 +49,38 @@ logger = logging.getLogger(__name__)
 
 _LOVELACE_DASHBOARD_PREFIX = "lovelace.dashboards."
 
+# Maps a per-key Settings flag onto the yaml_path top-level segment it
+# gates. Keep in lockstep with the custom component's
+# PACKAGES_ONLY_YAML_KEYS — every key in that frozenset must appear
+# here, otherwise a key would silently be unreachable through the
+# wrapper. The parity invariant (keys == PACKAGES_ONLY_YAML_KEYS, and
+# every value is a real Settings field) is enforced by
+# test_yaml_config_tool.py::test_flag_map_matches_packages_only_keys.
+_YAML_PACKAGES_FLAG_BY_KEY = {
+    "automation": "enable_yaml_packages_automation",
+    "script": "enable_yaml_packages_script",
+    "scene": "enable_yaml_packages_scene",
+}
+
+
+def _disabled_packages_keys(settings: Any) -> list[str]:
+    """Return the sorted list of PACKAGES_ONLY_YAML_KEYS whose Settings
+    flag is currently False.
+
+    Sorted so the value is deterministic in service payloads and test
+    assertions; the custom component treats it as a set so order is
+    irrelevant on the wire.
+
+    Uses ``getattr`` without a default so a future rename that breaks the
+    ``_YAML_PACKAGES_FLAG_BY_KEY`` → ``Settings`` mapping raises loudly
+    instead of silently treating the key as disabled (a dead toggle).
+    """
+    return sorted(
+        key
+        for key, flag in _YAML_PACKAGES_FLAG_BY_KEY.items()
+        if not getattr(settings, flag)
+    )
+
 
 async def _check_storage_mode_dashboard_collision(client: Any, yaml_path: str) -> None:
     """Raise a ToolError if a storage-mode dashboard already owns the requested
@@ -237,6 +271,56 @@ class YamlConfigTools:
                     )
                 )
 
+            # Per-key gate: reject before the custom-component round
+            # trip when the yaml_path top-level segment matches a
+            # disabled PACKAGES_ONLY key AND the target file is under
+            # packages/. The keys (automation / script / scene) are
+            # only ACCEPTED in packages/*.yaml in the first place, so
+            # writes to configuration.yaml must fall through here and
+            # let the component-side reject with its own message that
+            # lists the storage-mode tools to use instead.
+            settings = get_global_settings()
+            disabled_keys = _disabled_packages_keys(settings)
+            top_key = yaml_path.split(".", 1)[0] if yaml_path else ""
+            # Classify the target exactly like the custom component does
+            # (os.path.normpath + fnmatch against "packages/*.yaml") so the
+            # wrapper's early reject fires for precisely the paths the
+            # component treats as a package — e.g. "./packages/x.yaml" and
+            # "packages/sub/x.yaml" both normalise/match. Any other target
+            # (configuration.yaml, a non-package path) falls through to the
+            # component, which rejects these keys with its own storage-mode-
+            # tools advisory.
+            # os.path.normpath is a pure string transform (no I/O), so the
+            # ASYNC240 blocking-call lint doesn't apply — same suppression the
+            # component uses on its identical normpath classification.
+            normalized_target = os.path.normpath(file)  # noqa: ASYNC240
+            is_packages_target = fnmatch.fnmatch(normalized_target, "packages/*.yaml")
+            if is_packages_target and top_key in disabled_keys:
+                raise_tool_error(
+                    create_error_response(
+                        ErrorCode.VALIDATION_INVALID_PARAMETER,
+                        (
+                            f"yaml_path key {top_key!r} is disabled. Enable "
+                            f"'Allow {top_key} in packages/*.yaml' under "
+                            f"YAML config editing in Server Settings to use "
+                            f"this key, or use the storage-mode tool "
+                            f"(ha_config_set_{top_key})."
+                        ),
+                        suggestions=[
+                            f"Enable 'Allow {top_key} in packages/*.yaml' under "
+                            "YAML config editing in the ha-mcp Server Settings "
+                            "panel, then retry.",
+                            f"Or use the storage-mode tool ha_config_set_{top_key} "
+                            "instead of editing packages YAML directly.",
+                        ],
+                        context={
+                            "yaml_path": yaml_path,
+                            "disabled_key": top_key,
+                            "file": file,
+                        },
+                    )
+                )
+
             # Storage-mode dashboard collision check (only for lovelace.dashboards.*).
             # Skip on `remove` so users can clean up YAML entries that conflict
             # with a storage-mode dashboard (e.g., during a migration).
@@ -252,6 +336,7 @@ class YamlConfigTools:
                 "action": action,
                 "yaml_path": yaml_path,
                 "backup": backup,
+                "disabled_packages_keys": disabled_keys,
             }
             if content is not None:
                 service_data["content"] = content

ha_mcp_dev-7.6.0.dev624/src/ha_mcp/tools/validation_middleware.py

@@ -0,0 +1,57 @@
+"""FastMCP middleware that converts Pydantic validation errors to structured ToolErrors.
+
+When a model passes the wrong type for a tool parameter (e.g. a JSON string where
+a dict is required), FastMCP raises a PydanticValidationError with a raw message
+like "Input should be a valid dictionary". This middleware intercepts those errors
+and converts them to ha-mcp's structured format with actionable guidance.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from fastmcp.server.middleware.middleware import CallNext, Middleware, MiddlewareContext
+from pydantic import ValidationError as PydanticValidationError
+
+from ..errors import create_validation_error
+from .helpers import raise_tool_error
+
+logger = logging.getLogger(__name__)
+
+# Maps Pydantic error types to model-readable fix hints.
+# FastMCP uses non-strict Pydantic: scalar mismatches (bool, int) are coerced
+# rather than rejected, so only dict_type and list_type fire in practice.
+_TYPE_HINTS: dict[str, str] = {
+    "dict_type": (
+        "expected a JSON object. "
+        'Pass {"key": "value"} directly, not a JSON-encoded string.'
+    ),
+    "list_type": (
+        "expected a JSON array. Pass [...] directly, not a JSON-encoded string."
+    ),
+}
+
+
+class ValidationErrorMiddleware(Middleware):
+    """Convert PydanticValidationError from argument validation into ToolErrors."""
+
+    async def on_call_tool(
+        self, context: MiddlewareContext, call_next: CallNext
+    ) -> Any:
+        try:
+            return await call_next(context)
+        except PydanticValidationError as exc:
+            errors = exc.errors(include_url=False)
+            parts: list[str] = []
+            for err in errors:
+                loc = err.get("loc", ())
+                param = ".".join(str(p) for p in loc if p != "__root__")
+                hint = _TYPE_HINTS.get(err["type"], err["msg"])
+                parts.append(f"`{param}`: {hint}" if param else hint)
+            raise_tool_error(
+                create_validation_error(
+                    "; ".join(parts) if parts else "Invalid argument types.",
+                    details=", ".join(err["type"] for err in errors),
+                )
+            )

{ha_mcp_dev-7.6.0.dev622 → ha_mcp_dev-7.6.0.dev624/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.6.0.dev622
+Version: 7.6.0.dev624
 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.6.0.dev622 → ha_mcp_dev-7.6.0.dev624}/src/ha_mcp_dev.egg-info/SOURCES.txt

@@ -99,6 +99,7 @@ src/ha_mcp/tools/tools_voice_assistant.py
 src/ha_mcp/tools/tools_yaml_config.py
 src/ha_mcp/tools/tools_zones.py
 src/ha_mcp/tools/util_helpers.py
+src/ha_mcp/tools/validation_middleware.py
 src/ha_mcp/transforms/__init__.py
 src/ha_mcp/transforms/categorized_search.py
 src/ha_mcp/transforms/lite_docstrings.py