ha-mcp-dev 7.0.0.dev272__tar.gz → 7.0.0.dev274__tar.gz

{ha_mcp_dev-7.0.0.dev272/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.0.0.dev274}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.0.0.dev272"
+version = "7.0.0.dev274"
 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.0.0.dev272 → ha_mcp_dev-7.0.0.dev274}/src/ha_mcp/server.py

@@ -67,6 +67,7 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
         self._smart_tools: Any = None
         self._device_tools: Any = None
         self._tools_registry: ToolsRegistry | None = None
+        self._skill_tool_names: list[str] = []
 
         # Get server name/version from settings if no client provided
         if not self._client_provided:
@@ -208,14 +209,12 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
 
         return header + "\n".join(skill_blocks)
 
-    def _build_skill_block(
-        self, skill_name: str, main_file: Path
-    ) -> str | None:
-        """Build an instruction block for a single skill.
+    @staticmethod
+    def _parse_skill_frontmatter(main_file: Path) -> dict | None:
+        """Parse YAML frontmatter from a SKILL.md file.
 
-        Reads the description field from YAML frontmatter and includes it
-        verbatim. The description is designed for LLM consumption and
-        contains its own trigger conditions and symptom indicators.
+        Returns the frontmatter dict if valid, or None with a logged
+        warning for each failure case.
         """
         try:
             content = main_file.read_text(encoding="utf-8")
@@ -223,7 +222,6 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
             logger.warning("Could not read %s", main_file)
             return None
 
-        # Extract YAML frontmatter between --- markers
         parts = content.split("---", 2)
         if len(parts) < 3:
             logger.warning("No valid frontmatter delimiters in %s", main_file)
@@ -239,15 +237,34 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
             logger.warning("Frontmatter is not a mapping in %s", main_file)
             return None
 
-        description = frontmatter.get("description", "")
-        if not description:
-            logger.warning("No description in frontmatter for skill %s", skill_name)
+        if not frontmatter.get("description", ""):
+            logger.warning(
+                "No description in frontmatter for %s", main_file.parent.name
+            )
+            return None
+
+        return frontmatter
+
+    def _build_skill_block(
+        self, skill_name: str, main_file: Path
+    ) -> str | None:
+        """Build an instruction block for a single skill.
+
+        Reads the description field from YAML frontmatter and includes it
+        verbatim. The description is designed for LLM consumption and
+        contains its own trigger conditions and symptom indicators.
+        """
+        frontmatter = self._parse_skill_frontmatter(main_file)
+        if not frontmatter:
             return None
 
+        description = frontmatter["description"]
         uri = f"skill://{skill_name}/SKILL.md"
 
         return f"\n### Skill: {skill_name} ({uri})\n{description.strip()}"
 
+
+
     def _register_skills(self) -> None:
         """Register bundled HA best-practice skills as MCP resources.
 
@@ -308,6 +325,96 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
                 "Failed to expose skills as tools (resources still available)"
             )
 
