Add psutil dependency and improve process termination

- Add psutil as a required dependency for robust cross-platform process management
- Replace platform-specific process termination code with unified psutil implementation
- Update FallbackProcess.__aexit__ to only clean up streams, not terminate process
- Add Windows-specific ResourceWarning filters with documentation
- Add escape_path_for_python helper for cross-platform path handling in tests
- Add WindowsProcessWrapper for consistent process interface in tests
- Update test_stdio_client_universal_cleanup to use sys.executable
- Handle process trees properly on both Windows and Unix systems

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.

Reported-by: Felix Weinberger

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

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

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)

tests/client/test_stdio.py

@@ -1,5 +1,6 @@
 import os
 import shutil
+import subprocess
 import sys
 import tempfile
 import textwrap
@@ -21,6 +22,33 @@
 python: str = shutil.which("python")  # type: ignore
 
 
+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("\\", "/"))
+
+
+class WindowsProcessWrapper:
+    """Minimal wrapper for subprocess.Popen to work with anyio-style process interface."""
+
+    def __init__(self, popen):
+        self.pid = popen.pid
+        self._popen = popen
+        # Add popen attribute for compatibility with _terminate_process_with_children
+        self.popen = popen
+
+    async def wait(self):
+        while self._popen.poll() is None:
+            await anyio.sleep(0.1)
+        return self._popen.returncode
+
+    def terminate(self):
+        self._popen.terminate()
+
+    def kill(self):
+        self._popen.kill()
+
+
 @pytest.mark.anyio
 @pytest.mark.skipif(tee is None, reason="could not find tee command")
 async def test_stdio_context_manager_exiting():
@@ -122,12 +150,13 @@ async def test_stdio_client_universal_cleanup():
     )
 
     server_params = StdioServerParameters(
-        command="python",
+        command=sys.executable,
         args=["-c", long_running_script],
     )
 
     start_time = time.time()
 
+    # Use move_on_after which is more reliable for cleanup scenarios
     # Increased timeout to account for Windows process termination overhead
     with anyio.move_on_after(8.0) as cancel_scope:
         async with stdio_client(server_params) as (read_stream, write_stream):
@@ -335,11 +364,24 @@ def sigterm_handler(signum, frame):
 
 
 @pytest.mark.anyio
+@pytest.mark.filterwarnings("ignore::ResourceWarning" if sys.platform == "win32" else "default")
 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.
     """
 
     # Create a marker file for the child process to write to
@@ -360,15 +402,15 @@ async def test_stdio_client_child_process_cleanup():
             import os
 
             # Mark that parent started
-            with open({repr(parent_marker)}, 'w') as f:
+            with open({escape_path_for_python(parent_marker)}, 'w') as f:
                 f.write('parent started\\n')
 
             # Child script that writes continuously
-            child_script = '''
+            child_script = f'''
             import time
-            with open({repr(marker_file)}, 'a') as f:
+            with open({escape_path_for_python(marker_file)}, 'a') as f:
                 while True:
-                    f.write(f"{{time.time()}}\\\\n")
+                    f.write(f"{time.time()}")
                     f.flush()
                     time.sleep(0.1)
             '''
@@ -385,7 +427,14 @@ async def test_stdio_client_child_process_cleanup():
         print("\nStarting child process termination test...")
 
         # Start the parent process directly with process group
-        proc = await anyio.open_process([sys.executable, "-c", parent_script], start_new_session=True)
+        if sys.platform == "win32":
+            # Windows: Don't use CREATE_NEW_PROCESS_GROUP as it isolates the process
+            # Instead, let it inherit the parent's console which allows taskkill /T to work
+            popen = subprocess.Popen([sys.executable, "-c", parent_script])
+            proc = WindowsProcessWrapper(popen)
+        else:
+            # Unix: Use start_new_session for process group creation
+            proc = await anyio.open_process([sys.executable, "-c", parent_script], start_new_session=True)
 
         # Wait for processes to start
         await anyio.sleep(0.5)
@@ -431,6 +480,7 @@ async def test_stdio_client_child_process_cleanup():
 
 
 @pytest.mark.anyio
+@pytest.mark.filterwarnings("ignore::ResourceWarning" if sys.platform == "win32" else "default")
 async def test_stdio_client_nested_process_tree():
     """
     Test that a nested process tree (parent → child → grandchild) is properly cleaned up.
