ha-mcp-dev 7.12.3.dev1863__tar.gz → 7.12.3.dev1865__tar.gz

{ha_mcp_dev-7.12.3.dev1863/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.12.3.dev1865}/PKG-INFO

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

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "7.12.3.dev1863"
+version = "7.12.3.dev1865"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 # Upper bound widened to <3.15 so the package installs on Home Assistant's
@@ -103,6 +103,9 @@ module = [
     "awesomeversion",
     "yarl",
     "voluptuous",
+    # Ships with HA core at runtime (helpers.llm schema conversion, #1745);
+    # not installed in this dev environment.
+    "voluptuous_openapi",
     "jsonschema",
     "requests",
     "requests.*",
@@ -274,6 +277,10 @@ dev = [
     # Real voluptuous for the config-flow tests (the component's
     # config_flow imports it; HA provides it at runtime, tests need it here).
     "voluptuous>=0.15.2",
+    # Real voluptuous-openapi for the embedded e2e LLM-API test: it converts
+    # the REAL tool-schema catalog exactly like llm_api.py does at runtime
+    # (HA core provides it at runtime; unit tests stub it).
+    "voluptuous-openapi>=0.4.1",
     "pytest-xdist>=3.8.0",
     "requests>=2.25.0",
     "lefthook>=1.10.0",

ha_mcp_dev-7.12.3.dev1865/src/ha_mcp/llm_exposure.py

@@ -0,0 +1,214 @@
+"""Per-tool exposure control for the HA conversation-agent LLM API (#1745).
+
+The ``ha_mcp_tools`` custom component registers this server's toolset as a
+Home Assistant LLM API so conversation agents (and through them Assist chat
+and voice) can drive the tools. Which tools that surface offers is a separate
+axis from the global enable/disable in the settings UI:
+
+* a tool **disabled** in the settings UI is gone for every client — FastMCP
+  removes it from ``tools/list`` and rejects ``tools/call`` by name;
+* a tool **hidden from the LLM API** (this module) stays fully available to
+  regular MCP clients (claude.ai, Claude Code, ...) and is only invisible to
+  conversation agents — in both the full-catalog and tool-search exposure
+  modes of the component.
+
+The single source of truth travels **in-band**: :class:`LlmExposureMiddleware`
+stamps every ``tools/list`` entry with
+``_meta.ha_mcp = {"llm_api_exposed": bool, "pinned": bool}`` so the component
+(one more loopback MCP client) filters on data that can never drift from the
+server's settings, with zero extra round-trips. Stamping re-reads the
+persisted settings behind a short coalescing cache (2s TTL), so settings-UI
+changes apply on the agent's next conversation turn without a restart.
+
+Defaults are deny-by-default for the risky sets (owner decision, #1745):
+beta-tagged tools, developer-mode tools, and the restart/reload/backup
+family start hidden from conversation agents until a user explicitly enables
+them in the settings UI. Everything else starts exposed — selecting the LLM
+API on an agent is itself an explicit opt-in.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Mapping, Sequence
+from typing import TYPE_CHECKING, Any
+
+from fastmcp.server.middleware import Middleware
+
+if TYPE_CHECKING:
+    from fastmcp.server.middleware import CallNext, MiddlewareContext
+    from fastmcp.tools import Tool
+    from mcp import types as mt
+
+logger = logging.getLogger(__name__)
+
+# Key under tools/list ``_meta`` (and the key inside it) the custom component
+# filters on. The component treats an ABSENT stamp as "server too old for
+# per-tool exposure" and falls back to its own conservative deny-list.
+META_NAMESPACE = "ha_mcp"
+META_EXPOSED_KEY = "llm_api_exposed"
+META_PINNED_KEY = "pinned"
+
+# Key in tool_config.json holding the user's per-tool overrides
+# ({tool_name: bool}). Sparse on purpose: only tools the user explicitly
+# flipped are stored, so tools added by future releases keep getting their
+# DEFAULT (e.g. a new beta tool defaults hidden) instead of freezing the
+# catalog shape at save time.
+LLM_API_CONFIG_KEY = "llm_api"
+
+# Tools hidden from conversation agents by default regardless of tags:
+# operational hazards where an agent mistake is expensive (restart loops,
+# config reloads mid-edit, backup churn). Users can still enable each in the
+# settings UI.
+LLM_API_DEFAULT_OFF_TOOLS: frozenset[str] = frozenset(
+    {
+        "ha_restart",
+        "ha_reload_core",
+        "ha_manage_backup",
+    }
+)
+
+# Developer-mode tools are hidden by default via this name prefix (covers
+# ha_dev_manage_settings / ha_dev_manage_server and any future ha_dev_*).
+LLM_API_DEV_TOOL_PREFIX = "ha_dev_"
+
+# The beta gate is tag-based so future beta tools default to hidden without
+# touching this module.
+_BETA_TAG = "beta"
+
+# How long a live settings read is reused before re-reading the config file.
+# tools/list fires once per conversation turn per agent; the TTL only matters
+# when several agents list within the same moment.
+_OVERRIDES_TTL_SECONDS = 2.0
+
+
+def default_llm_api_exposed(name: str, tags: Sequence[str] | set[str]) -> bool:
+    """Return the default LLM-API exposure for a tool (no user override)."""
+    if _BETA_TAG in set(tags):
+        return False
+    if name.startswith(LLM_API_DEV_TOOL_PREFIX):
+        return False
+    return name not in LLM_API_DEFAULT_OFF_TOOLS
+
+
+def effective_llm_api_exposed(
+    name: str,
+    tags: Sequence[str] | set[str],
+    overrides: Mapping[str, Any],
+) -> bool:
+    """Return the effective exposure: user override if set, else the default."""
+    override = overrides.get(name)
+    if isinstance(override, bool):
+        return override
+    return default_llm_api_exposed(name, tags)
+
+
+def load_llm_api_overrides() -> dict[str, bool]:
+    """Read the persisted per-tool overrides from tool_config.json (live)."""
+    # Imported here, not at module top: settings_ui imports this module for
+    # the defaults, so a top-level import would be circular.
+    from .settings_ui import load_tool_config
+
+    config = load_tool_config()
+    # load_tool_config returns whatever the JSON file parses to — guard the
+    # valid-JSON-but-not-an-object case (e.g. `[]`) instead of raising.
+    if not isinstance(config, dict):
+        return {}
+    raw = config.get(LLM_API_CONFIG_KEY, {})
+    if not isinstance(raw, dict):
+        return {}
+    return {
+        name: value
+        for name, value in raw.items()
+        if isinstance(name, str) and isinstance(value, bool)
+    }
+
+
+def _pinned_tool_names() -> set[str]:
+    """Return the effective pinned set, matching the server's tool-search view.
+
+    Mirrors ``server.py::_apply_tool_search``'s always-visible computation:
+    the built-in DEFAULT_PINNED_TOOLS minus tools the user explicitly set to
+    plain "enabled" (an unpin), plus every tool the user set to "pinned"
+    (file or env). The component mirrors pinned tools directly into the
+    agent's tool list when the exposure mode is tool-search.
+    """
+    from .settings_ui import effective_tool_config
+    from .transforms import DEFAULT_PINNED_TOOLS
+
+    states = effective_tool_config().get("tools", {})
+    pinned = {name for name, state in states.items() if state == "pinned"}
+    unpinned_defaults = {
+        name for name in DEFAULT_PINNED_TOOLS if states.get(name) == "enabled"
+    }
+    return (set(DEFAULT_PINNED_TOOLS) - unpinned_defaults) | pinned
+
+
+class LlmExposureMiddleware(Middleware):
+    """Stamp every listed tool with its LLM-API exposure + pinned state.
+
+    Runs after the visibility layer, so globally-disabled tools are already
+    absent and never carry a stamp. The stamp is additive metadata — no tool
+    is hidden or altered for regular MCP clients.
+    """
+
+    def __init__(self) -> None:
+        """Initialize the short-lived settings cache."""
+        self._cache: tuple[float, dict[str, bool], set[str]] | None = None
+
+    def _current_settings(self) -> tuple[dict[str, bool], set[str]]:
+        """Return (overrides, pinned) with a short TTL over the file reads."""
+        now = time.monotonic()
+        if self._cache is not None:
+            stamp, overrides, pinned = self._cache
+            if now - stamp < _OVERRIDES_TTL_SECONDS:
+                return overrides, pinned
+        try:
+            overrides = load_llm_api_overrides()
+            pinned = _pinned_tool_names()
+        except Exception:
+            # Stamping must never break tools/list for regular clients — but
+            # the fallback direction matters for an exposure CONTROL: pure
+            # defaults would re-EXPOSE tools the user explicitly hid (their
+            # override lives in the unreadable settings), so serve the
+            # last-known-good values when we have them (review finding).
+            # Only a failure with no prior successful read stamps pure
+            # defaults. Visibly, either way.
+            if self._cache is not None:
+                _stamp, overrides, pinned = self._cache
+                logger.warning(
+                    "Could not read LLM-API exposure settings; keeping the "
+                    "last known values",
+                    exc_info=True,
+                )
+            else:
+                overrides, pinned = {}, set()
+                logger.warning(
+                    "Could not read LLM-API exposure settings and no prior "
+                    "read succeeded; stamping defaults",
+                    exc_info=True,
+                )
+        self._cache = (now, overrides, pinned)
+        return overrides, pinned
+
+    async def on_list_tools(
+        self,
+        context: MiddlewareContext[mt.ListToolsRequest],
+        call_next: CallNext[mt.ListToolsRequest, Sequence[Tool]],
+    ) -> Sequence[Tool]:
+        """Stamp ``_meta.ha_mcp`` on every tool in the list result."""
+        tools = await call_next(context)
+        overrides, pinned = self._current_settings()
+
+        stamped: list[Tool] = []
+        for tool in tools:
+            meta = dict(tool.meta or {})
+            namespace = dict(meta.get(META_NAMESPACE) or {})
+            namespace[META_EXPOSED_KEY] = effective_llm_api_exposed(
+                tool.name, tool.tags or set(), overrides
+            )
+            namespace[META_PINNED_KEY] = tool.name in pinned
+            meta[META_NAMESPACE] = namespace
+            stamped.append(tool.model_copy(update={"meta": meta}))
+        return stamped

{ha_mcp_dev-7.12.3.dev1863 → ha_mcp_dev-7.12.3.dev1865}/src/ha_mcp/server.py

@@ -243,6 +243,14 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
 
         self.mcp.add_middleware(ToolSearchHintMiddleware())
 
+        # Stamp every tools/list entry with its conversation-agent LLM API
+        # exposure + pinned state (#1745). Additive metadata only — regular
+        # clients are unaffected; the ha_mcp_tools custom component filters
+        # what it offers to Home Assistant conversation agents on it.
+        from .llm_exposure import LlmExposureMiddleware
+
+        self.mcp.add_middleware(LlmExposureMiddleware())
+
         # Read Only Mode write blocker (discussion #1569) — always
         # installed, consults the live flag per call. Before
         # PolicyMiddleware so a write blocked by Read Only Mode never

{ha_mcp_dev-7.12.3.dev1863 → ha_mcp_dev-7.12.3.dev1865}/src/ha_mcp/settings_ui/__init__.py

@@ -37,6 +37,7 @@ from ..config import (
     get_global_settings,
 )
 from ..errors import ErrorCode, create_error_response
+from ..llm_exposure import LLM_API_CONFIG_KEY
 from ..transforms import DEFAULT_PINNED_TOOLS, categorize_capability
 from ..utils.data_paths import get_data_dir
 
@@ -1370,14 +1371,38 @@ def build_settings_handlers(
         # (their write actions are blocked at call time instead). The JS
         # uses this to keep their toggles live while force-disabling the
         # other write-capable tools' rows when the mode is on.
+        # Conversation-agent LLM API exposure (#1745): effective value per
+        # tool (override else default) so the UI toggle renders the truth,
+        # plus the raw overrides so it can tell "user-set" from "default".
+        from ..llm_exposure import effective_llm_api_exposed, load_llm_api_overrides
         from ..read_only import READ_ONLY_EXEMPT_TOOLS
 
+        llm_overrides = load_llm_api_overrides()
+        # Feature-gated stub rows carry their primary tag but NOT the "beta"
+        # tag the registered tool declares (_render_stub renders from
+        # FEATURE_GATED_TOOLS metadata, whose tags are never empty) — append
+        # it whenever disabled_by is set so the toggle renders
+        # hidden-by-default, matching what the stamp will say once the flag
+        # turns the real tool on. Every feature-gated tool is beta by
+        # definition. (Review finding: a previous `or`-fallback here was dead
+        # code, so beta stubs rendered as exposed.)
+        llm_effective = {
+            t["name"]: effective_llm_api_exposed(
+                t["name"],
+                [*(t.get("tags") or []), *(["beta"] if t.get("disabled_by") else [])],
+                llm_overrides,
+            )
+            for t in tools
+        }
+
         return JSONResponse(
             {
                 "tools": tools,
                 "states": states,
                 "env_pinned": pinned,
                 "read_only_exempt": sorted(READ_ONLY_EXEMPT_TOOLS),
+                "llm_api": llm_effective,
+                "llm_api_overrides": llm_overrides,
             }
         )
 
@@ -1462,8 +1487,43 @@ def build_settings_handlers(
             name: state for name, state in states.items() if name not in env_pinned
         }
 
+        # Conversation-agent LLM API exposure overrides (#1745): a sparse
+        # {tool_name: bool} map, orthogonal to the states enum. Only bools
+        # persist — tools the user never flipped keep tracking their
+        # (deny-by-default for beta/dev/restart) defaults across releases.
+        raw_llm_api = body.get("llm_api", {})
+        if not isinstance(raw_llm_api, dict):
+            return JSONResponse(
+                create_error_response(
+                    ErrorCode.VALIDATION_INVALID_PARAMETER,
+                    "'llm_api' must be an object mapping tool names to booleans",
+                ),
+                status_code=400,
+            )
+        llm_api_overrides = {
+            name: value
+            for name, value in raw_llm_api.items()
+            if isinstance(name, str) and isinstance(value, bool)
+        }
+
         config = load_tool_config()
+
+        # The enable/disable/pin half still needs a restart to apply
+        # (visibility is wired at server build); the LLM-API exposure half
+        # applies live (stamped per tools/list). Only demand a restart when
+        # the half that needs one actually changed. Compare with the SAME
+        # default-pinned padding _get_tools applies to its response — the JS
+        # posts that padded map back verbatim, so an unpadded compare would
+        # flag every first save as a states change (live-found on #1745).
+        def _padded(tool_states: dict[str, str]) -> dict[str, str]:
+            padded = dict(tool_states)
+            for name in DEFAULT_PINNED_TOOLS:
+                padded.setdefault(name, "pinned")
+            return padded
+
+        states_changed = _padded(config.get("tools", {})) != _padded(states)
         config["tools"] = states
+        config[LLM_API_CONFIG_KEY] = llm_api_overrides
         if not save_tool_config(config):
             return JSONResponse(
                 create_error_response(
@@ -1480,9 +1540,13 @@ def build_settings_handlers(
         disabled_count = sum(1 for s in states.values() if s == "disabled")
         pinned_count = sum(1 for s in states.values() if s == "pinned")
         logger.info(
-            "Saved tool config (restart required to apply): %d disabled, %d pinned",
+            "Saved tool config (%s): %d disabled, %d pinned, %d LLM-API overrides",
+            "restart required to apply"
+            if states_changed
+            else "LLM-API exposure applies live",
             disabled_count,
             pinned_count,
+            len(llm_api_overrides),
         )
 
         # Same response shape as ``_save_feature_flags`` and
@@ -1496,8 +1560,9 @@ def build_settings_handlers(
             {
                 "success": True,
                 "applied": states,
+                "llm_api_applied": llm_api_overrides,
                 "mode": "file",
-                "restart_required": True,
+                "restart_required": states_changed,
             }
         )
 

{ha_mcp_dev-7.12.3.dev1863 → ha_mcp_dev-7.12.3.dev1865}/src/ha_mcp/settings_ui/settings.js

@@ -26,6 +26,13 @@ let toolStates = {};
 // Populated from data.env_pinned in loadTools(); read by render() to
 // lock rows and show the env-var name banner.
 let toolEnvPinned = {};
+// Conversation-agent LLM API exposure (#1745). toolLlm mirrors the
+// server-computed EFFECTIVE value per tool (user override, else the
+// deny-by-default for beta/dev/restart tools); toolLlmOverrides holds
+// only the user-set overrides and is what saveConfig persists — tools
+// never flipped keep tracking their defaults across releases.
+let toolLlm = {};
+let toolLlmOverrides = {};
 let saveTimer = null;
 let openGroups = new Set();
 
@@ -160,6 +167,8 @@ async function loadTools() {
   toolData = data.tools || [];
   toolStates = data.states || {};
   toolEnvPinned = data.env_pinned || {};
+  toolLlm = data.llm_api || {};
+  toolLlmOverrides = data.llm_api_overrides || {};
   READ_ONLY_EXEMPT = new Set(data.read_only_exempt || []);
   // Load policy state before the first render so the "security gated"
   // toggle reflects current policy.rules. loadPolicyState() never throws
@@ -741,6 +750,14 @@ function render() {
               `<span class="slider"></span></label>` +
             `<span>security gated</span>` +
           `</div>` +
+          `<div class="toggle-group ${isEnabled ? '' : 'disabled-toggle'}" ` +
+               `title="Offer this tool to Home Assistant conversation agents through the LLM API. Applies on the agent's next message - no restart. A tool disabled above is unavailable to agents regardless.">` +
+            `<label class="switch"><input type="checkbox" name="tool:${escapeHtml(t.name)}:llm" data-tool="${escapeHtml(t.name)}" data-field="llm" ` +
+              `aria-label="${escapeHtml(title)} exposed to the conversation-agent LLM API" ` +
+              `${(toolLlm[t.name] !== false) ? 'checked' : ''} ${isEnabled ? '' : 'disabled'}>` +
+              `<span class="slider"></span></label>` +
+            `<span>LLM API</span>` +
+          `</div>` +
         `</div>`;
 
       const inputs = div.querySelectorAll('input[type="checkbox"]');
@@ -766,6 +783,16 @@ function render() {
             render();
             return;
           }
+          if (field === 'llm') {
+            // LLM-API exposure lives in its own overrides map (persisted
+            // alongside states by saveConfig); the effective map mirrors it
+            // immediately so the re-render shows the new value.
+            toolLlm[t.name] = e.target.checked;
+            toolLlmOverrides[t.name] = e.target.checked;
+            scheduleSave();
+            render();
+            return;
+          }
           const currentState = getState(t.name);
           let newState = currentState;
           if (field === 'enabled') {
@@ -816,7 +843,7 @@ async function saveConfig() {
     resp = await fetch('./api/settings/tools', {
       method: 'POST',
       headers: {'Content-Type': 'application/json'},
-      body: JSON.stringify({states: toolStates}),
+      body: JSON.stringify({states: toolStates, llm_api: toolLlmOverrides}),
     });
   } catch (e) {
     // Auto-save is fire-and-forget (scheduleSave -> setTimeout); without
@@ -826,8 +853,20 @@ async function saveConfig() {
     return;
   }
   if (resp.ok) {
-    updateStatus('Saved. Restart required.', true);
-    markRestartRequired();
+    // LLM-API-exposure-only saves apply live (stamped per tools/list);
+    // enable/disable/pin changes still need a restart. The server tells
+    // us which happened.
+    let restartRequired = true;
+    try {
+      const saved = await resp.json();
+      restartRequired = saved.restart_required !== false;
+    } catch (e) { /* keep the conservative default */ }
+    if (restartRequired) {
+      updateStatus('Saved. Restart required.', true);
+      markRestartRequired();
+    } else {
+      updateStatus('Saved. LLM API exposure applies on the next agent message.', true);
+    }
   } else {
     // Surface the server's structured error when present (mirrors
     // saveAdvancedSettings / saveFeatureFlag) instead of a generic

{ha_mcp_dev-7.12.3.dev1863 → ha_mcp_dev-7.12.3.dev1865/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.12.3.dev1863
+Version: 7.12.3.dev1865
 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.12.3.dev1863 → ha_mcp_dev-7.12.3.dev1865}/src/ha_mcp_dev.egg-info/SOURCES.txt

@@ -10,6 +10,7 @@ src/ha_mcp/backup_manager.py
 src/ha_mcp/browser_landing.py
 src/ha_mcp/config.py
 src/ha_mcp/errors.py
+src/ha_mcp/llm_exposure.py
 src/ha_mcp/py.typed
 src/ha_mcp/read_only.py
 src/ha_mcp/server.py