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

aiohttp_tiny_mcp/__init__.py

@@ -0,0 +1,76 @@
+"""Stateless remote MCP server: aiohttp + pydantic, nothing else."""
+
+from __future__ import annotations
+
+from .client import Client
+from .client_base import ClientError, Elicitor
+from .core import (
+    Answer,
+    AnswerAction,
+    NeedInput,
+    elicit,
+    elicit_accept,
+    elicit_cancel,
+    elicit_decline,
+)
+from .endpoint import Endpoint
+from .exchange import Exchange
+from .http_sse import SseEndpoint
+from .hub import Hub, MemoryHub
+from .models import (
+    AudioContent,
+    CallToolResult,
+    Completion,
+    GetPromptResult,
+    Hint,
+    ImageContent,
+    PromptMessage,
+    ResourceLink,
+    TextContent,
+)
+from .namespaces import namespace
+from .protocol.selection import AdapterSet
+from .registry import Registry
+from .request_state import RequestStates
+from .sessions import MemorySessionStore, SessionRecord, SessionStore
+from .sse import SSEResponse
+from .stdio import run_stdio, serve_stdio
+from .stdio_client import StdioClient
+
+__all__ = [
+    "AdapterSet",
+    "Answer",
+    "AnswerAction",
+    "AudioContent",
+    "CallToolResult",
+    "Client",
+    "ClientError",
+    "Elicitor",
+    "Completion",
+    "Endpoint",
+    "SSEResponse",
+    "Exchange",
+    "GetPromptResult",
+    "Hint",
+    "Hub",
+    "ImageContent",
+    "MemoryHub",
+    "MemorySessionStore",
+    "NeedInput",
+    "namespace",
+    "PromptMessage",
+    "Registry",
+    "SseEndpoint",
+    "RequestStates",
+    "ResourceLink",
+    "SessionRecord",
+    "SessionStore",
+    "StdioClient",
+    "TextContent",
+    "elicit",
+    "elicit_accept",
+    "elicit_cancel",
+    "elicit_decline",
+    "run_stdio",
+    "serve_stdio",
+]

aiohttp_tiny_mcp/adapter.py

