Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 26 additions & 8 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -47,10 +47,25 @@ one, is answered with JSON, as before, where `MCP::Server` of the Perl `MCP`
opens the stream for every result that is a promise. The stream needs a client
that has `text/event-stream` in its `Accept`; for another one the notifications
go nowhere and the result is JSON. The stream has no inactivity timeout, as a
tool may take long between two notifications, and `X-Accel-Buffering: no`, so
that nginx passes each event at once. The connection of the stream that closes
before the result cancels the `Context`, which emits `cancelled` once, and the
result of a cancelled request is not written. A notification that the client
tool may take long between two notifications, a comment every `heartbeat`
seconds, of the helper `heartbeat` of Pyjoyment, which keeps a proxy from
closing it, and `X-Accel-Buffering: no`, so that nginx passes each event at
once. The connection of the stream that closes before the result cancels the
`Context`, which emits `cancelled` once, and the result of a cancelled request
is not written.

The promise of a tool, a prompt, a resource or a completion, or the one of its
coroutine, is cancelled with the `Context`, by `Context.cancellable` and
`cancel` of `Pyjo.Promise`, as Pyjoyment cancels an action that is a
coroutine when its connection closes: the coroutine gets the exception of the
cancellation of the reactor where it waits, and a request of `Pyjo.UserAgent`
that it waits for closes its connection, so that a request to a slow service
stops too. The action of `to_action` is not a coroutine, so Pyjoyment does not
cancel it itself. The cancellation is a `BaseException`, which
`Pyjo.JSON.RPC` would log as an error of the server, so `cancellable` rejects
its promise with an error of JSON-RPC instead, whose response is not written
anyway. With the reactor of asyncio, a coroutine whose task has not started
yet does not run at all, so its `finally` blocks do not run either. A notification that the client
did not ask for, progress without a `progressToken` or a log message below its
`logLevel`, is not sent at all.

Expand Down Expand Up @@ -212,9 +227,8 @@ A server ends a subscription with a response, not with `notifications/cancelled`
which the page of the cancellation names for it: the page of the subscriptions,
which describes the graceful closure, gives the response. Over Streamable HTTP, the event `finish` of the event loop, which a graceful
stop emits, ends the subscriptions of its connections, as a stream that stays
open would keep the server waiting until its timeout, and a recurring timer
writes a comment of the stream every `heartbeat` seconds, which keeps a proxy
from closing it. Over stdio, the end of the input ends the subscriptions of its
open would keep the server waiting until its timeout, and its comments every
`heartbeat` seconds are those of any stream of events. Over stdio, the end of the input ends the subscriptions of its
peer, as `Pyjo.JSON.RPC.serve` closes the stream only once the requests in
progress have their responses.

Expand Down Expand Up @@ -296,7 +310,11 @@ mise exec -- uv run --group sdk --with-editable ../Pyjoyment python -m Pyjo.Prov
## Development

The distribution depends on the release of Pyjoyment on PyPI, with the lowest
version that has what it uses, which `uv.lock` pins. A change of Pyjoyment that
version that has what it uses, which `uv.lock` pins. Until the release after
0.3.0, it uses `cancel` of `Pyjo.Promise` and the helper `heartbeat` of the
branch `main` of Pyjoyment, of `[tool.uv.sources]`, while its lowest version
stays 0.3.0, which the workflow Build installs from PyPI to import the wheel:
the release replaces both, the source and the lowest version. A change of Pyjoyment that
is not released yet would be its Git repository in `[tool.uv.sources]` of
`pyproject.toml`, until its release, and not a path to the checkout next to
this one: uv applies the sources of a dependency of Git, so whoever installs
Expand Down
7 changes: 6 additions & 1 deletion Pyjo/MCP/Prompt.py
Original file line number Diff line number Diff line change
Expand Up @@ -204,7 +204,10 @@ def get_p(self, arguments: Mapping[str, Any], context: Any = None) -> Pyjo.Promi
Call the function with the arguments, and return a :mod:`Pyjo.Promise`
of the result of the prompt, as ``prompts/get`` gives it, without its
``resultType``, or rejected with a :class:`Pyjo.JSON.RPC.Error` of
arguments that are not valid, or an exception of the function. ::
arguments that are not valid, or an exception of the function. A
promise or a coroutine of the function is cancelled with the
:class:`Pyjo.MCP.Server.Context` of the request, as
:meth:`Pyjo.MCP.Server.Context.cancellable` does. ::

