feature: add type checking for passing request object

Author: maxisbey

src/mcp/server/lowlevel/func_inspection.py

@@ -1,6 +1,8 @@
 import inspect
+import types
+import warnings
 from collections.abc import Callable
-from typing import Any
+from typing import Any, TypeVar, Union, get_args, get_origin
 
 
 def accepts_single_positional_arg(func: Callable[..., Any]) -> bool:
@@ -47,3 +49,169 @@ def accepts_single_positional_arg(func: Callable[..., Any]) -> bool:
     # not the responsibility of this function to check the validity of a
     # callback.
     return True
+
+
+def get_first_parameter_type(func: Callable[..., Any]) -> Any:
+    """
+    Get the type annotation of the first parameter of a function.
+
+    Returns None if:
+    - The function has no parameters
+    - The first parameter has no type annotation
+    - The signature cannot be inspected
+
+    Returns the actual annotation otherwise (could be a type, Any, Union, TypeVar, etc.)
+    """
+    try:
+        sig = inspect.signature(func)
+    except (ValueError, TypeError):
+        return None
+
+    params = list(sig.parameters.values())
+    if not params:
+        return None
+
+    first_param = params[0]
+
+    # Skip *args and **kwargs
+    if first_param.kind in (inspect.Parameter.VAR_POSITIONAL, inspect.Parameter.VAR_KEYWORD):
+        return None
+
+    annotation = first_param.annotation
+    if annotation == inspect.Parameter.empty:
+        return None
+
+    return annotation
+
+
+def type_accepts_request(param_type: Any, request_type: type) -> bool:
+    """
+    Check if a parameter type annotation can accept the request type.
+
+    Handles:
+    - Exact type match
+    - Union types (checks if request_type is in the Union)
+    - TypeVars (checks if request_type matches the bound or constraints)
+    - Generic types (basic support)
+    - Any (always returns True)
+
+    Returns False for None or incompatible types.
+    """
+    if param_type is None:
+        return False
+
+    # Check for Any type
+    if param_type is Any:
+        return True
+
+    # Exact match
+    if param_type == request_type:
+        return True
+
+    # Handle Union types (both typing.Union and | syntax)
+    origin = get_origin(param_type)
+    if origin is Union or origin is types.UnionType:
+        args = get_args(param_type)
+        # Check if request_type is in the Union
+        for arg in args:
+            if arg == request_type:
+                return True
+            # Recursively check each union member
+            if type_accepts_request(arg, request_type):
+                return True
+        return False
+
+    # Handle TypeVar
+    if isinstance(param_type, TypeVar):
+        # Check if request_type matches the bound
+        if param_type.__bound__ is not None:
+            if request_type == param_type.__bound__:
+                return True
+            # Check if request_type is a subclass of the bound
+            try:
+                if issubclass(request_type, param_type.__bound__):
+                    return True
+            except TypeError:
+                pass
+
+        # Check constraints
+        if param_type.__constraints__:
+            for constraint in param_type.__constraints__:
+                if request_type == constraint:
+                    return True
+                try:
+                    if issubclass(request_type, constraint):
+                        return True
+                except TypeError:
+                    pass
+
+        return False
+
+    # For other generic types, check if request_type matches the origin
+    if origin is not None:
+        # Get the base generic type (e.g., list from list[str])
+        return request_type == origin
+
+    return False
+
+
+def should_pass_request(func: Callable[..., Any], request_type: type) -> tuple[bool, bool]:
+    """
+    Determine if a request should be passed to the function based on parameter type inspection.
+
+    Returns a tuple of (should_pass_request, should_deprecate):
+    - should_pass_request: True if the request should be passed to the function
+    - should_deprecate: True if a deprecation warning should be issued
+
+    The decision logic:
+    1. If the function has no parameters -> (False, True) - old style without params, deprecate
+    2. If the function has parameters but can't accept positional args -> (False, False)
+    3. If the first parameter type accepts the request type -> (True, False) - pass request, no deprecation
+    4. If the first parameter is typed as Any -> (True, True) - pass request but deprecate (effectively untyped)
+    5. If the first parameter is typed with something incompatible -> (False, True) - old style, deprecate
+    6. If the first parameter is untyped but accepts positional args -> (True, True) - pass request, deprecate
+    """
+    can_accept_arg = accepts_single_positional_arg(func)
+
+    if not can_accept_arg:
+        # Check if it has no parameters at all (old style)
+        try:
+            sig = inspect.signature(func)
+            if len(sig.parameters) == 0:
+                # Old style handler with no parameters - don't pass request but deprecate
+                return False, True
+        except (ValueError, TypeError):
+            pass
+        # Can't accept positional arguments for other reasons
+        return False, False
+
+    param_type = get_first_parameter_type(func)
+
+    if param_type is None:
+        # Untyped parameter - this is the old style, pass request but deprecate
+        return True, True
+
+    # Check if the parameter type can accept the request
+    if type_accepts_request(param_type, request_type):
+        # Check if it's Any - if so, we should deprecate
+        if param_type is Any:
+            return True, True
+        # Properly typed to accept the request - pass request, no deprecation
+        return True, False
+
+    # Parameter is typed with something incompatible - this is an old style handler expecting
+    # a different signature, don't pass request, issue deprecation
+    return False, True
+
+
+def issue_deprecation_warning(func: Callable[..., Any], request_type: type) -> None:
+    """
+    Issue a deprecation warning for handlers that don't use the new request parameter style.
+    """
+    func_name = getattr(func, "__name__", str(func))
+    warnings.warn(
+        f"Handler '{func_name}' should accept a '{request_type.__name__}' parameter. "
+        "Support for handlers without this parameter will be removed in a future version.",
+        DeprecationWarning,
+        stacklevel=4,
+    )

src/mcp/server/lowlevel/server.py

@@ -82,7 +82,7 @@ async def main():
 from typing_extensions import TypeVar
 
 import mcp.types as types
-from mcp.server.lowlevel.func_inspection import accepts_single_positional_arg
+from mcp.server.lowlevel.func_inspection import issue_deprecation_warning, should_pass_request
 from mcp.server.lowlevel.helper_types import ReadResourceContents
 from mcp.server.models import InitializationOptions
 from mcp.server.session import ServerSession
@@ -235,7 +235,10 @@ def decorator(
             | Callable[[types.ListPromptsRequest], Awaitable[types.ListPromptsResult]],
         ):
             logger.debug("Registering handler for PromptListRequest")
-            pass_request = accepts_single_positional_arg(func)
+            pass_request, should_deprecate = should_pass_request(func, types.ListPromptsRequest)
+
+            if should_deprecate:
+                issue_deprecation_warning(func, types.ListPromptsRequest)
 
             if pass_request:
                 request_func = cast(Callable[[types.ListPromptsRequest], Awaitable[types.ListPromptsResult]], func)
@@ -280,7 +283,10 @@ def decorator(
             | Callable[[types.ListResourcesRequest], Awaitable[types.ListResourcesResult]],
         ):
             logger.debug("Registering handler for ListResourcesRequest")
-            pass_request = accepts_single_positional_arg(func)
+            pass_request, should_deprecate = should_pass_request(func, types.ListResourcesRequest)
+
+            if should_deprecate:
+                issue_deprecation_warning(func, types.ListResourcesRequest)
 
             if pass_request:
                 request_func = cast(Callable[[types.ListResourcesRequest], Awaitable[types.ListResourcesResult]], func)
@@ -420,7 +426,10 @@ def decorator(
             | Callable[[types.ListToolsRequest], Awaitable[types.ListToolsResult]],
         ):
             logger.debug("Registering handler for ListToolsRequest")
-            pass_request = accepts_single_positional_arg(func)
+            pass_request, should_deprecate = should_pass_request(func, types.ListToolsRequest)
+
+            if should_deprecate:
+                issue_deprecation_warning(func, types.ListToolsRequest)
 
             if pass_request:
                 request_func = cast(Callable[[types.ListToolsRequest], Awaitable[types.ListToolsResult]], func)