Implement cross-platform subprocess and children termination

- Add process group support on POSIX systems via start_new_session=True
- Implement _terminate_process_with_children() and _kill_process_and_children()
  functions that properly handle child process cleanup
- On POSIX: Kill entire process group at once to avoid orphaning children
  when parent dies first
- On Windows: Use taskkill /T for process tree termination
- Add pid property to FallbackProcess for consistent interface
- Add proper type annotations (Process | FallbackProcess)
- Replace existing termination logic with new unified approach

This addresses issues from PRs #850 (npx child processes) and #729
(Windows process trees) in a unified, dependency-free way.

Reported-by:surya-prakash-susarla
Reported-by:jingx8885
Github-Issue:#547

Add regression tests for child process termination

- test_stdio_client_child_process_cleanup: Verifies that child processes
  spawned by the parent (like npx spawning node) are properly terminated
- test_stdio_client_nested_process_tree: Tests that deeply nested process
  trees (parent -> child -> grandchild) are all terminated
- test_stdio_client_early_parent_exit: Tests the race condition where
  parent exits during cleanup but children are still terminated via
  process group

These tests verify the fix works correctly across different subprocess
spawning scenarios without requiring external dependencies like psutil.

Author: felixweinberger

pyproject.toml

@@ -32,6 +32,7 @@ dependencies = [
     "pydantic-settings>=2.5.2",
     "uvicorn>=0.23.1; sys_platform != 'emscripten'",
     "jsonschema>=4.20.0",
+    "psutil>=5.9.0,<6.0.0",
 ]
 
 [project.optional-dependencies]
@@ -110,6 +111,9 @@ members = ["examples/servers/*"]
 [tool.uv.sources]
 mcp = { workspace = true }
 
+[[tool.uv.index]]
+url = "https://pypi.org/simple"
+
 [tool.pytest.ini_options]
 log_cli = true
 xfail_strict = true

src/mcp/client/stdio/__init__.py

@@ -6,6 +6,9 @@
 
 import anyio
 import anyio.lowlevel
+import anyio.to_thread
+import psutil
+from anyio.abc import Process
 from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
 from anyio.streams.text import TextReceiveStream
 from pydantic import BaseModel, Field
@@ -14,6 +17,7 @@
 from mcp.shared.message import SessionMessage
 
 from .win32 import (
+    FallbackProcess,
     create_windows_process,
     get_windows_executable_command,
 )
@@ -180,7 +184,7 @@ async def stdin_writer():
             # MCP spec: stdio shutdown sequence
             # 1. Close input stream to server
             # 2. Wait for server to exit, or send SIGTERM if it doesn't exit in time
-            # 3. Send SIGKILL if still not exited
+            # 3. Send SIGKILL if still not exited (forcibly kill on Windows)
             if process.stdin:
                 try:
                     await process.stdin.aclose()
@@ -193,18 +197,9 @@ async def stdin_writer():
                 with anyio.fail_after(2.0):
                     await process.wait()
             except TimeoutError:
-                # Process didn't exit from stdin closure, escalate to SIGTERM
-                try:
-                    process.terminate()
-                    with anyio.fail_after(2.0):
-                        await process.wait()
-                except TimeoutError:
-                    # Process didn't respond to SIGTERM, force kill it
-                    process.kill()
-                    await process.wait()
-                except ProcessLookupError:
-                    # Process already exited, which is fine
-                    pass
+                # Process didn't exit from stdin closure, use our termination function
+                # that handles child processes properly
+                await _terminate_process_with_children(process)
             except ProcessLookupError:
                 # Process already exited, which is fine
                 pass
@@ -245,6 +240,86 @@ async def _create_platform_compatible_process(
     if sys.platform == "win32":
         process = await create_windows_process(command, args, env, errlog, cwd)
     else:
-        process = await anyio.open_process([command, *args], env=env, stderr=errlog, cwd=cwd)
+        # POSIX: Create new process group for easier cleanup
+        process = await anyio.open_process(
+            [command, *args],
+            env=env,
+            stderr=errlog,
+            cwd=cwd,
+            start_new_session=True,  # Creates new process group
+        )
 
     return process
+
+
+async def _terminate_process_with_children(process: Process | FallbackProcess, timeout: float = 2.0) -> None:
+    """
+    Terminate a process and all its children across platforms using psutil.
+
+    This provides consistent behavior across POSIX & Windows platforms and
+    properly handles process trees.
+
+    Args:
+        process: The process to terminate
+        timeout: Time to wait for graceful termination before force killing
+    """
+    pid = getattr(process, "pid", None)
+    if pid is None:
+        popen = getattr(process, "popen", None)
+        if popen:
+            pid = getattr(popen, "pid", None)
+
+    if not pid:
+        return
+
+    await _terminate_process_tree(pid, timeout)
+
+
+async def _terminate_process_tree(pid: int, timeout: float = 2.0) -> None:
+    """
+    Terminate a process and all its children using psutil.
+
+    This provides consistent behavior across platforms and properly
+    handles process trees without shell commands.
+
+    Platform behavior:
+    - On Unix: psutil.terminate() sends SIGTERM, allowing graceful shutdown
+    - On Windows: psutil.terminate() calls TerminateProcess() which is immediate
+      and doesn't allow cleanup handlers to run. This can cause ResourceWarnings
+      for subprocess.Popen objects that don't get to clean up.
+    """
+    try:
+        parent = psutil.Process(pid)
+        children = parent.children(recursive=True)
+
+        # First, try graceful termination for all children
+        for child in children:
+            try:
+                child.terminate()
+            except psutil.NoSuchProcess:
+                pass
+
+        # Then, also terminate the parent process
+        try:
+            parent.terminate()
+        except psutil.NoSuchProcess:
+            return
+
+        # Wait for processes to exit gracefully
+        all_procs = children + [parent]
+        _, alive = await anyio.to_thread.run_sync(lambda: psutil.wait_procs(all_procs, timeout=timeout))
+
+        # Force kill any remaining processes
+        for proc in alive:
+            try:
+                proc.kill()
+            except psutil.NoSuchProcess:
+                pass
+
+        # Wait a bit more for force-killed processes
+        if alive:
+            await anyio.to_thread.run_sync(lambda: psutil.wait_procs(alive, timeout=0.5))
+
+    except psutil.NoSuchProcess:
+        # Process already terminated
+        pass

src/mcp/client/stdio/win32.py

@@ -116,6 +116,11 @@ def kill(self) -> None:
         """Kill the subprocess immediately (alias for terminate)."""
         self.terminate()
 
+    @property
+    def pid(self) -> int:
+        """Return the process ID."""
+        return self.popen.pid
+
 
 # ------------------------
 # Updated function