feat: change to passing requests instead of cursors for pagination

Author: maxisbey

README.md

@@ -1763,10 +1763,13 @@ ITEMS = [f"Item {i}" for i in range(1, 101)]  # 100 items
 
 
 @server.list_resources()
-async def list_resources_paginated(cursor: types.Cursor | None) -> types.ListResourcesResult:
+async def list_resources_paginated(request: types.ListResourcesRequest) -> types.ListResourcesResult:
     """List resources with pagination support."""
     page_size = 10
 
+    # Extract cursor from request params
+    cursor = request.params.cursor if request.params is not None else None
+
     # Parse cursor to get offset
     start = 0 if cursor is None else int(cursor)
     end = start + page_size

examples/servers/simple-pagination/mcp_simple_pagination/server.py

@@ -59,9 +59,10 @@ def main(port: int, transport: str) -> int:
 
     # Paginated list_tools - returns 5 tools per page
     @app.list_tools()
-    async def list_tools_paginated(cursor: types.Cursor | None) -> types.ListToolsResult:
+    async def list_tools_paginated(request: types.ListToolsRequest) -> types.ListToolsResult:
         page_size = 5
 
+        cursor = request.params.cursor if request.params is not None else None
         if cursor is None:
             # First page
             start_idx = 0
@@ -86,10 +87,11 @@ async def list_tools_paginated(cursor: types.Cursor | None) -> types.ListToolsRe
     # Paginated list_resources - returns 10 resources per page
     @app.list_resources()
     async def list_resources_paginated(
-        cursor: types.Cursor | None,
+        request: types.ListResourcesRequest,
     ) -> types.ListResourcesResult:
         page_size = 10
 
+        cursor = request.params.cursor if request.params is not None else None
         if cursor is None:
             # First page
             start_idx = 0
