diff --git a/docs/run/index.md b/docs/run/index.md index dbea20d0fe..31476664d1 100644 --- a/docs/run/index.md +++ b/docs/run/index.md @@ -41,6 +41,19 @@ Nothing prints, and it doesn't return. It is waiting on stdin for a host to spea 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)**. +When stdin reaches EOF, the server gives in-flight handlers a drain window (one second by default) +to finish their responses. After the session returns, the stdio transport gives pending output +up to one additional second to finish writing. These are separate budgets: the handler timeout +does not bound the entire process shutdown, including application cleanup. + +Keep reading stdout after closing stdin if you need the remaining responses. If stdout stays +full and unread, transport shutdown stops waiting when its output drain expires; an unfinished +response may be lost. A closed stdout read end still surfaces a write error such as +`BrokenPipeError`. The SDK does not close caller-supplied streams. If a timed-out write is still +running, another stdio transport on the same process output is refused until that write finishes. +For custom output streams, the caller must also let any abandoned write finish before closing +or reusing the stream. + ### Try it ```console diff --git a/src/mcp/server/lowlevel/server.py b/src/mcp/server/lowlevel/server.py index efdf4b216e..6ca0eed3ab 100644 --- a/src/mcp/server/lowlevel/server.py +++ b/src/mcp/server/lowlevel/server.py @@ -77,6 +77,8 @@ async def main(): logger = logging.getLogger(__name__) +DEFAULT_READ_EOF_DRAIN_TIMEOUT_SECONDS = 1.0 + LifespanResultT = TypeVar("LifespanResultT", default=Any) _ParamsT = TypeVar("_ParamsT", bound=BaseModel, default=BaseModel) @@ -698,6 +700,18 @@ async def run( # but also make tracing exceptions much easier during testing and when using # in-process servers. raise_exceptions: bool = False, + # When True, the server is stateless and + # clients can perform initialization with any node. The client must still follow + # the initialization lifecycle, but can do so with any available node + # rather than requiring initialization for each connection. + stateless: bool = False, + # When True, treat read EOF as a half-close and allow in-flight handlers + # to drain their responses via the still-open write stream (e.g. stdio + # with bash-redirected stdin). + drain_on_read_close: bool = False, + # Maximum time to wait for in-flight handlers to drain after read EOF. + # None means wait indefinitely. + read_eof_drain_timeout_seconds: float | None = DEFAULT_READ_EOF_DRAIN_TIMEOUT_SECONDS, ) -> None: """Serve a single connection over the given streams until the read side closes. @@ -715,6 +729,9 @@ async def run( lifespan_state=lifespan_context, init_options=initialization_options, raise_exceptions=raise_exceptions, + session_id=None, + close_write_stream_on_read_close=not drain_on_read_close, + read_eof_drain_timeout_seconds=read_eof_drain_timeout_seconds, ) def streamable_http_app( diff --git a/src/mcp/server/mcpserver/server.py b/src/mcp/server/mcpserver/server.py index bc79c44a36..44901b7541 100644 --- a/src/mcp/server/mcpserver/server.py +++ b/src/mcp/server/mcpserver/server.py @@ -1022,6 +1022,7 @@ async def run_stdio_async(self) -> None: read_stream, write_stream, self._lowlevel_server.create_initialization_options(), + drain_on_read_close=True, ) async def run_sse_async( # pragma: no cover diff --git a/src/mcp/server/runner.py b/src/mcp/server/runner.py index 26e8efbe57..08c92b3ec8 100644 --- a/src/mcp/server/runner.py +++ b/src/mcp/server/runner.py @@ -476,6 +476,8 @@ async def serve_loop( session_id: str | None = None, init_options: InitializationOptions | None = None, raise_exceptions: bool = False, + close_write_stream_on_read_close: bool = True, + read_eof_drain_timeout_seconds: float | None = None, ) -> None: """Drive ``server`` in handshake-only loop mode over a stream pair until the channel closes. @@ -494,6 +496,8 @@ async def serve_loop( # next request (spec: SHOULD NOT, not MUST NOT) sees the initialized # state instead of failing the init-gate. inline_methods=frozenset({"initialize"}), + close_write_stream_on_read_close=close_write_stream_on_read_close, + read_eof_drain_timeout_seconds=read_eof_drain_timeout_seconds, ) connection = Connection.for_loop(dispatcher, session_id=session_id) await serve_connection( @@ -608,6 +612,8 @@ async def serve_dual_era_loop( session_id: str | None = None, init_options: InitializationOptions | None = None, raise_exceptions: bool = False, + close_write_stream_on_read_close: bool = True, + read_eof_drain_timeout_seconds: float | None = None, ) -> None: """Drive `server` over a duplex stream pair, in the era the client opens with. @@ -630,7 +636,13 @@ async def serve_dual_era_loop( ) if opens_modern: await _serve_modern_stream( - server, replayed, write_stream, lifespan_state=lifespan_state, raise_exceptions=raise_exceptions + server, + replayed, + write_stream, + lifespan_state=lifespan_state, + raise_exceptions=raise_exceptions, + close_write_stream_on_read_close=close_write_stream_on_read_close, + read_eof_drain_timeout_seconds=read_eof_drain_timeout_seconds, ) else: await _serve_legacy_stream( @@ -641,6 +653,8 @@ async def serve_dual_era_loop( session_id=session_id, init_options=init_options, raise_exceptions=raise_exceptions, + close_write_stream_on_read_close=close_write_stream_on_read_close, + read_eof_drain_timeout_seconds=read_eof_drain_timeout_seconds, ) finally: await write_stream.aclose() @@ -723,6 +737,8 @@ async def _serve_legacy_stream( session_id: str | None, init_options: InitializationOptions | None, raise_exceptions: bool, + close_write_stream_on_read_close: bool, + read_eof_drain_timeout_seconds: float | None, ) -> None: """Serve a 2025 handshake connection; enveloped requests are refused.""" dispatcher: JSONRPCDispatcher[TransportContext] = JSONRPCDispatcher( @@ -731,6 +747,8 @@ async def _serve_legacy_stream( raise_handler_exceptions=raise_exceptions, # `initialize` inline for the same pipelining reason as `serve_loop`. inline_methods=frozenset({"initialize"}), + close_write_stream_on_read_close=close_write_stream_on_read_close, + read_eof_drain_timeout_seconds=read_eof_drain_timeout_seconds, ) connection = Connection.for_loop(dispatcher, session_id=session_id) runner = ServerRunner(server, connection, lifespan_state, init_options=init_options) @@ -759,10 +777,16 @@ async def _serve_modern_stream( *, lifespan_state: LifespanT, raise_exceptions: bool, + close_write_stream_on_read_close: bool, + read_eof_drain_timeout_seconds: float | None, ) -> None: """Serve a 2026-07-28 connection: every request carries its own envelope.""" dispatcher: JSONRPCDispatcher[TransportContext] = JSONRPCDispatcher( - read_stream, write_stream, raise_handler_exceptions=raise_exceptions + read_stream, + write_stream, + raise_handler_exceptions=raise_exceptions, + close_write_stream_on_read_close=close_write_stream_on_read_close, + read_eof_drain_timeout_seconds=read_eof_drain_timeout_seconds, ) outbound = NotifyOnlyOutbound(dispatcher) diff --git a/src/mcp/server/stdio.py b/src/mcp/server/stdio.py index de8bbae5f1..6806e0d1fe 100644 --- a/src/mcp/server/stdio.py +++ b/src/mcp/server/stdio.py @@ -12,9 +12,11 @@ async def run_server(): """ import os +import queue import sys import threading from collections.abc import Callable +from concurrent.futures import CancelledError from contextlib import asynccontextmanager, suppress from dataclasses import dataclass from io import TextIOWrapper @@ -23,6 +25,7 @@ async def run_server(): import anyio import anyio.lowlevel import mcp_types as types +from anyio.from_thread import BlockingPortal from mcp.os.win32.utilities import rebind_std_handle_to_fd from mcp.shared._context_streams import create_context_streams @@ -41,12 +44,15 @@ async def run_server(): # diverted descriptor. Every failure lands on that safe side. _claims: dict[int, "_StreamClaim"] = {} _claims_lock = threading.Lock() +_STDOUT_DRAIN_TIMEOUT_SECONDS = 1.0 @dataclass class _StreamClaim: fd: int private_fd: int | None = None + pending_io: threading.Event | None = None + released: bool = False class _UnownedTextWrapper(TextIOWrapper): @@ -104,7 +110,11 @@ def _restore_fd(fd: int, private_fd: int) -> bool: def _claim_fd( - fd: int, stream: TextIO, mode: Literal["rb", "wb"], open_diversion: Callable[[], int] + fd: int, + stream: TextIO, + mode: Literal["rb", "wb"], + open_diversion: Callable[[], int], + pending_io: threading.Event | None = None, ) -> tuple[BinaryIO, Callable[[], None] | None]: """Claim a standard stream: divert fd and serve the wire from a private duplicate. @@ -116,8 +126,16 @@ def _claim_fd( """ if not _is_backed_by_fd(stream, fd): return stream.buffer, None - claim = _StreamClaim(fd) + claim = _StreamClaim(fd, pending_io=pending_io) with _claims_lock: + previous = _claims.get(fd) + if ( + previous is not None + and previous.released + and previous.pending_io is not None + and previous.pending_io.is_set() + ): + del _claims[fd] if fd in _claims: raise RuntimeError(f"another stdio_server() in this process has already claimed fd {fd}") _claims[fd] = claim @@ -125,7 +143,11 @@ def _claim_fd( def release() -> None: if claim.private_fd is None or _restore_fd(fd, claim.private_fd): with _claims_lock: - del _claims[fd] + claim.released = True + # A timed-out writer still owns the wire. Refuse a successor + # until it finishes, even though fd 1 has been restored. + if claim.pending_io is None or claim.pending_io.is_set(): + del _claims[fd] try: private_fd = _dup_above_std(fd) @@ -158,6 +180,66 @@ def release() -> None: return os.fdopen(private_fd, mode, closefd=False), release +class _StdoutWriter: + """One daemon thread, with at most one response awaiting completion.""" + + def __init__( + self, + write: Callable[[str], None], + close: Callable[[], None], + portal: BlockingPortal, + stopped: threading.Event, + ) -> None: + self._write = write + self._close = close + self._portal = portal + self._stopped = stopped + self._finished = anyio.Event() + self._stopping = threading.Event() + self._queue: queue.SimpleQueue[tuple[str, anyio.Event] | None] = queue.SimpleQueue() + self._error: Exception | None = None + self._thread = threading.Thread(target=self._run, name="mcp-stdout", daemon=True) + + def start(self) -> None: + self._thread.start() + + def _run(self) -> None: + try: + while (item := self._queue.get()) is not None: + text, complete = item + try: + self._write(text) + except Exception as exc: + # Thread boundary: report the original write/flush failure + # from the async writer, rather than losing it in the thread. + self._error = exc + if not self._stopping.is_set(): + # A write can complete after the drain deadline and portal exit. + with suppress(RuntimeError, CancelledError): + self._portal.call(complete.set) + if self._error is not None: + return + finally: + self._close() + self._stopped.set() + with suppress(RuntimeError, CancelledError): + self._portal.call(self._finished.set) + + async def write(self, text: str) -> None: + complete = anyio.Event() + self._queue.put((text, complete)) + await complete.wait() + if self._error is not None: + raise self._error + + def stop(self) -> None: + self._stopping.set() + self._queue.put(None) + + async def wait_stopped(self) -> None: + await self._finished.wait() + + @asynccontextmanager async def stdio_server(stdin: anyio.AsyncFile[str] | None = None, stdout: anyio.AsyncFile[str] | None = None): """Serve MCP over the process's stdin and stdout. @@ -170,16 +252,51 @@ async def stdio_server(stdin: anyio.AsyncFile[str] | None = None, stdout: anyio. # Re-wrap the binary buffers as UTF-8 text; the std handles' platform encodings are unreliable. restore_stdin: Callable[[], None] | None = None restore_stdout: Callable[[], None] | None = None + writer_stopped = threading.Event() + writer: _StdoutWriter | None = None + stdout_fd: int | None = None + process_stdout = stdout is None or stdout.wrapped is sys.stdout + output_encoding = "utf-8" + output_errors = "strict" + if stdout is not None and stdout.wrapped is sys.stdout: + output_encoding = sys.stdout.encoding or "utf-8" + output_errors = sys.stdout.errors or "strict" try: if not stdin: stdin_buffer, restore_stdin = _claim_fd(0, sys.stdin, "rb", _open_stdin_diversion) stdin = anyio.wrap_file(_UnownedTextWrapper(stdin_buffer, encoding="utf-8", errors="replace")) if not stdout: - stdout_buffer, restore_stdout = _claim_fd(1, sys.stdout, "wb", _open_stdout_diversion) + stdout_buffer, restore_stdout = _claim_fd(1, sys.stdout, "wb", _open_stdout_diversion, writer_stopped) stdout = anyio.wrap_file(_UnownedTextWrapper(stdout_buffer, encoding="utf-8")) + if process_stdout: + try: + output_fileno = stdout.wrapped.fileno() + except (AttributeError, OSError, ValueError): + pass + else: + # Windows CRT writes lock their fd. Keep restoration's source + # descriptor separate so dup2 cannot wait on a blocked write. + stdout_fd = os.dup(output_fileno) + + def write_stdout(text: str) -> None: + if stdout_fd is None: + stdout.wrapped.write(text) + stdout.wrapped.flush() + else: + # Bypass buffered locks, including sys.stdout.buffer in the + # degraded path: Python flushes that buffer during finalization. + data = memoryview(text.replace("\n", os.linesep).encode(output_encoding, errors=output_errors)) + while data: + written = os.write(stdout_fd, data) + data = data[written:] + + def close_stdout() -> None: + if stdout_fd is not None: + os.close(stdout_fd) read_stream_writer, read_stream = create_context_streams[SessionMessage | Exception](0) write_stream, write_stream_reader = create_context_streams[SessionMessage](0) + stdout_done = anyio.Event() async def stdin_reader(): try: @@ -201,16 +318,39 @@ async def stdout_writer(): async with write_stream_reader: async for session_message in write_stream_reader: json = session_message.message.model_dump_json(by_alias=True, exclude_unset=True) - await stdout.write(json + "\n") - await stdout.flush() - except anyio.ClosedResourceError: # pragma: no cover + assert writer is not None + await writer.write(json + "\n") + except anyio.ClosedResourceError: await anyio.lowlevel.checkpoint() + finally: + stdout_done.set() - async with anyio.create_task_group() as tg: - tg.start_soon(stdin_reader) - tg.start_soon(stdout_writer) - yield read_stream, write_stream + async with BlockingPortal() as portal: + writer = _StdoutWriter(write_stdout, close_stdout, portal, writer_stopped) + writer.start() + drain_deadline = float("inf") + try: + async with anyio.create_task_group() as tg: + tg.start_soon(stdin_reader) + tg.start_soon(stdout_writer) + try: + yield read_stream, write_stream + finally: + await write_stream.aclose() + # This is a separate transport budget, after the caller's + # handler drain. Cancelling an AnyIO file worker cannot + # interrupt write(2) or let its non-daemon thread exit. + drain_deadline = anyio.current_time() + _STDOUT_DRAIN_TIMEOUT_SECONDS + with anyio.CancelScope(deadline=drain_deadline, shield=True): + await stdout_done.wait() + tg.cancel_scope.cancel() + finally: + writer.stop() + with anyio.CancelScope(deadline=drain_deadline, shield=True): + await writer.wait_stopped() finally: + if writer is None: + writer_stopped.set() if restore_stdout is not None: restore_stdout() if restore_stdin is not None: diff --git a/src/mcp/shared/jsonrpc_dispatcher.py b/src/mcp/shared/jsonrpc_dispatcher.py index 87bdf31ceb..8092f0b4d1 100644 --- a/src/mcp/shared/jsonrpc_dispatcher.py +++ b/src/mcp/shared/jsonrpc_dispatcher.py @@ -10,6 +10,7 @@ import contextvars import logging from collections.abc import Awaitable, Callable, Mapping +from contextlib import AsyncExitStack from dataclasses import dataclass, field from functools import partial from typing import Any, Generic, Literal, cast @@ -272,6 +273,8 @@ def __init__( peer_cancel_mode: PeerCancelMode = "interrupt", raise_handler_exceptions: bool = False, inline_methods: frozenset[str] = frozenset(), + close_write_stream_on_read_close: bool = True, + read_eof_drain_timeout_seconds: float | None = None, on_stream_exception: Callable[[Exception], Awaitable[None]] | None = None, ) -> None: """Wire a dispatcher over a transport's `SessionMessage` stream pair. @@ -284,6 +287,13 @@ def __init__( inline_methods: Methods awaited in the read loop before the next message is dequeued (e.g. `initialize`); an inline handler that awaits the peer deadlocks the parked loop. + close_write_stream_on_read_close: Close the write stream when the + read stream closes. Full-duplex transports may set this to + false so in-flight handlers can finish writing responses after + input EOF. + read_eof_drain_timeout_seconds: Maximum time to wait for in-flight + handlers to drain after read EOF when the write stream stays + open; None waits indefinitely. on_stream_exception: Observer for `Exception` items on the read stream; without it they are debug-logged and dropped. Awaited inline in the read loop, so a slow observer stalls dispatch. @@ -298,6 +308,8 @@ def __init__( ) self._peer_cancel_mode: PeerCancelMode = peer_cancel_mode self._raise_handler_exceptions = raise_handler_exceptions + self._close_write_stream_on_read_close = close_write_stream_on_read_close + self._read_eof_drain_timeout_seconds = read_eof_drain_timeout_seconds self._inline_methods = inline_methods self.on_stream_exception = on_stream_exception """Observer for ``Exception`` items on the read stream. Mutable so a session can @@ -487,40 +499,50 @@ async def run( Single-shot: once the loop ends the dispatcher stays closed and cannot be restarted. """ self._on_notify_intercept = on_notify_intercept + normal_eof = False try: - # LIFO exits: the write stream closes only after the task-group join, so teardown writes still land. - async with self._write_stream: - async with anyio.create_task_group() as tg: - self._tg = tg - self._running = True - task_status.started() - try: - async with self._read_stream: - try: - async for item in self._read_stream: - # Duck-typed: only `ContextReceiveStream` carries the - # sender's per-message contextvars snapshot. - sender_ctx: contextvars.Context | None = getattr( - self._read_stream, "last_context", None - ) - await self._dispatch(item, on_request, on_notify, sender_ctx) - except anyio.ClosedResourceError: - # Receive end closed under us (stateless SHTTP teardown); same as EOF. - logger.debug("read stream closed by transport; treating as EOF") - # EOF: wake blocked `send_raw_request` waiters with CONNECTION_CLOSED. - self._running = False - self._closed = True - self._fan_out_closed() - finally: - # Cancel in-flight handlers; otherwise the task-group join - # waits on handlers whose callers are already gone. + async with anyio.create_task_group() as tg: + self._tg = tg + self._running = True + task_status.started() + try: + async with AsyncExitStack() as stack: + await stack.enter_async_context(self._read_stream) + if self._close_write_stream_on_read_close: + await stack.enter_async_context(self._write_stream) + try: + async for item in self._read_stream: + # Duck-typed: only `ContextReceiveStream` carries the + # sender's per-message contextvars snapshot. + sender_ctx: contextvars.Context | None = getattr( + self._read_stream, "last_context", None + ) + await self._dispatch(item, on_request, on_notify, sender_ctx) + except anyio.ClosedResourceError: + # Receive end closed under us (stateless SHTTP teardown); same as EOF. + logger.debug("read stream closed by transport; treating as EOF") + # EOF: wake blocked `send_raw_request` waiters with CONNECTION_CLOSED. + self._running = False + self._fan_out_closed() + normal_eof = True + finally: + if not normal_eof or self._close_write_stream_on_read_close: + # Cancel on crash/cancel paths. If read EOF also closed + # writes, handlers cannot drain responses anyway. tg.cancel_scope.cancel() + elif self._read_eof_drain_timeout_seconds is None: + pass + else: + tg.cancel_scope.deadline = anyio.current_time() + self._read_eof_drain_timeout_seconds finally: # Covers cancel/crash paths that skip the inline fan-out; idempotent. self._running = False self._closed = True self._tg = None self._fan_out_closed() + if not self._close_write_stream_on_read_close: + with anyio.CancelScope(shield=True): + await self._write_stream.aclose() await resync_tracer() async def _dispatch( diff --git a/tests/server/test_cancel_handling.py b/tests/server/test_cancel_handling.py index fd0e4b28af..1547ca9471 100644 --- a/tests/server/test_cancel_handling.py +++ b/tests/server/test_cancel_handling.py @@ -13,6 +13,7 @@ InitializeRequestParams, JSONRPCNotification, JSONRPCRequest, + JSONRPCResponse, ListToolsResult, PaginatedRequestParams, TextContent, @@ -107,17 +108,79 @@ async def first_request(): @pytest.mark.anyio -async def test_server_cancels_in_flight_handlers_on_transport_close(): - """When the transport closes mid-request, server.run() must cancel in-flight - handlers rather than join on them. +async def test_server_drains_in_flight_handlers_on_transport_read_eof(): + """When the transport's read side hits EOF (e.g., stdio stdin closes), the + server must drain already-started handlers so their responses reach the + peer via the still-open write side.""" + handler_started = anyio.Event() + handler_allowed_to_finish = anyio.Event() + server_run_returned = anyio.Event() - Without the cancel, the task group waits for the handler, which then tries - to respond through a write stream that _receive_loop already closed, - raising ClosedResourceError and crashing server.run() with exit code 1. + async def handle_call_tool(ctx: ServerRequestContext, params: CallToolRequestParams) -> CallToolResult: + handler_started.set() + await handler_allowed_to_finish.wait() + return CallToolResult(content=[TextContent(type="text", text="ok")]) - This drives server.run() with raw memory streams because InMemoryTransport - wraps it in its own finally-cancel (_memory.py) which masks the bug. - """ + server = Server("test", on_call_tool=handle_call_tool) + + to_server, server_read = anyio.create_memory_object_stream[SessionMessage | Exception](10) + server_write, from_server = anyio.create_memory_object_stream[SessionMessage](10) + + async def run_server(): + await server.run( + server_read, + server_write, + server.create_initialization_options(), + drain_on_read_close=True, + read_eof_drain_timeout_seconds=None, + ) + server_run_returned.set() + + init_req = JSONRPCRequest( + jsonrpc="2.0", + id=1, + method="initialize", + params=InitializeRequestParams( + protocol_version=LATEST_HANDSHAKE_VERSION, + capabilities=ClientCapabilities(), + client_info=Implementation(name="test", version="1.0"), + ).model_dump(by_alias=True, mode="json", exclude_none=True), + ) + initialized = JSONRPCNotification(jsonrpc="2.0", method="notifications/initialized") + call_req = JSONRPCRequest( + jsonrpc="2.0", + id=2, + method="tools/call", + params=CallToolRequestParams(name="slow", arguments={}).model_dump(by_alias=True, mode="json"), + ) + + with anyio.fail_after(5): + async with anyio.create_task_group() as tg, to_server, server_read, server_write, from_server: + tg.start_soon(run_server) + + await to_server.send(SessionMessage(init_req)) + await from_server.receive() # init response + await to_server.send(SessionMessage(initialized)) + await to_server.send(SessionMessage(call_req)) + + await handler_started.wait() + + # Close the server's input stream β€” this is what stdin EOF does. + # server.run()'s incoming_messages loop ends, finally-cancel fires, + # handler gets CancelledError, server.run() returns. + await to_server.aclose() + + handler_allowed_to_finish.set() + + response = await from_server.receive() + assert isinstance(response.message, JSONRPCResponse) + assert response.message.id == 2 + + await server_run_returned.wait() + + +@pytest.mark.anyio +async def test_server_bounds_drain_on_read_eof_when_handler_never_finishes(): handler_started = anyio.Event() handler_cancelled = anyio.Event() server_run_returned = anyio.Event() @@ -128,7 +191,6 @@ async def handle_call_tool(ctx: ServerRequestContext, params: CallToolRequestPar await anyio.sleep_forever() finally: handler_cancelled.set() - # unreachable: sleep_forever only exits via cancellation raise AssertionError # pragma: no cover server = Server("test", on_call_tool=handle_call_tool) @@ -136,6 +198,128 @@ async def handle_call_tool(ctx: ServerRequestContext, params: CallToolRequestPar to_server, server_read = anyio.create_memory_object_stream[SessionMessage | Exception](10) server_write, from_server = anyio.create_memory_object_stream[SessionMessage](10) + async def run_server(): + await server.run( + server_read, + server_write, + server.create_initialization_options(), + drain_on_read_close=True, + read_eof_drain_timeout_seconds=0.05, + ) + server_run_returned.set() + + init_req = JSONRPCRequest( + jsonrpc="2.0", + id=1, + method="initialize", + params=InitializeRequestParams( + protocol_version=LATEST_HANDSHAKE_VERSION, + capabilities=ClientCapabilities(), + client_info=Implementation(name="test", version="1.0"), + ).model_dump(by_alias=True, mode="json", exclude_none=True), + ) + initialized = JSONRPCNotification(jsonrpc="2.0", method="notifications/initialized") + call_req = JSONRPCRequest( + jsonrpc="2.0", + id=2, + method="tools/call", + params=CallToolRequestParams(name="slow", arguments={}).model_dump(by_alias=True, mode="json"), + ) + + with anyio.fail_after(2): + async with anyio.create_task_group() as tg, to_server, server_read, server_write, from_server: + tg.start_soon(run_server) + + await to_server.send(SessionMessage(init_req)) + await from_server.receive() # init response + await to_server.send(SessionMessage(initialized)) + await to_server.send(SessionMessage(call_req)) + + await handler_started.wait() + await to_server.aclose() + + await server_run_returned.wait() + + assert handler_cancelled.is_set() + + +@pytest.mark.anyio +async def test_server_reraises_handler_cancellation_when_server_is_cancelled(): + """If the server task is cancelled (e.g. KeyboardInterrupt), in-flight + request handlers will get cancelled too. Cancellation must be re-raised so + the task group can unwind cleanly.""" + handler_started = anyio.Event() + server_run_returned = anyio.Event() + cancel_scope = anyio.CancelScope() + + async def handle_call_tool(ctx: ServerRequestContext, params: CallToolRequestParams) -> CallToolResult: + handler_started.set() + await anyio.sleep_forever() + raise AssertionError # pragma: no cover + + server = Server("test", on_call_tool=handle_call_tool) + + to_server, server_read = anyio.create_memory_object_stream[SessionMessage | Exception](10) + server_write, from_server = anyio.create_memory_object_stream[SessionMessage](10) + + async def run_server(): + try: + with cancel_scope: + await server.run(server_read, server_write, server.create_initialization_options()) + finally: + server_run_returned.set() + + init_req = JSONRPCRequest( + jsonrpc="2.0", + id=1, + method="initialize", + params=InitializeRequestParams( + protocol_version=LATEST_HANDSHAKE_VERSION, + capabilities=ClientCapabilities(), + client_info=Implementation(name="test", version="1.0"), + ).model_dump(by_alias=True, mode="json", exclude_none=True), + ) + initialized = JSONRPCNotification(jsonrpc="2.0", method="notifications/initialized") + call_req = JSONRPCRequest( + jsonrpc="2.0", + id=2, + method="tools/call", + params=CallToolRequestParams(name="slow", arguments={}).model_dump(by_alias=True, mode="json"), + ) + + with anyio.fail_after(5): + async with anyio.create_task_group() as tg, to_server, server_read, server_write, from_server: + tg.start_soon(run_server) + + await to_server.send(SessionMessage(init_req)) + await from_server.receive() # init response + await to_server.send(SessionMessage(initialized)) + await to_server.send(SessionMessage(call_req)) + + await handler_started.wait() + cancel_scope.cancel() + await server_run_returned.wait() + + +@pytest.mark.anyio +async def test_server_drops_response_when_write_stream_closes_mid_request(): + """If the write side closes while a handler is in-flight, responding may + raise (ClosedResourceError/BrokenResourceError). The handler task should + exit without crashing the server.""" + handler_started = anyio.Event() + allow_finish = anyio.Event() + server_run_returned = anyio.Event() + + async def handle_call_tool(ctx: ServerRequestContext, params: CallToolRequestParams) -> CallToolResult: + handler_started.set() + await allow_finish.wait() + return CallToolResult(content=[TextContent(type="text", text="ok")]) + + server = Server("test", on_call_tool=handle_call_tool) + + to_server, server_read = anyio.create_memory_object_stream[SessionMessage | Exception](10) + server_write, from_server = anyio.create_memory_object_stream[SessionMessage](10) + async def run_server(): await server.run(server_read, server_write, server.create_initialization_options()) server_run_returned.set() @@ -168,16 +352,13 @@ async def run_server(): await to_server.send(SessionMessage(call_req)) await handler_started.wait() + await server_write.aclose() - # Close the server's input stream β€” this is what stdin EOF does. - # server.run()'s incoming_messages loop ends, finally-cancel fires, - # handler gets CancelledError, server.run() returns. + allow_finish.set() await to_server.aclose() await server_run_returned.wait() - assert handler_cancelled.is_set() - @pytest.mark.anyio async def test_server_handles_transport_close_with_pending_server_to_client_requests(): diff --git a/tests/server/test_stdio.py b/tests/server/test_stdio.py index eafd1fca59..e87c27870c 100644 --- a/tests/server/test_stdio.py +++ b/tests/server/test_stdio.py @@ -1,11 +1,14 @@ import gc import io import os +import subprocess import sys +import tempfile import threading from collections.abc import AsyncIterator, Iterator from contextlib import asynccontextmanager, contextmanager from io import TextIOWrapper +from typing import Literal import anyio import anyio.to_thread @@ -13,15 +16,27 @@ from mcp_types import ( CLIENT_CAPABILITIES_META_KEY, CLIENT_INFO_META_KEY, + LATEST_PROTOCOL_VERSION, PROTOCOL_VERSION_META_KEY, SERVER_INFO_META_KEY, + CallToolRequestParams, + CallToolResult, + ClientCapabilities, + Implementation, + InitializeRequestParams, JSONRPCMessage, + JSONRPCNotification, JSONRPCRequest, JSONRPCResponse, + ListToolsResult, + PaginatedRequestParams, + TextContent, + Tool, jsonrpc_message_adapter, ) from typing_extensions import Buffer +from mcp.server import Server, ServerRequestContext, stdio from mcp.server.mcpserver import MCPServer from mcp.server.stdio import stdio_server from mcp.shared.message import SessionMessage @@ -170,6 +185,250 @@ async def _read_from(fd: int) -> bytes: return await anyio.to_thread.run_sync(os.read, fd, 65536, abandon_on_cancel=True) +@pytest.mark.anyio +@pytest.mark.parametrize("operation", ["write", "flush"]) +async def test_stdio_server_bounds_an_injected_stdout_operation( + monkeypatch: pytest.MonkeyPatch, operation: Literal["write", "flush"] +) -> None: + """SDK-defined drain cancellation returns without closing caller-owned output.""" + started = threading.Event() + release = threading.Event() + finished = threading.Event() + + class GatedOutput(io.StringIO): + def write(self, text: str) -> int: + if operation == "write": + self.wait_for_release() + return super().write(text) + + def flush(self) -> None: + if operation == "flush": + self.wait_for_release() + super().flush() + + def wait_for_release(self) -> None: + started.set() + release.wait(5) + finished.set() + + output = GatedOutput() + monkeypatch.setattr(stdio, "_STDOUT_DRAIN_TIMEOUT_SECONDS", 0.01) + try: + with anyio.fail_after(5): + async with stdio_server(stdin=anyio.AsyncFile(io.StringIO()), stdout=anyio.AsyncFile(output)) as ( + read_stream, + write_stream, + ): + read_stream.close() + await write_stream.send(SessionMessage(JSONRPCResponse(jsonrpc="2.0", id=1, result={}))) + assert await anyio.to_thread.run_sync(started.wait, 5) + assert not output.closed + assert not finished.is_set() + finally: + release.set() + assert await anyio.to_thread.run_sync(finished.wait, 5) + + +@pytest.mark.anyio +@pytest.mark.parametrize("operation", ["write", "flush"]) +async def test_stdio_server_surfaces_an_injected_stdout_error( + monkeypatch: pytest.MonkeyPatch, operation: Literal["write", "flush"] +) -> None: + """SDK-defined writer errors propagate from either write or flush.""" + failure = BrokenPipeError("reader disconnected") + + def fail(*args: object) -> None: + raise failure + + output = io.StringIO() + monkeypatch.setattr(output, operation, fail) + + with ( + anyio.fail_after(5), + pytest.RaisesGroup(pytest.RaisesExc(BrokenPipeError, check=lambda exc: exc is failure), flatten_subgroups=True), + ): + async with stdio_server(stdin=anyio.AsyncFile(io.StringIO()), stdout=anyio.AsyncFile(output)) as ( + read_stream, + write_stream, + ): + read_stream.close() + await write_stream.send(SessionMessage(JSONRPCResponse(jsonrpc="2.0", id=1, result={}))) + await anyio.sleep_forever() + + +@pytest.mark.anyio +async def test_stdio_server_ignores_closed_output_during_shutdown(monkeypatch: pytest.MonkeyPatch) -> None: + """SDK-defined teardown tolerates output that is already closed by its owner.""" + output = io.StringIO() + + def closed_write(text: str) -> int: + raise anyio.ClosedResourceError + + monkeypatch.setattr(output, "write", closed_write) + with anyio.fail_after(5): + async with stdio_server(stdin=anyio.AsyncFile(io.StringIO()), stdout=anyio.AsyncFile(output)) as ( + read_stream, + write_stream, + ): + read_stream.close() + await write_stream.send(SessionMessage(JSONRPCResponse(jsonrpc="2.0", id=1, result={}))) + assert not output.closed + + +@pytest.mark.anyio +async def test_stdio_server_completes_partial_raw_stdout_writes(monkeypatch: pytest.MonkeyPatch) -> None: + """SDK-defined framing survives a short OS write without truncating a response.""" + real_write = os.write + + def short_write(fd: int, data: Buffer) -> int: + return real_write(fd, memoryview(data)[:3]) + + response = JSONRPCResponse(jsonrpc="2.0", id=1, result={"text": "δΈ­ζ–‡"}) + with _pipe_planted_on_fd1(monkeypatch) as (out_r, _): + monkeypatch.setattr(os, "write", short_write) + with anyio.fail_after(5): + async with stdio_server(stdin=anyio.AsyncFile(io.StringIO())) as (read_stream, write_stream): + read_stream.close() + await write_stream.send(SessionMessage(response)) + assert await _read_from(out_r) == _frame(response).replace(b"\n", os.linesep.encode()) + + +@pytest.mark.anyio +async def test_stdio_server_retains_the_claim_until_a_timed_out_writer_finishes( + monkeypatch: pytest.MonkeyPatch, +) -> None: + """A later stdio transport must not share the wire with an abandoned write.""" + started = threading.Event() + release = threading.Event() + real_write = os.write + + def gated_write(fd: int, data: Buffer) -> int: + started.set() + release.wait(5) + return real_write(fd, data) + + with _pipe_planted_on_fd1(monkeypatch): + monkeypatch.setattr(os, "write", gated_write) + monkeypatch.setattr(stdio, "_STDOUT_DRAIN_TIMEOUT_SECONDS", 0.01) + try: + with anyio.fail_after(5): + async with stdio_server(stdin=anyio.AsyncFile(io.StringIO())) as (read_stream, write_stream): + read_stream.close() + await write_stream.send(SessionMessage(JSONRPCResponse(jsonrpc="2.0", id=1, result={}))) + assert await anyio.to_thread.run_sync(started.wait, 5) + with pytest.raises(RuntimeError): + await stdio_server(stdin=anyio.AsyncFile(io.StringIO())).__aenter__() + pending_io = stdio._claims[1].pending_io + assert pending_io is not None + finally: + release.set() + assert await anyio.to_thread.run_sync(pending_io.wait, 5) + async with stdio_server(stdin=anyio.AsyncFile(io.StringIO())) as (read_stream, _): + read_stream.close() + + +@pytest.mark.parametrize("output", ["unread", "drained", "closed", "degraded", "explicit"]) +def test_stdio_process_exits_after_stdin_eof_with_a_large_response(output: str) -> None: + """SDK-defined shutdown must finish even when stdout stops accepting a response. + + A raw subprocess peer is necessary: the typed client cannot half-close stdin while + deliberately leaving stdout unread, and a coroutine returning does not prove process exit. + """ + server_code = """ +import sys +import anyio +from mcp.server.mcpserver import MCPServer +from mcp.server import Server +import mcp.server.stdio as stdio +from mcp_types import CallToolResult, TextContent + +if sys.argv[1] == 'degraded': + def no_duplicate(fd): + raise OSError('descriptor isolation unavailable') + stdio._dup_above_std = no_duplicate + +server = MCPServer('stdout-shutdown') +@server.tool() +def big() -> str: + return 'x' * 1_000_000 + +if sys.argv[1] == 'explicit': + async def big_response(ctx, params): + return CallToolResult(content=[TextContent(type='text', text='x' * 1_000_000)]) + lowlevel = Server('stdout-shutdown', on_call_tool=big_response) + async def main(): + async with stdio.stdio_server(stdout=anyio.wrap_file(sys.stdout)) as (read, write): + await lowlevel.run(read, write, lowlevel.create_initialization_options(), drain_on_read_close=True) + anyio.run(main) +else: + server.run() +print('server exited', file=sys.stderr, flush=True) +""" + # A traceback can fill Windows' small stderr pipe and block process exit. + stderr_file = tempfile.TemporaryFile() + process = subprocess.Popen( + [sys.executable, "-c", server_code, output], + stdin=subprocess.PIPE, + stdout=subprocess.PIPE, + stderr=stderr_file, + ) + assert process.stdin is not None + assert process.stdout is not None + # Cover startup and pipe reads too. Coverage-instrumented child startup on + # a host-mounted filesystem can consume its own five-second operation budget. + watchdog = threading.Timer(15, process.kill) + watchdog.daemon = True + watchdog.start() + initialize = JSONRPCRequest( + jsonrpc="2.0", + id=0, + method="initialize", + params={ + "protocolVersion": "2025-06-18", + "capabilities": {}, + "clientInfo": {"name": "shutdown-test", "version": "1"}, + }, + ) + try: + process.stdin.write(_frame(initialize)) + process.stdin.flush() + line = process.stdout.readline() + response = jsonrpc_message_adapter.validate_json(line) + assert isinstance(response, JSONRPCResponse) and response.id == 0 + process.stdin.write( + b'{"jsonrpc":"2.0","method":"notifications/initialized"}\n' + b'{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"big","arguments":{}}}\n' + ) + process.stdin.flush() + # A byte proves the large response has reached the actual OS pipe. + response_bytes = process.stdout.read(1) + if output == "closed": + process.stdout.close() + process.stdin.close() + if output == "drained": + response_bytes += process.stdout.read() + response = jsonrpc_message_adapter.validate_json(response_bytes) + assert isinstance(response, JSONRPCResponse) and response.id == 1 + assert response.result["content"] == [{"type": "text", "text": "x" * 1_000_000}] + returncode = process.wait(timeout=5) + stderr_file.seek(0) + stderr = stderr_file.read() + if output == "closed": + assert returncode != 0 + assert b"BrokenPipeError" in stderr + else: + assert returncode == 0, stderr.decode() + assert b"server exited" in stderr + finally: + watchdog.cancel() + process.kill() + process.wait(timeout=5) + watchdog.join(5) + process.stdin.close() + process.stdout.close() + stderr_file.close() + + @pytest.mark.anyio async def test_stdio_server_takes_stdin_off_the_descriptor_table_while_serving( monkeypatch: pytest.MonkeyPatch, @@ -692,3 +951,87 @@ def test_mcpserver_run_stdio_serves_a_modern_connection(monkeypatch: pytest.Monk # resultType is modern-only: proves the request was served at the discovered version. assert responses[1].result["tools"] == [] assert responses[1].result["resultType"] == "complete" + + +@pytest.mark.anyio +async def test_stdio_server_drains_in_flight_responses_on_stdin_eof(): + """When stdin reaches EOF (e.g., bash-redirected input), already-received + requests must still be able to emit their responses on stdout.""" + stdin = io.StringIO() + stdout = io.StringIO() + + tool_started_count = 0 + both_tools_started = anyio.Event() + allow_tools_to_finish = anyio.Event() + + async def handle_list_tools(ctx: ServerRequestContext, params: PaginatedRequestParams | None) -> ListToolsResult: + return ListToolsResult(tools=[Tool(name="slow", description="test", input_schema={"type": "object"})]) + + async def handle_call_tool(ctx: ServerRequestContext, params: CallToolRequestParams) -> CallToolResult: + nonlocal tool_started_count + tool_started_count += 1 + if tool_started_count == 2: + both_tools_started.set() + await allow_tools_to_finish.wait() + return CallToolResult(content=[TextContent(type="text", text="ok")]) + + server = Server("test", on_list_tools=handle_list_tools, on_call_tool=handle_call_tool) + + init_req = JSONRPCRequest( + jsonrpc="2.0", + id=0, + method="initialize", + params=InitializeRequestParams( + protocol_version=LATEST_PROTOCOL_VERSION, + capabilities=ClientCapabilities(), + client_info=Implementation(name="test", version="1.0"), + ).model_dump(by_alias=True, mode="json", exclude_none=True), + ) + initialized = JSONRPCNotification(jsonrpc="2.0", method="notifications/initialized") + list_tools = JSONRPCRequest(jsonrpc="2.0", id=10, method="tools/list") + call_1 = JSONRPCRequest( + jsonrpc="2.0", + id=1, + method="tools/call", + params=CallToolRequestParams(name="slow", arguments={}).model_dump(by_alias=True, mode="json"), + ) + call_2 = JSONRPCRequest( + jsonrpc="2.0", + id=2, + method="tools/call", + params=CallToolRequestParams(name="slow", arguments={}).model_dump(by_alias=True, mode="json"), + ) + + for message in (init_req, initialized, list_tools, call_1, call_2): + stdin.write(message.model_dump_json(by_alias=True, exclude_none=True) + "\n") + stdin.seek(0) + + async with stdio_server(stdin=anyio.AsyncFile(stdin), stdout=anyio.AsyncFile(stdout)) as ( + read_stream, + write_stream, + ): + with anyio.fail_after(5): + async with anyio.create_task_group() as tg: # pragma: no branch + + async def run_server() -> None: + await server.run( + read_stream, + write_stream, + server.create_initialization_options(), + drain_on_read_close=True, + ) + + tg.start_soon(run_server) + await both_tools_started.wait() + allow_tools_to_finish.set() + + stdout.seek(0) + output_lines = [line.strip() for line in stdout.readlines()] + messages = [jsonrpc_message_adapter.validate_json(line) for line in output_lines] + ids: set[int | str] = set() + for message in messages: + assert isinstance(message, JSONRPCResponse) + ids.add(message.id) + + assert 1 in ids + assert 2 in ids diff --git a/tests/shared/test_jsonrpc_dispatcher.py b/tests/shared/test_jsonrpc_dispatcher.py index 9bee8b2c3b..7f06d3b825 100644 --- a/tests/shared/test_jsonrpc_dispatcher.py +++ b/tests/shared/test_jsonrpc_dispatcher.py @@ -369,6 +369,62 @@ async def drive() -> None: s2c_recv.close() +@pytest.mark.anyio +async def test_run_closes_write_stream_after_clean_eof_without_drain_timeout(): + c2s_send, c2s_recv = anyio.create_memory_object_stream[SessionMessage | Exception](32) + s2c_send, s2c_recv = anyio.create_memory_object_stream[SessionMessage | Exception](32) + server: JSONRPCDispatcher[TransportContext] = JSONRPCDispatcher( + c2s_recv, + s2c_send, + close_write_stream_on_read_close=False, + read_eof_drain_timeout_seconds=None, + ) + on_request, on_notify = echo_handlers(Recorder()) + + with anyio.fail_after(5): + async with anyio.create_task_group() as tg, c2s_send, c2s_recv, s2c_send, s2c_recv: + await tg.start(server.run, on_request, on_notify) + c2s_send.close() + with pytest.raises(anyio.EndOfStream): # pragma: no branch + await s2c_recv.receive() + + +@pytest.mark.anyio +async def test_run_drains_in_flight_handlers_on_clean_eof_without_timeout(): + c2s_send, c2s_recv = anyio.create_memory_object_stream[SessionMessage | Exception](32) + s2c_send, s2c_recv = anyio.create_memory_object_stream[SessionMessage | Exception](32) + server: JSONRPCDispatcher[TransportContext] = JSONRPCDispatcher( + c2s_recv, + s2c_send, + close_write_stream_on_read_close=False, + read_eof_drain_timeout_seconds=None, + ) + handler_started = anyio.Event() + handler_allowed_to_finish = anyio.Event() + + async def handle_request(ctx: DCtx, method: str, params: Mapping[str, Any] | None) -> dict[str, Any]: + handler_started.set() + await handler_allowed_to_finish.wait() + return {"drained": True} + + async def on_notify(ctx: DCtx, method: str, params: Mapping[str, Any] | None) -> None: + raise NotImplementedError + + with anyio.fail_after(5): + async with anyio.create_task_group() as tg, c2s_send, c2s_recv, s2c_send, s2c_recv: + await tg.start(server.run, handle_request, on_notify) + await c2s_send.send(SessionMessage(message=JSONRPCRequest(jsonrpc="2.0", id=1, method="x", params=None))) + await handler_started.wait() + c2s_send.close() + handler_allowed_to_finish.set() + + response = await s2c_recv.receive() + assert isinstance(response, SessionMessage) + assert isinstance(response.message, JSONRPCResponse) + assert response.message.id == 1 + assert response.message.result == {"drained": True} + + @pytest.mark.anyio async def test_run_closes_write_stream_on_exit(): """run() owns both streams; the write end is released once the EOF teardown completes.""" @@ -1042,10 +1098,14 @@ async def test_shutdown_error_response_write_is_bounded_when_the_transport_is_we ): """Cancelling the task group hosting run() completes even when the shutdown error write wedges: only `_SHUTDOWN_WRITE_TIMEOUT` releases the join (SDK-defined). A 0-buffer stream nobody reads - expresses the wedge: run() closes its write stream only after the join, so the send stays parked.""" + expresses the wedge: drain-mode run() closes its write stream only after the join, so the send stays parked.""" c2s_send, c2s_recv = anyio.create_memory_object_stream[SessionMessage | Exception](1) s2c_send, s2c_recv = anyio.create_memory_object_stream[SessionMessage | Exception](0) - server: JSONRPCDispatcher[TransportContext] = JSONRPCDispatcher(c2s_recv, s2c_send) + server: JSONRPCDispatcher[TransportContext] = JSONRPCDispatcher( + c2s_recv, + s2c_send, + close_write_stream_on_read_close=False, + ) handler_started = anyio.Event() async def park(ctx: DCtx, method: str, params: Mapping[str, Any] | None) -> dict[str, Any]: @@ -1076,10 +1136,15 @@ async def on_notify(ctx: DCtx, method: str, params: Mapping[str, Any] | None) -> @pytest.mark.anyio async def test_shutdown_answers_in_flight_request_with_connection_closed(): """Read-stream EOF answers a still-running request with CONNECTION_CLOSED (SDK-defined): - run() keeps the write stream open until the task-group join, so the shielded teardown write lands.""" + drain-mode run() keeps the write stream open until the task-group join, so the shielded teardown write lands.""" c2s_send, c2s_recv = anyio.create_memory_object_stream[SessionMessage | Exception](4) s2c_send, s2c_recv = anyio.create_memory_object_stream[SessionMessage | Exception](4) - server: JSONRPCDispatcher[TransportContext] = JSONRPCDispatcher(c2s_recv, s2c_send) + server: JSONRPCDispatcher[TransportContext] = JSONRPCDispatcher( + c2s_recv, + s2c_send, + close_write_stream_on_read_close=False, + read_eof_drain_timeout_seconds=0.05, + ) handler_started = anyio.Event() async def park(ctx: DCtx, method: str, params: Mapping[str, Any] | None) -> dict[str, Any]: