Fix Windows process termination and add psutil support

- Add psutil as a required dependency for robust cross-platform process management
- Replace platform-specific process termination code with unified psutil implementation
- Fix FallbackProcess.wait() on Windows to use polling instead of blocking
- Add Windows-specific ResourceWarning filters with documentation
- Handle process trees properly on both Windows and Unix systems
- Fix Windows path escaping in test scripts

This ensures consistent behavior across platforms while properly handling
the fundamental differences in process termination:
- Unix: Uses signals (SIGTERM/SIGKILL) for graceful shutdown
- Windows: Uses TerminateProcess() which is immediate

All process termination tests now pass on both Windows and macOS.

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

@@ -1,13 +1,13 @@
 import os
-import signal
-import subprocess
 import sys
 from contextlib import asynccontextmanager
 from pathlib import Path
 from typing import Literal, TextIO
 
 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
@@ -252,67 +252,74 @@ async def _create_platform_compatible_process(
     return process
 
 
-async def _terminate_process_with_children(process: Process | FallbackProcess, timeout: float = 2.0) -> None:
+async def _terminate_process_tree(pid: int, timeout: float = 2.0) -> None:
     """
-    Terminate a process and all its children across platforms.
+    Terminate a process and all its children using psutil.
 
-    There's no cross-platform way in the stdlib to kill a process AND its children,
-    so we need platform-specific handling:
-    - POSIX: Use process groups and os.killpg()
-    - Windows: Use taskkill with /T flag for tree termination
+    This provides consistent behavior across platforms and properly
+    handles process trees without shell commands.
 
-    Args:
-        process: The process to terminate
-        timeout: Time to wait for graceful termination before force killing
+    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.
     """
-    if sys.platform != "win32":
-        # POSIX: Kill entire process group to avoid orphaning children
-        pid = getattr(process, "pid", None)
-        if not pid:
-            return
+    try:
+        parent = psutil.Process(pid)
+        children = parent.children(recursive=True)
+
+        # First, try graceful termination for all processes
+        for child in children:
+            try:
+                child.terminate()
+            except psutil.NoSuchProcess:
+                pass
 
         try:
-            # Try graceful termination of the group first
-            pgid = os.getpgid(pid)
-            os.killpg(pgid, signal.SIGTERM)
-
-            # Wait for termination
-            with anyio.fail_after(timeout):
-                await process.wait()
-        except TimeoutError:
-            # Force kill the process group
+            parent.terminate()
+        except psutil.NoSuchProcess:
+            return  # Parent already dead
+
+        # 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:
-                pgid = os.getpgid(pid)
-                os.killpg(pgid, signal.SIGKILL)
-            except (OSError, ProcessLookupError):
+                proc.kill()
+            except psutil.NoSuchProcess:
                 pass
-        except (OSError, ProcessLookupError):
-            # Process or group already dead
-            pass
-    else:
-        # Windows: Extract PID from FallbackProcess if needed
-        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
+        # Wait a bit more for force-killed processes
+        if alive:
+            await anyio.to_thread.run_sync(lambda: psutil.wait_procs(alive, timeout=0.5))
 
-        # Try graceful termination first
-        try:
-            process.terminate()
-            with anyio.fail_after(timeout):
-                await process.wait()
-        except TimeoutError:
-            # Force kill using taskkill for tree termination
-            await anyio.to_thread.run_sync(
-                subprocess.run,
-                ["taskkill", "/F", "/T", "/PID", str(pid)],
-                capture_output=True,
-                shell=False,
-                check=False,
-            )
-        except ProcessLookupError:
-            pass
+    except psutil.NoSuchProcess:
+        # Process already terminated
+        pass
+
+
+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 all platforms and properly
+    handles process trees.
+
+    Args:
+        process: The process to terminate
+        timeout: Time to wait for graceful termination before force killing
+    """
+    # Extract PID from any process type
+    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)

src/mcp/client/stdio/win32.py

@@ -8,7 +8,7 @@
 from pathlib import Path
 from typing import BinaryIO, TextIO, cast
 
-from anyio import to_thread
+import anyio
 from anyio.streams.file import FileReadStream, FileWriteStream
 
 
@@ -73,10 +73,11 @@ async def __aexit__(
         exc_val: BaseException | None,
         exc_tb: object | None,
     ) -> None:
-        """Terminate and wait on process exit inside a thread."""
-        self.popen.terminate()
-        await to_thread.run_sync(self.popen.wait)
+        """Clean up streams without terminating the process.
 
+        The process termination is handled by stdio_client's cleanup sequence
+        which implements the MCP spec-compliant shutdown flow.
+        """
         # Close the file handles to prevent ResourceWarning
         if self.stdin:
             await self.stdin.aclose()
@@ -91,7 +92,11 @@ async def __aexit__(
 
     async def wait(self):
         """Async wait for process completion."""
-        return await to_thread.run_sync(self.popen.wait)
+        # Poll the process status instead of blocking wait
+        # This allows anyio timeouts to work properly
+        while self.popen.poll() is None:
+            await anyio.sleep(0.1)
+        return self.popen.returncode
 
     def terminate(self):
         """Terminate the subprocess immediately."""