Address cubic review: by-name aliasing, return-annotation, callable-resolver naming

- tools/base.py: build tool_arg_names as 'alias or field_name' to match the
  runtime kwarg keys, so a by-name resolver param on an aliased field resolves
  instead of raising KeyError at call time.
- resolve.py: iterate inspect.signature params (not get_type_hints items, which
  include 'return') so a Resolve marker on a return annotation is ignored; add
  _resolver_name so callable-object resolvers raise InvalidSignature instead of
  AttributeError in error messages.
- migration.md: import DeclinedElicitation/CancelledElicitation used in the
  branching example so the snippet is runnable.

Add regression tests for each.

Author: Kludex

docs/migration.md

@@ -1435,7 +1435,15 @@ from typing import Annotated
 
 from pydantic import BaseModel
 
-from mcp.server.mcpserver import AcceptedElicitation, Context, Elicit, MCPServer, Resolve
+from mcp.server.mcpserver import (
+    AcceptedElicitation,
+    CancelledElicitation,
+    Context,
+    DeclinedElicitation,
+    Elicit,
+    MCPServer,
+    Resolve,
+)
 
 mcp = MCPServer(name="github")
 

src/mcp/server/mcpserver/resolve.py

@@ -100,15 +100,22 @@ def _type_hints(fn: Callable[..., Any]) -> dict[str, Any]:
         return {}
 
 
+def _resolver_name(fn: Callable[..., Any]) -> str:
+    """Best-effort display name for error messages (callable objects lack `__name__`)."""
+    return getattr(fn, "__name__", None) or type(fn).__name__
+
+
 def find_resolved_parameters(fn: Callable[..., Any]) -> dict[str, tuple[Resolve, bool]]:
     """Find parameters of `fn` annotated `Annotated[_, Resolve(...)]`.
 
     Returns a mapping of parameter name to `(Resolve, wants_union)`, where
     `wants_union` is True when the annotated type is an `ElicitationResult` member
     (the consumer wants the full outcome rather than the unwrapped model).
     """
+    hints = _type_hints(fn)
     resolved: dict[str, tuple[Resolve, bool]] = {}
-    for name, annotation in _type_hints(fn).items():
+    for name in inspect.signature(fn).parameters:
+        annotation = hints.get(name)
         if get_origin(annotation) is not Annotated:
             continue
         type_arg, *metadata = get_args(annotation)
@@ -140,7 +147,7 @@ def build_resolver_plans(
     def analyze(fn: Callable[..., Any], stack: tuple[int, ...]) -> None:
         key = id(fn)
         if key in stack:
-            raise InvalidSignature(f"Resolver {fn.__name__!r} has a cyclic dependency")
+            raise InvalidSignature(f"Resolver {_resolver_name(fn)!r} has a cyclic dependency")
         if key in plans:
             return
 
@@ -162,7 +169,7 @@ def analyze(fn: Callable[..., Any], stack: tuple[int, ...]) -> None:
                 params[param_name] = _ParamPlan("by_name")
                 continue
             raise InvalidSignature(
-                f"Resolver {fn.__name__!r} parameter {param_name!r} cannot be resolved: "
+                f"Resolver {_resolver_name(fn)!r} parameter {param_name!r} cannot be resolved: "
                 "expected a Context, an Annotated[_, Resolve(...)], or a tool argument by name"
             )
 

src/mcp/server/mcpserver/tools/base.py

@@ -92,9 +92,9 @@ def from_function(
         )
         parameters = func_arg_metadata.arg_model.model_json_schema(by_alias=True)
 
-        tool_arg_names = set(func_arg_metadata.arg_model.model_fields) | {
-            field.alias for field in func_arg_metadata.arg_model.model_fields.values() if field.alias
-        }
+        # Match `model_dump_one_level`'s kwarg keys (alias when present, else field name)
+        # so a by-name resolver param resolves to a key that exists at call time.
+        tool_arg_names = {field.alias or name for name, field in func_arg_metadata.arg_model.model_fields.items()}
         resolver_plans = build_resolver_plans(resolved_params, tool_arg_names)
 
         return cls(

tests/server/mcpserver/test_resolve.py

@@ -272,3 +272,45 @@ async def tool(login: Annotated[Login, Resolve(login)]) -> str:
 
     with pytest.raises(InvalidSignature, match="cannot be resolved"):
         Tool.from_function(tool)
+
+
+def test_resolve_marker_on_return_annotation_is_ignored():
+    async def login(ctx: Context) -> Login:
+        return Login(username="x")  # pragma: no cover
+
+    async def tool(repo: str) -> Annotated[str, Resolve(login)]:
+        return repo  # pragma: no cover
+
+    assert find_resolved_parameters(tool) == {}
+
+
+def test_callable_object_resolver_error_uses_type_name():
+    class BadResolver:
+        async def __call__(self, mystery: int) -> Login:
+            return Login(username="x")  # pragma: no cover
+
+    async def tool(login: Annotated[Login, Resolve(BadResolver())]) -> str:
+        return login.username  # pragma: no cover
+
+    with pytest.raises(InvalidSignature, match="'BadResolver'"):
+        Tool.from_function(tool)
+
+
+@pytest.mark.anyio
+async def test_by_name_resolver_param_uses_aliased_tool_arg():
+    mcp = MCPServer(name="Aliased")
+
+    # `schema` collides with a BaseModel attribute, so func_metadata aliases the field;
+    # the runtime kwarg key is the alias, which is what a by-name resolver must match.
+    async def upper(schema: str) -> Login:
+        return Login(username=schema.upper())
+
+    @mcp.tool()
+    async def run(schema: str, shouted: Annotated[Login, Resolve(upper)]) -> str:
+        return shouted.username
+
+    async def never(context: ClientRequestContext, params: ElicitRequestParams) -> ElicitResult:  # pragma: no cover
+        raise AssertionError("should not elicit")
+
+    async with Client(mcp, mode="legacy", elicitation_callback=never) as client:
+        assert await _text(client, "run", {"schema": "gpt"}) == "GPT"