chore: rename and clarify function inspection code

Author: maxisbey

src/mcp/server/lowlevel/func_inspection.py

@@ -3,14 +3,13 @@
 from typing import Any
 
 
-def accepts_request(func: Callable[..., Any]) -> bool:
+def accepts_single_positional_arg(func: Callable[..., Any]) -> bool:
     """
-    True if the function accepts a cursor parameter call, otherwise false.
+    True if the function accepts at least one positional argument, otherwise false.
 
-    `accepts_cursor` does not validate that the function will work. For
-    example, if `func` contains keyword-only arguments with no defaults,
-    then it will not work when used in the `lowlevel/server.py` code, but
-    this function will not raise an exception.
+    This function intentionally does not define behavior for `func`s that
+    contain more than one positional argument, or any required keyword
+    arguments without defaults.
     """
     try:
         sig = inspect.signature(func)
@@ -20,26 +19,28 @@ def accepts_request(func: Callable[..., Any]) -> bool:
     params = dict(sig.parameters.items())
 
     if len(params) == 0:
-        # No parameters at all - can't accept cursor
+        # No parameters at all - can't accept single argument
         return False
 
     # Check if ALL remaining parameters are keyword-only
     all_keyword_only = all(param.kind == inspect.Parameter.KEYWORD_ONLY for param in params.values())
 
     if all_keyword_only:
         # If all params are keyword-only, check if they ALL have defaults
-        # If they do, the function can be called with no arguments -> no cursor
+        # If they do, the function can be called with no arguments -> no argument
         all_have_defaults = all(param.default is not inspect.Parameter.empty for param in params.values())
-        return not all_have_defaults  # False if all have defaults (no cursor), True otherwise
+        if all_have_defaults:
+            return False
+        # otherwise, undefined (doesn't accept a positional argument, and requires at least one keyword only)
 
     # Check if the ONLY parameter is **kwargs (VAR_KEYWORD)
-    # A function with only **kwargs can't accept a positional cursor argument
+    # A function with only **kwargs can't accept a positional argument
     if len(params) == 1:
         only_param = next(iter(params.values()))
         if only_param.kind == inspect.Parameter.VAR_KEYWORD:
-            return False  # Can't pass positional cursor to **kwargs
+            return False  # Can't pass positional argument to **kwargs
 
-    # Has at least one positional or variadic parameter - can accept cursor
+    # Has at least one positional or variadic parameter - can accept argument
     # Important note: this is designed to _not_ handle the situation where
     # there are multiple keyword only arguments with no defaults. In those
     # situations it's an invalid handler function, and will error. But it's

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_request
+from mcp.server.lowlevel.func_inspection import accepts_single_positional_arg
 from mcp.server.lowlevel.helper_types import ReadResourceContents
 from mcp.server.models import InitializationOptions
 from mcp.server.session import ServerSession
@@ -235,7 +235,7 @@ def decorator(
             | Callable[[types.ListPromptsRequest], Awaitable[types.ListPromptsResult]],
         ):
             logger.debug("Registering handler for PromptListRequest")
-            pass_request = accepts_request(func)
+            pass_request = accepts_single_positional_arg(func)
 
             if pass_request:
                 request_func = cast(Callable[[types.ListPromptsRequest], Awaitable[types.ListPromptsResult]], func)
@@ -280,7 +280,7 @@ def decorator(
             | Callable[[types.ListResourcesRequest], Awaitable[types.ListResourcesResult]],
         ):
             logger.debug("Registering handler for ListResourcesRequest")
-            pass_request = accepts_request(func)
+            pass_request = accepts_single_positional_arg(func)
 
             if pass_request:
                 request_func = cast(Callable[[types.ListResourcesRequest], Awaitable[types.ListResourcesResult]], func)
@@ -420,7 +420,7 @@ def decorator(
             | Callable[[types.ListToolsRequest], Awaitable[types.ListToolsResult]],
         ):
             logger.debug("Registering handler for ListToolsRequest")
-            pass_request = accepts_request(func)
+            pass_request = accepts_single_positional_arg(func)
 
             if pass_request:
                 request_func = cast(Callable[[types.ListToolsRequest], Awaitable[types.ListToolsResult]], func)

tests/server/lowlevel/test_func_inspection.py

@@ -4,10 +4,9 @@
 import pytest
 
 from mcp import types
-from mcp.server.lowlevel.func_inspection import accepts_request
+from mcp.server.lowlevel.func_inspection import accepts_single_positional_arg
 
 
-# Test fixtures - functions and methods with various signatures
 class MyClass:
     async def no_request_method(self):
         """Instance method without request parameter"""
@@ -161,13 +160,17 @@ async def mixed_positional_and_keyword(request: types.ListPromptsRequest, *, ext
     ],
     ids=lambda x: x if isinstance(x, str) else "",
 )
-def test_accepts_request(callable_obj: Callable[..., Any], expected: bool, description: str):
-    """Test that accepts_request correctly identifies functions that accept a request parameter.
+def test_accepts_single_positional_arg(callable_obj: Callable[..., Any], expected: bool, description: str):
+    """Test that `accepts_single_positional_arg` correctly identifies functions that accept a single argument.
+
+    `accepts_single_positional_arg` is currently only used in the case of
+    the lowlevel server code checking whether a handler accepts a request
+    argument, so the test cases reference a "request" param/arg.
 
     The function should return True if the callable can potentially accept a positional
     request argument. Returns False if:
     - No parameters at all
     - Only keyword-only parameters that ALL have defaults (can call with no args)
     - Only **kwargs parameter (can't accept positional arguments)
     """
-    assert accepts_request(callable_obj) == expected, f"Failed for {description}"
+    assert accepts_single_positional_arg(callable_obj) == expected, f"Failed for {description}"