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

aiohttp_mcp_server/__init__.py

@@ -0,0 +1,249 @@
+"""MCP (Model Context Protocol) server support for aiohttp."""
+
+from collections.abc import Callable, Collection
+from typing import Literal
+
+from aiohttp import web
+from yarl import URL
+
+from ._auth import TOKEN_INFO_KEY, Authorization, ScopeMatcher, TokenInfo, TokenValidator
+from ._auth_server import (
+    AuthenticateRequest,
+    CheckCredentials,
+    ConsentContext,
+    LocalAuthorization,
+    RenderConsent,
+)
+from ._content import (
+    AudioContent,
+    Content,
+    EmbeddedResource,
+    Icon,
+    ImageContent,
+    ResourceLink,
+    TextContent,
+)
+from ._elicitation import (
+    BooleanSchema,
+    Elicitation,
+    ElicitResult,
+    EnumSchema,
+    FieldSchema,
+    FormElicitation,
+    InputRequired,
+    IntegerSchema,
+    MultiSelectEnumSchema,
+    NumberSchema,
+    SecureFormElicitation,
+    StringSchema,
+    URLElicitation,
+)
+from ._handlers import Doc, Header
+from ._prompts import Message, Prompt, PromptHandler, PromptRegistry, PromptResult
+from ._protocol import PROTOCOL_VERSIONS
+from ._resources import (
+    Resource,
+    ResourceContents,
+    ResourceHandler,
+    ResourceRegistry,
+    ResourceResult,
+)
+from ._secure_form import FormContext, RenderForm
+from ._server import MCPServer
+from ._tools import RateLimiter, Tool, ToolError, ToolHandler, ToolRegistry, ToolResult
+from ._transport import MCPRequest
+from ._validators import IntrospectionAuthorization
+
+__version__ = "0.1.0"
+
+# https://github.com/sphinx-doc/sphinx/issues/6495
+#: Protocol revisions implemented, newest first.
+PROTOCOL_VERSIONS: tuple[str, ...]  # type: ignore[no-redef]
+#: The :class:`~aiohttp.web.Request` key under which the validated
+#: :class:`TokenInfo` is stored for authenticated requests.
+TOKEN_INFO_KEY: web.RequestKey[TokenInfo]  # type: ignore[no-redef]
+
+__all__ = (
+    "PROTOCOL_VERSIONS",
+    "TOKEN_INFO_KEY",
+    "AudioContent",
+    "AuthenticateRequest",
+    "Authorization",
+    "BooleanSchema",
+    "CheckCredentials",
+    "ConsentContext",
+    "Content",
+    "Doc",
+    "ElicitResult",
+    "Elicitation",
+    "EmbeddedResource",
+    "EnumSchema",
+    "FieldSchema",
+    "FormContext",
+    "FormElicitation",
+    "Header",
+    "Icon",
+    "ImageContent",
+    "InputRequired",
+    "IntegerSchema",
+    "IntrospectionAuthorization",
+    "LocalAuthorization",
+    "MCPRequest",
+    "MCPServer",
+    "Message",
+    "MultiSelectEnumSchema",
+    "NumberSchema",
+    "Prompt",
+    "PromptHandler",
+    "PromptRegistry",
+    "PromptResult",
+    "RateLimiter",
+    "RenderConsent",
+    "RenderForm",
+    "Resource",
+    "ResourceContents",
+    "ResourceHandler",
+    "ResourceLink",
+    "ResourceRegistry",
+    "ResourceResult",
+    "ScopeMatcher",
+    "SecureFormElicitation",
+    "StringSchema",
+    "TextContent",
+    "TokenInfo",
+    "TokenValidator",
+    "Tool",
+    "ToolError",
+    "ToolHandler",
+    "ToolRegistry",
+    "ToolResult",
+    "URLElicitation",
+    "setup",
+)
+
+
+def setup(
+    app: web.Application,
+    *,
+    name: str = "aiohttp-mcp-server",
+    version: str = __version__,
+    path: str = "/mcp",
+    title: str | None = None,
+    description: str | None = None,
+    website_url: str | None = None,
+    instructions: str | None = None,
+    include_server_info: bool = True,
+    discover_ttl: float = 3600.0,
+    discover_cache_scope: Literal["public", "private"] = "public",
+    allowed_origins: Collection[str] | Callable[[str], bool] | None = None,
+    sse_keepalive: float = 15.0,
+    authorization: Authorization | None = None,
+    well_known_routes: bool = True,
+    prompts: PromptRegistry | None = None,
+    resources: ResourceRegistry | None = None,
+    tools: ToolRegistry | None = None,
+    state_secret: bytes | None = None,
+    authenticate_request: AuthenticateRequest | None = None,
+    render_form: RenderForm | None = None,
+) -> MCPServer:
+    """Serve an MCP endpoint at ``path`` on ``app``.
+
+    :param name: Server name, reported as ``serverInfo`` and by ``server/discover``.
+    :param version: Version of the server implementation.
+    :param path: path for the MCP endpoint.
+    :param title: Optional human-readable display name.
+    :param description: Optional human-readable description of the server.
+    :param website_url: Optional URL of the server's website.
+    :param instructions: Optional natural-language guidance for LLMs, returned
+        by ``server/discover``. For most harnesses, these instructions and a list
+        of tool names is likely the only thing the LLM will see at session start.
+    :param include_server_info: Include ``serverInfo`` in every result's
+        ``_meta`` (recommended by the specification).
+    :param discover_ttl: Client-side cache lifetime of the ``server/discover``
+        result, in seconds.
+    :param discover_cache_scope: Whether shared intermediaries may cache the
+        ``server/discover`` result (``"public"``) or only the requesting
+        client (``"private"``).
+    :param allowed_origins: Hosts allowed to appear in the ``Origin`` header
+        (compared against the header's parsed host), or a callable receiving
+        that host and replacing the policy. Defaults to the host of
+        ``authorization``'s resource when authorization is configured, and to
+        ``localhost`` otherwise. Behind a reverse proxy,
+        make sure the forwarded scheme and host are applied to requests
+        (e.g. with :mod:`aiohttp_remotes`) so built URLs are correct.
+    :param sse_keepalive: Interval in seconds between SSE keep-alive comments
+        on response streams; also bounds how quickly a client disconnect is
+        detected.
+    :param authorization: Enable authorization using :brand:`OAuth` tokens.
+    :param well_known_routes: Register the well-known discovery
+        documents on ``app``.  Set to :data:`False` when ``app`` is mounted as a
+        sub-application - those documents must be served from the origin
+        root, so call :meth:`Authorization.register_well_known` on the
+        root application instead.
+    :param prompts: The registry of prompts to serve. Enables the ``prompts`` capability.
+    :param resources: The registry of resources to serve. Enables the
+        ``resources`` capability, including per-resource update notifications
+        via :meth:`.MCPServer.resource_updated`.
+    :param tools: The registry of tools to serve. Enables the ``tools`` capability.
+    :param state_secret: Key used for signing when using :meth:`.MCPRequest.elicit`.
+        Random when omitted, which invalidates in-flight requests on restart and
+        breaks them across workers.
+    :param authenticate_request: Returns the authenticated browser user for a
+        request, enabling :class:`SecureFormElicitation` pages to verify who
+        opened them. Not needed with :class:`LocalAuthorization`, whose login
+        session is used by default.
+    :param render_form: Replaces the hosted secure-form page. Receives the
+        request and a :class:`FormContext`. The page it returns must satisfy
+        the form contract documented there.
+    """
+    if authorization is not None:
+        authorization._bind(path)
+    if allowed_origins is None:
+        if authorization is not None:
+            host = URL(authorization._resource).host
+            assert host is not None  # enforced by Authorization
+            allowed_origins = (host,)
+        else:
+            allowed_origins = ("localhost", "127.0.0.1", "::1")
+    server = MCPServer(
+        name=name,
+        version=version,
+        title=title,
+        description=description,
+        website_url=website_url,
+        instructions=instructions,
+        include_server_info=include_server_info,
+        discover_ttl=discover_ttl,
+        discover_cache_scope=discover_cache_scope,
+        allowed_origins=allowed_origins,
+        sse_keepalive=sse_keepalive,
+        authorization=authorization,
+        prompts=prompts,
+        resources=resources,
+        tools=tools,
+        state_secret=state_secret,
+    )
+    app.router.add_post(path, server._handle)
+    if authorization is not None:
+        authorization._register_routes(app)
+        if well_known_routes:
+            authorization.register_well_known(app)
+
+    # Secure-form elicitation pages, when a browser identity is available.
+    form_identity = authenticate_request
+    if isinstance(authorization, LocalAuthorization):
+        if form_identity is None:
+            form_identity = authorization._subject
+        server._form_login = lambda r: authorization._login_redirect(r.rel_url)
+    if authorization is not None and form_identity is not None:
+        server._form_identity = form_identity
+        if render_form is not None:
+            server._form_render = render_form
+        resource = app.router.add_resource(f"{path}/elicit/{{ticket}}")
+        resource.add_route("GET", server._handle_form)
+        resource.add_route("POST", server._handle_form)
+        server._form_resource = resource
+        if isinstance(authorization, LocalAuthorization):
+            authorization._extra_return_prefixes.append(lambda: str(resource.url_for(ticket="")))
+    app.on_shutdown.append(server._shutdown)
+    return server

