From d33031e2769210ce3960892c4d7220162d7badc8 Mon Sep 17 00:00:00 2001 From: Piotr Roszatycki Date: Thu, 12 Nov 2026 20:26:03 +0100 Subject: [PATCH] Pyjo.MCP.Client: the transport stdio, of a server in a child process 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 --- AGENTS.md | 28 +++ Pyjo/MCP/Client.py | 427 +++++++++++++++++++++++++++++++++++--- README.md | 7 +- docs/guides/tutorial.rst | 13 ++ examples/mcp_cli.py | 18 +- t/MCP_Client.py | 157 ++++++++++++++ t/docs/MCP_Client.py | 78 ++++++- t/docs/guides_tutorial.py | 9 + t/examples/mcp_cli.py | 13 ++ 9 files changed, 719 insertions(+), 31 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index f2c2e7f..f433ffa 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -127,6 +127,34 @@ streams its response writes, is not parsed by `Pyjo.Content`: its events stay in the body, which the client parses at the end. Every other message of the stream is the event `notification`. +The transport stdio of the client is its `command`, which `Pyjo.IOLoop.ChildProcess` +runs at the first request, with `Pyjo.IOLoop.Messages` of lines on its +standard output and input, and not `Pyjo.JSON.RPC.serve`, whose client gives +a request an id of its own: the client writes the request that it built and +keeps its promise by its `id`. The specification forbids the requests of a +server on the standard output, as the input of a multi round-trip request is +a result, so a message of the server is a response, a message of a +subscription, by the `subscriptionId` of its `_meta`, which goes to the +function of `listen`, or the event `notification`. The server runs until it +exits, which fails the requests in progress, and the next request runs it +again, as the specification asks of a client to restart a server that exits; +its standard error is the event `stderr`, or the standard error of the +process without a subscriber, as the specification lets a server log there. +`close` ends it as the specification asks: the end of its standard input, +then `SIGTERM` and `SIGKILL` after `shutdown_timeout`. The blocking methods +wait for their promises with the event loop, as the child process belongs to +the reactor of the singleton, so they fail in an event loop that runs +already, unlike the ones of Streamable HTTP, whose user agent blocks with an +event loop of its own. + +A promise of a method of the client is cancellable with `cancel` of +`Pyjo.Promise`, as the one of a coroutine that awaits it: the connection of +Streamable HTTP closes, as `start_p` of `Pyjo.UserAgent` does, and the +transport stdio sends `notifications/cancelled`, as it cannot close a +connection of its own, and drops a response that comes after it. A promise of +`then` does not cancel the promise that it follows, so the methods keep the +cancellation of the request in the promise that they return. + ## The Tests `Pyjo.MCP.Test` is a subclass of `Pyjo.Test.Pyjo`, in the package of the diff --git a/Pyjo/MCP/Client.py b/Pyjo/MCP/Client.py index 373b883..50d83f0 100644 --- a/Pyjo/MCP/Client.py +++ b/Pyjo/MCP/Client.py @@ -19,6 +19,10 @@ # Non-blocking client.call_tool_p('add', {'a': 1, 'b': 2}).then(lambda result: print(result['structuredContent'])).wait() + # The transport stdio, of a server in a child process + with Pyjo.MCP.Client.new(command=['python', 'calculator.py', 'stdio']) as client: + print(client.call_tool('add', {'a': 1, 'b': 2})['structuredContent']) + :mod:`Pyjo.MCP.Client` is a client of the Model Context Protocol over Streamable HTTP, of the revision :data:`Pyjo.MCP.PROTOCOL_VERSION` of the specification, made with :mod:`Pyjo.UserAgent`. It sends what every request @@ -28,6 +32,13 @@ ``x-mcp-header`` of a tool, and reads the response in JSON or in a stream of events. +With a :attr:`~Pyjo_MCP_Client.command`, it speaks the transport stdio +instead: it runs the server in a child process of +:mod:`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 :mod:`Pyjo.IOLoop.Messages`. The methods are the same for both +transports. + It is a client to test a server with and to start from, not an agent: it caches nothing for the ``ttlMs`` of a result, and leaves the authorization to the application, which sends its headers with :attr:`~Pyjo_MCP_Client.headers`. @@ -44,6 +55,9 @@ import Pyjo.EventEmitter import Pyjo.Exception +import Pyjo.IOLoop +import Pyjo.IOLoop.ChildProcess +import Pyjo.IOLoop.Messages import Pyjo.JSON import Pyjo.JSON.RPC import Pyjo.Promise @@ -58,11 +72,14 @@ from . import Tool import builtins +import os import re +import signal +import sys import weakref -from collections.abc import Callable -from typing import Any, cast +from collections.abc import Callable, Mapping, Sequence +from typing import Any, Self, cast type Anything = builtins.object @@ -103,9 +120,24 @@ def notification(client, message): ... Emitted for every message of the stream of events of a response that is - not the response itself, as a notification of the progress of a tool. :: + not the response itself, as a notification of the progress of a tool, or, + over the transport stdio, for every notification of the server that is not + a message of a subscription of :meth:`listen`. :: client.on('notification', lambda client, message: print(message['method'])) + + ``stderr`` :: + + @client.on('stderr') + def stderr(client, chunk): + ... + + Emitted for the standard error of the server of the transport stdio, as + :class:`bytes`, which goes to the standard error of this process without + a subscriber. The specification lets a server log there, so it is not an + error of the server. :: + + client.on('stderr', lambda client, chunk: log.debug(chunk.decode(errors='replace'))) """ def __init__( @@ -114,17 +146,66 @@ def __init__( ua: Pyjo.UserAgent.object | None = None, name: str = 'Pyjo.MCP', version: str = '1.0.0', + *, + command: Sequence[str] | None = None, + cwd: str | os.PathLike[str] | None = None, + env: Mapping[str, str] | None = None, ) -> None: """:: client = Pyjo.MCP.Client.new() client = Pyjo.MCP.Client.new('http://127.0.0.1:3000/mcp', name='calculator-client', version='2.0.0') client = Pyjo.MCP.Client.new('/mcp', ua=t.ua) + client = Pyjo.MCP.Client.new(command=['uv', 'run', 'app.py', 'stdio'], cwd='/srv/app', env={'DEBUG': '1'}) - Construct a new :mod:`Pyjo.MCP.Client` object. + Construct a new :mod:`Pyjo.MCP.Client` object, of Streamable HTTP, or + of the transport stdio with a ``command``. """ super().__init__() + self.command: list[str] | None = list(command) if command is not None else None + """:: + + command = client.command + client.command = ['uv', 'run', 'app.py', 'stdio'] + + The program and the arguments of the server of the transport stdio, + which the client runs in a child process at its first request, and + again at the first request after the process has exited, or ``None`` + for Streamable HTTP of :attr:`url`, the default. + """ + + self.cwd = cwd + """:: + + cwd = client.cwd + client.cwd = '/srv/app' + + The working directory of the server of :attr:`command`, the one of this + process by default. + """ + + self.env: dict[str, str] = dict(env or {}) + """:: + + env = client.env + client.env = {'DEBUG': '1'} + + The variables of the environment of the server of :attr:`command`, + over the ones of this process, an empty :class:`dict` by default. + """ + + self.shutdown_timeout: float = 5 + """:: + + timeout = client.shutdown_timeout + client.shutdown_timeout = 1 + + How long :meth:`close` waits for the server of :attr:`command` to exit + after the end of its standard input, and then after ``SIGTERM``, + before ``SIGKILL``, in seconds, ``5`` by default. + """ + self.capabilities: dict[str, Any] = {} """:: @@ -198,11 +279,44 @@ def __init__( self._id = 0 self._ua = ua + self._own_ua = False # The response of a stream of events, which the parser of the content takes from the body self._responses: weakref.WeakKeyDictionary[Pyjo.Transaction.HTTP.object, dict[str, Any]] = ( weakref.WeakKeyDictionary() ) + # The server of the transport stdio, the requests that wait for their responses, and the subscriptions + self._process: Pyjo.IOLoop.ChildProcess.object | None = None + self._messages: Pyjo.IOLoop.Messages.object | None = None + self._pending: dict[Any, Pyjo.Promise.object] = {} + self._requests: dict[Any, dict[str, Any]] = {} + self._listeners: dict[Any, Callable[[dict[str, Any]], Any]] = {} + + def __enter__(self) -> Self: + return self + + def __exit__(self, *args: Any) -> None: + self.close() + + async def __aenter__(self) -> Self: + return self + + async def __aexit__(self, *args: Any) -> None: + await self.close_p() + + @property + def process(self) -> Pyjo.IOLoop.ChildProcess.object | None: + """:: + + process = client.process + + The :mod:`Pyjo.IOLoop.ChildProcess` of the server of :attr:`command` + while it runs, or ``None``. :: + + print(client.process.pid) + """ + return self._process + @property def ua(self) -> Pyjo.UserAgent.object: """:: @@ -214,11 +328,13 @@ def ua(self) -> Pyjo.UserAgent.object: """ if self._ua is None: self._ua = Pyjo.UserAgent.new() + self._own_ua = True return self._ua @ua.setter def ua(self, value: Pyjo.UserAgent.object) -> None: self._ua = value + self._own_ua = False def build_notification(self, method: str, params: dict[str, Any] | None = None) -> dict[str, Any]: """:: @@ -329,7 +445,63 @@ def call_tool_p( Same as :meth:`call_tool`, but returns a :mod:`Pyjo.Promise` of the result instead of blocking. """ - return self.send_request_p(self._call_tool(name, arguments, input_responses, request_state)).then(_result) + return _then(self.send_request_p(self._call_tool(name, arguments, input_responses, request_state)), _result) + + def close(self) -> None: + """:: + + client.close() + + End the server of :attr:`command`, as the specification asks of a + client of the transport stdio: close its standard input, wait + :attr:`shutdown_timeout` seconds for it to exit, then send ``SIGTERM``, + and ``SIGKILL`` after as long again, and block until it has exited. + The requests in progress fail. A client of Streamable HTTP closes the + connections of its :attr:`ua`, unless the user agent was given to it. + A ``with`` block closes the client at its end. :: + + with Pyjo.MCP.Client.new(command=['python', 'calculator.py', 'stdio']) as client: + print(client.list_tools()['tools']) + """ + if self._process is None: + self.close_p() + return + _wait(self.close_p()) + + def close_p(self) -> Pyjo.Promise.object: + """:: + + promise = client.close_p() + + Same as :meth:`close`, but returns a :mod:`Pyjo.Promise` that is + fulfilled once the server has exited, instead of blocking. An + ``async with`` block closes the client with it. :: + + async with Pyjo.MCP.Client.new(command=['python', 'calculator.py', 'stdio']) as client: + print((await client.list_tools_p())['tools']) + """ + if self._own_ua and self._ua is not None: + self._ua.close() + if (process := self._process) is None or (messages := self._messages) is None: + return Pyjo.Promise.resolve() + loop = Pyjo.IOLoop.singleton + timers: list[str] = [] + + def kill(loop: Any) -> None: + process.kill(signal.SIGKILL) + + def terminate(loop: Any) -> None: + process.kill(signal.SIGTERM) + timers.append(loop.timer(self.shutdown_timeout, kill)) + + def closed(*args: Any) -> None: + for timer in timers: + loop.remove(timer) + + promise = process.once_p('close').then(closed) + timers.append(loop.timer(self.shutdown_timeout, terminate)) + messages.close_gracefully() + return promise def complete( self, ref: dict[str, Any], argument: str, value: str, arguments: dict[str, str] | None = None @@ -358,7 +530,7 @@ def complete_p( Same as :meth:`complete`, but returns a :mod:`Pyjo.Promise` of the result instead of blocking. """ - return self.send_request_p(self._complete(ref, argument, value, arguments)).then(_result) + return _then(self.send_request_p(self._complete(ref, argument, value, arguments)), _result) def discover(self) -> dict[str, Any]: """:: @@ -378,7 +550,7 @@ def discover_p(self) -> Pyjo.Promise.object: Same as :meth:`discover`, but returns a :mod:`Pyjo.Promise` of the result instead of blocking. """ - return self.send_request_p(self.build_request('server/discover')).then(_result) + return _then(self.send_request_p(self.build_request('server/discover')), _result) def get_prompt( self, @@ -421,7 +593,7 @@ def get_prompt_p( Same as :meth:`get_prompt`, but returns a :mod:`Pyjo.Promise` of the result instead of blocking. """ - return self.send_request_p(self._get_prompt(name, arguments, input_responses, request_state)).then(_result) + return _then(self.send_request_p(self._get_prompt(name, arguments, input_responses, request_state)), _result) def list_prompts(self) -> dict[str, Any]: """:: @@ -443,7 +615,7 @@ def list_prompts_p(self) -> Pyjo.Promise.object: Same as :meth:`list_prompts`, but returns a :mod:`Pyjo.Promise` of the result instead of blocking. """ - return self.send_request_p(self.build_request('prompts/list')).then(_result) + return _then(self.send_request_p(self.build_request('prompts/list')), _result) def list_resources(self) -> dict[str, Any]: """:: @@ -465,7 +637,7 @@ def list_resources_p(self) -> Pyjo.Promise.object: Same as :meth:`list_resources`, but returns a :mod:`Pyjo.Promise` of the result instead of blocking. """ - return self.send_request_p(self.build_request('resources/list')).then(_result) + return _then(self.send_request_p(self.build_request('resources/list')), _result) def list_resource_templates(self) -> dict[str, Any]: """:: @@ -488,7 +660,7 @@ def list_resource_templates_p(self) -> Pyjo.Promise.object: Same as :meth:`list_resource_templates`, but returns a :mod:`Pyjo.Promise` of the result instead of blocking. """ - return self.send_request_p(self.build_request('resources/templates/list')).then(_result) + return _then(self.send_request_p(self.build_request('resources/templates/list')), _result) def list_tools(self) -> dict[str, Any]: """:: @@ -514,7 +686,7 @@ def list_tools_p(self) -> Pyjo.Promise.object: Same as :meth:`list_tools`, but returns a :mod:`Pyjo.Promise` of the result instead of blocking. """ - return self.send_request_p(self.build_request('tools/list')).then(_result) + return _then(self.send_request_p(self.build_request('tools/list')), _result) def listen(self, notifications: dict[str, Any], cb: Callable[[dict[str, Any]], Any]) -> dict[str, Any] | None: """:: @@ -544,7 +716,13 @@ def updated(message): updated.count = 0 client.listen({'resourceSubscriptions': ['file:///project/README.md']}, updated) print(client.read_resource('file:///project/README.md')['contents'][0]['text']) + + Over the transport stdio, the messages of the subscription are those of + the ``subscriptionId`` of its request, and the function closes it with + ``notifications/cancelled``. """ + if self.command is not None: + return _wait(self.listen_p(notifications, cb)) tx, finished = self._listen(notifications, cb) return finished(self.ua.start(tx)) @@ -556,6 +734,8 @@ def listen_p(self, notifications: dict[str, Any], cb: Callable[[dict[str, Any]], Same as :meth:`listen`, but returns a :mod:`Pyjo.Promise` of the result instead of blocking. """ + if self.command is not None: + return self._listen_stdio_p(notifications, cb) tx, finished = self._listen(notifications, cb) def failed(e: Any) -> Any: @@ -591,7 +771,7 @@ def read_resource_p( Same as :meth:`read_resource`, but returns a :mod:`Pyjo.Promise` of the result instead of blocking. """ - return self.send_request_p(self._read_resource(uri, input_responses, request_state)).then(_result) + return _then(self.send_request_p(self._read_resource(uri, input_responses, request_state)), _result) def read_response(self, tx: Pyjo.Transaction.HTTP.object, request: dict[str, Any]) -> dict[str, Any] | None: """:: @@ -608,10 +788,7 @@ def read_response(self, tx: Pyjo.Transaction.HTTP.object, request: dict[str, Any tx = client.ua.start(client.build_tx(request)) print(client.read_response(tx, request)['result']['tools']) """ - response = self._read_response(tx, request) - if request.get('method') == 'tools/list' and isinstance(result := _object(response).get('result'), dict): - response = {**_object(response), 'result': self._tools(cast(dict[str, Any], result))} - return response + return self._response(request, self._read_response(tx, request)) def send_request(self, request: dict[str, Any]) -> dict[str, Any] | None: """:: @@ -619,14 +796,22 @@ def send_request(self, request: dict[str, Any]) -> dict[str, Any] | None: response = client.send_request(request) Send a request or a notification and return the response, or ``None`` - for one that the server accepted without a response, ``202 - Accepted``. A response of HTTP without one of JSON-RPC fails with a - :mod:`Pyjo.Exception`, with the text of an error in plain text, as a - server of an older revision tells the revisions that it supports. :: + for a notification, which the server accepts without a response, ``202 + Accepted`` over Streamable HTTP. A response of HTTP without one of + JSON-RPC fails with a :mod:`Pyjo.Exception`, with the text of an error + in plain text, as a server of an older revision tells the revisions + that it supports, and so does a server of :attr:`command` that cannot + run or exits before the response. :: response = client.send_request(client.build_request('tools/list')) print(response['result']['tools']) + + Over the transport stdio, the blocking methods wait for their responses + with the event loop, so they cannot be called in an event loop that + runs already, where the methods with a promise can. """ + if self.command is not None: + return _wait(self.send_request_p(request)) response = self.read_response(self.ua.start(self.build_tx(request)), request) if self._renegotiate(request, response): response = self.read_response(self.ua.start(self.build_tx(request)), request) @@ -638,19 +823,32 @@ def send_request_p(self, request: dict[str, Any]) -> Pyjo.Promise.object: promise = client.send_request_p(request) Same as :meth:`send_request`, but returns a :mod:`Pyjo.Promise` of the - response instead of blocking. + response instead of blocking. The promise of this method, and the ones + of the other methods with ``_p`` but :meth:`listen_p`, abandon the + request when they are cancelled with + :meth:`~Pyjo.Promise.Pyjo_Promise.cancel`, as when the coroutine that + awaits them is cancelled: the connection of Streamable HTTP closes, and + the transport stdio sends ``notifications/cancelled``, as the + specification has it, and drops a response that comes after it. The + promise is rejected with ``Request cancelled``. :: + + promise = client.call_tool_p('count', {'to': 100}) + Pyjo.IOLoop.timer(1, lambda loop: promise.cancel()) """ - - def response(tx: Pyjo.Transaction.HTTP.object) -> dict[str, Any] | None: - return self.read_response(tx, request) + current: list[Pyjo.Promise.object] = [] def start() -> Pyjo.Promise.object: - return self.ua.start_p(self.build_tx(request)).then(response) + current[:] = [self._send_p(request)] + return current[0] def renegotiate(response: Any = None) -> Any: return start() if self._renegotiate(request, response) else response - return start().then(renegotiate) + def cancel() -> None: + for promise in current: + promise.cancel() + + return _cancellable(start().then(renegotiate), cancel) def _call_tool( self, name: str, arguments: dict[str, Any] | None, responses: dict[str, Any] | None, state: str | None @@ -758,6 +956,141 @@ def _read_response(self, tx: Pyjo.Transaction.HTTP.object, request: dict[str, An message += f': {body}' raise Pyjo.Exception.new(message) + def _listen_stdio_p( + self, notifications: dict[str, Any], cb: Callable[[dict[str, Any]], Any] + ) -> Pyjo.Promise.object: + # A subscription of the transport stdio, whose messages are those of its subscriptionId, and which the function + # closes with notifications/cancelled, without a response + request = self.build_request('subscriptions/listen', {'notifications': notifications}) + id = request['id'] + closed = False + + def message(message: dict[str, Any]) -> None: + nonlocal closed + if not closed and cb(message) is False: + closed = True + promise.cancel() + + def done(response: Any = None) -> dict[str, Any]: + self._listeners.pop(id, None) + return _result(response) + + def failed(e: Any = None) -> Any: + self._listeners.pop(id, None) + return None if closed else Pyjo.Promise.reject(e) + + self._listeners[id] = message + promise = self._send_p(request) + return promise.then(done, failed) + + def _receive(self, data: bytes) -> None: + # A message of the server of the transport stdio: the response of a request, a message of a subscription, or + # another notification + try: + message = Pyjo.JSON.decode_json(data) + except ValueError: + return + if not isinstance(message, dict): + return + message = cast(dict[str, Any], message) + if 'method' not in message: + if (promise := self._pending.pop(message.get('id'), None)) is not None: + promise.resolve(self._response(self._requests.pop(message.get('id'), {}), message)) + return + meta = _object(_object(message.get('params')).get('_meta')) + if (listener := self._listeners.get(meta.get(MCP.META_SUBSCRIPTION_ID))) is not None: + listener(message) + return + self.emit('notification', message) + + def _response(self, request: dict[str, Any], response: Any) -> Any: + # The response with the tools of a result of tools/list kept, without the ones of the event invalid_tool + if request.get('method') == 'tools/list' and isinstance(result := _object(response).get('result'), dict): + response = {**_object(response), 'result': self._tools(cast(dict[str, Any], result))} + return response + + def _send_p(self, request: dict[str, Any]) -> Pyjo.Promise.object: + # One request of the transport, whose promise abandons it when it is cancelled + if self.command is None: + started = self.ua.start_p(self.build_tx(request)) + + def response(tx: Pyjo.Transaction.HTTP.object) -> dict[str, Any] | None: + return self.read_response(tx, request) + + return _cancellable(started.then(response), started.cancel) + + messages = self._spawn() + if (id := request.get('id')) is None: + if messages is not None: + messages.send(Pyjo.JSON.encode_json(request)) + return Pyjo.Promise.resolve(None) + + def cancel() -> None: + if self._pending.pop(id, None) is None: + return + self._requests.pop(id, None) + self._listeners.pop(id, None) + if messages is not None and self._messages is messages: + notification = self.build_notification('notifications/cancelled', {'requestId': id}) + messages.send(Pyjo.JSON.encode_json(notification)) + promise.reject(Pyjo.Exception.new('Request cancelled')) + + promise = Pyjo.Promise.new(cancel=cancel) + self._pending[id] = promise + self._requests[id] = request + if messages is not None: + messages.send(Pyjo.JSON.encode_json(request)) + return promise + + def _spawn(self) -> Pyjo.IOLoop.Messages.object | None: + # The server of the transport stdio, which runs from the first request until it exits, or None for a program + # that cannot run, whose event error fails the requests + if self._process is not None: + return self._messages + command = self.command or [] + name = ' '.join(command) + process = Pyjo.IOLoop.ChildProcess.new() + ref = weakref.ref(self) + + # The requests in progress fail once the server is gone, and the next request runs it again + def ended(message: str) -> None: + if (client := ref()) is None or client._process is not process: + return + client._process = client._messages = None + pending, client._pending, client._requests, client._listeners = client._pending, {}, {}, {} + for promise in pending.values(): + promise.reject(Pyjo.Exception.new(f'{name}: {message}')) + + def error(process: Any, e: BaseException) -> None: + ended(str(e)) + + def close(process: Any, code: int | None, signal_: int | None) -> None: + ended(f'Exited with signal {signal_}' if signal_ is not None else f'Exited with code {code}') + + def stderr(stream: Any, chunk: bytes) -> None: + if (client := ref()) is not None and client.has_subscribers('stderr'): + client.emit('stderr', chunk) + elif (buffer := getattr(sys.stderr, 'buffer', None)) is not None: + buffer.write(chunk) + buffer.flush() + else: + sys.stderr.write(chunk.decode(errors='replace')) + + def receive(messages: Any, data: bytes) -> None: + if (client := ref()) is not None: + client._receive(data) + + process.on('error', error) + process.on('close', close) + process.spawn(command, cwd=self.cwd, env={**os.environ, **self.env} if self.env else None) + self._process = process + if process.stdout is None or process.stdin is None or process.stderr is None: + return None + process.stderr.on('read', stderr) + self._messages = messages = Pyjo.IOLoop.Messages.new(process.stdout, output=process.stdin) + messages.on('message', receive) + return messages + def _tools(self, result: dict[str, Any]) -> dict[str, Any]: # The tools whose x-mcp-header the specification allows, as a client excludes the others def nothing(**arguments: Any) -> None: @@ -782,6 +1115,21 @@ def nothing(**arguments: Any) -> None: return {**result, 'tools': definitions} +def _cancellable(promise: Pyjo.Promise.object, cancel: Callable[[], Any]) -> Pyjo.Promise.object: + # A promise of the value of another one, which cancels what the other one waits for, as a promise of then does not + cancellable = Pyjo.Promise.new(cancel=cancel) + + # Without returning the promise that they settle, which the promise of then would follow and leave unhandled + def resolve(*values: Any) -> None: + cancellable.resolve(*values) + + def reject(*reasons: Any) -> None: + cancellable.reject(*reasons) + + promise.then(resolve, reject) + return cancellable + + def _encode(value: Any) -> str: # A value of a header, plain ASCII, or Base64 of UTF-8 with the sentinel of MCP text = value if isinstance(value, str) else Pyjo.JSON.to_json(value) @@ -826,6 +1174,11 @@ def _result(response: Any) -> dict[str, Any]: return _object(response_.get('result')) +def _then(promise: Pyjo.Promise.object, cb: Callable[[Any], Any]) -> Pyjo.Promise.object: + # The then of a promise that stays cancellable + return _cancellable(promise.then(cb), promise.cancel) + + def _value(arguments: Any, path: list[str]) -> Any: # The value of an argument at the path of its properties for key in path: @@ -835,6 +1188,26 @@ def _value(arguments: Any, path: list[str]) -> Any: return arguments +def _wait(promise: Pyjo.Promise.object) -> Any: + # The value of a promise for a blocking method, which waits for it with the event loop, or raises its error + if promise.ioloop.is_running: + raise Pyjo.Exception.new('A blocking method cannot run in an event loop that runs already, use the one with _p') + results: list[Any] = [] + errors: list[Any] = [] + + def done(value: Any = None) -> None: + results.append(value) + + def failed(e: Any = None) -> None: + errors.append(e) + + promise.then(done, failed).wait() + if errors: + e = errors[0] + raise e if isinstance(e, BaseException) else Pyjo.Exception.new(str(e)) + return results[0] if results else None + + new = Pyjo_MCP_Client.new object = Pyjo_MCP_Client Client = Pyjo_MCP_Client diff --git a/README.md b/README.md index 5497aeb..22aac1e 100644 --- a/README.md +++ b/README.md @@ -125,16 +125,21 @@ the lists of objects, or JSON: uv run python examples/mcp_cli.py --help uv run python examples/mcp_cli.py forecast --place Kraków --language pl --days 2 uv run python examples/mcp_cli.py hourly-forecast -p Warsaw -H 6 -f json +uv run python examples/mcp_cli.py -c 'uv run python examples/calculator.py stdio' add -a 1 -b 2 ``` It is made with `Pyjo.MCP.Client`, a client of MCP over Streamable HTTP, which -sends the `_meta` and the headers that every request carries: +sends the `_meta` and the headers that every request carries, or over the +transport stdio, of a server that it starts itself: ```python from Pyjo.MCP.Client import Client client = Client('http://127.0.0.1:3000/mcp') print(client.call_tool('divide', {'a': 7, 'b': 2})['structuredContent']) + +with Client(command=['uv', 'run', 'python', 'examples/calculator.py', 'stdio']) as client: + print(client.call_tool('divide', {'a': 7, 'b': 2})['structuredContent']) ``` `Pyjo.MCP.Test` tests a server with the requests of the client, without diff --git a/docs/guides/tutorial.rst b/docs/guides/tutorial.rst index 4f32a86..9ed95b4 100644 --- a/docs/guides/tutorial.rst +++ b/docs/guides/tutorial.rst @@ -302,6 +302,19 @@ in progress have their responses. Claude Code starts it with the command: $ claude mcp add hello -- uv run python stdio.py stdio +:mod:`Pyjo.MCP.Client` starts such a server too, with its ``command``, and +ends it when it closes, as at the end of a ``with`` block, with the same +methods as over Streamable HTTP. Its standard error, the log of the +application, goes to the standard error of the client, or to the event +``stderr`` of the client: + +.. code-block:: python + + import Pyjo.MCP.Client + + with Pyjo.MCP.Client.new(command=['uv', 'run', 'python', 'stdio.py', 'stdio']) as client: + print(client.call_tool('greet', {'name': 'Pyjo'})['content'][0]['text']) + Testing ------- diff --git a/examples/mcp_cli.py b/examples/mcp_cli.py index 4dd5956..ce73706 100644 --- a/examples/mcp_cli.py +++ b/examples/mcp_cli.py @@ -8,6 +8,7 @@ python mcp_cli.py hourly-forecast -p Warsaw -H 6 -f json python calculator.py daemon -l http://*:3001 # starts another one at port 3001 python mcp_cli.py -u http://127.0.0.1:3001/mcp add -a 1 -b 2 + python mcp_cli.py -c 'python calculator.py stdio' add -a 1 -b 2 A command line client of the tools of a server of MCP: a tool is a command, its name in kebab-case, and its arguments are the options of the command, with the @@ -18,7 +19,13 @@ The commands are the tools of the server, so another server has other ones, which python mcp_cli.py lists. +The client starts a server of the transport stdio itself with a command, as a +host of MCP does, and ends it when the command of the tool is done. + Options: + -c, --command Command of a server of the transport stdio, in the + syntax of the shell, defaults to the value of + MCP_COMMAND, in the place of the URL -f, --format Format of the result, "text" or "json", defaults to "text" -h, --help Show this summary of available options and commands @@ -39,6 +46,7 @@ import json import os import re +import shlex import sys @@ -159,8 +167,9 @@ def main(args=None): # The options before the command, as an option of a tool may have the name of one of them i = 0 while i < len(args) and args[i].startswith('-') and args[i] != '--': - i += 2 if args[i] in ('-u', '--url', '-f', '--format') else 1 + i += 2 if args[i] in ('-c', '--command', '-u', '--url', '-f', '--format') else 1 getopt = Pyjo.GetOpt.new() + getopt.option('c|command=s', default=os.environ.get('MCP_COMMAND') or None) getopt.option('f|format=s', default='text', choices=FORMATS) getopt.option('h|help') getopt.option('u|url=s', default=os.environ.get('MCP_URL') or 'http://127.0.0.1:3000/mcp') @@ -168,7 +177,10 @@ def main(args=None): if not (opts := getopt.parse(head)) or head: return 2 command, rest = (args[i], args[i + 1 :]) if i < len(args) else (None, []) - client = Pyjo.MCP.Client.new(opts.url, ua=ua, name='mcp_cli') + if opts.command: + client = Pyjo.MCP.Client.new(command=shlex.split(opts.command), name='mcp_cli') + else: + client = Pyjo.MCP.Client.new(opts.url, ua=ua, name='mcp_cli') client.on( 'invalid_tool', lambda client, definition, e: print(f'Tool {definition.get("name")} left out: {e.message}', file=sys.stderr), @@ -232,6 +244,8 @@ def main(args=None): except Pyjo.Exception.object as e: print(e.message.rstrip(), file=sys.stderr) return 1 + finally: + client.close() # The result, or the error of the tool if result.get('isError'): diff --git a/t/MCP_Client.py b/t/MCP_Client.py index ad0a7b2..e718660 100644 --- a/t/MCP_Client.py +++ b/t/MCP_Client.py @@ -10,13 +10,29 @@ import Pyjo.UserAgent import Pyjoyment +from Pyjo.File import curfile from Pyjo.Test import * import base64 +import os +import re +import signal +import sys +import time # The client of MCP over Streamable HTTP, against the server of the distribution, which checks the headers of MCP +ROOT = curfile().dirname().dirname() +CALCULATOR = ROOT.child('examples', 'calculator.py').to_str() +TUTORIAL = ROOT.child('docs', 'guides', 'tutorial') + +# Servers of the transport stdio that print their directory and environment, ignore the end of their standard input, +# and ignore SIGTERM too +PRINTING = 'import os, sys; sys.stderr.write(os.getcwd() + " " + os.environ["EXAMPLE"]); sys.stdin.read()' +STUBBORN = 'import sys, time; sys.stdin.read(); time.sleep(60)' +DEAF = 'import signal, sys, time; signal.signal(signal.SIGTERM, signal.SIG_IGN); sys.stdin.read(); time.sleep(60)' + server = Pyjo.MCP.Server.new(name='ExampleServer', version='1.0.0', instructions='Utilities.') @@ -603,4 +619,145 @@ def action(c): c.discover_p().catch(errors.append).wait() is_ok(errors[1].message, '/mcp: 404 Not Found', 'error of HTTP') +with subtest('Cancellation'): + # A promise of a method that is cancelled closes the connection of its request + waiting = Pyjo.MCP.Server.new(name='ExampleServer') + abandoned = [] + + @waiting.tool(context=True) + def wait(context) -> str: + context.on('cancelled', lambda context: abandoned.append(True)) + return Pyjo.Promise.timer(5, 'Too late') + + c = client(application(waiting.to_action())) + errors = [] + promise = c.call_tool_p('wait') + Pyjo.IOLoop.timer(0.05, lambda loop: promise.cancel()) + promise.catch(errors.append).wait() + is_ok(str(errors[0]).strip(), 'Request cancelled', 'rejected') + Pyjo.Promise.timer(0.05).wait() + is_deeply_ok(abandoned, [True], 'request abandoned') + +with subtest('Transport stdio'): + # The servers of the examples and of the tutorial in a child process, as a host of MCP runs them + c = Pyjo.MCP.Client.new(command=[sys.executable, CALCULATOR, 'stdio'], name='ExampleClient') + is_ok(c.process, None, 'no process before the first request') + is_ok(c.discover()['capabilities'], {'tools': {}}, 'discover') + ok(c.process.pid, 'process') + is_deeply_ok([tool['name'] for tool in c.list_tools()['tools']], ['add', 'subtract', 'multiply', 'divide'], 'tools') + is_deeply_ok(list(c.tools), ['add', 'subtract', 'multiply', 'divide'], 'tools of the client') + is_ok(c.call_tool('add', {'a': 1, 'b': 2})['structuredContent'], 3, 'call') + is_ok(c.call_tool('divide', {'a': 1, 'b': 0})['isError'], True, 'error of a tool') + is_deeply_ok(error(failure(lambda: c.call_tool('power'))), (-32602, 'Unknown tool: power'), 'error of JSON-RPC') + is_ok(c.send_request(c.build_notification('notifications/initialized')), None, 'notification') + results = [] + Pyjo.Promise.all(c.call_tool_p('add', {'a': 1, 'b': 1}), c.call_tool_p('multiply', {'a': 2, 'b': 3})).then( + lambda *values: results.extend(value[0]['structuredContent'] for value in values) + ).wait() + is_deeply_ok(results, [2, 6], 'requests at the same time') + c.close() + is_ok(c.process, None, 'closed') + is_ok(c.call_tool('add', {'a': 2, 'b': 2})['structuredContent'], 4, 'run again') + c.close() + + # The notifications of a request, and its cancellation, which stops the coroutine of the tool + c = Pyjo.MCP.Client.new(command=[sys.executable, TUTORIAL.child('progress.py').to_str(), 'stdio']) + notifications = [] + c.on('notification', lambda c, message: notifications.append(message['method'])) + meta = {'progressToken': 'p1', 'io.modelcontextprotocol/logLevel': 'info'} + response = c.send_request(c.build_request('tools/call', {'name': 'count', 'arguments': {'to': 2}, '_meta': meta})) + is_ok(response['result']['structuredContent'], 2, 'result after the notifications') + is_deeply_ok( + notifications, + ['notifications/message', 'notifications/progress', 'notifications/progress'], + 'notifications', + ) + errors = [] + promise = c.call_tool_p('count', {'to': 100}) + Pyjo.IOLoop.timer(0.15, lambda loop: promise.cancel()) + promise.catch(errors.append).wait() + is_ok(errors[0].message, 'Request cancelled', 'cancelled') + is_ok(c.call_tool('count', {'to': 1})['structuredContent'], 1, 'next request') + c.close() + + # A multi round-trip request, whose rounds are results over stdio too + c = Pyjo.MCP.Client.new(command=[sys.executable, TUTORIAL.child('confirm.py').to_str(), 'stdio']) + c.capabilities = {'elicitation': {}} + result = c.call_tool('delete', {'name': 'notes.txt'}) + is_ok(result['resultType'], 'input_required', 'input required') + result = c.call_tool( + 'delete', + {'name': 'notes.txt'}, + input_responses={'confirm': {'action': 'accept'}}, + request_state=result.get('requestState'), + ) + is_ok(result['content'][0]['text'], 'Deleted notes.txt', 'input responses') + c.close() + + # A subscription, whose messages are those of its subscriptionId, and which the function closes + c = Pyjo.MCP.Client.new(command=[sys.executable, TUTORIAL.child('notes.py').to_str(), 'stdio']) + messages = [] + c.on('notification', lambda c, message: messages.append(('other', message['method']))) + + def listener(message): + messages.append(('listen', message['method'])) + if len(messages) == 1: + c.call_tool_p('add_note', {'text': 'Buy milk'}) + return len(messages) < 3 + + result = c.listen({'resourcesListChanged': True, 'resourceSubscriptions': ['notes://all']}, listener) + is_ok(result, None, 'closed by the function') + is_deeply_ok( + messages, + [ + ('listen', 'notifications/subscriptions/acknowledged'), + ('listen', 'notifications/resources/list_changed'), + ('listen', 'notifications/resources/updated'), + ], + 'messages of the subscription', + ) + is_ok(c.read_resource('notes://all')['contents'][0]['text'], '* Buy milk\n', 'next request') + c.close() + + # The standard error of the server, a program that cannot run, and a server that exits before its response + c = Pyjo.MCP.Client.new(command=[sys.executable, '-c', 'import sys; sys.stderr.write("Starting"); input()']) + chunks = [] + c.on('stderr', lambda c, chunk: chunks.append(chunk)) + is_ok(failure(lambda: c.list_tools()).message, f'{sys.executable} -c {c.command[2]}: Exited with code 0', 'exited') + is_ok(b''.join(chunks), b'Starting', 'standard error') + c = Pyjo.MCP.Client.new(command=['/nonexistent/server']) + like_ok(failure(lambda: c.list_tools()).message, re.compile(r'^/nonexistent/server: .*No such file'), 'no program') + c = Pyjo.MCP.Client.new(command=[sys.executable, '-c', 'import os; os.read(0, 1); os._exit(3)']) + like_ok(failure(lambda: c.list_tools()).message, re.compile(r': Exited with code 3$'), 'exit code') + + # The directory and the environment of the server + c = Pyjo.MCP.Client.new(command=[sys.executable, '-c', PRINTING], cwd=TUTORIAL.to_str(), env={'EXAMPLE': '1'}) + chunks = [] + c.on('stderr', lambda c, chunk: chunks.append(chunk)) + c.send_request(c.build_notification('notifications/initialized')) + c.close() + is_ok(b''.join(chunks).decode(), f'{os.path.realpath(TUTORIAL.to_str())} 1', 'cwd and env') + + # A server that ignores the end of its standard input gets SIGTERM, and one that ignores SIGTERM too gets SIGKILL + for code, signal_, timeouts in ((STUBBORN, signal.SIGTERM, 1), (DEAF, signal.SIGKILL, 2)): + c = Pyjo.MCP.Client.new(command=[sys.executable, '-c', code]) + c.shutdown_timeout = 0.2 + c.send_request(c.build_notification('notifications/initialized')) + process = c.process + started = time.monotonic() + c.close() + ok(time.monotonic() - started >= 0.2 * timeouts, f'{signal_.name} after {timeouts} timeouts') + is_ok(process.signal_code, signal_, f'{signal_.name}') + is_ok(c.process, None, 'ended') + + # In a coroutine, with an asynchronous block + async def main(): + async with Pyjo.MCP.Client.new(command=[sys.executable, CALCULATOR, 'stdio']) as client: + result = await client.call_tool_p('subtract', {'a': 3, 'b': 1}) + return result['structuredContent'], client.process + + results = [] + Pyjo.Promise.new(main()).then(results.append).wait() + is_deeply_ok(results, [(2, None)], 'async with') + done_testing() diff --git a/t/docs/MCP_Client.py b/t/docs/MCP_Client.py index 56d0a82..2338cb4 100644 --- a/t/docs/MCP_Client.py +++ b/t/docs/MCP_Client.py @@ -3,15 +3,21 @@ import Pyjo.MCP.Client import Pyjo.MCP.Server import Pyjo.MCP.Tool +import Pyjo.Promise import Pyjo.SSE import Pyjo.Test.Pyjo import Pyjo.UserAgent import Pyjoyment +from Pyjo.File import curfile from Pyjo.Test import * import contextlib import io +import sys + + +CALCULATOR = curfile().dirname().dirname().sibling('examples', 'calculator.py').to_str() # The server of the examples, the calculator of the synopsis of Pyjo.MCP.Server with greet and divide, prompts and a @@ -94,7 +100,11 @@ def local(client, application=app): # Non-blocking client.call_tool_p('add', {'a': 1, 'b': 2}).then(lambda result: print(result['structuredContent'])).wait() - is_ok(stdout.getvalue(), '3\n3\n', 'printed') + + # The transport stdio, of a server in a child process + with Pyjo.MCP.Client.new(command=[sys.executable, CALCULATOR, 'stdio']) as client: + print(client.call_tool('add', {'a': 1, 'b': 2})['structuredContent']) + is_ok(stdout.getvalue(), '3\n3\n3\n', 'printed') with subtest('invalid_tool'): definitions = [{'name': 'bad', 'inputSchema': {'properties': {'n': {'type': 'number', 'x-mcp-header': 'N'}}}}] @@ -147,6 +157,21 @@ def notification(client, message): is_deeply_ok(got, [{'jsonrpc': '2.0', 'method': 'notifications/progress', 'params': {'progress': 1}}], 'message') is_ok(stdout.getvalue(), 'notifications/progress\n', 'printed') +with subtest('stderr'): + client = Pyjo.MCP.Client.new(command=[sys.executable, '-c', 'import sys; sys.stderr.write("Starting"); input()']) + got = [] + + @client.on('stderr') + def stderr(client, chunk): + got.append(chunk) + + client.on('stderr', lambda client, chunk: print(chunk.decode(errors='replace'))) + with contextlib.redirect_stdout(io.StringIO()) as stdout: + client.send_request(client.build_notification('notifications/initialized')) + client.close() + is_deeply_ok(got, [b'Starting'], 'chunk') + is_ok(stdout.getvalue(), 'Starting\n', 'printed') + with subtest('new'): client = Pyjo.MCP.Client.new() is_ok(client.url, 'http://localhost:3000/mcp', 'url') @@ -156,6 +181,12 @@ def notification(client, message): client = Pyjo.MCP.Client.new('/mcp', ua=t.ua) is_ok(client.discover()['supportedVersions'], ['2026-07-28'], 'user agent of the test') t.ua.close() + client = Pyjo.MCP.Client.new(command=['uv', 'run', 'app.py', 'stdio'], cwd='/srv/app', env={'DEBUG': '1'}) + is_deeply_ok( + (client.command, client.cwd, client.env), + (['uv', 'run', 'app.py', 'stdio'], '/srv/app', {'DEBUG': '1'}), + 'transport stdio', + ) with subtest('Attributes'): client = local(Pyjo.MCP.Client.new()) @@ -182,6 +213,16 @@ def notification(client, message): ua = client.ua isa_ok(ua, Pyjo.UserAgent.object, 'ua') client.ua = Pyjo.UserAgent.new() + command = client.command + is_ok(command, None, 'command') + cwd = client.cwd + is_ok(cwd, None, 'cwd') + env = client.env + is_deeply_ok(env, {}, 'env') + timeout = client.shutdown_timeout + is_ok(timeout, 5, 'shutdown timeout') + process = client.process + is_ok(process, None, 'process') meta = client.build_request('tools/list')['params']['_meta'] is_deeply_ok( meta, @@ -260,6 +301,32 @@ def notification(client, message): promise.then(results.append).wait() is_ok(results[0]['content'][0]['text'], 'Hello, Pyjo!', 'result') +with subtest('close'): + with Pyjo.MCP.Client.new(command=[sys.executable, CALCULATOR, 'stdio']) as stdio: + is_deeply_ok([tool['name'] for tool in stdio.list_tools()['tools']][:1], ['add'], 'tools') + process = stdio.process + is_ok((stdio.process, process.exit_code), (None, 0), 'closed at the end of the block') + stdio = Pyjo.MCP.Client.new(command=[sys.executable, CALCULATOR, 'stdio']) + stdio.discover() + stdio.close() + is_ok(stdio.process, None, 'closed') + local(Pyjo.MCP.Client.new()).close() + +with subtest('close_p'): + stdio = Pyjo.MCP.Client.new(command=[sys.executable, CALCULATOR, 'stdio']) + stdio.discover() + promise = stdio.close_p() + promise.wait() + is_ok(stdio.process, None, 'closed') + + async def main(): + async with Pyjo.MCP.Client.new(command=[sys.executable, CALCULATOR, 'stdio']) as client: + return (await client.list_tools_p())['tools'][0]['name'] + + results = [] + Pyjo.Promise.new(main()).then(results.append).wait() + is_deeply_ok(results, ['add'], 'async with') + with subtest('complete'): # A server of its own, with completions completing = Pyjo.MCP.Server.new() @@ -475,4 +542,13 @@ def updated(message): promise.then(results.append).wait() is_ok(results[0]['result']['supportedVersions'], ['2026-07-28'], 'response') + stdio = Pyjo.MCP.Client.new(command=[sys.executable, CALCULATOR, 'stdio']) + stdio.discover() + promise = stdio.call_tool_p('add', {'a': 1, 'b': 2}) + promise.cancel() + errors = [] + promise.catch(errors.append).wait() + is_ok(errors[0].message, 'Request cancelled', 'cancelled') + stdio.close() + done_testing() diff --git a/t/docs/guides_tutorial.py b/t/docs/guides_tutorial.py index 494a4cb..039e745 100644 --- a/t/docs/guides_tutorial.py +++ b/t/docs/guides_tutorial.py @@ -1,5 +1,6 @@ import Pyjo.File import Pyjo.IOLoop +import Pyjo.MCP.Client import Pyjo.MCP.Test from Pyjo.Test import * @@ -314,6 +315,14 @@ def start(ua, tx): t = tutorial('stdio') t.call_ok('greet', name='Pyjo').status_is(200).text_content_is('Hello, Pyjo!') + # The client of the distribution, which starts the server itself + logged = [] + with Pyjo.MCP.Client.new(command=[sys.executable, EXAMPLES.child('stdio.py').to_str(), 'stdio']) as client: + client.env = {'PYJO_LOG_LEVEL': 'info'} + client.on('stderr', lambda client, chunk: logged.append(chunk)) + is_ok(client.call_tool('greet', {'name': 'Pyjo'})['content'][0]['text'], 'Hello, Pyjo!', 'client of stdio') + like_ok(b''.join(logged).decode(), re.compile(r'Greeting Pyjo'), 'log of the server') + with subtest('Testing'): result = subprocess.run( [sys.executable, EXAMPLES.child('hello_test.py').to_str()], diff --git a/t/examples/mcp_cli.py b/t/examples/mcp_cli.py index dc1f0cc..0e694b9 100644 --- a/t/examples/mcp_cli.py +++ b/t/examples/mcp_cli.py @@ -14,6 +14,8 @@ import io import json import re +import shlex +import sys # The client of the command line of examples/mcp_cli.py, whose user agent requests the applications of the test, without @@ -210,6 +212,17 @@ def respond(response): 'text of the error of HTTP', ) +with subtest('Transport stdio'): + # The server in a child process, which the client starts and ends + stdio = shlex.join([sys.executable, ROOT.child('examples', 'calculator.py').to_str(), 'stdio']) + with contextlib.redirect_stdout(io.StringIO()) as stdout, contextlib.redirect_stderr(io.StringIO()) as stderr: + code = cli.main(['-c', stdio, 'add', '-a', '1', '-b', '2']) + is_deeply_ok((code, stdout.getvalue(), stderr.getvalue()), (0, '3.0\n', ''), 'result') + with contextlib.redirect_stdout(io.StringIO()) as stdout, contextlib.redirect_stderr(io.StringIO()) as stderr: + code = cli.main(['--command', '/nonexistent/server', 'add']) + is_ok(code, 1, 'no program') + like_ok(stderr.getvalue(), re.compile(r'^/nonexistent/server: .*No such file'), 'message') + cli.ua.close() done_testing()