+        # Phase 4: Register skill guidance tools for clients that don't read
+        # server instructions (e.g., claude.ai). The tool description contains
+        # the trigger conditions so the AI sees them in the tool listing.
+        # Names stored for pinning in search transforms (always-visible).
+        self._register_skill_guidance_tools(skills_dir)
+
+    def _register_skill_guidance_tools(self, skills_dir: Path) -> None:
+        """Register a lightweight guidance tool per skill.
+
+        Clients like claude.ai don't read the MCP server instructions field,
+        so the bootstrap prompt (trigger conditions, symptoms) is invisible.
+        This registers a tool per skill whose description contains the trigger
+        conditions. The tool itself just lists available reference files —
+        actual content is loaded on demand via read_resource.
+        """
+        try:
+            entries = sorted(skills_dir.iterdir())
+        except OSError:
+            logger.warning("Could not read skills directory: %s", skills_dir)
+            return
+
+        for skill_dir in entries:
+            main_file = skill_dir / "SKILL.md"
+            if not skill_dir.is_dir() or not main_file.exists():
+                continue
+
+            frontmatter = self._parse_skill_frontmatter(main_file)
+            if not frontmatter:
+                continue
+
+            description = frontmatter["description"].strip()
+            skill_name = skill_dir.name
+            tool_name = f"ha_get_skill_{skill_name.replace('-', '_')}"
+            uri = f"skill://{skill_name}/SKILL.md"
+
+            tool_description = (
+                f"CALL THIS FIRST before performing matching actions. "
+                f"{description}\n\n"
+                f"Returns available reference files. Use read_resource with "
+                f"the file URI to load specific guides as needed."
+            )
+
+            # Collect available reference files for the listing.
+            # Filter out symlinks and verify path containment to prevent
+            # traversal via symlinked directories.
+            ref_files = []
+            resolved_root = skill_dir.resolve()
+            try:
+                for f in sorted(skill_dir.rglob("*")):
+                    if not f.is_file() or f.is_symlink():
+                        continue
+                    # Ensure resolved path stays within the skill directory
+                    if not f.resolve().is_relative_to(resolved_root):
+                        continue
+                    rel = f.relative_to(skill_dir)
+                    ref_uri = f"skill://{skill_name}/{rel}"
+                    ref_files.append({"name": str(rel), "uri": ref_uri})
+            except OSError:
+                logger.warning("Error reading skill files in %s", skill_dir)
+
+            # Use factory to capture ref_files in closure
+            def _make_skill_handler(
+                s_name: str, s_uri: str, files: list[dict[str, str]],
+            ):
+                async def handler() -> dict[str, Any]:
+                    return {
+                        "skill": s_name,
+                        "skill_uri": s_uri,
+                        "how_to_use": (
+                            "Use read_resource with a file URI below to load "
+                            "the specific reference you need. Start with "
+                            "SKILL.md for the decision workflow."
+                        ),
+                        "available_files": files,
+                    }
+                return handler
+
+            self.mcp.tool(
+                name=tool_name,
+                description=tool_description,
+                annotations={"readOnlyHint": True},
+            )(_make_skill_handler(skill_name, uri, ref_files))
+
+            self._skill_tool_names.append(tool_name)
+            logger.info(
+                "Registered skill guidance tool %s (%d reference files)",
+                tool_name,
+                len(ref_files),
+            )
+
     # Helper methods required by EnhancedToolsMixin
 
     async def smart_entity_search(

ha_mcp_dev-7.0.0.dev274/src/ha_mcp/tools/best_practice_checker.py

@@ -0,0 +1,392 @@
+"""Reactive best-practice checker for HA automation/script configs.
+
+Stateless payload inspection — returns warnings pointing to skill reference
+files. Zero overhead on clean calls (returns empty list).
+
+When skills are enabled (ENABLE_SKILLS=true), warnings include skill:// URIs
+so the LLM can read the relevant reference file. When skills are disabled,
+callers should pass a fallback prefix (e.g. GitHub URLs) or None to omit
+references entirely.
+
+Anti-patterns sourced from:
+  https://github.com/homeassistant-ai/skills
+  skill://home-assistant-best-practices
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Any
+
+_SKILL_URI_PREFIX = "skill://home-assistant-best-practices/references"
+_GITHUB_URL_PREFIX = (
+    "https://github.com/homeassistant-ai/skills/blob/main"
+    "/skills/home-assistant-best-practices/references"
+)
+_DEFAULT_SKILL_PREFIX = _SKILL_URI_PREFIX
+
+
+def get_skill_prefix() -> str:
+    """Return the appropriate skill prefix based on global settings.
+
+    When skills are enabled (ENABLE_SKILLS=true), returns skill:// URIs.
+    Otherwise falls back to GitHub URLs for the reference files.
+    """
+    from ..config import get_global_settings
+
+    if get_global_settings().enable_skills:
+        return _SKILL_URI_PREFIX
+    return _GITHUB_URL_PREFIX
+
+# ---------------------------------------------------------------------------
+# Regex patterns for template anti-patterns
+# ---------------------------------------------------------------------------
+
+# float/int comparison: | float > 25, | int(0) >= 10, float(x) < 5
+_RE_NUMERIC_CMP = re.compile(
+    r"\|\s*(?:float|int)\s*(?:\([^)]*\)\s*)?[><]=?"
+    r"|(?:float|int)\s*\([^)]*\)\s*[><]=?"
+)
+# is_state() call (not is_state_attr)
+_RE_IS_STATE = re.compile(r"\bis_state\s*\(")
+# now().hour or now().minute
+_RE_NOW_TIME = re.compile(r"\bnow\(\)\s*\.\s*(?:hour|minute)\b")
+# now().weekday() / now().isoweekday() / now().strftime('%A'|'%w')
+_RE_WEEKDAY = re.compile(
+    r"\bnow\(\)\s*\.\s*(?:weekday|isoweekday)\s*\("
+    r"|\bnow\(\)\s*\.\s*strftime\s*\(\s*['\"]%[Aaw]['\"]"
+)
+# sun.sun entity references
+_RE_SUN = re.compile(r"(?:is_state|state_attr|states)\s*\(\s*['\"]sun\.sun['\"]")
+# states('x') in [...] or states('x') in (...)
+_RE_STATE_IN = re.compile(r"states\s*\([^)]+\)\s+in\s+[\[(]")
+# Unsafe direct state access: states.sensor.x.state
+_RE_DIRECT_STATE = re.compile(r"\bstates\.\w+\.\w+\.state\b")
+# Motion entity pattern
+_RE_MOTION = re.compile(r"binary_sensor\.\w*motion", re.IGNORECASE)
+
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+
+def check_automation_config(
+    config: dict[str, Any],
+    *,
+    skill_prefix: str | None = _DEFAULT_SKILL_PREFIX,
+) -> list[str]:
+    """Return best-practice warnings for an automation config.
+
+    Args:
+        config: The automation configuration dict.
+        skill_prefix: Base URI for skill references (e.g.
+            "skill://home-assistant-best-practices/references").
+            Pass None when skills are disabled — warnings still fire
+            but without the "See skill://..." suffix.
+    """
+    if "use_blueprint" in config:
+        return []
+
+    warnings: list[str] = []
+
+    # Condition templates
+    _check_condition_templates(config.get("condition", []), warnings, skill_prefix)
+
+    # Action tree (wait_template + nested conditions)
+    _check_action_tree(config.get("action", []), warnings, skill_prefix)
+
+    # Trigger templates + device_id
+    _check_triggers(config.get("trigger", []), warnings, skill_prefix)
+
+    # Mode vs motion pattern
+    _check_mode_motion(config, warnings, skill_prefix)
+
+    return _dedupe(warnings)
+
+
+def check_script_config(
+    config: dict[str, Any],
+    *,
+    skill_prefix: str | None = _DEFAULT_SKILL_PREFIX,
+) -> list[str]:
+    """Return best-practice warnings for a script config.
+
+    Args:
+        config: The script configuration dict.
+        skill_prefix: Base URI for skill references.
+            Pass None when skills are disabled.
+    """
+    if "use_blueprint" in config:
+        return []
+
+    warnings: list[str] = []
+    _check_action_tree(config.get("sequence", []), warnings, skill_prefix)
+    return _dedupe(warnings)
+
+
+# ---------------------------------------------------------------------------
+# Skill reference helper
+# ---------------------------------------------------------------------------
+
+
+def _ref(skill_prefix: str | None, path: str) -> str:
+    """Return a ' See <URI>' suffix when skills are enabled, empty otherwise."""
+    if skill_prefix:
+        return f" See {skill_prefix}/{path}"
+    return ""
+
+
+# ---------------------------------------------------------------------------
+# Condition template checks
+# ---------------------------------------------------------------------------
+
+
+def _check_condition_templates(
+    conditions: Any, warnings: list[str], skill_prefix: str | None
+) -> None:
+    """Check condition tree for template anti-patterns."""
+    for cond in _as_list(conditions):
+        if isinstance(cond, str) and "{{" in cond:
+            # Shorthand template condition
+            _check_template_string(cond, warnings, skill_prefix)
+        elif isinstance(cond, dict):
+            if cond.get("condition") == "template":
+                vt = cond.get("value_template", "")
+                if isinstance(vt, str):
+                    _check_template_string(vt, warnings, skill_prefix)
+            # Recurse into compound conditions (and/or/not)
+            nested = cond.get("conditions")
+            if nested:
+                _check_condition_templates(nested, warnings, skill_prefix)
+
+
+def _check_template_string(
+    template: str, warnings: list[str], skill_prefix: str | None
+) -> None:
+    """Check a single template string for known anti-patterns."""
+    if _RE_NUMERIC_CMP.search(template):
+        warnings.append(
+            "Condition uses template with float/int comparison — use native "
+            "`numeric_state` condition instead."
+            + _ref(skill_prefix, "automation-patterns.md#native-conditions")
+        )
+    if _RE_SUN.search(template):
+        warnings.append(
+            "Condition uses template referencing `sun.sun` — use native "
+            "`sun` condition instead."
+            + _ref(skill_prefix, "automation-patterns.md#native-conditions")
+        )
+    elif _RE_IS_STATE.search(template):
+        # Only flag if not already flagged as sun pattern
+        warnings.append(
+            "Condition uses template with `is_state()` — use native "
+            "`state` condition instead."
+            + _ref(skill_prefix, "automation-patterns.md#native-conditions")
+        )
+    if _RE_NOW_TIME.search(template):
+        warnings.append(
+            "Condition uses template with `now().hour/minute` — use native "
+            "`time` condition instead."
+            + _ref(skill_prefix, "automation-patterns.md#native-conditions")
+        )
+    if _RE_WEEKDAY.search(template):
+        warnings.append(
+            "Condition uses template for day-of-week check — use native "
+            "`time` condition with `weekday:` list instead."
+            + _ref(skill_prefix, "automation-patterns.md#native-conditions")
+        )
+    if _RE_STATE_IN.search(template):
+        warnings.append(
+            "Condition uses template with `states(...) in [...]` — use native "
+            "`state` condition with `state:` list instead."
+            + _ref(skill_prefix, "automation-patterns.md#native-conditions")
+        )
+    if _RE_DIRECT_STATE.search(template):
+        warnings.append(
+            "Template uses `states.domain.entity.state` direct access which "
+            "errors if entity doesn't exist — use `states('entity_id')` "
+            "function instead."
+            + _ref(skill_prefix, "template-guidelines.md#common-patterns")
+        )
+
+
+# ---------------------------------------------------------------------------
+# Action tree checks
+# ---------------------------------------------------------------------------
+
+
+def _check_action_tree(
+    actions: Any, warnings: list[str], skill_prefix: str | None
+) -> None:
+    """Walk action tree checking for wait_template and nested conditions."""
+    for action in _as_list(actions):
+        if not isinstance(action, dict):
+            continue
+
+        if "wait_template" in action:
+            warnings.append(
+                "Action uses `wait_template` — consider `wait_for_trigger` "
+                "with a state trigger (note: different semantics — "
+                "`wait_for_trigger` waits for a *change*, `wait_template` "
+                "passes immediately if already true)."
+                + _ref(skill_prefix, "automation-patterns.md#wait-actions")
+            )
+
+        # Nested conditions in choose/if/repeat
+        if "choose" in action:
+            for option in _as_list(action["choose"]):
+                if isinstance(option, dict):
+                    _check_condition_templates(
+                        option.get("conditions", []), warnings, skill_prefix
+                    )
+                    _check_action_tree(
+                        option.get("sequence", []), warnings, skill_prefix
+                    )
+
+        if "if" in action:
+            _check_condition_templates(action["if"], warnings, skill_prefix)
+
+        for key in ("then", "else", "default"):
+            nested = action.get(key)
+            if isinstance(nested, list):
+                _check_action_tree(nested, warnings, skill_prefix)
+
+        if "repeat" in action and isinstance(action["repeat"], dict):
+            repeat = action["repeat"]
+            _check_condition_templates(
+                repeat.get("while", []), warnings, skill_prefix
+            )
+            _check_condition_templates(
+                repeat.get("until", []), warnings, skill_prefix
+            )
+            _check_action_tree(
+                repeat.get("sequence", []), warnings, skill_prefix
+            )
+
+
+# ---------------------------------------------------------------------------
+# Trigger checks
+# ---------------------------------------------------------------------------
+
+
+def _check_triggers(
+    triggers: Any, warnings: list[str], skill_prefix: str | None
+) -> None:
+    """Check triggers for device_id and template anti-patterns."""
+    for trigger in _as_list(triggers):
+        if not isinstance(trigger, dict):
+            continue
+
+        platform = trigger.get("platform", trigger.get("trigger", ""))
+
+        # Device trigger → prefer entity_id-based triggers
+        if platform == "device":
+            warnings.append(
+                "Trigger uses `device` platform with `device_id` — prefer "
+                "`state` or `event` trigger with `entity_id` when possible "
+                "(device_id breaks on re-add)."
+                + _ref(skill_prefix, "device-control.md#entity-id-vs-device-id")
+            )
+
+        # Template trigger with detectable native alternative
+        if platform == "template":
+            vt = trigger.get("value_template", "")
+            if isinstance(vt, str):
+                if _RE_NUMERIC_CMP.search(vt):
+                    warnings.append(
+                        "Trigger uses template with float/int comparison — "
+                        "use native `numeric_state` trigger instead."
+                        + _ref(
+                            skill_prefix,
+                            "automation-patterns.md#trigger-types",
+                        )
+                    )
+                if _RE_IS_STATE.search(vt):
+                    warnings.append(
+                        "Trigger uses template with `is_state()` — use "
+                        "native `state` trigger instead."
+                        + _ref(
+                            skill_prefix,
+                            "automation-patterns.md#trigger-types",
+                        )
+                    )
+
+
+# ---------------------------------------------------------------------------
+# Mode + motion check
+# ---------------------------------------------------------------------------
+
+
+def _check_mode_motion(
+    config: dict[str, Any], warnings: list[str], skill_prefix: str | None
+) -> None:
+    """Detect mode:single (default) with motion triggers and delay/wait."""
+    mode = config.get("mode", "single")
+    if mode != "single":
+        return
+
+    triggers = _as_list(config.get("trigger", []))
+    has_motion = any(
+        isinstance(t, dict)
+        and any(
+            isinstance(e, str) and _RE_MOTION.search(e)
+            for e in _as_list(t.get("entity_id", []))
+        )
+        for t in triggers
+    )
+    if not has_motion:
+        return
+
+    if _has_delay_or_wait(config.get("action", [])):
+        warnings.append(
+            "Automation uses motion trigger with delay/wait but "
+            "`mode: single` (default) — consider `mode: restart` so "
+            "re-triggers reset the timer."
+            + _ref(skill_prefix, "automation-patterns.md#automation-modes")
+        )
+
+
+def _has_delay_or_wait(actions: Any) -> bool:
+    """Recursively check if any action uses delay or wait."""
+    for action in _as_list(actions):
+        if not isinstance(action, dict):
+            continue
+        if any(k in action for k in ("delay", "wait_for_trigger", "wait_template")):
+            return True
+        for key in ("then", "else", "default", "sequence"):
+            if key in action and _has_delay_or_wait(action[key]):
+                return True
+        if "choose" in action:
+            for opt in _as_list(action["choose"]):
+                if isinstance(opt, dict) and _has_delay_or_wait(
+                    opt.get("sequence", [])
+                ):
+                    return True
+        if "repeat" in action and isinstance(action["repeat"], dict):
+            if _has_delay_or_wait(action["repeat"].get("sequence", [])):
+                return True
+    return False
+
+
+# ---------------------------------------------------------------------------
+# Utilities
+# ---------------------------------------------------------------------------
+
+
+def _as_list(val: Any) -> list:
+    """Coerce a value to a list."""
+    if isinstance(val, list):
+        return val
+    return [val] if val else []
+
+
+def _dedupe(warnings: list[str]) -> list[str]:
+    """Remove duplicate warnings while preserving order."""
+    seen: set[str] = set()
+    result: list[str] = []
+    for w in warnings:
+        if w not in seen:
+            seen.add(w)
+            result.append(w)
+    return result

{ha_mcp_dev-7.0.0.dev272 → ha_mcp_dev-7.0.0.dev274}/src/ha_mcp/tools/tools_config_automations.py

@@ -16,6 +16,12 @@ from ..errors import (
     create_resource_not_found_error,
     create_validation_error,
 )
+from .best_practice_checker import (
+    check_automation_config as _check_best_practices,
+)
+from .best_practice_checker import (
+    get_skill_prefix as _get_skill_prefix,
+)
 from .helpers import exception_to_structured_error, log_tool_usage, raise_tool_error
 from .util_helpers import (
     coerce_bool_param,
@@ -416,6 +422,7 @@ def register_config_automation_tools(mcp: Any, client: Any, **kwargs: Any) -> No
         - Use ha_eval_template() to test Jinja2 templates before using in automations
         - Use ha_search_entities(domain_filter='automation') to find existing automations
         """
+        bp_warnings: list[str] = []
         try:
             # Parse JSON config if provided as string
             try:
@@ -468,6 +475,13 @@ def register_config_automation_tools(mcp: Any, client: Any, **kwargs: Any) -> No
                     "To create a genuinely new automation, remove the 'id' field from the config.",
                 ))
 
