Unify process termination on POSIX & Windows (+ tests) #1044

felixweinberger · 2025-06-26T21:11:26Z

Motivation and Context

#555, #559 address important but different ways MCP servers can hang or fail to successfully terminate on Windows & POSIX systems.

This PR re-implements #555 by aligning process termination between Windows and Unix to make sure SIGTERM-ignoring processes don't inadvertently cause hangs.

How Has This Been Tested?

New regression tests added for #555 and #559. These were developed and tested on both POSIX and Windows systems.

Original authors: @cristipufu, @LionNatsu

Breaking Changes

None.

Types of changes

Bug fix (non-breaking change which fixes an issue)
New feature (non-breaking change which adds functionality)
Breaking change (fix or feature that would cause existing functionality to change)
Documentation update

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
New and existing tests pass locally
I have added appropriate error handling
I have added or updated documentation as needed

Additional context

This test shows that MCP server cleanup code in lifespan doesn't run when the process is terminated, but does run when stdin is closed first (as implemented in PR #1044). The test includes: - Demonstration of current broken behavior (cleanup doesn't run) - Verification that stdin closure allows graceful shutdown - Windows-specific ResourceWarning handling - Detailed documentation of the issue and solution Github-Issue:#1027

jingx8885 · 2025-07-02T00:04:49Z

