Repository navigation
fix(stdio): drain responses and bound stdout shutdown after EOF #2680
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
base: main
Are you sure you want to change the base?
Changes from all commits
66568d3
878c45c
aa32ab4
252ff38
8cdc81d
4731187
665ff8b
6b14ed4
7d386fb
ae4142f
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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, | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. P1: The default deadline cancels any in-flight handler still running one second after stdin EOF, so slower tools can still lose the response this change is meant to preserve. Give stdio callers a configurable, suitable drain deadline or avoid timing out handler execution. Prompt for AI agents |
||
| ) -> 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( | ||
|
|
||
| Original file line number | Diff line number | Diff line change | ||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
|
@@ -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,16 +126,28 @@ 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 | ||||||||||||
|
|
||||||||||||
| 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 | ||||||||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. P2: Explicit Prompt for AI agents |
||||||||||||
| 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) | ||||||||||||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. P2: Prompt for AI agents
Suggested change
|
||||||||||||
|
|
||||||||||||
| 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: | ||||||||||||
|
|
||||||||||||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
P2: This reintroduces
Server.run(stateless=)as a no-op, despite the migration guide saying the flag was removed and statelessness comes from connection construction. Remove this parameter and its misleading documentation.Prompt for AI agents