[v1.x] Deprecate the WebSocket transport and the experimental tasks entry points (#2828)

tests/experimental/tasks/conftest.py

@@ -0,0 +1,18 @@
+"""Shared configuration for the experimental tasks suite."""
+
+from pathlib import Path
+
+import pytest
+
+_HERE = Path(__file__).parent
+
+# The tasks suite intentionally exercises the deprecated experimental tasks API.
+_TASKS_DEPRECATION_IGNORE = pytest.mark.filterwarnings(
+    "ignore:The experimental tasks API is deprecated:DeprecationWarning"
+)
+
+
+def pytest_collection_modifyitems(items: list[pytest.Item]) -> None:
+    for item in items:
+        if _HERE in item.path.parents:
+            item.add_marker(_TASKS_DEPRECATION_IGNORE)

tests/experimental/tasks/test_deprecations.py

@@ -0,0 +1,72 @@
+"""Tests for the deprecation warnings on the experimental tasks entry points."""
+
+import warnings
+
+import pytest
+
+import mcp.types as types
+from mcp.client.experimental.task_handlers import ExperimentalTaskHandlers
+from mcp.client.session import ClientSession
+from mcp.server.lowlevel import Server
+from mcp.server.models import InitializationOptions
+from mcp.server.session import ServerSession
+from mcp.shared.memory import create_client_server_memory_streams, create_connected_server_and_client_session
+
+_DEPRECATION_MATCH = "The experimental tasks API is deprecated"
+
+
+@pytest.mark.anyio
+async def test_client_session_experimental_property_is_deprecated() -> None:
+    async with create_client_server_memory_streams() as (client_streams, _):
+        read_stream, write_stream = client_streams
+        session = ClientSession(read_stream, write_stream)
+        with pytest.warns(DeprecationWarning, match=_DEPRECATION_MATCH):
+            features = session.experimental
+        # The cached path warns as well
+        with pytest.warns(DeprecationWarning, match=_DEPRECATION_MATCH):
+            assert session.experimental is features
+
+
+@pytest.mark.anyio
+async def test_client_session_experimental_task_handlers_kwarg_is_deprecated() -> None:
+    async with create_client_server_memory_streams() as (client_streams, _):
+        read_stream, write_stream = client_streams
+        with pytest.warns(DeprecationWarning, match=_DEPRECATION_MATCH):
+            ClientSession(read_stream, write_stream, experimental_task_handlers=ExperimentalTaskHandlers())
+
+
+@pytest.mark.anyio
+async def test_server_session_experimental_property_is_deprecated() -> None:
+    init_options = InitializationOptions(
+        server_name="test-server",
+        server_version="0.1.0",
+        capabilities=types.ServerCapabilities(),
+    )
+    async with create_client_server_memory_streams() as (_, server_streams):
+        read_stream, write_stream = server_streams
+        async with ServerSession(read_stream, write_stream, init_options) as session:
+            with pytest.warns(DeprecationWarning, match=_DEPRECATION_MATCH):
+                features = session.experimental
+            # The cached path warns as well. coverage.py misreports the branch arcs of the
+            # last statement in a nested `async with` body on Python 3.11+.
+            with pytest.warns(DeprecationWarning, match=_DEPRECATION_MATCH):  # pragma: no branch
+                assert session.experimental is features
+
+
+def test_lowlevel_server_experimental_property_is_deprecated() -> None:
+    server: Server = Server("test-server")
+    with pytest.warns(DeprecationWarning, match=_DEPRECATION_MATCH):
+        handlers = server.experimental
+    # The cached path warns as well
+    with pytest.warns(DeprecationWarning, match=_DEPRECATION_MATCH):
+        assert server.experimental is handlers
+
+
+@pytest.mark.anyio
+async def test_plain_session_usage_does_not_warn() -> None:
+    """Clients and servers that don't touch the tasks API must not see deprecation warnings."""
+    server: Server = Server("test-server")
+    with warnings.catch_warnings():
+        warnings.simplefilter("error")
+        async with create_connected_server_and_client_session(server) as session:
+            await session.send_ping()

tests/experimental/tasks/test_request_context.py

@@ -181,7 +181,7 @@ async def test_run_task_with_an_explicit_task_id_emits_a_deprecation_warning() -
         # deprecated argument has been reported.
         with pytest.raises(RuntimeError, match="Task support not enabled"):
             # The deliberate use of the deprecated overload is the point of this test.
-            await exp.run_task(work, task_id="explicitly-chosen")  # pyright: ignore[reportDeprecated]
+            await exp.run_task(work, task_id="explicitly-chosen")
 
 
 @pytest.mark.anyio

tests/shared/test_ws.py

@@ -10,6 +10,7 @@ import uvicorn
 from pydantic import AnyUrl
 from starlette.applications import Starlette
 from starlette.routing import WebSocketRoute
+from starlette.types import Message
 from starlette.websockets import WebSocket
 
 from mcp.client.session import ClientSession
@@ -30,6 +31,11 @@ from tests.test_helpers import wait_for_server
 
 SERVER_NAME = "test_server_for_WS"
 
+# This suite intentionally exercises the deprecated WebSocket transport.
+pytestmark = pytest.mark.filterwarnings(
+    "ignore:The WebSocket (client|server) transport is deprecated:DeprecationWarning"
+)
+
 
 @pytest.fixture
 def server_port() -> int:
@@ -198,3 +204,22 @@ async def test_ws_client_timeout(
         assert len(result.contents) > 0
         assert isinstance(result.contents[0], TextResourceContents)
         assert result.contents[0].text == "Read example"
+
+
+def test_websocket_client_is_deprecated() -> None:
+    """Creating the websocket_client context manager emits a DeprecationWarning."""
+    with pytest.warns(DeprecationWarning, match="The WebSocket client transport is deprecated"):
+        websocket_client("ws://127.0.0.1:1/ws")
+
+
+def test_websocket_server_is_deprecated() -> None:
+    """Creating the websocket_server context manager emits a DeprecationWarning."""
+
+    async def receive() -> Message:
+        raise NotImplementedError
+
+    async def send(message: Message) -> None:
+        raise NotImplementedError
+
+    with pytest.warns(DeprecationWarning, match="The WebSocket server transport is deprecated"):
+        websocket_server({"type": "websocket"}, receive, send)