# {'messages': [{'role': 'user', 'content': {'type': 'text', 'text': 'Review this Python code:\\nx = 1'}}]}
prompt.get_p({'code': 'x = 1'}).then(print).wait()
Expand All @@ -226,6 +229,8 @@ def get_p(self, arguments: Mapping[str, Any], context: Any = None) -> Pyjo.Promi
if inspect.iscoroutine(value):
value = Pyjo.Promise.new(value)
if isinstance(value, Pyjo.Promise.object):
if context is not None:
value = context.cancellable(value)
return value.then(self.result)
return Pyjo.Promise.resolve(self.result(value))

Expand Down
7 changes: 6 additions & 1 deletion Pyjo/MCP/Resource.py
Original file line number Diff line number Diff line change
Expand Up @@ -167,7 +167,10 @@ def read_p(self, context: Any = None) -> Pyjo.Promise.object:

Call the function, and return a :mod:`Pyjo.Promise` of the result of
the resource, as ``resources/read`` gives it, without its
``resultType``, or rejected with an exception of the function. ::
``resultType``, or rejected with an exception of the function. A promise
or a coroutine of the function is cancelled with the
:class:`Pyjo.MCP.Server.Context` of the request, as
:meth:`Pyjo.MCP.Server.Context.cancellable` does. ::

# {'contents': [{'uri': 'file:///project/README.md', 'mimeType': 'text/markdown', 'text': '# Pyjo-MCP'}]}
resource.read_p().then(print).wait()
Expand All @@ -179,6 +182,8 @@ def read_p(self, context: Any = None) -> Pyjo.Promise.object:
if inspect.iscoroutine(value):
value = Pyjo.Promise.new(value)
if isinstance(value, Pyjo.Promise.object):
if context is not None:
value = context.cancellable(value)
return value.then(self.result)
return Pyjo.Promise.resolve(self.result(value))

Expand Down
80 changes: 61 additions & 19 deletions Pyjo/MCP/Server.py
Original file line number Diff line number Diff line change
Expand Up @@ -186,7 +186,9 @@ def cancelled(context):
Emitted once when the client abandons the request, as when it closes the
connection of a response of Streamable HTTP before the result, or sends
``notifications/cancelled`` of the request over the transport stdio, so
that a tool that runs long stops. ::
that a tool that runs long stops. A coroutine of a tool, or the promise
that the tool returns, is cancelled by the server, with
:meth:`cancellable`, and another one subscribes to the event. ::

id = Pyjo.IOLoop.recurring(1, lambda: ...)
context.on('cancelled', lambda context: Pyjo.IOLoop.remove(id))
Expand Down Expand Up @@ -379,6 +381,46 @@ def cancel(self) -> Self:
self.emit('cancelled')
return self

def cancellable(self, promise: Pyjo.Promise.object) -> Pyjo.Promise.object:
"""::

promise = context.cancellable(promise)

Cancel the promise with :meth:`Pyjo.Promise.Pyjo_Promise.cancel` when
the client abandons the request, and return a promise of its value,
which the server does for the promise or the coroutine of a tool, a
prompt, a resource and a completion: a coroutine gets the exception of
the cancellation of the reactor, as :class:`asyncio.CancelledError`,
where it waits, so that its ``finally`` blocks run, and a request of
:meth:`Pyjo.UserAgent.Pyjo_UserAgent.start_p` that it waits for closes
its connection. That cancellation rejects the returned promise with an
error of JSON-RPC, not of the server, which is not logged, as nothing
reads its response anymore. ::

# A coroutine that stops where it waits when the client goes away
async def slow() -> str:
await Pyjo.Promise.timer(60)
return 'Done'

promise = context.cancellable(Pyjo.Promise.new(slow()))
"""

def cancelled(context: Context) -> None:
promise.cancel()

if self._cancelled:
promise.cancel()
else:
self.once('cancelled', cancelled)

# The cancellation of the promise, not an error of the server
def failed(e: Any = None) -> Pyjo.Promise.object:
if self._cancelled and not isinstance(e, Exception):
return Pyjo.Promise.reject(Pyjo.JSON.RPC.Error.new(Pyjo.JSON.RPC.INTERNAL_ERROR, 'Request cancelled'))
return Pyjo.Promise.reject(e)

return promise.catch(failed)

def elicit(self, key: str, message: str, schema: dict[str, Any] | None = None) -> dict[str, Any]:
"""::

Expand Down Expand Up @@ -579,10 +621,11 @@ def __init__(self, name: str = 'Pyjo.MCP', version: str = '1.0.0', instructions:
interval = server.heartbeat
server.heartbeat = 15

How often a subscription of Streamable HTTP sends a comment of the
stream of events, which keeps a connection without notifications from
being closed by a proxy, in seconds, ``30`` by default, or ``0`` for
never.
How often a stream of events of Streamable HTTP, as a subscription or
a tool that runs long, sends a comment, with the helper ``heartbeat``
of :mod:`Pyjoyment`, which keeps a connection without notifications
from being closed by a proxy, in seconds, ``30`` by default, or ``0``
for never.
"""

