aiohttp-tiny-mcp 0.3.5__tar.gz → 0.3.6__tar.gz

{aiohttp_tiny_mcp-0.3.5 → aiohttp_tiny_mcp-0.3.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: aiohttp-tiny-mcp
-Version: 0.3.5
+Version: 0.3.6
 Summary: Remote MCP server and client library for aiohttp
 License-Expression: Apache-2.0
 License-File: LICENSE

{aiohttp_tiny_mcp-0.3.5 → aiohttp_tiny_mcp-0.3.6}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "aiohttp-tiny-mcp"
-version = "0.3.5"
+version = "0.3.6"
 description = "Remote MCP server and client library for aiohttp"
 readme = "README.md"
 license = "Apache-2.0"

{aiohttp_tiny_mcp-0.3.5 → aiohttp_tiny_mcp-0.3.6}/pyproject.toml.orig

@@ -1,6 +1,6 @@
 [project]
 name = "aiohttp-tiny-mcp"
-version = "0.3.5"
+version = "0.3.6"
 description = "Remote MCP server and client library for aiohttp"
 readme = "README.md"
 license = "Apache-2.0"

{aiohttp_tiny_mcp-0.3.5 → aiohttp_tiny_mcp-0.3.6}/src/aiohttp_tiny_mcp/__init__.py

@@ -27,6 +27,7 @@ from .models import (
     GetPromptResult,
     Hint,
     ImageContent,
+    MethodFilter,
     PromptMessage,
     ResourceLink,
     TextContent,
@@ -63,6 +64,7 @@ __all__ = [
     "ImageContent",
     "MemoryHub",
     "MemorySessionStore",
+    "MethodFilter",
     "NeedInput",
     "namespace",
     "PromptMessage",

{aiohttp_tiny_mcp-0.3.5 → aiohttp_tiny_mcp-0.3.6}/src/aiohttp_tiny_mcp/client_base.py

@@ -25,6 +25,7 @@ from .models import (
     ListPromptsResult,
     ListResourcesResult,
     ListToolsResult,
+    MethodFilter,
     Params,
     PromptDef,
     ReadResourceParams,
@@ -258,13 +259,25 @@ class BaseClient(ABC):
         tools_changed: bool = False,
         prompts_changed: bool = False,
         resources_changed: bool = False,
+        methods: Sequence[str | MethodFilter | Mapping[str, Any]] = (),
     ) -> AsyncIterator[dict[str, Any]]:
-        """Yield changes until cancelled, via a request stream or legacy resource subscriptions."""
+        """Yield changes until cancelled, via a request stream or legacy resource subscriptions.
+
+        `methods` names the extension broadcasts to relay: a method name for
+        every event of it, or `MethodFilter(method, topics)` (a mapping of
+        the same shape will do) for the topics of a multicast. A legacy
+        stream carries every broadcast the server declares, so there it is
+        not sent.
+        """
         wanted = ListenNotifications(
             tools_list_changed=tools_changed,
             prompts_list_changed=prompts_changed,
             resources_list_changed=resources_changed,
             resource_subscriptions=list(resources),
+            methods=[
+                entry if isinstance(entry, str | MethodFilter) else MethodFilter(**entry)
+                for entry in methods
+            ],
         )
         method = self.adapter.method_for(Operation.LISTEN)
         if method is not None:

{aiohttp_tiny_mcp-0.3.5 → aiohttp_tiny_mcp-0.3.6}/src/aiohttp_tiny_mcp/console/console.js

@@ -876,6 +876,10 @@ function choose(what) {
     page.subject.textContent = what.item.name;
     page.about.textContent = "Enter a method and its JSON parameters from the extension documentation.";
     reportValue("Capabilities", what.item.capabilities);
+    if ((what.item.capabilities || {}).notifications) {
+      // Method to the params field that carries its topic; null for a plain broadcast.
+      reportValue("Broadcasts", what.item.capabilities.notifications);
+    }
     chosen.fields = buildFields({
       properties: {
         method: { type: "string", default: what.item.name === SKILLS_EXTENSION ? "skills/list" : "" },

{aiohttp_tiny_mcp-0.3.5 → aiohttp_tiny_mcp-0.3.6}/src/aiohttp_tiny_mcp/endpoint.py

@@ -434,7 +434,11 @@ class Endpoint:
             found = await events.poll()
             if not found:
                 continue
-            accepted = wanted(capabilities, self.open_values(request, await self.stored(request)))
+            accepted = wanted(
+                capabilities,
+                self.open_values(request, await self.stored(request)),
+                self.registry.broadcasts,
+            )
             for event in found:
                 if relays(event.message, accepted):
                     text = json.dumps(event.message, ensure_ascii=False)

{aiohttp_tiny_mcp-0.3.5 → aiohttp_tiny_mcp-0.3.6}/src/aiohttp_tiny_mcp/extensions.py

@@ -3,7 +3,7 @@
 from __future__ import annotations
 
 import json
-from collections.abc import Awaitable, Callable, Mapping
+from collections.abc import Awaitable, Callable, Iterable, Mapping
 from copy import deepcopy
 from dataclasses import dataclass
 from types import MappingProxyType
@@ -17,12 +17,47 @@ from .models import ResultModel
 from .schema import json_schema
 from .specs import Bound, ResourceSpec
 
+RESERVED_NOTIFICATIONS = frozenset(
+    {
+        "notifications/cancelled",
+        "notifications/initialized",
+        "notifications/message",
+        "notifications/progress",
+        "notifications/prompts/list_changed",
+        "notifications/resources/list_changed",
+        "notifications/resources/updated",
+        "notifications/roots/list_changed",
+        "notifications/subscriptions/acknowledged",
+        "notifications/tools/list_changed",
+    }
+)
+
+
+def check_notification(name: str, field: str | None) -> None:
+    """Refuse a broadcast name the protocol owns or a client could not route, and a topic
+    field a listener could not match on.
+    """
+    if (
+        not name.startswith("notifications/")
+        or len(name) <= len("notifications/")
+        or any(char.isspace() for char in name)
+        or any(part in ("", ".", "..") for part in name.split("/"))
+    ):
+        raise ValueError(f"invalid broadcast notification: {name!r}")
+    if name in RESERVED_NOTIFICATIONS:
+        raise ValueError(f"extension cannot broadcast a protocol notification: {name}")
+    if field is not None and (not isinstance(field, str) or not field or field == "_meta"):
+        raise ValueError(f"invalid topic field for {name}: {field!r}")
+
 
 @dataclass(frozen=True)
 class ExtensionSpec:
     capabilities: Mapping[str, Any]
     min_revision: str
     methods: Mapping[str, Bound]
+    #: Broadcast method to the params field that carries its topic, or None for one
+    #: every listener of the method gets.
+    notifications: Mapping[str, str | None] = MappingProxyType({})
 
 
 class ExtensionResult(ResultModel):
@@ -84,6 +119,7 @@ class Extension:
         *,
         capabilities: Mapping[str, Any] | None = None,
         min_revision: str = "2026-07-28",
+        notifications: Iterable[str] | Mapping[str, str | None] = (),
     ) -> None:
         if (
             not name
@@ -99,6 +135,18 @@ class Extension:
         self.min_revision = min_revision
         self.methods: dict[str, Bound] = {}
         self.resources: dict[str, ResourceSpec] = {}
+        #: Methods `Registry.broadcast` may send, each with the params field that
+        #: carries its topic. None makes it a broadcast every listener of the method
+        #: gets; a field makes it a multicast a listener filters by topic.
+        self.notifications: dict[str, str | None] = {}
+        declared = (
+            notifications.items()
+            if isinstance(notifications, Mapping)
+            else ((method, None) for method in notifications)
+        )
+        for method, field in declared:
+            check_notification(method, field)
+            self.notifications[method] = field
 
     def method(self, name: str, fn: Callable[..., Awaitable[Any]] | None = None):
         """Register an async handler whose first argument is a Pydantic model.
@@ -233,6 +281,9 @@ class Extension:
             ),
             "capabilities": self.capabilities,
             "methods": sorted(self.methods),
+            "notifications": {
+                name: self.notifications[name] for name in sorted(self.notifications)
+            },
             "resources": sorted(
                 [
                     spec.legacy_uri
@@ -276,4 +327,5 @@ class Extension:
             methods=MappingProxyType(
                 {name: bound.model_copy(deep=True) for name, bound in self.methods.items()}
             ),
+            notifications=MappingProxyType(dict(self.notifications)),
         )

{aiohttp_tiny_mcp-0.3.5 → aiohttp_tiny_mcp-0.3.6}/src/aiohttp_tiny_mcp/http_sse.py

@@ -5,8 +5,10 @@ from __future__ import annotations
 import asyncio
 import json
 import logging
+from collections.abc import Coroutine
 from contextlib import suppress
 from dataclasses import replace
+from typing import Any
 
 from aiohttp import web
 
@@ -24,7 +26,7 @@ from .core import (
 from .dispatcher import Dispatcher
 from .endpoint import Endpoint
 from .exchange import Exchange
-from .hub import Subscription, topic
+from .hub import NOTIFICATIONS, Subscription, topic
 from .namespaces import scoped
 from .protocol.selection import AdapterSet
 from .registry import Registry
@@ -38,6 +40,7 @@ from .sessions import (
     stored_version,
 )
 from .sse import SSEResponse
+from .subscriptions import relays, wanted
 
 log = logging.getLogger(__name__)
 
@@ -103,7 +106,9 @@ class SseEndpoint:
         session_id = await self.open_session()
         where = topic(STREAM, session_id)
         hub = self.registry.hub
-        events = await hub.subscribe(where, wait=self.registry.hub_poll_seconds)
+        wait = self.registry.hub_poll_seconds
+        events = await hub.subscribe(where, wait=wait)
+        shared = await hub.subscribe(topic(NOTIFICATIONS), wait=wait)
 
         response = SSEResponse(compress=self.compress)
         await response.prepare(request)
@@ -111,7 +116,11 @@ class SseEndpoint:
         await self.write(response, "endpoint", f"{posting}?session_id={session_id}")
 
         try:
-            await self.relay_until_disconnect(request, response, events)
+            await self.relay_until_disconnect(
+                request,
+                self.relay(response, events),
+                self.relay_shared(response, shared, session_id),
+            )
         finally:
             await hub.delete(where)
             await self.registry.session_store.delete(scoped(session_id))
@@ -128,26 +137,54 @@ class SseEndpoint:
         return session_id
 
     async def relay_until_disconnect(
-        self, request: web.Request, response: SSEResponse, events: Subscription
+        self, request: web.Request, *relays: Coroutine[Any, Any, None]
     ) -> None:
-        """Run a relay until its client disconnects, then always join it."""
-        relay = asyncio.create_task(self.relay(response, events))
+        """Run the relays until the client disconnects or one ends, then always join them."""
+        tasks = [asyncio.create_task(relay) for relay in relays]
         try:
-            while not relay.done():
-                await asyncio.wait({relay}, timeout=0.05)
+            while not any(task.done() for task in tasks):
+                await asyncio.wait(tasks, timeout=0.05, return_when=asyncio.FIRST_COMPLETED)
                 transport = request.transport
                 if transport is None or transport.is_closing():
                     break
         finally:
-            relay.cancel()
-            with suppress(asyncio.CancelledError, ConnectionError):
-                await relay
+            for task in tasks:
+                task.cancel()
+            for task in tasks:
+                with suppress(asyncio.CancelledError, ConnectionError):
+                    await task
 
     async def relay(self, response: SSEResponse, events: Subscription) -> None:
         """Write everything published for this connection, until cancelled."""
         async for event in events:
             await self.write(response, "message", json.dumps(event.message, ensure_ascii=False))
 
+    async def relay_shared(
+        self, response: SSEResponse, events: Subscription, session_id: str
+    ) -> None:
+        """Write the list changes, resource updates and broadcasts this session wants.
+
+        The session is re-read for each batch, so a subscription made through
+        the message endpoint takes effect on the stream that is already open.
+        """
+        store = self.registry.session_store
+        while True:
+            found = await events.poll()
+            if not found:
+                continue
+            record = await store.get(scoped(session_id))
+            if record is None:
+                return
+            adapter = self.adapters.resolve_version(stored_version(record) or VERSION)
+            session = Session(store, session_id, record, self.registry.session_ttl_seconds)
+            accepted = wanted(
+                adapter.capabilities(self.registry), session, self.registry.broadcasts
+            )
+            for event in found:
+                if relays(event.message, accepted):
+                    text = json.dumps(event.message, ensure_ascii=False)
+                    await self.write(response, "message", text)
+
     async def write(self, response: SSEResponse, event: str, data: str) -> None:
         log.debug("-> [%s] %s %s", VERSION, event, data)
         await response.send(data, event=event)

{aiohttp_tiny_mcp-0.3.5 → aiohttp_tiny_mcp-0.3.6}/src/aiohttp_tiny_mcp/models.py

@@ -313,11 +313,21 @@ class ListParams(Params):
     cursor: str | None = None
 
 
+class MethodFilter(Model):
+    """One extension multicast, narrowed to the topics named."""
+
+    method: StrictStr
+    topics: list[StrictStr] = Field(default_factory=list)
+
+
 class ListenNotifications(Model):
     tools_list_changed: StrictBool = False
     prompts_list_changed: StrictBool = False
     resources_list_changed: StrictBool = False
     resource_subscriptions: list[StrictStr] = Field(default_factory=list)
+    #: Extension broadcasts to relay: a method name for every event of it, or a
+    #: `MethodFilter` for the topics of a multicast.
+    methods: list[StrictStr | MethodFilter] = Field(default_factory=list)
 
 
 class ListenParams(Params):

{aiohttp_tiny_mcp-0.3.5 → aiohttp_tiny_mcp-0.3.6}/src/aiohttp_tiny_mcp/protocol/v2026_07_28.py

@@ -324,7 +324,16 @@ class Adapter2026_07_28(Adapter):  # noqa: N801 -- revision date, greppable agai
     def capabilities(self, registry: RegistryProtocol) -> dict[str, Any]:
         caps = dict(super().capabilities(registry))
         extensions = {
-            name: dict(spec.capabilities)
+            name: (
+                {
+                    **spec.capabilities,
+                    "notifications": {
+                        name: spec.notifications[name] for name in sorted(spec.notifications)
+                    },
+                }
+                if spec.notifications
+                else dict(spec.capabilities)
+            )
             for name, spec in registry.extensions.items()
             if spec.min_revision <= self.version
         }

{aiohttp_tiny_mcp-0.3.5 → aiohttp_tiny_mcp-0.3.6}/src/aiohttp_tiny_mcp/registry.py

@@ -2,13 +2,13 @@
 
 from __future__ import annotations
 
-from collections.abc import Awaitable, Callable
+from collections.abc import Awaitable, Callable, Mapping
 from typing import Any
 
 from .auth import Authorization, Principal
 from .exchange import Exchange, Instance
 from .extensions import Extension, ExtensionSpec
-from .hub import Hub, MemoryHub
+from .hub import NOTIFICATIONS, Cursor, Hub, MemoryHub, topic
 from .models import Implementation
 from .request_state import DEFAULT_TTL_SECONDS as STATE_TTL_SECONDS
 from .request_state import RequestStates
@@ -85,6 +85,11 @@ class Registry:
             if any(name in spec.methods for spec in self.extensions.values()):
                 raise ValueError(f"duplicate extension method: {name}")
             self.check(name, bound)
+        for method in extension.notifications:
+            if any(adapter.operation_for(method) is not None for adapter in adapters):
+                raise ValueError(f"extension cannot broadcast a protocol notification: {method}")
+            if method in self.broadcasts:
+                raise ValueError(f"duplicate broadcast notification: {method}")
         routes, methods = extension.method_resources()
         manifest = extension.manifest_resource(routes, methods)
         assert manifest.definition is not None
@@ -129,6 +134,49 @@ class Registry:
                 else:
                     self.resources_templated.append(resource)
 
+    @property
+    def broadcasts(self) -> frozenset[str]:
+        """Every notification method some installed extension may broadcast."""
+        return frozenset(self.topic_fields)
+
+    @property
+    def topic_fields(self) -> dict[str, str | None]:
+        """Each declared broadcast with the params field that carries its topic, or None."""
+        found: dict[str, str | None] = {}
+        for spec in self.extensions.values():
+            found.update(spec.notifications)
+        return found
+
+    async def broadcast(
+        self,
+        method: str,
+        params: Mapping[str, Any] | None = None,
+        *,
+        meta: Mapping[str, Any] | None = None,
+    ) -> Cursor:
+        """Send one notification to every client listening in the current namespace.
+
+        `method` must be declared by an installed extension. A method declared
+        with a topic field is a multicast: `params` must carry that field as a
+        string, and a listener that named topics gets the event only when the
+        value is one of them. The event goes through the hub, so a listener
+        on another worker gets it too, and a legacy stream that reconnects
+        with `Last-Event-ID` is replayed it. Returns the hub id the event was
+        stored under.
+        """
+        fields = self.topic_fields
+        if method not in fields:
+            raise ValueError(f"no installed extension declares the broadcast {method!r}")
+        sent: dict[str, Any] = dict(params or {})
+        field = fields[method]
+        if field is not None and not isinstance(sent.get(field), str):
+            raise ValueError(f"{method} is a multicast: params[{field!r}] must be a string topic")
+        if meta:
+            sent["_meta"] = {**dict(sent.get("_meta") or {}), **meta}
+        return await self.hub.publish(
+            topic(NOTIFICATIONS), {"jsonrpc": "2.0", "method": method, "params": sent}
+        )
+
     def provide(self, kind: type, source: Any) -> None:
         """Bind a type to where it comes from. Call before registering
         handlers -- plans are checked at registration, not at first call.

{aiohttp_tiny_mcp-0.3.5 → aiohttp_tiny_mcp-0.3.6}/src/aiohttp_tiny_mcp/subscriptions.py

@@ -1,15 +1,18 @@
 """Notification filtering for modern request streams and legacy session subscriptions.
 
 Both read the same hub topic; legacy streams reload subscriptions from the shared session.
+Extension broadcasts travel the same topic: a modern stream names the methods it wants, a
+legacy stream gets every declared one.
 """
 
 from __future__ import annotations
 
-from collections.abc import Mapping
+from collections.abc import Iterable, Mapping
+from types import MappingProxyType
 from typing import TYPE_CHECKING, Any
 
 from . import hub as hubs
-from .models import EmptyResult, ListenParams, Meta
+from .models import EmptyResult, ListenParams, Meta, MethodFilter
 from .sessions import SUBSCRIPTIONS_KEY, Session
 
 if TYPE_CHECKING:
@@ -29,8 +32,17 @@ def tag(payload: Mapping[str, Any], subscription_id: str | int) -> dict[str, Any
     return {**payload, "params": params}
 
 
-def relays(payload: Mapping[str, Any], accepted: Mapping[str, Any]) -> bool:
-    """Whether this event is one the client asked for."""
+def relays(
+    payload: Mapping[str, Any],
+    accepted: Mapping[str, Any],
+    fields: Mapping[str, str | None] = MappingProxyType({}),
+) -> bool:
+    """Whether this event is one the client asked for.
+
+    `fields` maps a multicast method to the params field that carries its
+    topic; an accepted entry with `topics` matches only when that field holds
+    one of them.
+    """
     method = payload.get("method")
     if "id" in payload or payload.get("jsonrpc") != "2.0":
         return False
@@ -39,7 +51,59 @@ def relays(payload: Mapping[str, Any], accepted: Mapping[str, Any]) -> bool:
         if not isinstance(params, Mapping):
             return False
         return params.get("uri") in accepted.get("resourceSubscriptions", [])
-    return method in LIST_CHANGES and bool(accepted.get(LIST_CHANGES[method][0]))
+    if method in LIST_CHANGES:
+        return bool(accepted.get(LIST_CHANGES[method][0]))
+    for entry in accepted.get("methods", ()):
+        if isinstance(entry, str):
+            if entry == method:
+                return True
+            continue
+        if entry.get("method") != method:
+            continue
+        field = fields.get(method)
+        params = payload.get("params")
+        if field is None or not isinstance(params, Mapping):
+            return False
+        return params.get(field) in entry.get("topics", ())
+    return False
+
+
+def broadcasts_for(ex: Exchange) -> dict[str, str | None]:
+    """The broadcasts this revision may hear, those of the extensions it can see, each with
+    its topic field.
+    """
+    found: dict[str, str | None] = {}
+    for spec in ex.registry.extensions.values():
+        if spec.min_revision <= ex.adapter.version:
+            found.update(spec.notifications)
+    return found
+
+
+def merged(
+    requested: Iterable[str | MethodFilter], declared: Mapping[str, str | None]
+) -> list[str | dict[str, Any]]:
+    """The entries a listen request keeps, in first-seen order, one per method.
+
+    A bare name asks for every event of the method, so it wins over any
+    filter for the same method. Filters on one method merge their topics. A
+    filter on a method declared without a topic field has nothing to match
+    on and becomes the bare name. Undeclared methods are dropped.
+    """
+    kept: dict[str, list[str] | None] = {}
+    for entry in requested:
+        name = entry if isinstance(entry, str) else entry.method
+        if name not in declared:
+            continue
+        topics = None if isinstance(entry, str) or declared[name] is None else entry.topics
+        held = kept.get(name, [])
+        if topics is None or held is None:
+            kept[name] = None
+        else:
+            kept[name] = list(dict.fromkeys([*held, *topics]))
+    return [
+        name if topics is None else {"method": name, "topics": topics}
+        for name, topics in kept.items()
+    ]
 
 
 async def listen(ex: Exchange) -> EmptyResult:
@@ -55,6 +119,10 @@ async def listen(ex: Exchange) -> EmptyResult:
         uris = [uri for uri in wanted.resource_subscriptions if ex.registry.match_resource(uri)]
         if uris:
             accepted["resourceSubscriptions"] = list(dict.fromkeys(uris))
+    declared = broadcasts_for(ex)
+    methods = merged(wanted.methods, declared)
+    if methods:
+        accepted["methods"] = methods
 
     ack = tag(
         {
@@ -73,7 +141,7 @@ async def listen(ex: Exchange) -> EmptyResult:
     await ex.emit(ack)
     while not ex.cancelled.is_set():
         for event in await events.poll():
-            if relays(event.message, accepted):
+            if relays(event.message, accepted, declared):
                 await ex.emit(tag(event.message, ex.id))
     return EmptyResult(meta=Meta.model_validate({SUBSCRIPTION_ID: ex.id}))
 
@@ -107,9 +175,11 @@ async def unsubscribe(session: Session, uri: str) -> None:
     )
 
 
-def wanted(capabilities: Mapping[str, Any], session: Session | None) -> dict[str, Any]:
+def wanted(
+    capabilities: Mapping[str, Any], session: Session | None, broadcasts: Iterable[str] = ()
+) -> dict[str, Any]:
     """Legacy list changes follow advertised capabilities; resource updates follow session
-    subscriptions.
+    subscriptions; every declared broadcast is relayed, as a legacy stream cannot choose.
     """
     accepted: dict[str, Any] = {}
     for field, capability in LIST_CHANGES.values():
@@ -119,4 +189,7 @@ def wanted(capabilities: Mapping[str, Any], session: Session | None) -> dict[str
         uris = subscribed(session)
         if uris:
             accepted["resourceSubscriptions"] = uris
+    methods = sorted(broadcasts)
+    if methods:
+        accepted["methods"] = methods
     return accepted