ygo74-agent-runtime-mcp 0.1.0__tar.gz

ygo74_agent_runtime_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: ygo74-agent-runtime-mcp
+Version: 0.1.0
+Summary: MCP server hosting for the ygo74 agent runtime: transport, authentication and health
+Requires-Python: >=3.12
+Requires-Dist: ygo74-agent-runtime-security==0.1.0
+Requires-Dist: pydantic>=2.7
+Provides-Extra: http
+Requires-Dist: mcp<2,>=1.24; extra == "http"
+Requires-Dist: starlette>=0.37; extra == "http"
+Requires-Dist: uvicorn[standard]>=0.30; extra == "http"
+Requires-Dist: httpx>=0.27; extra == "http"

ygo74_agent_runtime_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,46 @@
+[build-system]
+requires = ["setuptools>=68", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "ygo74-agent-runtime-mcp"
+version = "0.1.0"
+description = "MCP server hosting for the ygo74 agent runtime: transport, authentication and health"
+requires-python = ">=3.12"
+
+# Hosting a Model Context Protocol *server* - the other side of
+# `ygo74-agent-runtime-agents`' `domains.mcp`, which is the client.
+#
+# It depends on the security distribution and not on the agents one, deliberately:
+# an MCP server has no agent, no conversation and no discovery descriptor, but it
+# has exactly the same question to answer about who is calling. Sharing the
+# authentication model is the point; sharing the agent machinery would be baggage.
+dependencies = [
+  "ygo74-agent-runtime-security==0.1.0",
+  "pydantic>=2.7",
+]
+
+[project.optional-dependencies]
+# Serving a server over streamable HTTP. Stdio needs none of this, which is why it
+# is an extra: a server reached as a child process should not have to install a web
+# stack to be one.
+#
+# The `mcp` upper bound is deliberate - 2.0 moved to `httpx2` and reshaped the
+# transport API. See the agents distribution for the full reason.
+http = [
+  "mcp>=1.24,<2",
+  "starlette>=0.37",
+  "uvicorn[standard]>=0.30",
+  # `McpServerHost.verify_reachable` drives the application in-process, before the
+  # port is opened, to catch a server that would answer its own callers with 421.
+  # Starlette's test client is what runs the lifespan correctly while doing it, and
+  # it needs httpx - which `mcp` already brings in anyway.
+  "httpx>=0.27",
+]
+
+[tool.setuptools.packages.find]
+include = ["ygo74*"]
+namespaces = true
+
+[tool.setuptools.package-data]
+"ygo74.agent_runtime.domains.mcpserver" = ["py.typed"]

ygo74_agent_runtime_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

ygo74_agent_runtime_mcp-0.1.0/ygo74/agent_runtime/domains/mcpserver/host.py

@@ -0,0 +1,319 @@
+"""Hosting a Model Context Protocol server over HTTP.
+
+Over stdio an MCP server's security argument is the operating system: it is a child
+process, its credential never leaves it, and the caller talks to it through a pipe
+nobody else can open. Over HTTP that argument is gone. The pipe becomes a port and
+every process that can reach the port can reach the tools, while nothing else about
+the server changes - same tools, same payloads - which is exactly why the difference
+is easy to miss.
+
+This host is the part that does not change between servers: the authentication
+chain, an open health probe, OAuth discovery, and a start-up check on the one trap
+that costs a production incident to find.
+
+**Why a middleware rather than the SDK's `TokenVerifier`.** The MCP SDK can verify a
+bearer token, and only that. An API key in ``x-api-key``, a Basic credential, a
+Kerberos ticket - none is expressible through it. Running the runtime's
+:class:`RequestAuthenticator` as ASGI middleware is what lets one authentication
+model serve an agent and an MCP server instead of two models drifting apart.
+
+The authenticated caller is attached to the request scope but is **not** yet the
+authority on what a tool operates upon: tools still take the subject they act for as
+an argument. Making the authenticated identity authoritative is the next piece of
+work, and this host is shaped so that it does not have to be undone first.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, Any
+
+from ygo74.agent_runtime.domains.auth.auth_errors import AuthenticationError
+from ygo74.agent_runtime.domains.auth.authentication_policy import (
+    AuthenticationMode,
+    AuthenticationPolicy,
+)
+from ygo74.agent_runtime.domains.auth.jwt_authenticator import JwtAuthenticator
+from ygo74.agent_runtime.domains.mcpserver.http_binding import (
+    HEALTH_PATH,
+    McpHttpBinding,
+)
+from ygo74.agent_runtime.domains.mcpserver.protected_resource import (
+    PROTECTED_RESOURCE_PATH,
+    ProtectedResource,
+)
+from ygo74.agent_runtime.domains.mcpserver.server_errors import (
+    McpServerConfigurationError,
+    McpServerUnreachableError,
+)
+
+if TYPE_CHECKING:  # pragma: no cover - imported for typing only
+    from starlette.applications import Starlette
+
+# The scope key the authenticated caller is published under. Named rather than
+# inlined because the next piece of work - making that identity authoritative over
+# what a tool operates upon - reads it.
+AUTH_CONTEXT_KEY = "ygo74.auth_context"
+
+_logger = logging.getLogger(__name__)
+
+
+class McpServerHost:
+    """Serves an MCP application to callers that prove who they are.
+
+    Args:
+        policy: Which authentication schemes this server accepts. There is no
+            default: serving everyone is a decision, and
+            :meth:`AuthenticationPolicy.anonymous` is how it is said.
+        binding: Where the server listens and what callers reach it at.
+        resource_url: The canonical URL of this server, required in JWT mode so it
+            can name itself as an OAuth resource. Ignored otherwise.
+        scopes: Scopes a client should request, when the deployment requires any.
+    """
+
+    def __init__(
+        self,
+        *,
+        policy: AuthenticationPolicy,
+        binding: McpHttpBinding | None = None,
+        resource_url: str = "",
+        scopes: tuple[str, ...] = (),
+    ) -> None:
+        self._policy = policy
+        self._binding = binding or McpHttpBinding()
+        self._authenticator = policy.build()
+        self._resource = self._protected_resource(policy, resource_url, scopes)
+
+    @property
+    def binding(self) -> McpHttpBinding:
+        """Where this server listens."""
+        return self._binding
+
+    @property
+    def protected_resource(self) -> ProtectedResource | None:
+        """The OAuth metadata this server publishes, when it publishes any."""
+        return self._resource
+
+    def application(self, tools: Starlette) -> Starlette:
+        """Wrap an MCP application with authentication, health and discovery.
+
+        ``tools`` is what ``FastMCP.streamable_http_app()`` returns. The host adds
+        routes rather than replacing them, so a server keeps whatever else it
+        exposes.
+        """
+        from starlette.middleware.base import BaseHTTPMiddleware
+        from starlette.requests import Request
+        from starlette.responses import JSONResponse
+        from starlette.routing import Route
+
+        async def health(_request: Request) -> JSONResponse:
+            return JSONResponse({"status": "ok"})
+
+        async def metadata(_request: Request) -> JSONResponse:
+            # Only reachable when a resource was configured, because the route is
+            # only added then. A 404 elsewhere is the honest answer: this server
+            # implements no OAuth flow.
+            assert self._resource is not None
+            return JSONResponse(self._resource.metadata())
+
+        async def guard(request: Request, call_next: Any) -> Any:
+            if self._is_open(request.url.path):
+                return await call_next(request)
+
+            try:
+                context = self._authenticator.authenticate(dict(request.headers))
+            except AuthenticationError:
+                return self._refusal(request.url.path)
+            except Exception as failure:  # noqa: BLE001 - translated, not swallowed
+                # An authenticator a host wrote itself. The built-in schemes turn a
+                # malformed credential into an AuthenticationError, but Basic,
+                # Kerberos or whatever a deployment actually has is arbitrary code
+                # on the request path, and an unauthenticated caller able to raise
+                # inside the process holding the credential is a log-flood vector on
+                # the one surface meant to be hard.
+                #
+                # Failing closed is the whole translation: a scheme that could not
+                # decide is a scheme that did not authenticate.
+                _logger.warning(
+                    "authenticator %s raised %s; refusing the request",
+                    type(self._authenticator).__name__,
+                    type(failure).__name__,
+                )
+                return self._refusal(request.url.path)
+
+            request.scope[AUTH_CONTEXT_KEY] = context
+            return await call_next(request)
+
+        tools.router.routes.append(Route(HEALTH_PATH, health, methods=["GET"]))
+        if self._resource is not None:
+            tools.router.routes.append(Route(PROTECTED_RESOURCE_PATH, metadata, methods=["GET"]))
+        tools.add_middleware(BaseHTTPMiddleware, dispatch=guard)
+        return tools
+
+    def verify_reachable(self, transport_security: object | None) -> None:
+        """Refuse to serve a server that would reject its own callers.
+
+        ``FastMCP`` derives a DNS-rebinding allow-list from the bind address at
+        construction and never revisits it, then enforces it *inside* the streamable
+        HTTP handler. A server built with the default address therefore answers every
+        request carrying a service name in ``Host`` with 421 - after authentication,
+        before any tool, with the health probe still green because the probe never
+        reaches that handler.
+
+        The allow-list is read rather than probed. A synthetic request cannot find
+        this: the only route that enforces the rule is the one this host has just
+        put an authentication guard in front of, so a probe would be refused at the
+        door and learn nothing. Reading the configuration is also a better error -
+        it can say which host was expected and which were allowed.
+        """
+        allowed = self._allowed_hosts(transport_security)
+        if allowed is None:
+            return
+
+        public_host = self._binding.public_host
+        if any(_host_matches(public_host, pattern) for pattern in allowed):
+            return
+
+        raise McpServerUnreachableError(
+            f"this server would answer 421 to a request for host {public_host!r}: its DNS-rebinding "
+            f"allow-list is {sorted(allowed)}, derived from a bind address that does not include it. "
+            "FastMCP freezes that allow-list at construction, so pass the real bind address to the "
+            "constructor rather than assigning to settings afterwards"
+        )
+
+    def serve(self, server: object) -> None:
+        """Verify, wrap, then serve until stopped.
+
+        Takes the ``FastMCP`` server rather than its application, because the
+        allow-list that decides reachability lives in its settings and is gone by the
+        time the application exists.
+        """
+        import uvicorn
+
+        settings = getattr(server, "settings", None)
+        self.verify_reachable(getattr(settings, "transport_security", None))
+
+        application = self.application(server.streamable_http_app())  # type: ignore[attr-defined]
+        _logger.info(
+            "serving MCP over HTTP on %s:%s as %s - %s",
+            self._binding.host,
+            self._binding.port,
+            self._binding.public_host,
+            self._policy.describe(),
+        )
+        uvicorn.run(application, host=self._binding.host, port=self._binding.port)
+
+    @staticmethod
+    def _allowed_hosts(transport_security: object | None) -> list[str] | None:
+        """The hosts a server accepts, or None when it accepts every host.
+
+        ``None`` covers both "no transport security" and "protection switched off",
+        which is what FastMCP produces for any non-loopback bind address.
+        """
+        if transport_security is None:
+            return None
+        if not getattr(transport_security, "enable_dns_rebinding_protection", False):
+            return None
+        return list(getattr(transport_security, "allowed_hosts", []) or [])
+
+    def _is_open(self, path: str) -> bool:
+        """Whether a path is reachable without a credential.
+
+        Compared exactly, not by prefix: a probe an orchestrator can call and a
+        metadata document a client needs before it has a token are the only two, and
+        `/healthzextra` is not either of them.
+
+        A plain comparison, deliberately. Constant time buys nothing here - both
+        paths are published constants, not secrets - and `hmac.compare_digest`
+        raises on non-ASCII `str`, which an ASGI server hands over verbatim after
+        percent-decoding. That would turn any unauthenticated request for `/%C3%A9`
+        into a 500 and a traceback in the log of a credential-holding process: the
+        exact log-flood vector this guard exists to close, arriving through the
+        guard itself.
+        """
+        return path in self._open_paths()
+
+    def _open_paths(self) -> tuple[str, ...]:
+        """Paths reachable without a credential.
+
+        The metadata path is open whether or not this server publishes it. When it
+        does, a client must be able to read it before it has a token; when it does
+        not, routing answers 404 - which is the honest "I am not an OAuth resource
+        server". Guarding it instead would answer 401, and a client probing for
+        OAuth support would read that as "there is a flow here, you just need a
+        credential".
+        """
+        return (HEALTH_PATH, PROTECTED_RESOURCE_PATH)
+
+    def _refusal(self, path: str) -> Any:
+        """Answer a caller that could not prove itself.
+
+        No detail about what was wrong: which part failed is information a guesser
+        can use, and the operator has the server log.
+
+        The path is quoted before it is logged. It is attacker-controlled and
+        percent-decoded by the server, so a request for `/%0AINFO:%20all%20clear`
+        would otherwise write a second, forged line into the same log.
+        """
+        from starlette.responses import JSONResponse
+
+        _logger.warning("refused an unauthenticated request to %r", path)
+        headers = {} if self._resource is None else {"WWW-Authenticate": self._resource.challenge()}
+        return JSONResponse({"error": "unauthorized"}, status_code=401, headers=headers)
+
+    @staticmethod
+    def _protected_resource(
+        policy: AuthenticationPolicy,
+        resource_url: str,
+        scopes: tuple[str, ...],
+    ) -> ProtectedResource | None:
+        """Build the OAuth metadata, when this server is an OAuth resource server."""
+        if policy.mode is not AuthenticationMode.JWT:
+            return None
+
+        if not resource_url.strip():
+            raise McpServerConfigurationError(
+                "serving JWT-authenticated MCP requires resource_url: a resource server that "
+                "cannot name itself cannot be discovered, and a client has no way to learn "
+                "which issuer to authenticate against"
+            )
+
+        issuer = _issuer_of(policy)
+        if not issuer:
+            raise McpServerConfigurationError(
+                "serving JWT-authenticated MCP requires an issuer in the validation config: "
+                "without one there is no authorization server to advertise"
+            )
+
+        return ProtectedResource(resource_url.rstrip("/"), issuer, scopes)
+
+
+def _issuer_of(policy: AuthenticationPolicy) -> str:
+    """Read the issuer out of the policy's JWT authenticator."""
+    for authenticator in policy.authenticators:
+        config = getattr(authenticator, "config", None) if isinstance(authenticator, JwtAuthenticator) else None
+        if config is not None and config.issuer:
+            return str(config.issuer)
+    return ""
+
+
+def _host_matches(host: str, pattern: str) -> bool:
+    """Whether a host satisfies an allow-list entry, as FastMCP decides it.
+
+    Its rule is an exact match, or a pattern ending in ``:*`` whose base the host
+    carries followed by a colon. Nothing else - no ``*`` on its own, no ``?``, no
+    character classes.
+
+    Reimplemented rather than approximated with :func:`fnmatch`, which reads a
+    strictly larger grammar and disagrees in both directions. ``["*"]`` is the
+    natural way to write "allow every host" and ``fnmatch`` accepts it, while
+    FastMCP refuses every request - green at boot, 421 for every caller, which is
+    precisely the incident this check exists to prevent. In the other direction
+    ``fnmatch`` reads ``[::1]`` as a character class and refuses a correctly
+    configured IPv6 deployment.
+    """
+    if host == pattern:
+        return True
+    if not pattern.endswith(":*"):
+        return False
+    return host.startswith(pattern[:-1])

ygo74_agent_runtime_mcp-0.1.0/ygo74/agent_runtime/domains/mcpserver/http_binding.py

@@ -0,0 +1,70 @@
+"""Where an MCP server listens, and what it calls itself.
+
+Two addresses, and conflating them is what produced the worst defect this package
+was written to prevent.
+
+The **bind address** is which interfaces the process accepts connections on. In a
+container that is every interface, because the container's network namespace is the
+boundary; what keeps that safe is the credential, not the address.
+
+The **public host** is the name callers use. It is what arrives in the ``Host``
+header, what an OAuth resource identifier is built from, and what a DNS-rebinding
+allow-list has to contain. A wildcard bind is not a name anything can address, so it
+cannot serve as one.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+HEALTH_PATH = "/healthz"
+
+# Addresses that mean "every interface" rather than naming one. A caller cannot put
+# any of them in a `Host` header, so they cannot stand in for a public name.
+_WILDCARDS = frozenset({"0.0.0.0", "::", "[::]", ""})
+
+_LOOPBACK = "localhost"
+
+
+@dataclass(frozen=True, slots=True)
+class McpHttpBinding:
+    """The address an MCP server is served on.
+
+    Args:
+        host: The interface to bind. ``0.0.0.0`` is normal in a container.
+        port: The port to bind.
+        public_host: The authority callers reach the server at, including the port
+            when it is not implied - ``mail-mcp-gmail:9100``. Defaults to the bind
+            address, which is right on a workstation and wrong behind a service
+            name, so a deployment that has one should say it.
+    """
+
+    host: str = _LOOPBACK
+    port: int = 9100
+    public_host: str = ""
+
+    def __post_init__(self) -> None:
+        if not self.public_host:
+            object.__setattr__(self, "public_host", self._derived_public_host())
+
+    def _derived_public_host(self) -> str:
+        """Guess the authority when the deployment did not name one.
+
+        A wildcard bind falls back to loopback rather than to itself: guessing wrong
+        towards something unusable is better than minting an authority that resolves
+        nowhere and silently ends up in an OAuth resource identifier.
+
+        An IPv6 literal is bracketed, because ``::1:9100`` is not an authority - the
+        colons of the address and the colon of the port are indistinguishable, and
+        both a ``Host`` header and a URL need ``[::1]:9100``.
+        """
+        if self.host in _WILDCARDS:
+            return f"{_LOOPBACK}:{self.port}"
+
+        host = f"[{self.host}]" if _is_ipv6_literal(self.host) else self.host
+        return f"{host}:{self.port}"
+
+
+def _is_ipv6_literal(host: str) -> bool:
+    """Whether a bind address is a bare IPv6 literal needing brackets."""
+    return ":" in host and not host.startswith("[")

ygo74_agent_runtime_mcp-0.1.0/ygo74/agent_runtime/domains/mcpserver/protected_resource.py

@@ -0,0 +1,54 @@
+"""OAuth 2.1 protected-resource metadata, so a client can find the issuer itself.
+
+The MCP specification expects an HTTP server to behave as an OAuth 2.1 resource
+server: answer a credential-less request with a ``WWW-Authenticate`` header naming
+where its metadata lives, and publish that metadata at a well-known path (RFC 9728).
+
+That is the whole difference between a server a generic MCP client - VS Code,
+Claude Desktop - can connect to by URL alone, and one that needs a human to be told
+out of band which realm to authenticate against.
+
+The metadata is published **unauthenticated**, necessarily: a client cannot present
+a token before learning where to obtain one. It discloses only what a client needs
+to start the flow, and nothing about the tools behind it.
+
+Only published in JWT mode. A server authenticating an API key does not implement
+an OAuth flow, and advertising one would be a lie a client would then act on.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+PROTECTED_RESOURCE_PATH = "/.well-known/oauth-protected-resource"
+
+
+@dataclass(frozen=True, slots=True)
+class ProtectedResource:
+    """What this server is, and which authorization server issues for it.
+
+    Args:
+        resource_url: The canonical URL of this MCP server, which is also its RFC
+            8707 resource indicator - the audience a token must carry.
+        issuer: The authorization server tokens come from.
+        scopes: Scopes a client should ask for, when the deployment requires any.
+    """
+
+    resource_url: str
+    issuer: str
+    scopes: tuple[str, ...] = ()
+
+    def metadata(self) -> dict[str, object]:
+        """The RFC 9728 document."""
+        document: dict[str, object] = {
+            "resource": self.resource_url,
+            "authorization_servers": [self.issuer],
+            "bearer_methods_supported": ["header"],
+        }
+        if self.scopes:
+            document["scopes_supported"] = list(self.scopes)
+        return document
+
+    def challenge(self) -> str:
+        """The ``WWW-Authenticate`` value that points a client at the metadata."""
+        return f'Bearer resource_metadata="{self.resource_url}{PROTECTED_RESOURCE_PATH}"'

ygo74_agent_runtime_mcp-0.1.0/ygo74/agent_runtime/domains/mcpserver/server_errors.py

@@ -0,0 +1,28 @@
+"""Failures that stop an MCP server from being served at all.
+
+Both of these are deliberately fatal, and both exist because the alternative is a
+server that runs and looks healthy while doing the wrong thing. A process that
+refuses to start is a cheap, loud failure somebody fixes in a minute; a process
+serving its tools to an unauthenticated network, or answering every real request
+with 421 behind a green health probe, is neither cheap nor loud.
+"""
+
+from __future__ import annotations
+
+
+class McpServerError(RuntimeError):
+    """Base of the failures raised while standing an MCP server up."""
+
+
+class McpServerConfigurationError(McpServerError):
+    """Raised when the server cannot be served safely as configured."""
+
+
+class McpServerUnreachableError(McpServerError):
+    """Raised when the server would refuse the callers it was deployed for.
+
+    Found the hard way: ``FastMCP`` derives its DNS-rebinding allow-list from the
+    bind address at construction and never revisits it, so a server built with the
+    default address answers every request carrying a service name in ``Host`` with
+    421 - after authentication, before any tool, with the health probe still green.
+    """

ygo74_agent_runtime_mcp-0.1.0/ygo74/agent_runtime/domains/mcpserver/settings.py

@@ -0,0 +1,220 @@
+"""Reading an MCP server's authentication out of the environment.
+
+The schemes live in :mod:`ygo74.agent_runtime.domains.auth`; this is only the
+mapping from environment variables onto them. It sits in the library rather than in
+each server because two servers in one deployment growing two different answers to
+"who may call me" is how a weaker one appears without anybody deciding it should.
+
+The prefix is what distinguishes them - ``MAIL_MCP_``, ``WIKI_MCP_`` - exactly as
+``AgentHttpSettings.from_env`` distinguishes two agents in one process.
+
+Variables, for a prefix of ``MAIL_MCP_``:
+
+``MAIL_MCP_AUTH_MODE``
+    ``none``, ``api_key`` or ``jwt``.
+``MAIL_MCP_HTTP_TOKEN``
+    The shared secret, for ``api_key``.
+``MAIL_MCP_OIDC_ISSUER`` and ``MAIL_MCP_OIDC_AUDIENCE``
+    The issuer to validate against, for ``jwt``.
+``MAIL_MCP_RESOURCE_URL``
+    What the server calls itself as an OAuth resource, required for ``jwt``.
+
+**The mode may be inferred, but never inferred as anonymous.** A deployment that set
+a token has said something unambiguous, and breaking every running container to make
+it say the same thing twice would buy nothing. A deployment that set nothing has said
+nothing, and gets a refusal rather than an open port.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from typing import Self
+
+from ygo74.agent_runtime.domains.auth.apikey_authenticator import (
+    StaticApiKeyUserResolver,
+)
+from ygo74.agent_runtime.domains.auth.auth_context import ResolvedUser
+from ygo74.agent_runtime.domains.auth.authentication_policy import (
+    AuthenticationConfigurationError,
+    AuthenticationMode,
+    AuthenticationPolicy,
+)
+from ygo74.agent_runtime.domains.auth.jwt_authenticator import (
+    DiscoveredJwksKeyResolver,
+    JwksKeyResolver,
+    JwtKeyResolver,
+    JwtValidationConfig,
+)
+
+MODE_SUFFIX = "AUTH_MODE"
+TOKEN_SUFFIX = "HTTP_TOKEN"
+ISSUER_SUFFIX = "OIDC_ISSUER"
+AUDIENCE_SUFFIX = "OIDC_AUDIENCE"
+RESOURCE_SUFFIX = "RESOURCE_URL"
+JWKS_SUFFIX = "JWKS_URL"
+ROLES_CLAIM_SUFFIX = "ROLES_CLAIM_PATH"
+
+# Symmetric algorithms are refused: HS256 would mean the server holds the same key
+# that signs tokens, which turns a resource server into an issuer by accident.
+ASYMMETRIC_ALGORITHMS = ("RS256", "RS384", "RS512", "ES256", "ES384")
+
+
+@dataclass(frozen=True, slots=True)
+class McpServerAuthentication:
+    """The authentication an MCP server was configured with."""
+
+    policy: AuthenticationPolicy
+    resource_url: str = ""
+
+    @classmethod
+    def from_env(
+        cls,
+        prefix: str,
+        *,
+        caller_id: str,
+        environment: dict[str, str] | None = None,
+    ) -> Self:
+        """Read one server's authentication from prefixed environment variables.
+
+        Args:
+            prefix: What distinguishes this server's variables - ``MAIL_MCP_``.
+            caller_id: Who the shared secret authenticates, in ``api_key`` mode. A
+                deployment, not a person: the secret says "you are the agent I was
+                deployed with" and nothing about whose data is read.
+            environment: Read instead of the process environment, for tests.
+
+        Raises:
+            AuthenticationConfigurationError: nothing was configured, or what was
+                configured is incomplete. Always fatal: a server that started anyway
+                would be its tools on an open port, and the only sign of it would be
+                the absence of a line in a log.
+        """
+        source = environment if environment is not None else dict(os.environ)
+        names = _Names(prefix)
+        mode = cls._mode(source, names)
+
+        if mode is AuthenticationMode.NONE:
+            return cls(AuthenticationPolicy.anonymous())
+
+        if mode is AuthenticationMode.API_KEY:
+            return cls(cls._api_key_policy(source, names, caller_id))
+
+        return cls(cls._jwt_policy(source, names), _required(source, names.resource, names.mode, "jwt"))
+
+    @staticmethod
+    def _mode(source: dict[str, str], names: _Names) -> AuthenticationMode:
+        """Which mode was asked for, inferring a scheme but never inferring silence."""
+        declared = source.get(names.mode, "").strip()
+        if declared:
+            return AuthenticationMode.named(declared)
+
+        if source.get(names.token, "").strip():
+            # Unambiguous: a token was configured, so a token is what is checked.
+            return AuthenticationMode.API_KEY
+
+        if source.get(names.issuer, "").strip():
+            return AuthenticationMode.JWT
+
+        raise AuthenticationConfigurationError(
+            f"serving over HTTP requires {names.mode}: this process holds a credential for the "
+            "system behind it, and an unauthenticated port would hand that system to anything "
+            f"that can reach it. Set {names.mode}=api_key with {names.token}, or {names.mode}=jwt "
+            f"with {names.issuer}, or {names.mode}=none if serving everyone really is the intent"
+        )
+
+    @staticmethod
+    def _api_key_policy(source: dict[str, str], names: _Names, caller_id: str) -> AuthenticationPolicy:
+        """Authenticate a shared secret carried in an Authorization header."""
+        secret = source.get(names.token, "").strip()
+        if not secret:
+            raise AuthenticationConfigurationError(
+                f"{names.mode} is 'api_key' but {names.token} is empty: "
+                "there is nothing to check a caller against"
+            )
+
+        return AuthenticationPolicy.api_key(
+            StaticApiKeyUserResolver({secret: ResolvedUser(user_id=caller_id)}),
+            header_name="authorization",
+            scheme="Bearer",
+        )
+
+    @staticmethod
+    def _jwt_policy(source: dict[str, str], names: _Names) -> AuthenticationPolicy:
+        """Validate tokens against the configured issuer.
+
+        The signing keys are *discovered* rather than derived. Appending a path to
+        the issuer only works for one provider; asking the issuer works for all of
+        them. An explicit ``<prefix>JWKS_URL`` still wins, because an operator who
+        names a URL has a reason.
+
+        Without a key resolver the authenticator refuses every token before it ever
+        reaches a signature check - a server that publishes discovery metadata,
+        sends a client to the right realm, and then answers 401 to the valid token
+        it comes back with. It fails closed, which is why nothing catches it except
+        driving a real token through.
+        """
+        issuer = _required(source, names.issuer, names.mode, "jwt")
+        audience = source.get(names.audience, "").strip()
+        explicit_jwks = source.get(names.jwks, "").strip()
+        resolver: JwtKeyResolver = (
+            JwksKeyResolver(jwks_url=explicit_jwks)
+            if explicit_jwks
+            else DiscoveredJwksKeyResolver(issuer=issuer)
+        )
+
+        return AuthenticationPolicy.jwt(
+            JwtValidationConfig(
+                issuer=issuer,
+                audience=audience or None,
+                allowed_algorithms=ASYMMETRIC_ALGORITHMS,
+                key_resolver=resolver,
+                roles_claim_path=source.get(names.roles_claim, "").strip() or None,
+            )
+        )
+
+
+@dataclass(frozen=True, slots=True)
+class _Names:
+    """The variable names of one prefix."""
+
+    prefix: str
+
+    @property
+    def mode(self) -> str:
+        return f"{self.prefix}{MODE_SUFFIX}"
+
+    @property
+    def token(self) -> str:
+        return f"{self.prefix}{TOKEN_SUFFIX}"
+
+    @property
+    def issuer(self) -> str:
+        return f"{self.prefix}{ISSUER_SUFFIX}"
+
+    @property
+    def audience(self) -> str:
+        return f"{self.prefix}{AUDIENCE_SUFFIX}"
+
+    @property
+    def resource(self) -> str:
+        return f"{self.prefix}{RESOURCE_SUFFIX}"
+
+    @property
+    def jwks(self) -> str:
+        return f"{self.prefix}{JWKS_SUFFIX}"
+
+    @property
+    def roles_claim(self) -> str:
+        return f"{self.prefix}{ROLES_CLAIM_SUFFIX}"
+
+
+def _required(source: dict[str, str], variable: str, mode_variable: str, mode: str) -> str:
+    """Read a variable the chosen mode cannot work without."""
+    value = source.get(variable, "").strip()
+    if not value:
+        raise AuthenticationConfigurationError(
+            f"{mode_variable} is {mode!r} but {variable} is empty: "
+            "a resource server that cannot name itself or its issuer cannot be discovered"
+        )
+    return value

ygo74_agent_runtime_mcp-0.1.0/ygo74_agent_runtime_mcp.egg-info/PKG-INFO

@@ -0,0 +1,12 @@
+Metadata-Version: 2.4
+Name: ygo74-agent-runtime-mcp
+Version: 0.1.0
+Summary: MCP server hosting for the ygo74 agent runtime: transport, authentication and health
+Requires-Python: >=3.12
+Requires-Dist: ygo74-agent-runtime-security==0.1.0
+Requires-Dist: pydantic>=2.7
+Provides-Extra: http
+Requires-Dist: mcp<2,>=1.24; extra == "http"
+Requires-Dist: starlette>=0.37; extra == "http"
+Requires-Dist: uvicorn[standard]>=0.30; extra == "http"
+Requires-Dist: httpx>=0.27; extra == "http"

ygo74_agent_runtime_mcp-0.1.0/ygo74_agent_runtime_mcp.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+pyproject.toml
+ygo74/agent_runtime/domains/mcpserver/host.py
+ygo74/agent_runtime/domains/mcpserver/http_binding.py
+ygo74/agent_runtime/domains/mcpserver/protected_resource.py
+ygo74/agent_runtime/domains/mcpserver/py.typed
+ygo74/agent_runtime/domains/mcpserver/server_errors.py
+ygo74/agent_runtime/domains/mcpserver/settings.py
+ygo74_agent_runtime_mcp.egg-info/PKG-INFO
+ygo74_agent_runtime_mcp.egg-info/SOURCES.txt
+ygo74_agent_runtime_mcp.egg-info/dependency_links.txt
+ygo74_agent_runtime_mcp.egg-info/requires.txt
+ygo74_agent_runtime_mcp.egg-info/top_level.txt

ygo74_agent_runtime_mcp-0.1.0/ygo74_agent_runtime_mcp.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

ygo74_agent_runtime_mcp-0.1.0/ygo74_agent_runtime_mcp.egg-info/requires.txt

@@ -0,0 +1,8 @@
+ygo74-agent-runtime-security==0.1.0
+pydantic>=2.7
+
+[http]
+mcp<2,>=1.24
+starlette>=0.37
+uvicorn[standard]>=0.30
+httpx>=0.27

ygo74_agent_runtime_mcp-0.1.0/ygo74_agent_runtime_mcp.egg-info/top_level.txt

@@ -0,0 +1 @@
+ygo74