docs: fix docstrings across public API surface (#2095)

Author: jonathanhefner

src/mcp/cli/cli.py

@@ -317,12 +317,12 @@ def run(
 ) -> None:  # pragma: no cover
     """Run an MCP server.
 
-    The server can be specified in two ways:\n
-    1. Module approach: server.py - runs the module directly, expecting a server.run() call.\n
-    2. Import approach: server.py:app - imports and runs the specified server object.\n\n
+    The server can be specified in two ways:
+    1. Module approach: server.py - runs the module directly, expecting a server.run() call.
+    2. Import approach: server.py:app - imports and runs the specified server object.
 
     Note: This command runs the server directly. You are responsible for ensuring
-    all dependencies are available.\n
+    all dependencies are available.
     For dependency management, use `mcp install` or `mcp dev` instead.
     """  # noqa: E501
     file, server_object = _parse_file_path(file_spec)

src/mcp/client/auth/extensions/client_credentials.py

@@ -450,7 +450,7 @@ def _add_client_authentication_jwt(self, *, token_data: dict[str, Any]):  # prag
         # When using private_key_jwt, in a client_credentials flow, we use RFC 7523 Section 2.2
         token_data["client_assertion"] = assertion
         token_data["client_assertion_type"] = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer"
-        # We need to set the audience to the resource server, the audience is difference from the one in claims
+        # We need to set the audience to the resource server, the audience is different from the one in claims
         # it represents the resource server that will validate the token
         token_data["audience"] = self.context.get_resource_url()
 

src/mcp/client/auth/oauth2.py

@@ -215,6 +215,7 @@ def prepare_token_auth(
 
 class OAuthClientProvider(httpx.Auth):
     """OAuth2 authentication for httpx.
+
     Handles OAuth flow with automatic client registration and token storage.
     """
 
@@ -241,7 +242,7 @@ def __init__(
             callback_handler: Handler for authorization callbacks.
             timeout: Timeout for the OAuth flow.
             client_metadata_url: URL-based client ID. When provided and the server
-                advertises client_id_metadata_document_supported=true, this URL will be
+                advertises client_id_metadata_document_supported=True, this URL will be
                 used as the client_id instead of performing dynamic client registration.
                 Must be a valid HTTPS URL with a non-root pathname.
             validate_resource_url: Optional callback to override resource URL validation.

src/mcp/client/auth/utils.py

@@ -38,7 +38,7 @@ def extract_field_from_www_auth(response: Response, field_name: str) -> str | No
 
 
 def extract_scope_from_www_auth(response: Response) -> str | None:
-    """Extract scope parameter from WWW-Authenticate header as per RFC6750.
+    """Extract scope parameter from WWW-Authenticate header as per RFC 6750.
 
     Returns:
         Scope string if found in WWW-Authenticate header, None otherwise
@@ -47,7 +47,7 @@ def extract_scope_from_www_auth(response: Response) -> str | None:
 
 
 def extract_resource_metadata_from_www_auth(response: Response) -> str | None:
-    """Extract protected resource metadata URL from WWW-Authenticate header as per RFC9728.
+    """Extract protected resource metadata URL from WWW-Authenticate header as per RFC 9728.
 
     Returns:
         Resource metadata URL if found in WWW-Authenticate header, None otherwise
@@ -67,8 +67,8 @@ def build_protected_resource_metadata_discovery_urls(www_auth_url: str | None, s
     3. Fall back to root-based well-known URI: /.well-known/oauth-protected-resource
 
     Args:
-        www_auth_url: optional resource_metadata url extracted from the WWW-Authenticate header
-        server_url: server url
+        www_auth_url: Optional resource_metadata URL extracted from the WWW-Authenticate header
+        server_url: Server URL
 
     Returns:
         Ordered list of URLs to try for discovery
@@ -120,10 +120,10 @@ def get_client_metadata_scopes(
 
 
 def build_oauth_authorization_server_metadata_discovery_urls(auth_server_url: str | None, server_url: str) -> list[str]:
-    """Generate ordered list of (url, type) tuples for discovery attempts.
+    """Generate an ordered list of URLs for authorization server metadata discovery.
 
     Args:
-        auth_server_url: URL for the OAuth Authorization Metadata URL if found, otherwise None
+        auth_server_url: OAuth Authorization Server Metadata URL if found, otherwise None
         server_url: URL for the MCP server, used as a fallback if auth_server_url is None
     """
 
@@ -170,7 +170,7 @@ async def handle_protected_resource_response(
     Per SEP-985, supports fallback when discovery fails at one URL.
 
     Returns:
-        True if metadata was successfully discovered, False if we should try next URL
+        ProtectedResourceMetadata if successfully discovered, None if we should try next URL
     """
     if response.status_code == 200:
         try:
@@ -206,7 +206,7 @@ def create_oauth_metadata_request(url: str) -> Request:
 def create_client_registration_request(
     auth_server_metadata: OAuthMetadata | None, client_metadata: OAuthClientMetadata, auth_base_url: str
 ) -> Request:
-    """Build registration request or skip if already registered."""
+    """Build a client registration request."""
 
     if auth_server_metadata and auth_server_metadata.registration_endpoint:
         registration_url = str(auth_server_metadata.registration_endpoint)
@@ -261,7 +261,7 @@ def should_use_client_metadata_url(
     """Determine if URL-based client ID (CIMD) should be used instead of DCR.
 
     URL-based client IDs should be used when:
-    1. The server advertises client_id_metadata_document_supported=true
+    1. The server advertises client_id_metadata_document_supported=True
     2. The client has a valid client_metadata_url configured
 
     Args:
@@ -306,7 +306,7 @@ def create_client_info_from_metadata_url(
 async def handle_token_response_scopes(
     response: Response,
 ) -> OAuthToken:
-    """Parse and validate token response with optional scope validation.
+    """Parse and validate a token response.
 
     Parses token response JSON. Callers should check response.status_code before calling.
 

src/mcp/client/client.py

@@ -37,8 +37,8 @@
 class Client:
     """A high-level MCP client for connecting to MCP servers.
 
-    Currently supports in-memory transport for testing. Pass a Server or
-    MCPServer instance directly to the constructor.
+    Supports in-memory transport for testing (pass a Server or MCPServer instance),
+    Streamable HTTP transport (pass a URL string), or a custom Transport instance.
 
     Example:
         ```python
@@ -205,7 +205,7 @@ async def read_resource(self, uri: str, *, meta: RequestParamsMeta | None = None
 
         Args:
             uri: The URI of the resource to read.
-            meta: Additional metadata for the request
+            meta: Additional metadata for the request.
 
         Returns:
             The resource content.
@@ -239,7 +239,7 @@ async def call_tool(
             meta: Additional metadata for the request
 
         Returns:
-            The tool result
+            The tool result.
         """
         return await self.session.call_tool(
             name=name,

src/mcp/client/experimental/tasks.py

@@ -83,7 +83,7 @@ async def call_tool_as_task(
                 status = await session.experimental.get_task(task_id)
                 if status.status == "completed":
                     break
-                await asyncio.sleep(0.5)
+                await anyio.sleep(0.5)
 
             # Get result
             final = await session.experimental.get_task_result(task_id, CallToolResult)
@@ -177,7 +177,7 @@ async def poll_task(self, task_id: str) -> AsyncIterator[types.GetTaskResult]:
         """Poll a task until it reaches a terminal status.
 
         Yields GetTaskResult for each poll, allowing the caller to react to
-        status changes (e.g., handle input_required). Exits when task reaches
+        status changes (e.g., handle input_required). Exits when the task reaches
         a terminal status (completed, failed, cancelled).
 
         Respects the pollInterval hint from the server.

src/mcp/client/session_group.py

@@ -3,7 +3,7 @@
 Tools, resources, and prompts are aggregated across servers. Servers may
 be connected to or disconnected from at any point after initialization.
 
-This abstractions can handle naming collisions using a custom user-provided hook.
+This abstraction can handle naming collisions using a custom user-provided hook.
 """
 
 import contextlib
@@ -30,7 +30,7 @@
 
 
 class SseServerParameters(BaseModel):
-    """Parameters for initializing a sse_client."""
+    """Parameters for initializing an sse_client."""
 
     # The endpoint URL.
     url: str
@@ -67,8 +67,8 @@ class StreamableHttpParameters(BaseModel):
 ServerParameters: TypeAlias = StdioServerParameters | SseServerParameters | StreamableHttpParameters
 
 
-# Use dataclass instead of pydantic BaseModel
-# because pydantic BaseModel cannot handle Protocol fields.
+# Use dataclass instead of Pydantic BaseModel
+# because Pydantic BaseModel cannot handle Protocol fields.
 @dataclass
 class ClientSessionParameters:
     """Parameters for establishing a client session to an MCP server."""
@@ -119,7 +119,7 @@ class _ComponentNames(BaseModel):
     _session_exit_stacks: dict[mcp.ClientSession, contextlib.AsyncExitStack]
 
     # Optional fn consuming (component_name, server_info) for custom names.
-    # This is provide a means to mitigate naming conflicts across servers.
+    # This is to provide a means to mitigate naming conflicts across servers.
     # Example: (tool_name, server_info) => "{result.server_info.name}.{tool_name}"
     _ComponentNameHook: TypeAlias = Callable[[str, types.Implementation], str]
     _component_name_hook: _ComponentNameHook | None

src/mcp/client/sse.py

@@ -47,6 +47,7 @@ async def sse_client(
         headers: Optional headers to include in requests.
         timeout: HTTP timeout for regular operations (in seconds).
         sse_read_timeout: Timeout for SSE read operations (in seconds).
+        httpx_client_factory: Factory function for creating the HTTPX client.
         auth: Optional HTTPX authentication handler.
         on_session_created: Optional callback invoked with the session ID when received.
     """

src/mcp/client/stdio.py

@@ -87,17 +87,17 @@ class StdioServerParameters(BaseModel):
 
     encoding: str = "utf-8"
     """
-    The text encoding used when sending/receiving messages to the server
+    The text encoding used when sending/receiving messages to the server.
 
-    defaults to utf-8
+    Defaults to utf-8.
     """
 
     encoding_error_handler: Literal["strict", "ignore", "replace"] = "strict"
     """
     The text encoding error handler.
 
     See https://docs.python.org/3/library/codecs.html#codec-base-classes for
-    explanations of possible values
+    explanations of possible values.
     """
 
 

src/mcp/client/streamable_http.py

@@ -358,7 +358,7 @@ async def _handle_sse_response(
                     resumption_callback=(ctx.metadata.on_resumption_token_update if ctx.metadata else None),
                     is_initialization=is_initialization,
                 )
-                # If the SSE event indicates completion, like returning respose/error
+                # If the SSE event indicates completion, like returning response/error
                 # break the loop
                 if is_complete:
                     await response.aclose()