ha-mcp-dev 7.4.1.dev500__tar.gz → 7.4.1.dev501__tar.gz

{ha_mcp_dev-7.4.1.dev500/src/ha_mcp_dev.egg-info → ha_mcp_dev-7.4.1.dev501}/PKG-INFO

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

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

@@ -113,6 +113,15 @@ 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")
 
+    # Lite docstrings — replace selected heavy tool descriptions with
+    # shorter variants that defer detailed guidance to the
+    # ``ha_get_skill_home_assistant_best_practices`` skill tool/resource.
+    # Reduces idle catalog token usage at the cost of relying on the LLM
+    # to actually consult the skill when it needs detail. Beta feature
+    # (issue #1062); a startup WARNING is emitted when enabled so
+    # env-var users see the trade-off in their logs.
+    enable_lite_docstrings: bool = Field(False, alias="ENABLE_LITE_DOCSTRINGS")
+
     # Code Mode — sandboxed Python execution via pydantic-monty.
     # Provides an "escape hatch" tool (ha_manage_custom_tool) that lets LLMs write
     # custom one-off Python code when no existing tool covers the request.

{ha_mcp_dev-7.4.1.dev500 → ha_mcp_dev-7.4.1.dev501}/src/ha_mcp/server.py

@@ -263,6 +263,12 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
         # search indexing too).
         self._apply_settings_visibility()
 
+        # Replace heavy tool descriptions with lite variants when
+        # ENABLE_LITE_DOCSTRINGS=true. Must come BEFORE keyword
+        # enrichment so BM25 keywords append to the lite text (instead
+        # of the full description we just discarded).
+        self._apply_lite_docstrings()
+
         # Enrich tool descriptions with BM25 keyword boosts. Runs
         # unconditionally so Claude's native deferred-tool search
         # (claude.ai) benefits even when ENABLE_TOOL_SEARCH is off.
@@ -536,6 +542,147 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
         ),
     }
 
