Skip to content

Add owned stdio clients for local MCP servers - #16

Merged
quinnj merged 2 commits into
mainfrom
feat/stdio-client
Oct 2, 2026
Merged

quinnj merged 2 commits into
mainfrom
feat/stdio-client

Conversation

@quinnj

@quinnj quinnj commented Sep 26, 2026 •

Copy link
Copy Markdown
Member

Local MCP servers using stdin/stdout cannot currently use this package's client: a manually constructed stdio descriptor fails during initialization with transport_unsupported. Add the qualified ModelContextProtocol.prepare_stdio_client(command) constructor, including a do-block form, and reuse the existing initialization, list/call, handler, and termination APIs.

The client owns one child process and its protocol pipes. It matches concurrent responses by exact request ID, separates stderr, bounds frames and pending work, and applies one deadline to queued writes and response waits. EOF or invalid output fails pending calls and starts process cleanup. Write failures preserve the original failure; complete responses received before EOF remain available.

Notifications retain arrival order. Legacy server requests run in bounded, owned tasks so a handler's nested call can receive another server request before completing. Request handlers may overlap notifications and other request handlers. External close waits for all owned tasks under one deadline. A callback calling close waits for process and IO shutdown without waiting on other callbacks, avoiding cycles between callbacks that close concurrently. Unfinished callbacks remain owned for a later external close; arbitrary blocked user code still needs cooperative release.

Protocol selection is explicit: 2025-11-25 by default, or 2026-07-28 discovery and request metadata. Automatic version probing/restart/replay, modern subscriptions, and Agentif catalog import are outside this change. Subprocess stdio requires the Julia runtime; the existing static native server remains separate. There are no new dependencies or exports. Existing HTTP behavior and positional client constructors remain covered. MCPClient gains one optional field, changing its exact field layout.

Validation on macOS arm64:

  • Full Julia 1.10.12 / HTTP 1.11 / OAuth 2 suite: 1,048 assertions passed.
  • Full Julia 1.13.1 / HTTP 2.8 / OAuth 4 suite: 1,053 assertions passed, including seven strict native compilation/execution checks with zero verifier errors or warnings.
  • Both full suites pass all 446 stdio checks and the 125 argument-serialization checks merged in Keep tool argument headers and bodies in sync #15. The new nested-request regression failed before the correction and passes afterward.
  • Lifecycle controls cover blocked notifications, active-handler overflow, EOF/malformed output during nested calls, simultaneous handler closes, notification/handler close, retained callbacks, cleanup retry, exact IDs, cancellation, and blocked pipes.
  • An independent review found no actionable issues. Its separate three-level nested-request and blocked-notification check passed all nine assertions, including shutdown and recovery.
  • Strict documentation, doctests, and the runnable local-child example pass. Local documentation deployment was disabled.

AI-driven research and implementation with Codex, followed by independent review.

Co-authored by Codex

quinnj added 2 commits October 2, 2026 00:05
Keep notifications ordered while owning legacy request-handler tasks separately. Let callback-initiated close finish process and IO shutdown without waiting on other callbacks, while external close retains and joins unfinished handlers under one deadline.
@quinnj
quinnj force-pushed the feat/stdio-client branch from 8760a1c to 2b23657 Compare October 2, 2026 06:26
@quinnj
quinnj merged commit 7e7dfa5 into main Oct 2, 2026
11 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant