Make ElicitationResult subscriptable so the documented Resolve union form works

Codex review caught that the documented Annotated[ElicitationResult[Login],
Resolve(login)] form silently dropped the resolver: ElicitationResult was a
collapsed union alias (not subscriptable), so under 'from __future__ import
annotations' get_type_hints raised, _type_hints swallowed it, and the parameter
stayed client-supplied with the resolver never running.

Redefine ElicitationResult via TypeAliasType so ElicitationResult[T] is
genuinely subscriptable, and teach _wants_union to unwrap the alias. Update the
migration doc to use the clean ElicitationResult[T] form. Add a regression test
exercising the postponed-annotations path.

Author: Kludex

docs/migration.md

@@ -1476,13 +1476,14 @@ async def star_repo(
     return f"starred {repo} as {login.username}" if confirm.ok else "cancelled"
 ```
 
-The injected type follows the consumer's annotation. Annotating the unwrapped model (`Annotated[Login, Resolve(login)]`) injects the model on accept and aborts the call with an error result on decline or cancel. To branch on the outcome instead, annotate the elicitation result union:
+The injected type follows the consumer's annotation. Annotating the unwrapped model (`Annotated[Login, Resolve(login)]`) injects the model on accept and aborts the call with an error result on decline or cancel. To branch on the outcome instead, annotate `ElicitationResult[Login]` (or an explicit `AcceptedElicitation[Login] | DeclinedElicitation | CancelledElicitation` union):
 
 ```python
+from mcp.server.mcpserver import ElicitationResult
+
+
 @mcp.tool()
-async def whoami(
-    login: Annotated[AcceptedElicitation[Login] | DeclinedElicitation | CancelledElicitation, Resolve(login)],
-) -> str:
+async def whoami(login: Annotated[ElicitationResult[Login], Resolve(login)]) -> str:
     match login:
         case AcceptedElicitation(data=data):
             return f"hi {data.username}"

src/mcp/server/elicitation.py

@@ -7,6 +7,7 @@
 from pydantic import BaseModel, ValidationError
 from pydantic.json_schema import GenerateJsonSchema, JsonSchemaValue
 from pydantic_core import core_schema
+from typing_extensions import TypeAliasType
 
 from mcp.server.session import ServerSession
 from mcp.types import RequestId
@@ -36,7 +37,11 @@ class CancelledElicitation(BaseModel):
     action: Literal["cancel"] = "cancel"
 
 
-ElicitationResult = AcceptedElicitation[ElicitSchemaModelT] | DeclinedElicitation | CancelledElicitation
+ElicitationResult = TypeAliasType(
+    "ElicitationResult",
+    AcceptedElicitation[ElicitSchemaModelT] | DeclinedElicitation | CancelledElicitation,
+    type_params=(ElicitSchemaModelT,),
+)
 
 
 class AcceptedUrlElicitation(BaseModel):

src/mcp/server/mcpserver/resolve.py

@@ -126,7 +126,16 @@ def find_resolved_parameters(fn: Callable[..., Any]) -> dict[str, tuple[Resolve,
 
 
 def _wants_union(type_arg: Any) -> bool:
-    """True when `type_arg` is an `ElicitationResult` member (or a union of them)."""
+    """True when `type_arg` is an `ElicitationResult` member (or a union of them).
+
+    Handles the bare `ElicitationResult[T]` alias (a `TypeAliasType` carrying the
+    union on `__value__`), an explicit `AcceptedElicitation[T] | ... ` union, and a
+    single member.
+    """
+    origin = get_origin(type_arg)
+    value = getattr(origin, "__value__", None)
+    if value is not None:
+        type_arg = value
     members = get_args(type_arg) if get_origin(type_arg) is not None else (type_arg,)
     return any(isinstance(m, type) and issubclass(m, _ELICITATION_RESULT_MEMBERS) for m in members)
 

tests/server/mcpserver/test_resolve.py

@@ -13,6 +13,7 @@
     Context,
     DeclinedElicitation,
     Elicit,
+    ElicitationResult,
     MCPServer,
     Resolve,
 )
@@ -30,6 +31,10 @@ class Confirm(BaseModel):
     ok: bool
 
 
+async def _alias_login(ctx: Context) -> Login:
+    return Login(username="x")  # pragma: no cover - only the signature is inspected
+
+
 def _accept(content: dict[str, str | int | float | bool | list[str] | None]):
     async def callback(context: ClientRequestContext, params: ElicitRequestParams) -> ElicitResult:
         return ElicitResult(action="accept", content=content)
@@ -92,9 +97,7 @@ async def login(ctx: Context) -> Login | Elicit[Login]:
         return Elicit("GitHub username?", Login)
 
     @mcp.tool()
-    async def whoami(
-        login: Annotated[AcceptedElicitation[Login] | DeclinedElicitation | CancelledElicitation, Resolve(login)],
-    ) -> str:
+    async def whoami(login: Annotated[ElicitationResult[Login], Resolve(login)]) -> str:
         match login:
             case AcceptedElicitation(data=data):
                 return f"hi {data.username}"
@@ -263,6 +266,20 @@ def fn(x: int) -> int:
     assert find_resolved_parameters(fn) == {}
 
 
+def test_elicitation_result_alias_resolves_under_postponed_annotations():
+    # Reproduces the case where `from __future__ import annotations` stringifies
+    # `Annotated[ElicitationResult[Login], Resolve(_alias_login)]`: the alias must be
+    # subscriptable so the resolver is detected (not silently dropped) and the
+    # consumer is recognized as wanting the result union.
+    def tool(login: str) -> str:
+        return login  # pragma: no cover
+
+    tool.__annotations__["login"] = "Annotated[ElicitationResult[Login], Resolve(_alias_login)]"
+    resolved = find_resolved_parameters(tool)
+    assert "login" in resolved
+    assert resolved["login"][1] is True  # wants_union
+
+
 def test_unresolvable_resolver_param_raises_at_registration():
     async def login(mystery: int) -> Login:
         return Login(username="x")  # pragma: no cover