refactor: rename Dispatcher.call to send_request, replace RequestSender with Outbound

The design doc's `send_request = call` alias only makes the concrete class
satisfy RequestSender, not the abstract Dispatcher Protocol — so any consumer
typed against `Dispatcher[TT]` (Connection, ServerRunner) couldn't pass it to
something expecting a RequestSender without a cast or hand-written bridge.

RequestSender was also half a contract: every implementor (Dispatcher,
DispatchContext, Connection, Context) has `notify` too, and PeerMixin needs
both for its typed sugar (elicit/sample are requests, log is a notification).

Outbound(Protocol) declares both methods; Dispatcher and DispatchContext extend
it. PeerMixin will wrap an Outbound. One verb everywhere, no aliases, no extra
Protocols.

- Dispatcher.call -> send_request
- OnCall -> OnRequest, on_call -> on_request
- RequestSender -> Outbound (now also declares notify)
- Dispatcher(Outbound, Protocol[TT]), DispatchContext(Outbound, Protocol[TT])

Author: maxisbey

src/mcp/shared/direct_dispatcher.py

@@ -1,7 +1,7 @@
 """In-memory `Dispatcher` that wires two peers together with no transport.
 
-`DirectDispatcher` is the simplest possible `Dispatcher` implementation: a call
-on one side directly invokes the other side's `on_call`. There is no
+`DirectDispatcher` is the simplest possible `Dispatcher` implementation: a
+request on one side directly invokes the other side's `on_request`. There is no
 serialization, no JSON-RPC framing, and no streams. It exists to:
 
 * prove the `Dispatcher` Protocol is implementable without JSON-RPC
@@ -21,7 +21,7 @@
 
 import anyio
 
-from mcp.shared.dispatcher import CallOptions, OnCall, OnNotify, ProgressFnT
+from mcp.shared.dispatcher import CallOptions, OnNotify, OnRequest, ProgressFnT
 from mcp.shared.exceptions import MCPError, NoBackChannelError
 from mcp.shared.transport_context import TransportContext
 from mcp.types import INTERNAL_ERROR, REQUEST_TIMEOUT
@@ -31,20 +31,20 @@
 DIRECT_TRANSPORT_KIND = "direct"
 
 
-_Call = Callable[[str, Mapping[str, Any] | None, CallOptions | None], Awaitable[dict[str, Any]]]
+_Request = Callable[[str, Mapping[str, Any] | None, CallOptions | None], Awaitable[dict[str, Any]]]
 _Notify = Callable[[str, Mapping[str, Any] | None], Awaitable[None]]
 
 
 @dataclass
 class _DirectDispatchContext:
-    """`DispatchContext` for an inbound call on a `DirectDispatcher`.
+    """`DispatchContext` for an inbound request on a `DirectDispatcher`.
 
     The back-channel callables target the *originating* side, so a handler's
-    `send_request` reaches the peer that made the inbound call.
+    `send_request` reaches the peer that made the inbound request.
     """
 
     transport: TransportContext
-    _back_call: _Call
+    _back_request: _Request
     _back_notify: _Notify
     _on_progress: ProgressFnT | None = None
     cancel_requested: anyio.Event = field(default_factory=anyio.Event)
@@ -60,7 +60,7 @@ async def send_request(
     ) -> dict[str, Any]:
         if not self.transport.can_send_request:
             raise NoBackChannelError(method)
-        return await self._back_call(method, params, opts)
+        return await self._back_request(method, params, opts)
 
     async def progress(self, progress: float, total: float | None = None, message: str | None = None) -> None:
         if self._on_progress is not None:
@@ -71,38 +71,38 @@ class DirectDispatcher:
     """A `Dispatcher` that calls a peer's handlers directly, in-process.
 
     Two instances are wired together with `create_direct_dispatcher_pair`; each
-    holds a reference to the other. `call` on one awaits the peer's `on_call`.
-    `run` parks until `close` is called.
+    holds a reference to the other. `send_request` on one awaits the peer's
+    `on_request`. `run` parks until `close` is called.
     """
 
     def __init__(self, transport_ctx: TransportContext):
         self._transport_ctx = transport_ctx
         self._peer: DirectDispatcher | None = None
-        self._on_call: OnCall | None = None
+        self._on_request: OnRequest | None = None
         self._on_notify: OnNotify | None = None
         self._ready = anyio.Event()
         self._closed = anyio.Event()
 
     def connect_to(self, peer: DirectDispatcher) -> None:
         self._peer = peer
 