@@ -114,10 +116,11 @@ async def list_resources_paginated(
     # Paginated list_prompts - returns 7 prompts per page
     @app.list_prompts()
     async def list_prompts_paginated(
-        cursor: types.Cursor | None,
+        request: types.ListPromptsRequest,
     ) -> types.ListPromptsResult:
         page_size = 7
 
+        cursor = request.params.cursor if request.params is not None else None
         if cursor is None:
             # First page
             start_idx = 0

examples/snippets/servers/pagination_example.py

@@ -15,10 +15,13 @@
 
 
 @server.list_resources()
-async def list_resources_paginated(cursor: types.Cursor | None) -> types.ListResourcesResult:
+async def list_resources_paginated(request: types.ListResourcesRequest) -> types.ListResourcesResult:
     """List resources with pagination support."""
     page_size = 10
 
+    # Extract cursor from request params
+    cursor = request.params.cursor if request.params is not None else None
+
     # Parse cursor to get offset
     start = 0 if cursor is None else int(cursor)
     end = start + page_size

src/mcp/server/lowlevel/func_inspection.py

@@ -3,7 +3,7 @@
 from typing import Any
 
 
-def accepts_cursor(func: Callable[..., Any]) -> bool:
+def accepts_request(func: Callable[..., Any]) -> bool:
     """
     True if the function accepts a cursor parameter call, otherwise false.
 

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_cursor
+from mcp.server.lowlevel.func_inspection import accepts_request
 from mcp.server.lowlevel.helper_types import ReadResourceContents
 from mcp.server.models import InitializationOptions
 from mcp.server.session import ServerSession
@@ -233,19 +233,19 @@ def request_context(
     def list_prompts(self):
         def decorator(
             func: Callable[[], Awaitable[list[types.Prompt]]]
-            | Callable[[types.Cursor | None], Awaitable[types.ListPromptsResult]],
+            | Callable[[types.ListPromptsRequest], Awaitable[types.ListPromptsResult]],
         ):
             logger.debug("Registering handler for PromptListRequest")
-            pass_cursor = accepts_cursor(func)
+            pass_request = accepts_request(func)
 
-            if pass_cursor:
-                cursor_func = cast(Callable[[types.Cursor | None], Awaitable[types.ListPromptsResult]], func)
+            if pass_request:
+                request_func = cast(Callable[[types.ListPromptsRequest], Awaitable[types.ListPromptsResult]], func)
 
-                async def cursor_handler(req: types.ListPromptsRequest):
-                    result = await cursor_func(req.params.cursor if req.params is not None else None)
+                async def request_handler(req: types.ListPromptsRequest):
+                    result = await request_func(req)
                     return types.ServerResult(result)
 
-                handler = cursor_handler
+                handler = request_handler
             else:
                 list_func = cast(Callable[[], Awaitable[list[types.Prompt]]], func)
 
@@ -278,19 +278,19 @@ async def handler(req: types.GetPromptRequest):
     def list_resources(self):
         def decorator(
             func: Callable[[], Awaitable[list[types.Resource]]]
-            | Callable[[types.Cursor | None], Awaitable[types.ListResourcesResult]],
+            | Callable[[types.ListResourcesRequest], Awaitable[types.ListResourcesResult]],
         ):
             logger.debug("Registering handler for ListResourcesRequest")
-            pass_cursor = accepts_cursor(func)
+            pass_request = accepts_request(func)
 
-            if pass_cursor:
-                cursor_func = cast(Callable[[types.Cursor | None], Awaitable[types.ListResourcesResult]], func)
+            if pass_request:
+                request_func = cast(Callable[[types.ListResourcesRequest], Awaitable[types.ListResourcesResult]], func)
 
-                async def cursor_handler(req: types.ListResourcesRequest):
-                    result = await cursor_func(req.params.cursor if req.params is not None else None)
+                async def request_handler(req: types.ListResourcesRequest):
+                    result = await request_func(req)
                     return types.ServerResult(result)
 
-                handler = cursor_handler
+                handler = request_handler
             else:
                 list_func = cast(Callable[[], Awaitable[list[types.Resource]]], func)
 
@@ -418,22 +418,22 @@ async def handler(req: types.UnsubscribeRequest):
     def list_tools(self):
         def decorator(
             func: Callable[[], Awaitable[list[types.Tool]]]
-            | Callable[[types.Cursor | None], Awaitable[types.ListToolsResult]],
+            | Callable[[types.ListToolsRequest], Awaitable[types.ListToolsResult]],
         ):
             logger.debug("Registering handler for ListToolsRequest")
-            pass_cursor = accepts_cursor(func)
+            pass_request = accepts_request(func)
 
-            if pass_cursor:
-                cursor_func = cast(Callable[[types.Cursor | None], Awaitable[types.ListToolsResult]], func)
+            if pass_request:
+                request_func = cast(Callable[[types.ListToolsRequest], Awaitable[types.ListToolsResult]], func)
 
-                async def cursor_handler(req: types.ListToolsRequest):
-                    result = await cursor_func(req.params.cursor if req.params is not None else None)
+                async def request_handler(req: types.ListToolsRequest):
+                    result = await request_func(req)
                     # Refresh the tool cache with returned tools
                     for tool in result.tools:
                         self._tool_cache[tool.name] = tool
                     return types.ServerResult(result)
 
-                handler = cursor_handler
+                handler = request_handler
             else:
                 list_func = cast(Callable[[], Awaitable[list[types.Tool]]], func)
 

tests/server/lowlevel/test_func_inspection.py

@@ -4,83 +4,83 @@
 import pytest
 
 from mcp import types
-from mcp.server.lowlevel.func_inspection import accepts_cursor
+from mcp.server.lowlevel.func_inspection import accepts_request
 
 
 # Test fixtures - functions and methods with various signatures
 class MyClass:
-    async def no_cursor_method(self):
-        """Instance method without cursor parameter"""
+    async def no_request_method(self):
+        """Instance method without request parameter"""
         pass
 
     # noinspection PyMethodParameters
-    async def no_cursor_method_bad_self_name(bad):  # pyright: ignore[reportSelfClsParameterName]
-        """Instance method with cursor parameter, but with bad self name"""
+    async def no_request_method_bad_self_name(bad):  # pyright: ignore[reportSelfClsParameterName]
+        """Instance method without request parameter, but with bad self name"""
         pass
 
-    async def cursor_method(self, cursor: types.Cursor | None):
-        """Instance method with cursor parameter"""
+    async def request_method(self, request: types.ListPromptsRequest):
+        """Instance method with request parameter"""
         pass
 
     # noinspection PyMethodParameters
-    async def cursor_method_bad_self_name(bad, cursor: types.Cursor | None):  # pyright: ignore[reportSelfClsParameterName]
-        """Instance method with cursor parameter, but with bad self name"""
+    async def request_method_bad_self_name(bad, request: types.ListPromptsRequest):  # pyright: ignore[reportSelfClsParameterName]
+        """Instance method with request parameter, but with bad self name"""
         pass
 
     @classmethod
-    async def no_cursor_class_method(cls):
-        """Class method without cursor parameter"""
+    async def no_request_class_method(cls):
+        """Class method without request parameter"""
         pass
 
     # noinspection PyMethodParameters
     @classmethod
-    async def no_cursor_class_method_bad_cls_name(bad):  # pyright: ignore[reportSelfClsParameterName]
-        """Class method without cursor parameter, but with bad cls name"""
+    async def no_request_class_method_bad_cls_name(bad):  # pyright: ignore[reportSelfClsParameterName]
+        """Class method without request parameter, but with bad cls name"""
         pass
 
     @classmethod
-    async def cursor_class_method(cls, cursor: types.Cursor | None):
-        """Class method with cursor parameter"""
+    async def request_class_method(cls, request: types.ListPromptsRequest):
+        """Class method with request parameter"""
         pass
 
     # noinspection PyMethodParameters
     @classmethod
-    async def cursor_class_method_bad_cls_name(bad, cursor: types.Cursor | None):  # pyright: ignore[reportSelfClsParameterName]
-        """Class method with cursor parameter, but with bad cls name"""
+    async def request_class_method_bad_cls_name(bad, request: types.ListPromptsRequest):  # pyright: ignore[reportSelfClsParameterName]
+        """Class method with request parameter, but with bad cls name"""
         pass
 
     @staticmethod
-    async def no_cursor_static_method():
-        """Static method without cursor parameter"""
+    async def no_request_static_method():
+        """Static method without request parameter"""
         pass
 
     @staticmethod
-    async def cursor_static_method(cursor: types.Cursor | None):
-        """Static method with cursor parameter"""
+    async def request_static_method(request: types.ListPromptsRequest):
+        """Static method with request parameter"""
         pass
 
     @staticmethod
-    async def cursor_static_method_bad_arg_name(self: types.Cursor | None):  # pyright: ignore[reportSelfClsParameterName]
-        """Static method with cursor parameter, but the cursor argument is named self"""
+    async def request_static_method_bad_arg_name(self: types.ListPromptsRequest):  # pyright: ignore[reportSelfClsParameterName]
+        """Static method with request parameter, but the request argument is named self"""
         pass
 
 
-async def no_cursor_func():
-    """Function without cursor parameter"""
+async def no_request_func():
+    """Function without request parameter"""
     pass
 
 
-async def cursor_func(cursor: types.Cursor | None):
-    """Function with cursor parameter"""
+async def request_func(request: types.ListPromptsRequest):
+    """Function with request parameter"""
     pass
 
 
-async def cursor_func_different_name(c: types.Cursor | None):
-    """Function with cursor parameter but different arg name"""
+async def request_func_different_name(req: types.ListPromptsRequest):
+    """Function with request parameter but different arg name"""
     pass
 
 
-async def cursor_func_with_self(self: types.Cursor | None):
+async def request_func_with_self(self: types.ListPromptsRequest):
     """Function with parameter named 'self' (edge case)"""
     pass
 
@@ -90,8 +90,8 @@ async def var_positional_func(*args: Any):
     pass
 
 
-async def positional_with_var_positional_func(cursor: types.Cursor | None, *args: Any):
-    """Function with cursor and *args"""
+async def positional_with_var_positional_func(request: types.ListPromptsRequest, *args: Any):
+    """Function with request and *args"""
     pass
 
 
@@ -100,18 +100,18 @@ async def var_keyword_func(**kwargs: Any):
     pass
 
 
-async def cursor_with_var_keyword_func(cursor: types.Cursor | None, **kwargs: Any):
-    """Function with cursor and **kwargs"""
+async def request_with_var_keyword_func(request: types.ListPromptsRequest, **kwargs: Any):
+    """Function with request and **kwargs"""
     pass
 
 
-async def cursor_with_default(cursor: types.Cursor | None = None):
-    """Function with cursor parameter having default value"""
+async def request_with_default(request: types.ListPromptsRequest | None = None):
+    """Function with request parameter having default value"""
     pass
 
 
-async def keyword_only_with_defaults(*, cursor: types.Cursor | None = None):
-    """Function with keyword-only cursor with default"""
+async def keyword_only_with_defaults(*, request: types.ListPromptsRequest | None = None):
+    """Function with keyword-only request with default"""
     pass
 
 
@@ -120,7 +120,7 @@ async def keyword_only_multiple_all_defaults(*, a: str = "test", b: int = 42):
     pass
 
 
-async def mixed_positional_and_keyword(cursor: types.Cursor | None, *, extra: str = "test"):
+async def mixed_positional_and_keyword(request: types.ListPromptsRequest, *, extra: str = "test"):
     """Function with positional and keyword-only params"""
     pass
 
@@ -129,45 +129,45 @@ async def mixed_positional_and_keyword(cursor: types.Cursor | None, *, extra: st
     "callable_obj,expected,description",
     [
         # Regular functions
-        (no_cursor_func, False, "function without parameters"),
-        (cursor_func, True, "function with cursor parameter"),
-        (cursor_func_different_name, True, "function with cursor (different param name)"),
-        (cursor_func_with_self, True, "function with param named 'self'"),
+        (no_request_func, False, "function without parameters"),
+        (request_func, True, "function with request parameter"),
+        (request_func_different_name, True, "function with request (different param name)"),
+        (request_func_with_self, True, "function with param named 'self'"),
         # Instance methods
-        (MyClass().no_cursor_method, False, "instance method without cursor"),
-        (MyClass().no_cursor_method_bad_self_name, False, "instance method without cursor (bad self name)"),
-        (MyClass().cursor_method, True, "instance method with cursor"),
-        (MyClass().cursor_method_bad_self_name, True, "instance method with cursor (bad self name)"),
+        (MyClass().no_request_method, False, "instance method without request"),
+        (MyClass().no_request_method_bad_self_name, False, "instance method without request (bad self name)"),
+        (MyClass().request_method, True, "instance method with request"),
+        (MyClass().request_method_bad_self_name, True, "instance method with request (bad self name)"),
         # Class methods
-        (MyClass.no_cursor_class_method, False, "class method without cursor"),
-        (MyClass.no_cursor_class_method_bad_cls_name, False, "class method without cursor (bad cls name)"),
-        (MyClass.cursor_class_method, True, "class method with cursor"),
-        (MyClass.cursor_class_method_bad_cls_name, True, "class method with cursor (bad cls name)"),
+        (MyClass.no_request_class_method, False, "class method without request"),
+        (MyClass.no_request_class_method_bad_cls_name, False, "class method without request (bad cls name)"),
+        (MyClass.request_class_method, True, "class method with request"),
+        (MyClass.request_class_method_bad_cls_name, True, "class method with request (bad cls name)"),
         # Static methods
-        (MyClass.no_cursor_static_method, False, "static method without cursor"),
-        (MyClass.cursor_static_method, True, "static method with cursor"),
-        (MyClass.cursor_static_method_bad_arg_name, True, "static method with cursor (bad arg name)"),
+        (MyClass.no_request_static_method, False, "static method without request"),
+        (MyClass.request_static_method, True, "static method with request"),
+        (MyClass.request_static_method_bad_arg_name, True, "static method with request (bad arg name)"),
         # Variadic parameters
         (var_positional_func, True, "function with *args"),
-        (positional_with_var_positional_func, True, "function with cursor and *args"),
+        (positional_with_var_positional_func, True, "function with request and *args"),
         (var_keyword_func, False, "function with **kwargs"),
-        (cursor_with_var_keyword_func, True, "function with cursor and **kwargs"),
+        (request_with_var_keyword_func, True, "function with request and **kwargs"),
         # Edge cases
-        (cursor_with_default, True, "function with cursor having default value"),
+        (request_with_default, True, "function with request having default value"),
         # Keyword-only parameters
         (keyword_only_with_defaults, False, "keyword-only with default (can call with no args)"),
         (keyword_only_multiple_all_defaults, False, "multiple keyword-only all with defaults"),
         (mixed_positional_and_keyword, True, "mixed positional and keyword-only params"),
     ],
     ids=lambda x: x if isinstance(x, str) else "",
 )
-def test_accepts_cursor(callable_obj: Callable[..., Any], expected: bool, description: str):
-    """Test that accepts_cursor correctly identifies functions that accept a cursor parameter.
+def test_accepts_request(callable_obj: Callable[..., Any], expected: bool, description: str):
+    """Test that accepts_request correctly identifies functions that accept a request parameter.
 
     The function should return True if the callable can potentially accept a positional
-    cursor argument. Returns False if:
+    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_cursor(callable_obj) == expected, f"Failed for {description}"
+    assert accepts_request(callable_obj) == expected, f"Failed for {description}"