Clarify protocol-version docstrings and tighten new tests

- _SERVER_REQUEST_METHODS documents the SDK union, not the spec union
  (the 2025-11-25 tasks methods are deliberately absent)
- protocol_version docstrings no longer claim 'always None' in stateless
  mode: a client that sends initialize anyway still commits the version
- the priming-event test asserts the store saw traffic, so the final
  all() cannot pass vacuously
- add missing test docstrings

Author: maxisbey

src/mcp/client/session.py

@@ -98,9 +98,10 @@ async def _default_logging_callback(
 _SERVER_REQUEST_METHODS: frozenset[str] = frozenset(
     cast(type[BaseModel], arm).model_fields["method"].default for arm in get_args(types.ServerRequest)
 )
-"""Method names in the spec `ServerRequest` union, derived from the
-discriminator literal on each arm. Requests for any other method are answered
-with METHOD_NOT_FOUND instead of failing union validation."""
+"""Method names in the SDK's `ServerRequest` union, derived from the
+discriminator literal on each arm. Requests for any other method — including
+spec methods this SDK deliberately doesn't model, like `tasks/*` — are
+answered with METHOD_NOT_FOUND instead of failing union validation."""
 
 
 class ClientSession(

src/mcp/server/connection.py

@@ -84,8 +84,9 @@ class Connection:
 
     protocol_version: str | None
     """The protocol version negotiated during `initialize`; `None` before
-    initialization, and always `None` on stateless connections (no handshake
-    reaches them). Handlers read this as `ServerSession.protocol_version`."""
+    initialization. Stateless connections don't require the handshake, so this
+    normally stays `None` there (a client that sends `initialize` anyway still
+    commits it). Handlers read this as `ServerSession.protocol_version`."""
 
     initialized: anyio.Event
     """Set when `notifications/initialized` arrives (matches TS `oninitialized`);

src/mcp/server/session.py

@@ -54,10 +54,10 @@ def client_params(self) -> types.InitializeRequestParams | None:
     def protocol_version(self) -> str | None:
         """The protocol version negotiated during `initialize`.
 
-        `None` before initialization completes, and always `None` on stateless
-        connections (no handshake reaches them; on streamable HTTP the
-        per-request version is the `MCP-Protocol-Version` header, available
-        via `ctx.request.headers`).
+        `None` before initialization completes. Stateless connections don't
+        require the handshake, so this is normally `None` there (on streamable
+        HTTP the per-request version is the `MCP-Protocol-Version` header,
+        available via `ctx.request.headers`).
         """
         return self._connection.protocol_version
 

tests/server/test_session.py

@@ -185,6 +185,7 @@ def _init_params(protocol_version: str) -> dict[str, Any]:
 
 @pytest.mark.anyio
 async def test_protocol_version_is_none_before_initialize():
+    """No negotiated version is readable before the initialize handshake."""
     async with connected_runner(_runner_server([]), initialized=False) as (_client, runner):
         assert runner.session.protocol_version is None
 

tests/shared/test_streamable_http.py

@@ -1771,7 +1771,9 @@ async def test_initialize_with_unknown_protocol_version_gets_no_priming_event(
         )
         assert response.status_code == 200
 
-    # Priming events are stored with a None payload; none may exist for this client.
+    # The store must have seen traffic (the initialize response), but no
+    # priming event — priming events are stored with a None payload.
+    assert event_store._events
     assert all(message is not None for _, _, message in event_store._events)
 
 

tests/shared/test_version.py

@@ -24,6 +24,7 @@
     ],
 )
 def test_is_version_at_least_ordering(version: str, minimum: str, expected: bool) -> None:
+    """Known revisions order by registry position: equal, newer, and older pairs."""
     assert is_version_at_least(version, minimum) is expected