@@ -456,42 +506,49 @@ async def test_stdio_client_nested_process_tree():
             import os
 
             # Child will spawn grandchild and write to child file
-            child_script = '''import subprocess
+            child_script = f'''import subprocess
             import sys
             import time
 
             # Grandchild just writes to file
-            grandchild_script = \\"\\"\\"import time
-            with open({repr(grandchild_file)}, 'a') as f:
+            grandchild_script = \"\"\"import time
+            with open({escape_path_for_python(grandchild_file)}, 'a') as f:
                 while True:
-                    f.write(f"gc {{time.time()}}\\\\\\\\n")
+                    f.write(f"gc {{time.time()}}")
                     f.flush()
-                    time.sleep(0.1)\\"\\"\\"
+                    time.sleep(0.1)\"\"\"
 
             # Spawn grandchild
             subprocess.Popen([sys.executable, '-c', grandchild_script])
 
             # Child writes to its file
-            with open({repr(child_file)}, 'a') as f:
+            with open({escape_path_for_python(child_file)}, 'a') as f:
                 while True:
-                    f.write(f"c {{time.time()}}\\\\\\\\n")
+                    f.write(f"c {time.time()}")
                     f.flush()
                     time.sleep(0.1)'''
 
             # Spawn child process
             subprocess.Popen([sys.executable, '-c', child_script])
 
             # Parent writes to its file
-            with open({repr(parent_file)}, 'a') as f:
+            with open({escape_path_for_python(parent_file)}, 'a') as f:
                 while True:
-                    f.write(f"p {{time.time()}}\\\\n")
+                    f.write(f"p {time.time()}")
                     f.flush()
                     time.sleep(0.1)
             """
         )
 
         # Start parent process directly
-        proc = await anyio.open_process([sys.executable, "-c", parent_script], start_new_session=True)
+        if sys.platform == "win32":
+            # Windows: Don't use CREATE_NEW_PROCESS_GROUP as it isolates the process
+            # Instead, let it inherit the parent's console which allows taskkill /T to work
+            popen = subprocess.Popen([sys.executable, "-c", parent_script])
+            proc = WindowsProcessWrapper(popen)
+        else:
+            # Unix: Use start_new_session for process group creation
+            proc = await anyio.open_process([sys.executable, "-c", parent_script], start_new_session=True)
 
         # Let all processes start
         await anyio.sleep(1.0)
@@ -530,6 +587,7 @@ async def test_stdio_client_nested_process_tree():
 
 
 @pytest.mark.anyio
+@pytest.mark.filterwarnings("ignore::ResourceWarning" if sys.platform == "win32" else "default")
 async def test_stdio_client_early_parent_exit():
     """
     Test that child processes are cleaned up when parent exits during cleanup.
@@ -551,10 +609,10 @@ async def test_stdio_client_early_parent_exit():
             import signal
 
             # Child that continues running
-            child_script = '''import time
-            with open({repr(marker_file)}, 'a') as f:
+            child_script = f'''import time
+            with open({escape_path_for_python(marker_file)}, 'a') as f:
                 while True:
-                    f.write(f"child {{time.time()}}\\\\n")
+                    f.write(f"child {time.time()}")
                     f.flush()
                     time.sleep(0.1)'''
 
@@ -574,7 +632,14 @@ def handle_term(sig, frame):
         )
 
         # Start the parent process
-        proc = await anyio.open_process([sys.executable, "-c", parent_script], start_new_session=True)
+        if sys.platform == "win32":
+            # Windows: Don't use CREATE_NEW_PROCESS_GROUP as it isolates the process
+            # Instead, let it inherit the parent's console which allows taskkill /T to work
+            popen = subprocess.Popen([sys.executable, "-c", parent_script])
+            proc = WindowsProcessWrapper(popen)
+        else:
+            # Unix: Use start_new_session for process group creation
+            proc = await anyio.open_process([sys.executable, "-c", parent_script], start_new_session=True)
 
         # Let child start writing
         await anyio.sleep(0.5)