Implement cross-platform process termination using psutil

Replace platform-specific process termination code with a unified
psutil-based implementation that properly handles process trees on
both Windows and Unix systems.

Key changes:
- Add psutil as a required dependency for robust process management
- Replace custom Windows taskkill and Unix killpg implementations
  with psutil's cross-platform process tree termination
- Fix FallbackProcess.wait() on Windows to use polling instead of
  blocking, allowing anyio timeouts to work properly
- Add Windows-specific ResourceWarning filters with documentation
  explaining why they occur (TerminateProcess() doesn't allow
  cleanup handlers to run)

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.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: felixweinberger

src/mcp/client/stdio/__init__.py

@@ -255,10 +255,10 @@ async def _create_platform_compatible_process(
 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
@@ -268,38 +268,34 @@ async def _terminate_process_tree(pid: int, timeout: float = 2.0) -> None:
     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:
             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)
-        )
-        
+        _, 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)
-            )
-            
+            await anyio.to_thread.run_sync(lambda: psutil.wait_procs(alive, timeout=0.5))
+
     except psutil.NoSuchProcess:
         # Process already terminated
         pass
@@ -308,10 +304,10 @@ async def _terminate_process_tree(pid: int, timeout: float = 2.0) -> None:
 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
@@ -322,8 +318,8 @@ async def _terminate_process_with_children(process: Process | FallbackProcess, t
         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

@@ -9,7 +9,6 @@
 from typing import BinaryIO, TextIO, cast
 
 import anyio
-from anyio import to_thread
 from anyio.streams.file import FileReadStream, FileWriteStream
 
 
@@ -75,7 +74,7 @@ async def __aexit__(
         exc_tb: object | None,
     ) -> None:
         """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.
         """

tests/client/test_stdio.py

@@ -5,7 +5,6 @@
 import tempfile
 import textwrap
 import time
-import warnings
 
 import anyio
 import pytest
@@ -26,7 +25,7 @@
 def escape_path_for_python(path: str) -> str:
     """Escape a file path for use in Python code strings."""
     # Use forward slashes which work on all platforms and don't need escaping
-    return repr(path.replace('\\', '/'))
+    return repr(path.replace("\\", "/"))
 
 
 class WindowsProcessWrapper:
@@ -371,15 +370,15 @@ async def test_stdio_client_child_process_cleanup():
     Test that child processes are properly terminated when the parent is killed.
     This addresses the issue where processes like npx spawn child processes
     that need to be cleaned up.
-    
+
     Note on Windows ResourceWarning:
     On Windows, we may see ResourceWarning about subprocess still running. This is
     expected behavior due to how Windows process termination works:
     - anyio's process.terminate() calls Windows TerminateProcess() API
     - TerminateProcess() immediately kills the process without allowing cleanup
     - subprocess.Popen objects in the killed process can't run their cleanup code
     - Python detects this during garbage collection and issues a ResourceWarning
-    
+
     This warning does NOT indicate a process leak - the processes are properly
     terminated. It only means the Popen objects couldn't clean up gracefully.
     This is a fundamental difference between Windows and Unix process termination.