+    # Lite docstrings — beta opt-in (enable_lite_docstrings, #1062).
+    # Each entry replaces the full docstring on a heavy tool with a
+    # shorter variant that defers schema/example detail to
+    # ha_get_skill_home_assistant_best_practices. Every entry preserves
+    # a pointer to that skill so the LLM still has a path to the full
+    # guidance from inside the trimmed description. The trade-off
+    # (LLMs that skip the skill tool get less guidance) is surfaced in
+    # the dev-addon toggle, docs/beta.md, and a startup WARNING.
+    _LITE_DOCSTRINGS: ClassVar[dict[str, str]] = {
+        "ha_config_get_automation": (
+            "Get a Home Assistant automation configuration by "
+            "entity_id or unique_id. Returns the full config "
+            "(trigger, condition, action, mode) plus a stable "
+            "config_hash for use with python_transform on "
+            "ha_config_set_automation.\n\n"
+            "For schema and field-level details, see "
+            "ha_get_skill_home_assistant_best_practices."
+        ),
+        "ha_config_set_automation": (
+            "Create or update a Home Assistant automation.\n\n"
+            "Supports two modes: full `config` replacement, or surgical "
+            "`python_transform` on an existing automation (requires "
+            "`identifier` and `config_hash` from "
+            "ha_config_get_automation). Omit `identifier` to create a "
+            "new automation.\n\n"
+            "For schema details, examples, and native-vs-template "
+            "guidance, see ha_get_skill_home_assistant_best_practices."
+        ),
+        "ha_config_get_script": (
+            "Get a Home Assistant script configuration by "
+            "script_id or entity_id. Returns the full config (sequence, "
+            "mode, fields) plus a stable config_hash for use with "
+            "python_transform on ha_config_set_script.\n\n"
+            "For schema details, see "
+            "ha_get_skill_home_assistant_best_practices."
+        ),
+        "ha_config_set_script": (
+            "Create or update a Home Assistant script.\n\n"
+            "Supports two modes: full `config` replacement, or surgical "
+            "`python_transform` on an existing script (requires "
+            "`identifier` and `config_hash` from "
+            "ha_config_get_script). Omit `identifier` to create a new "
+            "script.\n\n"
+            "For schema details and examples, see "
+            "ha_get_skill_home_assistant_best_practices."
+        ),
+        "ha_config_get_scene": (
+            "Get a Home Assistant scene configuration by "
+            "scene_id or entity_id. Returns the full config plus a "
+            "stable config_hash for use with python_transform on "
+            "ha_config_set_scene.\n\n"
+            "For schema details, see "
+            "ha_get_skill_home_assistant_best_practices."
+        ),
+        "ha_config_set_scene": (
+            "Create or update a Home Assistant scene.\n\n"
+            "Supports two modes: full `config` replacement, or surgical "
+            "`python_transform` on an existing scene (requires "
+            "`identifier` and `config_hash`).\n\n"
+            "For schema details and examples, see "
+            "ha_get_skill_home_assistant_best_practices."
+        ),
+        "ha_config_list_helpers": (
+            "List Home Assistant helpers of a given simple type. "
+            "Accepts the 12 storage-backed helper types only: "
+            "input_button, input_boolean, input_select, input_number, "
+            "input_text, input_datetime, counter, timer, schedule, "
+            "zone, person, tag. Flow-based helpers (template, group, "
+            "utility_meter, derivative, statistics, trend, threshold, "
+            "filter, switch_as_x, etc.) cannot be listed through this "
+            "tool — use ha_search_entities or ha_deep_search.\n\n"
+            "For per-type schemas, see ha_get_helper_schema and "
+            "ha_get_skill_home_assistant_best_practices."
+        ),
+        "ha_config_set_helper": (
+            "Create or update a Home Assistant helper. Supports all "
+            "supported helper types: the simple types (input_*, "
+            "counter, timer, schedule, zone, person, tag) and the "
+            "flow-based types (template, group, utility_meter, "
+            "derivative, statistics, trend, threshold, filter, "
+            "switch_as_x, and others).\n\n"
+            "For per-type config schemas, call "
+            "ha_get_helper_schema(helper_type) first. For decision "
+            "matrix and worked examples (which helper type for which "
+            "use case), see ha_get_skill_home_assistant_best_practices."
+        ),
+        "ha_config_get_dashboard": (
+            "Get Home Assistant dashboard info (list mode, search "
+            "mode, or full config).\n\n"
+            "Three modes: (1) list — `list_only=True` returns all "
+            "storage-mode dashboards with metadata. (2) search — pass "
+            "any of `entity_id`, `card_type`, `heading` to find cards "
+            "(and their `jq_path`) inside a specific dashboard; the "
+            "result includes a `config_hash` you can pair with "
+            "ha_config_set_dashboard(python_transform=...) to edit "
+            "matched cards surgically. (3) get — no search params "
+            "returns the full Lovelace config plus a stable "
+            "`config_hash`. Use `url_path='default'` for the main "
+            "dashboard.\n\n"
+            "For card-type taxonomy and search workflow examples, see "
+            "ha_get_skill_home_assistant_best_practices."
+        ),
+        "ha_config_set_dashboard": (
+            "Create or update a Home Assistant dashboard.\n\n"
+            "Supports two modes: full `config` replacement (new "
+            "dashboards or full restructures), or surgical "
+            "`python_transform` on an existing dashboard (requires "
+            "`config_hash` from ha_config_get_dashboard; recommended "
+            "for edits). Use `url_path` of 'default' or 'lovelace' "
+            "to target the built-in dashboard.\n\n"
+            "For card types, layout patterns, and python_transform "
+            "security rules, see "
+            "ha_get_skill_home_assistant_best_practices."
+        ),
+        "ha_call_service": (
+            "Execute a Home Assistant service to control entities or "
+            "trigger automations. Calls `<domain>.<service>` "
+            "(e.g., light.turn_on, climate.set_temperature). Use "
+            "ha_search_entities to find entity IDs and ha_get_state "
+            "to read current values before changing them.\n\n"
+            "For service-parameter details and per-domain guidance, "
+            "see ha_get_skill_home_assistant_best_practices."
+        ),
+        "ha_config_set_yaml": (
+            "Update raw YAML in configuration.yaml or packages/*.yaml "
+            "via add / replace / remove on a single top-level key "
+            "(LAST RESORT).\n\n"
+            "Dedicated tools (ha_config_set_automation, "
+            "ha_config_set_script, ha_config_set_scene, "
+            "ha_config_set_helper) cover almost every use case and "
+            "should be preferred. Use this only for YAML-only "
+            "integrations (command_line, rest, shell_command, notify) "
+            "or registering YAML-mode dashboards via "
+            "`lovelace.dashboards.<url_path>`. Most edits require a "
+            "full HA restart; template, mqtt, and group support "
+            "reload.\n\n"
+            "For routing guidance and the full allowlist, see "
+            "ha_get_skill_home_assistant_best_practices."
+        ),
+    }
+
     # Description overrides that REPLACE the original description for BM25.
     # Used to narrow overly broad tools so they stop matching generic queries
     # against ha-mcp's internal BM25 search tool. Only applied when
