feat: BaseContext

Composition over a DispatchContext: forwards transport/cancel_requested/
send_request/notify/progress and adds meta. Satisfies Outbound so PeerMixin
works on it (proven by Peer(bctx).ping() round-tripping).

The server Context (next commit) extends this with lifespan/connection;
ClientContext will be an alias once ClientSession is reworked.

Author: maxisbey

src/mcp/shared/context.py

@@ -0,0 +1,82 @@
+"""`BaseContext` — the user-facing per-request context.
+
+Composition over a `DispatchContext`: forwards the transport metadata, the
+back-channel (`send_request`/`notify`), progress reporting, and the cancel
+event. Adds `meta` (the inbound request's `_meta` field).
+
+Satisfies `Outbound`, so `PeerMixin` works on it (the server-side `Context`
+mixes that in directly). Shared between client and server: the server's
+`Context` extends this with `lifespan`/`connection`; `ClientContext` is just an
+alias.
+"""
+
+from collections.abc import Mapping
+from typing import Any, Generic
+
+import anyio
+from typing_extensions import TypeVar
+
+from mcp.shared.dispatcher import CallOptions, DispatchContext
+from mcp.shared.transport_context import TransportContext
+from mcp.types import RequestParamsMeta
+
+__all__ = ["BaseContext"]
+
+TransportT = TypeVar("TransportT", bound=TransportContext, default=TransportContext)
+
+
+class BaseContext(Generic[TransportT]):
+    """Per-request context wrapping a `DispatchContext`.
+
+    `ServerRunner` (PR4) constructs one per inbound request and passes it to
+    the user's handler.
+    """
+
+    def __init__(self, dctx: DispatchContext[TransportT], meta: RequestParamsMeta | None = None) -> None:
+        self._dctx = dctx
+        self._meta = meta
+
+    @property
+    def transport(self) -> TransportT:
+        """Transport-specific metadata for this inbound request."""
+        return self._dctx.transport
+
+    @property
+    def cancel_requested(self) -> anyio.Event:
+        """Set when the peer sends ``notifications/cancelled`` for this request."""
+        return self._dctx.cancel_requested
+
+    @property
+    def can_send_request(self) -> bool:
+        """Whether the back-channel can deliver server-initiated requests."""
+        return self._dctx.transport.can_send_request
+
+    @property
+    def meta(self) -> RequestParamsMeta | None:
+        """The inbound request's ``_meta`` field, if present."""
+        return self._meta
+
+    async def send_request(
+        self,
+        method: str,
+        params: Mapping[str, Any] | None,
+        opts: CallOptions | None = None,
+    ) -> dict[str, Any]:
+        """Send a request to the peer on the back-channel.
+
+        Raises:
+            MCPError: The peer responded with an error.
+            NoBackChannelError: ``can_send_request`` is ``False``.
+        """
+        return await self._dctx.send_request(method, params, opts)
+
+    async def notify(self, method: str, params: Mapping[str, Any] | None) -> None:
+        """Send a notification to the peer on the back-channel."""
+        await self._dctx.notify(method, params)
+
+    async def report_progress(self, progress: float, total: float | None = None, message: str | None = None) -> None:
+        """Report progress for this request, if the peer supplied a progress token.
+
+        A no-op when no token was supplied.
+        """
+        await self._dctx.progress(progress, total, message)

tests/shared/test_context.py

@@ -0,0 +1,115 @@
+"""Tests for `BaseContext`.
+
+`BaseContext` is composition over a `DispatchContext` — it forwards
+``transport``/``cancel_requested``/``send_request``/``notify``/``progress``
+and adds ``meta``. It must satisfy `Outbound` so `PeerMixin` works on it.
+"""
+
+from collections.abc import Mapping
+from typing import Any
+
+import anyio
+import pytest
+
+from mcp.shared.context import BaseContext
+from mcp.shared.dispatcher import DispatchContext
+from mcp.shared.peer import Peer
+from mcp.shared.transport_context import TransportContext
+
+from .conftest import direct_pair
+from .test_dispatcher import Recorder, echo_handlers, running_pair
+
+DCtx = DispatchContext[TransportContext]
+
+
+@pytest.mark.anyio
+async def test_base_context_forwards_transport_and_cancel_requested():
+    captured: list[BaseContext[TransportContext]] = []
+
+    async def server_on_request(ctx: DCtx, method: str, params: Mapping[str, Any] | None) -> dict[str, Any]:
+        bctx = BaseContext(ctx)
+        captured.append(bctx)
+        return {}
+
+    async with running_pair(direct_pair, server_on_request=server_on_request) as (client, *_):
+        with anyio.fail_after(5):
+            await client.send_request("t", None)
+    bctx = captured[0]
+    assert bctx.transport.kind == "direct"
+    assert isinstance(bctx.cancel_requested, anyio.Event)
+    assert bctx.can_send_request is True
+    assert bctx.meta is None
+
+
+@pytest.mark.anyio
+async def test_base_context_send_request_and_notify_forward_to_dispatch_context():
+    crec = Recorder()
+    c_req, c_notify = echo_handlers(crec)
+
+    async def server_on_request(ctx: DCtx, method: str, params: Mapping[str, Any] | None) -> dict[str, Any]:
+        bctx = BaseContext(ctx)
+        sample = await bctx.send_request("sampling/createMessage", {"x": 1})
+        await bctx.notify("notifications/message", {"level": "info"})
+        return {"sample": sample}
+
+    async with running_pair(
+        direct_pair,
+        server_on_request=server_on_request,
+        client_on_request=c_req,
+        client_on_notify=c_notify,
+    ) as (client, *_):
+        with anyio.fail_after(5):
+            result = await client.send_request("tools/call", None)
+            await crec.notified.wait()
+    assert crec.requests == [("sampling/createMessage", {"x": 1})]
+    assert crec.notifications == [("notifications/message", {"level": "info"})]
+    assert result["sample"] == {"echoed": "sampling/createMessage", "params": {"x": 1}}
+
+
+@pytest.mark.anyio
+async def test_base_context_report_progress_invokes_caller_on_progress():
+    received: list[tuple[float, float | None, str | None]] = []
+
+    async def on_progress(progress: float, total: float | None, message: str | None) -> None:
+        received.append((progress, total, message))
+
+    async def server_on_request(ctx: DCtx, method: str, params: Mapping[str, Any] | None) -> dict[str, Any]:
+        bctx = BaseContext(ctx)
+        await bctx.report_progress(0.5, total=1.0, message="halfway")
+        return {}
+
+    async with running_pair(direct_pair, server_on_request=server_on_request) as (client, *_):
+        with anyio.fail_after(5):
+            await client.send_request("t", None, {"on_progress": on_progress})
+    assert received == [(0.5, 1.0, "halfway")]
+
+
+@pytest.mark.anyio
+async def test_base_context_satisfies_outbound_so_peer_mixin_works():
+    """Wrapping a BaseContext in Peer proves it satisfies Outbound structurally."""
+
+    async def server_on_request(ctx: DCtx, method: str, params: Mapping[str, Any] | None) -> dict[str, Any]:
+        bctx = BaseContext(ctx)
+        await Peer(bctx).ping()
+        return {}
+
+    crec = Recorder()
+    c_req, c_notify = echo_handlers(crec)
+    async with running_pair(
+        direct_pair, server_on_request=server_on_request, client_on_request=c_req, client_on_notify=c_notify
+    ) as (client, *_):
+        with anyio.fail_after(5):
+            await client.send_request("t", None)
+    assert crec.requests == [("ping", None)]
+
+
+@pytest.mark.anyio
+async def test_base_context_meta_holds_supplied_request_params_meta():
+    async def server_on_request(ctx: DCtx, method: str, params: Mapping[str, Any] | None) -> dict[str, Any]:
+        bctx = BaseContext(ctx, meta={"progressToken": "abc"})
+        assert bctx.meta is not None and bctx.meta.get("progressToken") == "abc"
+        return {}
+
+    async with running_pair(direct_pair, server_on_request=server_on_request) as (client, *_):
+        with anyio.fail_after(5):
+            await client.send_request("t", None)