[v1.x] fix(stdio): handle BrokenResourceError in stdout_reader race (#1960)

[ddullah]

Summary

Fixes #1960. The stdio_client in mcp/client/stdio/__init__.py has a race
condition: read_stream_writer.aclose() in the finally block can close the
stream while the background stdout_reader task is mid-send, which raises
anyio.BrokenResourceError and propagates through the task group as an
ExceptionGroup, failing the caller.

Root cause

The two read_stream_writer.send(...) sites inside stdout_reader were not
guarded against BrokenResourceError. The outer except only caught
ClosedResourceError, which is the sibling class raised on already-closed
streams; BrokenResourceError is raised when the receiver is closed during
an in-flight send, which is the exact shape of this shutdown race.

Fix

• Wrap each read_stream_writer.send(...) in try/except catching both
  ClosedResourceError and BrokenResourceError, then return cleanly.
• Widen the outer except to the same union for defense in depth.
• No API changes.

Alternative considered

Issue #1960 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: it treats the
shutdown race as a graceful exit from stdout_reader specifically, without
altering the task group lifecycle.

Reproduction

Any stdio MCP server that emits log-channel notifications alongside tool
responses will exhibit this when driven by a downstream wrapper (e.g.,
mcp2cli) that opens a fresh stdio_client per invocation. The task group
exits quickly, the subprocess is still flushing output, and the race is
triggered.

Verification

Drove jules-mcp-server (an MCP server that emits notifications/message
log frames during init) through mcp2cli with a list-schedules tool call.

Before this patch:

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 220, in send_nowait
    |     raise BrokenResourceError
    | anyio.BrokenResourceError

After this patch:

{"count": 0, "schedules": []}
EXIT:0

Closes #1960.

[Copilot]

Pull request overview

Fixes a shutdown race in the stdio transport where stdout_reader could raise anyio.BrokenResourceError during an in-flight send() when the stdio client context exits quickly, causing an ExceptionGroup to escape to callers.

Changes:

• Catch anyio.BrokenResourceError (in addition to ClosedResourceError) around read_stream_writer.send(...) calls inside stdout_reader.
• Widen the outer stdout_reader exception handler to also include BrokenResourceError for defense-in-depth.

---

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

[Copilot]

Add a regression test that exercises the shutdown race by having the subprocess emit at least one complete JSON-RPC line to stdout while the stdio_client context exits quickly, and assert that no ExceptionGroup/BrokenResourceError escapes. Current stdio_client tests cover cleanup timing but don’t appear to trigger the in-flight send failure this change handles.