Tolerate lazily-evaluated type aliases in the input_required return check

Accessing `__value__` on a PEP 695 `type X = ...` alias evaluates it, so an
alias naming TYPE_CHECKING-only imports raised NameError at registration for
resolver-using tools that registered fine before the check existed. Such an
alias declares no arm the check can see; the in-call guard still covers a
body that returns an InputRequiredResult.

Also pin the neighboring shapes that already work: a subscripted generic
alias forwards `__value__` to its origin and is rejected, and a
parameterized builtin generic return registers on every supported Python.

Author: maxisbey

src/mcp/server/mcpserver/resolve.py

@@ -189,8 +189,15 @@ def _has_input_required_arm(annotation: Any) -> bool:
     """Walk an annotation's arms through `Annotated`, type aliases, and unions."""
     if get_origin(annotation) is Annotated:
         return _has_input_required_arm(get_args(annotation)[0])
-    # A `type X = ...` / `TypeAliasType` alias carries its target on `__value__`.
-    value = getattr(annotation, "__value__", None)
+    # A `type X = ...` / `TypeAliasType` alias carries its target on `__value__` (a
+    # subscripted alias forwards the attribute to its origin). The access evaluates
+    # a PEP 695 alias lazily, so an alias naming things unavailable at runtime
+    # (TYPE_CHECKING-only imports) raises NameError; such an alias declares no arm
+    # this check can see, and the in-call guard in `Tool.run` still covers it.
+    try:
+        value = getattr(annotation, "__value__", None)
+    except NameError:
+        return False
     if value is not None:
         return _has_input_required_arm(value)
     if _is_union(annotation):

tests/server/mcpserver/test_resolve.py

@@ -3,7 +3,7 @@
 import json
 from collections.abc import Callable
 from datetime import datetime
-from typing import Annotated, Any, Literal
+from typing import Annotated, Any, Literal, TypeVar
 
 import anyio
 import pytest
@@ -62,8 +62,20 @@ class Restock(BaseModel):
     needed: bool
 
 
-# The `type X = ...` spelling of an InputRequiredResult-bearing return annotation.
+# The `type X = ...` spelling of an InputRequiredResult-bearing return annotation,
+# bare and generic (a subscripted alias forwards `__value__` to its origin).
 IRRAlias = TypeAliasType("IRRAlias", InputRequiredResult | str)
+T_alias = TypeVar("T_alias")
+IRRAliasGeneric = TypeAliasType("IRRAliasGeneric", InputRequiredResult | T_alias, type_params=(T_alias,))
+
+
+class _UnevaluableAlias:
+    """Stand-in for `type X = GhostType | str` whose names exist only under
+    TYPE_CHECKING: accessing `__value__` evaluates the alias and raises."""
+
+    @property
+    def __value__(self) -> Any:
+        raise NameError("name 'GhostType' is not defined")
 
 
 class Handle(BaseModel):
@@ -1711,6 +1723,7 @@ def answer(key: str, params: ElicitRequestFormParams) -> ElicitResult:
         Annotated[InputRequiredResult | str, "meta"],
         str | Annotated[InputRequiredResult, "meta"],  # Annotated as a union member
         IRRAlias,  # `type X = ...` alias
+        IRRAliasGeneric[str],  # subscripted generic alias
     ],
 )
 def test_tool_combining_resolvers_with_input_required_return_is_rejected(annotation: Any):
@@ -1736,6 +1749,30 @@ async def manual() -> InputRequiredResult:
     assert returns_input_required(manual)
 
 
+def test_unevaluable_alias_and_parameterized_generics_declare_no_arm():
+    # A `type X = ...` alias is evaluated lazily, so one naming TYPE_CHECKING-only
+    # imports raises NameError on `__value__` access: it declares no arm the check
+    # can see and must not break registration (the in-call guard still covers a
+    # body that returns an InputRequiredResult anyway). A parameterized generic
+    # return is never the InputRequiredResult class either.
+    mcp = MCPServer(name="RegistrationTolerance")
+
+    async def lookup(ctx: Context) -> Login:
+        return Login(username="x")  # pragma: no cover - only registration is exercised
+
+    async def lazy(login: Annotated[Login, Resolve(lookup)]):
+        raise NotImplementedError  # pragma: no cover
+
+    lazy.__annotations__["return"] = _UnevaluableAlias()
+    assert not returns_input_required(lazy)
+
+    @mcp.tool()
+    async def listy(login: Annotated[Login, Resolve(lookup)]) -> list[str]:
+        raise NotImplementedError  # pragma: no cover
+
+    assert not returns_input_required(listy)
+
+
 @pytest.mark.anyio
 async def test_tool_returning_input_required_dynamically_with_resolvers_is_an_error():
     # The annotated form of this combination is rejected at registration; a body