aiohttp-tiny-mcp 0.1.0__py3-none-any.whl

aiohttp_tiny_mcp/stdio_client.py

@@ -0,0 +1,91 @@
+"""BaseClient transport over asyncio streams."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import AsyncIterator, Callable, Mapping
+from contextlib import asynccontextmanager
+from typing import Any, Protocol, runtime_checkable
+
+from .adapter import Adapter
+from .client_base import BaseClient, ClientError, Elicitor
+from .models import Implementation
+
+
+@runtime_checkable
+class ByteWriter(Protocol):
+    """Writer interface required by StdioClient."""
+
+    def write(self, data: bytes) -> Any: ...
+
+    async def drain(self) -> Any: ...
+
+
+class StdioClient(BaseClient):
+    def __init__(
+        self,
+        reader: asyncio.StreamReader,
+        writer: ByteWriter,
+        adapter: Adapter,
+        *,
+        client_info: Implementation | None = None,
+        on_ask: Elicitor | None = None,
+        on_notification: Callable[[Mapping[str, Any]], Any] | None = None,
+        log_level: str | None = None,
+    ) -> None:
+        super().__init__(
+            adapter,
+            client_info=client_info,
+            on_ask=on_ask,
+            on_notification=on_notification,
+            log_level=log_level,
+        )
+        self.reader = reader
+        self.writer = writer
+
+    def write_line(self, envelope: dict[str, Any]) -> None:
+        self.writer.write((json.dumps(envelope, ensure_ascii=False) + "\n").encode())
+
+    async def exchange(
+        self, envelope: dict[str, Any], *, method: str, name: str | None
+    ) -> AsyncIterator[dict[str, Any]]:
+        self.write_line(envelope)
+        await self.writer.drain()
+        while True:
+            line = await self.reader.readline()
+            if not line:
+                raise ClientError(-32000, "stdio server closed the stream before replying")
+            yield json.loads(line)
+
+    async def send_notification(self, envelope: dict[str, Any], *, method: str) -> None:
+        self.write_line(envelope)
+        await self.writer.drain()
+
+    async def reply(self, envelope: dict[str, Any]) -> None:
+        """Send the answer on the shared JSON-RPC channel."""
+        self.write_line(envelope)
+        await self.writer.drain()
+
+    @classmethod
+    @asynccontextmanager
+    async def spawn(
+        cls,
+        *cmd: str,
+        adapter: Adapter,
+        client_info: Implementation | None = None,
+        on_ask: Elicitor | None = None,
+    ) -> AsyncIterator[StdioClient]:
+        """Launch cmd with protocol pipes; inherit stderr so logging cannot corrupt stdout."""
+        process = await asyncio.create_subprocess_exec(
+            *cmd, stdin=asyncio.subprocess.PIPE, stdout=asyncio.subprocess.PIPE
+        )
+        assert process.stdin is not None
+        assert process.stdout is not None
+        try:
+            yield cls(
+                process.stdout, process.stdin, adapter, client_info=client_info, on_ask=on_ask
+            )
+        finally:
+            process.terminate()
+            await process.wait()

aiohttp_tiny_mcp/subscriptions.py

@@ -0,0 +1,124 @@
+"""Notification filtering for modern request streams and legacy session subscriptions.
+
+Both read the same hub topic; legacy streams reload subscriptions from the shared session.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import TYPE_CHECKING, Any
+
+from . import hub as hubs
+from .models import EmptyResult, ListenParams, Meta
+from .sessions import SUBSCRIPTIONS_KEY, Session
+
+if TYPE_CHECKING:
+    from .exchange import Exchange
+
+SUBSCRIPTION_ID = "io.modelcontextprotocol/subscriptionId"
+LIST_CHANGES = {
+    "notifications/tools/list_changed": ("toolsListChanged", "tools"),
+    "notifications/prompts/list_changed": ("promptsListChanged", "prompts"),
+    "notifications/resources/list_changed": ("resourcesListChanged", "resources"),
+}
+
+
+def tag(payload: Mapping[str, Any], subscription_id: str | int) -> dict[str, Any]:
+    params = dict(payload.get("params") or {})
+    params["_meta"] = {**params.get("_meta", {}), SUBSCRIPTION_ID: subscription_id}
+    return {**payload, "params": params}
+
+
+def relays(payload: Mapping[str, Any], accepted: Mapping[str, Any]) -> bool:
+    """Whether this event is one the client asked for."""
+    method = payload.get("method")
+    if "id" in payload or payload.get("jsonrpc") != "2.0":
+        return False
+    if method == "notifications/resources/updated":
+        params = payload.get("params")
+        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]))
+
+
+async def listen(ex: Exchange) -> EmptyResult:
+    assert isinstance(ex.call.params, ListenParams)
+    wanted = ex.call.params.notifications
+    caps = ex.adapter.capabilities(ex.registry)
+    accepted: dict[str, Any] = {}
+    requested = wanted.wire()
+    for field, capability in LIST_CHANGES.values():
+        if requested.get(field) and caps.get(capability, {}).get("listChanged"):
+            accepted[field] = True
+    if caps.get("resources", {}).get("subscribe"):
+        uris = [uri for uri in wanted.resource_subscriptions if ex.registry.match_resource(uri)]
+        if uris:
+            accepted["resourceSubscriptions"] = list(dict.fromkeys(uris))
+
+    ack = tag(
+        {
+            "jsonrpc": "2.0",
+            "method": "notifications/subscriptions/acknowledged",
+            "params": {"notifications": accepted},
+        },
+        ex.id,
+    )
+    hub = ex.registry.hub
+    if not accepted:
+        await ex.emit(ack)
+        return EmptyResult(meta=Meta.model_validate({SUBSCRIPTION_ID: ex.id}))
+
+    topic = hubs.topic(hubs.NOTIFICATIONS)
+    cursor = await hub.position(topic)
+    await ex.emit(ack)
+    while not ex.cancelled.is_set():
+        messages, cursor = await hub.poll(topic, cursor, timeout=ex.registry.hub_poll_seconds)
+        for payload in messages:
+            if relays(payload, accepted):
+                await ex.emit(tag(payload, ex.id))
+    return EmptyResult(meta=Meta.model_validate({SUBSCRIPTION_ID: ex.id}))
+
+
+URIS = "uris"
+
+
+def subscribed(session: Session | None) -> list[str]:
+    """Resources this client asked to hear about."""
+    if session is None:
+        return []
+    uris = session.slot(SUBSCRIPTIONS_KEY).get(URIS)
+    if not isinstance(uris, Mapping):
+        return []
+    return [uri for uri in uris if isinstance(uri, str)]
+
+
+async def subscribe(session: Session, uri: str) -> None:
+    await session.update_slot(
+        SUBSCRIPTIONS_KEY, lambda held: {**held, URIS: {**dict(held.get(URIS) or {}), uri: True}}
+    )
+
+
+async def unsubscribe(session: Session, uri: str) -> None:
+    await session.update_slot(
+        SUBSCRIPTIONS_KEY,
+        lambda held: {
+            **held,
+            URIS: {key: True for key in dict(held.get(URIS) or {}) if key != uri},
+        },
+    )
+
+
+def wanted(capabilities: Mapping[str, Any], session: Session | None) -> dict[str, Any]:
+    """Legacy list changes follow advertised capabilities; resource updates follow session
+    subscriptions.
+    """
+    accepted: dict[str, Any] = {}
+    for field, capability in LIST_CHANGES.values():
+        if capabilities.get(capability, {}).get("listChanged"):
+            accepted[field] = True
+    if capabilities.get("resources", {}).get("subscribe"):
+        uris = subscribed(session)
+        if uris:
+            accepted["resourceSubscriptions"] = uris
+    return accepted

