fix(stdio): handle BrokenResourceError in stdout_reader race (#1960)

[ddullah]

Summary

Fixes #1960. Paired with #2449 (the matching [v1.x] backport).

stdio_client has a shutdown race: read_stream_writer.aclose() in the
context's finally block can close the receiver while the background
stdout_reader task is mid-send. anyio raises BrokenResourceError,
which the outer except does not cover (ClosedResourceError is the
sibling class, raised on already-closed streams, not streams closed
during an in-flight send). The exception propagates through the task
group as ExceptionGroup and fails every caller that exits the context
while the subprocess is still writing to stdout.

Trigger

Any MCP server that writes a burst of output (startup banners, log-level
notifications/message frames, scheduler init messages, etc.) paired with
a caller that opens a short-lived stdio_client per invocation. The task
group exits before the subprocess drains, and the race fires.

Reproduced against jules-mcp-server — which emits three
notifications/message frames on init — driven by mcp2cli. Every tool
call surfaced as:

```
ExceptionGroup: unhandled errors in a TaskGroup (1 sub-exception)
+-+---------------- 1 ----------------
| Traceback (most recent call last):
| File '.../mcp/client/stdio/init.py', line 162, in stdout_reader
| await read_stream_writer.send(session_message)
| File '.../anyio/streams/memory.py', line 213, in send_nowait
| raise BrokenResourceError
| anyio.BrokenResourceError
```

Fix

Wrap both read_stream_writer.send(...) sites in stdout_reader with
try/except (ClosedResourceError, BrokenResourceError): return, and
widen the outer except to the same union for defense in depth.
stdout_reader now shuts down cleanly no matter how abruptly the caller
exits the context. No API changes.

Alternative considered

#1960 also suggests tg.cancel_scope.cancel() before the stream closes in
finally. That works but changes shutdown ordering (cancels user-defined
notification handlers, etc.). The chosen fix is narrower: treat the
shutdown race as a graceful exit from stdout_reader specifically, without
altering the task group lifecycle.

Tests

Added test_stdio_client_exits_cleanly_while_server_still_writing in
tests/client/test_stdio.py. Spawns a subprocess that writes a thousand
valid JSONRPC notifications, exits the stdio_client context immediately,
asserts no exception propagates. Wrapped in anyio.fail_after(5.0) per
AGENTS.md. Fails before the fix (ExceptionGroup / BrokenResourceError),
passes after.

Closes #1960.

[Copilot]

Pull request overview

Fixes a shutdown race in stdio_client where the background stdout_reader task could raise anyio.BrokenResourceError (propagating as an ExceptionGroup) if the context exits while an in-flight send() is happening.

Changes:

• Catch anyio.BrokenResourceError (alongside ClosedResourceError) around both read_stream_writer.send(...) call sites in stdout_reader, plus widen the outer handler.
• Add a regression test that exits the stdio_client context while a subprocess is still producing stdout output, asserting the context exits cleanly.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated no comments.

File	Description
src/mcp/client/stdio.py	Makes stdout_reader resilient to stream-closure races by treating ClosedResourceError/BrokenResourceError as a graceful shutdown signal.
tests/client/test_stdio.py	Adds a regression test to ensure fast context exit during server output no longer fails via ExceptionGroup/BrokenResourceError.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.