feat: add paginated list decorators for prompts, resources, and tools

Add list_prompts_paginated, list_resources_paginated, and list_tools_paginated
decorators to support cursor-based pagination for listing endpoints.

These decorators:
- Accept a cursor parameter (can be None for first page)
- Return the respective ListResult type directly
- Maintain backward compatibility with existing non-paginated decorators
- Update tool cache for list_tools_paginated

Also includes simplified unit tests that verify cursor passthrough.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: maxisbey

src/mcp/server/lowlevel/server.py

@@ -242,6 +242,19 @@ async def handler(_: Any):
 
         return decorator
 
+    def list_prompts_paginated(self):
+        def decorator(func: Callable[[types.Cursor | None], Awaitable[types.ListPromptsResult]]):
+            logger.debug("Registering handler for PromptListRequest with pagination")
+
+            async def handler(req: types.ListPromptsRequest):
+                result = await func(req.params.cursor if req.params else None)
+                return types.ServerResult(result)
+
+            self.request_handlers[types.ListPromptsRequest] = handler
+            return func
+
+        return decorator
+
     def get_prompt(self):
         def decorator(
             func: Callable[[str, dict[str, str] | None], Awaitable[types.GetPromptResult]],
@@ -270,6 +283,19 @@ async def handler(_: Any):
 
         return decorator
 
+    def list_resources_paginated(self):
+        def decorator(func: Callable[[types.Cursor | None], Awaitable[types.ListResourcesResult]]):
+            logger.debug("Registering handler for ListResourcesRequest with pagination")
+
+            async def handler(req: types.ListResourcesRequest):
+                result = await func(req.params.cursor if req.params else None)
+                return types.ServerResult(result)
+
+            self.request_handlers[types.ListResourcesRequest] = handler
+            return func
+
+        return decorator
+
     def list_resource_templates(self):
         def decorator(func: Callable[[], Awaitable[list[types.ResourceTemplate]]]):
             logger.debug("Registering handler for ListResourceTemplatesRequest")
@@ -397,6 +423,25 @@ async def handler(_: Any):
 
         return decorator
 
+    def list_tools_paginated(self):
+        def decorator(
+            func: Callable[[types.Cursor | None], Awaitable[types.ListToolsResult]]
+        ):
+            logger.debug("Registering paginated handler for ListToolsRequest")
+
+            async def handler(request: types.ListToolsRequest):
+                cursor = request.params.cursor if request.params else None
+                result = await func(cursor)
+                # Refresh the tool cache with returned tools
+                for tool in result.tools:
+                    self._tool_cache[tool.name] = tool
+                return types.ServerResult(result)
+
+            self.request_handlers[types.ListToolsRequest] = handler
+            return func
+
+        return decorator
+
     def _make_error_result(self, error_message: str) -> types.ServerResult:
         """Create a ServerResult with an error CallToolResult."""
         return types.ServerResult(

tests/server/lowlevel/__init__.py

@@ -0,0 +1,110 @@
+import pytest
+
+from mcp.server import Server
+from mcp.types import (
+    Cursor,
+    ListPromptsRequest,
+    ListPromptsResult,
+    ListResourcesRequest,
+    ListResourcesResult,
+    ListToolsRequest,
+    ListToolsResult,
+    PaginatedRequestParams,
+    ServerResult,
+)
+
+
+@pytest.mark.anyio
+async def test_list_prompts_pagination() -> None:
+    server = Server("test")
+    test_cursor = "test-cursor-123"
+    
+    # Track what cursor was received
+    received_cursor: Cursor | None = None
+    
+    @server.list_prompts_paginated()
+    async def handle_list_prompts(cursor: Cursor | None) -> ListPromptsResult:
+        nonlocal received_cursor
+        received_cursor = cursor
+        return ListPromptsResult(prompts=[], nextCursor="next")
+    
+    handler = server.request_handlers[ListPromptsRequest]
+    
+    # Test: No cursor provided -> handler receives None
+    request = ListPromptsRequest(method="prompts/list", params=None)
+    result = await handler(request)
+    assert received_cursor is None
+    assert isinstance(result, ServerResult)
+    
+    # Test: Cursor provided -> handler receives exact cursor value
+    request_with_cursor = ListPromptsRequest(
+        method="prompts/list",
+        params=PaginatedRequestParams(cursor=test_cursor)
+    )
+    result2 = await handler(request_with_cursor)
+    assert received_cursor == test_cursor
+    assert isinstance(result2, ServerResult)
+
+
+@pytest.mark.anyio
+async def test_list_resources_pagination() -> None:
+    server = Server("test")
+    test_cursor = "resource-cursor-456"
+    
+    # Track what cursor was received
+    received_cursor: Cursor | None = None
+    
+    @server.list_resources_paginated()
+    async def handle_list_resources(cursor: Cursor | None) -> ListResourcesResult:
+        nonlocal received_cursor
+        received_cursor = cursor
+        return ListResourcesResult(resources=[], nextCursor="next")
+    
+    handler = server.request_handlers[ListResourcesRequest]
+    
+    # Test: No cursor provided -> handler receives None
+    request = ListResourcesRequest(method="resources/list", params=None)
+    result = await handler(request)
+    assert received_cursor is None
+    assert isinstance(result, ServerResult)
+    
+    # Test: Cursor provided -> handler receives exact cursor value
+    request_with_cursor = ListResourcesRequest(
+        method="resources/list",
+        params=PaginatedRequestParams(cursor=test_cursor)
+    )
+    result2 = await handler(request_with_cursor)
+    assert received_cursor == test_cursor
+    assert isinstance(result2, ServerResult)
+
+
+@pytest.mark.anyio
+async def test_list_tools_pagination() -> None:
+    server = Server("test")
+    test_cursor = "tools-cursor-789"
+    
+    # Track what cursor was received
+    received_cursor: Cursor | None = None
+    
+    @server.list_tools_paginated()
+    async def handle_list_tools(cursor: Cursor | None) -> ListToolsResult:
+        nonlocal received_cursor
+        received_cursor = cursor
+        return ListToolsResult(tools=[], nextCursor="next")
+    
+    handler = server.request_handlers[ListToolsRequest]
+    
+    # Test: No cursor provided -> handler receives None
+    request = ListToolsRequest(method="tools/list", params=None)
+    result = await handler(request)
+    assert received_cursor is None
+    assert isinstance(result, ServerResult)
+    
+    # Test: Cursor provided -> handler receives exact cursor value
+    request_with_cursor = ListToolsRequest(
+        method="tools/list",
+        params=PaginatedRequestParams(cursor=test_cursor)
+    )
+    result2 = await handler(request_with_cursor)
+    assert received_cursor == test_cursor
+    assert isinstance(result2, ServerResult)