aiohttp_mcp_server/_auth.py

@@ -0,0 +1,291 @@
+"""Authorization: OAuth 2.1 resource-server behaviour for the MCP endpoint."""
+
+import re
+import sys
+from collections.abc import Awaitable, Callable, Collection, Iterable, Mapping, Sequence
+from dataclasses import dataclass, field
+from typing import Final, NoReturn, NotRequired, TypedDict
+
+if sys.version_info >= (3, 12):
+    from typing import TypeAliasType
+else:
+    from typing_extensions import TypeAliasType
+
+from aiohttp import hdrs, web
+from yarl import URL
+
+from ._protocol import INVALID_REQUEST, MCPError, error_envelope
+
+# https://datatracker.ietf.org/doc/html/rfc9728#name-well-known-uri-registry
+_WELL_KNOWN: Final = "/.well-known/oauth-protected-resource"
+
+# b64token syntax of RFC 6750 section 2.1 (token68 of RFC 9110).
+_B64TOKEN: Final = re.compile(r"[A-Za-z0-9\-._~+/]+=*")
+# scope-token syntax of RFC 6749 section 3.3.
+_SCOPE_TOKEN: Final = re.compile(r"[\x21\x23-\x5b\x5d-\x7e]+")
+
+_LOOPBACK: Final = frozenset({"127.0.0.1", "::1", "localhost"})
+
+
+def _secure_url(url: URL) -> bool:
+    return url.scheme == "https" or (url.scheme == "http" and url.host in _LOOPBACK)
+
+
+
+@dataclass(frozen=True, slots=True)
+class TokenInfo:
+    """Validated access-token information produced by a :data:`TokenValidator`."""
+
+    #: The scopes granted to the token, from the ``scope`` claim.
+    scopes: frozenset[str] = frozenset()
+    #: Who the token was issued to (the ``sub`` claim), when known.
+    subject: str | None = None
+    #: All claims returned by the validator, for application-specific checks
+    #: (e.g. ``email``); keys are validator-dependent.
+    claims: Mapping[str, object] = field(default_factory=dict)
+
+
+# TODO(PY312): use the `type` statement.
+ScopeMatcher = TypeAliasType("ScopeMatcher", Callable[[str, frozenset[str]], bool])
+TokenValidator = TypeAliasType(
+    "TokenValidator", Callable[[str, web.Request], Awaitable["TokenInfo | None"]]
+)
+
+TOKEN_INFO_KEY: Final = web.RequestKey("TOKEN_INFO_KEY", TokenInfo)
+
+
+# TODO(PY315): closed=True
+class ProtectedResourceMetadata(TypedDict):
+    """The RFC 9728 metadata subset emitted by this library."""
+
+    resource: str
+    authorization_servers: Sequence[str]
+    bearer_methods_supported: Sequence[str]
+    scopes_supported: NotRequired[Sequence[str]]
+    resource_name: NotRequired[str]
+    resource_documentation: NotRequired[str]
+
+
+class _AuthError(Exception):
+    """Carries the finished HTTP response for a failed authentication."""
+
+    def __init__(self, response: web.Response) -> None:
+        super().__init__(response.reason)
+        self.response = response
+
+
+class Authorization:
+    """Authorization configuration for an MCP endpoint.
+
+    :param validator: Asynchronous callable validating a presented bearer token. The
+        callback will receive the token and the request and must return a
+        :class:`TokenInfo` object or :data:`None` if the token is not valid.
+    :param resource: Base URL this MCP server is reachable at: scheme and
+        host (and optional port), plus the mount prefix when served from a
+        sub-application — e.g. ``"https://mcp.mydomain.example"`` or
+        ``"https://mcp.mydomain.example/api"``. Must be absolute ``http(s)``,
+        canonical, without query or fragment. The canonical resource
+        identifier that clients request tokens for is completed by
+        :func:`~aiohttp_mcp_server.setup`, which appends the MCP endpoint path — so
+        the identifier always matches the endpoint it is served on.
+    :param auth_servers: Issuer identifiers of at least one authorization
+        server from which clients can obtain access tokens.
+    :param default_scopes: The initial set of scopes advertised to a client.
+        Generally a client will start by requesting an access token with all
+        of these scopes. It is recommended to advertise only enough scopes for
+        basic functionality. Clients will re-authenticate to acquire new scopes
+        when needed for additional functionality.
+    :param scope_matcher: A callback which receives the requested scope and the
+        user's current scopes and returns True if the requested scope is
+        allowed, False otherwise. This can be used to implement scope hierarchy.
+        Defaults to an exact match (:code:`requested in user_scopes`).
+    :param resource_name: Optional human-readable name for display purposes.
+    :param resource_documentation: Optional URL of developer documentation.
+    """
+
+    _resource: str
+    _metadata_path: str
+    _metadata_url: str
+    _metadata: ProtectedResourceMetadata
+
+    def __init__(
+        self,
+        validator: TokenValidator,
+        *,
+        resource: str,
+        auth_servers: Sequence[str],
+        default_scopes: Iterable[str] = (),
+        scope_matcher: ScopeMatcher | None = None,
+        resource_name: str | None = None,
+        resource_documentation: str | None = None,
+    ) -> None:
+        # https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization#canonical-server-uri
+        resource = resource.rstrip("/")
+        resource_url = URL(resource)
+        if (
+            not resource_url.is_absolute()
+            or resource_url.scheme not in {"http", "https"}
+            or resource_url.host is None
+            or resource_url.query_string
+            or resource_url.fragment
+        ):
+            raise ValueError(
+                "resource must be an absolute http(s) URL without query or fragment"
+            )
+        if str(resource_url) != resource:
+            raise ValueError(f"resource must be in canonical form: {str(resource_url)!r}")
+        if "%" in resource:
+            raise ValueError("percent-encoded resource paths are not supported")
+        self._origin: Final = str(resource_url.origin())
+        if not resource.startswith(self._origin):
+            # e.g. userinfo, which origin() strips.
+            raise ValueError("resource must not contain userinfo")
+        if not auth_servers:
+            raise ValueError("at least one authorization server is required")
+        for issuer in auth_servers:
+            issuer_url = URL(issuer)
+            if not issuer_url.is_absolute() or not _secure_url(issuer_url):
+                # https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization/security-considerations#communication-security
+                raise ValueError(f"authorization server must be an HTTPS URL: {issuer!r}")
+
+        self._default_scopes = tuple(default_scopes)
+        for scope in self._default_scopes:
+            if not _SCOPE_TOKEN.fullmatch(scope):
+                raise ValueError(f"invalid scope token: {scope!r}")
+
+        self._validator = validator
+        self._base: Final = resource
+        self._scope_matcher: ScopeMatcher = (
+            scope_matcher if scope_matcher is not None else lambda s, scopes: s in scopes
+        )
+        self._auth_servers = tuple(auth_servers)
+        self._resource_name = resource_name
+        self._resource_documentation = resource_documentation
+
+    def _bind(self, path: str) -> None:
+        """Complete the resource identifier with the MCP endpoint ``path``."""
+        resource = self._base + (path.rstrip("/") if path != "/" else "")
+        if hasattr(self, "_resource"):
+            if self._resource != resource:
+                raise RuntimeError(
+                    f"authorization is already bound to {self._resource!r}; "
+                    "use a separate Authorization instance per endpoint"
+                )
+            return
+        if str(URL(resource)) != resource or "%" in resource:
+            raise ValueError(f"endpoint path is not canonical: {path!r}")
+        self._resource = resource
+
+        # RFC 9728 path-insertion relative to the resource identifier:
+        # https://mcp.example.com/mcp -> /.well-known/oauth-protected-resource/mcp
+        self._metadata_path = _WELL_KNOWN + resource[len(self._origin):]
+        self._metadata_url = self._origin + self._metadata_path
+
+        self._metadata = {
+            "resource": self._resource,
+            "authorization_servers": self._auth_servers,
+            # https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization#token-requirements
+            "bearer_methods_supported": ("header",),
+        }
+        if self._default_scopes:
+            self._metadata["scopes_supported"] = self._default_scopes
+        if self._resource_name is not None:
+            self._metadata["resource_name"] = self._resource_name
+        if self._resource_documentation is not None:
+            self._metadata["resource_documentation"] = self._resource_documentation
+
+    def _register_routes(self, app: web.Application) -> None:
+        """Register any routes and lifecycle hooks on app."""
+
+    def register_well_known(self, app: web.Application) -> None:
+        """Register the well-known discovery documents.
+
+        These must be served from the origin root (:rfc:`9728`/:rfc:`8414`
+        path-inserted well-known URIs): call on the root application.
+        """
+        if not hasattr(self, "_resource"):
+            raise RuntimeError("setup() must be called before register_well_known()")
+        app.router.add_get(self._metadata_path, self._handle_metadata)
+
+    async def _handle_metadata(self, request: web.Request) -> web.Response:
+        """GET handler for the RFC 9728 well-known metadata document."""
+        return web.json_response(self._metadata)
+
+    def _challenge(
+        self,
+        error: str | None,
+        description: str | None,
+        scopes: Collection[str] | None = None,
+    ) -> str:
+        # https://datatracker.ietf.org/doc/html/rfc6750#section-3
+        # https://datatracker.ietf.org/doc/html/rfc9728#name-www-authenticate-response
+        params = [f'resource_metadata="{self._metadata_url}"']
+        if error is not None:
+            params.append(f'error="{error}"')
+        if description is not None:
+            params.append(f'error_description="{description}"')
+        if effective := (scopes or self._default_scopes):
+            params.append(f'scope="{" ".join(effective)}"')
+        return "Bearer " + ", ".join(params)
+
+    def _fail(
+        self,
+        status: int,
+        error: str | None = None,
+        description: str | None = None,
+        scopes: Collection[str] | None = None,
+    ) -> NoReturn:
+        # https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization#error-handling
+        body = error_envelope(MCPError(INVALID_REQUEST, description or "Unauthorized"))
+        response = web.json_response(
+            body,
+            status=status,
+            headers={hdrs.WWW_AUTHENTICATE: self._challenge(error, description, scopes)},
+        )
+        raise _AuthError(response)
+
+    async def _authenticate(
+        self,
+        request: web.Request,
+        scopes: Collection[str] | None = None,
+    ) -> TokenInfo:
+        """Validate the request's bearer token and the operation's scopes.
+
+        Raises ``_AuthError`` with the appropriate challenge when the token is
+        missing/invalid (401), malformed (400), or lacks one of ``scopes``
+        (403).  ``scopes`` is the current operation's scope requirements when
+        known.
+        """
+        # https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization#token-requirements
+        if "access_token" in request.query:
+            self._fail(
+                400,
+                "invalid_request",
+                "Access tokens must not be sent in the URI query string",
+                scopes=scopes,
+            )
+
+        # TODO(aiohttp4): Update this for HeadersDictProxy
+        headers = request.headers.getall(hdrs.AUTHORIZATION, ())
+        if not headers:
+            self._fail(401, scopes=scopes)
+        if len(headers) > 1:
+            self._fail(
+                400, "invalid_request", "Multiple Authorization headers", scopes=scopes
+            )
+        scheme, _, token = headers[0].partition(" ")
+        token = token.strip(" ")
+        if scheme.lower() != "bearer" or not _B64TOKEN.fullmatch(token):
+            self._fail(
+                400, "invalid_request", "Malformed Authorization header", scopes=scopes
+            )
+
+        info = await self._validator(token, request)
+        if info is None:
+            self._fail(
+                401, "invalid_token", "Invalid or expired access token", scopes=scopes
+            )
+        # https://modelcontextprotocol.io/specification/2026-07-28/basic/authorization#runtime-insufficient-scope-errors
+        if scopes and not all(self._scope_matcher(s, info.scopes) for s in scopes):
+            self._fail(403, "insufficient_scope", "Insufficient scope", scopes=scopes)
+        return info