Conform stdio docstrings to Google style

Every docstring now opens with a single-line summary sentence followed by
a blank line and the body. Restores the useful content that an earlier
slimming pass cut from create_windows_process: the SelectorEventLoop /
NotImplementedError fallback explanation, the Job Object purpose, the
assignment-window caveat, and a Returns section explaining the
Process | FallbackProcess union.

Docstring-only change; no code or behavior changes.

Author: maxisbey

src/mcp/client/stdio.py

@@ -1,10 +1,11 @@
-"""stdio client transport: run an MCP server as a subprocess and exchange
-newline-delimited JSON-RPC messages with it over stdin/stdout.
-
-Two pipe tasks bridge the server's pipes to the session's in-memory streams.
-Shutdown follows the MCP spec sequence (close stdin, wait, then kill the
-process tree) inside a cancellation shield with every wait bounded, so a
-cancelled caller can neither leak a live server process nor hang on one.
+"""stdio client transport.
+
+Runs an MCP server as a subprocess and exchanges newline-delimited JSON-RPC
+messages with it over stdin/stdout. Two pipe tasks bridge the server's pipes
+to the session's in-memory streams; shutdown follows the MCP spec sequence
+(close stdin, wait, then kill the process tree) inside a cancellation shield
+with every wait bounded, so a cancelled caller can neither leak a live server
+process nor hang on one.
 """
 
 import logging
@@ -72,7 +73,7 @@
 
 
 def get_default_environment() -> dict[str, str]:
-    """Return only the environment variables that are safe to inherit."""
+    """Returns only the environment variables that are safe to inherit."""
     env: dict[str, str] = {}
 
     for key in DEFAULT_INHERITED_ENV_VARS:
@@ -113,11 +114,11 @@ class StdioServerParameters(BaseModel):
 async def stdio_client(
     server: StdioServerParameters, errlog: TextIO = sys.stderr
 ) -> AsyncGenerator[TransportStreams, None]:
-    """Spawn an MCP server subprocess and connect to it over stdin/stdout.
+    """Spawns an MCP server subprocess and connects to it over stdin/stdout.
 
     Raises:
-        OSError: if the server process cannot be spawned.
-        ValueError: if the spawn parameters are invalid (embedded NUL bytes).
+        OSError: If the server process cannot be spawned.
+        ValueError: If the spawn parameters are invalid (embedded NUL bytes).
     """
     command = _get_executable_command(server.command)
 
@@ -181,7 +182,7 @@ async def stdin_writer() -> None:
             writer_done.set()
 
     async def shutdown() -> None:
-        """Stop traffic, flush, stop the server process, release the streams."""
+        """Winds the transport down: stop traffic, flush, stop the server, release the streams."""
         # Unblock the reader into its drain: a server stuck writing stdout cannot
         # read its stdin, so draining is what lets the flush below complete.
         read_stream.close()
@@ -215,7 +216,7 @@ async def shutdown() -> None:
 
 
 def _parse_line(line: str) -> SessionMessage | Exception:
-    """Parse one stdout line; parse errors are returned as values for the session."""
+    """Parses one stdout line, returning parse errors as values for the session to surface."""
     try:
         message = types.jsonrpc_message_adapter.validate_json(line, by_name=False)
     except ValueError as exc:
@@ -225,8 +226,12 @@ def _parse_line(line: str) -> SessionMessage | Exception:
 
 
 async def _drain_stdout(process: ServerProcess) -> None:
