Add Windows-specific ResourceWarning filters with explanation

On Windows, process termination via TerminateProcess() is immediate and
doesn't allow subprocess.Popen cleanup handlers to run. This causes
ResourceWarnings when garbage collecting Popen objects from forcefully
terminated processes.

Added:
- Windows-specific warning filters to the three process termination tests
- Detailed comment explaining the Windows vs Unix termination differences
- Documentation about where TerminateProcess() is called (via psutil/anyio)

The warnings don't indicate process leaks - processes are properly
terminated. They only indicate that Popen objects couldn't run cleanup
code, which is expected behavior on Windows when forcefully terminating
process trees.

Author: felixweinberger

src/mcp/client/stdio/__init__.py

@@ -258,6 +258,12 @@ async def _terminate_process_tree(pid: int, timeout: float = 2.0) -> None:
     
     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)

tests/client/test_stdio.py

@@ -365,11 +365,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
@@ -468,6 +481,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.
@@ -574,6 +588,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.