ha-mcp-dev 8.5.0.dev2689__tar.gz → 8.5.0.dev2690__tar.gz

{ha_mcp_dev-8.5.0.dev2689/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.5.0.dev2690}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.5.0.dev2689
+Version: 8.5.0.dev2690
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -33,6 +33,7 @@ Requires-Dist: jsonschema-path>=0.3.4
 Requires-Dist: openapi-pydantic>=0.5.1
 Requires-Dist: opentelemetry-api>=1.28.0
 Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: psutil>=7.0.0
 Requires-Dist: py-key-value-aio[filetree,keyring,memory]<0.5.0,>=0.4.4
 Requires-Dist: pydantic-settings>=2.0.0
 Requires-Dist: pyjwt[crypto]>=2.10.1

{ha_mcp_dev-8.5.0.dev2689 → ha_mcp_dev-8.5.0.dev2690}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.5.0.dev2689"
+version = "8.5.0.dev2690"
 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
@@ -44,6 +44,7 @@ dependencies = [
     "openapi-pydantic>=0.5.1",
     "opentelemetry-api>=1.28.0",
     "platformdirs>=4.0.0",
+    "psutil>=7.0.0",
     "py-key-value-aio[filetree,keyring,memory]>=0.4.4,<0.5.0",
     "pydantic-settings>=2.0.0",
     "pyjwt[crypto]>=2.10.1",
@@ -150,6 +151,7 @@ explicit_package_bases = true
 [[tool.mypy.overrides]]
 module = [
     "jq",
+    "psutil",
     "pydantic_monty",
     "pydantic_monty.*",
 ]

{ha_mcp_dev-8.5.0.dev2689 → ha_mcp_dev-8.5.0.dev2690}/src/ha_mcp/tools/tools_bug_report.py

@@ -31,6 +31,7 @@ from .._version import get_version, is_embedded, is_running_in_addon
 from ..client.supervisor_client import make_supervisor_httpx_client
 from ..config import Settings, get_global_settings
 from ..errors import create_validation_error
+from ..utils.mcp_client_host import detect_client_host
 from ..utils.usage_logger import (
     AVG_LOG_ENTRIES_PER_TOOL,
     get_recent_logs,
@@ -93,9 +94,10 @@ KNOWN_CLIENT_ISSUES_HINT = (
     "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"
+    "homeassistant-ai/ha-mcp#2472 and anthropics/claude-code#94608 (fixed "
+    "upstream). Tell the user to update Claude Desktop to 2.2553.0 or later; "
+    "if they cannot update, downgrading to 1.52386.6 (links in #2472) also "
+    "works.\n"
     "Only file a bug if the problem persists after the matching workaround."
 )
 
@@ -466,6 +468,72 @@ def _format_client_info_for_template(info: dict[str, str]) -> str:
     return base
 
 
+# Claude Desktop advertises every stdio server as ``local-agent-mode-<server
+# name> 1.0.0`` (#1701, #2472, #2484), so the name alone never says which
+# Desktop release is involved.
+_CLAUDE_DESKTOP_STDIO_PREFIX = "local-agent-mode-"
+HOST_NOT_DETECTED = "not detected"
+
+# stdio-to-HTTP bridges present their own identity in the handshake, so the
+# server never sees the real client behind them. ``mcp 0.1.0`` is the Python
+# MCP SDK's default clientInfo, which is what fastmcp-remote and mcp-proxy
+# style bridges send (observed live from Claude Desktop -> fastmcp-remote ->
+# component, 2026-09).
+_STDIO_BRIDGE_NAMES = {
+    "mcp": "Python MCP SDK default identity, i.e. a fastmcp-remote / mcp-proxy style bridge",
+    "mcp-remote": "mcp-remote bridge",
+    "mcp-proxy": "mcp-proxy bridge",
+    "fastmcp-remote": "fastmcp-remote bridge",
+}
+
+
+def _http_user_agent() -> str:
+    """The request's ``User-Agent``, or ``""`` outside an HTTP request."""
+    value = get_http_headers(include={"user-agent"}).get("user-agent", "")
+    return str(value).strip()
+
+
+def _format_client_host_for_template(diagnostic_info: dict[str, Any]) -> str:
+    """Render what the server could learn about the host app beyond ``clientInfo``.
+
+    Over stdio the host is the process that spawned ha-mcp, so the parent
+    chain names it and, for Claude Desktop, gives the release. Over HTTP the
+    ``User-Agent`` is the only extra signal (and for Anthropic's connector
+    broker it carries no app version). The wording tells the agent exactly
+    when it still has to ask the user.
+    """
+    client_info = diagnostic_info.get("mcp_client_info") or {}
+    client_host = diagnostic_info.get("mcp_client_host") or {}
+    user_agent = diagnostic_info.get("http_user_agent") or ""
+    parts: list[str] = []
+    name = client_info.get("name") or ""
+    if name.startswith(_CLAUDE_DESKTOP_STDIO_PREFIX):
+        parts.append("Claude Desktop (local agent mode)")
+    # "mcp" is only the SDK default when paired with its literal 0.1.0; a
+    # client that names itself "mcp" with a real version is not a bridge.
+    bridge = _STDIO_BRIDGE_NAMES.get(name.lower())
+    if name.lower() == "mcp" and client_info.get("version") != "0.1.0":
+        bridge = None
+    if bridge:
+        parts.append(
+            f"stdio bridge ({bridge}); the real client app is hidden behind "
+            "it, ask the user which app and version launched the bridge, do "
+            "not guess"
+        )
+    if diagnostic_info.get("mcp_transport") == "stdio":
+        if client_host:
+            version = client_host.get("version") or "unknown"
+            parts.append(
+                f"{client_host.get('name') or 'unknown'} {version} "
+                "_(from the parent process)_"
+            )
+        else:
+            parts.append(HOST_NOT_DETECTED)
+    elif user_agent and client_info.get("title") != "from HTTP User-Agent":
+        parts.append(f"User-Agent `{user_agent}`")
+    return "; ".join(parts) or HOST_NOT_DETECTED
+
+
 def _detect_mcp_transport() -> str:
     """Best-effort MCP transport detection.
 
@@ -496,6 +564,12 @@ def _detect_mcp_transport() -> str:
     if os.environ.get("MCP_HTTP_PORT") or os.environ.get("FASTMCP_PORT"):
         return "http"
 
+    # The in-process server inside HA core only ever serves HTTP, and HA's
+    # stdin is not a TTY, so the isatty fallback below would label every
+    # embedded install "stdio" (seen on a live component install, 8.5.0).
+    if is_embedded():
+        return "http"
+
     # Home Assistant add-on always runs HTTP via homeassistant-addon/start.py.
     # Placed after the explicit hints (argv0 / env) so an operator override
     # still wins, but before the stdin-isatty fallback because Supervisor-
@@ -755,6 +829,7 @@ def _build_formatted_report(
         f"Installation Method: {diagnostic_info['installation_method']}",
         f"MCP Transport: {mcp_transport}",
         f"MCP Client: {_format_client_info_for_template(client_info)}",
+        f"MCP Client Host: {_format_client_host_for_template(diagnostic_info)}",
         f"Operating System: {platform_info['os']} {platform_info['os_release']} ({platform_info['architecture']})",
         f"Python Version: {platform_info['python_version']}",
         f"Home Assistant Version: {diagnostic_info['home_assistant_version']}",
@@ -1016,6 +1091,12 @@ class BugReportTools:
         config_toggles = _get_config_toggles()
         mcp_transport = _detect_mcp_transport()
         client_info = _extract_client_info(ctx)
+        client_host = (
+            await asyncio.to_thread(detect_client_host)
+            if mcp_transport == "stdio"
+            else {}
+        )
+        user_agent = _http_user_agent()
         installed_version = await asyncio.to_thread(_detect_installed_version)
         component_version = await self._detect_component_version()
         tools_entry_status = await self._detect_tools_entry_status()
@@ -1036,6 +1117,8 @@ class BugReportTools:
             "websockets_dependency": _websockets_dependency_state(),
             "mcp_transport": mcp_transport,
             "mcp_client_info": client_info,
+            "mcp_client_host": client_host,
+            "http_user_agent": user_agent,
             "config_toggles": config_toggles,
             "connection_status": "Unknown",
             "home_assistant_version": "Unknown",
@@ -1218,7 +1301,19 @@ class BugReportTools:
                 "     for triage — do not skip it.\n"
                 "   `MCP Transport` and `MCP Client` are auto-detected by the server (the latter\n"
                 "   from the MCP `initialize` handshake); leave both as-is unless they're clearly\n"
-                "   wrong.\n\n"
+                "   wrong.\n"
+                "   - `**MCP Client Host:**` — the app that launched ha-mcp and its release, read\n"
+                "     from the parent process over stdio. Claude Desktop only advertises\n"
+                "     `local-agent-mode-<server> 1.0.0` in the handshake, and Desktop releases are\n"
+                "     what client-side regressions hinge on (#2472). If this line says\n"
+                '     "not detected", "stdio bridge", or the version is "unknown", ASK the\n'
+                "     user which app and version they are using (Claude Desktop: Settings ->\n"
+                "     About; Claude Code: `claude --version`) and write THEIR answer on this\n"
+                "     line. NEVER fill it in yourself: you cannot know the app or its version,\n"
+                "     and a guessed value sends triage the wrong way. If the user does not\n"
+                '     know, write "unknown (user asked)". An `MCP Client` of `mcp 0.1.0` is\n'
+                "     a bridge such as fastmcp-remote, not the real client, so the same rule\n"
+                "     applies there.\n\n"
                 "5. **Present the anonymized report to the user**:\n"
                 "   a. Show the suggested_title (user can edit if needed) and tell them GitHub's\n"
                 "      title field is now pre-filled via the submission URL — they don't need to\n"
@@ -1553,6 +1648,7 @@ ha_call_service(domain="light", service="turn_on", entity_id="light.example")
 - **Installation Method:** {diagnostic_info.get("installation_method", "Unknown")}
 - **MCP Transport:** {mcp_transport} _(auto-detected — correct if wrong)_
 - **MCP Client:** {_format_client_info_for_template(client_info)} _(auto-detected from the MCP `initialize` handshake)_
+- **MCP Client Host:** {_format_client_host_for_template(diagnostic_info)} _(auto-detected; if this says "not detected" or "unknown", ask the user which app and version launched ha-mcp and write it here)_
 - **AI Model:**
 - **Operating System:** {platform_info.get("os", "Unknown")} {platform_info.get("os_release", "")} ({platform_info.get("architecture", "Unknown")})
 - **Python Version:** {platform_info.get("python_version", "Unknown")}
@@ -1720,6 +1816,7 @@ def _generate_agent_behavior_template(
 - **Installation Method:** {diagnostic_info.get("installation_method", "Unknown")}
 - **MCP Transport:** {mcp_transport} _(auto-detected — correct if wrong)_
 - **MCP Client:** {_format_client_info_for_template(client_info)} _(auto-detected from the MCP `initialize` handshake)_
+- **MCP Client Host:** {_format_client_host_for_template(diagnostic_info)} _(auto-detected; if this says "not detected" or "unknown", ask the user which app and version launched ha-mcp and write it here)_
 - **AI Model:**
 - **Home Assistant Version:** {diagnostic_info.get("home_assistant_version", "Unknown")}
 

ha_mcp_dev-8.5.0.dev2690/src/ha_mcp/utils/mcp_client_host.py

@@ -0,0 +1,168 @@
+"""Identify the host application that launched this stdio MCP server.
+
+The MCP ``initialize`` handshake only carries what the client chooses to
+advertise. Claude Desktop, for example, sends ``local-agent-mode-<server>
+1.0.0`` for every stdio server, so a bug report never learns which Desktop
+release was involved -- and Desktop releases are exactly what client-side
+regressions such as homeassistant-ai/ha-mcp#2472 hinge on. Over stdio the
+host is an ancestor of this process, so its executable path (and, for the
+Claude Desktop bundles, its version) can be read off the process tree.
+"""
+
+from __future__ import annotations
+
+import logging
+import plistlib
+import re
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# Launch-chain intermediaries between the host app and ha-mcp: shells,
+# package runners, interpreters, and Claude Desktop's own ``disclaimer``
+# helper. Matched on the lowercased basename with any ``.exe``/``.cmd``
+# suffix removed.
+_WRAPPER_NAMES = frozenset(
+    {
+        "bash",
+        "caffeinate",
+        "cmd",
+        "conhost",
+        "dash",
+        "disclaimer",
+        "env",
+        "fish",
+        "ha-mcp",
+        "login",
+        "mcp-proxy",
+        "mcp-remote",
+        "node",
+        "nohup",
+        "npm",
+        "npx",
+        "powershell",
+        "pwsh",
+        "python",
+        "pythonw",
+        "sh",
+        "uv",
+        "uvx",
+        "wsl",
+        "wslhost",
+        "zsh",
+    }
+)
+_PYTHON_VERSIONED_RE = re.compile(r"^python\d")
+
+# Claude Desktop on Windows: the Squirrel installer keeps each release under
+# ``%LOCALAPPDATA%\AnthropicClaude\app-<version>\claude.exe`` (the same
+# layout Claude Code's ``/desktop`` command version-gates on), and the MSIX
+# package lands under ``WindowsApps\Claude_<version>_x64__<hash>\app\``.
+_WINDOWS_VERSION_PATTERNS = (
+    re.compile(r"[\\/]AnthropicClaude[\\/]app-(\d+(?:\.\d+)+)[\\/]"),
+    re.compile(r"[\\/]WindowsApps[\\/]Claude_(\d+(?:\.\d+)+)_"),
+)
+_MAC_BUNDLE_MARKER = "/Claude.app/Contents/"
+
+
+def detect_client_host() -> dict[str, str]:
+    """Return ``{"name", "version", "evidence"}`` for the launching host app.
+
+    Walks this process's ancestors nearest-first and reports the first one
+    that is not a known launch-chain wrapper. Claude Desktop is recognised
+    by its macOS bundle path or Windows install layout and gets a real
+    version; any other host is reported by executable name with version
+    ``unknown`` so the agent knows to ask the user. Returns ``{}`` when
+    ``psutil`` is unavailable or the tree cannot be read -- never raises,
+    since this runs inside the bug-report path that must stay robust.
+    """
+    try:
+        import psutil
+    except ImportError:
+        logger.debug("psutil unavailable; skipping MCP client host detection")
+        return {}
+    try:
+        ancestors = psutil.Process().parents()
+    except (psutil.Error, OSError) as exc:
+        logger.debug("Cannot read process ancestry: %s", exc)
+        return {}
+    for proc in ancestors:
+        exe, name = _exe_and_name(proc, psutil)
+        if not name:
+            continue
+        host = classify_host(exe, name)
+        if host is not None:
+            return host
+    return {}
+
+
+def _exe_and_name(proc: Any, psutil: Any) -> tuple[str, str]:
+    """``(exe_path, basename)`` for a process; either may be empty.
+
+    ``exe()`` raises ``AccessDenied`` for protected binaries such as MSIX
+    packages under ``WindowsApps``; the bare ``name()`` still identifies
+    the host, just without a path to derive a version from.
+    """
+    exe = ""
+    name = ""
+    try:
+        exe = proc.exe() or ""
+    except (psutil.Error, OSError):
+        pass  # protected or vanished binary: fall back to the bare name
+    try:
+        name = proc.name() or ""
+    except (psutil.Error, OSError):
+        pass  # process gone mid-walk: skipped by the caller as nameless
+    if not name and exe:
+        name = Path(exe).name
+    return exe, name
+
+
+def classify_host(exe: str, name: str) -> dict[str, str] | None:
+    """Classify one ancestor: a host-app record, or ``None`` for a wrapper."""
+    if _MAC_BUNDLE_MARKER in exe:
+        return {
+            "name": "Claude Desktop",
+            "version": _mac_bundle_version(exe) or "unknown",
+            "evidence": exe,
+        }
+    windows_version = _windows_path_version(exe)
+    if windows_version:
+        return {"name": "Claude Desktop", "version": windows_version, "evidence": exe}
+    stem = _stem(name)
+    if stem in _WRAPPER_NAMES or _PYTHON_VERSIONED_RE.match(stem):
+        return None
+    # ``claude.exe`` is also Claude Code's Windows binary, so without the
+    # Desktop install layout in the path only the bare name is reported.
+    return {"name": name, "version": "unknown", "evidence": exe or name}
+
+
+def _stem(name: str) -> str:
+    lowered = name.lower()
+    for suffix in (".exe", ".cmd", ".bat"):
+        if lowered.endswith(suffix):
+            return lowered[: -len(suffix)]
+    return lowered
+
+
+def _mac_bundle_version(exe: str) -> str:
+    """``CFBundleShortVersionString`` of the ``.app`` bundle containing ``exe``."""
+    bundle_root = exe.split("/Contents/", 1)[0]
+    plist_path = Path(bundle_root) / "Contents" / "Info.plist"
+    try:
+        with plist_path.open("rb") as handle:
+            plist = plistlib.load(handle)
+    except (OSError, plistlib.InvalidFileException, ValueError) as exc:
+        logger.debug("Cannot read %s: %s", plist_path, exc)
+        return ""
+    version = plist.get("CFBundleShortVersionString")
+    return str(version) if version else ""
+
+
+def _windows_path_version(exe: str) -> str:
+    for pattern in _WINDOWS_VERSION_PATTERNS:
+        match = pattern.search(exe)
+        if match:
+            return match.group(1)
+    return ""

{ha_mcp_dev-8.5.0.dev2689 → ha_mcp_dev-8.5.0.dev2690/src/ha_mcp_dev.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.5.0.dev2689
+Version: 8.5.0.dev2690
 Summary: Home Assistant MCP Server - Complete control of Home Assistant through MCP
 Author-email: Julien <github@qc-h.net>
 License: MIT
@@ -33,6 +33,7 @@ Requires-Dist: jsonschema-path>=0.3.4
 Requires-Dist: openapi-pydantic>=0.5.1
 Requires-Dist: opentelemetry-api>=1.28.0
 Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: psutil>=7.0.0
 Requires-Dist: py-key-value-aio[filetree,keyring,memory]<0.5.0,>=0.4.4
 Requires-Dist: pydantic-settings>=2.0.0
 Requires-Dist: pyjwt[crypto]>=2.10.1

{ha_mcp_dev-8.5.0.dev2689 → ha_mcp_dev-8.5.0.dev2690}/src/ha_mcp_dev.egg-info/SOURCES.txt

@@ -707,6 +707,7 @@ src/ha_mcp/utils/domain_handlers.py
 src/ha_mcp/utils/entity_membership.py
 src/ha_mcp/utils/fuzzy_search.py
 src/ha_mcp/utils/kill_signal_diagnostics.py
+src/ha_mcp/utils/mcp_client_host.py
 src/ha_mcp/utils/operation_manager.py
 src/ha_mcp/utils/python_sandbox.py
 src/ha_mcp/utils/registry_update_lock.py

{ha_mcp_dev-8.5.0.dev2689 → ha_mcp_dev-8.5.0.dev2690}/src/ha_mcp_dev.egg-info/requires.txt

@@ -10,6 +10,7 @@ jsonschema-path>=0.3.4
 openapi-pydantic>=0.5.1
 opentelemetry-api>=1.28.0
 platformdirs>=4.0.0
+psutil>=7.0.0
 py-key-value-aio[filetree,keyring,memory]<0.5.0,>=0.4.4
 pydantic-settings>=2.0.0
 pyjwt[crypto]>=2.10.1