ha-mcp-dev 7.4.1.dev441__tar.gz → 7.4.1.dev443__tar.gz

{ha_mcp_dev-7.4.1.dev441/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.4.1.dev443}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.4.1.dev441
+Version: 7.4.1.dev443
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -254,12 +254,9 @@ An MCP server can create automations, helpers, and dashboards, but it has no opi
 
 ### Bundled Skills (built-in)
 
-Skills from `homeassistant-ai/skills` are bundled and served as [MCP resources](https://modelcontextprotocol.io/docs/concepts/resources) via `skill://` URIs. Any MCP client that supports resources can discover them automatically — no manual installation needed.
+Skills from `homeassistant-ai/skills` are bundled and served as [MCP resources](https://modelcontextprotocol.io/docs/concepts/resources) via `skill://` URIs. Any MCP client that supports resources can discover them automatically — no manual installation needed. For tool-only clients, the same skills are also exposed as `ha_list_resources` / `ha_read_resource` tools. Resources are not auto-injected into context — clients must explicitly request them, so idle context cost is just the metadata listing.
 
-| Setting | Default | Description |
-|---------|---------|-------------|
-| `ENABLE_SKILLS` | `true` | Serve skills as MCP resources. Resources are not auto-injected into context — clients must explicitly request them. |
-| `ENABLE_SKILLS_AS_TOOLS` | `true` | Expose skills and doc resources via `list_resources`/`read_resource` tools. Resource-capable clients can set to `false` to reduce tool count. |
+If you want to hide either tool from the catalog, disable it from the web settings UI like any other tool.
 
 Skills can still be installed manually for clients that prefer local skill files — see the [skills repo](https://github.com/homeassistant-ai/skills) for instructions.
 
@@ -344,6 +341,8 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 - **[@gcormier](https://github.com/gcormier)** — Windows installer improvements: removed unused variable and fixed terminal closing after install.
 - **[@ekobres](https://github.com/ekobres)** — Feature flags for `HAMCP_ENABLE_FILESYSTEM_TOOLS` and `HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION` in the add-on config, with beta tagging in source and docs.
 - **[@w3z315](https://github.com/w3z315)** — Financial support via [GitHub Sponsors](https://github.com/sponsors/julienld). Thank you! ☕
+- **[@griffinmartin](https://github.com/griffinmartin)** — Added OpenCode (by Anomaly) as a selectable AI client in the setup wizard, with both stdio and streamable HTTP support.
+- **[@hhopke](https://github.com/hhopke)** — Fixed addon API calls to route through HA Core ingress proxy instead of direct container connections, fixing `ha_manage_addon` proxy mode on addon installs.
 
 ---
 

{ha_mcp_dev-7.4.1.dev441 → ha_mcp_dev-7.4.1.dev443}/README.md

@@ -225,12 +225,9 @@ An MCP server can create automations, helpers, and dashboards, but it has no opi
 
 ### Bundled Skills (built-in)
 
-Skills from `homeassistant-ai/skills` are bundled and served as [MCP resources](https://modelcontextprotocol.io/docs/concepts/resources) via `skill://` URIs. Any MCP client that supports resources can discover them automatically — no manual installation needed.
+Skills from `homeassistant-ai/skills` are bundled and served as [MCP resources](https://modelcontextprotocol.io/docs/concepts/resources) via `skill://` URIs. Any MCP client that supports resources can discover them automatically — no manual installation needed. For tool-only clients, the same skills are also exposed as `ha_list_resources` / `ha_read_resource` tools. Resources are not auto-injected into context — clients must explicitly request them, so idle context cost is just the metadata listing.
 
-| Setting | Default | Description |
-|---------|---------|-------------|
-| `ENABLE_SKILLS` | `true` | Serve skills as MCP resources. Resources are not auto-injected into context — clients must explicitly request them. |
-| `ENABLE_SKILLS_AS_TOOLS` | `true` | Expose skills and doc resources via `list_resources`/`read_resource` tools. Resource-capable clients can set to `false` to reduce tool count. |
+If you want to hide either tool from the catalog, disable it from the web settings UI like any other tool.
 
 Skills can still be installed manually for clients that prefer local skill files — see the [skills repo](https://github.com/homeassistant-ai/skills) for instructions.
 
@@ -315,6 +312,8 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 - **[@gcormier](https://github.com/gcormier)** — Windows installer improvements: removed unused variable and fixed terminal closing after install.
 - **[@ekobres](https://github.com/ekobres)** — Feature flags for `HAMCP_ENABLE_FILESYSTEM_TOOLS` and `HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION` in the add-on config, with beta tagging in source and docs.
 - **[@w3z315](https://github.com/w3z315)** — Financial support via [GitHub Sponsors](https://github.com/sponsors/julienld). Thank you! ☕
+- **[@griffinmartin](https://github.com/griffinmartin)** — Added OpenCode (by Anomaly) as a selectable AI client in the setup wizard, with both stdio and streamable HTTP support.
+- **[@hhopke](https://github.com/hhopke)** — Fixed addon API calls to route through HA Core ingress proxy instead of direct container connections, fixing `ha_manage_addon` proxy mode on addon installs.
 
 ---
 

{ha_mcp_dev-7.4.1.dev441 → ha_mcp_dev-7.4.1.dev443}/pyproject.toml

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

@@ -9,7 +9,7 @@ import os
 from pathlib import Path
 
 from dotenv import load_dotenv
-from pydantic import Field, field_validator, model_validator
+from pydantic import Field, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 from ha_mcp._version import get_version
@@ -92,17 +92,6 @@ class Settings(BaseSettings):
         True, alias="ENABLE_DASHBOARD_PARTIAL_TOOLS"
     )
 
-    # Skills configuration
-    # Serve bundled HA best-practice skills as MCP resources (skill:// URIs).
-    # Resources are not auto-injected — clients must explicitly request them.
-    enable_skills: bool = Field(True, alias="ENABLE_SKILLS")
-
-    # Expose skills and doc resources as tools (list_resources/read_resource)
-    # for clients that don't support MCP resources natively.
-    # Defaults to True so all clients can access documentation and skills.
-    # Resource-capable clients can set to False to reduce tool count.
-    enable_skills_as_tools: bool = Field(True, alias="ENABLE_SKILLS_AS_TOOLS")
-
     # Tool search transform — replaces the full tool catalog with a unified
     # BM25 search tool and categorized call proxies (read/write/delete).
     # Dramatically reduces idle context token usage for LLMs.
@@ -124,18 +113,6 @@ class Settings(BaseSettings):
     # supervisor UI rejects out-of-range values before they reach env vars.
     tool_search_max_results: int = Field(5, ge=2, le=10, alias="TOOL_SEARCH_MAX_RESULTS")
 
-    @model_validator(mode="after")
-    def _skills_dependency(self) -> "Settings":
-        """Auto-enable skills (resources) when skills-as-tools is on.
-
-        skills_as_tools wraps ResourcesAsTools which requires skills to be
-        registered as MCP resources first. Without this, enabling
-        skills_as_tools alone would produce empty list_resources results.
-        """
-        if self.enable_skills_as_tools and not self.enable_skills:
-            self.enable_skills = True
-        return self
-
     @property
     def env_file_name(self) -> str:
         """Get the current environment file name."""

{ha_mcp_dev-7.4.1.dev441 → ha_mcp_dev-7.4.1.dev443}/src/ha_mcp/server.py

@@ -16,6 +16,7 @@ from typing import TYPE_CHECKING, Any, ClassVar, cast
 
 import yaml  # type: ignore[import-untyped]
 from fastmcp import FastMCP
+from fastmcp.server.transforms import ResourcesAsTools
 from mcp.types import Icon
 
 from .config import _PACKAGE_VERSION, get_global_settings
@@ -23,11 +24,84 @@ from .tools.enhanced import EnhancedToolsMixin
 from .transforms import DEFAULT_PINNED_TOOLS
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
+
+    from fastmcp.server.transforms import GetToolNext
+    from fastmcp.tools.base import Tool
+    from fastmcp.utilities.versions import VersionSpec
+
     from .client.rest_client import HomeAssistantClient
     from .tools.registry import ToolsRegistry
 
 logger = logging.getLogger(__name__)
 
+
+class HaResourcesAsTools(ResourcesAsTools):
+    """ResourcesAsTools renamed to follow ha-mcp's ha_<verb>_<noun> convention.
+
+    FastMCP's ResourcesAsTools transform hardcodes ``list_resources`` and
+    ``read_resource``. This subclass renames them to ``ha_list_resources``
+    and ``ha_read_resource`` so they behave like every other tool in the
+    catalog (consistent prefix, discoverable in the web settings UI).
+
+    Upgrade fragility: depends on FastMCP's ``_make_list_resources_tool`` /
+    ``_make_read_resource_tool`` private factories and on the names
+    ``list_resources`` / ``read_resource`` produced by them. A FastMCP
+    upgrade that renames either factory or either tool name will require
+    a matching update here. ``list_tools`` logs a warning if the rename
+    fails to match exactly two tools so the regression is loud at boot.
+    """
+
+    LIST_TOOL_NAME = "ha_list_resources"
+    READ_TOOL_NAME = "ha_read_resource"
+    _RENAMES: ClassVar[dict[str, str]] = {
+        "list_resources": LIST_TOOL_NAME,
+        "read_resource": READ_TOOL_NAME,
+    }
+
+    async def list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        # Scan the entire result rather than slicing the tail so a future
+        # FastMCP change that reorders or expands the appended tool set
+        # surfaces as a logged warning instead of silently leaking the
+        # unprefixed names into the catalog.
+        result = list(await super().list_tools(tools))
+        renamed: list[Tool] = []
+        matches = 0
+        for tool in result:
+            new_name = self._RENAMES.get(tool.name)
+            if new_name is None:
+                renamed.append(tool)
+                continue
+            renamed.append(tool.model_copy(update={"name": new_name}))
+            matches += 1
+        if matches != len(self._RENAMES):
+            logger.warning(
+                "HaResourcesAsTools: expected to rename %d tools (%s) but "
+                "matched %d in the upstream tool list — fastmcp's "
+                "ResourcesAsTools contract may have changed",
+                len(self._RENAMES),
+                ", ".join(self._RENAMES),
+                matches,
+            )
+        return renamed
+
+    async def get_tool(
+        self,
+        name: str,
+        call_next: GetToolNext,
+        *,
+        version: VersionSpec | None = None,
+    ) -> Tool | None:
+        if name == self.LIST_TOOL_NAME:
+            return self._make_list_resources_tool().model_copy(
+                update={"name": self.LIST_TOOL_NAME}
+            )
+        if name == self.READ_TOOL_NAME:
+            return self._make_read_resource_tool().model_copy(
+                update={"name": self.READ_TOOL_NAME}
+            )
+        return await call_next(name, version=version)
+
 # Server icon configuration using GitHub-hosted images
 # These icons are bundled in packaging/mcpb/ and also available via GitHub raw URLs
 SERVER_ICONS = [
@@ -179,12 +253,9 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
         is authored for LLM consumption and should not be parsed or
         restructured by code.
 
-        Returns None when skills are disabled, leaving instructions unchanged
-        from the default (None).
+        Returns None when no skills directory or no parseable skills are
+        present, leaving instructions unchanged from the default (None).
         """
-        if not self.settings.enable_skills:
-            return None
-
         skills_dir = self._get_skills_dir()
         if not skills_dir:
             return None
@@ -208,22 +279,15 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
         if not skill_blocks:
             return None
 
-        # Build the access method instruction based on config
-        if self.settings.enable_skills_as_tools:
-            access_method = (
-                "Read the skill via MCP resources (resources/read with the "
-                "skill:// URI) — if you can read these instructions, you "
-                "should be able to access resources as well. If for any "
-                "reason you cannot access MCP resources, use the "
-                "list_resources and read_resource tools as a fallback. "
-                "If you can access resources normally, do not waste "
-                "time or tokens on those tools."
-            )
-        else:
-            access_method = (
-                "Read the skill via MCP resources (resources/read with the "
-                "skill:// URI)."
-            )
+        access_method = (
+            "Read the skill via MCP resources (resources/read with the "
+            "skill:// URI) — if you can read these instructions, you "
+            "should be able to access resources as well. If for any "
+            "reason you cannot access MCP resources, use the "
+            "ha_list_resources and ha_read_resource tools as a fallback. "
+            "If you can access resources normally, do not waste "
+            "time or tokens on those tools."
+        )
 
         header = (
             "IMPORTANT: This server provides best-practice skills that MUST "
@@ -517,25 +581,27 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
         pinned = list(self._PINNED_TOOLS)
         pinned.extend(self._user_pinned_tools)
 
-        # Pin ResourcesAsTools and skill guidance tools if skills-as-tools is enabled
-        if self.settings.enable_skills_as_tools:
-            pinned.extend(["list_resources", "read_resource"])
-            # Forward-compatible: pin skill guidance tools registered by #732
-            pinned.extend(getattr(self, "_skill_tool_names", []))
-
-        # When skills-as-tools is enabled, the client likely doesn't support
-        # resources or server instructions — add skills hint to the search
-        # tool description (the one place the LLM is guaranteed to see).
-        description = self._SEARCH_TOOL_DESCRIPTION
-        if self.settings.enable_skills_as_tools:
-            description += (
-                "\n\nThis server also provides best-practice skills via "
-                "skill:// resources. If your client supports MCP resources, "
-                "prefer reading them directly. Otherwise, call "
-                "list_resources and read_resource (directly, no proxy "
-                "needed) to access the relevant SKILL.md before creating "
-                "automations or configuring devices."
-            )
+        # Pin the skills-as-tools transform pair and the per-skill guidance
+        # tools so they remain visible when search-based discovery is on.
+        # The settings UI's mcp.disable() flow runs after these transforms
+        # are appended, so a per-tool disable still wins over this pin.
+        pinned.extend(
+            [HaResourcesAsTools.LIST_TOOL_NAME, HaResourcesAsTools.READ_TOOL_NAME]
+        )
+        pinned.extend(getattr(self, "_skill_tool_names", []))
+
+        # The client may not support resources or server instructions — add
+        # skills hint to the search tool description (the one place the LLM
+        # is guaranteed to see).
+        description = self._SEARCH_TOOL_DESCRIPTION + (
+            "\n\nThis server also provides best-practice skills via "
+            "skill:// resources. If your client supports MCP resources, "
+            f"prefer reading them directly. Otherwise, call "
+            f"{HaResourcesAsTools.LIST_TOOL_NAME} and "
+            f"{HaResourcesAsTools.READ_TOOL_NAME} (directly, no proxy "
+            "needed) to access the relevant SKILL.md before creating "
+            "automations or configuring devices."
+        )
 
         try:
             self.mcp.add_transform(
@@ -556,14 +622,29 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
     def _register_skills(self) -> None:
         """Register bundled HA best-practice skills as MCP resources.
 
-        Uses FastMCP's SkillsDirectoryProvider to serve skill files via skill:// URIs.
-        Optionally exposes skills as tools (list_resources/read_resource) for clients
-        that don't support MCP resources natively.
-
-        Controlled by ENABLE_SKILLS and ENABLE_SKILLS_AS_TOOLS settings.
+        Uses FastMCP's SkillsDirectoryProvider to serve skill files via
+        skill:// URIs and exposes them as tools (ha_list_resources /
+        ha_read_resource) for clients that don't support MCP resources
+        natively. Per-tool visibility is managed via the web settings UI;
+        users who want either tool off can disable it there.
+
+        Each phase tracks success in ``status`` so the final summary log
+        line tells operators at a glance whether the skill system is
+        healthy, partially degraded, or fully unavailable. Without that
+        summary, three independent ``logger.exception`` calls leave
+        operators reconstructing state from scattered log lines.
+
+        Failure modes degrade unevenly across clients: if Phase 3
+        (transform) fails, resource-capable clients still see skills,
+        but tool-only clients (claude.ai etc.) lose ha_list_resources
+        and ha_read_resource from their catalog with no protocol-level
+        error — only the warning summary signals it.
         """
-        if not self.settings.enable_skills:
-            return
+        status: dict[str, str | int] = {
+            "provider": "skipped",
+            "transform": "skipped",
+            "guidance_tools": 0,
+        }
 
         # Phase 1: Import SkillsDirectoryProvider
         try:
@@ -572,6 +653,7 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
             logger.warning(
                 "SkillsDirectoryProvider not available in fastmcp, skipping skills"
             )
+            self._log_skill_registration_summary(status)
             return
 
         # Phase 2: Register skills as MCP resources
@@ -582,6 +664,7 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
                     "Skills directory not found at %s, skipping skill registration",
                     Path(__file__).parent / "resources" / "skills-vendor" / "skills",
                 )
+                self._log_skill_registration_summary(status)
                 return
 
             self.mcp.add_provider(
@@ -590,36 +673,61 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
                 )
             )
             logger.info("Registered bundled skills as MCP resources")
+            status["provider"] = "ok"
         except Exception:
             logger.exception("Failed to register skills as resources")
+            status["provider"] = "failed"
+            self._log_skill_registration_summary(status)
             return
 
-        # Phase 3: Optionally expose skills as tools
-        if not self.settings.enable_skills_as_tools:
-            return
-
+        # Phase 3: Expose skills as tools so clients without resource
+        # support can still reach the documentation.
         try:
-            from fastmcp.server.transforms import ResourcesAsTools
-        except ImportError:
-            logger.warning(
-                "ResourcesAsTools not available in fastmcp, "
-                "skills registered as resources but not exposed as tools"
+            self.mcp.add_transform(HaResourcesAsTools(self.mcp))
+            logger.info(
+                "Skills also exposed as tools (ha_list_resources / ha_read_resource)"
             )
-            return
-
-        try:
-            self.mcp.add_transform(ResourcesAsTools(self.mcp))
-            logger.info("Skills also exposed as tools (ResourcesAsTools)")
+            status["transform"] = "ok"
         except Exception:
             logger.exception(
                 "Failed to expose skills as tools (resources still available)"
             )
+            status["transform"] = "failed"
 
         # 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)
+        status["guidance_tools"] = len(self._skill_tool_names)
+
+        self._log_skill_registration_summary(status)
+
+    @staticmethod
+    def _log_skill_registration_summary(status: dict[str, str | int]) -> None:
+        """Emit one-line summary of skill registration outcome.
+
+        ``info`` when both provider and transform succeeded *and* at least
+        one guidance tool registered; ``warning`` otherwise. The
+        guidance>0 gate catches the "shipped but exposes nothing" case
+        (skills directory exists but is empty, or every SKILL.md fails to
+        parse) — both prior phases succeed yet no skill is actually
+        reachable. This is the line operators should grep for when a
+        user reports missing skill features.
+        """
+        provider = status.get("provider")
+        transform = status.get("transform")
+        raw_guidance = status.get("guidance_tools", 0)
+        guidance = raw_guidance if isinstance(raw_guidance, int) else 0
+
+        message = (
+            "Skill system summary: provider=%s, transform=%s, guidance_tools=%d"
+        )
+        args = (provider, transform, guidance)
+        if provider == "ok" and transform == "ok" and guidance > 0:
+            logger.info(message, *args)
+        else:
+            logger.warning(message, *args)
 
     def _register_skill_guidance_tools(self, skills_dir: Path) -> None:
         """Register a lightweight guidance tool per skill.
@@ -628,7 +736,9 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
         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.
+        actual content is loaded on demand via the resources/read MCP method
+        (or the ha_read_resource fallback tool when the client lacks resource
+        support).
         """
         try:
             entries = sorted(skills_dir.iterdir())
@@ -653,7 +763,8 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
             tool_description = (
                 f"CALL THIS FIRST before performing matching actions. "
                 f"{description}\n\n"
-                f"Returns available reference files. Use read_resource with "
+                f"Returns available reference files. Read each file via "
+                f"resources/read (or ha_read_resource as a fallback) using "
                 f"the file URI to load specific guides as needed."
             )
 
@@ -670,9 +781,11 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
                         "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."
+                            "Read each file via resources/read (or "
+                            "ha_read_resource as a fallback) with a file "
+                            "URI below to load the specific reference you "
+                            "need. Start with SKILL.md for the decision "
+                            "workflow."
                         ),
                         "available_files": files,
                     }

{ha_mcp_dev-7.4.1.dev441 → ha_mcp_dev-7.4.1.dev443}/src/ha_mcp/settings_ui.py

@@ -13,7 +13,7 @@ import json
 import logging
 import os
 from pathlib import Path
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, NotRequired, TypedDict
 
 import httpx
 from starlette.requests import Request
@@ -30,6 +30,26 @@ if TYPE_CHECKING:
     from .config import Settings
     from .server import HomeAssistantSmartMCPServer
 
+
+class ToolStub(TypedDict):
+    """Metadata advertised in the settings UI for a tool that isn't visible
+    in ``local_provider._list_tools()``.
+
+    Two reasons a tool needs a stub: it's added by a FastMCP transform at
+    runtime (``TRANSFORM_GENERATED_TOOLS``), or it's feature-gated and
+    only registers when a setting is on (``FEATURE_GATED_TOOLS``). The
+    consumer (`_get_tool_metadata`) renders the same shape for both;
+    ``disabled_by`` is the only field that differs and signals UI
+    placement of the "Beta — set X" hint.
+    """
+
+    title: str
+    primary_tag: str
+    description: str
+    readOnlyHint: NotRequired[bool]
+    destructiveHint: NotRequired[bool]
+    disabled_by: NotRequired[str]
+
 _VALID_STATES = frozenset({"enabled", "disabled", "pinned"})
 
 logger = logging.getLogger(__name__)
@@ -48,6 +68,39 @@ MANDATORY_TOOLS: set[str] = {
     "ha_report_issue",
 }
 
+# Tools created by FastMCP transforms (not registered through
+# local_provider). The ``ResourcesAsTools`` transform — subclassed in
+# server.py as ``HaResourcesAsTools`` — appends ``ha_list_resources`` and
+# ``ha_read_resource`` at runtime, so they never show up in
+# ``local_provider._list_tools()``. Inject stub metadata so the UI can
+# render them and ``mcp.disable()`` can hide them from the catalog.
+#
+# Keys MUST match ``HaResourcesAsTools.LIST_TOOL_NAME`` / ``READ_TOOL_NAME``;
+# server.py is not imported here to avoid a top-level cycle, but the
+# ``test_transform_generated_tool_names_match_class_constants`` unit test
+# fails fast if either side drifts.
+TRANSFORM_GENERATED_TOOLS: dict[str, ToolStub] = {
+    "ha_list_resources": {
+        "title": "List Resources",
+        "primary_tag": "System",
+        "description": (
+            "List bundled skill files and other MCP resources exposed via "
+            "skill:// URIs. Fallback for clients that do not support MCP "
+            "resources natively."
+        ),
+        "readOnlyHint": True,
+    },
+    "ha_read_resource": {
+        "title": "Read Resource",
+        "primary_tag": "System",
+        "description": (
+            "Read a skill or resource by URI. Fallback for clients that do "
+            "not support MCP resources natively."
+        ),
+        "readOnlyHint": True,
+    },
+}
+
 # Tools that exist in the codebase but are only registered when a
 # corresponding feature flag/env var is set. When the flag is off, these
 # won't appear in local_provider._list_tools(), so we inject stub entries
@@ -55,48 +108,48 @@ MANDATORY_TOOLS: set[str] = {
 # it. Keep this dict in sync with the ``"beta"`` tag added to each tool's
 # source file (tools_yaml_config.py, tools_filesystem.py, tools_mcp_component.py)
 # — a future rename or removal needs to land in both places.
-FEATURE_GATED_TOOLS: dict[str, dict[str, str]] = {
+FEATURE_GATED_TOOLS: dict[str, ToolStub] = {
     "ha_config_set_yaml": {
         "title": "Set YAML Config",
         "primary_tag": "System",
         "description": "Add, replace, or remove top-level keys in configuration.yaml or package files.",
         "disabled_by": "enable_yaml_config_editing",
-        "destructiveHint": "true",
+        "destructiveHint": True,
     },
     "ha_list_files": {
         "title": "List Files",
         "primary_tag": "Files",
         "description": "List files in a directory within the Home Assistant config.",
         "disabled_by": "enable_filesystem_tools",
-        "readOnlyHint": "true",
+        "readOnlyHint": True,
     },
     "ha_read_file": {
         "title": "Read File",
         "primary_tag": "Files",
         "description": "Read a file from the Home Assistant config directory.",
         "disabled_by": "enable_filesystem_tools",
-        "readOnlyHint": "true",
+        "readOnlyHint": True,
     },
     "ha_write_file": {
         "title": "Write File",
         "primary_tag": "Files",
         "description": "Write a file to allowed directories in the Home Assistant config.",
         "disabled_by": "enable_filesystem_tools",
-        "destructiveHint": "true",
+        "destructiveHint": True,
     },
     "ha_delete_file": {
         "title": "Delete File",
         "primary_tag": "Files",
         "description": "Delete a file from allowed directories.",
         "disabled_by": "enable_filesystem_tools",
-        "destructiveHint": "true",
+        "destructiveHint": True,
     },
     "ha_install_mcp_tools": {
         "title": "Install MCP Tools Component",
         "primary_tag": "Utilities",
         "description": "Install the ha_mcp_tools custom component via HACS.",
         "disabled_by": "enable_custom_component_integration",
-        "destructiveHint": "true",
+        "destructiveHint": True,
     },
 }
 
@@ -179,6 +232,35 @@ def save_tool_config(config: dict[str, Any]) -> bool:
     return True
 
 
+def _render_stub(name: str, meta: ToolStub) -> dict[str, Any]:
+    """Render a ToolStub as the dict shape ``_get_tool_metadata`` returns.
+
+    Both transform-generated and feature-gated stubs share the same UI
+    representation; the only meaningful difference is whether
+    ``disabled_by`` carries the safety-toggle name (which the JS
+    template renders as a "Beta — set X" hint). Annotations come
+    through as bools and are dropped from the final dict when False
+    so the JSON payload stays small.
+    """
+    annotations: dict[str, bool] = {}
+    if meta.get("readOnlyHint"):
+        annotations["readOnlyHint"] = True
+    if meta.get("destructiveHint"):
+        annotations["destructiveHint"] = True
+
+    rendered: dict[str, Any] = {
+        "name": name,
+        "title": meta["title"],
+        "description": meta["description"],
+        "tags": [meta["primary_tag"]],
+        "primary_tag": meta["primary_tag"],
+        "annotations": annotations,
+    }
+    if "disabled_by" in meta:
+        rendered["disabled_by"] = meta["disabled_by"]
+    return rendered
+
+
 async def _get_tool_metadata(server: HomeAssistantSmartMCPServer) -> list[dict[str, Any]]:
     """Extract metadata for all registered tools from the server.
 
@@ -218,25 +300,21 @@ async def _get_tool_metadata(server: HomeAssistantSmartMCPServer) -> list[dict[s
             "annotations": annotations,
         })
 
-    # Inject stub entries for feature-gated tools that aren't registered
     registered_names = {t["name"] for t in tools}
+
+    # Inject stub entries for tools generated by FastMCP transforms — these
+    # never reach local_provider so they have to be advertised explicitly.
+    for name, transform_meta in TRANSFORM_GENERATED_TOOLS.items():
+        if name in registered_names:
+            continue
+        tools.append(_render_stub(name, transform_meta))
+        registered_names.add(name)
+
+    # Inject stub entries for feature-gated tools that aren't registered
     for name, meta in FEATURE_GATED_TOOLS.items():
         if name in registered_names:
             continue
-        stub_annotations: dict[str, bool] = {}
-        if meta.get("readOnlyHint") == "true":
-            stub_annotations["readOnlyHint"] = True
-        if meta.get("destructiveHint") == "true":
-            stub_annotations["destructiveHint"] = True
-        tools.append({
-            "name": name,
-            "title": meta["title"],
-            "description": meta["description"],
-            "tags": [meta["primary_tag"]],
-            "primary_tag": meta["primary_tag"],
-            "annotations": stub_annotations,
-            "disabled_by": meta["disabled_by"],
-        })
+        tools.append(_render_stub(name, meta))
 
     tools.sort(key=lambda t: (t["primary_tag"], t["name"]))
     return tools
@@ -380,7 +458,7 @@ _SETTINGS_HTML = """\
   <span id="status" class="status">Loading...</span>
 </div>
 <div class="readonly-notice">
-  Safety toggles (Enable Skills, Tool Search, YAML Config Editing) are managed in the
+  Safety toggles (Tool Search, YAML Config Editing) are managed in the
   add-on configuration page and require a restart to change.
 </div>
 <div class="pin-notice show" id="pinNotice">

{ha_mcp_dev-7.4.1.dev441 → ha_mcp_dev-7.4.1.dev443}/src/ha_mcp/tools/best_practice_checker.py

@@ -3,10 +3,10 @@
 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.
+Warnings include skill:// URIs so the LLM can read the relevant reference
+file via the bundled SkillsDirectoryProvider. The ``skill_prefix`` kwarg
+lets callers pass any URL prefix (e.g., a GitHub mirror) when skill://
+isn't reachable, or ``None`` to omit references entirely.
 
 Anti-patterns sourced from:
   https://github.com/homeassistant-ai/skills
@@ -19,25 +19,8 @@ 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
 # ---------------------------------------------------------------------------

{ha_mcp_dev-7.4.1.dev441 → ha_mcp_dev-7.4.1.dev443}/src/ha_mcp/tools/tools_config_automations.py

@@ -28,9 +28,6 @@ from ..utils.python_sandbox import (
 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,
@@ -575,9 +572,7 @@ class AutomationConfigTools:
                 # Normalize and validate the transformed config
                 transformed_config = _normalize_automation_config(transformed_config)
                 self._validate_required_fields(transformed_config, identifier)
-                bp_warnings = _check_best_practices(
-                    transformed_config, skill_prefix=_get_skill_prefix()
-                )
+                bp_warnings = _check_best_practices(transformed_config)
 
                 # Save transformed config
                 result = await self._client.upsert_automation_config(
@@ -642,9 +637,7 @@ class AutomationConfigTools:
             self._validate_required_fields(config_dict, identifier)
 
             # Pre-check for best-practice issues.
-            bp_warnings = _check_best_practices(
-                config_dict, skill_prefix=_get_skill_prefix()
-            )
+            bp_warnings = _check_best_practices(config_dict)
 
             # Cross-check literal service and entity references against
             # the live registries. Soft warnings only — the write still

{ha_mcp_dev-7.4.1.dev441 → ha_mcp_dev-7.4.1.dev443}/src/ha_mcp/tools/tools_config_scripts.py

@@ -22,9 +22,6 @@ from ..utils.python_sandbox import (
 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,
@@ -476,9 +473,7 @@ class ConfigScriptTools:
                             context={"action": "python_transform", "script_id": script_id},
                         )
                     )
-                bp_warnings = _check_best_practices(
-                    transformed_config, skill_prefix=_get_skill_prefix()
-                )
+                bp_warnings = _check_best_practices(transformed_config)
 
                 # Save transformed config
                 result = await self._client.upsert_script_config(
@@ -524,9 +519,7 @@ class ConfigScriptTools:
                 await self._fetch_and_verify_hash(script_id, config_hash, "set")
 
             # Pre-check for best-practice issues.
-            bp_warnings = _check_best_practices(
-                config_dict, skill_prefix=_get_skill_prefix()
-            )
+            bp_warnings = _check_best_practices(config_dict)
 
             # Cross-check literal service and entity references against
             # the live registries. Soft warnings only — the write still

{ha_mcp_dev-7.4.1.dev441 → ha_mcp_dev-7.4.1.dev443/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.4.1.dev441
+Version: 7.4.1.dev443
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -254,12 +254,9 @@ An MCP server can create automations, helpers, and dashboards, but it has no opi
 
 ### Bundled Skills (built-in)
 
-Skills from `homeassistant-ai/skills` are bundled and served as [MCP resources](https://modelcontextprotocol.io/docs/concepts/resources) via `skill://` URIs. Any MCP client that supports resources can discover them automatically — no manual installation needed.
+Skills from `homeassistant-ai/skills` are bundled and served as [MCP resources](https://modelcontextprotocol.io/docs/concepts/resources) via `skill://` URIs. Any MCP client that supports resources can discover them automatically — no manual installation needed. For tool-only clients, the same skills are also exposed as `ha_list_resources` / `ha_read_resource` tools. Resources are not auto-injected into context — clients must explicitly request them, so idle context cost is just the metadata listing.
 
-| Setting | Default | Description |
-|---------|---------|-------------|
-| `ENABLE_SKILLS` | `true` | Serve skills as MCP resources. Resources are not auto-injected into context — clients must explicitly request them. |
-| `ENABLE_SKILLS_AS_TOOLS` | `true` | Expose skills and doc resources via `list_resources`/`read_resource` tools. Resource-capable clients can set to `false` to reduce tool count. |
+If you want to hide either tool from the catalog, disable it from the web settings UI like any other tool.
 
 Skills can still be installed manually for clients that prefer local skill files — see the [skills repo](https://github.com/homeassistant-ai/skills) for instructions.
 
@@ -344,6 +341,8 @@ This project is licensed under the MIT License - see the [LICENSE](LICENSE) file
 - **[@gcormier](https://github.com/gcormier)** — Windows installer improvements: removed unused variable and fixed terminal closing after install.
 - **[@ekobres](https://github.com/ekobres)** — Feature flags for `HAMCP_ENABLE_FILESYSTEM_TOOLS` and `HAMCP_ENABLE_CUSTOM_COMPONENT_INTEGRATION` in the add-on config, with beta tagging in source and docs.
 - **[@w3z315](https://github.com/w3z315)** — Financial support via [GitHub Sponsors](https://github.com/sponsors/julienld). Thank you! ☕
+- **[@griffinmartin](https://github.com/griffinmartin)** — Added OpenCode (by Anomaly) as a selectable AI client in the setup wizard, with both stdio and streamable HTTP support.
+- **[@hhopke](https://github.com/hhopke)** — Fixed addon API calls to route through HA Core ingress proxy instead of direct container connections, fixing `ha_manage_addon` proxy mode on addon installs.
 
 ---