+            # Pre-check for best-practice issues (used for both success
+            # warnings and error enrichment if the API call fails).
+            # Pre-check for best-practice issues.
+            bp_warnings = _check_best_practices(
+                config_dict, skill_prefix=_get_skill_prefix()
+            )
+
             result = await client.upsert_automation_config(config_dict, identifier)
 
             # If the client could not verify the entity was registered, warn but don't hard-fail.
@@ -493,6 +507,9 @@ def register_config_automation_tools(mcp: Any, client: Any, **kwargs: Any) -> No
                 except Exception as e:
                     result["warning"] = f"Automation created but verification failed: {e}"
 
+            if bp_warnings:
+                result["best_practice_warnings"] = bp_warnings
+
             return {
                 "success": True,
                 **result,
@@ -502,16 +519,22 @@ def register_config_automation_tools(mcp: Any, client: Any, **kwargs: Any) -> No
             raise
         except Exception as e:
             logger.error(f"Error upserting automation: {e}")
+            suggestions = [
+                "Check automation configuration format",
+                "Ensure required fields: alias, trigger, action",
+                "Use entity_id format: automation.morning_routine or unique_id",
+                "Use ha_search_entities(domain_filter='automation') to find automations",
+                "Use ha_get_domain_docs('automation') for comprehensive configuration help",
+            ]
+            if bp_warnings:
+                suggestions.append(
+                    "Config had best-practice issues that may be related: "
+                    + "; ".join(bp_warnings)
+                )
             exception_to_structured_error(
                 e,
                 context={"identifier": identifier},
-                suggestions=[
-                    "Check automation configuration format",
-                    "Ensure required fields: alias, trigger, action",
-                    "Use entity_id format: automation.morning_routine or unique_id",
-                    "Use ha_search_entities(domain_filter='automation') to find automations",
-                    "Use ha_get_domain_docs('automation') for comprehensive configuration help",
-                ],
+                suggestions=suggestions,
             )
 
     @mcp.tool(

{ha_mcp_dev-7.0.0.dev272 → ha_mcp_dev-7.0.0.dev274}/src/ha_mcp/tools/tools_config_scripts.py

@@ -12,6 +12,12 @@ from fastmcp.exceptions import ToolError
 from pydantic import Field
 
 from ..errors import ErrorCode, create_error_response
+from .best_practice_checker import (
+    check_script_config as _check_best_practices,
+)
+from .best_practice_checker import (
+    get_skill_prefix as _get_skill_prefix,
+)
 from .helpers import exception_to_structured_error, log_tool_usage, raise_tool_error
 from .util_helpers import (
     coerce_bool_param,
@@ -231,6 +237,7 @@ def register_config_script_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         Note: Scripts use Home Assistant's action syntax. Check the documentation for advanced
         features like conditions, variables, parallel execution, and service call options.
         """
+        bp_warnings: list[str] = []
         try:
             # Parse JSON config if provided as string
             try:
@@ -264,6 +271,11 @@ def register_config_script_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                     context={"script_id": script_id, "required_fields": ["sequence OR use_blueprint"]},
                 ))
 
+            # Pre-check for best-practice issues.
+            bp_warnings = _check_best_practices(
+                config_dict, skill_prefix=_get_skill_prefix()
+            )
+
             result = await client.upsert_script_config(config_dict, script_id)
 
             # Wait for script to be queryable
@@ -277,6 +289,9 @@ def register_config_script_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
                 except Exception as e:
                     result["warning"] = f"Script created but verification failed: {e}"
 
+            if bp_warnings:
+                result["best_practice_warnings"] = bp_warnings
+
             return {
                 "success": True,
                 **result,
@@ -285,17 +300,23 @@ def register_config_script_tools(mcp: Any, client: Any, **kwargs: Any) -> None:
         except ToolError:
             raise
         except Exception as e:
+            suggestions = [
+                "Ensure config includes either 'sequence' field (regular scripts) or 'use_blueprint' field (blueprint-based scripts)",
+                "For blueprint scripts, use ha_get_blueprint(domain='script') to list available blueprints",
+                "Validate sequence actions syntax for regular scripts",
+                "Check entity_ids exist if using service calls",
+                "Use ha_search_entities(domain_filter='script') to find scripts",
+                "Use ha_get_domain_docs('script') for configuration help",
+            ]
+            if bp_warnings:
+                suggestions.append(
+                    "Config had best-practice issues that may be related: "
+                    + "; ".join(bp_warnings)
+                )
             exception_to_structured_error(
                 e,
                 context={"script_id": script_id},
-                suggestions=[
-                    "Ensure config includes either 'sequence' field (regular scripts) or 'use_blueprint' field (blueprint-based scripts)",
-                    "For blueprint scripts, use ha_get_blueprint(domain='script') to list available blueprints",
-                    "Validate sequence actions syntax for regular scripts",
-                    "Check entity_ids exist if using service calls",
-                    "Use ha_search_entities(domain_filter='script') to find scripts",
-                    "Use ha_get_domain_docs('script') for configuration help",
-                ],
+                suggestions=suggestions,
             )
 
     @mcp.tool(

{ha_mcp_dev-7.0.0.dev272 → ha_mcp_dev-7.0.0.dev274/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.0.0.dev272
+Version: 7.0.0.dev274
 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.0.0.dev272 → ha_mcp_dev-7.0.0.dev274}/src/ha_mcp_dev.egg-info/SOURCES.txt

@@ -37,6 +37,7 @@ src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/referenc
 src/ha_mcp/resources/skills-vendor/skills/home-assistant-best-practices/references/template-guidelines.md
 src/ha_mcp/tools/__init__.py
 src/ha_mcp/tools/backup.py
+src/ha_mcp/tools/best_practice_checker.py
 src/ha_mcp/tools/device_control.py
 src/ha_mcp/tools/enhanced.py
 src/ha_mcp/tools/helpers.py