Skip to content

Commit 4611fa7

Browse files
Zac-HDclaude
andcommitted
stdio: answer every request read before stdin EOF, stop at once when stdout closes
A stdio client stops the server by closing its stdin, and keeps reading stdout meanwhile (spec lifecycle, shutdown), so every request the server had already read is still owed an answer. The dispatcher cancelled all in-flight handlers the moment its read stream ended, which lost results that had already been computed and were queued behind the stdout writer: with twenty pipelined tool calls, roughly half were never answered, and the process exited 0 (modelcontextprotocol#2678). EOF on stdin is a half-close, and the transport now says so: the stdio read stream is marked `eof_is_half_close`, the server loop turns that into the dispatcher's new `drain_on_eof`, and on a clean EOF the dispatcher lets in-flight handlers run to completion and write their answers, keeps their notifications flowing, and fails any new request to the peer at once. There is no drain budget: a half-closed peer is owed every answer, and how long to wait for the server is the client's decision, which the spec's shutdown sequence already makes (close stdin, wait, kill). A full close still cancels immediately, as do the cancellation and crash paths, and every other transport keeps today's behaviour, since for them EOF means the peer is gone. A client that closes its end of the server's stdout has stopped reading, whatever stdin says. Before, the broken pipe on the next write crashed out of run_stdio_async as a nested exception group, and if the client also held stdin open the exit never came, because the stdin reader sat in an anyio pool thread that cancellation could not interrupt and that interpreter exit would have joined. The stdout writer now treats a broken pipe as the client leaving: it logs, cancels the transport's task group, and the block exits normally, cutting short any in-flight requests, a drain included. Stdin is read on a daemon thread of our own that hands lines to the loop through a blocking portal, so a parked read can hold neither run_stdio_async nor the process open; it ends once stdin does. Co-Authored-By: Claude Fable 5.1 <[email protected]> Claude-Session: https://claude.ai/code/session_01NVnAFCbYxmG2UVcP1g75Ko
1 parent 6affe5c commit 4611fa7

8 files changed

Lines changed: 583 additions & 25 deletions

File tree

‎docs/run/index.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -39,6 +39,8 @@ python server.py
3939

4040
Nothing prints, and it doesn't return. It is waiting on stdin for a host to speak first.
4141

42+
Closing that stdin is how a host stops the server. Requests it has already read are still answered: handlers in flight run to completion, their results go out on stdout, and only then does `run()` return. It also means `python server.py < requests.jsonl > responses.jsonl` answers every request in the file. How long to wait for that is the host's decision, not the server's: a host that has closed stdin and run out of patience kills the process, which is the shutdown sequence the spec describes. A host that closes the server's stdout instead has stopped reading, so the server stops at once, in-flight requests included.
43+
4244
That also means stdout **is the wire**. While serving, the SDK moves the wire to a private descriptor and diverts output that is *flushed* to stdout (a subprocess writing to its inherited stdout, a flushed `print()`) to stderr, where it can't corrupt the stream. Output flushed to stdout *before* serving begins (a wrapper script echoing, an unbuffered import-time print) still lands on the wire, and so does a `print()` that stays buffered until the interpreter drains it at exit. For output you actually want, the `logging` module is the right tool: its handler flushes each record to stderr as it happens. That story is in **[Logging](../handlers/logging.md)**.
4345

4446
### Try it

‎src/mcp/server/runner.py‎

Lines changed: 25 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -494,13 +494,24 @@ async def serve_loop(
494494
# next request (spec: SHOULD NOT, not MUST NOT) sees the initialized
495495
# state instead of failing the init-gate.
496496
inline_methods=frozenset({"initialize"}),
497+
drain_on_eof=_eof_is_half_close(read_stream),
497498
)
498499
connection = Connection.for_loop(dispatcher, session_id=session_id)
499500
await serve_connection(
500501
server, dispatcher, connection=connection, lifespan_state=lifespan_state, init_options=init_options
501502
)
502503

503504

505+
def _eof_is_half_close(read_stream: ReadStream[Any]) -> bool:
506+
"""Whether the transport marked this read stream's EOF as a half-close.
507+
508+
Duck-typed like `_sender_context`: only the stdio transport's `ContextReceiveStream`
509+
sets it, because closing the server's stdin is how a stdio client stops it
510+
while it keeps reading the answers to what it already sent.
511+
"""
512+
return bool(getattr(read_stream, "eof_is_half_close", False))
513+
514+
504515
def _has_modern_envelope(params: Mapping[str, Any] | None) -> bool:
505516
"""Whether `params._meta` carries the reserved protocol-version key.
506517
@@ -623,14 +634,22 @@ async def serve_dual_era_loop(
623634
"""
624635
# This loop owns both streams from the moment it is called, so the write
625636
# stream is closed even if the client leaves before sending any request.
637+
# The replay stream is the SDK's own, so the transport's EOF semantics are
638+
# read off the original stream here and handed down.
639+
drain_on_eof = _eof_is_half_close(read_stream)
626640
try:
627641
async with _replay_from_opening_request(read_stream) as (opening, replayed):
628642
opens_modern = (
629643
opening is not None and opening.method != "initialize" and _has_modern_envelope(opening.params)
630644
)
631645
if opens_modern:
632646
await _serve_modern_stream(
633-
server, replayed, write_stream, lifespan_state=lifespan_state, raise_exceptions=raise_exceptions
647+
server,
648+
replayed,
649+
write_stream,
650+
lifespan_state=lifespan_state,
651+
raise_exceptions=raise_exceptions,
652+
drain_on_eof=drain_on_eof,
634653
)
635654
else:
636655
await _serve_legacy_stream(
@@ -641,6 +660,7 @@ async def serve_dual_era_loop(
641660
session_id=session_id,
642661
init_options=init_options,
643662
raise_exceptions=raise_exceptions,
663+
drain_on_eof=drain_on_eof,
644664
)
645665
finally:
646666
await write_stream.aclose()
@@ -723,6 +743,7 @@ async def _serve_legacy_stream(
723743
session_id: str | None,
724744
init_options: InitializationOptions | None,
725745
raise_exceptions: bool,
746+
drain_on_eof: bool,
726747
) -> None:
727748
"""Serve a 2025 handshake connection; enveloped requests are refused."""
728749
dispatcher: JSONRPCDispatcher[TransportContext] = JSONRPCDispatcher(
@@ -731,6 +752,7 @@ async def _serve_legacy_stream(
731752
raise_handler_exceptions=raise_exceptions,
732753
# `initialize` inline for the same pipelining reason as `serve_loop`.
733754
inline_methods=frozenset({"initialize"}),
755+
drain_on_eof=drain_on_eof,
734756
)
735757
connection = Connection.for_loop(dispatcher, session_id=session_id)
736758
runner = ServerRunner(server, connection, lifespan_state, init_options=init_options)
@@ -759,10 +781,11 @@ async def _serve_modern_stream(
759781
*,
760782
lifespan_state: LifespanT,
761783
raise_exceptions: bool,
784+
drain_on_eof: bool,
762785
) -> None:
763786
"""Serve a 2026-07-28 connection: every request carries its own envelope."""
764787
dispatcher: JSONRPCDispatcher[TransportContext] = JSONRPCDispatcher(
765-
read_stream, write_stream, raise_handler_exceptions=raise_exceptions
788+
read_stream, write_stream, raise_handler_exceptions=raise_exceptions, drain_on_eof=drain_on_eof
766789
)
767790
outbound = NotifyOnlyOutbound(dispatcher)
768791

‎src/mcp/server/stdio.py‎

Lines changed: 49 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,8 @@ async def run_server():
1111
```
1212
"""
1313

14+
import concurrent.futures
15+
import logging
1416
import os
1517
import sys
1618
import threading
@@ -21,13 +23,16 @@ async def run_server():
2123
from typing import BinaryIO, Literal, TextIO
2224

2325
import anyio
26+
import anyio.from_thread
2427
import anyio.lowlevel
2528
import mcp_types as types
2629

2730
from mcp.os.win32.utilities import rebind_std_handle_to_fd
2831
from mcp.shared._context_streams import create_context_streams
2932
from mcp.shared.message import SessionMessage
3033

34+
logger = logging.getLogger(__name__)
35+
3136
if sys.platform != "win32": # pragma: no branch
3237
import fcntl # pragma: lax no cover - POSIX-only line, uncovered on Windows runners
3338

@@ -166,6 +171,14 @@ async def stdio_server(stdin: anyio.AsyncFile[str] | None = None, stdout: anyio.
166171
and children read EOF and their stray output misses the wire; both descriptors
167172
are restored on exit. Explicit streams skip the claim, and a second concurrent
168173
stdio_server() raises RuntimeError.
174+
175+
EOF on stdin is a half-close (spec lifecycle: closing it is how the client asks
176+
the server to stop, and it keeps reading stdout meanwhile), so the read stream is
177+
marked `eof_is_half_close` and the server loop answers every request it has
178+
already read before it returns. Bounding that is the caller's job: the client
179+
is the one that decides how long to wait before killing the process. A client
180+
that closes our stdout instead has stopped reading, so the server stops at once,
181+
in-flight requests included, and the block exits normally.
169182
"""
170183
# Re-wrap the binary buffers as UTF-8 text; the std handles' platform encodings are unreliable.
171184
restore_stdin: Callable[[], None] | None = None
@@ -178,23 +191,40 @@ async def stdio_server(stdin: anyio.AsyncFile[str] | None = None, stdout: anyio.
178191
stdout_buffer, restore_stdout = _claim_fd(1, sys.stdout, "wb", _open_stdout_diversion)
179192
stdout = anyio.wrap_file(_UnownedTextWrapper(stdout_buffer, encoding="utf-8"))
180193

181-
read_stream_writer, read_stream = create_context_streams[SessionMessage | Exception](0)
194+
read_stream_writer, read_stream = create_context_streams[SessionMessage | Exception](0, eof_is_half_close=True)
182195
write_stream, write_stream_reader = create_context_streams[SessionMessage](0)
183196

184197
async def stdin_reader():
185-
try:
186-
async with read_stream_writer:
187-
async for line in stdin:
188-
try:
189-
message = types.jsonrpc_message_adapter.validate_json(line, by_name=False)
190-
except Exception as exc:
191-
await read_stream_writer.send(exc)
192-
continue
193-
194-
session_message = SessionMessage(message)
195-
await read_stream_writer.send(session_message)
196-
except anyio.ClosedResourceError: # pragma: no cover
197-
await anyio.lowlevel.checkpoint()
198+
eof = anyio.Event()
199+
200+
async def deliver(line: str | None) -> None:
201+
if line is None:
202+
eof.set()
203+
return
204+
try:
205+
message = types.jsonrpc_message_adapter.validate_json(line, by_name=False)
206+
except Exception as exc:
207+
await read_stream_writer.send(exc)
208+
return
209+
await read_stream_writer.send(SessionMessage(message))
210+
211+
# A daemon thread of our own, not a pool thread: a pool thread parked in
212+
# readline is joined at interpreter exit, so a client that closed our stdout
213+
# but holds stdin open could pin the process. This one dies with it.
214+
async with read_stream_writer, anyio.from_thread.BlockingPortal() as portal:
215+
216+
def read_lines() -> None:
217+
try:
218+
for line in stdin.wrapped:
219+
portal.call(deliver, line)
220+
portal.call(deliver, None)
221+
except (RuntimeError, concurrent.futures.CancelledError, anyio.BrokenResourceError):
222+
# The server stopped wanting stdin (portal stopped, or the read
223+
# stream torn down) while a read was still in flight.
224+
return
225+
226+
threading.Thread(target=read_lines, name="mcp stdio stdin reader", daemon=True).start()
227+
await eof.wait()
198228

199229
async def stdout_writer():
200230
try:
@@ -203,6 +233,11 @@ async def stdout_writer():
203233
json = session_message.message.model_dump_json(by_alias=True, exclude_unset=True)
204234
await stdout.write(json + "\n")
205235
await stdout.flush()
236+
except BrokenPipeError:
237+
# The client closed its end of our stdout: nobody reads our answers any
238+
# more, whatever stdin says. A full disconnect, so stop everything now.
239+
logger.info("client closed stdout; stopping the stdio server")
240+
tg.cancel_scope.cancel()
206241
except anyio.ClosedResourceError: # pragma: no cover
207242
await anyio.lowlevel.checkpoint()
208243

‎src/mcp/shared/_context_streams.py‎

Lines changed: 13 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -61,11 +61,18 @@ async def __aexit__(
6161
class ContextReceiveStream(Generic[T]):
6262
"""Receive-side wrapper that yields ``T`` and stores the sender's context in ``last_context``."""
6363

64-
__slots__ = ("_inner", "last_context")
64+
__slots__ = ("_inner", "last_context", "eof_is_half_close")
6565

66-
def __init__(self, inner: MemoryObjectReceiveStream[_Envelope[T]]) -> None:
66+
def __init__(self, inner: MemoryObjectReceiveStream[_Envelope[T]], *, eof_is_half_close: bool = False) -> None:
6767
self._inner = inner
6868
self.last_context: contextvars.Context | None = None
69+
self.eof_is_half_close = eof_is_half_close
70+
"""Whether this stream ending means the peer stopped sending but still reads what we send.
71+
72+
A transport sets it for a half-close (stdio: the client closes our stdin, then drains
73+
our stdout), so a consumer finishes the work it already dequeued and answers it. False
74+
means EOF is a full disconnect, so pending work has no one to answer.
75+
"""
6976

7077
async def receive(self) -> T:
7178
ctx, item = await self._inner.receive()
@@ -112,8 +119,10 @@ class create_context_streams(
112119
matching anyio's ``create_memory_object_stream`` API style.
113120
"""
114121

115-
def __new__(cls, max_buffer_size: float = 0) -> tuple[ContextSendStream[T], ContextReceiveStream[T]]: # type: ignore[type-var]
122+
def __new__( # type: ignore[type-var]
123+
cls, max_buffer_size: float = 0, *, eof_is_half_close: bool = False
124+
) -> tuple[ContextSendStream[T], ContextReceiveStream[T]]:
116125
raw_send: MemoryObjectSendStream[Any]
117126
raw_receive: MemoryObjectReceiveStream[Any]
118127
raw_send, raw_receive = anyio.create_memory_object_stream(max_buffer_size)
119-
return (ContextSendStream(raw_send), ContextReceiveStream(raw_receive))
128+
return (ContextSendStream(raw_send), ContextReceiveStream(raw_receive, eof_is_half_close=eof_is_half_close))

‎src/mcp/shared/jsonrpc_dispatcher.py‎

Lines changed: 25 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -273,6 +273,7 @@ def __init__(
273273
raise_handler_exceptions: bool = False,
274274
inline_methods: frozenset[str] = frozenset(),
275275
on_stream_exception: Callable[[Exception], Awaitable[None]] | None = None,
276+
drain_on_eof: bool = False,
276277
) -> None:
277278
"""Wire a dispatcher over a transport's `SessionMessage` stream pair.
278279
@@ -287,6 +288,14 @@ def __init__(
287288
on_stream_exception: Observer for `Exception` items on the read
288289
stream; without it they are debug-logged and dropped. Awaited
289290
inline in the read loop, so a slow observer stalls dispatch.
291+
drain_on_eof: Treat a clean read-stream EOF as a half-close: the
292+
peer stopped sending but still reads (stdio: the client closes
293+
our stdin, then reads our stdout to the end), so in-flight
294+
handlers run to completion and their answers are written before
295+
`run()` returns. Off (the default), EOF cancels them: on a full
296+
disconnect nobody would read the answers. A handler that never
297+
returns then holds `run()` open; bounding that is the caller's
298+
job. Never applies to `run()` being cancelled or crashing.
290299
"""
291300
self._read_stream = read_stream
292301
self._write_stream = write_stream
@@ -299,6 +308,7 @@ def __init__(
299308
self._peer_cancel_mode: PeerCancelMode = peer_cancel_mode
300309
self._raise_handler_exceptions = raise_handler_exceptions
301310
self._inline_methods = inline_methods
311+
self._drain_on_eof = drain_on_eof
302312
self.on_stream_exception = on_stream_exception
303313
"""Observer for ``Exception`` items on the read stream. Mutable so a session can
304314
bind it after the dispatcher is built (e.g. ``ClientSession`` routing into
@@ -311,6 +321,7 @@ def __init__(
311321
self._tg: anyio.abc.TaskGroup | None = None
312322
self._running = False
313323
self._closed = False
324+
self._draining = False
314325

315326
async def send_raw_request(
316327
self,
@@ -458,7 +469,9 @@ async def notify(
458469
torn-down transport drops the notification with a debug log instead
459470
of raising (same policy as the response writes and `ctx.notify`).
460471
"""
461-
if self._closed:
472+
# A draining dispatcher is closed for requests (nothing can answer them) but
473+
# its peer still reads, so notifications from in-flight handlers go out.
474+
if self._closed and not self._draining:
462475
logger.debug("dropped %s: dispatcher closed", method)
463476
return
464477
# Leave `params` unset when None: with `exclude_unset=True` an explicit
@@ -511,14 +524,24 @@ async def run(
511524
self._running = False
512525
self._closed = True
513526
self._fan_out_closed()
514-
finally:
527+
except BaseException:
528+
# Crash or cancel: the in-flight handlers' callers are gone too.
529+
tg.cancel_scope.cancel()
530+
raise
531+
if self._drain_on_eof:
532+
# Half-close: the peer stopped sending but still reads, so the
533+
# join lets in-flight handlers answer. The fan-out above already
534+
# woke any that were waiting on the peer.
535+
self._draining = True
536+
else:
515537
# Cancel in-flight handlers; otherwise the task-group join
516538
# waits on handlers whose callers are already gone.
517539
tg.cancel_scope.cancel()
518540
finally:
519541
# Covers cancel/crash paths that skip the inline fan-out; idempotent.
520542
self._running = False
521543
self._closed = True
544+
self._draining = False
522545
self._tg = None
523546
self._fan_out_closed()
524547
await resync_tracer()

0 commit comments

Comments
 (0)