-    async def call(
+    async def send_request(
         self,
         method: str,
         params: Mapping[str, Any] | None,
         opts: CallOptions | None = None,
     ) -> dict[str, Any]:
         if self._peer is None:
             raise RuntimeError("DirectDispatcher has no peer; use create_direct_dispatcher_pair()")
-        return await self._peer._dispatch_call(method, params, opts)
+        return await self._peer._dispatch_request(method, params, opts)
 
     async def notify(self, method: str, params: Mapping[str, Any] | None) -> None:
         if self._peer is None:
             raise RuntimeError("DirectDispatcher has no peer; use create_direct_dispatcher_pair()")
         await self._peer._dispatch_notify(method, params)
 
-    async def run(self, on_call: OnCall, on_notify: OnNotify) -> None:
-        self._on_call = on_call
+    async def run(self, on_request: OnRequest, on_notify: OnNotify) -> None:
+        self._on_request = on_request
         self._on_notify = on_notify
         self._ready.set()
         await self._closed.wait()
@@ -115,25 +115,25 @@ def _make_context(self, on_progress: ProgressFnT | None = None) -> _DirectDispat
         peer = self._peer
         return _DirectDispatchContext(
             transport=self._transport_ctx,
-            _back_call=lambda m, p, o: peer._dispatch_call(m, p, o),
+            _back_request=lambda m, p, o: peer._dispatch_request(m, p, o),
             _back_notify=lambda m, p: peer._dispatch_notify(m, p),
             _on_progress=on_progress,
         )
 
-    async def _dispatch_call(
+    async def _dispatch_request(
         self,
         method: str,
         params: Mapping[str, Any] | None,
         opts: CallOptions | None,
     ) -> dict[str, Any]:
         await self._ready.wait()
-        assert self._on_call is not None
+        assert self._on_request is not None
         opts = opts or {}
         dctx = self._make_context(on_progress=opts.get("on_progress"))
         try:
             with anyio.fail_after(opts.get("timeout")):
                 try:
-                    return await self._on_call(dctx, method, params)
+                    return await self._on_request(dctx, method, params)
                 except MCPError:
                     raise
                 except Exception as e:

src/mcp/shared/dispatcher.py

@@ -2,9 +2,9 @@
 
 A Dispatcher turns a duplex message channel into two things:
 
-* an outbound API: ``call(method, params)`` and ``notify(method, params)``
-* an inbound pump: ``run(on_call, on_notify)`` that drives the receive loop and
-  invokes the supplied handlers for each incoming request/notification
+* an outbound API: ``send_request(method, params)`` and ``notify(method, params)``
+* an inbound pump: ``run(on_request, on_notify)`` that drives the receive loop
+  and invokes the supplied handlers for each incoming request/notification
 
 It is deliberately *not* MCP-aware. Method names are strings, params and
 results are ``dict[str, Any]``. The MCP type layer (request/result models,
@@ -28,23 +28,23 @@
     "DispatchContext",
     "DispatchMiddleware",
     "Dispatcher",
-    "OnCall",
     "OnNotify",
+    "OnRequest",
+    "Outbound",
     "ProgressFnT",
-    "RequestSender",
 ]
 
 TransportT_co = TypeVar("TransportT_co", bound=TransportContext, covariant=True)
 
 
 class ProgressFnT(Protocol):
-    """Callback invoked when a progress notification arrives for a pending call."""
+    """Callback invoked when a progress notification arrives for a pending request."""
 
     async def __call__(self, progress: float, total: float | None, message: str | None) -> None: ...
 
 
 class CallOptions(TypedDict, total=False):
-    """Per-call options for `RequestSender.send_request` / `Dispatcher.call`.
+    """Per-call options for `Outbound.send_request`.
 
     All keys are optional. Dispatchers ignore keys they do not understand.
     """
@@ -53,37 +53,51 @@ class CallOptions(TypedDict, total=False):
     """Seconds to wait for a result before raising and sending ``notifications/cancelled``."""
 
     on_progress: ProgressFnT
-    """Receive ``notifications/progress`` updates for this call."""
+    """Receive ``notifications/progress`` updates for this request."""
 
     resumption_token: str
-    """Opaque token to resume a previously interrupted call (transport-dependent)."""
+    """Opaque token to resume a previously interrupted request (transport-dependent)."""
 
     on_resumption_token: Callable[[str], Awaitable[None]]
     """Receive a resumption token when the transport issues one."""
 
 
 @runtime_checkable
-class RequestSender(Protocol):
-    """Anything that can send a request and await its result.
+class Outbound(Protocol):
+    """Anything that can send requests and notifications to the peer.
 
-    `DispatchContext` satisfies this; `PeerMixin` (and `Connection`/`Peer`) wrap
-    a `RequestSender` to provide typed request methods.
+    Both `Dispatcher` (top-level outbound) and `DispatchContext` (back-channel
+    during an inbound request) extend this. `PeerMixin` wraps an `Outbound` to
+    provide typed MCP request/notification methods.
     """
 
     async def send_request(
         self,
         method: str,
         params: Mapping[str, Any] | None,
         opts: CallOptions | None = None,
-    ) -> dict[str, Any]: ...
+    ) -> dict[str, Any]:
+        """Send a request and await its result.
+
+        Raises:
+            MCPError: If the peer responded with an error, or the handler
+                raised. Implementations normalize all handler exceptions to
+                `MCPError` so callers see a single exception type.
+        """
+        ...
 
+    async def notify(self, method: str, params: Mapping[str, Any] | None) -> None:
+        """Send a fire-and-forget notification."""
+        ...
 
-class DispatchContext(Protocol[TransportT_co]):
-    """Per-request context handed to ``on_call`` / ``on_notify``.
+
+class DispatchContext(Outbound, Protocol[TransportT_co]):
+    """Per-request context handed to ``on_request`` / ``on_notify``.
 
     Carries the transport metadata for the inbound message and provides the
     back-channel for sending requests/notifications to the peer while handling
-    it.
+    it. `send_request` raises `NoBackChannelError` if
+    ``transport.can_send_request`` is ``False``.
     """
 
     @property
@@ -96,23 +110,6 @@ def cancel_requested(self) -> anyio.Event:
         """Set when the peer sends ``notifications/cancelled`` for this request."""
         ...
 
-    async def notify(self, method: str, params: Mapping[str, Any] | None) -> None:
-        """Send a notification to the peer."""
-        ...
-
-    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 and await its result.
-
-        Raises:
-            NoBackChannelError: if ``transport.can_send_request`` is ``False``.
-        """
-        ...
-
     async def progress(self, progress: float, total: float | None = None, message: str | None = None) -> None:
         """Report progress for the inbound request, if the peer supplied a progress token.
 
@@ -121,47 +118,28 @@ async def progress(self, progress: float, total: float | None = None, message: s
         ...
 
 
-OnCall = Callable[[DispatchContext[TransportContext], str, Mapping[str, Any] | None], Awaitable[dict[str, Any]]]
+OnRequest = Callable[[DispatchContext[TransportContext], str, Mapping[str, Any] | None], Awaitable[dict[str, Any]]]
 """Handler for inbound requests: ``(ctx, method, params) -> result``. Raise ``MCPError`` to send an error response."""
 
 OnNotify = Callable[[DispatchContext[TransportContext], str, Mapping[str, Any] | None], Awaitable[None]]
 """Handler for inbound notifications: ``(ctx, method, params)``."""
 
-DispatchMiddleware = Callable[[OnCall], OnCall]
-"""Wraps an ``OnCall`` to produce another ``OnCall``. Applied outermost-first."""
+DispatchMiddleware = Callable[[OnRequest], OnRequest]
+"""Wraps an ``OnRequest`` to produce another ``OnRequest``. Applied outermost-first."""
 
 
-class Dispatcher(Protocol[TransportT_co]):
+class Dispatcher(Outbound, Protocol[TransportT_co]):
     """A duplex request/notification channel with call-return semantics.
 
-    Implementations own correlation of outbound calls to inbound results, the
+    Implementations own correlation of outbound requests to inbound results, the
     receive loop, per-request concurrency, and cancellation/progress wiring.
     """
 
-    async def call(
-        self,
-        method: str,
-        params: Mapping[str, Any] | None,
-        opts: CallOptions | None = None,
-    ) -> dict[str, Any]:
-        """Send a request and await its result.
-
-        Raises:
-            MCPError: If the peer responded with an error, or the handler
-                raised. Implementations normalize all handler exceptions to
-                `MCPError` so callers see a single exception type.
-        """
-        ...
-
-    async def notify(self, method: str, params: Mapping[str, Any] | None) -> None:
-        """Send a fire-and-forget notification."""
-        ...
-
-    async def run(self, on_call: OnCall, on_notify: OnNotify) -> None:
+    async def run(self, on_request: OnRequest, on_notify: OnNotify) -> None:
         """Drive the receive loop until the underlying channel closes.
 
-        Each inbound request is dispatched to ``on_call`` in its own task; the
-        returned dict (or raised ``MCPError``) is sent back as the response.
+        Each inbound request is dispatched to ``on_request`` in its own task;
+        the returned dict (or raised ``MCPError``) is sent back as the response.
         Inbound notifications go to ``on_notify``.
         """
         ...