Skip to content

Pyjo.MCP.Client: the transport stdio, of a server in a child process - #55

Merged
dex4er merged 1 commit into
mainfrom
client-stdio
Nov 12, 2026
Merged

dex4er merged 1 commit into
mainfrom
client-stdio

Conversation

@dex4er

@dex4er dex4er commented Nov 12, 2026

Copy link
Copy Markdown
Collaborator

Pyjo.MCP.Client gets the transport stdio: a client with a command runs its server in a child process and talks to it over its standard input and output. The methods are the same as over Streamable HTTP.

with Pyjo.MCP.Client.new(command=['uv', 'run', 'app.py', 'stdio'], cwd='/srv/app', env={'DEBUG': '1'}) as client:
    client.list_tools()
    client.call_tool('add', {'a': 1, 'b': 2})

Closes #53

The transport stdio

  • Messages. Pyjo.IOLoop.ChildProcess runs the server at the first request. Pyjo.IOLoop.Messages frames one message on each line. The client writes the requests that it built, with its own ids, so it does not use the client of Pyjo.JSON.RPC.
  • Routing. A response goes to its request by its id. A message of a subscription goes to the function of listen by its subscriptionId. Any other notification, such as progress or a log message, is the event notification.
  • Input. The server sends no requests, as the specification forbids them on stdout, so a multi round-trip request works as over HTTP, through its input_required results.
  • Standard error. It is the new event stderr, or the standard error of the process when nothing subscribes to the event.
  • A server that exits. The requests in progress fail with the command and the exit code or signal. The next request runs the server again, as the specification asks of a client to restart a server that exits unexpectedly. This differs from the issue, which left the restart to the application.
  • close(), close_p(), with and async with. They close the standard input, wait shutdown_timeout (5 s), send SIGTERM, and send SIGKILL after another timeout. A client of HTTP closes its user agent, unless the user agent was given to it.
  • Blocking methods. Over stdio they wait with the event loop, because the child process belongs to the reactor of the singleton, so they fail in an event loop that runs already, where the methods _p work.

Cancellation

  • The promise of a method _p can be cancelled with Pyjo.Promise.cancel, which also happens when a coroutine that awaits it is cancelled. Over stdio it sends notifications/cancelled and drops a response that comes later. Over HTTP it closes the connection, with start_p of Pyjo.UserAgent.
  • listen over stdio sends notifications/cancelled when its function returns False.
  • The methods keep the cancellation in the promise they return, because a promise of then does not cancel the promise it follows.

Other changes

  • examples/mcp_cli.py takes -c/--command (or MCP_COMMAND) as well as a URL.
  • Docstrings, the tutorial (section "Standard input and output"), README, and the section "The Client" of AGENTS.md.

Validation

  • t/MCP_Client.py runs examples/calculator.py and the tutorial servers (progress.py, confirm.py, notes.py) over stdio. It covers:
    • the methods, blocking and _p, and requests at the same time
    • notifications, and the cancellation of a running tool
    • a multi round-trip request
    • listen closed by its function
    • stderr, cwd and env
    • a program that does not exist, and a server that exits before its response
    • a server that ignores the end of its stdin (SIGTERM) and one that ignores SIGTERM too (SIGKILL)
    • async with
    • the cancellation over HTTP
  • t/docs/MCP_Client.py, t/docs/guides_tutorial.py and t/examples/mcp_cli.py cover the new docstrings, the tutorial snippet and --command.
  • python -m Pyjo.Prove -l -r t passes all 21 files with PYTHONDEVMODE=1 and the PYTHONWARNINGS of CI, with no ResourceWarning. t/sdk passes too.
  • sphinx-build -W --keep-going builds and trunk check is clean.

🤖 Generated with Claude Code

A client with a command runs its server with Pyjo.IOLoop.ChildProcess at its
first request, and sends the messages to its standard input and reads them
from its standard output, one on each line, with Pyjo.IOLoop.Messages. The
methods are those of Streamable HTTP: a response goes to its request by its
id, a message of a subscription to the function of listen by its
subscriptionId, and another notification is the event notification. The
standard error of the server is the event stderr, or the standard error of
the process. A server that exits fails the requests in progress, and the next
request runs it again. close, close_p and a with block end it as the
specification asks: the end of its standard input, then SIGTERM and SIGKILL
after shutdown_timeout.

A promise of a method is cancellable with Pyjo.Promise.cancel: the transport
stdio sends notifications/cancelled, and Streamable HTTP closes the
connection. examples/mcp_cli.py takes a command with -c as well as a URL.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@dex4er dex4er added this to the 0.2.1 milestone Nov 12, 2026
@read-the-docs-community

Copy link
Copy Markdown

Documentation build overview

📚 Pyjo-MCP | 🛠️ Build #35848739 | 📁 Comparing d33031e against latest (6a135b8)

  🔍 Preview build  

3 files changed
± genindex.html
± api/Pyjo_MCP_Client.html
± guides/tutorial.html

@github-actions

Copy link
Copy Markdown
Contributor

Tests

Job Tests Passed ✅ Skipped ⚠️ Failed ❌ Log
prove (python 3.12) 248 247 1 0 ✅ 131434048931
prove (python 3.13) 248 247 1 0 ✅ 131434048959
prove (python 3.14) 248 247 1 0 ✅ 131434048876
prove (python 3.15) 248 247 1 0 ✅ 131434048937
prove (python 3.15t) 248 247 1 0 ✅ 131434049061
prove (python pypy3.12) 248 247 1 0 ✅ 131434049053
sdk (python 3.15) 12 12 0 0 ✅ 131434048630
All 1500 1494 6 0 ✅

The run of the workflow

@dex4er
dex4er merged commit 6c2a4ed into main Nov 12, 2026
13 checks passed
@dex4er
dex4er deleted the client-stdio branch November 12, 2026 19:31
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.

Pyjo.MCP.Client: the transport stdio, of a server in a child process

1 participant