fix: catch fastmcp 3.4.3's wrapped ValidationError in arg-validation middleware (#1757)

fastmcp 3.4.3 (tools/function_tool.py) re-raises an argument-validation
pydantic.ValidationError as fastmcp.exceptions.ValidationError, chained via
`from e`. ValidationErrorMiddleware only caught pydantic.ValidationError, so
under 3.4.3 the raw wrapped error propagated instead of ha-mcp's structured,
actionable ToolError (3 tests in test_validation_middleware.py failed once
fastmcp was bumped in #1753).

Catch both exception shapes and recover the pydantic errors from the
FastMCPValidationError's __cause__; re-raise any fastmcp ValidationError with no
pydantic cause (e.g. a return-value failure) unchanged. Cross-version safe: a
bare pydantic.ValidationError on older fastmcp is still handled directly.

Adds a version-independent regression test that synthesises the wrapped error so
the 3.4.3 path is exercised on the current (3.4.2) CI, not only once #1753 lands.

Co-authored-by: kingpanther13 <kingpanther13@users.noreply.github.com>
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: kingpanther13

src/ha_mcp/tools/validation_middleware.py

@@ -1,16 +1,19 @@
 """FastMCP middleware that converts Pydantic 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 raises a PydanticValidationError with a raw message
-like "Input should be a valid dictionary". This middleware intercepts those errors
-and converts them to ha-mcp's structured format with actionable guidance.
+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.
 """
 
 from __future__ import annotations
 
 import logging
 from typing import Any
 
+from fastmcp.exceptions import ValidationError as FastMCPValidationError
 from fastmcp.server.middleware.middleware import CallNext, Middleware, MiddlewareContext
 from pydantic import ValidationError as PydanticValidationError
 
@@ -40,9 +43,20 @@ async def on_call_tool(
         self, context: MiddlewareContext, call_next: CallNext
     ) -> Any:
         try:
-            return await call_next(context)
-        except PydanticValidationError as exc:
-            errors = exc.errors(include_url=False)
+            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` /
@@ -73,3 +87,4 @@ async def on_call_tool(
                     details=", ".join(dict.fromkeys(err["type"] for err in errors)),
                 )
             )
+        return result

tests/src/unit/test_validation_middleware.py

@@ -32,6 +32,39 @@ async def ha_test_two_params(config: dict, items: list) -> dict:
     return mcp
 
 
+@pytest.mark.asyncio
+async def test_wrapped_fastmcp_validation_error_is_structured():
+    """fastmcp >= 3.4.3 wraps an arg-validation pydantic error in
+    ``fastmcp.exceptions.ValidationError`` (chained via ``from e``); the
+    middleware must recover the pydantic cause and still emit a structured
+    ToolError. Version-independent: the wrapped error is synthesised, so this
+    exercises the 3.4.3 code path even on older fastmcp.
+    """
+    from fastmcp.exceptions import ValidationError as FastMCPValidationError
+    from pydantic import BaseModel
+    from pydantic import ValidationError as PydanticValidationError
+
+    class _Args(BaseModel):
+        config: dict
+
+    with pytest.raises(PydanticValidationError) as pyd_info:
+        _Args(config="{}")  # str where a dict is required -> dict_type error
+
+    wrapped = FastMCPValidationError(str(pyd_info.value))
+    wrapped.__cause__ = pyd_info.value
+
+    async def _raise_wrapped(_context):
+        raise wrapped
+
+    middleware = ValidationErrorMiddleware()
+    with pytest.raises(ToolError) as exc_info:
+        await middleware.on_call_tool(None, _raise_wrapped)
+
+    msg = json.loads(str(exc_info.value))["error"]["message"]
+    assert "config" in msg
+    assert "JSON object" in msg
+
+
 @pytest.mark.asyncio
 async def test_string_for_dict_gives_actionable_message():
     """Passing a JSON string where a dict is expected raises a structured ToolError."""