ha-mcp-dev 9.1.1.dev3380__tar.gz → 9.1.1.dev3382__tar.gz

{ha_mcp_dev-9.1.1.dev3380 → ha_mcp_dev-9.1.1.dev3382}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 9.1.1.dev3380
+Version: 9.1.1.dev3382
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Keywords: mcp,home-assistant,ai,automation,smart-home
 Author: Julien
@@ -442,7 +442,7 @@ A `ha_manage_*` tool combines several operations, so it is reachable from more t
 
 Leave it off in clients with deferred tool loading (claude.ai, Claude Desktop, Claude Code); the full catalog has no idle cost there, direct calls skip the search step, and the client's built-in tool search is the better choice — there is no benefit to running ha-mcp's on top of it. Whether tools are deferred depends on the client and model combination: the same model can behave differently per client — GitHub Copilot CLI running Claude Sonnet/Opus inlines the full catalog and still benefits from tool search here. Some Codex models and ChatGPT include deferred tools too — check your client/model directly to confirm its features so you don't leave this enabled unnecessarily.
 
-> 🔄 **Refresh your client's tool list after changing this (or any) setting.** Toggling `ENABLE_TOOL_SEARCH` (or changing pinned/disabled tools, Read Only Mode, etc.) changes the tools the server exposes, but your AI client keeps serving its **cached** tool list until it re-fetches. Restarting the app or Home Assistant does **not** refresh the client — reconnect or refresh the MCP server in your client (e.g. in ChatGPT open **Settings**, then the plugin settings, select the connector and click **Refresh tools**; or close and reopen Claude Desktop). If you skip this, newly enabled tools won't appear in the client at all, and tools the server no longer exposes still show as available but fail when called (`Unknown tool`, or the Read Only Mode error for a write tool that mode hides). ChatGPT sometimes keeps serving the stale list even after the connector is removed and re-added under the same name — if tools are still missing after a refresh, delete the connector and create a new one with a **different name**. The [FAQ](https://homeassistant-ai.github.io/ha-mcp/faq/#chatgpt-stale-tools) has the full steps.
+> 🔄 **Refresh your client's tool list after changing this (or any) setting.** Toggling `ENABLE_TOOL_SEARCH` (or changing pinned/disabled tools, Read Only Mode, etc.) changes the tools the server exposes, but your AI client keeps serving its **cached** tool list until it re-fetches. Restarting the app or Home Assistant does **not** refresh the client — reconnect or refresh the MCP server in your client (e.g. in ChatGPT open **Settings**, then the plugin settings, select the connector and click **Refresh tools**; disconnect and reconnect a Claude Desktop custom connector; refresh the tools list of a claude.ai connector; or quit and reopen Claude Desktop for a server in `claude_desktop_config.json`), then start a new conversation. If you skip this, newly enabled tools won't appear in the client at all, and tools the server no longer exposes still show as available but fail when called (`Unknown tool`, or the Read Only Mode error for a write tool that mode hides). ChatGPT sometimes keeps serving the stale list even after the connector is removed and re-added under the same name — if tools are still missing after a refresh, delete the connector and create a new one with a **different name**. The [FAQ](https://homeassistant-ai.github.io/ha-mcp/faq/#chatgpt-stale-tools) has the full steps.
 
 For the HA app, the same option is documented in [`homeassistant-addon/DOCS.md`](homeassistant-addon/DOCS.md#enable_tool_search) along with the in-app settings UI for fine-grained tool enable/disable/pin.
 

{ha_mcp_dev-9.1.1.dev3380 → ha_mcp_dev-9.1.1.dev3382}/README.md

@@ -381,7 +381,7 @@ A `ha_manage_*` tool combines several operations, so it is reachable from more t
 
 Leave it off in clients with deferred tool loading (claude.ai, Claude Desktop, Claude Code); the full catalog has no idle cost there, direct calls skip the search step, and the client's built-in tool search is the better choice — there is no benefit to running ha-mcp's on top of it. Whether tools are deferred depends on the client and model combination: the same model can behave differently per client — GitHub Copilot CLI running Claude Sonnet/Opus inlines the full catalog and still benefits from tool search here. Some Codex models and ChatGPT include deferred tools too — check your client/model directly to confirm its features so you don't leave this enabled unnecessarily.
 
-> 🔄 **Refresh your client's tool list after changing this (or any) setting.** Toggling `ENABLE_TOOL_SEARCH` (or changing pinned/disabled tools, Read Only Mode, etc.) changes the tools the server exposes, but your AI client keeps serving its **cached** tool list until it re-fetches. Restarting the app or Home Assistant does **not** refresh the client — reconnect or refresh the MCP server in your client (e.g. in ChatGPT open **Settings**, then the plugin settings, select the connector and click **Refresh tools**; or close and reopen Claude Desktop). If you skip this, newly enabled tools won't appear in the client at all, and tools the server no longer exposes still show as available but fail when called (`Unknown tool`, or the Read Only Mode error for a write tool that mode hides). ChatGPT sometimes keeps serving the stale list even after the connector is removed and re-added under the same name — if tools are still missing after a refresh, delete the connector and create a new one with a **different name**. The [FAQ](https://homeassistant-ai.github.io/ha-mcp/faq/#chatgpt-stale-tools) has the full steps.
+> 🔄 **Refresh your client's tool list after changing this (or any) setting.** Toggling `ENABLE_TOOL_SEARCH` (or changing pinned/disabled tools, Read Only Mode, etc.) changes the tools the server exposes, but your AI client keeps serving its **cached** tool list until it re-fetches. Restarting the app or Home Assistant does **not** refresh the client — reconnect or refresh the MCP server in your client (e.g. in ChatGPT open **Settings**, then the plugin settings, select the connector and click **Refresh tools**; disconnect and reconnect a Claude Desktop custom connector; refresh the tools list of a claude.ai connector; or quit and reopen Claude Desktop for a server in `claude_desktop_config.json`), then start a new conversation. If you skip this, newly enabled tools won't appear in the client at all, and tools the server no longer exposes still show as available but fail when called (`Unknown tool`, or the Read Only Mode error for a write tool that mode hides). ChatGPT sometimes keeps serving the stale list even after the connector is removed and re-added under the same name — if tools are still missing after a refresh, delete the connector and create a new one with a **different name**. The [FAQ](https://homeassistant-ai.github.io/ha-mcp/faq/#chatgpt-stale-tools) has the full steps.
 
 For the HA app, the same option is documented in [`homeassistant-addon/DOCS.md`](homeassistant-addon/DOCS.md#enable_tool_search) along with the in-app settings UI for fine-grained tool enable/disable/pin.
 

{ha_mcp_dev-9.1.1.dev3380 → ha_mcp_dev-9.1.1.dev3382}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.1.dev3380"
+version = "9.1.1.dev3382"
 description = "Home Assistant MCP Server - Complete control of Home Assistant through MCP"
 readme = "README.md"
 requires-python = ">=3.13,<3.15"

{ha_mcp_dev-9.1.1.dev3380 → ha_mcp_dev-9.1.1.dev3382}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "ha-mcp-dev"
-version = "9.1.1.dev3380"
+version = "9.1.1.dev3382"
 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

{ha_mcp_dev-9.1.1.dev3380 → ha_mcp_dev-9.1.1.dev3382}/src/ha_mcp/renamed_tools.py

@@ -18,11 +18,16 @@ readers pick the more restrictive one (``rename_retired_keys``'s ``prefer``).
 And a call on a retired name carries the old signature, which the merged tool
 cannot dispatch without the ``action`` it never had —
 ``adapt_retired_arguments`` fills that in.
+
+A parameter can move the same way a tool does. ``RENAMED_PARAMETERS`` keeps
+the old parameter name callable for a client that has not re-listed, and
+``CLIENT_TOOL_LIST_REFRESH_STEPS`` is what such a client's user has to do.
 """
 
 from __future__ import annotations
 
-from collections.abc import Callable, Mapping
+import json
+from collections.abc import Callable, Mapping, Sequence
 from typing import Any
 
 # Retired tool name -> the name that serves it today.
@@ -37,6 +42,24 @@ RENAMED_TOOLS: dict[str, str] = {
     "ha_import_blueprint": "ha_manage_blueprints",
 }
 
+# Current tool name -> retired parameter name -> the name that serves it today.
+# Only a pure rename belongs here: the value keeps its meaning and its format.
+RENAMED_PARAMETERS: dict[str, dict[str, str]] = {
+    "ha_config_get_automation": {"identifier": "entity_id"},
+    "ha_config_set_automation": {"identifier": "entity_id"},
+    "ha_config_remove_automation": {"identifier": "entity_id"},
+}
+
+# How each client re-fetches the tool list, for every text that tells an agent
+# its list is stale. Steps are separated by ";" and carry none inside.
+CLIENT_TOOL_LIST_REFRESH_STEPS = (
+    "Claude Desktop custom connector: disconnect and reconnect it; "
+    "server in claude_desktop_config.json: quit and reopen Claude Desktop; "
+    "claude.ai: refresh the connector's tools list; Claude Code: /mcp, "
+    "reconnect; ChatGPT: open Settings, then the plugin settings, select the "
+    "connector and click Refresh tools"
+)
+
 
 def current_tool_name(name: str) -> str:
     """The name a tool answers to today, given any name it has had."""
@@ -101,3 +124,56 @@ def adapt_retired_arguments(
     if adapter is None:
         return dict(arguments) if arguments is not None else None
     return adapter(dict(arguments or {}))
+
+
+def retired_parameters_used(
+    name: str, arguments: Mapping[str, Any] | None
+) -> dict[str, str]:
+    """The retired parameter names a call on ``name`` carries, with their current names.
+
+    A retired name sent together with its current name is left out: that
+    caller knows the current signature, so the stray argument is rejected like
+    any other unknown one instead of replacing the value sent under the
+    current name.
+    """
+    renames = RENAMED_PARAMETERS.get(name)
+    if not renames or not arguments:
+        return {}
+    return {
+        old: new
+        for old, new in renames.items()
+        if old in arguments and new not in arguments
+    }
+
+
+def add_stale_list_warning(result: Any, renames: Sequence[tuple[str, str]]) -> None:
+    """Tell the caller of a call served through an old name that its list is stale.
+
+    ``renames`` holds each old name with its current one. The warning joins the
+    result's top-level ``warnings`` in both representations: the structured
+    content and the JSON text a client without it reads.
+    """
+    listed = ", ".join(f"`{old}` is now `{new}`" for old, new in renames)
+    warning = (
+        f"This call used a name from before an ha-mcp update ({listed}). It "
+        "was served, but your tool list is a stale copy. Ask the user to "
+        f"refresh it ({CLIENT_TOOL_LIST_REFRESH_STEPS}), then start a new "
+        "conversation."
+    )
+    structured = getattr(result, "structured_content", None)
+    if isinstance(structured, dict):
+        result.structured_content = {
+            **structured,
+            "warnings": [*(structured.get("warnings") or []), warning],
+        }
+    for block in getattr(result, "content", None) or []:
+        text = getattr(block, "text", None)
+        if not isinstance(text, str):
+            continue
+        try:
+            parsed = json.loads(text)
+        except json.JSONDecodeError:
+            continue
+        if isinstance(parsed, dict):
+            parsed["warnings"] = [*(parsed.get("warnings") or []), warning]
+            block.text = json.dumps(parsed)

{ha_mcp_dev-9.1.1.dev3380 → ha_mcp_dev-9.1.1.dev3382}/src/ha_mcp/server_tool_text.py

@@ -480,10 +480,11 @@ LITE_DOCSTRINGS: dict[str, str] = {
         "The response carries the full workflow in its `instructions` "
         "field (duplicate check, the mandatory anonymisation step, and "
         "how to file the issue), plus "
-        '`missing_tool_hint` for the "a tool I expected is missing" '
-        "case, which is usually a stale client tool list rather than a "
-        "bug. Read `instructions` before presenting anything to the "
-        "user; ha_get_skill_guide does not cover issue reporting."
+        '`missing_tool_hint` for the "a tool I expected is missing" or '
+        '"a tool rejects as unknown a parameter my tool list shows" case, '
+        "which is usually a stale client tool list rather than a bug. Read "
+        "`instructions` before presenting anything to the user; "
+        "ha_get_skill_guide does not cover issue reporting."
     ),
 }
 

{ha_mcp_dev-9.1.1.dev3380 → ha_mcp_dev-9.1.1.dev3382}/src/ha_mcp/settings_ui/locales/en.json

@@ -27,7 +27,7 @@
     "tabs.policies": "Tool Security Policies",
     "tabs.visibility": "Entity Visibility",
     "tabs.accessibility": "Accessibility",
-    "notice.restart_required": "⚠ Changes saved. Restart HA-MCP for them to take effect. On next startup, HA-MCP fully removes disabled tools from the MCP tool list. Then reconnect or refresh the MCP server in your AI client (e.g. refresh tool list on claude.ai, re-add/refresh the connector in ChatGPT, or close and reopen Claude Desktop) so it reloads the tool list. Restarting the app (add-on) or Home Assistant does NOT refresh your client's cached tool list. ChatGPT sometimes keeps serving its cached tool list even after the connector is removed and re-added — if tools are still missing, delete the connector and create a new one under a different name.",
+    "notice.restart_required": "⚠ Changes saved. Restart HA-MCP for them to take effect. On next startup, HA-MCP fully removes disabled tools from the MCP tool list. Then reconnect or refresh the MCP server in your AI client (e.g. refresh tool list on claude.ai; in ChatGPT open Settings, then the plugin settings, select the connector and click Refresh tools; disconnect and reconnect a Claude Desktop custom connector; or quit and reopen Claude Desktop for a server in claude_desktop_config.json) so it reloads the tool list, then start a new conversation. Restarting the app (add-on) or Home Assistant does NOT refresh your client's cached tool list. ChatGPT sometimes keeps serving its cached tool list even after the connector is removed and re-added — if tools are still missing, delete the connector and create a new one under a different name.",
     "notice.shared_settings": "Server-wide features (Tool Search, YAML config editing, filesystem tools, etc.) appear in both the <strong>Server Settings</strong> tab and the app (add-on) Configuration page; they're the same settings either way. Either surface stays in sync with the other after the app (add-on) restarts. Changes require HA-MCP to be restarted.",
     "notice.env_pins": "Tools listed in the <code>DISABLED_TOOLS</code> or <code>PINNED_TOOLS</code> env vars are locked read-only; unset the env var to edit them here. Pin toggles only take effect when Tool Search is enabled (Server Settings tab or app (add-on) Configuration page).",
     "actions.restart_addon": "Restart app (add-on)",
@@ -39,7 +39,7 @@
     "tools.read_only.help": "Turns off all write tools and blocks every tool from making write or destructive calls. Mixed read/write tools (backups, Apps (add-ons), energy preferences, voice pipelines, and code mode when enabled) stay available with their write operations blocked.",
     "tools.read_only.unknown": "Could not read server settings. Read Only Mode status unknown; this view may not reflect what the server enforces.",
     "tools.search": "Search tools...",
-    "server.auto_save_notice": "Settings on this tab save automatically. Changes take effect only after you restart HA-MCP (applies them server-side) and reconnect or refresh the MCP server in your AI client (reloads the tool list), e.g. refresh tool list on claude.ai, re-add or refresh the connector in ChatGPT, or close and reopen Claude Desktop. ChatGPT sometimes keeps serving its cached tool list even after the connector is removed and re-added — if tools are still missing, delete the connector and create a new one under a different name.",
+    "server.auto_save_notice": "Settings on this tab save automatically. Changes take effect only after you restart HA-MCP (applies them server-side) and reconnect or refresh the MCP server in your AI client (reloads the tool list), e.g. refresh tool list on claude.ai; in ChatGPT open Settings, then the plugin settings, select the connector and click Refresh tools; disconnect and reconnect a Claude Desktop custom connector; or quit and reopen Claude Desktop for a server in claude_desktop_config.json; then start a new conversation. ChatGPT sometimes keeps serving its cached tool list even after the connector is removed and re-added — if tools are still missing, delete the connector and create a new one under a different name.",
     "server.sections.search": "Search & matching",
     "server.sections.operations": "Operations",
     "server.sections.tool_surface": "Tool surface",
@@ -221,10 +221,10 @@
     "common.range_or_value": "Range {min}–{max}, or {value}.",
     "common.restart_required": "Restart required.",
     "common.none": "(none)",
-    "notice.restart.addon": "⚠ Changes saved. Click \"Restart app (add-on)\" for them to take effect. Disabled tools will be removed from the MCP tool list on next startup. Then refresh the tool list in your AI client; restarting the App alone does not refresh the client's cached list.",
-    "notice.restart.embedded": "⚠ Changes saved. Click \"Restart HA-MCP Server\" to reload the in-process integration. Then refresh the MCP tool list in your AI client.",
-    "notice.restart.sidecar": "⚠ Changes saved. Fully quit and reopen your MCP client for them to take effect. Disabled tools will be removed from the MCP tool list on next startup.",
-    "notice.restart.standalone": "⚠ Changes saved. Restart the ha-mcp process, then refresh the MCP tool list in your AI client.",
+    "notice.restart.addon": "⚠ Changes saved. Click \"Restart app (add-on)\" for them to take effect. Disabled tools will be removed from the MCP tool list on next startup. Then refresh the tool list in your AI client (for a Claude Desktop custom connector, disconnect and reconnect it; for a server in claude_desktop_config.json, quit and reopen Claude Desktop) and start a new conversation; restarting the App alone does not refresh the client's cached list.",
+    "notice.restart.embedded": "⚠ Changes saved. Click \"Restart HA-MCP Server\" to reload the in-process integration. Then refresh the MCP tool list in your AI client (for a Claude Desktop custom connector, disconnect and reconnect it; for a server in claude_desktop_config.json, quit and reopen Claude Desktop) and start a new conversation.",
+    "notice.restart.sidecar": "⚠ Changes saved. Fully quit and reopen your MCP client for them to take effect. Disabled tools will be removed from the MCP tool list on next startup. Then start a new conversation.",
+    "notice.restart.standalone": "⚠ Changes saved. Restart the ha-mcp process, then refresh the MCP tool list in your AI client (for a Claude Desktop custom connector, disconnect and reconnect it; for a server in claude_desktop_config.json, quit and reopen Claude Desktop) and start a new conversation.",
     "server.sidecar.confirm_disable": "⚠ PERMANENTLY disable the settings server?\n\nThis stops the server and writes a marker that prevents it from starting again. To restore access, delete ~/.ha-mcp/settings_ui_disabled and unset HA_MCP_DISABLE_SETTINGS_UI. Continue?",
     "tools.empty": "No tools found. The sidecar reads ~/.ha-mcp/tool_metadata.json. If it is missing or empty, restart your MCP client. See ~/.ha-mcp/sidecar.log for details.",
     "tools.group_count": "{enabled}/{total} enabled",

{ha_mcp_dev-9.1.1.dev3380 → ha_mcp_dev-9.1.1.dev3382}/src/ha_mcp/settings_ui/settings.html

@@ -173,10 +173,13 @@
     ⚠ Changes saved. Restart HA-MCP for them to take effect. On next
     startup, HA-MCP fully removes disabled tools from the MCP tool list.
     Then reconnect or refresh the MCP server in your AI client (e.g.
-    refresh tool list on claude.ai, re-add/refresh the connector in
-    ChatGPT, or close and reopen Claude Desktop) so it reloads the tool
-    list. Restarting the App (add-on) or Home Assistant does NOT refresh your
-    client's cached tool list.
+    refresh tool list on claude.ai; in ChatGPT open Settings, then the
+    plugin settings, select the connector and click Refresh tools;
+    disconnect and reconnect a Claude Desktop custom connector; or quit
+    and reopen Claude Desktop for a server in claude_desktop_config.json)
+    so it reloads the tool list, then start a new conversation. Restarting
+    the App (add-on) or Home Assistant does NOT refresh your client's
+    cached tool list.
   </span>
   <button class="restart-btn" id="restartBtn" style="display:none" data-i18n="actions.restart_addon">Restart App (add-on)</button>
 </div>
@@ -232,8 +235,11 @@
       Settings on this tab save automatically. Changes take effect only after
       you restart the App (add-on) (applies them server-side) and reconnect or
       refresh the MCP server in your AI client (reloads the tool list), e.g.
-      refresh tool list on claude.ai, re-add or refresh the connector in
-      ChatGPT, or close and reopen Claude Desktop.
+      refresh tool list on claude.ai; in ChatGPT open Settings, then the
+      plugin settings, select the connector and click Refresh tools;
+      disconnect and reconnect a Claude Desktop custom connector; or quit
+      and reopen Claude Desktop for a server in claude_desktop_config.json;
+      then start a new conversation.
     </div>
   </div>
 

ha_mcp_dev-9.1.1.dev3382/src/ha_mcp/tools/renamed_tool_middleware.py

@@ -0,0 +1,117 @@
+"""FastMCP middleware: keep retired tool and parameter names callable.
+
+Home Assistant 2026.2 renamed add-ons to apps, and this server's two add-on
+tools moved with it (``ha_get_addon`` -> ``ha_get_app``, ``ha_manage_addon``
+-> ``ha_manage_app``). Renaming a tool or one of its parameters is not a
+breaking change here — clients resolve tools by name at runtime and re-list
+after a server update — but a client that has not re-listed yet would get a
+bare "Unknown tool", or an unknown-parameter rejection, until it does.
+
+This middleware closes that window without paying for it in the catalog. It
+runs before FastMCP resolves the name and validates the arguments
+(``call_tool`` builds the middleware context first and its ``call_next``
+re-reads ``context.message``), so rewriting the name or an argument key here
+dispatches the call to the current tool. The old names are never registered
+or declared, so they stay out of ``tools/list`` and cost no tokens.
+
+The call is served, so nothing else tells that client its list is stale: the
+result carries a warning with the refresh steps, and the server log records
+the first use of each old name.
+
+Registering the old name as a second, disabled tool would not work:
+``get_tool`` filters on ``is_enabled`` and ``call_tool`` then raises
+``NotFoundError``, so a disabled tool is unlisted *and* uncallable.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from ha_mcp._vendor.fastmcp.server.middleware.middleware import (
+    CallNext,
+    Middleware,
+    MiddlewareContext,
+)
+
+from ..renamed_tools import (
+    RENAMED_TOOLS,
+    adapt_retired_arguments,
+    add_stale_list_warning,
+    retired_parameters_used,
+)
+
+logger = logging.getLogger(__name__)
+
+__all__ = ["RENAMED_TOOLS", "RenamedToolAliasMiddleware"]
+
+
+class RenamedToolAliasMiddleware(Middleware):
+    """Dispatch a call on a retired tool or parameter name to its current name.
+
+    Installed first in the chain so every later middleware — read-only
+    exemptions, policy gating, redaction — sees the current names it is keyed
+    on, rather than an alias it would not recognise.
+    """
+
+    def __init__(self) -> None:
+        # Which retired names have been logged at INFO already, so the first
+        # call on each is audible and the rest stay at DEBUG. An operator
+        # otherwise has no way to know a client is still calling the old name —
+        # the one observation that could ever justify retiring this alias —
+        # while a per-call INFO line would be noise for a tool called in a
+        # loop. Log de-duplication only: no dispatch decision reads it, and a
+        # restart simply announces each name once more.
+        self._announced: set[str] = set()
+
+    def _announce(self, key: str, old: str, new: str) -> None:
+        if key in self._announced:
+            logger.debug(
+                "%s was renamed to %s; dispatching the call to the current name",
+                old,
+                new,
+            )
+            return
+        self._announced.add(key)
+        logger.info(
+            "A client called %s, which was renamed to %s; dispatching to the "
+            "current name. Old names stay callable, but a client that re-lists "
+            "its tools after a server update will not need this.",
+            old,
+            new,
+        )
+
+    async def on_call_tool(
+        self, context: MiddlewareContext, call_next: CallNext
+    ) -> Any:
+        called = context.message.name
+        name = RENAMED_TOOLS.get(called, called)
+        arguments = context.message.arguments
+        renames: list[tuple[str, str]] = []
+        if name != called:
+            self._announce(called, called, name)
+            renames.append((called, name))
+            # A consolidated tool needs the ``action`` the retired signature
+            # never carried; a plain rename forwards the arguments as they are.
+            arguments = adapt_retired_arguments(called, arguments)
+        retired_parameters = retired_parameters_used(name, arguments)
+        if retired_parameters:
+            arguments = {
+                retired_parameters.get(key, key): value
+                for key, value in (arguments or {}).items()
+            }
+            for old, new in retired_parameters.items():
+                self._announce(f"{name}.{old}", f"{name}({old}=...)", new)
+                renames.append((old, new))
+        if not renames:
+            return await call_next(context)
+
+        result = await call_next(
+            context.copy(
+                message=context.message.model_copy(
+                    update={"name": name, "arguments": arguments}
+                )
+            )
+        )
+        add_stale_list_warning(result, renames)
+        return result

{ha_mcp_dev-9.1.1.dev3380 → ha_mcp_dev-9.1.1.dev3382}/src/ha_mcp/tools/tools_bug_report.py

@@ -34,6 +34,7 @@ from ..mcp_client_context import (
     extract_client_info,
     protocol_version,
 )
+from ..renamed_tools import CLIENT_TOOL_LIST_REFRESH_STEPS
 from ..utils.mcp_client_host import detect_client_host
 from ..utils.usage_logger import (
     AVG_LOG_ENTRIES_PER_TOOL,
@@ -95,22 +96,19 @@ _TITLE_PREFIXES = {
 # GitHub refuses a longer issue title.
 _ISSUE_TITLE_MAX_CHARS = 256
 
-# Guidance surfaced when the reported problem is a tool that never shows up in
-# the client's tool list. In issue #1804 this produced a false bug report: the
-# tool was enabled and loaded server-side (startup logs even said so), but the
-# MCP client had never refreshed its cached tool list, so the agent concluded
-# it was a server bug. A stale client-side tool list is the single most likely
-# cause of a missing tool and must be ruled out before filing.
+# #1804 (missing tool) and #2968 / #2978 (renamed parameter) were filed as
+# server bugs; a stale client tool list caused #1804 and #2968 and is the
+# likely cause of #2978, so the hint has the agent rule it out before filing.
+# The name predates the parameter case and stays: it is a response key.
 MISSING_TOOL_HINT = (
-    "MISSING/UNAVAILABLE TOOL? If the problem is that a tool you expected is not "
-    "in your tool list (can't find it, can't call it), this is very likely NOT a "
-    "bug. MCP clients cache the tool list when they connect and do NOT pick up "
-    "newly enabled tools until the connection is refreshed. Server-side logs "
-    "saying a tool is 'enabled' do NOT mean the client has loaded it. Ask the "
-    "user to refresh their MCP connection first: in Claude Desktop / claude.ai "
-    "use the connector's refresh option, or simply disconnect and reconnect it; "
-    "in Claude Code run /mcp and reconnect the server. Only file a bug if the "
-    "tool is still missing after a refresh."
+    "MISSING TOOL OR UNKNOWN PARAMETER? A tool you expected is not in your tool "
+    "list, or a tool rejects as unknown a parameter your tool list shows: very "
+    "likely NOT a bug. MCP clients cache the tool list, so they miss newly "
+    "enabled tools and keep showing parameter names an ha-mcp update renamed; "
+    "server logs saying a tool is 'enabled' do NOT mean the client loaded it. "
+    f"Ask the user to refresh first ({CLIENT_TOOL_LIST_REFRESH_STEPS}), then "
+    "start a new conversation. Only file a bug if the problem remains after a "
+    "refresh."
 )
 
 # Known Claude Desktop bugs that present as ha-mcp failures. Both live in
@@ -793,8 +791,8 @@ class BugReportTools:
         before showing anything to the user: it covers the missing-tool and
         known-client pre-checks, the duplicate check, the mandatory
         anonymisation step, and how to file the issue. Check
-        `missing_tool_hint` FIRST when the report is about a missing tool: a
-        stale client tool list (not a bug) is the usual cause.
+        `missing_tool_hint` FIRST when a tool is missing or rejects as unknown
+        a parameter your tool list shows: a stale list (not a bug) is the usual cause.
         """
         # Validate fields= before anything is collected: the projection at the
         # end was the only parse, outside any ValueError handler, so a
@@ -993,13 +991,13 @@ class BugReportTools:
                 "known_client_issues_hint": KNOWN_CLIENT_ISSUES_HINT,
                 "instructions": (
                     "WORKFLOW FOR FILING A REPORT:\n\n"
-                    "0. **PRE-CHECK — is the problem a missing/unavailable tool?** If "
-                    "the user's issue is that a tool they expected is missing or "
-                    "cannot be called, DO NOT file a bug yet. See the "
-                    "`missing_tool_hint` field: the likely cause is a stale MCP "
-                    "client tool list (not a server bug), fixed by refreshing or "
-                    "reconnecting the MCP connection. Only continue with this report "
-                    "if the tool is still missing after the user refreshes.\n\n"
+                    "0. **PRE-CHECK — missing tool or unknown parameter?** If the "
+                    "user's issue is that a tool they expected is missing, cannot be "
+                    "called or rejects as unknown a parameter the client's tool list "
+                    "shows, DO NOT file a bug yet. See the `missing_tool_hint` field: "
+                    "the likely cause is a stale MCP client tool list (not a server "
+                    "bug), fixed by refreshing or reconnecting the MCP connection. "
+                    "Only continue if the problem remains after the user refreshes.\n\n"
                     "0b. **PRE-CHECK — is it a known Claude Desktop bug?** A write "
                     "tool that hangs to a 4-minute timeout, or every call failing "
                     "with 'expected nonoptional, received undefined', is a client "