style: ASCII-only docstrings/comments in v2 dispatcher files

Replace double-backticks with single, em-dashes with hyphens, and the one
fat-arrow with => across files this branch touches. Also drop the unused
TransportBuilder type alias (stale after the request_id arg was removed
from the builder signature).

Author: maxisbey

src/mcp/server/_typed_request.py

@@ -1,12 +1,12 @@
-"""Typed ``send_request`` for server-to-client requests.
+"""Typed `send_request` for server-to-client requests.
 
 `TypedServerRequestMixin` provides a typed `send_request(req) -> Result` over
 the host's raw `Outbound.send_raw_request`. Spec server-to-client request types
 have their result type inferred via per-type overloads; custom requests pass
-``result_type=`` explicitly.
+`result_type=` explicitly.
 
 If the spec's request set grows substantially, consider declaring the result
-mapping on the request types themselves (a ``__mcp_result__`` ClassVar read via
+mapping on the request types themselves (a `__mcp_result__` ClassVar read via
 a structural protocol) so this overload ladder doesn't need maintaining
 per-host-class.
 """
@@ -42,10 +42,10 @@
 
 
 class TypedServerRequestMixin:
-    """Typed ``send_request`` for the server-to-client request set.
+    """Typed `send_request` for the server-to-client request set.
 
     Mixed into `Connection` and the server `Context`. Each method constrains
-    ``self`` to `Outbound` so any host with ``send_raw_request`` works.
+    `self` to `Outbound` so any host with `send_raw_request` works.
     """
 
     @overload
@@ -74,12 +74,12 @@ async def send_request(
         """Send a typed server-to-client request and return its typed result.
 
         For spec request types the result type is inferred. For custom requests
-        pass ``result_type=`` explicitly.
+        pass `result_type=` explicitly.
 
         Raises:
             MCPError: The peer responded with an error.
             NoBackChannelError: No back-channel for server-initiated requests.
-            KeyError: ``result_type`` omitted for a non-spec request type.
+            KeyError: `result_type` omitted for a non-spec request type.
         """
         raw = await self.send_raw_request(req.method, dump_params(req.params), opts)
         cls = result_type if result_type is not None else _RESULT_FOR[type(req)]

src/mcp/server/connection.py

@@ -1,14 +1,14 @@
-"""`Connection` — per-client connection state and the standalone outbound channel.
+"""`Connection` - per-client connection state and the standalone outbound channel.
 
-Always present on `Context` (never ``None``), even in stateless deployments.
-Holds peer info populated at ``initialize`` time, per-connection scratch
-``state`` and an ``exit_stack`` for teardown, and an `Outbound` for the
+Always present on `Context` (never `None`), even in stateless deployments.
+Holds peer info populated at `initialize` time, per-connection scratch
+`state` and an `exit_stack` for teardown, and an `Outbound` for the
 standalone stream (the SSE GET stream in streamable HTTP, or the single duplex
 stream in stdio).
 
 `notify` is best-effort: it never raises. If there's no standalone channel
 (stateless HTTP) or the stream has been dropped, the notification is
-debug-logged and silently discarded — server-initiated notifications are
+debug-logged and silently discarded - server-initiated notifications are
 inherently advisory. `send_raw_request` *does* raise `NoBackChannelError` when
 there's no channel; `ping` is the only spec-sanctioned standalone request.
 """
@@ -43,7 +43,7 @@ class Connection(TypedServerRequestMixin):
     """Per-client connection state and standalone-stream `Outbound`.
 
     Constructed by `ServerRunner` once per connection. The peer-info fields are
-    ``None`` until ``initialize`` completes; ``initialized`` is set then.
+    `None` until `initialize` completes; `initialized` is set then.
     """
 
     def __init__(self, outbound: Outbound, *, has_standalone_channel: bool, session_id: str | None = None) -> None:
@@ -63,8 +63,8 @@ def __init__(self, outbound: Outbound, *, has_standalone_channel: bool, session_
         self.exit_stack: AsyncExitStack = AsyncExitStack()
         """Cleanup stack unwound by `ServerRunner` when the connection closes.
 
-        Push context managers (``await exit_stack.enter_async_context(...)``)
-        or callbacks (``exit_stack.push_async_callback(...)``) from handlers or
+        Push context managers (`await exit_stack.enter_async_context(...)`)
+        or callbacks (`exit_stack.push_async_callback(...)`) from handlers or
         middleware to register per-connection teardown. Unwound LIFO after
         `dispatcher.run()` returns, shielded from cancellation."""
 
@@ -76,13 +76,13 @@ async def send_raw_request(
     ) -> dict[str, Any]:
         """Send a raw request on the standalone stream.
 
-        Low-level `Outbound` channel. Prefer the typed ``send_request`` (from
+        Low-level `Outbound` channel. Prefer the typed `send_request` (from
         `TypedServerRequestMixin`) or the convenience methods below; use this
         directly only for off-spec messages.
 
         Raises:
             MCPError: The peer responded with an error.
-            NoBackChannelError: ``has_standalone_channel`` is ``False``.
+            NoBackChannelError: `has_standalone_channel` is `False`.
         """
         if not self.has_standalone_channel:
             raise NoBackChannelError(method)
@@ -103,16 +103,16 @@ async def notify(self, method: str, params: Mapping[str, Any] | None) -> None:
             logger.debug("dropped %s: standalone stream closed", method)
 
     async def ping(self, *, meta: Meta | None = None, opts: CallOptions | None = None) -> None:
-        """Send a ``ping`` request on the standalone stream.
+        """Send a `ping` request on the standalone stream.
 
         Raises:
             MCPError: The peer responded with an error.
-            NoBackChannelError: ``has_standalone_channel`` is ``False``.
+            NoBackChannelError: `has_standalone_channel` is `False`.
         """
         await self.send_raw_request("ping", dump_params(None, meta), opts)
 
     async def log(self, level: LoggingLevel, data: Any, logger: str | None = None, *, meta: Meta | None = None) -> None:
-        """Send a ``notifications/message`` log entry on the standalone stream. Best-effort."""
+        """Send a `notifications/message` log entry on the standalone stream. Best-effort."""
         params: dict[str, Any] = {"level": level, "data": data}
         if logger is not None:
             params["logger"] = logger
@@ -133,9 +133,9 @@ async def send_resource_updated(self, uri: str, *, meta: Meta | None = None) ->
     def check_capability(self, capability: ClientCapabilities) -> bool:
         """Return whether the connected client declared the given capability.
 
-        Returns ``False`` if ``initialize`` hasn't completed yet.
+        Returns `False` if `initialize` hasn't completed yet.
         """
-        # TODO: redesign — mirrors v1 ServerSession.check_client_capability
+        # TODO: redesign - mirrors v1 ServerSession.check_client_capability
         # verbatim for parity.
         if self.client_capabilities is None:
             return False

src/mcp/server/context.py

@@ -39,9 +39,9 @@ class Context(BaseContext[TransportContext], PeerMixin, TypedServerRequestMixin,
     """Server-side per-request context.
 
     Composes `BaseContext` (forwards to `DispatchContext`, satisfies `Outbound`),
-    `PeerMixin` (kwarg-style ``sample``/``elicit_*``/``list_roots``/``ping``),
-    and `TypedServerRequestMixin` (typed ``send_request(req) -> Result``). Adds
-    ``lifespan`` and ``connection``.
+    `PeerMixin` (kwarg-style `sample`/`elicit_*`/`list_roots`/`ping`),
+    and `TypedServerRequestMixin` (typed `send_request(req) -> Result`). Adds
+    `lifespan` and `connection`.
 
     Constructed by `ServerRunner` per inbound request and handed to the user's
     handler.
@@ -73,7 +73,7 @@ def connection(self) -> Connection:
     def session_id(self) -> str | None:
         """The transport's session id for this connection, when one exists.
 
-        Convenience for ``ctx.connection.session_id``. ``None`` on stdio and
+        Convenience for `ctx.connection.session_id`. `None` on stdio and
         stateless HTTP.
         """
         return self._connection.session_id
@@ -82,16 +82,16 @@ def session_id(self) -> str | None:
     def headers(self) -> Mapping[str, str] | None:
         """Request headers carried by this message, when the transport has them.
 
-        Convenience for ``ctx.transport.headers``. ``None`` on stdio.
+        Convenience for `ctx.transport.headers`. `None` on stdio.
         """
         return self.transport.headers
 
     async def log(self, level: LoggingLevel, data: Any, logger: str | None = None, *, meta: Meta | None = None) -> None:
-        """Send a request-scoped ``notifications/message`` log entry.
+        """Send a request-scoped `notifications/message` log entry.
 
         Uses this request's back-channel (so the entry rides the request's SSE
-        stream in streamable HTTP), not the standalone stream — use
-        ``ctx.connection.log(...)`` for that.
+        stream in streamable HTTP), not the standalone stream - use
+        `ctx.connection.log(...)` for that.
         """
         params: dict[str, Any] = {"level": level, "data": data}
         if logger is not None:
@@ -111,16 +111,16 @@ async def log(self, level: LoggingLevel, data: Any, logger: str | None = None, *
 
 
 class ServerMiddleware(Protocol[_MwLifespanT]):
-    """Context-tier middleware: ``(ctx, method, typed_params, call_next) -> result``.
+    """Context-tier middleware: `(ctx, method, typed_params, call_next) -> result`.
 
     Runs *inside* `ServerRunner._on_request` after params validation and
-    `Context` construction. Wraps registered handlers (including ``ping``) but
-    not ``initialize``, ``METHOD_NOT_FOUND``, or validation failures. Listed
+    `Context` construction. Wraps registered handlers (including `ping`) but
+    not `initialize`, `METHOD_NOT_FOUND`, or validation failures. Listed
     outermost-first on `Server.middleware`.
 
     `Server[L].middleware` holds `ServerMiddleware[L]`, so an app-specific
     middleware sees `ctx.lifespan: L`. A reusable middleware can be typed
-    `ServerMiddleware[object]` — `Context` is covariant in `LifespanT`, so it
+    `ServerMiddleware[object]` - `Context` is covariant in `LifespanT`, so it
     registers on any `Server[L]`.
     """
 

src/mcp/server/lowlevel/server.py

@@ -81,10 +81,10 @@ async def main():
 _ParamsT = TypeVar("_ParamsT", bound=BaseModel, default=BaseModel)
 
 RequestHandler = Callable[[ServerRequestContext[LifespanResultT], _ParamsT], Awaitable[HandlerResult]]
-"""A registered request handler: ``(ctx, params) -> result``."""
+"""A registered request handler: `(ctx, params) -> result`."""
 
 NotificationHandler = Callable[[ServerRequestContext[LifespanResultT], _ParamsT], Awaitable[None]]
-"""A registered notification handler: ``(ctx, params) -> None``."""
+"""A registered notification handler: `(ctx, params) -> None`."""
 
 
 @dataclass(frozen=True, slots=True)
@@ -93,7 +93,7 @@ class HandlerEntry(Generic[LifespanResultT]):
 
     Stored in `Server._request_handlers` / `_notification_handlers` and consumed
     by `ServerRunner` to validate, build `Context`, and invoke. The handler's
-    second-argument type is erased to ``Any`` in storage (each entry has a
+    second-argument type is erased to `Any` in storage (each entry has a
     different concrete params type and `Callable` parameters are contravariant);
     the precise type is recoverable via `params_type`. The correlation is
     enforced at registration time by `Server.add_request_handler`.
@@ -262,11 +262,11 @@ def add_request_handler(
         params_type: type[_ParamsT],
         handler: RequestHandler[LifespanResultT, _ParamsT],
     ) -> None:
-        """Register a request handler for ``method``.
+        """Register a request handler for `method`.
 
-        ``params_type`` is the model incoming params are validated against
+        `params_type` is the model incoming params are validated against
         before the handler is invoked. It should subclass `RequestParams` so
-        ``_meta`` parses uniformly. Replaces any existing handler for the same
+        `_meta` parses uniformly. Replaces any existing handler for the same
         method (no collision guard against spec methods).
         """
         self._request_handlers[method] = HandlerEntry(params_type, handler)
@@ -277,9 +277,9 @@ def add_notification_handler(
         params_type: type[_ParamsT],
         handler: NotificationHandler[LifespanResultT, _ParamsT],
     ) -> None:
-        """Register a notification handler for ``method``.
+        """Register a notification handler for `method`.
 
-        ``params_type`` should subclass `NotificationParams` so ``_meta``
+        `params_type` should subclass `NotificationParams` so `_meta`
         parses uniformly. Replaces any existing handler.
         """
         self._notification_handlers[method] = HandlerEntry(params_type, handler)
@@ -300,11 +300,11 @@ def _has_handler(self, method: str) -> bool:
     # --- ServerRegistry protocol (consumed by ServerRunner) ------------------
 
     def get_request_handler(self, method: str) -> HandlerEntry[LifespanResultT] | None:
-        """Return the registered entry for a request method, or ``None``."""
+        """Return the registered entry for a request method, or `None`."""
         return self._request_handlers.get(method)
 
     def get_notification_handler(self, method: str) -> HandlerEntry[LifespanResultT] | None:
-        """Return the registered entry for a notification method, or ``None``."""
+        """Return the registered entry for a notification method, or `None`."""
         return self._notification_handlers.get(method)
 
     def capabilities(self) -> types.ServerCapabilities:

src/mcp/server/runner.py

@@ -1,16 +1,16 @@
-"""`ServerRunner` — per-connection orchestrator over a `Dispatcher`.
+"""`ServerRunner` - per-connection orchestrator over a `Dispatcher`.
 
 `ServerRunner` is the bridge between the dispatcher layer (`on_request` /
 `on_notify`, untyped dicts) and the user's handler layer (typed `Context`,
 typed params). One instance per client connection. It:
 
-* handles the ``initialize`` handshake and populates `Connection`
-* gates requests until initialized (``ping`` exempt)
+* handles the `initialize` handshake and populates `Connection`
+* gates requests until initialized (`ping` exempt)
 * looks up the handler in the server's registry, validates params, builds
   `Context`, runs the middleware chain, returns the result dict
-* drives ``dispatcher.run()`` and the per-connection lifespan
+* drives `dispatcher.run()` and the per-connection lifespan
 
-`ServerRunner` holds a `Server` directly — `Server` is the registry.
+`ServerRunner` holds a `Server` directly - `Server` is the registry.
 """
 
 from __future__ import annotations
@@ -56,8 +56,8 @@ def otel_middleware(next_on_request: OnRequest) -> OnRequest:
     """Dispatch-tier middleware that wraps each request in an OpenTelemetry span.
 
     Mirrors the span shape of the existing `Server._handle_request`: span name
-    ``"MCP handle <method> [<target>]"``, ``mcp.method.name`` attribute, W3C
-    trace context extracted from ``params._meta`` (SEP-414), and an ERROR
+    `"MCP handle <method> [<target>]"`, `mcp.method.name` attribute, W3C
+    trace context extracted from `params._meta` (SEP-414), and an ERROR
     status if the handler raises.
     """
 
@@ -133,8 +133,8 @@ async def run(self, *, task_status: anyio.abc.TaskStatus[None] = anyio.TASK_STAT
         """Drive the dispatcher until the underlying channel closes.
 
         Composes `dispatch_middleware` over `_on_request` and hands the result
-        to `dispatcher.run()`. ``task_status.started()`` is forwarded so callers
-        can ``await tg.start(runner.run)`` and resume once the dispatcher is
+        to `dispatcher.run()`. `task_status.started()` is forwarded so callers
+        can `await tg.start(runner.run)` and resume once the dispatcher is
         ready to accept requests. Once the dispatcher exits,
         `connection.exit_stack` is unwound (shielded) so any per-connection
         cleanup registered by handlers or middleware runs to completion.
@@ -148,8 +148,8 @@ async def run(self, *, task_status: anyio.abc.TaskStatus[None] = anyio.TASK_STAT
     def _compose_on_request(self) -> OnRequest:
         """Wrap `_on_request` in `dispatch_middleware`, outermost-first.
 
-        Dispatch-tier middleware sees raw ``(dctx, method, params) -> dict``
-        and wraps everything — initialize, METHOD_NOT_FOUND, validation
+        Dispatch-tier middleware sees raw `(dctx, method, params) -> dict`
+        and wraps everything - initialize, METHOD_NOT_FOUND, validation
         failures included. `run()` calls this once and hands the result to
         `dispatcher.run()`.
         """
@@ -212,7 +212,7 @@ def _handle_initialize(self, params: Mapping[str, Any] | None) -> dict[str, Any]
         self.connection.client_info = init.client_info
         self.connection.client_capabilities = init.capabilities
         # TODO: real version negotiation. This always responds with LATEST,
-        # which is wrong — the server should pick the highest version both
+        # which is wrong - the server should pick the highest version both
         # sides support and compute a per-connection feature set from it.
         # See FOLLOWUPS: "Consolidate per-connection mode/negotiation".
         self.connection.protocol_version = (

src/mcp/shared/context.py

@@ -1,4 +1,4 @@
-"""`BaseContext` — the user-facing per-request context.
+"""`BaseContext` - the user-facing per-request context.
 
 Composition over a `DispatchContext`: forwards the transport metadata, the
 back-channel (`send_raw_request`/`notify`), progress reporting, and the cancel
@@ -43,7 +43,7 @@ def transport(self) -> TransportT:
 
     @property
     def cancel_requested(self) -> anyio.Event:
-        """Set when the peer sends ``notifications/cancelled`` for this request."""
+        """Set when the peer sends `notifications/cancelled` for this request."""
         return self._dctx.cancel_requested
 
     @property
@@ -53,7 +53,7 @@ def can_send_request(self) -> bool:
 
     @property
     def meta(self) -> RequestParamsMeta | None:
-        """The inbound request's ``_meta`` field, if present."""
+        """The inbound request's `_meta` field, if present."""
         return self._meta
 
     async def send_raw_request(
@@ -66,7 +66,7 @@ async def send_raw_request(
 
         Raises:
             MCPError: The peer responded with an error.
-            NoBackChannelError: ``can_send_request`` is ``False``.
+            NoBackChannelError: `can_send_request` is `False`.
         """
         return await self._dctx.send_raw_request(method, params, opts)