ha-mcp-dev 8.5.0.dev2678__tar.gz → 8.5.0.dev2680__tar.gz

{ha_mcp_dev-8.5.0.dev2678/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.5.0.dev2680}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.5.0.dev2678
+Version: 8.5.0.dev2680
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-8.5.0.dev2678 → ha_mcp_dev-8.5.0.dev2680}/pyproject.toml

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

@@ -217,6 +217,10 @@ class HomeAssistantSmartMCPServer:
         # of the full description we just discarded).
         self._apply_lite_docstrings()
 
+        # Append the Claude Desktop approval note to write tools. After
+        # lite docstrings so the note survives the replacement.
+        self._apply_write_tool_note()
+
         # 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.
@@ -1127,6 +1131,20 @@ class HomeAssistantSmartMCPServer:
                 "default."
             )
 
+    def _apply_write_tool_note(self) -> None:
+        """Append the Claude Desktop manual-approval note to write tools.
+
+        Applied unconditionally: the dropped calls never reach the server
+        (issue #2367), so the tool description is the only channel that
+        reaches the agent before the user clicks approve.
+        """
+        try:
+            from .transforms import WriteToolNoteTransform
+
+            self.mcp.add_transform(WriteToolNoteTransform())
+        except Exception:
+            logger.exception("Failed to apply WriteToolNoteTransform")
+
     def _apply_search_keyword_enrichment(self) -> None:
         """Append BM25 keyword boosts to tool descriptions.
 

{ha_mcp_dev-8.5.0.dev2678 → ha_mcp_dev-8.5.0.dev2680}/src/ha_mcp/tools/tools_bug_report.py

@@ -73,6 +73,32 @@ MISSING_TOOL_HINT = (
     "tool is still missing after a refresh."
 )
 
+# Known Claude Desktop bugs that present as ha-mcp failures. Both live in
+# the client, never reach this server, and already have upstream tickets, so
+# the agent must rule them out before filing here.
+KNOWN_CLIENT_ISSUES_HINT = (
+    "KNOWN CLAUDE DESKTOP ISSUES (not ha-mcp bugs; check before filing):\n"
+    "1. A write tool (dashboard, automation, script, helper, service call) "
+    "hangs and the client reports a 4-minute timeout with no result, while "
+    "read tools work. Cause: Claude Desktop's manual-approval dialog for a "
+    "local MCP server accepts the click before the call is fully generated "
+    "and silently drops the call. The server never receives it. Tracked in "
+    "homeassistant-ai/ha-mcp#2367 and anthropics/claude-code#92014. Tell the "
+    "user to retry and wait a few seconds before clicking Allow once, or to "
+    "set the write tools to Always allow (Settings -> Connectors -> the "
+    "server -> Tool permissions). A dropped call never reached Home "
+    "Assistant, but the same timeout can also hide a call that landed and "
+    "lost only its result (anthropics/claude-code#80012), so read the target "
+    "back before repeating a write that is not idempotent.\n"
+    "2. Every tool call fails with 'expected nonoptional, received "
+    "undefined' when an optional parameter is omitted. Cause: Claude Desktop "
+    "2.110.0 rejects omitted optional MCP parameters. Tracked in "
+    "homeassistant-ai/ha-mcp#2472 and anthropics/claude-code#94608. Tell the "
+    "user to downgrade Claude Desktop to 1.52386.6 (links in #2472) until "
+    "the upstream fix ships.\n"
+    "Only file a bug if the problem persists after the matching workaround."
+)
+
 # Max characters to include from addon container logs.
 # 3000 chars ≈ 750 LLM tokens — keeps the tool response well below context budgets
 # while still capturing enough recent output to diagnose most issues.
@@ -906,7 +932,8 @@ class BugReportTools:
                     "None = full response. Typical for a runtime bug: "
                     "'runtime_bug_template,suggested_title,"
                     "runtime_bug_submit_url,duplicate_check_urls,"
-                    "anonymization_guide,instructions'; for agent feedback "
+                    "anonymization_guide,missing_tool_hint,"
+                    "known_client_issues_hint,instructions'; for agent feedback "
                     "swap in agent_behavior_template and "
                     "agent_behavior_submit_url. The templates already embed "
                     "the relevant logs, so the raw log keys are only needed "
@@ -917,7 +944,8 @@ class BugReportTools:
                     "runtime_bug_template, agent_behavior_template, "
                     "anonymization_guide, suggested_title, "
                     "runtime_bug_submit_url, agent_behavior_submit_url, "
-                    "duplicate_check_urls, missing_tool_hint, instructions."
+                    "duplicate_check_urls, missing_tool_hint, "
+                    "known_client_issues_hint, instructions."
                 ),
             ),
         ] = None,
@@ -1139,6 +1167,7 @@ class BugReportTools:
             "agent_behavior_submit_url": agent_behavior_submit_url,
             "duplicate_check_urls": duplicate_check_urls,
             "missing_tool_hint": MISSING_TOOL_HINT,
+            "known_client_issues_hint": KNOWN_CLIENT_ISSUES_HINT,
             "instructions": (
                 "WORKFLOW FOR PRESENTING BUG REPORTS:\n\n"
                 "0. **PRE-CHECK — is the problem a missing/unavailable tool?** If "
@@ -1148,6 +1177,12 @@ class BugReportTools:
                 "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"
+                "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 "
+                "bug with an upstream ticket. See the `known_client_issues_hint` "
+                "field for the workaround to give the user, and only continue "
+                "if the problem persists after it.\n\n"
                 "1. **Check for duplicates FIRST** (before presenting the template):\n"
                 "   - Use the duplicate_check_urls to search for similar issues\n"
                 '   - If gh CLI is available: use `gh issue list --search "keyword"`\n'

{ha_mcp_dev-8.5.0.dev2678 → ha_mcp_dev-8.5.0.dev2680}/src/ha_mcp/transforms/__init__.py

@@ -8,12 +8,15 @@ from .categorized_search import (
     categorize_capability,
 )
 from .lite_docstrings import LiteDocstringsTransform
+from .write_tool_note import DESKTOP_APPROVAL_NOTE, WriteToolNoteTransform
 
 __all__ = [
     "Capability",
     "CategorizedSearchTransform",
     "DEFAULT_PINNED_TOOLS",
+    "DESKTOP_APPROVAL_NOTE",
     "LiteDocstringsTransform",
     "SearchKeywordsTransform",
+    "WriteToolNoteTransform",
     "categorize_capability",
 ]

{ha_mcp_dev-8.5.0.dev2678 → ha_mcp_dev-8.5.0.dev2680}/src/ha_mcp/transforms/categorized_search.py

@@ -35,6 +35,7 @@ from ha_mcp._vendor.mcp.types import ToolAnnotations
 
 from ..errors import TOOL_ERROR_LOG_LEVEL, ErrorCode, create_error_response
 from ..renamed_tools import adapt_retired_arguments, current_tool_name
+from .write_tool_note import DESKTOP_APPROVAL_NOTE
 
 if TYPE_CHECKING:
     from ha_mcp._vendor.fastmcp.server.transforms import GetToolNext
@@ -171,14 +172,16 @@ def _build_proxy_descriptions(search_tool_name: str) -> dict[str, str]:
             f"Creates or updates data. Use for any tool that modifies "
             f"state but does not delete/remove resources.\n"
             f"{_PROXY_PARAMS_SUFFIX}\n"
-            f'EXAMPLE: ha_call_write_tool(name="ha_set_area_or_floor", arguments={{"kind": "area", "name": "Kitchen"}})'
+            f'EXAMPLE: ha_call_write_tool(name="ha_set_area_or_floor", arguments={{"kind": "area", "name": "Kitchen"}})\n'
+            f"{DESKTOP_APPROVAL_NOTE}"
         ),
         "delete": (
             f"Execute a delete/remove tool discovered via {search_tool_name}. "
             f"Permanently removes data. Use for tools that delete or "
             f"remove resources (areas, automations, devices, etc.).\n"
             f"{_PROXY_PARAMS_SUFFIX}\n"
-            f'EXAMPLE: ha_call_delete_tool(name="ha_remove_area_or_floor", arguments={{"kind": "area", "id": "old_area"}})'
+            f'EXAMPLE: ha_call_delete_tool(name="ha_remove_area_or_floor", arguments={{"kind": "area", "id": "old_area"}})\n'
+            f"{DESKTOP_APPROVAL_NOTE}"
         ),
     }
 

ha_mcp_dev-8.5.0.dev2680/src/ha_mcp/transforms/write_tool_note.py

@@ -0,0 +1,57 @@
+"""Append a client-facing note to every write tool's description.
+
+Claude Desktop's manual-approval dialog for a local MCP server becomes
+clickable while the model is still streaming the call's arguments; an
+early "Allow once" silently drops the call and the client reports a
+4-minute timeout (issue #2367, anthropics/claude-code#92014). The server
+never sees those calls, so the only place to steer the user is the tool
+description the agent reads. Read-only tools are left untouched: they are
+short enough that the window is effectively closed.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from typing import TYPE_CHECKING
+
+from ha_mcp._vendor.fastmcp.server.transforms import Transform
+from ha_mcp._vendor.fastmcp.tools import Tool
+
+if TYPE_CHECKING:
+    from ha_mcp._vendor.fastmcp.server.transforms import GetToolNext
+    from ha_mcp._vendor.fastmcp.utilities.versions import VersionSpec
+
+DESKTOP_APPROVAL_NOTE = (
+    "If a Claude Desktop user gets a 4-minute timeout with no result on this "
+    "call, read the target back before repeating it, and tell them to wait a "
+    "few seconds before clicking the manual-approve button, or to set this "
+    "tool to Always allow."
+)
+
+
+class WriteToolNoteTransform(Transform):
+    """Append ``note`` to the description of every ``destructive_hint`` tool."""
+
+    def __init__(self, note: str = DESKTOP_APPROVAL_NOTE) -> None:
+        self._note = note
+
+    def _rewrite(self, tool: Tool) -> Tool:
+        annotations = tool.annotations
+        if not (annotations and annotations.destructive_hint):
+            return tool
+        base = (tool.description or "").rstrip()
+        description = f"{base}\n\n{self._note}" if base else self._note
+        return tool.model_copy(update={"description": description})
+
+    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-8.5.0.dev2678 → ha_mcp_dev-8.5.0.dev2680/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.5.0.dev2678
+Version: 8.5.0.dev2680
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT

{ha_mcp_dev-8.5.0.dev2678 → ha_mcp_dev-8.5.0.dev2680}/src/ha_mcp_dev.egg-info/SOURCES.txt

@@ -694,6 +694,7 @@ src/ha_mcp/tools/smart_search/_scoring.py
 src/ha_mcp/transforms/__init__.py
 src/ha_mcp/transforms/categorized_search.py
 src/ha_mcp/transforms/lite_docstrings.py
+src/ha_mcp/transforms/write_tool_note.py
 src/ha_mcp/utils/__init__.py
 src/ha_mcp/utils/config_hash.py
 src/ha_mcp/utils/config_write_lock.py