ha-mcp-dev 7.6.0.dev621__tar.gz → 7.6.0.dev623__tar.gz

{ha_mcp_dev-7.6.0.dev621/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.6.0.dev623}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.6.0.dev621"
+version = "7.6.0.dev623"
 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.dev621 → ha_mcp_dev-7.6.0.dev623}/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.
@@ -144,6 +165,18 @@ class Settings(BaseSettings):
     # env-var users see the trade-off in their logs.
     enable_lite_docstrings: bool = Field(False, alias="ENABLE_LITE_DOCSTRINGS")
 
+    # Mandatory best-practice skills — server-side master switch for the
+    # write-tool skill_content delivery feature (issue #1182). When True
+    # (default), the six write tools (automations / scripts / scenes /
+    # helpers / dashboards / yaml) attach the canonical best-practice
+    # reference files under ``skill_content`` on every successful write,
+    # plus auto-embed any sections cited by best-practice warnings. The
+    # per-call ``MandatoryBPS`` parameter on each tool controls whether
+    # the canonical files ship for that one call. This setting is the
+    # master gate above that — when False, NO skill_content goes out
+    # regardless of the per-call param or BP warnings. Default on.
+    enable_mandatory_bps: bool = Field(True, alias="ENABLE_MANDATORY_BPS")
+
     # Filesystem tools — read/write/delete/list under the HA config dir.
     # Previously gated by a direct ``os.getenv`` call in
     # ``tools/tools_filesystem.py`` so callers (and the settings UI)
@@ -412,7 +445,28 @@ FEATURE_FLAG_FIELDS: tuple[FeatureFlagField, ...] = (
     FeatureFlagField(
         "enable_tool_security_policies", "ENABLE_TOOL_SECURITY_POLICIES", bool
     ),
+    # Non-beta, default-ON master switch for write-tool skill_content
+    # delivery (#1182). Grouped with the non-beta flags above the beta
+    # run below; intentionally NOT in BETA_FEATURE_FIELDS (it must not be
+    # gated by the beta master) nor in ADVANCED_SETTINGS_FIELDS (registries
+    # 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(
@@ -449,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",
@@ -461,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
@@ -613,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.
     """
@@ -632,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.
@@ -730,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
@@ -738,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.dev621 → ha_mcp_dev-7.6.0.dev623}/src/ha_mcp/server.py

@@ -200,10 +200,13 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
 
         Skills are vendored via a git submodule at resources/skills-vendor/.
         The actual skill directories live under the skills/ subdirectory
-        within that repo.
+        within that repo. Delegates to
+        :func:`ha_mcp.utils.skill_loader.get_skills_dir` so the write-tool
+        ``MandatoryBPS`` parameter resolves the same path.
         """
-        skills_dir = Path(__file__).parent / "resources" / "skills-vendor" / "skills"
-        return skills_dir if skills_dir.exists() else None
+        from .utils.skill_loader import get_skills_dir
+
+        return get_skills_dir()
 
     def _build_skills_instructions(self) -> str | None:
         """Build server instructions from bundled skill frontmatter.
@@ -1434,13 +1437,28 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
                 )
             )
 
-        return {
-            "success": True,
-            "skill": skill,
-            "file": file,
-            "uri": f"skill://{skill}/{file}",
-            "content": content,
-        }
+        # Hint goes at the top of the response so the LLM sees it before
+        # parsing the (potentially large) content body. Scoped to the
+        # best-practice skill because that's the one the write-tool
+        # MandatoryBPS param gates; other skills (if any) are unrelated.
+        from .tools.util_helpers import (
+            _HA_BEST_PRACTICES_SKILL_NAME,
+            _SKILL_GUIDE_MANDATORYBPS_HINT,
+        )
+
+        response: dict[str, Any] = {}
+        if skill == _HA_BEST_PRACTICES_SKILL_NAME:
+            response["skill_content_hint"] = _SKILL_GUIDE_MANDATORYBPS_HINT
+        response.update(
+            {
+                "success": True,
+                "skill": skill,
+                "file": file,
+                "uri": f"skill://{skill}/{file}",
+                "content": content,
+            }
+        )
+        return response
 
     # Helper methods required by EnhancedToolsMixin
 

{ha_mcp_dev-7.6.0.dev621 → ha_mcp_dev-7.6.0.dev623}/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
@@ -2165,6 +2174,10 @@ const FEATURE_META = {
     label: "Enable Tool Security Policies",
     help: "Opt-in middleware that gates high-stakes MCP tool calls behind user approval. When enabled, tools that match a rule in the Tool Security Policies tab require you to click Approve in the web UI before they run. Off by default. Per-tool rules with optional argument conditions are configured in the Tool Security Policies tab. Requires restart to take effect.",
   },
+  enable_mandatory_bps: {
+    label: "Attach best-practice skills on writes",
+    help: "Master switch for the write-tool skill content delivery feature (issue #1182). When enabled (default), the six config write tools (automations, scripts, scenes, helpers, dashboards, raw YAML) attach the canonical Home Assistant best-practice reference files under skill_content on every successful write, plus auto-embed any reference sections cited by best-practice warnings. Each tool also exposes a per-call MandatoryBPS parameter the agent can set to false on subsequent calls once it has the content. When this master switch is off, NO skill_content goes out regardless of the per-call parameter or BP warnings. Leave on if your LLM benefits from inline guidance; turn off to minimise tokens when using an LLM that has the best-practice files indexed via skills or another retrieval path. Requires restart to take effect.",
+  },
   // Master beta toggle — gates the 5 sub-flags below at runtime
   // (see config.py:_apply_feature_flag_overrides master gate). UI
   // dims sub-rows when this is off and re-renders live on flip.
@@ -2176,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.",
@@ -2200,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
@@ -2309,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);
@@ -2377,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');
@@ -2413,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);
   });
 }
 
@@ -4186,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,
@@ -4539,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,
@@ -4704,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,
                     )
@@ -5239,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,
@@ -5279,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,
                 )
@@ -5288,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,
                 )
@@ -5338,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,
                 )
@@ -5363,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,
                     )
@@ -5462,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,
         )