Verification of Windows Process Tree Termination Fix
(Originally encountered in #729 context)

Scenario:
In a Python MCP server (uv-pyproject structure) using stdio mode launched via:
uv run --env-file=xxx mcp_server.py

We observed the following process hierarchy:

Python parent process  
  → Python subprocess (middle layer)  
    → uv.exe  
      → MCP stdio service

Failure:
Terminating the middle Python subprocess failed to terminate its descendants, leaving:

uv.exe process
MCP stdio service process

...as orphaned/zombie processes on Windows.

Validation:
➡️ This specific failure mode was resolved by the process termination logic **originally implemented in #729 **.
➡️ The equivalent solution now exists in #1044's unified approach.
➡️ This logic has been production-validated on Windows 11 across:

Live production systems
Daily development/testing cycles
High-frequency restart scenarios

Conclusion:
#1044 successfully addresses this Windows-specific process tree termination flaw. The child process cleanup behavior required for this scenario is correctly implemented.

felixweinberger · 2025-07-03T11:32:34Z

After receiving offline feedback from @dsp-ant I'm splitting this PR into 2:

This PR will keep the changes from Fix stdio_client kill process after timeout #555 Fix hanging on streams when stdio_client exiting #559 Align stdio shutdown sequence with spec #765
Improve child process termination on POSIX & Windows #1078 will house the changes Subprocess kill win32 #729 Fix child process kill error with npx based servers #850 - there's some rework needed to avoid race conditions

FYI for @jingx8885 @surya-prakash-susarla, it's currently in draft and still needs work, I'll tag you once its ready

Kludex · 2025-07-04T06:02:28Z

@agronholm Should we have to create OSS specific logic for termination when using anyio.open_process?

src/mcp/client/stdio/__init__.py

agronholm · 2025-07-04T09:22:55Z

@agronholm Should we have to create OSS specific logic for termination when using anyio.open_process?

I'm not sure I follow. Can you give me more context? I'm very new to this project.

The stdio cleanup was hanging indefinitely when processes ignored termination signals or took too long to exit. This caused the MCP client to freeze during shutdown, especially with servers that don't handle SIGTERM properly. This was already being handled on Windows, but not Unix systems. This Commit unifies the two approaches, removing special logic for windows process termination. The fix introduces a 2-second timeout for process termination. If a process doesn't exit gracefully within this window, it's forcefully killed. This ensures the client always completes cleanup in bounded time while still giving well-behaved servers a chance to exit cleanly. This resolves hanging issues reported when MCP servers ignore standard termination signals. resolves #555 Also adds regression tests for #559. Co-authored-by: Cristian Pufu <cristian.pufu@uipath.com>

This re-establishes behavior before #596 in the default case. - Attempt to use anyio's native open_process function on Windows - Fall back to subprocess.Popen only if NotImplementedError is raised - This improves compatibility with event loops that support async subprocesses - Extract fallback logic into separate function for clarity

felixweinberger · 2025-07-04T17:41:23Z

Hi @Kludex, @agronholm thanks for taking a look!

For context, we actually don't spawn windows processes with anyio.open_process on Windows anymore since #596. We now use subprocess.Popen - the reason was that trying to spawn processes with anyio way was causing NotImplementedError on Windows when using the SelectorEventLoop (apparently the default for Python 3.13+ and e.g. in Streamlit, Google AgentKit google/adk-python#1321), which was blocking Windows development of MCP servers in those environments.

However, your comment made me realize that we should probably explicitly guard for that case and still use anyio by default if possible as a first try, so I added a commit on top of this PR to attempt with anyio first and only in the NotImplementedError case use the FallbackProcess wrapper.

If this could somehow be fixed upstream in anyio that would of course be fantastic - though we did get feedback from Microsoft that Python's asyncio is relatively underdeveloped on Windows, which might be a root cause why we ran into this issue in the first place and might make it difficult to address there?

agronholm · 2025-07-05T00:19:47Z

Any idea why SelectorEventLoop would be the default there? It stopped being the Python default on Windows on Python 3.8.

felixweinberger force-pushed the fweinberger/stream-cleanup-only-approach branch 2 times, most recently from 9f88ea7 to a27fcef Compare June 26, 2025 21:31

felixweinberger mentioned this pull request Jun 26, 2025

Fix stdio_client kill process after timeout #555

Closed

9 tasks

felixweinberger force-pushed the fweinberger/stream-cleanup-only-approach branch 6 times, most recently from caa5628 to 1d495ca Compare June 30, 2025 14:55

felixweinberger changed the title ~~Add regression tests for #559 and #555~~ Add regression tests for #559, #555, #765 Jun 30, 2025

felixweinberger changed the title ~~Add regression tests for #559, #555, #765~~ Add regression tests for #555, #559, #765 Jun 30, 2025

felixweinberger force-pushed the fweinberger/stream-cleanup-only-approach branch from 9e8d74b to 3f6c472 Compare June 30, 2025 15:39

felixweinberger mentioned this pull request Jun 30, 2025

Align stdio shutdown sequence with spec #765

Open

9 tasks

felixweinberger changed the title ~~Add regression tests for #555, #559, #765~~ [WIP] Add regression tests for #555, #559, #765, #729, #850 Jul 1, 2025

felixweinberger force-pushed the fweinberger/stream-cleanup-only-approach branch 15 times, most recently from cbaee2e to e8954dd Compare July 1, 2025 17:45

felixweinberger changed the title ~~[WIP] Add regression tests for #555, #559, #765, #729, #850~~ Unify process termination on POSIX & Windows and add comprehensive regression testing Jul 1, 2025

felixweinberger force-pushed the fweinberger/stream-cleanup-only-approach branch from 50559f7 to 84c4b0f Compare July 3, 2025 11:28

agronholm reviewed Jul 4, 2025

View reviewed changes

src/mcp/client/stdio/__init__.py Outdated Show resolved Hide resolved

felixweinberger force-pushed the fweinberger/stream-cleanup-only-approach branch from 84c4b0f to 4d1804a Compare July 4, 2025 12:16

felixweinberger marked this pull request as draft July 4, 2025 14:39

felixweinberger force-pushed the fweinberger/stream-cleanup-only-approach branch 11 times, most recently from 7dff9c1 to 0205aa0 Compare July 4, 2025 17:08

felixweinberger force-pushed the fweinberger/stream-cleanup-only-approach branch from 0205aa0 to 2be6f09 Compare July 4, 2025 17:13

felixweinberger force-pushed the fweinberger/stream-cleanup-only-approach branch from e817dfb to 7af9e65 Compare July 4, 2025 17:39

felixweinberger marked this pull request as ready for review July 4, 2025 17:41

felixweinberger mentioned this pull request Jul 4, 2025

Improve child process termination on POSIX & Windows #1078

Open

9 tasks

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Unify process termination on POSIX & Windows (+ tests) #1044

Unify process termination on POSIX & Windows (+ tests) #1044

felixweinberger commented Jun 26, 2025 •

edited

Loading

Uh oh!

jingx8885 commented Jul 2, 2025 •

edited

Loading

Uh oh!

felixweinberger commented Jul 3, 2025 •

edited

Loading

Uh oh!

Kludex commented Jul 4, 2025

Uh oh!

Uh oh!

agronholm commented Jul 4, 2025

Uh oh!

felixweinberger commented Jul 4, 2025 •

edited

Loading

Uh oh!

agronholm commented Jul 5, 2025

Uh oh!

Uh oh!

Unify process termination on POSIX & Windows (+ tests) #1044

Are you sure you want to change the base?

Unify process termination on POSIX & Windows (+ tests) #1044

Conversation

felixweinberger commented Jun 26, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Motivation and Context

How Has This Been Tested?

Breaking Changes

Types of changes

Checklist

Additional context

Uh oh!

jingx8885 commented Jul 2, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

felixweinberger commented Jul 3, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Kludex commented Jul 4, 2025

Uh oh!

Uh oh!

agronholm commented Jul 4, 2025

Uh oh!

felixweinberger commented Jul 4, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

agronholm commented Jul 5, 2025

Uh oh!

Uh oh!

felixweinberger commented Jun 26, 2025 •

edited

Loading

jingx8885 commented Jul 2, 2025 •

edited

Loading

felixweinberger commented Jul 3, 2025 •

edited

Loading

felixweinberger commented Jul 4, 2025 •

edited

Loading