fix: wrapped annotations handling in func_metadata

Use the original function's __globals__ for type hint resolution
when dealing with wrapped functions. This ensures that any type hints
defined in the original function's module are correctly resolved.

This also includes adding common typing names for resiliency.

Fixes #1391

Author: stevenh

src/mcp/server/fastmcp/utilities/func_metadata.py

@@ -1,8 +1,11 @@
+import functools
 import inspect
 import json
+import sys
+import typing as t
 from collections.abc import Awaitable, Callable, Sequence
 from itertools import chain
-from types import GenericAlias
+from types import GenericAlias, MethodType, ModuleType
 from typing import Annotated, Any, ForwardRef, cast, get_args, get_origin, get_type_hints
 
 import pydantic_core
@@ -468,10 +471,67 @@ def try_eval_type(value: Any, globalns: dict[str, Any], localns: dict[str, Any])
     return annotation
 
 
+def _resolve_callable_and_globalns(
+    callable_obj: Callable[..., object] | functools.partial[Any] | MethodType,
+) -> tuple[Callable[..., object], dict[str, object]]:
+    """Unwrap a possibly-decorated/partial/method callable.
+
+    Returns the original function and robust global namespace for type-hint evaluation.
+
+    Args:
+        callable_obj: A function, bound method, or functools.partial.
+
+    Returns:
+        (unwrapped_callable, globalns)
+    """
+    # Handle functools.partial
+    base: object = callable_obj.func if isinstance(callable_obj, functools.partial) else callable_obj
+
+    # Follow __wrapped__ chain (requires @functools.wraps in decorators)
+    unwrapped_obj: object = inspect.unwrap(cast(Callable[..., object], base))
+
+    # Handle bound methods
+    if inspect.ismethod(unwrapped_obj):
+        unwrapped_callable: Callable[..., object] = cast(MethodType, unwrapped_obj).__func__  # type: ignore[assignment]
+    else:
+        unwrapped_callable = cast(Callable[..., object], unwrapped_obj)
+
+    # Build globalns from module + function’s own globals
+    globalns: dict[str, object] = {}
+    module_name: str | None = getattr(unwrapped_callable, "__module__", None)  # type: ignore[attr-defined]
+    module_obj: ModuleType | None = sys.modules.get(module_name) if isinstance(module_name, str) else None
+    if module_obj is not None:
+        globalns.update(vars(module_obj))
+
+    func_globals: dict[str, object] | None = getattr(unwrapped_callable, "__globals__", None)  # type: ignore[attr-defined]
+    if isinstance(func_globals, dict):
+        globalns.update(func_globals)
+
+    # Seed common typing names for resilience
+    globalns.setdefault("typing", t)
+    for name in (
+        "Literal",
+        "Annotated",
+        "Optional",
+        "Union",
+        "Tuple",
+        "Dict",
+        "List",
+        "Set",
+        "Type",
+        "Callable",
+    ):
+        if name not in globalns and hasattr(t, name):
+            globalns[name] = getattr(t, name)  # type: ignore[index]
+
+    return unwrapped_callable, globalns
+
+
 def _get_typed_signature(call: Callable[..., Any]) -> inspect.Signature:
     """Get function signature while evaluating forward references"""
-    signature = inspect.signature(call)
-    globalns = getattr(call, "__globals__", {})
+    fn, globalns = _resolve_callable_and_globalns(call)
+    signature = inspect.signature(fn)
+
     typed_params = [
         inspect.Parameter(
             name=param.name,

tests/server/fastmcp/test_func_metadata.py

@@ -14,6 +14,8 @@
 
 from mcp.server.fastmcp.utilities.func_metadata import func_metadata
 
+from .test_wrapped import wrapped_function
+
 
 class SomeInputModelA(BaseModel):
     pass
@@ -1094,3 +1096,20 @@ def func_with_reserved_json(
     assert result["json"] == {"nested": "data"}
     assert result["model_dump"] == [1, 2, 3]
     assert result["normal"] == "plain string"
+
+
+@pytest.mark.anyio
+async def test_wrapped_annotations_func() -> None:
+    """Test that func_metadata works with wrapped annotations functions."""
+    meta = func_metadata(wrapped_function)
+
+    result = await meta.call_fn_with_arg_validation(
+        wrapped_function,
+        fn_is_async=False,
+        arguments_to_validate={
+            "literal": "test",
+        },
+        arguments_to_pass_directly=None,
+    )
+
+    assert result == "test"

tests/server/fastmcp/test_instrument.py

@@ -0,0 +1,21 @@
+from collections.abc import Callable
+from functools import wraps
+from typing import TypeVar
+
+from typing_extensions import ParamSpec
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+
+def instrument(func: Callable[P, R]) -> Callable[P, R]:
+    """
+    Example decorator that logs before/after the call
+    while preserving the original function's type signature.
+    """
+
+    @wraps(func)
+    def wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+        return func(*args, **kwargs)
+
+    return wrapper

tests/server/fastmcp/test_wrapped.py

@@ -0,0 +1,10 @@
+from __future__ import annotations
+
+from typing import Literal
+
+from .test_instrument import instrument
+
+
+@instrument
+def wrapped_function(literal: Literal["test"] | None = None) -> Literal["test"] | None:
+    return literal