ha-mcp-dev 8.4.3.dev2664__tar.gz → 8.4.3.dev2669__tar.gz

{ha_mcp_dev-8.4.3.dev2664/src/ha_mcp_dev.egg-info → ha_mcp_dev-8.4.3.dev2669}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: ha-mcp-dev
-Version: 8.4.3.dev2664
+Version: 8.4.3.dev2669
 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.4.3.dev2664 → ha_mcp_dev-8.4.3.dev2669}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "ha-mcp-dev"
-version = "8.4.3.dev2664"
+version = "8.4.3.dev2669"
 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.4.3.dev2664 → ha_mcp_dev-8.4.3.dev2669}/src/ha_mcp/dashboard_screenshot/paths.py

@@ -34,7 +34,7 @@ _DECODE_URI_RESERVED_VIEW_CHARS = frozenset("$&+,:;=")
 class DashboardRenderTarget:
     """Resolved frontend route and audit metadata for a screenshot request."""
 
-    dashboard_url_path: str
+    url_path: str
     view_path: str | None
     render_path: str
     view_index: int | None
@@ -152,7 +152,7 @@ def _render_path_metadata(
         render_path = _normalize_dashboard_path(f"{base_path}/{fallback_suffix}")
 
     metadata: dict[str, Any] = {
-        "dashboard_url_path": base_path,
+        "url_path": base_path,
         "view_index": index,
         "view_path": stable_path,
         "title": view_config.get("title"),
@@ -181,7 +181,7 @@ def dashboard_render_paths(
         return (
             [
                 {
-                    "dashboard_url_path": base_path,
+                    "url_path": base_path,
                     "view_index": None,
                     "view_path": None,
                     "title": None,
@@ -252,7 +252,7 @@ def _fallback_view_target(
     """Build one verified numeric fallback target for an unusable named path."""
     fallback_suffix = _numeric_fallback_suffix(view_index, views)
     return DashboardRenderTarget(
-        dashboard_url_path=base_path,
+        url_path=base_path,
         view_path=view_path,
         render_path=_normalize_dashboard_path(f"{base_path}/{fallback_suffix}"),
         view_index=view_index,
@@ -264,11 +264,9 @@ def _fallback_view_target(
     )
 
 
-async def fetch_dashboard_render_config(
-    client: Any, dashboard_url_path: str
-) -> dict[str, Any]:
+async def fetch_dashboard_render_config(client: Any, url_path: str) -> dict[str, Any]:
     """Fetch a Lovelace dashboard config for stable view-path resolution."""
-    base_path = dashboard_frontend_path(dashboard_url_path)
+    base_path = dashboard_frontend_path(url_path)
     request: dict[str, Any] = {"type": "lovelace/config", "force": True}
     if base_path != "lovelace":
         request["url_path"] = base_path
@@ -281,10 +279,9 @@ async def fetch_dashboard_render_config(
         raise_tool_error(
             create_error_response(
                 ErrorCode.CONNECTION_FAILED,
-                f"Could not load dashboard '{dashboard_url_path}' for view-path "
-                "resolution.",
+                f"Could not load dashboard '{url_path}' for view-path resolution.",
                 details=str(exc),
-                context={"dashboard_url_path": dashboard_url_path},
+                context={"url_path": url_path},
                 suggestions=[
                     "Check the Home Assistant connection",
                     "Retry with legacy dashboard_path if you already know the frontend route",
@@ -310,8 +307,8 @@ async def fetch_dashboard_render_config(
             raise_tool_error(
                 create_error_response(
                     ErrorCode.RESOURCE_NOT_FOUND,
-                    f"Could not load dashboard '{dashboard_url_path}': {message}",
-                    context={"dashboard_url_path": dashboard_url_path},
+                    f"Could not load dashboard '{url_path}': {message}",
+                    context={"url_path": url_path},
                     suggestions=[
                         "Use ha_config_get_dashboard(list_only=True) to list dashboard URL paths"
                     ],
@@ -320,9 +317,9 @@ async def fetch_dashboard_render_config(
         raise_tool_error(
             create_error_response(
                 ErrorCode.SERVICE_CALL_FAILED,
-                f"Failed to load dashboard '{dashboard_url_path}': {message}",
+                f"Failed to load dashboard '{url_path}': {message}",
                 context={
-                    "dashboard_url_path": dashboard_url_path,
+                    "url_path": url_path,
                     "home_assistant_error_code": error_code or None,
                 },
                 suggestions=[
@@ -337,9 +334,9 @@ async def fetch_dashboard_render_config(
         raise_tool_error(
             create_error_response(
                 ErrorCode.SERVICE_CALL_FAILED,
-                f"Dashboard '{dashboard_url_path}' returned an invalid config payload.",
+                f"Dashboard '{url_path}' returned an invalid config payload.",
                 context={
-                    "dashboard_url_path": dashboard_url_path,
+                    "url_path": url_path,
                     "payload_type": type(config).__name__,
                 },
             )
@@ -348,7 +345,7 @@ async def fetch_dashboard_render_config(
 
 
 def match_dashboard_view(
-    dashboard_url_path: str,
+    url_path: str,
     config: dict[str, Any],
     view_path: str,
     *,
@@ -382,7 +379,7 @@ def match_dashboard_view(
                 ErrorCode.VALIDATION_INVALID_PARAMETER,
                 "Strategy dashboards do not expose static named view paths.",
                 context={
-                    "dashboard_url_path": dashboard_url_path,
+                    "url_path": url_path,
                     "view_path": view_path,
                 },
                 suggestions=list(strategy_suggestions),
@@ -408,7 +405,7 @@ def match_dashboard_view(
                 ErrorCode.RESOURCE_NOT_FOUND,
                 f"Dashboard view path '{view_path}' is {reason}.",
                 context={
-                    "dashboard_url_path": dashboard_url_path,
+                    "url_path": url_path,
                     "view_path": view_path,
                     "available_view_paths": available,
                 },
@@ -419,12 +416,12 @@ def match_dashboard_view(
 
 
 def resolve_dashboard_view(
-    dashboard_url_path: str,
+    url_path: str,
     config: dict[str, Any],
     view_path: str | None,
 ) -> DashboardRenderTarget:
     """Resolve one named Lovelace view to a canonical frontend route."""
-    base_path = dashboard_frontend_path(dashboard_url_path)
+    base_path = dashboard_frontend_path(url_path)
     if view_path is None:
         views = config.get("views")
         has_static_views = isinstance(views, list) and bool(views)
@@ -444,7 +441,7 @@ def resolve_dashboard_view(
                 "only the base route is available."
             )
         return DashboardRenderTarget(
-            dashboard_url_path=base_path,
+            url_path=base_path,
             view_path=None,
             render_path=base_path,
             view_index=None,
@@ -452,7 +449,7 @@ def resolve_dashboard_view(
             warnings=(warning,),
         )
 
-    view_index, _ = match_dashboard_view(dashboard_url_path, config, view_path)
+    view_index, _ = match_dashboard_view(url_path, config, view_path)
     cleaned_view_path = view_path
     views = config.get("views")
     if not isinstance(views, list):
@@ -477,7 +474,7 @@ def resolve_dashboard_view(
             ),
         )
     return DashboardRenderTarget(
-        dashboard_url_path=base_path,
+        url_path=base_path,
         view_path=cleaned_view_path,
         render_path=render_path,
         view_index=view_index,
@@ -497,7 +494,7 @@ async def _resolve_legacy_dashboard_target(
             create_error_response(
                 ErrorCode.VALIDATION_INVALID_PARAMETER,
                 f"Raw view suffix '{parts[1]}' is reserved by Home Assistant.",
-                context={"dashboard_url_path": dashboard_root},
+                context={"url_path": dashboard_root},
             )
         )
     validated_config = await _validate_legacy_dashboard_root(client, render_path)
@@ -505,7 +502,7 @@ async def _resolve_legacy_dashboard_target(
         raw_view = parts[1] if len(parts) > 1 else None
         numeric_index = _numeric_view_index(raw_view) if raw_view is not None else None
         return DashboardRenderTarget(
-            dashboard_url_path="lovelace",
+            url_path="lovelace",
             view_path=None,
             render_path=render_path,
             view_index=numeric_index,
@@ -521,7 +518,7 @@ async def _resolve_legacy_dashboard_target(
     raw_view = parts[1]
     if "strategy" in validated_config:
         return DashboardRenderTarget(
-            dashboard_url_path=dashboard_root,
+            url_path=dashboard_root,
             view_path=None,
             render_path=render_path,
             view_index=None,
@@ -545,7 +542,7 @@ async def _resolve_legacy_dashboard_target(
                     ErrorCode.RESOURCE_NOT_FOUND,
                     f"Dashboard view path '{raw_view}' was not found.",
                     context={
-                        "dashboard_url_path": dashboard_root,
+                        "url_path": dashboard_root,
                         "view_path": raw_view,
                         "available_view_paths": [
                             path
@@ -562,7 +559,7 @@ async def _resolve_legacy_dashboard_target(
         duplicate_count = sum(_configured_view_path(view) == raw_view for view in views)
         if duplicate_count > 1:
             return DashboardRenderTarget(
-                dashboard_url_path=dashboard_root,
+                url_path=dashboard_root,
                 view_path=raw_view,
                 render_path=_normalize_dashboard_path(f"{dashboard_root}/{raw_view}"),
                 view_index=view_index,
@@ -584,7 +581,7 @@ async def _resolve_legacy_dashboard_target(
                 ErrorCode.RESOURCE_NOT_FOUND,
                 f"Dashboard view index '{raw_view}' was not found.",
                 context={
-                    "dashboard_url_path": dashboard_root,
+                    "url_path": dashboard_root,
                     "view_index": numeric_index,
                     "available_view_count": len(views)
                     if isinstance(views, list)
@@ -606,10 +603,10 @@ async def _resolve_legacy_dashboard_target(
     if not warnings:
         warnings.append(
             f"Numeric view index '{render_path}' is fragile; assign the view a "
-            "unique views[].path and use dashboard_url_path/view_path addressing."
+            "unique views[].path and use url_path/view_path addressing."
         )
     return DashboardRenderTarget(
-        dashboard_url_path=dashboard_root,
+        url_path=dashboard_root,
         view_path=None,
         render_path=render_path,
         view_index=view_index,
@@ -622,44 +619,44 @@ async def resolve_dashboard_render_target(
     client: Any,
     *,
     dashboard_path: str | None,
-    dashboard_url_path: str | None,
+    url_path: str | None,
     view_path: str | None,
 ) -> DashboardRenderTarget:
     """Resolve legacy raw or structured screenshot addressing."""
-    if dashboard_path is not None and dashboard_url_path is not None:
+    if dashboard_path is not None and url_path is not None:
         raise_tool_error(
             create_error_response(
                 ErrorCode.VALIDATION_INVALID_PARAMETER,
-                "Use dashboard_path or dashboard_url_path/view_path, not both.",
+                "Use dashboard_path or url_path/view_path, not both.",
                 context={
                     "dashboard_path": dashboard_path,
-                    "dashboard_url_path": dashboard_url_path,
+                    "url_path": url_path,
                     "view_path": view_path,
                 },
             )
         )
-    if dashboard_url_path is None:
+    if url_path is None:
         if view_path is not None:
             raise_tool_error(
                 create_error_response(
                     ErrorCode.VALIDATION_MISSING_PARAMETER,
-                    "dashboard_url_path is required when view_path is supplied.",
+                    "url_path is required when view_path is supplied.",
                     context={"view_path": view_path},
                 )
             )
         return await _resolve_legacy_dashboard_target(client, dashboard_path)
 
-    if not dashboard_url_path.strip():
+    if not url_path.strip():
         raise_tool_error(
             create_error_response(
                 ErrorCode.VALIDATION_INVALID_PARAMETER,
-                "dashboard_url_path cannot be empty.",
-                context={"dashboard_url_path": dashboard_url_path},
+                "url_path cannot be empty.",
+                context={"url_path": url_path},
             )
         )
-    if dashboard_frontend_path(dashboard_url_path) == "lovelace" and view_path is None:
+    if dashboard_frontend_path(url_path) == "lovelace" and view_path is None:
         return DashboardRenderTarget(
-            dashboard_url_path="lovelace",
+            url_path="lovelace",
             view_path=None,
             render_path="lovelace",
             view_index=None,
@@ -669,8 +666,8 @@ async def resolve_dashboard_render_target(
                 "renders the first view visible to Puppet's Home Assistant user.",
             ),
         )
-    config = await fetch_dashboard_render_config(client, dashboard_url_path)
-    return resolve_dashboard_view(dashboard_url_path, config, view_path)
+    config = await fetch_dashboard_render_config(client, url_path)
+    return resolve_dashboard_view(url_path, config, view_path)
 
 
 async def _validate_legacy_dashboard_root(
@@ -715,12 +712,12 @@ async def _numeric_view_warning(
     parts = render_path.split("/", maxsplit=1)
     if len(parts) < 2:
         return []
-    dashboard_url_path, raw_view = parts
+    url_path, raw_view = parts
     index = _numeric_view_index(raw_view)
     if index is None:
         return []
     if config is None:
-        config = await fetch_dashboard_render_config(client, dashboard_url_path)
+        config = await fetch_dashboard_render_config(client, url_path)
     views = config.get("views")
     if not isinstance(views, list):
         return []
@@ -740,12 +737,10 @@ async def _numeric_view_warning(
     ]
     if matching_paths.count(stable_path) != 1:
         return []
-    canonical = _safe_named_render_path(
-        dashboard_frontend_path(dashboard_url_path), stable_path
-    )
+    canonical = _safe_named_render_path(dashboard_frontend_path(url_path), stable_path)
     if canonical is None:
         return []
     return [
         f"Numeric view index '{render_path}' is fragile; use the stable render "
-        + f"path '{canonical}' or dashboard_url_path/view_path addressing."
+        + f"path '{canonical}' or url_path/view_path addressing."
     ]

{ha_mcp_dev-8.4.3.dev2664 → ha_mcp_dev-8.4.3.dev2669}/src/ha_mcp/tools/smart_search/_deep.py

@@ -1085,8 +1085,8 @@ class DeepSearchMixin(SceneSearchMixin):
                 else (match.get("title") or url_path)
             )
             records[url_path] = {
-                "dashboard_url": url_path,
-                "dashboard_title": title,
+                "url_path": url_path,
+                "title": title,
                 "score": 100,
                 "match_in_config": True,
                 # Dashboards are not a search/related item type, so this is
@@ -1163,8 +1163,8 @@ class DeepSearchMixin(SceneSearchMixin):
                 if config_score >= threshold:
                     return [
                         {
-                            "dashboard_url": url_path,
-                            "dashboard_title": title,
+                            "url_path": url_path,
+                            "title": title,
                             "score": config_score,
                             "match_in_config": True,
                             "match_in_references": False,

{ha_mcp_dev-8.4.3.dev2664 → ha_mcp_dev-8.4.3.dev2669}/src/ha_mcp/tools/tools_config_dashboards.py

@@ -1811,7 +1811,7 @@ class DashboardConfigTools:
         force_reload: Annotated[
             bool,
             Field(
-                description="Force reload from storage (bypass cache). Not applicable in search mode (search always uses force=True for fresh results)."
+                description="Force reload from storage (bypass cache). Not applicable in search mode, which always reads fresh config."
             ),
         ] = False,
         entity_id: Annotated[
@@ -1914,7 +1914,7 @@ class DashboardConfigTools:
           python_transform=f'config{m["python_path"]}["icon"] = "mdi:x"' (it is
           NOT valid on its own without the `config` prefix). jq_path is the same
           location in jq dot-notation.
-          Multiple criteria are AND-ed. Always fetches fresh config (force=True).
+          Multiple criteria are AND-ed. Always fetches fresh config, bypassing the cache.
           Search covers cards/card/custom_fields/states containers up to a depth
           bound; if the dashboard carries a non-traversed child-bearing shape
           (e.g. picture-elements `elements`), the result carries a `warnings`

{ha_mcp_dev-8.4.3.dev2664 → ha_mcp_dev-8.4.3.dev2669}/src/ha_mcp/tools/tools_dashboard_screenshot.py

@@ -38,6 +38,7 @@ from ..dashboard_screenshot.content import (
     dashboard_screenshot_warnings,
 )
 from ..dashboard_screenshot.paths import (
+    DashboardRenderTarget,
     resolve_dashboard_render_target,
 )
 from ..errors import ErrorCode, create_error_response
@@ -50,7 +51,7 @@ logger = logging.getLogger(__name__)
 def _package_screenshot_result(
     *,
     captures: list[Any],
-    target: Any,
+    target: DashboardRenderTarget,
     capture_failures: list[dict[str, Any]],
     capture_warnings: list[str],
 ) -> ToolResult:
@@ -58,7 +59,7 @@ def _package_screenshot_result(
     try:
         structured_content: dict[str, Any] = {
             "success": True,
-            "dashboard_url_path": target.dashboard_url_path,
+            "url_path": target.url_path,
             "view_path": target.view_path,
             "view_index": target.view_index,
             "render_path": target.render_path,
@@ -123,11 +124,11 @@ class DashboardScreenshotTools:
                 description="Legacy Lovelace frontend path to render, e.g. "
                 "'lovelace/0' (default dashboard, first view), "
                 "'lovelace-home/kitchen', or 'my-dashboard'. Leading slash "
-                "optional. Prefer dashboard_url_path + view_path for a stable "
-                "named view. Mutually exclusive with dashboard_url_path."
+                "optional. Prefer url_path + view_path for a stable "
+                "named view. Mutually exclusive with url_path."
             ),
         ] = None,
-        dashboard_url_path: Annotated[
+        url_path: Annotated[
             str | None,
             Field(
                 description="Stable dashboard URL path, e.g. 'lovelace-home' "
@@ -138,7 +139,7 @@ class DashboardScreenshotTools:
             str | None,
             Field(
                 description="Stable Lovelace views[].path value to render. "
-                "Requires dashboard_url_path."
+                "Requires url_path."
             ),
         ] = None,
         width: Annotated[
@@ -246,7 +247,7 @@ class DashboardScreenshotTools:
         target = await resolve_dashboard_render_target(
             self._client,
             dashboard_path=dashboard_path,
-            dashboard_url_path=dashboard_url_path,
+            url_path=url_path,
             view_path=view_path,
         )
         validate_capture_parameters(

{ha_mcp_dev-8.4.3.dev2664 → ha_mcp_dev-8.4.3.dev2669}/src/ha_mcp/tools/tools_search.py

@@ -1178,7 +1178,7 @@ def _dashboard_split_serviceable(req: _ResolvedSearch, caps: Any) -> bool:
 class _DashboardLeg:
     """The dashboards surface's contribution to a component-served ha_search.
 
-    ``records`` are legacy-shaped (``dashboard_url`` / ``dashboard_title`` /
+    ``records`` are legacy-shaped (``url_path`` / ``title`` /
     ``score``), NOT component records — they never pass through
     ``_normalize_component_config_record``. ``failed`` is the leg's own
     "not scanned" count, reported with the deep path's wording. ``error`` is
@@ -1226,13 +1226,13 @@ def _merge_sort_key(record: dict[str, Any]) -> str:
     the wire records unchanged, so the merge reproduces the exact order that
     decided window membership. Dashboard records are outside the component
     corpus, so any deterministic key places them consistently across pages —
-    ``dashboard_url`` extends the same chain.
+    ``url_path`` extends the same chain.
     """
     return str(
         record.get("entity_id")
         or record.get("id")
         or record.get("name")
-        or record.get("dashboard_url")
+        or record.get("url_path")
         or ""
     )
 

ha_mcp_dev-8.4.3.dev2669/src/ha_mcp/tools/validation_middleware.py

@@ -0,0 +1,195 @@
+"""FastMCP middleware that converts argument-validation errors to structured ToolErrors.
+
+When a model passes the wrong type for a tool parameter (e.g. a JSON string where
+a dict is required), FastMCP surfaces a validation error with a raw message like
+"Input should be a valid dictionary" -- a bare ``pydantic.ValidationError`` on
+older FastMCP, or a ``fastmcp.exceptions.ValidationError`` wrapping it (chained
+via ``from e``) on FastMCP >= 3.4.3. This middleware intercepts either shape and
+converts it to ha-mcp's structured format with actionable guidance. When the
+tool's schema can be read, an argument name the tool does not declare is
+reported with the closest declared parameter, if one resembles it, and the full
+parameter list.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections.abc import Sequence
+from difflib import SequenceMatcher
+from typing import Any
+
+from pydantic import ValidationError as PydanticValidationError
+from pydantic_core import ErrorDetails
+
+from ha_mcp._vendor.fastmcp.exceptions import ValidationError as FastMCPValidationError
+from ha_mcp._vendor.fastmcp.server.middleware.middleware import (
+    CallNext,
+    Middleware,
+    MiddlewareContext,
+)
+
+from ..errors import create_validation_error
+from .helpers import raise_tool_error
+
+logger = logging.getLogger(__name__)
+
+# Maps Pydantic error types to model-readable fix hints.
+# FastMCP uses non-strict Pydantic: scalar mismatches (bool, int) are coerced
+# rather than rejected, so only dict_type and list_type fire among type errors.
+_TYPE_HINTS: dict[str, str] = {
+    "dict_type": (
+        "expected a JSON object. "
+        'Pass {"key": "value"} directly, not a JSON-encoded string.'
+    ),
+    "list_type": (
+        "expected a JSON array. Pass [...] directly, not a JSON-encoded string."
+    ),
+}
+
+_UNKNOWN_ARGUMENT = "unexpected_keyword_argument"
+
+
+async def _tool_parameter_names(context: MiddlewareContext | None) -> list[str] | None:
+    """Return the called tool's declared parameter names, or None if unavailable."""
+    fastmcp_context = getattr(context, "fastmcp_context", None)
+    tool_name = getattr(getattr(context, "message", None), "name", None)
+    if fastmcp_context is None or not tool_name:
+        return None
+    try:
+        tool = await fastmcp_context.fastmcp.get_tool(tool_name)
+    except Exception:
+        logger.warning(
+            "Parameter lookup for %s failed; unknown-argument hint omitted",
+            tool_name,
+            exc_info=True,
+        )
+        return None
+    if tool is None:
+        logger.warning(
+            "Parameter lookup for %s returned no tool; unknown-argument hint omitted",
+            tool_name,
+        )
+        return None
+    properties = tool.parameters.get("properties")
+    if not isinstance(properties, dict):
+        logger.warning(
+            "No parameter schema for %s; unknown-argument hint omitted", tool_name
+        )
+        return None
+    return list(properties)
+
+
+def _closest_parameter(unknown: str, candidates: Sequence[str]) -> str | None:
+    """Return the declared parameter an invented argument name most likely meant.
+
+    A candidate qualifies by sharing an underscore-separated word with the name
+    (``dashboard_url`` for ``url_path``) or by a similarity ratio of at least
+    0.6 (typos). A declared name the invented one ends with ranks first
+    (``dashboard_url_path`` for ``url_path``), then more shared words; the ratio
+    breaks ties.
+    """
+    unknown_lower = unknown.lower()
+    words = set(unknown_lower.split("_")) - {""}
+    best: tuple[bool, int, float, str] | None = None
+    for candidate in candidates:
+        candidate_lower = candidate.lower()
+        shared = len(words & set(candidate_lower.split("_")))
+        ratio = SequenceMatcher(None, unknown_lower, candidate_lower).ratio()
+        if not shared and ratio < 0.6:
+            continue
+        suffix = unknown_lower.endswith(f"_{candidate_lower}")
+        if best is None or (suffix, shared, ratio) > best[:3]:
+            best = (suffix, shared, ratio, candidate)
+    return best[3] if best else None
+
+
+def _unknown_argument_hint(param: str, unclaimed: Sequence[str]) -> str:
+    """Name an undeclared argument, suggesting the parameter it likely meant."""
+    match = _closest_parameter(param, unclaimed)
+    return (
+        f"unknown parameter, did you mean `{match}`?" if match else "unknown parameter"
+    )
+
+
+def _type_hint(errs: Sequence[ErrorDetails]) -> str:
+    """Prefer a dict_type/list_type hint; else the first error's raw message."""
+    return next(
+        (_TYPE_HINTS[e["type"]] for e in errs if e["type"] in _TYPE_HINTS),
+        errs[0]["msg"],
+    )
+
+
+class ValidationErrorMiddleware(Middleware):
+    """Convert argument-validation failures into structured ToolErrors."""
+
+    async def on_call_tool(
+        self, context: MiddlewareContext, call_next: CallNext
+    ) -> Any:
+        try:
+            result = await call_next(context)
+        except (PydanticValidationError, FastMCPValidationError) as exc:
+            # fastmcp >= 3.4.3 re-raises an argument-validation failure as
+            # ``fastmcp.exceptions.ValidationError`` wrapping the pydantic error
+            # (chained via ``from e``); older fastmcp raises the pydantic error
+            # directly. Recover the pydantic errors from whichever shape arrived,
+            # and let any other fastmcp ValidationError (e.g. a return-value
+            # failure with no pydantic cause) propagate unchanged.
+            pydantic_exc = (
+                exc if isinstance(exc, PydanticValidationError) else exc.__cause__
+            )
+            if not isinstance(pydantic_exc, PydanticValidationError):
+                raise
+            errors = pydantic_exc.errors(include_url=False)
+            # Group by the real argument path. A union param like
+            # `str | list[str]` emits one error per arm with loc (param, "str"),
+            # (param, "list[str]"); without grouping the user saw `param.str` /
+            # `param.list[str]` instead of `param` (#1601). We keep the param
+            # name plus any numeric list indices (so a bad element still reports
+            # `monday.1`) but drop the non-numeric union-arm tags.
+            grouped: dict[str, list[ErrorDetails]] = {}
+            for err in errors:
+                loc = [str(p) for p in err.get("loc", ()) if p != "__root__"]
+                if loc:
+                    key = ".".join([loc[0], *(p for p in loc[1:] if p.isdigit())])
+                else:
+                    key = ""
+                grouped.setdefault(key, []).append(err)
+
+            valid_parameters = (
+                await _tool_parameter_names(context)
+                if any(err["type"] == _UNKNOWN_ARGUMENT for err in errors)
+                else None
+            )
+            unclaimed: list[str] = []
+            if valid_parameters is not None:
+                # Skip parameters the call already supplied: a second, invented
+                # argument almost never means one of them.
+                message_obj = getattr(context, "message", None)
+                supplied = getattr(message_obj, "arguments", None) or {}
+                unclaimed = [p for p in valid_parameters if p not in supplied]
+
+            parts: list[str] = []
+            for param, errs in grouped.items():
+                if (
+                    valid_parameters is not None
+                    and errs[0]["type"] == _UNKNOWN_ARGUMENT
+                ):
+                    hint = _unknown_argument_hint(param, unclaimed)
+                else:
+                    hint = _type_hint(errs)
+                parts.append(f"`{param}`: {hint}" if param else hint)
+            message = "; ".join(parts) if parts else "Invalid argument types."
+            error_context: dict[str, Any] | None = None
+            if valid_parameters is not None:
+                separator = " " if message.endswith((".", "?")) else ". "
+                listing = ", ".join(valid_parameters) or "none"
+                message += f"{separator}Valid parameters: {listing}."
+                error_context = {"valid_parameters": valid_parameters}
+            raise_tool_error(
+                create_validation_error(
+                    message,
+                    details=", ".join(dict.fromkeys(err["type"] for err in errors)),
+                    context=error_context,
+                )
+            )
+        return result

{ha_mcp_dev-8.4.3.dev2664 → ha_mcp_dev-8.4.3.dev2669/src/ha_mcp_dev.egg-info}/PKG-INFO

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