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()