@@ -0,0 +1,321 @@
+"""Protocol adapters and structural interfaces for requests and registries."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from collections.abc import Mapping, Sequence
+from types import MappingProxyType
+from typing import Any, ClassVar, Protocol, cast
+
+from pydantic import BaseModel, ValidationError
+
+from .core import (
+    AnswerAction,
+    Call,
+    ClientInfo,
+    ClientProfile,
+    DecodeFailure,
+    Failure,
+    FailureKind,
+    InputRequest,
+    NeedsInput,
+    Operation,
+    Preamble,
+    Rejected,
+    Value,
+    answer_actions,
+    decode_failure_target,
+)
+from .hub import Hub
+from .models import (
+    CallToolParams,
+    CompleteParams,
+    ErrorBody,
+    ErrorResponse,
+    GetPromptParams,
+    Implementation,
+    Incoming,
+    ListParams,
+    Params,
+    PromptDef,
+    ReadResourceParams,
+    ResourceDef,
+    ResourceTemplateDef,
+    ToolDef,
+)
+from .specs import Bound, PromptSpec, ResourceSpec, ToolSpec
+
+
+class RequestLike(Protocol):
+    """Request interface for AppKey-based dependency injection, including non-HTTP transports."""
+
+    @property
+    def app(self) -> Any: ...
+
+
+class RegistryProtocol(Protocol):
+    """Read-only properties allow registries with concrete dict collections to conform."""
+
+    @property
+    def info(self) -> Implementation: ...
+    @property
+    def instructions(self) -> str | None: ...
+    @property
+    def hub(self) -> Hub: ...
+    @property
+    def tools(self) -> Mapping[str, ToolSpec]: ...
+    @property
+    def resources_fixed(self) -> Mapping[str, ResourceSpec]: ...
+    @property
+    def resources_templated(self) -> Sequence[ResourceSpec]: ...
+    @property
+    def prompts(self) -> Mapping[str, PromptSpec]: ...
+    @property
+    def completer(self) -> Bound | None: ...
+    def match_resource(self, uri: str) -> tuple[ResourceSpec, dict[str, str]] | None: ...
+
+
+class Adapter(ABC):
+    """One instance per revision, stateless and shared across requests."""
+
+    version: ClassVar[str]
+    supersedes: ClassVar[tuple[str, ...]] = ()
+
+    BASE_FAILURE_MAP: ClassVar[Mapping[FailureKind, tuple[int, int]]] = MappingProxyType(
+        {
+            FailureKind.PARSE: (-32700, 400),
+            FailureKind.MALFORMED: (-32600, 400),
+            FailureKind.INVALID_PARAMS: (-32602, 200),
+            FailureKind.ORIGIN_REJECTED: (-32600, 403),
+            FailureKind.INTERNAL: (-32603, 200),
+            FailureKind.INVALID_ARGUMENTS: (-32603, 200),
+            FailureKind.UNKNOWN_METHOD: (-32601, 200),
+            FailureKind.UNKNOWN_TARGET: (-32601, 200),
+            FailureKind.RESOURCE_NOT_FOUND: (-32002, 200),
+            FailureKind.HEADER_MISMATCH: (-32603, 200),
+            FailureKind.UNSUPPORTED_VERSION: (-32600, 400),
+            FailureKind.INPUT_UNSUPPORTED: (-32603, 200),
+            FailureKind.MISSING_REQUIRED_CAPABILITY: (-32603, 200),
+        }
+    )
+    FAILURE_MAP: ClassVar[Mapping[FailureKind, tuple[int, int]]] = BASE_FAILURE_MAP
+
+    def bind(self, versions: tuple[str, ...]) -> None:
+        """Receive the served revisions once at AdapterSet construction, for discovery."""
+        return None  # noqa: B027 -- concrete default, most revisions need nothing
+
+    def check_http(
+        self,
+        pre: Preamble,
+        headers: Mapping[str, str],
+        registry: RegistryProtocol | None = None,
+    ) -> None:
+        """Raise `Rejected` on a revision-specific HTTP binding violation."""
+        return None  # noqa: B027 -- concrete default, most revisions check nothing
+
+    def decode(self, pre: Preamble) -> Sequence[Call | DecodeFailure]:
+        """Decode messages independently; one invalid item does not abort the batch."""
+        if pre.parse_error:
+            raise Rejected(Failure(FailureKind.PARSE, "invalid JSON body"))
+        if pre.is_batch:
+            if not self.allows_batch:
+                raise Rejected(Failure(FailureKind.MALFORMED, "batching not supported"))
+            if not pre.body:  # `is_batch` already means the body is a list
+                raise Rejected(Failure(FailureKind.MALFORMED, "empty batch"))
+            return [self.decode_item(item) for item in pre.body]
+        return [self.decode_item(pre.body)]
+
+    def decode_item(self, item: object) -> Call | DecodeFailure:
+        """Preserve the request id on failure without aborting sibling batch items."""
+        if not isinstance(item, dict):
+            return DecodeFailure(
+                id=None,
+                failure=Failure(FailureKind.MALFORMED, "request must be an object"),
+                must_respond=True,
+            )
+        body = cast(dict[str, Any], item)
+        try:
+            return self.decode_one(body)
+        except Rejected as e:
+            call_id, must_respond = decode_failure_target(body)
+            return DecodeFailure(id=call_id, failure=e.failure, must_respond=must_respond)
+
+    def decode_one(self, body: dict[str, Any]) -> Call:
+        if "id" in body and body["id"] is None:
+            raise Rejected(Failure(FailureKind.MALFORMED, "id must not be null"))
+        try:
+            msg = Incoming.model_validate(body)
+        except ValidationError as e:
+            raise Rejected(Failure(FailureKind.MALFORMED, str(e))) from None
+        operation = self.operation_for(msg.method)
+        if operation is None:
+            raise Rejected(Failure(FailureKind.UNKNOWN_METHOD, f"unknown method: {msg.method}"))
+        self.check_message(operation, msg)
+        try:
+            params = self.params_model(operation).model_validate(msg.params)
+        except ValidationError as e:
+            raise Rejected(Failure(FailureKind.INVALID_PARAMS, str(e))) from None
+        self.check_params(params)
+        return self.build_call(operation, msg, params)
+
+    def build_call(self, operation: Operation, msg: Incoming, params: Params) -> Call:
+        target: str | None = None
+        arguments: dict[str, Any] = {}
+        match params:
+            case CallToolParams() | GetPromptParams():
+                target, arguments = params.name, dict(params.arguments)
+            case ReadResourceParams():
+                target = params.uri
+            case CompleteParams():
+                arguments = params.model_dump(
+                    by_alias=True, exclude={"meta", "input_responses", "request_state"}
+                )
+            case ListParams():
+                arguments = {"cursor": params.cursor} if params.cursor else {}
+        return Call(
+            operation=operation,
+            id=msg.id,
+            target=target,
+            arguments=arguments,
+            params=params,
+            client=self.client_info_for(params),
+            progress_token=params.meta.progress_token,
+            log_level=params.meta.log_level,
+            answers=self.answers_for(params),
+            actions=self.actions_for(params),
+            state=params.request_state,
+            raw=msg.params,
+            is_notification=msg.is_notification,
+        )
+
+    def params_model(self, operation: Operation) -> type[Params]:
+        """The params model this revision validates `operation` against."""
+        return Params
+
+    def check_message(self, operation: Operation, msg: Incoming) -> None:
+        """Reject an envelope this revision does not allow for `operation`."""
+        return None  # noqa: B027 -- concrete default, most revisions check nothing
+
+    def check_params(self, params: Params) -> None:
+        """Reject params this revision requires more of (2026-07-28 `_meta`)."""
+        return None  # noqa: B027 -- concrete default, most revisions check nothing
+
+    def client_info_for(self, params: Params) -> ClientInfo:
+        """Client identity, if the revision supplies it."""
+        return ClientInfo()
+
+    def answers_for(self, params: Params) -> Mapping[str, Any]:
+        """MRTR answers, as this revision carries them."""
+        return params.input_responses or {}
+
+    def actions_for(self, params: Params) -> Mapping[str, AnswerAction]:
+        """Whether each answer accepted, declined, or cancelled its request."""
+        return answer_actions(params.input_responses)
+
+    @abstractmethod
+    def operation_for(self, method: str) -> Operation | None: ...
+
+    @abstractmethod
+    def method_for(self, operation: Operation) -> str | None: ...
+
+    def encode(
+        self, call: Call, registry: RegistryProtocol, outcome: Value | NeedsInput | Failure
+    ) -> Mapping[str, Any]:
+        """Encode a final response, identically for JSON, SSE, and stdio."""
+        match outcome:
+            case Value():
+                return self.encode_value(call, registry, outcome.result)
+            case NeedsInput():
+                return self.encode_input_required(call, registry, outcome)
+            case Failure():
+                return self.encode_failure(call.id, outcome)
+
+    @abstractmethod
+    def encode_value(
+        self, call: Call, registry: RegistryProtocol, result: BaseModel
+    ) -> Mapping[str, Any]: ...
+
+    def encode_input_required(
+        self, call: Call, registry: RegistryProtocol, out: NeedsInput
+    ) -> Mapping[str, Any]:
+        raise NotImplementedError(f"{self.version} cannot carry MRTR")
+
+    def encode_failure(self, call_id: Any, failure: Failure) -> Mapping[str, Any]:
+        code, _ = self.FAILURE_MAP[failure.kind]
+        return ErrorResponse(
+            id=call_id, error=ErrorBody(code=code, message=failure.message, data=failure.data)
+        ).wire()
+
+    @property
+    def carries_state(self) -> bool:
+        """Client-held state must be sealed on output and verified on return."""
+        return self.can_ask or self.asks_in_arguments
+
+    def http_status(self, failure: Failure) -> int:
+        return self.FAILURE_MAP[failure.kind][1]
+
+    def client_headers(
+        self,
+        method: str,
+        name: str | None = None,
+        params: Mapping[str, Any] | None = None,
+        tool: ToolDef | None = None,
+    ) -> Mapping[str, str]:
+        """Required HTTP headers; `name` identifies the tool, resource, or prompt."""
+        return {}
+
+    def client_handshake_params(self, client: ClientProfile) -> Params:
+        """Params for `initialize` or `server/discover`."""
+        return Params()
+
+    def client_decorate_params(self, params: Params, client: ClientProfile) -> Params:
+        """Apply revision-specific metadata before sending a request."""
+        return params
+
+    def client_input_requests(
+        self, result: Mapping[str, Any]
+    ) -> tuple[Mapping[str, InputRequest], Any] | None:
+        """Return input requests and retry state, or None. Stream-pushed requests bypass this."""
+        return None
+
+    def capabilities(self, registry: RegistryProtocol) -> Mapping[str, Any]:
+        """Capabilities shared by all supported revisions."""
+        caps: dict[str, Any] = {}
+        if registry.tools:
+            caps["tools"] = {"listChanged": True}
+        if registry.resources_fixed or registry.resources_templated:
+            caps["resources"] = {"listChanged": True, "subscribe": True}
+        if registry.prompts:
+            caps["prompts"] = {"listChanged": True}
+        if registry.completer is not None:
+            caps["completions"] = {}
+        caps["logging"] = {}
+        return caps
+
+    @abstractmethod
+    def describe_server(self, registry: RegistryProtocol, call: Call) -> BaseModel:
+        """Negotiate the requested legacy revision from `call.params.protocol_version`."""
+
+    @abstractmethod
+    def describe_tool(self, spec: ToolSpec) -> ToolDef | None: ...
+
+    def describe_resource(self, spec: ResourceSpec) -> ResourceDef | ResourceTemplateDef | None:
+        """Resource definitions are shared across revisions."""
+        return spec.definition if spec.definition is not None else spec.template
+
+    def describe_prompt(self, spec: PromptSpec) -> PromptDef | None:
+        """Prompt definitions are shared across revisions."""
+        return spec.definition
+
+    #: MRTR: return questions, then retry with answers.
+    can_ask: ClassVar[bool] = False
+    #: Push questions on the active stream; receive answers in a separate POST.
+    can_push_ask: ClassVar[bool] = False
+    #: Pre-elicitation fallback: exchange questions and answers through tool calls.
+    asks_in_arguments: ClassVar[bool] = False
+    #: Whether a progress notification may carry a human-readable `message`.
+    #: It arrived in 2025-03-26.
+    progress_message: ClassVar[bool] = True
+    allows_batch: ClassVar[bool] = False
+    #: Negotiate once via initialize; retain the revision and capabilities in a session.
+    has_handshake: ClassVar[bool] = False

aiohttp_tiny_mcp/auth.py

@@ -0,0 +1,129 @@
+"""Bearer-token verification for an OAuth protected MCP resource."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Iterable, Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Any, Protocol, runtime_checkable
+from urllib.parse import urlsplit
+
+WELL_KNOWN = "/.well-known/oauth-protected-resource"
+
+
+@dataclass(frozen=True, slots=True)
+class Principal:
+    """Identity and claims returned by a token verifier."""
+
+    subject: str | None = None
+    client_id: str = ""
+    issuer: str | None = None
+    scopes: frozenset[str] = frozenset()
+    expires_at: float | None = None
+    claims: Mapping[str, Any] = field(default_factory=dict)
+
+    def holds(self, wanted: Iterable[str]) -> frozenset[str]:
+        """Return required scopes absent from this principal."""
+        return frozenset(wanted) - self.scopes
+
+    @property
+    def expired(self) -> bool:
+        return self.expires_at is not None and self.expires_at < time.time()
+
+    @property
+    def identity(self) -> str:
+        """Return an issuer-qualified subject or client identifier."""
+        if self.subject:
+            return f"{self.issuer or ''}|{self.subject}"
+        return f"{self.issuer or ''}|client:{self.client_id}"
+
+
+@runtime_checkable
+class TokenVerifier(Protocol):
+    """Verify a bearer token for this resource."""
+
+    async def verify(self, token: str) -> Principal | None: ...
+
+
+class Unauthorized(Exception):
+    """Authentication or authorization failed."""
+
+    def __init__(self, error: str, description: str, status: int = 401) -> None:
+        super().__init__(description)
+        self.error = error
+        self.description = description
+        self.status = status
+
+
+@dataclass(frozen=True)
+class Authorization:
+    """Configuration for an OAuth protected resource server."""
+
+    verifier: TokenVerifier
+    resource: str
+    authorization_servers: Sequence[str] = ()
+    scopes_supported: Sequence[str] | None = None
+    required_scopes: Sequence[str] = ()
+    resource_name: str | None = None
+    documentation: str | None = None
+    bind_sessions: bool = True
+    namespace_from_token: bool = True
+
+    @property
+    def metadata_path(self) -> str:
+        """Return this resource's RFC 9728 metadata path."""
+        path = urlsplit(self.resource).path.rstrip("/")
+        return f"{WELL_KNOWN}{path}"
+
+    def metadata(self) -> dict[str, Any]:
+        """Build this resource's RFC 9728 metadata document."""
+        found: dict[str, Any] = {"resource": self.resource}
+        if self.authorization_servers:
+            found["authorization_servers"] = list(self.authorization_servers)
+        if self.scopes_supported is not None:
+            found["scopes_supported"] = list(self.scopes_supported)
+        if self.resource_name:
+            found["resource_name"] = self.resource_name
+        if self.documentation:
+            found["resource_documentation"] = self.documentation
+        found["bearer_methods_supported"] = ["header"]
+        return found
+
+    def challenge(self, refusal: Unauthorized) -> str:
+        """Build a Bearer challenge with a metadata URL."""
+        parts = [
+            f'error="{refusal.error}"',
+            f'error_description="{refusal.description}"',
+            f'resource_metadata="{self.metadata_url}"',
+        ]
+        return "Bearer " + ", ".join(parts)
+
+    @property
+    def metadata_url(self) -> str:
+        split = urlsplit(self.resource)
+        return f"{split.scheme}://{split.netloc}{self.metadata_path}"
+
+    async def principal(self, authorization: str | None) -> Principal:
+        """Verify an Authorization header and return its principal."""
+        if not authorization or not authorization.lower().startswith("bearer "):
+            raise Unauthorized("invalid_request", "authorization required")
+        found = await self.verifier.verify(authorization[len("bearer ") :].strip())
+        if found is None or found.expired:
+            raise Unauthorized("invalid_token", "the token is not valid for this resource")
+        missing = found.holds(self.required_scopes)
+        if missing:
+            raise Unauthorized(
+                "insufficient_scope",
+                f"missing scope: {', '.join(sorted(missing))}",
+                status=403,
+            )
+        return found
+
+
+__all__ = [
+    "WELL_KNOWN",
+    "Authorization",
+    "Principal",
+    "TokenVerifier",
+    "Unauthorized",
+]