@@ -552,6 +699,61 @@ class HomeAssistantSmartMCPServer(EnhancedToolsMixin):
         ),
     }
 
+    def _apply_lite_docstrings(self) -> None:
+        """Swap heavy tool descriptions for shorter variants if enabled.
+
+        Beta feature gated on ``settings.enable_lite_docstrings`` /
+        ``ENABLE_LITE_DOCSTRINGS=true``. Replaces the description on
+        each tool listed in ``_LITE_DOCSTRINGS`` with a shorter variant
+        that defers detail to
+        ``ha_get_skill_home_assistant_best_practices``. Tools not in the
+        mapping pass through unchanged.
+
+        Emits a startup WARNING when enabled so non-addon users (Docker,
+        uvx, pip) see the trade-off in their logs — the addon UI surfaces
+        the same warning via the toggle description. A second WARNING is
+        emitted if the transform install fails, so users don't silently
+        get full descriptions back after explicitly enabling the toggle.
+
+        Runs before ``_apply_search_keyword_enrichment`` so BM25 keywords
+        append to the lite text instead of the discarded full description.
+        """
+        if not self.settings.enable_lite_docstrings:
+            return
+
+        logger.warning(
+            "ENABLE_LITE_DOCSTRINGS=true: replacing %d tool descriptions "
+            "with shorter variants. This reduces idle catalog token usage "
+            "but may degrade LLM performance — the trimmed descriptions "
+            "rely on the LLM calling ha_get_skill_home_assistant_best_practices "
+            "(or reading skill:// resources) for detail, which is not "
+            "guaranteed. See docs/beta.md.",
+            len(self._LITE_DOCSTRINGS),
+        )
+
+        try:
+            from .transforms import LiteDocstringsTransform
+        except ImportError:
+            logger.exception(
+                "LiteDocstringsTransform not importable — please file a "
+                "bug. ENABLE_LITE_DOCSTRINGS=true is in effect but full "
+                "tool descriptions will be exposed."
+            )
+            return
+
+        try:
+            self.mcp.add_transform(
+                LiteDocstringsTransform(replacements=self._LITE_DOCSTRINGS)
+            )
+        except Exception:
+            logger.exception("Failed to apply LiteDocstringsTransform")
+            logger.warning(
+                "ENABLE_LITE_DOCSTRINGS=true was set but the transform "
+                "failed to install — full tool descriptions remain in "
+                "effect. Catalog token usage will be unchanged from the "
+                "default."
+            )
+
     def _apply_search_keyword_enrichment(self) -> None:
         """Append BM25 keyword boosts to tool descriptions.
 

ha_mcp_dev-7.4.1.dev501/src/ha_mcp/transforms/__init__.py

@@ -0,0 +1,15 @@
+"""Custom FastMCP transforms for ha-mcp."""
+
+from .categorized_search import (
+    DEFAULT_PINNED_TOOLS,
+    CategorizedSearchTransform,
+    SearchKeywordsTransform,
+)
+from .lite_docstrings import LiteDocstringsTransform
+
+__all__ = [
+    "CategorizedSearchTransform",
+    "DEFAULT_PINNED_TOOLS",
+    "LiteDocstringsTransform",
+    "SearchKeywordsTransform",
+]

ha_mcp_dev-7.4.1.dev501/src/ha_mcp/transforms/lite_docstrings.py

@@ -0,0 +1,62 @@
+"""Lite docstrings transform for ha-mcp.
+
+Replaces the description on a configurable set of tools with a shorter,
+"lite" variant that defers detailed guidance to the
+``ha_get_skill_home_assistant_best_practices`` tool (or its skill://
+resource). Trades catalog token usage for the assumption that the LLM
+will read the skill when it needs more detail — see issue #1062.
+
+Opt-in via ``enable_lite_docstrings``; see ``docs/beta.md`` for trade-offs.
+Tools NOT in the mapping pass through unchanged, so smaller tools keep
+their existing descriptions without us having to enumerate them.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from fastmcp.server.transforms import Transform
+from fastmcp.tools import Tool
+
+if TYPE_CHECKING:
+    from fastmcp.server.transforms import GetToolNext
+    from fastmcp.utilities.versions import VersionSpec
+
+
+class LiteDocstringsTransform(Transform):
+    """Replace heavy tool descriptions with shorter variants.
+
+    Mirrors ``SearchKeywordsTransform``: an empty mapping is a no-op,
+    so installing the transform unconditionally would be safe. The
+    caller (``server._apply_lite_docstrings``) only installs it when
+    the feature flag is on, but the empty-dict-as-no-op contract keeps
+    the transform self-contained.
+
+    The transform deliberately does not auto-append a pointer to
+    ``ha_get_skill_home_assistant_best_practices`` — the mapped lite
+    description owns its own pointer text so per-tool wording can stay
+    natural.
+    """
+
+    def __init__(self, replacements: dict[str, str] | None = None) -> None:
+        self._replacements: dict[str, str] = replacements or {}
+
+    def _rewrite(self, tool: Tool) -> Tool:
+        lite = self._replacements.get(tool.name)
+        if lite is None:
+            return tool
+        return tool.model_copy(update={"description": lite})
+
+    async def list_tools(self, tools: Sequence[Tool]) -> Sequence[Tool]:
+        return [self._rewrite(t) for t in tools]
+
+    async def get_tool(
+        self,
+        name: str,
+        call_next: GetToolNext,
+        *,
+        version: VersionSpec | None = None,
+    ) -> Tool | None:
+        tool = await call_next(name, version=version)
+        return self._rewrite(tool) if tool else None

{ha_mcp_dev-7.4.1.dev500 → ha_mcp_dev-7.4.1.dev501/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 7.4.1.dev500
+Version: 7.4.1.dev501
 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.4.1.dev500 → ha_mcp_dev-7.4.1.dev501}/src/ha_mcp_dev.egg-info/SOURCES.txt

@@ -88,6 +88,7 @@ src/ha_mcp/tools/tools_zones.py
 src/ha_mcp/tools/util_helpers.py
 src/ha_mcp/transforms/__init__.py
 src/ha_mcp/transforms/categorized_search.py
+src/ha_mcp/transforms/lite_docstrings.py
 src/ha_mcp/utils/__init__.py
 src/ha_mcp/utils/config_hash.py
 src/ha_mcp/utils/data_paths.py

ha_mcp_dev-7.4.1.dev500/src/ha_mcp/transforms/__init__.py

@@ -1,9 +0,0 @@
-"""Custom FastMCP transforms for ha-mcp."""
-
-from .categorized_search import (
-    DEFAULT_PINNED_TOOLS,
-    CategorizedSearchTransform,
-    SearchKeywordsTransform,
-)
-
-__all__ = ["CategorizedSearchTransform", "DEFAULT_PINNED_TOOLS", "SearchKeywordsTransform"]