Add a client extension API (#3034)

examples/stories/custom_methods/client.py

@@ -1,6 +1,6 @@
 """Send a vendor-prefixed request via the `client.session` escape hatch."""
 
-from typing import Literal, cast
+from typing import Literal
 
 import mcp_types as types
 
@@ -26,12 +26,10 @@ async def main(target: Target, *, mode: str = "auto") -> None:
     async with Client(target, mode=mode) as client:
         # `Client` only exposes spec-defined verbs, so vendor methods have to drop one
         # layer to `client.session` today — there is no `Client`-level API for them
-        # yet, and whether `.session` stays public is undecided. `send_request` is
-        # typed against the closed `ClientRequest` union, hence the cast; at runtime
-        # the body only calls `.model_dump()` and the unknown method skips the
-        # per-spec result-validation registry.
+        # yet, and whether `.session` stays public is undecided. `send_request`
+        # accepts any `Request` subclass.
         request = SearchRequest(params=SearchParams(query="mcp", limit=3))
-        result = await client.session.send_request(cast("types.ClientRequest", request), SearchResult)
+        result = await client.session.send_request(request, SearchResult)
         assert result.items == ["mcp-0", "mcp-1", "mcp-2"], result