aiohttp_tiny_mcp/testing.py

@@ -0,0 +1,200 @@
+"""Test helpers for in-memory and HTTP MCP clients."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+from collections.abc import AsyncIterator, Awaitable, Callable, Mapping
+from contextlib import asynccontextmanager
+from typing import Any
+
+from aiohttp import web
+
+from .adapter import Adapter
+from .client import Client
+from .client_base import BaseClient, Elicitor
+from .core import elicit_accept, elicit_decline
+from .endpoint import Endpoint
+from .models import Implementation
+from .protocol.selection import AdapterSet
+from .registry import Registry
+from .stdio import serve_stdio
+from .stdio_client import StdioClient
+
+
+class Pipe:
+    """One direction of an in-memory connection."""
+
+    def __init__(self) -> None:
+        self.reader = asyncio.StreamReader()
+
+    def write(self, data: bytes) -> None:
+        self.reader.feed_data(data)
+
+    async def drain(self) -> None:
+        return None
+
+    def close(self) -> None:
+        self.reader.feed_eof()
+
+
+def answering(answers: Mapping[str, Any] | None) -> Elicitor | None:
+    """Build an elicitation callback from a mapping."""
+    if answers is None:
+        return None
+
+    async def answer(request: Mapping[str, Any]) -> Mapping[str, Any]:
+        key = str((request.get("params") or {}).get("message", ""))
+        for wanted, value in answers.items():
+            if wanted in key:
+                return elicit_decline() if value is None else elicit_accept(value)
+        return elicit_decline()
+
+    return answer
+
+
+@asynccontextmanager
+async def connect(
+    registry: Registry,
+    *,
+    adapter: Adapter | str | None = None,
+    answers: Mapping[str, Any] | None = None,
+    on_ask: Elicitor | None = None,
+    client_info: Implementation | None = None,
+    initialize: bool = True,
+) -> AsyncIterator[BaseClient]:
+    """A client talking to `registry` through memory.
+
+    No port, no subprocess, and nothing to tear down. The protocol is the
+    real one: pick `adapter` to see what a client of that revision sees.
+
+    Answer a handler's questions with `answers`, keyed by any part of the
+    question's text::
+
+        async with connect(registry, answers={"Deploy": {"ok": True}}) as client:
+            result = await client.call_tool("deploy", {"service": "web"})
+    """
+    chosen = pick(adapter)
+    to_server, to_client = Pipe(), Pipe()
+
+    def send(payload: Mapping[str, Any]) -> None:
+        to_client.write((json.dumps(payload, ensure_ascii=False) + "\n").encode())
+
+    served = asyncio.ensure_future(serve_stdio(registry, to_server.reader, send))
+    client = StdioClient(
+        to_client.reader,
+        to_server,
+        chosen,
+        client_info=client_info,
+        on_ask=on_ask or answering(answers),
+    )
+    try:
+        if initialize:
+            await client.initialize()
+        yield client
+    finally:
+        to_server.close()
+        served.cancel()
+        await asyncio.gather(served, return_exceptions=True)
+
+
+@asynccontextmanager
+async def serving(
+    registry: Registry,
+    *,
+    path: str = "/mcp",
+    adapters: AdapterSet | None = None,
+    middlewares: list[Any] | None = None,
+) -> AsyncIterator[str]:
+    """`registry` on a loopback port, for the examples that are about HTTP.
+
+    Yields the URL. The port is whichever one was free, so nothing collides
+    with anything else running.
+    """
+    app = web.Application(middlewares=middlewares or [])
+    Endpoint(registry, adapters=adapters).setup(app, path)
+    runner = web.AppRunner(app, access_log=None)
+    await runner.setup()
+    site = web.TCPSite(runner, "127.0.0.1", 0)
+    await site.start()
+    host, port = runner.addresses[0]
+    try:
+        yield f"http://{host}:{port}{path}"
+    finally:
+        await runner.cleanup()
+
+
+@asynccontextmanager
+async def over_http(
+    registry: Registry,
+    *,
+    adapter: Adapter | str | None = None,
+    answers: Mapping[str, Any] | None = None,
+    on_ask: Elicitor | None = None,
+    headers: Mapping[str, str] | None = None,
+    initialize: bool = True,
+) -> AsyncIterator[Client]:
+    """A real HTTP client against a real server, both started here.
+
+    Use it where the transport is the subject: a session that has to survive
+    a second request, a stream, a header the server reads. Where it is not,
+    `connect` says the same thing without a socket.
+    """
+    import aiohttp
+
+    async with serving(registry) as url:
+        async with aiohttp.ClientSession(headers=dict(headers or {})) as session:
+            async with Client(
+                url,
+                pick(adapter),
+                session=session,
+                on_ask=on_ask or answering(answers),
+            ) as client:
+                if initialize:
+                    await client.initialize()
+                yield client
+
+
+def pick(adapter: Adapter | str | None) -> Adapter:
+    """The adapter to speak, named or taken whole.
+
+    Defaults to the newest revision, which is what a client that knows
+    nothing about this server would offer.
+    """
+    known = AdapterSet.default()
+    if adapter is None:
+        return known.adapters[0]
+    if isinstance(adapter, str):
+        return known.by_version[adapter]
+    return adapter
+
+
+async def every_revision(
+    registry: Registry,
+    call: Callable[[BaseClient], Awaitable[Any]],
+    *,
+    answers: Mapping[str, Any] | None = None,
+    on_ask: Elicitor | None = None,
+) -> dict[str, Any]:
+    """Run `call` once per revision, and report what each one saw.
+
+    The claim this package makes is that one declaration serves five
+    revisions. This is how an application checks that claim about its own
+    handlers, in one line instead of a loop with a fixture in it.
+    """
+    seen: dict[str, Any] = {}
+    for adapter in AdapterSet.default().adapters:
+        async with connect(registry, adapter=adapter, answers=answers, on_ask=on_ask) as client:
+            seen[adapter.version] = await call(client)
+    return seen
+
+
+__all__ = [
+    "Pipe",
+    "answering",
+    "connect",
+    "every_revision",
+    "over_http",
+    "pick",
+    "serving",
+]

aiohttp_tiny_mcp-0.1.0.dist-info/METADATA

@@ -0,0 +1,12 @@
+Metadata-Version: 2.3
+Name: aiohttp-tiny-mcp
+Version: 0.1.0
+Requires-Dist: aiohttp>=3.14
+Requires-Dist: pydantic>=2.13
+Requires-Dist: psycopg[binary,pool]>=3 ; extra == 'postgres'
+Requires-Dist: redis>=5 ; extra == 'redis'
+Requires-Dist: aiosqlite>=0.20 ; extra == 'sqlite'
+Requires-Python: >=3.10
+Provides-Extra: postgres
+Provides-Extra: redis
+Provides-Extra: sqlite

aiohttp_tiny_mcp-0.1.0.dist-info/RECORD

@@ -0,0 +1,41 @@
+aiohttp_tiny_mcp/__init__.py,sha256=s02rK6AmMEmUfG4M-evjV7UwjTEYBTJLUJfhVMP1djo,1614
+aiohttp_tiny_mcp/adapter.py,sha256=esTqt_Ncq8yRoWF3Yyr5o_rkhO0yfAbLbmdQv1aQuaY,12575
+aiohttp_tiny_mcp/auth.py,sha256=1tIH2GYmy1j1QRM1jNOL9Vavi_4ibonu5enwU-Rc-T4,4420
+aiohttp_tiny_mcp/client.py,sha256=jVD3cKBDziglmhbea32AQEANlpkUiPyVzhgs9aB3CYI,4347
+aiohttp_tiny_mcp/client_base.py,sha256=NwKlOS1Y9JC9xjpR7uXcYlN7JuqcQ9wX1Hj4PeK8d4Y,11793
+aiohttp_tiny_mcp/console/__init__.py,sha256=b0qVFsqneXj9B_-D13t_DYc1lzu6HyC0TM92_0TzJPg,3207
+aiohttp_tiny_mcp/console/console.css,sha256=H8zAjc4UShyJ3-S7i4pNBocSROzmFSyOb9pymABV_Yo,13257
+aiohttp_tiny_mcp/console/console.js,sha256=Z8iFEwzXmwQPUq5pKIoAPLwvvUreo8rhzcQkeAozVfE,41871
+aiohttp_tiny_mcp/console/index.html,sha256=fyj19zbaB9NxJUEIWRwG_n7cDYt-LkutS_yLPHH2o6w,3446
+aiohttp_tiny_mcp/core.py,sha256=r29q1VqiH0hmTP7vKx2a4_i3IXiSNBKUJM1_SzKdFY8,9640
+aiohttp_tiny_mcp/dispatcher.py,sha256=6oZU0y6GEGdyxnr9TFv80AKcNahDWWQjzvPJuVwd5IE,12608
+aiohttp_tiny_mcp/endpoint.py,sha256=bLNgtMzmvCuJGydDceHNRs5lGgeu_qfVT2MhRQk99zI,21223
+aiohttp_tiny_mcp/exchange.py,sha256=VGvzus31WyOjjqE4C8VZZ_hRcC-MFxiZAUnrMvga_II,9901
+aiohttp_tiny_mcp/http_sse.py,sha256=fXdQySm16gAlyBWvundYb8D6j5_5ABwJ4pEPA3hBeok,9427
+aiohttp_tiny_mcp/hub.py,sha256=WqA4lMhsDC2KXjJG6uI9f8t3gh3nHNzDfviNLgAzRTo,3638
+aiohttp_tiny_mcp/models.py,sha256=J4RlhL5OmfTLUImz8yL1MhcODSMLNmkNCmZ_QWvnlaU,9229
+aiohttp_tiny_mcp/namespaces.py,sha256=km-hQfhTNf0cNQARJ6BFcYWjZMOg9dOOS_226Zuxv2s,997
+aiohttp_tiny_mcp/postgres.py,sha256=_w5T_IuRWcRWgpOonOmmgtVLeEDI2umW3QdNajXvfck,15843
+aiohttp_tiny_mcp/protocol/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aiohttp_tiny_mcp/protocol/selection.py,sha256=JfdjGQzG9cNow-415Wu03sza3NAP8cWOhGS7FuSZIpQ,3358
+aiohttp_tiny_mcp/protocol/v2024_11_05.py,sha256=UH1tdkUc1lKCaxnmaFlgJHtGNp_hHFeYG0TnnJZsSrQ,1176
+aiohttp_tiny_mcp/protocol/v2025_03_26.py,sha256=sUYJ6HQAuBz53-m_EtfNUikGU5SO0myjPruXKj9Zpzo,6352
+aiohttp_tiny_mcp/protocol/v2025_06_18.py,sha256=zbq2p4CT5-aD0SqE9LHjoXpTPa2_RRCobt58aIBsyzg,331
+aiohttp_tiny_mcp/protocol/v2025_11_25.py,sha256=TDR_RqBTOb2vLURt87jaGwZMLDh5D6qWYPM7N53ZPIE,6017
+aiohttp_tiny_mcp/protocol/v2026_07_28.py,sha256=TGBUia7Riu-A_Qrhx80Sa0lfvJjLFighX9mlP8ZI8Ro,14181
+aiohttp_tiny_mcp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+aiohttp_tiny_mcp/redis.py,sha256=Jy8T0bimOcGeOrQDRHgVsiGKgPbBh64284DVLhrCAEA,6069
+aiohttp_tiny_mcp/registry.py,sha256=aCTioi4w9IR9huXFQ9htyBz_BUDNWKOSdGkwA8QcojM,7067
+aiohttp_tiny_mcp/request_state.py,sha256=yhW9wyNxVZcFOGjPqC-wtJPmyYOtsJbxTsfQPejlVeQ,3404
+aiohttp_tiny_mcp/schema.py,sha256=Y5W-Xvszdpi9QMdS7KL3Hy4Q9iO5F8C1Zn4_GisK9ss,4940
+aiohttp_tiny_mcp/sessions.py,sha256=knm-3r9qen2rU-M4KXq6wJZNoclU6U2w-IP1BjNSy6U,11762
+aiohttp_tiny_mcp/specs.py,sha256=n_1cyuJxfwZmp0vwj-5xjHcjSoBqdphup0ix54w2DLI,8944
+aiohttp_tiny_mcp/sqlite.py,sha256=_2Tg6gbP3Me8NFkhz9fPXIURKIrr8KMzpQCciy8-Buo,8565
+aiohttp_tiny_mcp/sse.py,sha256=QO7FPPNKRmWK3yCqLhw1lg50yKMG8ukclnfJ-DuU4E0,8843
+aiohttp_tiny_mcp/stdio.py,sha256=0irKliwRWyRj3Y3xC5tpLAX4novmTIj7ZAP8uh1iwfI,6593
+aiohttp_tiny_mcp/stdio_client.py,sha256=rRuLovXCJpEwyaVN_74aRknx_cQmVb_yGmnC1KFEj0c,2947
+aiohttp_tiny_mcp/subscriptions.py,sha256=5YkJU2e3FX0kwmYzkh-wAg-psT0xhzKiA-4g9lK9Ig0,4440
+aiohttp_tiny_mcp/testing.py,sha256=AIL3tdxnKwUi6PG9jbY_Dh4bM17eb-t0QORzQPPXots,6044
+aiohttp_tiny_mcp-0.1.0.dist-info/WHEEL,sha256=oy45bIW3ehK02fnLDUKD-FzeaR3VpJxY5Jdblkktnpw,80
+aiohttp_tiny_mcp-0.1.0.dist-info/METADATA,sha256=xwTlYhy4lTrXDKusVrEys46XnNGf6Z0Yv7un38upVzc,368
+aiohttp_tiny_mcp-0.1.0.dist-info/RECORD,,

aiohttp_tiny_mcp-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: uv 0.12.0
+Root-Is-Purelib: true
+Tag: py3-none-any