refactor: consolidate coverage-tracer resync workarounds into one helper

Eight call sites carried near-identical comment blocks explaining the
CPython 3.11 trace-loss workaround (python/cpython#106749). Move the
explanation into a single resync_tracer() helper in mcp.shared._compat
and call it by name, so the workaround is greppable and deletable as a
unit when 3.11 support ends.

Author: maxisbey

src/mcp/client/sse.py

@@ -5,12 +5,12 @@
 from urllib.parse import parse_qs, urljoin, urlparse
 
 import anyio
-import anyio.lowlevel
 import httpx
 from anyio.abc import TaskStatus
 from httpx_sse import SSEError, aconnect_sse
 
 from mcp import types
+from mcp.shared._compat import resync_tracer
 from mcp.shared._context_streams import create_context_streams
 from mcp.shared._httpx_utils import McpHttpClientFactory, create_mcp_http_client
 from mcp.shared.message import SessionMessage
@@ -158,10 +158,4 @@ async def _send_message(session_message: SessionMessage) -> None:
 
                 yield read_stream, write_stream
                 tg.cancel_scope.cancel()
-            # The cancel above is delivered via `coro.throw()` into this task at
-            # the task-group join; on CPython 3.11 (gh-106749) that drops `'call'`
-            # trace events for the outer await chain and desyncs coverage's CTracer
-            # past the caller's frame. Yielding once here resumes via `.send()`,
-            # which re-stamps the missing `'call'` events and resyncs the tracer.
-            # Shielded so a pending outer cancel is not re-delivered at this point.
-            await anyio.lowlevel.cancel_shielded_checkpoint()
+            await resync_tracer()

src/mcp/client/streamable_http.py

@@ -9,13 +9,13 @@
 from dataclasses import dataclass
 
 import anyio
-import anyio.lowlevel
 import httpx
 from anyio.abc import TaskGroup
 from httpx_sse import EventSource, ServerSentEvent, aconnect_sse
 from pydantic import ValidationError
 
 from mcp.client._transport import TransportStreams
+from mcp.shared._compat import resync_tracer
 from mcp.shared._context_streams import ContextReceiveStream, ContextSendStream, create_context_streams
 from mcp.shared._httpx_utils import create_mcp_http_client
 from mcp.shared.message import ClientMessageMetadata, SessionMessage
@@ -587,10 +587,4 @@ def start_get_stream() -> None:
                 if transport.session_id and terminate_on_close:
                     await transport.terminate_session(client)
                 tg.cancel_scope.cancel()
-        # The cancel above is delivered via `coro.throw()` into this task at
-        # the task-group join; on CPython 3.11 (gh-106749) that drops `'call'`
-        # trace events for the outer await chain and desyncs coverage's CTracer
-        # past the caller's frame. Yielding once here resumes via `.send()`,
-        # which re-stamps the missing `'call'` events and resyncs the tracer.
-        # Shielded so a pending outer cancel is not re-delivered at this point.
-        await anyio.lowlevel.cancel_shielded_checkpoint()
+        await resync_tracer()

src/mcp/client/websocket.py

@@ -3,13 +3,13 @@
 from contextlib import asynccontextmanager
 
 import anyio
-import anyio.lowlevel
 from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
 from pydantic import ValidationError
 from websockets.asyncio.client import connect as ws_connect
 from websockets.typing import Subprotocol
 
 from mcp import types
+from mcp.shared._compat import resync_tracer
 from mcp.shared.message import SessionMessage
 
 
@@ -84,10 +84,4 @@ async def ws_writer():
 
             # Once the caller's 'async with' block exits, we shut down
             tg.cancel_scope.cancel()
-        # The cancel above is delivered via `coro.throw()` into this task at
-        # the task-group join; on CPython 3.11 (gh-106749) that drops `'call'`
-        # trace events for the outer await chain and desyncs coverage's CTracer
-        # past the caller's frame. Yielding once here resumes via `.send()`,
-        # which re-stamps the missing `'call'` events and resyncs the tracer.
-        # Shielded so a pending outer cancel is not re-delivered at this point.
-        await anyio.lowlevel.cancel_shielded_checkpoint()
+        await resync_tracer()

src/mcp/server/streamable_http_manager.py

@@ -9,7 +9,6 @@
 from uuid import uuid4
 
 import anyio
-import anyio.lowlevel
 from anyio.abc import TaskStatus
 from starlette.requests import Request
 from starlette.responses import Response
@@ -22,6 +21,7 @@
     StreamableHTTPServerTransport,
 )
 from mcp.server.transport_security import TransportSecuritySettings
