refactor: add @overload decorators and @deprecated for list methods

Implements feedback from maxisbey on PR #1453. This change improves type
safety and deprecation handling for list methods (list_tools, list_resources,
list_prompts, list_resource_templates):

- Add @overload decorators with three signatures to provide clear IDE typing:
  - cursor: str (positional argument)
  - params: PaginatedRequestParams (keyword-only argument)
  - no arguments

- Replace warnings.warn() with @deprecated decorator from typing_extensions
  for cleaner deprecation signaling

- Add validation to raise ValueError when both cursor and params are provided,
  preventing ambiguous parameter combinations

- Update tests to expect ValueError when both parameters are specified

This ensures the Python SDK has type checking equivalent to the TypeScript SDK
and provides better developer experience through IDE assistance and clear
deprecation messaging.

Author: felixweinberger

src/mcp/client/session.py

@@ -1,7 +1,8 @@
 import logging
-import warnings
 from datetime import timedelta
-from typing import Any, Protocol
+from typing import Any, Protocol, overload
+
+from typing_extensions import deprecated
 
 import anyio.lowlevel
 from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
@@ -213,6 +214,16 @@ async def set_logging_level(self, level: types.LoggingLevel) -> types.EmptyResul
             types.EmptyResult,
         )
 
+    @deprecated("Use params=PaginatedRequestParams(...) instead")
+    @overload
+    async def list_resources(self, cursor: str) -> types.ListResourcesResult: ...
+
+    @overload
+    async def list_resources(self, *, params: types.PaginatedRequestParams) -> types.ListResourcesResult: ...
+
+    @overload
+    async def list_resources(self) -> types.ListResourcesResult: ...
+
     async def list_resources(
         self,
         cursor: str | None = None,
@@ -222,23 +233,36 @@ async def list_resources(
         """Send a resources/list request.
 
         Args:
-            cursor: (Deprecated) Pagination cursor. Use params parameter instead.
-            params: Pagination parameters. Defaults to None (omits params field).
+            cursor: Simple cursor string for pagination (deprecated, use params instead)
+            params: Full pagination parameters including cursor and any future fields
         """
-        if cursor is not None:
-            warnings.warn(
-                "cursor parameter is deprecated, use params=PaginatedRequestParams(cursor=...) instead",
-                DeprecationWarning,
-                stacklevel=2,
-            )
-            if params is None:
-                params = types.PaginatedRequestParams(cursor=cursor)
+        if params is not None and cursor is not None:
+            raise ValueError("Cannot specify both cursor and params")
+
+        if params is not None:
+            request_params = params
+        elif cursor is not None:
+            request_params = types.PaginatedRequestParams(cursor=cursor)
+        else:
+            request_params = None
 
         return await self.send_request(
-            types.ClientRequest(types.ListResourcesRequest(params=params)),
+            types.ClientRequest(types.ListResourcesRequest(params=request_params)),
             types.ListResourcesResult,
         )
 
+    @deprecated("Use params=PaginatedRequestParams(...) instead")
+    @overload
+    async def list_resource_templates(self, cursor: str) -> types.ListResourceTemplatesResult: ...
+
+    @overload
+    async def list_resource_templates(
+        self, *, params: types.PaginatedRequestParams
+    ) -> types.ListResourceTemplatesResult: ...
+
+    @overload
+    async def list_resource_templates(self) -> types.ListResourceTemplatesResult: ...
+
     async def list_resource_templates(
         self,
         cursor: str | None = None,
@@ -248,20 +272,21 @@ async def list_resource_templates(
         """Send a resources/templates/list request.
 
         Args:
-            cursor: (Deprecated) Pagination cursor. Use params parameter instead.
-            params: Pagination parameters. Defaults to None (omits params field).
+            cursor: Simple cursor string for pagination (deprecated, use params instead)
+            params: Full pagination parameters including cursor and any future fields
         """
-        if cursor is not None:
-            warnings.warn(
-                "cursor parameter is deprecated, use params=PaginatedRequestParams(cursor=...) instead",
-                DeprecationWarning,
-                stacklevel=2,
-            )
-            if params is None:
-                params = types.PaginatedRequestParams(cursor=cursor)
+        if params is not None and cursor is not None:
+            raise ValueError("Cannot specify both cursor and params")
+
+        if params is not None:
+            request_params = params
+        elif cursor is not None:
+            request_params = types.PaginatedRequestParams(cursor=cursor)
+        else:
+            request_params = None
 
         return await self.send_request(
-            types.ClientRequest(types.ListResourceTemplatesRequest(params=params)),
+            types.ClientRequest(types.ListResourceTemplatesRequest(params=request_params)),
             types.ListResourceTemplatesResult,
         )
 
@@ -330,7 +355,7 @@ async def _validate_tool_result(self, name: str, result: types.CallToolResult) -
         """Validate the structured content of a tool result against its output schema."""
         if name not in self._tool_output_schemas:
             # refresh output schema cache
-            await self.list_tools()
+            await self.list_tools()  # type: ignore[reportDeprecated]
 
         output_schema = None
         if name in self._tool_output_schemas:
@@ -348,6 +373,16 @@ async def _validate_tool_result(self, name: str, result: types.CallToolResult) -
             except SchemaError as e:
                 raise RuntimeError(f"Invalid schema for tool {name}: {e}")
 
+    @deprecated("Use params=PaginatedRequestParams(...) instead")
+    @overload
+    async def list_prompts(self, cursor: str) -> types.ListPromptsResult: ...
+
+    @overload
+    async def list_prompts(self, *, params: types.PaginatedRequestParams) -> types.ListPromptsResult: ...
+
+    @overload
+    async def list_prompts(self) -> types.ListPromptsResult: ...
+
     async def list_prompts(
         self,
         cursor: str | None = None,
@@ -357,20 +392,21 @@ async def list_prompts(
         """Send a prompts/list request.
 
         Args:
-            cursor: (Deprecated) Pagination cursor. Use params parameter instead.
-            params: Pagination parameters. Defaults to None (omits params field).
+            cursor: Simple cursor string for pagination (deprecated, use params instead)
+            params: Full pagination parameters including cursor and any future fields
         """
-        if cursor is not None:
-            warnings.warn(
-                "cursor parameter is deprecated, use params=PaginatedRequestParams(cursor=...) instead",
-                DeprecationWarning,
-                stacklevel=2,
-            )
-            if params is None:
-                params = types.PaginatedRequestParams(cursor=cursor)
+        if params is not None and cursor is not None:
+            raise ValueError("Cannot specify both cursor and params")
+
+        if params is not None:
+            request_params = params
+        elif cursor is not None:
+            request_params = types.PaginatedRequestParams(cursor=cursor)
+        else:
+            request_params = None
 
         return await self.send_request(
-            types.ClientRequest(types.ListPromptsRequest(params=params)),
+            types.ClientRequest(types.ListPromptsRequest(params=request_params)),
             types.ListPromptsResult,
         )
 
@@ -409,6 +445,16 @@ async def complete(
             types.CompleteResult,
         )
 
+    @deprecated("Use params=PaginatedRequestParams(...) instead")
+    @overload
+    async def list_tools(self, cursor: str) -> types.ListToolsResult: ...
+
+    @overload
+    async def list_tools(self, *, params: types.PaginatedRequestParams) -> types.ListToolsResult: ...
+
+    @overload
+    async def list_tools(self) -> types.ListToolsResult: ...
+
     async def list_tools(
         self,
         cursor: str | None = None,
@@ -418,20 +464,21 @@ async def list_tools(
         """Send a tools/list request.
 
         Args:
-            cursor: (Deprecated) Pagination cursor. Use params parameter instead.
-            params: Pagination parameters. Defaults to None (omits params field).
+            cursor: Simple cursor string for pagination (deprecated, use params instead)
+            params: Full pagination parameters including cursor and any future fields
         """
-        if cursor is not None:
-            warnings.warn(
-                "cursor parameter is deprecated, use params=PaginatedRequestParams(cursor=...) instead",
-                DeprecationWarning,
-                stacklevel=2,
-            )
-            if params is None:
-                params = types.PaginatedRequestParams(cursor=cursor)
+        if params is not None and cursor is not None:
+            raise ValueError("Cannot specify both cursor and params")
+
+        if params is not None:
+            request_params = params
+        elif cursor is not None:
+            request_params = types.PaginatedRequestParams(cursor=cursor)
+        else:
+            request_params = None
 
         result = await self.send_request(
-            types.ClientRequest(types.ListToolsRequest(params=params)),
+            types.ClientRequest(types.ListToolsRequest(params=request_params)),
             types.ListToolsResult,
         )
 

tests/client/test_list_methods_cursor.py

@@ -165,42 +165,34 @@ async def test_list_methods_params_parameter(
 
 
 @pytest.mark.parametrize(
-    "method_name,request_method",
+    "method_name",
     [
-        ("list_tools", "tools/list"),
-        ("list_resources", "resources/list"),
-        ("list_prompts", "prompts/list"),
-        ("list_resource_templates", "resources/templates/list"),
+        "list_tools",
+        "list_resources",
+        "list_prompts",
+        "list_resource_templates",
     ],
 )
-@pytest.mark.filterwarnings("ignore::DeprecationWarning")
-async def test_list_methods_params_takes_precedence_over_cursor(
-    stream_spy: Callable[[], StreamSpyCollection],
+async def test_list_methods_raises_error_when_both_cursor_and_params_provided(
     full_featured_server: FastMCP,
     method_name: str,
-    request_method: str,
 ):
-    """Test that params parameter takes precedence over cursor parameter.
+    """Test that providing both cursor and params raises ValueError.
 
     Covers: list_tools, list_resources, list_prompts, list_resource_templates
 
-    When both cursor and params are provided, params should be used and
-    cursor should be ignored, ensuring safe migration path.
+    When both cursor and params are provided, a ValueError should be raised
+    to prevent ambiguity.
     """
     async with create_session(full_featured_server._mcp_server) as client_session:
-        spies = stream_spy()
         method = getattr(client_session, method_name)
 
-        # Call with both cursor and params - params should take precedence
-        _ = await method(
-            cursor="old_cursor",
-            params=types.PaginatedRequestParams(cursor="new_cursor"),
-        )
-        requests = spies.get_client_requests(method=request_method)
-        assert len(requests) == 1
-        # Verify params takes precedence (new_cursor should be used, not old_cursor)
-        assert requests[0].params is not None
-        assert requests[0].params["cursor"] == "new_cursor"
+        # Call with both cursor and params - should raise ValueError
+        with pytest.raises(ValueError, match="Cannot specify both cursor and params"):
+            await method(
+                cursor="old_cursor",
+                params=types.PaginatedRequestParams(cursor="new_cursor"),
+            )
 
 
 async def test_list_tools_with_strict_server_validation():