-    """Consume leftover stdout so a flushing server cannot block on a full pipe
-    and miss its chance to exit; shielded, raw bytes, ends when shutdown closes it."""
+    """Consumes and discards the server's remaining stdout.
+
+    Keeps a server flushing buffered output from blocking on a full pipe and
+    missing its chance to exit; shielded, raw bytes, ends when shutdown closes
+    the pipe.
+    """
     assert process.stdout
     with anyio.CancelScope(shield=True):
         with suppress(
@@ -241,7 +246,7 @@ async def _drain_stdout(process: ServerProcess) -> None:
 
 
 async def _stop_server_process(process: ServerProcess) -> None:
-    """Close stdin, give the server a grace period, then kill its whole tree.
+    """Closes stdin, waits out the grace period, then kills the whole tree.
 
     The escalation order is spec text; timeouts and tree-wide scope are SDK policy:
     https://modelcontextprotocol.io/specification/2025-11-25/basic/lifecycle#shutdown
@@ -263,13 +268,13 @@ async def _stop_server_process(process: ServerProcess) -> None:
 
 
 async def _close_pipe(stream: AsyncResource) -> None:
-    """Close a pipe stream, tolerating one already closed, broken, or contended."""
+    """Closes a pipe stream, tolerating one already closed, broken, or contended."""
     with suppress(OSError, anyio.BrokenResourceError, anyio.ClosedResourceError):
         await stream.aclose()
 
 
 async def _wait_for_process_exit(process: ServerProcess, timeout: float) -> bool:
-    """Whether the process died within timeout, by polling returncode.
+    """Returns whether the process died within the timeout, by polling returncode.
 
     Not process.wait(): on asyncio 3.11+ it also waits for pipe EOF, and a
     child that inherited the pipes makes an exited server look hung.
@@ -283,8 +288,11 @@ async def _wait_for_process_exit(process: ServerProcess, timeout: float) -> bool
 
 
 async def _terminate_process_tree(process: ServerProcess) -> None:
-    """Kill the process tree: SIGTERM then SIGKILL to the POSIX process group,
-    or immediate Job Object termination on Windows."""
+    """Kills the process and all its descendants.
+
+    POSIX: SIGTERM to the process group, SIGKILL after FORCE_KILL_TIMEOUT.
+    Windows: immediate Job Object termination (already a hard kill).
+    """
     if sys.platform == "win32":  # pragma: no cover
         await terminate_windows_process_tree(process)
     else:  # pragma: lax no cover
@@ -294,9 +302,12 @@ async def _terminate_process_tree(process: ServerProcess) -> None:
 
 
 def _close_subprocess_transport(process: ServerProcess) -> None:
-    """Close the asyncio subprocess transport, which otherwise stays open (and
-    warns at GC) while a surviving descendant holds a pipe; nothing public
-    exposes it, hence the attribute walk. No-op on trio and the fallback."""
+    """Closes the asyncio subprocess transport, if there is one.
+
+    The transport otherwise stays open (and warns at GC) while a surviving
+    descendant holds a pipe end; nothing public exposes it, hence the attribute
+    walk. No-op on trio and the Windows fallback.
+    """
     transport = getattr(getattr(process, "_process", None), "_transport", None)
     # Duck-typed: uvloop's UVProcessTransport is not an asyncio.SubprocessTransport.
     close = getattr(transport, "close", None)
@@ -307,7 +318,7 @@ def _close_subprocess_transport(process: ServerProcess) -> None:
 
 
 def _get_executable_command(command: str) -> str:
-    """Normalize the command for the current platform."""
+    """Normalizes the command for the current platform."""
     if sys.platform == "win32":  # pragma: no cover
         return get_windows_executable_command(command)
     else:  # pragma: lax no cover
@@ -321,8 +332,10 @@ async def _create_platform_compatible_process(
     errlog: TextIO = sys.stderr,
     cwd: Path | str | None = None,
 ) -> ServerProcess:
-    """Spawn the server in its own kill scope: a new session/process group on
-    POSIX, a Job Object on Windows."""
+    """Spawns the server in its own kill scope.
+
+    A new session/process group on POSIX, a Job Object on Windows.
+    """
     if sys.platform == "win32":  # pragma: no cover
         return await create_windows_process(command, args, env, errlog, cwd)
     else:  # pragma: lax no cover
@@ -336,6 +349,6 @@ async def _create_platform_compatible_process(
 
 
 async def _aclose_all(*streams: AsyncResource) -> None:
-    """Close every given stream."""
+    """Closes every given stream."""
     for stream in streams:
         await stream.aclose()

src/mcp/os/posix/utilities.py

@@ -15,14 +15,14 @@
 
 
 async def terminate_posix_process_tree(process: Process, timeout_seconds: float = 2.0) -> None:
-    """SIGTERM the process group, wait up to timeout_seconds for it to
-    disappear, then SIGKILL whatever remains.
-
-    killpg reaches every descendant atomically, even ones whose parent already
-    exited; daemonizers that left the group escape by design. A group only
-    disappears once every member is dead and reaped, so a client running as
-    PID 1 should reap orphans (e.g. docker run --init) or the wait below runs
-    its full timeout.
+    """Terminates a process and all its descendants on POSIX.
+
+    SIGTERMs the process group, waits up to timeout_seconds for it to
+    disappear, then SIGKILLs whatever remains. killpg reaches every descendant
+    atomically, even ones whose parent already exited; daemonizers that left
+    the group escape by design. A group only disappears once every member is
+    dead and reaped, so a client running as PID 1 should reap orphans (e.g.
+    docker run --init) or the wait below runs its full timeout.
     """
     # The leader's pid is the pgid (start_new_session). Never use getpgid():
     # it fails once the leader is reaped, even with live members left.
@@ -53,7 +53,7 @@ async def terminate_posix_process_tree(process: Process, timeout_seconds: float
 
 
 def _group_alive(pgid: int) -> bool:
-    """Probe the group with signal 0; only ESRCH proves it is gone."""
+    """Probes the group with signal 0; only ESRCH proves it is gone."""
     try:
         os.killpg(pgid, 0)
     except ProcessLookupError:

src/mcp/os/win32/utilities.py

@@ -39,8 +39,11 @@
 
 
 def get_windows_executable_command(command: str) -> str:
-    """Resolve the command to a Windows executable path, trying the bare name
-    first and then the common script extensions (.cmd, .bat, .exe, .ps1)."""
+    """Resolves the command to a Windows executable path.
+
+    Tries the bare name first, then the common script extensions (.cmd, .bat,
+    .exe, .ps1).
+    """
     try:
         if command_path := shutil.which(command):
             return command_path
@@ -56,8 +59,11 @@ def get_windows_executable_command(command: str) -> str:
 
 
 class FallbackProcess:
-    """Async wrapper around subprocess.Popen for Windows event loops without
-    async subprocess support (SelectorEventLoop)."""
+    """Async wrapper around subprocess.Popen for SelectorEventLoop.
+
+    Windows event loops without async subprocess support get this Popen-backed
+    fallback, with anyio file streams wrapping the pipes.
+    """
 
     def __init__(self, popen_obj: subprocess.Popen[bytes]) -> None:
         self.popen: subprocess.Popen[bytes] = popen_obj
@@ -68,29 +74,34 @@ def __init__(self, popen_obj: subprocess.Popen[bytes]) -> None:
         self.stdout = FileReadStream(cast(BinaryIO, stdout)) if stdout else None
 
     async def wait(self) -> int:
-        """Wait for exit by polling; a thread blocked in Popen.wait() cannot be
-        cancelled by anyio, which would defeat every timeout around this call."""
+        """Waits for exit by polling the Popen.
+
+        A thread blocked in Popen.wait() cannot be cancelled by anyio, which
+        would defeat every timeout placed around this call.
+        """
         while (returncode := self.popen.poll()) is None:
             await anyio.sleep(_EXIT_POLL_INTERVAL)
         return returncode
 
     def terminate(self) -> None:
-        """Terminate the subprocess."""
+        """Terminates the subprocess."""
         self.popen.terminate()
 
     def kill(self) -> None:
-        """Kill the subprocess (same hard kill as terminate on Windows)."""
+        """Kills the subprocess (on Windows the same hard kill as terminate)."""
         self.popen.kill()
 
     @property
     def pid(self) -> int:
-        """Return the process ID."""
+        """Returns the process ID."""
         return self.popen.pid
 
     @property
     def returncode(self) -> int | None:
-        """Exit code, or None while running; polls Popen so death is observable
-        without anyone calling wait()."""
+        """The exit code, or None while the process is still running.
+
+        Polls the Popen so death is observable without anyone calling wait().
+        """
         return self.popen.poll()
 
 
@@ -106,9 +117,18 @@ async def create_windows_process(
     errlog: TextIO | None = sys.stderr,
     cwd: Path | str | None = None,
 ) -> Process | FallbackProcess:
-    """Spawn the server inside a Job Object so its children can be terminated
-    with it; falls back to subprocess.Popen on event loops without async
-    subprocess support."""
+    """Creates a subprocess with Job Object support for tree termination.
+
+    Spawns via anyio's open_process; event loops without async subprocess
+    support (notably the SelectorEventLoop) raise NotImplementedError, in which
+    case the spawn falls back to a Popen-backed FallbackProcess. Either way the
+    process is then assigned to a Job Object so its children can be terminated
+    with it; children spawned before the assignment completes are not captured
+    (see the inline note below).
+
+    Returns:
+        Process | FallbackProcess: The spawned process with async stdin/stdout streams.
+    """
     try:
         process = await anyio.open_process(
             [command, *args],
@@ -137,7 +157,7 @@ async def _create_windows_fallback_process(
     errlog: TextIO | None = sys.stderr,
     cwd: Path | str | None = None,
 ) -> FallbackProcess:
-    """Spawn via subprocess.Popen and wrap it in FallbackProcess."""
+    """Spawns via subprocess.Popen and wraps it in FallbackProcess."""
     popen_obj = subprocess.Popen(
         [command, *args],
         stdin=subprocess.PIPE,
@@ -152,7 +172,7 @@ async def _create_windows_fallback_process(
 
 
 def _create_job_object() -> object | None:
-    """Create a Windows Job Object configured to terminate all processes when closed."""
+    """Creates a Windows Job Object configured to terminate all its processes when closed."""
     if sys.platform != "win32" or not win32api or not win32job:
         return None
 
@@ -173,8 +193,10 @@ def _create_job_object() -> object | None:
 
 
 def _maybe_assign_process_to_job(process: Process | FallbackProcess, job: object | None) -> None:
-    """Assign the process to the job and record it for tree termination; on
-    any failure the job handle is closed instead."""
+    """Assigns the process to the job and records it for tree termination.
+
+    On any failure the job handle is closed instead.
+    """
     if job is None:
         return
 
@@ -201,9 +223,12 @@ def _maybe_assign_process_to_job(process: Process | FallbackProcess, job: object
 
 
 def close_process_job(process: Process | FallbackProcess) -> None:
-    """Close the process's Job Object handle, killing any members still alive
-    (KILL_ON_JOB_CLOSE) deterministically rather than at GC time; a deliberate
-    divergence from POSIX, where a graceful server's children are left alive."""
+    """Closes the process's Job Object handle, if it still has one.
+
+    KILL_ON_JOB_CLOSE makes the close also kill any members still alive,
+    deterministically rather than at GC time; a deliberate divergence from
+    POSIX, where a graceful server's children are left alive.
+    """
     if sys.platform != "win32":
         return
 
@@ -213,9 +238,12 @@ def close_process_job(process: Process | FallbackProcess) -> None:
 
 
 async def terminate_windows_process_tree(process: Process | FallbackProcess) -> None:
-    """Terminate the job (an immediate hard kill of every member), or just the
-    process if it has no job. Windows has no tree-wide SIGTERM; the stdin-close
-    grace period is the server's chance to exit cleanly."""
+    """Terminates the process's job, or just the process if it has no job.
+
+    Job termination is an immediate hard kill of every member. Windows has no
+    tree-wide SIGTERM; the stdin-close grace period is the server's chance to
+    exit cleanly.
+    """
     if sys.platform != "win32":
         return
 
@@ -235,7 +263,7 @@ async def terminate_windows_process_tree(process: Process | FallbackProcess) ->
 
 
 def _close_job_handle(job: object) -> None:
-    """Close a Job Object handle, tolerating one that is already closed."""
+    """Closes a Job Object handle, tolerating one that is already closed."""
     if win32api and pywintypes:
         with suppress(pywintypes.error):
             win32api.CloseHandle(job)