docs: fix docstrings across public API surface

Fix typos (e.g., "respose", "loosing", "ommited", "beging"), grammar
issues (article agreement, capitalization of "Pydantic"), and formatting
(missing periods, PEP 257 blank lines after summary, erroneous literal
`\n` in `cli.py` docstrings).

Correct several inaccuracies in docstring content:

- Update `JSONRPCMessage` references to `SessionMessage` in websocket
  docs
- Fix `Returns` → `Yields` for `create_client_server_memory_streams()`
- Fix return type description in `handle_protected_resource_response()`
- Use `async def` / `await` in `Context` and `MCPServer` examples
- Fix `requestedSchema` → `requested_schema` in example code
- Fix `sampling/create_message` → `sampling/createMessage`
- Fix `async get_data()` → `async def get_data()` syntax in example
- Add missing parameter docs (`httpx_client_factory`, `icons`, `meta`,
  etc.)

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()