From 889aa0fcbcd058c2c93a3752a4b4d9ee2f7d031b Mon Sep 17 00:00:00 2001
From: Soham Dahivalkar <sohamdahivalkar4@gmail.com>
Date: Sun, 31 May 2026 04:16:29 +0530
Subject: [PATCH] docs: add missing docstrings to core public API methods

Add docstrings to undocumented public methods in the client and server
session modules:

- ClientSession.initialize(): document handshake flow, return type, and
  RuntimeError on unsupported protocol version
- ServerSession.client_params: document property returning client's
  InitializeRequestParams
- ServerSession.incoming_messages: document the ServerRequestResponder
  stream property
- remove_request_params(): document URL query-stripping utility

These are the most user-facing public methods that currently lack
docstrings, making IDE tooltips and help() output incomplete.
---
 src/mcp/client/session.py | 14 ++++++++++++++
 src/mcp/client/sse.py     |  5 +++++
 src/mcp/server/session.py | 10 ++++++++++
 3 files changed, 29 insertions(+)

diff --git a/src/mcp/client/session.py b/src/mcp/client/session.py
index 86113874be..c6a8e8def1 100644
--- a/src/mcp/client/session.py
+++ b/src/mcp/client/session.py
@@ -146,6 +146,20 @@ def _receive_notification_adapter(self) -> TypeAdapter[types.ServerNotification]
         return types.server_notification_adapter
 
     async def initialize(self) -> types.InitializeResult:
+        """Perform the MCP initialization handshake with the server.
+
+        Sends an InitializeRequest with the client's capabilities (sampling,
+        elicitation, roots, tasks) and client_info, waits for the server's
+        InitializeResult, validates the negotiated protocol version, stores
+        the result, and sends an InitializedNotification.
+
+        Returns:
+            The server's InitializeResult containing server_info,
+            capabilities, instructions, and the negotiated protocol_version.
+
+        Raises:
+            RuntimeError: If the server returns an unsupported protocol version.
+        """
         sampling = (
             (self._sampling_capabilities or types.SamplingCapability())
             if self._sampling_callback is not _default_sampling_callback
diff --git a/src/mcp/client/sse.py b/src/mcp/client/sse.py
index 74e5ba8062..5bb4d86a18 100644
--- a/src/mcp/client/sse.py
+++ b/src/mcp/client/sse.py
@@ -18,6 +18,11 @@
 
 
 def remove_request_params(url: str) -> str:
+    """Strip query parameters from a URL, returning only scheme + host + path.
+
+    Used to derive the base endpoint URL from an SSE connection URL that may
+    include session identifiers or other transient query parameters.
+    """
     return urljoin(url, urlparse(url).path)
 
 
diff --git a/src/mcp/server/session.py b/src/mcp/server/session.py
index fc2f97a9cb..ea78e93b19 100644
--- a/src/mcp/server/session.py
+++ b/src/mcp/server/session.py
@@ -107,6 +107,11 @@ def _receive_notification_adapter(self) -> TypeAdapter[types.ClientNotification]
 
     @property
     def client_params(self) -> types.InitializeRequestParams | None:
+        """The client's InitializeRequestParams received during handshake.
+
+        Contains client_info, capabilities, and the requested protocol_version.
+        Returns None if the session has not yet been initialized.
+        """
         return self._client_params
 
     @property
@@ -689,4 +694,9 @@ async def _handle_incoming(self, req: ServerRequestResponder) -> None:
 
     @property
     def incoming_messages(self) -> MemoryObjectReceiveStream[ServerRequestResponder]:
+        """Stream of incoming client requests wrapped as ServerRequestResponder objects.
+
+        Each item in the stream pairs the original client request with a
+        responder that the server handler uses to send back a result or error.
+        """
         return self._incoming_message_stream_reader