self.instructions = instructions
Expand Down Expand Up @@ -978,12 +1021,12 @@ def to_action(self) -> Callable[['Pyjoyment.Controller.object'], Any]:
notification of the request, of :meth:`Context.notify`, turns the
response into a stream of events, ``text/event-stream``, where the
``Accept`` of the request has it, with the notifications and then the
response, and a connection that closes before the result cancels the
:class:`Context`. A subscription of ``subscriptions/listen`` is such a
stream, which needs the ``Accept`` and stays open, with a comment every
:attr:`heartbeat` seconds, until the client closes the connection, or
until the event loop stops gracefully, which ends the subscription with
its response. ::
response, with a comment every :attr:`heartbeat` seconds, and a
connection that closes before the result cancels the :class:`Context`.
A subscription of ``subscriptions/listen`` is such a stream, which
needs the ``Accept`` and stays open, until the client closes the
connection, or until the event loop stops gracefully, which ends the
subscription with its response. ::

# Pyjoyment.Lite
any('/mcp', server.to_action())
Expand Down Expand Up @@ -1017,6 +1060,8 @@ def stream(notification: dict[str, Any]) -> None:
c.helpers.inactivity_timeout(0)
c.res.headers.header('X-Accel-Buffering', 'no')
c.write_sse()
if self.heartbeat:
c.helpers.heartbeat(self.heartbeat)
c.write_sse({'text': Pyjo.JSON.to_json(notification)})

if 'text/event-stream' in (c.req.headers.accept or ''):
Expand Down Expand Up @@ -1115,7 +1160,9 @@ def _complete(self, context: Context, /, **params: Any) -> Pyjo.Promise.object:
return Pyjo.Promise.reject(e)
if inspect.iscoroutine(values):
values = Pyjo.Promise.new(values)
promise = values if isinstance(values, Pyjo.Promise.object) else Pyjo.Promise.resolve(values)
promise = (
context.cancellable(values) if isinstance(values, Pyjo.Promise.object) else Pyjo.Promise.resolve(values)
)

def result(values: Any = None) -> dict[str, Any]:
values = [str(v) for v in cast(list[Any], values or [])]
Expand Down Expand Up @@ -1247,14 +1294,11 @@ def _listen(self, context: Context, **params: Any) -> Pyjo.Promise.object:
promise = Pyjo.Promise.new()
subscriptions = self._subscriptions
loop = Pyjo.IOLoop.singleton
timer: str | None = None
finish: Any = None

def remove() -> None:
if subscription in subscriptions:
subscriptions.remove(subscription)
if timer is not None:
loop.remove(timer)
if finish is not None:
loop.unsubscribe('finish', finish)

Expand All @@ -1273,10 +1317,8 @@ def cancelled(context: Context) -> None:
subscriptions.append(subscription)
subscription.notify('notifications/subscriptions/acknowledged', {'notifications': honored})

# A connection of HTTP gets the comments that keep it open, and ends with a graceful stop of the event loop
if (c := context.controller) is not None:
if self.heartbeat:
timer = loop.recurring(self.heartbeat, lambda loop: c.write_sse({'comment': 'keepalive'}))
# A connection of HTTP ends with a graceful stop of the event loop
if context.controller is not None:

def stopping(loop: Any) -> None:
end()
Expand Down
6 changes: 5 additions & 1 deletion Pyjo/MCP/Tool.py
Original file line number Diff line number Diff line change
Expand Up @@ -248,7 +248,9 @@ def call_p(self, arguments: Mapping[str, Any], context: Any = None) -> Pyjo.Prom
Call the function with the arguments, and return a :mod:`Pyjo.Promise`
of the result of the tool, as ``tools/call`` gives it, without its
``resultType``, or rejected with an exception of the function that is not an
:class:`Error`, an error of the server. ::
:class:`Error`, an error of the server. A promise or a coroutine of the
function is cancelled with the :class:`Pyjo.MCP.Server.Context` of the
request, as :meth:`Pyjo.MCP.Server.Context.cancellable` does. ::