aiohttp_tiny_mcp/client.py

@@ -0,0 +1,111 @@
+"""HTTP transport for BaseClient. See stdio_client.py for the stdio transport."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import AsyncIterator, Callable, Mapping
+from typing import Any
+
+import aiohttp
+
+from .adapter import Adapter
+from .client_base import BaseClient, Elicitor
+from .models import Implementation
+from .sse import read_sse
+
+ANSWER_METHOD = "elicitation/create"
+
+NOTIFICATIONS_METHOD = "notifications/message"
+
+BASE_HEADERS = {"Content-Type": "application/json", "Accept": "application/json, text/event-stream"}
+
+
+async def frames(resp: aiohttp.ClientResponse) -> AsyncIterator[dict[str, Any]]:
+    """Yield JSON or SSE messages immediately; waiting for EOF would deadlock pushed questions."""
+    if resp.content_type != "text/event-stream":
+        yield await resp.json(content_type=None)
+        return
+    async for event in read_sse(resp):
+        if event.data:
+            yield json.loads(event.data)
+
+
+class Client(BaseClient):
+    def __init__(
+        self,
+        base_url: str,
+        adapter: Adapter,
+        *,
+        client_info: Implementation | None = None,
+        session: aiohttp.ClientSession | 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.base_url = base_url
+        self.session = session
+        self.owns_session = session is None
+        self.session_id: str | None = None
+
+    async def __aenter__(self) -> Client:
+        if self.owns_session:
+            self.session = aiohttp.ClientSession()
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        if self.owns_session and self.session is not None:
+            await self.session.close()
+
+    def headers(
+        self, method: str, name: str | None = None, params: Any = None, tool: Any = None
+    ) -> dict[str, str]:
+        headers = {
+            **BASE_HEADERS,
+            **self.adapter.client_headers(method, name, params, tool),
+        }
+        if self.session_id is not None:
+            headers["Mcp-Session-Id"] = self.session_id
+        return headers
+
+    async def exchange(
+        self, envelope: dict[str, Any], *, method: str, name: str | None
+    ) -> AsyncIterator[dict[str, Any]]:
+        assert self.session is not None, "use 'async with Client(...) as client:'"
+        tool = self.tool_definitions.get(name) if name is not None else None
+        headers = self.headers(method, name, envelope.get("params"), tool)
+        async with self.session.post(self.base_url, json=envelope, headers=headers) as resp:
+            issued = resp.headers.get("Mcp-Session-Id")
+            if issued:
+                self.session_id = issued
+            async for frame in frames(resp):
+                yield frame
+
+    async def send_notification(self, envelope: dict[str, Any], *, method: str) -> None:
+        assert self.session is not None, "use 'async with Client(...) as client:'"
+        headers = self.headers(method, params=envelope.get("params"))
+        async with self.session.post(self.base_url, json=envelope, headers=headers) as resp:
+            await resp.read()
+
+    async def stream_notifications(self) -> AsyncIterator[dict[str, Any]]:
+        """Open the legacy notification stream with GET; keep it open until cancelled."""
+        assert self.session is not None, "use 'async with Client(...) as client:'"
+        headers = self.headers(NOTIFICATIONS_METHOD)
+        headers["Accept"] = "text/event-stream"
+        async with self.session.get(self.base_url, headers=headers) as resp:
+            resp.raise_for_status()
+            async for frame in frames(resp):
+                yield frame
+
+    async def reply(self, envelope: dict[str, Any]) -> None:
+        """Send a bare JSON-RPC response. The hub routes it to the node waiting for the answer."""
+        assert self.session is not None, "use 'async with Client(...) as client:'"
+        headers = self.headers(ANSWER_METHOD)
+        async with self.session.post(self.base_url, json=envelope, headers=headers) as resp:
+            await resp.read()