+from mcp.shared._compat import resync_tracer
 from mcp.types import INVALID_REQUEST, ErrorData, JSONRPCError
 
 if TYPE_CHECKING:
@@ -140,13 +140,7 @@ async def lifespan(app: Starlette) -> AsyncIterator[None]:
                 # Clear any remaining server instances
                 self._server_instances.clear()
                 self._session_owners.clear()
-        # The cancel above is delivered via `coro.throw()` into this task at
-        # the task-group join; on CPython 3.11 (gh-106749) that drops `'call'`
-        # trace events for the outer await chain and desyncs coverage's CTracer
-        # past the caller's frame. Yielding once here resumes via `.send()`,
-        # which re-stamps the missing `'call'` events and resyncs the tracer.
-        # Shielded so a pending outer cancel is not re-delivered at this point.
-        await anyio.lowlevel.cancel_shielded_checkpoint()
+        await resync_tracer()
 
     async def handle_request(self, scope: Scope, receive: Receive, send: Send) -> None:
         """Process ASGI request with proper session handling and transport setup.

src/mcp/shared/_compat.py

@@ -0,0 +1,19 @@
+"""Workarounds for CPython interpreter bugs the SDK papers over."""
+
+import anyio.lowlevel
+
+__all__ = ["resync_tracer"]
+
+
+async def resync_tracer() -> None:
+    """Resync coverage tracing after a cancelled task-group join.
+
+    A cancel delivered at a join resumes the awaiting coroutine chain via
+    `coro.throw()`; on CPython 3.11 (python/cpython#106749) that drops the
+    `'call'` trace events for the outer frames and desyncs coverage's CTracer
+    until the chain next suspends and resumes normally. Yielding once here
+    resumes via `.send()`, which re-stamps the missing events. Shielded so a
+    pending outer cancel is not re-delivered at this point; behaviorally a
+    no-op. Delete this module when Python 3.11 support ends (EOL 2027-10).
+    """
+    await anyio.lowlevel.cancel_shielded_checkpoint()

src/mcp/shared/memory.py

@@ -5,8 +5,7 @@
 from collections.abc import AsyncGenerator
 from contextlib import asynccontextmanager
 
-import anyio.lowlevel
-
+from mcp.shared._compat import resync_tracer
 from mcp.shared._context_streams import ContextReceiveStream, ContextSendStream, create_context_streams
 from mcp.shared.message import SessionMessage
 
@@ -30,11 +29,5 @@ async def create_client_server_memory_streams() -> AsyncGenerator[tuple[MessageS
 
     async with server_to_client_receive, client_to_server_send, client_to_server_receive, server_to_client_send:
         yield client_streams, server_streams
-    # Callers routinely cancel a task group wrapped around these streams just
-    # before this context exits; that cancel is delivered via `coro.throw()`,
-    # which on CPython 3.11 (gh-106749) drops `'call'` trace events for the
-    # outer await chain and desyncs coverage's CTracer past the caller's frame.
-    # Closing memory streams never suspends, so this is the last chance to
-    # resync: yielding once resumes via `.send()`, which re-stamps the missing
-    # `'call'` events. Shielded so a pending outer cancel is not re-delivered.
-    await anyio.lowlevel.cancel_shielded_checkpoint()
+    # Heals caller-driven cancels; closing memory streams never suspends.
+    await resync_tracer()

src/mcp/shared/session.py

@@ -7,12 +7,12 @@
 from typing import Any, Generic, Protocol, TypeVar
 
 import anyio
-import anyio.lowlevel
 from anyio.streams.memory import MemoryObjectSendStream
 from opentelemetry.trace import SpanKind
 from pydantic import BaseModel, TypeAdapter
 from typing_extensions import Self
 
+from mcp.shared._compat import resync_tracer
 from mcp.shared._otel import inject_trace_context, otel_span
 from mcp.shared._stream_protocols import ReadStream, WriteStream
 from mcp.shared.exceptions import MCPError
@@ -175,13 +175,7 @@ async def __aexit__(
         # in the task group.
         self._task_group.cancel_scope.cancel()
         result = await self._task_group.__aexit__(exc_type, exc_val, exc_tb)
-        # The cancel above is delivered via `coro.throw()` into this task; on
-        # CPython 3.11 (gh-106749) that drops `'call'` trace events for the
-        # outer await chain and desyncs coverage's CTracer past the caller's
-        # frame. Yielding once here resumes via `.send()`, which re-stamps the
-        # missing `'call'` events and resyncs the tracer. Shielded so a pending
-        # outer cancel is not re-delivered at this point.
-        await anyio.lowlevel.cancel_shielded_checkpoint()
+        await resync_tracer()
         return result
 
     async def send_request(

tests/interaction/transports/_bridge.py

@@ -31,11 +31,12 @@
 
 import anyio
 import anyio.abc
-import anyio.lowlevel
 import httpx
 from anyio.streams.memory import MemoryObjectReceiveStream
 from starlette.types import ASGIApp, Message, Scope
 
+from mcp.shared._compat import resync_tracer
+
 
 class _StreamingResponseBody(httpx.AsyncByteStream):
     """A response body that yields chunks as the application produces them.
@@ -89,10 +90,7 @@ async def __aexit__(
         if self._cancel_on_close:
             self._task_group.cancel_scope.cancel()
         await self._task_group.__aexit__(exc_type, exc_value, traceback)
-        # gh-106749: the cancel above is delivered via coro.throw() on
-        # CPython 3.11; resume via .send() so coverage's CTracer re-syncs
-        # for whatever the caller does after this context manager exits.
-        await anyio.lowlevel.cancel_shielded_checkpoint()
+        await resync_tracer()
 
     async def handle_async_request(self, request: httpx.Request) -> httpx.Response:
         assert isinstance(request.stream, httpx.AsyncByteStream)

tests/shared/test_streamable_http.py

@@ -16,7 +16,6 @@
 from urllib.parse import urlparse
 
 import anyio
-import anyio.lowlevel
 import httpx
 import pytest
 from httpx_sse import ServerSentEvent
@@ -41,6 +40,7 @@
 )
 from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
 from mcp.server.transport_security import TransportSecuritySettings
+from mcp.shared._compat import resync_tracer
 from mcp.shared._context import RequestContext
 from mcp.shared._context_streams import create_context_streams
 from mcp.shared.message import ClientMessageMetadata, ServerMessageMetadata, SessionMessage
@@ -1188,10 +1188,7 @@ async def run_tool():
                     # Kill the client session while tool is waiting on lock
                     tg.cancel_scope.cancel()
 
-    # gh-106749 heal: the cancel above is delivered via coro.throw() on
-    # CPython 3.11; resume via .send() so coverage's CTracer re-syncs before
-    # the second session's lines.
-    await anyio.lowlevel.cancel_shielded_checkpoint()
+    await resync_tracer()
 
     async with make_client(app, headers=headers) as httpx_client2:
         async with streamable_http_client(f"{BASE_URL}/mcp", http_client=httpx_client2) as (