# {'content': [{'type': 'text', 'text': '3'}], 'structuredContent': 3, 'isError': False}
tool.call_p({'a': 1, 'b': 2}).then(print).wait()
Expand All @@ -269,6 +271,8 @@ def call_p(self, arguments: Mapping[str, Any], context: Any = None) -> Pyjo.Prom
if inspect.iscoroutine(value):
value = Pyjo.Promise.new(value)
if isinstance(value, Pyjo.Promise.object):
if context is not None:
value = context.cancellable(value)

def failed(e: Any = None) -> Any:
if isinstance(e, Error):
Expand Down
10 changes: 6 additions & 4 deletions docs/guides/tutorial.rst
Original file line number Diff line number Diff line change
Expand Up @@ -141,10 +141,12 @@ asks for them in the ``_meta`` of its request, with a ``progressToken`` and
the lowest level of the log messages that it wants, and the notifications that
it did not ask for go nowhere. Over Streamable HTTP, the first notification
turns the response into a stream of events, which ends with the result, when
the client accepts one, and a client that closes the connection before the
result cancels the request, which
:attr:`~Pyjo.MCP.Server.Context.is_cancelled` tells. Over the transport stdio,
the notifications are messages of the same stream:
the client accepts one, and which a comment keeps open while the tool is
silent. A client that closes the connection before the result cancels the
request, which stops a tool that is a coroutine where it waits, with the
requests of :mod:`Pyjo.UserAgent` that it waits for, and which
:attr:`~Pyjo.MCP.Server.Context.is_cancelled` tells another one. Over the
transport stdio, the notifications are messages of the same stream:

.. literalinclude:: tutorial/progress.py
:language: python
Expand Down
5 changes: 5 additions & 0 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,11 @@ sdk = ["mcp>=2.3.0"]
[tool.uv.dependency-groups]
docs = { requires-python = ">=3.14" }

# Pyjoyment of Git until its release after 0.3.0, with Pyjo.Promise.cancel and the helper heartbeat, when the lowest
# version of the dependency becomes that release
[tool.uv.sources]
pyjoyment = { git = "https://github.com/pyjoyment/Pyjoyment", branch = "main" }

# Only the package Pyjo.MCP: the package Pyjo is the one of Pyjoyment, whose namespace extend_path keeps open
[tool.hatch.build.targets.wheel]
only-include = ["Pyjo/MCP"]
Expand Down
19 changes: 19 additions & 0 deletions t/MCP_Prompt.py
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
import Pyjo.IOLoop
import Pyjo.JSON.RPC
import Pyjo.MCP.Prompt
import Pyjo.MCP.Server
import Pyjo.Promise

from Pyjo.Test import *
Expand Down Expand Up @@ -162,6 +164,23 @@ async def broken() -> str:

isa_ok(get(Pyjo.MCP.Prompt.new(broken), {}), ValueError, 'exception of a coroutine rejects')

# A coroutine that the cancellation of the context stops where it waits
stopped = []

async def slow() -> str:
try:
await Pyjo.Promise.timer(5)
finally:
stopped.append(True)
return 'Too late'

context = Pyjo.MCP.Server.Context.new()
Pyjo.IOLoop.timer(0.01, lambda loop: context.cancel())
error = get(Pyjo.MCP.Prompt.new(slow), {}, context)
isa_ok(error, Pyjo.JSON.RPC.Error, 'cancelled')
is_ok(error.message, 'Request cancelled', 'message')
is_deeply_ok(stopped, [True], 'finally of the coroutine')

with subtest('Errors'):

def explain(topic: str) -> str:
Expand Down
20 changes: 20 additions & 0 deletions t/MCP_Resource.py
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
import Pyjo.IOLoop
import Pyjo.JSON.RPC
import Pyjo.MCP.Resource
import Pyjo.MCP.Server
import Pyjo.Promise

from Pyjo.Test import *
Expand Down Expand Up @@ -123,6 +126,23 @@ async def broken() -> str:

isa_ok(read(Pyjo.MCP.Resource.new('file:///broken', broken)), ValueError, 'exception of a coroutine rejects')

# A coroutine that the cancellation of the context stops where it waits
stopped = []

async def slow() -> str:
try:
await Pyjo.Promise.timer(5)
finally:
stopped.append(True)
return 'Too late'

context = Pyjo.MCP.Server.Context.new()
Pyjo.IOLoop.timer(0.01, lambda loop: context.cancel())
error = read(Pyjo.MCP.Resource.new('file:///slow', slow), context)
isa_ok(error, Pyjo.JSON.RPC.Error, 'cancelled')
is_ok(error.message, 'Request cancelled', 'message')
is_deeply_ok(stopped, [True], 'finally of the coroutine')

with subtest('Errors'):

def broken():
Expand Down
Loading
Loading