Errored while searching.
;
+} else if (response === undefined) {
+ return Loading...
;
+} else if (!response.found) {
+ return Not found
;
+} else {
+ return {response.value?.toJson() as string}
;
+}
+```
+
+
+
+See [Call your API from
+React](/learn_more/call/from_react) to learn more about how to call methods from
+React.
diff --git a/documentation/docs/library_services/overview.md b/documentation/docs/library_services/overview.md
index 7bcb73b4..751712db 100644
--- a/documentation/docs/library_services/overview.md
+++ b/documentation/docs/library_services/overview.md
@@ -8,6 +8,7 @@ import TabItem from "@theme/TabItem";
The standard library uses Reboot's capabilities to build powerful data structures and APIs for common tasks.
The current libraries are:
+* [Ciphertext](./ciphertext) - Envelope encryption with a revocable wrapping key: encrypt values at rest and crypto-shred them by destroying a single key.
* [PubSub](./pubsub) - A pub/sub implementation that enables you to subscribe and broadcast to topics.
* [Queue](./queue) - A durable queue implementation that allows you to enqueue and dequeue items.
* [OrderedMap](./ordered_map) - A newer implementation of a collection / dictionary / map that may be larger than memory. We recommend using this.
diff --git a/documentation/docs/library_services/pubsub.mdx b/documentation/docs/library_services/pubsub.mdx
index 5a41f12a..00fd0c27 100644
--- a/documentation/docs/library_services/pubsub.mdx
+++ b/documentation/docs/library_services/pubsub.mdx
@@ -30,17 +30,28 @@ To read messages from a subscribed [`Queue`](/library_services/queue), you will
- {personalizedMessage}: {response?.value ?? 0}
-
- );
-};
-```
-
-#### mcp=None Example
-
-Hide a method from the AI (e.g., for human-only actions):
-
-```python
-# In an application type's Methods():
-# Only callable from the React UI, not by the AI.
-confirm_dangerous_action=Writer(
- request=ConfirmRequest,
- response=None,
- description="Confirm a dangerous action.",
- mcp=None,
-),
-```
-
-#### List State Patterns
-
-For application types with list-based state (items, entries,
-messages, etc.):
-
-- Define helper Model types as standalone classes (e.g.,
- `class Item(Model)`) — NOT nested on the application type
-- Use `list[Item]` in the state with `default_factory=list`
-- Add CRUD Writers: add, remove, toggle, reorder as needed
-- Each Writer validates indices before mutating
-- The `reorder` pattern uses `pop` + `insert`
-- In the servicer, import helpers standalone:
- `from
-
- );
- }
-
- return (
- loading...
-
-
- );
-};
-```
-
-### `web/ui/
-
-
-
- syncing...
-
-
-
-
-
- {value}
-
- {trend && (
- {trendIcon}
- )}
-
+
+
+
+
diff --git a/reboot/aio/auth/oauth_providers.py b/reboot/aio/auth/oauth_providers.py
index 784ac9ed..e05613e2 100644
--- a/reboot/aio/auth/oauth_providers.py
+++ b/reboot/aio/auth/oauth_providers.py
@@ -3,12 +3,25 @@
from __future__ import annotations
import aiohttp
+import hashlib
+import hmac
import jwt
+import os
from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from jinja2 import Template
from log.log import get_logger, log_at_most_once_per
-from typing import NewType
+from rbt.std.oauth.v1.oauth_rbt import OAuthTokens
+from reboot.aio.exceptions import InputError
+from reboot.aio.http import PythonWebFramework
+from reboot.crypto import root_keys
+from reboot.run_environments import running_rbt_dev
+from starlette.requests import Request
+from starlette.responses import HTMLResponse
+from typing import Any, NewType, Optional
from ulid import ULID
-from urllib.parse import urlencode
+from urllib.parse import urlencode, urlparse, urlunparse
logger = get_logger(__name__)
@@ -17,6 +30,58 @@
_DEFAULT_ACCESS_TOKEN_TTL_SECONDS = 24 * 60 * 60 # 24 hours.
+@dataclass(frozen=True)
+class ExchangeResult:
+ """The result of exchanging an identity provider authorization code:
+ the resolved user ID and, when the provider captures them, the
+ provider's tokens.
+ """
+ user_id: UserId
+ # The provider's tokens, present only when the provider was
+ # constructed with `store_tokens=True`; `None` otherwise, so apps
+ # that don't opt in never carry these secrets around.
+ tokens: Optional[OAuthTokens]
+
+
+def _expires_at_from_expires_in(expires_in: Any) -> Optional[int]:
+ """Convert a token endpoint's `expires_in` (seconds from now) into an
+ absolute epoch-seconds expiry, or `None` if absent or unparsable.
+ """
+ try:
+ now = int(datetime.now(timezone.utc).timestamp())
+ return now + int(expires_in)
+ except (TypeError, ValueError):
+ return None
+
+
+def _scopes_from_response(granted: Any, requested: list[str]) -> list[str]:
+ """Parse the granted `scope` string from a token response, falling
+ back to the scopes we requested when the provider doesn't echo
+ them.
+ """
+ if isinstance(granted, str) and granted.strip():
+ return granted.split()
+ return requested
+
+
+def origin_from_request(request: Request) -> str:
+ """
+ Derive the server's origin (`scheme://host`) from request headers.
+
+ Respects `X-Forwarded-Proto` and `X-Forwarded-Host` when behind a
+ reverse proxy.
+ """
+ scheme = request.headers.get(
+ "x-forwarded-proto",
+ request.url.scheme,
+ )
+ host = request.headers.get(
+ "x-forwarded-host",
+ request.headers.get("host", "localhost"),
+ )
+ return f"{scheme}://{host}"
+
+
class OAuthProvider(ABC):
"""
Base class for identity providers.
@@ -54,9 +119,10 @@ async def exchange_code(
self,
code: str,
redirect_uri: str,
- ) -> UserId:
- """Exchange an identity provider authorization code for
- a user ID.
+ ) -> ExchangeResult:
+ """Exchange an identity provider authorization code for a user
+ ID (and, for providers that capture them, the provider's
+ tokens).
Args:
code: The authorization code received from the
@@ -67,28 +133,109 @@ async def exchange_code(
"""
raise NotImplementedError()
+ @property
+ def stores_tokens(self) -> bool:
+ """Whether this provider captures and persists the identity
+ provider's tokens. `False` by default; providers that support it
+ flip this on when constructed with `store_tokens=True`.
+ """
+ return False
+
+ @property
+ def token_service_id(self) -> str:
+ """The `OAuthTokenManager` state id this provider's tokens are
+ stored under — names the external third-party service (e.g.
+ "google.com"), so application code can read them back via
+ `OAuthTokenManager.ref(...)`. Providers that set `stores_tokens`
+ must override this.
+ """
+ raise NotImplementedError()
+
+ def mount_routes(self, http: PythonWebFramework.HTTP) -> None:
+ """
+ Optional hook to register provider-specific HTTP routes.
+
+ Default: no extra routes.
+ """
+
+ def validate(self) -> None:
+ """
+ Optional hook to verify the provider's configuration.
+
+ Called when this provider will be used in this process (i.e.
+ it's been selected). Subclasses override to fail fast on missing
+ or invalid configuration; the default is a no-op.
+ """
+
class RegisteredOAuthProvider(OAuthProvider):
"""
Base class for providers that use pre-registered client credentials.
-
+
These providers require developers to go through some manual
registration flow once, which produces a `client_id` and
`client_secret` that we need to know.
"""
- def __init__(self, *, client_id: str, client_secret: str):
+ # The scope this provider always requests, on top of any the
+ # developer adds, because identity resolution depends on it (e.g.
+ # `openid` for Google, `read:user` for GitHub). Subclasses set this.
+ _REQUIRED_SCOPE: str = ""
+
+ def __init__(
+ self,
+ *,
+ # `client_id`/`client_secret` are typed `Optional` so a
+ # production-only provider can still be constructed in dev
+ # processes where it is present but won't be used.
+ client_id: Optional[str],
+ client_secret: Optional[str],
+ # Extra OAuth scopes to request on top of `_REQUIRED_SCOPE`, so
+ # the app can call the provider's API on the user's behalf.
+ scopes: Optional[list[str]] = None,
+ # When `True`, capture the provider's access/refresh tokens
+ # during the code exchange and persist them (encrypted) so the
+ # app can use them later to call the provider's API. Off by
+ # default — opting in requires the `ciphertext` library and
+ # `REBOOT_CRYPTO_ROOT_KEYS`.
+ store_tokens: bool = False,
+ ):
+
super().__init__()
- if not client_id:
- raise ValueError(
- f"{type(self).__name__} requires a non-empty `client_id`."
- )
- if not client_secret:
- raise ValueError(
- f"{type(self).__name__} requires a non-empty `client_secret`."
- )
self._client_id = client_id
self._client_secret = client_secret
+ self._extra_scopes = scopes or []
+ self._store_tokens = store_tokens
+
+ @property
+ def stores_tokens(self) -> bool:
+ return self._store_tokens
+
+ def _requested_scopes(self) -> list[str]:
+ """The full scope list: the required base scope plus the
+ developer's extras (deduplicated, base scope first).
+ """
+ scopes = [self._REQUIRED_SCOPE]
+ for scope in self._extra_scopes:
+ if scope not in scopes:
+ scopes.append(scope)
+ return scopes
+
+ def validate(self) -> None:
+ if not self._client_id:
+ raise InputError(
+ reason=(
+ f"{type(self).__name__} requires a non-empty "
+ "`client_id`."
+ ),
+ )
+ if not self._client_secret:
+ raise InputError(
+ reason=(
+ f"{type(self).__name__} requires a non-empty "
+ "`client_secret`."
+ ),
+ )
class Google(RegisteredOAuthProvider):
@@ -101,6 +248,15 @@ class Google(RegisteredOAuthProvider):
_AUTHORIZATION_ENDPOINT = "https://accounts.google.com/o/oauth2/v2/auth"
_TOKEN_ENDPOINT = "https://oauth2.googleapis.com/token"
+ # `openid` is the minimum OIDC scope; gives us an ID token with the
+ # `sub` claim (the user's ID).
+ _REQUIRED_SCOPE = "openid"
+
+ @property
+ def token_service_id(self) -> str:
+ # Mirrors `reboot.std.oauth.v1.oauth.GOOGLE`.
+ return "google.com"
+
def authorization_url(
self,
state: str,
@@ -110,10 +266,13 @@ def authorization_url(
"client_id": self._client_id,
"redirect_uri": redirect_uri,
"response_type": "code",
- # `openid` is the minimum OIDC scope; gives us an ID token
- # with the `sub` claim (the user's ID).
- "scope": "openid",
+ "scope": " ".join(self._requested_scopes()),
"state": state,
+ # `offline` asks Google for a refresh token. Google only
+ # returns one on the *first* consent (not on later sign-ins),
+ # so the token store carries the existing refresh token
+ # forward rather than us forcing the consent screen every
+ # time with `prompt=consent` (see `OAuthServer._store_oauth_tokens`).
"access_type": "offline",
}
return f"{self._AUTHORIZATION_ENDPOINT}?{urlencode(params)}"
@@ -122,9 +281,9 @@ async def exchange_code(
self,
code: str,
redirect_uri: str,
- ) -> UserId:
+ ) -> ExchangeResult:
"""
- Exchange the Google auth code for user ID.
+ Exchange the Google auth code for a user ID (and tokens).
"""
data = {
"code": code,
@@ -171,18 +330,72 @@ async def exchange_code(
user_id = decoded.get("sub")
if user_id is None:
raise ValueError("Google ID token did not contain a 'sub' claim.")
- return UserId(user_id)
+ return ExchangeResult(
+ user_id=UserId(user_id),
+ tokens=self._tokens_from_response(token_response),
+ )
+
+ def _tokens_from_response(
+ self,
+ token_response: dict,
+ ) -> Optional[OAuthTokens]:
+ """Build an `OAuthTokens` from a Google token endpoint response,
+ or `None` when token storage isn't enabled or no access token came
+ back.
+ """
+ if not self._store_tokens:
+ return None
+ access_token = token_response.get("access_token")
+ if access_token is None:
+ return None
+ return OAuthTokens(
+ access_token=access_token,
+ refresh_token=token_response.get("refresh_token"),
+ expires_at=_expires_at_from_expires_in(
+ token_response.get("expires_in")
+ ),
+ scopes=_scopes_from_response(
+ token_response.get("scope"),
+ self._requested_scopes(),
+ ),
+ )
class GitHub(RegisteredOAuthProvider):
"""
GitHub OAuth provider (plain OAuth 2.0).
+
+ Note on refresh tokens (relevant only with `store_tokens=True`):
+ whether GitHub issues a `refresh_token` is entirely a property of how
+ the credentials were created, not anything we can request:
+
+ - A classic **OAuth App** never issues a refresh token. Its access
+ token simply does not expire (so there is nothing to refresh, and
+ `OAuthTokens.refresh_token` / `expires_at` come back unset).
+ - A **GitHub App** issues a `refresh_token` (and an expiring access
+ token) only when "Expire user authorization tokens" is enabled in
+ the app's settings. With that opt-out left disabled, its
+ user-to-server token behaves like the OAuth App's — no refresh
+ token.
+
+ So to get refresh tokens, register a GitHub App and enable expiring
+ user tokens; `client_id`/`client_secret` are then that app's
+ credentials. We store whatever the token endpoint returns either way.
"""
_AUTHORIZATION_ENDPOINT = "https://github.com/login/oauth/authorize"
_TOKEN_ENDPOINT = "https://github.com/login/oauth/access_token"
_USER_API = "https://api.github.com/user"
+ # `read:user`: minimum scope needed to call `GET /user` and obtain
+ # the numeric user ID.
+ _REQUIRED_SCOPE = "read:user"
+
+ @property
+ def token_service_id(self) -> str:
+ # Mirrors `reboot.std.oauth.v1.oauth.GITHUB`.
+ return "github.com"
+
def authorization_url(
self,
state: str,
@@ -191,9 +404,7 @@ def authorization_url(
params = {
"client_id": self._client_id,
"redirect_uri": redirect_uri,
- # `read:user`: minimum scope needed to call `GET /user` and
- # obtain the numeric user ID.
- "scope": "read:user",
+ "scope": " ".join(self._requested_scopes()),
"state": state,
}
return f"{self._AUTHORIZATION_ENDPOINT}?{urlencode(params)}"
@@ -202,9 +413,9 @@ async def exchange_code(
self,
code: str,
redirect_uri: str,
- ) -> UserId:
+ ) -> ExchangeResult:
"""
- Exchange the GitHub auth code for user ID.
+ Exchange the GitHub auth code for a user ID (and tokens).
"""
# Since GitHub isn't an OpenID provider (only plain OAuth), we
# must first POST to the token endpoint for an access token,
@@ -248,7 +459,249 @@ async def exchange_code(
user_id = user_info.get("id")
if user_id is None:
raise ValueError("GitHub user API did not return an 'id' field.")
- return UserId(str(user_id))
+ return ExchangeResult(
+ user_id=UserId(str(user_id)),
+ tokens=self._tokens_from_response(token_response),
+ )
+
+ def _tokens_from_response(
+ self,
+ token_response: dict,
+ ) -> Optional[OAuthTokens]:
+ """Build an `OAuthTokens` from a GitHub token endpoint response,
+ or `None` when token storage isn't enabled. Classic GitHub OAuth
+ App tokens don't expire and carry no refresh token; GitHub Apps
+ issue expiring tokens with a `refresh_token` and `expires_in`.
+ """
+ if not self._store_tokens:
+ return None
+ access_token = token_response.get("access_token")
+ if access_token is None:
+ return None
+ return OAuthTokens(
+ access_token=access_token,
+ refresh_token=token_response.get("refresh_token"),
+ expires_at=_expires_at_from_expires_in(
+ token_response.get("expires_in")
+ ),
+ scopes=_scopes_from_response(
+ token_response.get("scope"),
+ self._requested_scopes(),
+ ),
+ )
+
+
+class Auth0(RegisteredOAuthProvider):
+ """
+ Auth0 OAuth provider (OpenID Connect).
+
+ Auth0 is an identity broker: a single Auth0 application can let
+ users sign in through any of the connections you enable in the
+ Auth0 dashboard (Google, GitHub, username/password, enterprise
+ SSO, …). To the app it's one OIDC provider — the per-user choice
+ of login method happens upstream, in Auth0, not here.
+
+ All endpoints live under your tenant domain (e.g.
+ `your-tenant.us.auth0.com`), so unlike `Google`/`GitHub` this
+ provider takes a `domain`. Register a "Regular Web Application" in
+ Auth0 and add Reboot's callback (`Who do you want to be?
+pick an identity to log in as
+ {% for account in accounts %} + + {{ account.initial }} + + {{ account.name }} + {{ account.email }} + + + {% endfor %} + +
+
+ );
+ }
+
+ if (items.length === 0) {
+ return (
+ Loading cart...
+
+
+ );
+ }
+
+ return (
+ Shopping Cart
+
+ Your cart is empty. Browse the store to add items!
+
+
+
+ );
+};
diff --git a/reboot/examples/reboot-swag-store/web/ui/cart/index.html b/reboot/examples/reboot-swag-store/web/ui/cart/index.html
new file mode 100644
index 00000000..fb98aa91
--- /dev/null
+++ b/reboot/examples/reboot-swag-store/web/ui/cart/index.html
@@ -0,0 +1,12 @@
+
+
+
+
+
+ Shopping Cart
+ +
+ {items.map((item) => (
+
+
+
+ {item.imageUrl && (
+ 
+ )}
+
+ ))}
+
+
+ {item.name}
+ {item.size && ` (${item.size})`}
+
+ Qty: {item.quantity}
+
+
+ {formatPrice(item.priceCents * item.quantity)}
+
+
+
+
+
+
+ Subtotal
+ {formatPrice(subtotalCents)}
+
+ {couponValid && (
+
+ Coupon discount
+ -{formatPrice(subtotalCents)}
+
+ )}
+
+ Total
+ {formatPrice(totalCents)}
+
+
+
+
+ Shipping Address
+
+
+
+ setName(e.target.value)}
+ onBlur={() => markTouched("name")}
+ aria-invalid={!!errorFor("name")}
+ />
+ {errorFor("name") && (
+
+ {errorFor("name")}
+ )}
+
+ setEmail(e.target.value)}
+ onBlur={() => markTouched("email")}
+ aria-invalid={!!errorFor("email")}
+ />
+ {errorFor("email") && (
+
+ {errorFor("email")}
+ )}
+
+ setAddress1(e.target.value)}
+ onBlur={() => markTouched("address1")}
+ aria-invalid={!!errorFor("address1")}
+ />
+ {errorFor("address1") && (
+
+ setAddress2(e.target.value)}
+ />
+ {errorFor("address1")}
+ )}
+
+
+
+ setCity(e.target.value)}
+ onBlur={() => markTouched("city")}
+ aria-invalid={!!errorFor("city")}
+ />
+ {errorFor("city") && (
+
+ {errorFor("city")}
+ )}
+
+ setStateCode(e.target.value.toUpperCase())}
+ onBlur={() => markTouched("stateCode")}
+ aria-invalid={!!errorFor("stateCode")}
+ maxLength={2}
+ />
+ {errorFor("stateCode") && (
+
+ {errorFor("stateCode")}
+ )}
+
+
+
+ setZipCode(e.target.value)}
+ onBlur={() => markTouched("zipCode")}
+ aria-invalid={!!errorFor("zipCode")}
+ maxLength={10}
+ />
+ {errorFor("zipCode") && (
+
+ {errorFor("zipCode")}
+ )}
+
+ setCountryCode(e.target.value.toUpperCase())}
+ onBlur={() => markTouched("countryCode")}
+ aria-invalid={!!errorFor("countryCode")}
+ maxLength={2}
+ />
+ {errorFor("countryCode") && (
+
+ {errorFor("countryCode")}
+ )}
+
+
+
+
+ {checkoutError && (
+ Coupon Code
+
+ {
+ setCouponCode(e.target.value);
+ setCouponValid(false);
+ setCouponError("");
+ }}
+ />
+
+
+ {couponValid && (
+
+ Coupon applied! Your order is free.
+
+ )}
+ {couponError && {couponError}
}
+ {checkoutError}
+ )}
+
+
+ );
+ }
+
+ if (!response || !response.orderId) {
+ return (
+ Loading order...
+
+
+ );
+ }
+
+ return (
+ Order not found.
+
+
+ );
+};
diff --git a/reboot/examples/reboot-swag-store/web/ui/confirmation/index.html b/reboot/examples/reboot-swag-store/web/ui/confirmation/index.html
new file mode 100644
index 00000000..b3dc71df
--- /dev/null
+++ b/reboot/examples/reboot-swag-store/web/ui/confirmation/index.html
@@ -0,0 +1,12 @@
+
+
+
+
+
+ ✓
+ Order Confirmed!
+Order #{response.orderId.slice(0, 8)}
+{formatDate(response.createdAt)}
+ +
+ {response.items.map((item) => (
+
+
+
+
+ ))}
+
+
+ {item.name}
+ {item.size && ` (${item.size})`}
+
+ x{item.quantity}
+
+
+ {formatPrice(item.priceCents * item.quantity)}
+
+
+
+
+ {response.shippingName && (
+
+ Subtotal
+ {formatPrice(response.subtotalCents)}
+
+
+ Shipping
+ {formatPrice(response.shippingCents)}
+
+
+ Total
+ {formatPrice(response.totalCents)}
+
+ Shipping to {response.shippingName}
+ )} +
+ {displayImage && (
+ 
+ )}
+
+ );
+};
+
+export const StoreApp: FC = () => {
+ const app = useMcpApp();
+ const user = useUser();
+ // The MCP host merges the tool's input arguments into
+ // `toolData`, so a call of `browse_store({"product_ids":
+ // ["abc", "def"]})` lands at `toolData.product_ids`. The
+ // model picks these IDs after reading the catalog from
+ // `list_products`; an empty (or missing) list means show
+ // everything.
+ const toolData = useMcpToolData();
+ const productIds = useMemo
+
+ {product.name}
+{product.description}
+ {hasColors && ( +
+ {colors.map((color) => (
+
+ ))}
+
+ )}
+ {hasSizes && (
+
+ )}
+
+
+ {formatPrice(selectedVariant?.priceCents ?? product.priceCents)}
+
+ onAdd(selectedVariant!.id)}
+ />
+
+
+
+ );
+ }
+
+ const isFiltered = productIds.length > 0;
+
+ return (
+ Loading store...
+
+
+ );
+};
diff --git a/reboot/examples/reboot-swag-store/web/ui/store/index.html b/reboot/examples/reboot-swag-store/web/ui/store/index.html
new file mode 100644
index 00000000..f546ba19
--- /dev/null
+++ b/reboot/examples/reboot-swag-store/web/ui/store/index.html
@@ -0,0 +1,12 @@
+
+
+
+
+
+ Reboot Swag Store
++ {isFiltered + ? `Showing ${products.length} of ${allProducts.length} products` + : "Official Reboot merch"} +
+
+ {products.map((product) => (
+ {
+ const variant = product.variants.find((v) => v.id === variantId);
+ await app?.sendMessage({
+ role: "user",
+ content: [
+ {
+ type: "text",
+ text:
+ `Add to my cart: ` +
+ `product_id="${product.id}", ` +
+ `variant_id="${variantId}", ` +
+ `name="${product.name}", ` +
+ `price_cents=${
+ variant?.priceCents ?? product.priceCents
+ }, ` +
+ `image_url="${variant?.imageUrl || product.imageUrl}", ` +
+ `size="${variant?.size ?? ""}"`,
+ },
+ ],
+ });
+ }}
+ />
+ ))}
+
+
+
+
+
+
+
diff --git a/reboot/mcp/factories.py b/reboot/mcp/factories.py
index 0ff1810c..caadc3af 100644
--- a/reboot/mcp/factories.py
+++ b/reboot/mcp/factories.py
@@ -19,9 +19,8 @@
_init_session_state,
_set_user_id,
)
-from reboot.mcp.proxy import _UI_ASSETS_PREFIX
+from reboot.mcp.request_state import _UI_ASSETS_PREFIX, _request_user_agent
from reboot.mcp.ui import (
- _request_user_agent,
_resolve_dist_path,
_resource_meta,
_ui_tool_cache_bust_info,
@@ -238,8 +237,14 @@ async def reject(reason: str) -> None:
def create_mcp_factory(
*,
server: FastMCP,
- new_session_hooks: Sequence[Callable[[ExternalContext, Optional[str]],
- Awaitable[None]]],
+ new_session_hooks: Sequence[Callable[
+ [ExternalContext, Optional[str]],
+ Awaitable[None],
+ ]],
+ per_request_hooks: Sequence[Callable[
+ [ExternalContext, Optional[str], Request],
+ Awaitable[None],
+ ]] = (),
token_verifier: Optional[Any],
) -> Callable[
[Callable[[Request], Any]],
@@ -253,6 +258,11 @@ def create_mcp_factory(
new_session_hooks: Async callables to invoke when a new
MCP session starts (e.g. to auto-construct state). Arguments
passed: (external_context, user_id_or_none).
+ per_request_hooks: Async callables to invoke on *every*
+ inbound MCP request, regardless of session boundary.
+ Arguments passed: (external_context, user_id_or_none,
+ request) — the Starlette `Request` lets hooks inspect
+ headers (e.g., `x-forwarded-host`).
token_verifier: Optional MCP SDK `TokenVerifier`
(from `mcp.server.auth.provider`). When set, it can reject
requests with missing or expired bearer tokens with an HTTP
@@ -286,7 +296,7 @@ async def mcp_asgi_app(
) -> None:
# Static-asset branch: serve the UI's dist files
# directly from disk for production-mode MCP Apps.
- # The path shape, set by `prod_loader_html`, is
+ # The path shape, set by `cache_busting_iframe_html`, is
# `/mcp<_UI_ASSETS_PREFIX>UI unavailable
+Claude can’t view this UI over a free ngrok tunnel
++ ngrok’s free tier puts a browser interstitial in front of some + requests, which prevents this UI from loading. +
+To view this UI, do any one of:
+-
+
- + Use a paid ngrok plan, or a different tunnel, that doesn’t + inject an interstitial. + +
- + Open the app in a different MCP client — for example ChatGPT, or + MCPJam. These do work over free ngrok. + +
+ {hasMcpTools ? ( + <> + Try this app in a chat client. + + ) : ( + <> + Your API is ready. + + )} +
++ {hasMcpTools ? ( + <> + Only a few more steps to get{" "} + {titleReady ? title : "this Reboot app"} working in + the chat client of your choice. + + ) : ( + <> + {titleReady ? title : "This Reboot app"} is serving + traffic. It doesn't expose any MCP tools yet — here's how to call it + directly. + + )} +
+
+
+
+
+
+ {CONNECTION_LABEL[connectionState]}
+
+
+ {titleReady ? (
+ title
+ ) : (
+
+ )}
+
+ {!titleReady ? (
+ + +
+ ) : description ? ( +{description}
+ ) : ( +
+ Add a description= to your Application(...) for a
+ friendlier intro here.
+
` inside body copy. The dedicated code blocks
+ (`.inline-code`, `.code-block`) opt out by sitting in their own
+ class scope and not matching any of these selectors. */
+p code,
+li code,
+.step__intro code,
+.substep__title code,
+.substep__hint code {
+ background: rgba(16, 55, 97, 0.08);
+ padding: 1px 6px;
+ border-radius: 4px;
+ color: var(--navy);
+ font-size: 0.92em;
+}
+
+/* ---------------- Top nav ---------------- */
+
+.top-nav {
+ max-width: 992px;
+ margin: 0 auto;
+ padding: 32px 32px 0;
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+}
+
+.top-nav__brand {
+ display: flex;
+ align-items: center;
+ gap: 10px;
+ font-size: 15.5px;
+ font-weight: 600;
+ color: var(--navy);
+ letter-spacing: -0.01em;
+}
+
+.top-nav__brand img {
+ height: 20px;
+ width: auto;
+}
+
+.top-nav__divider {
+ color: var(--tan);
+ font-weight: 400;
+}
+
+.top-nav__app-name {
+ color: var(--navy);
+}
+
+.top-nav__actions {
+ display: flex;
+ align-items: center;
+ gap: 8px;
+}
+
+.button {
+ font: inherit;
+ border: 1px solid transparent;
+ border-radius: 999px;
+ padding: 9px 18px;
+ cursor: pointer;
+ font-size: 13.5px;
+ font-weight: 600;
+ letter-spacing: 0.2px;
+ transition: background-color 0.15s ease, border-color 0.15s ease,
+ color 0.15s ease;
+ text-decoration: none;
+ display: inline-flex;
+ align-items: center;
+ gap: 6px;
+}
+
+.button--ghost {
+ background: transparent;
+ color: var(--navy);
+ border-color: transparent;
+}
+.button--ghost:hover {
+ background: rgba(16, 55, 97, 0.08);
+}
+
+.button--outline {
+ background: transparent;
+ color: var(--navy);
+ border-color: var(--navy);
+}
+.button--outline:hover {
+ background: var(--navy);
+ color: var(--cream);
+}
+
+.button--primary {
+ background: var(--navy);
+ color: var(--cream);
+ border-color: var(--navy);
+}
+.button--primary:hover {
+ background: #0c2d57;
+}
+
+.button--small {
+ font-size: 12.5px;
+ padding: 7px 14px;
+}
+
+.button:disabled,
+.button[disabled] {
+ cursor: not-allowed;
+ opacity: 0.45;
+}
+
+/* ---------------- Wizard wrapper + hero ---------------- */
+
+.wizard {
+ max-width: 992px;
+ margin: 0 auto;
+ padding: 24px 32px 96px;
+}
+
+.hero {
+ padding: 48px 0 32px;
+}
+
+.hero__title {
+ margin: 0;
+ font-size: 72px;
+ font-weight: 700;
+ line-height: 1;
+ letter-spacing: -0.036em;
+ color: var(--navy);
+}
+
+.hero__title em,
+.step__title em {
+ font-style: normal;
+ background: var(--highlight);
+ padding: 0 8px;
+ border-radius: 4px;
+ box-decoration-break: clone;
+ -webkit-box-decoration-break: clone;
+}
+
+.hero__subtitle {
+ margin: 20px 0 36px;
+ font-size: 18px;
+ font-weight: 400;
+ line-height: 1.5;
+ color: var(--navy);
+ max-width: 640px;
+}
+
+.app-info {
+ display: flex;
+ align-items: center;
+ justify-content: space-between;
+ gap: 24px;
+ background: var(--surface);
+ border: 1.5px solid var(--navy);
+ border-radius: 14px;
+ padding: 18px 22px;
+ /* Same brand drop-shadow as the picker cards — keeps the page's
+ "block" cards visually consistent. */
+ box-shadow: 6px 6px 0 0 var(--navy);
+}
+
+.app-info__main {
+ min-width: 0;
+}
+
+.app-info__name {
+ font-size: 17px;
+ font-weight: 700;
+ color: var(--navy);
+ margin-bottom: 4px;
+ letter-spacing: -0.005em;
+}
+
+.app-info__description {
+ font-size: 13.5px;
+ font-weight: 400;
+ color: var(--muted);
+ margin: 0;
+}
+
+.app-info__placeholder {
+ font-style: italic;
+ color: var(--tan);
+}
+
+.pill {
+ flex-shrink: 0;
+ display: inline-flex;
+ align-items: center;
+ background: transparent;
+ padding: 0;
+ font-size: 14px;
+ font-weight: 600;
+}
+
+/* App is responding — ✓ glyph and text both in green. */
+.pill--connected {
+ color: var(--success-text, #1f7a52);
+}
+
+/* Reader is (still) trying to (re)connect to the app — ✗ glyph
+ and text both in red so the developer notices the broken
+ state. */
+.pill--connecting {
+ color: #c53030;
+}
+
+/* ---------------- Step cards ---------------- */
+
+.step {
+ display: grid;
+ grid-template-columns: 180px 1fr;
+ column-gap: 48px;
+ border-top: 1.5px solid var(--navy);
+ padding: 64px 0;
+}
+
+.step__index {
+ align-self: start;
+}
+
+.step__number {
+ font-size: 64px;
+ font-weight: 700;
+ color: var(--navy);
+ line-height: 0.9;
+ letter-spacing: -0.031em;
+ font-feature-settings: "tnum" on;
+}
+
+.step__label {
+ margin-top: 12px;
+ font-size: 11.5px;
+ font-weight: 700;
+ color: var(--muted);
+ text-transform: uppercase;
+ letter-spacing: 0.157em;
+}
+
+.step__body {
+ min-width: 0;
+}
+
+.step__title {
+ margin: 0;
+ font-size: 40px;
+ font-weight: 700;
+ line-height: 1.05;
+ letter-spacing: -0.035em;
+ color: var(--navy);
+}
+
+.step__intro {
+ margin: 16px 0 28px;
+ font-size: 15.5px;
+ font-weight: 400;
+ line-height: 1.55;
+ color: var(--muted);
+ max-width: 560px;
+}
+
+/* ---------------- Radio group (shared) ---------------- */
+
+.radio-group {
+ display: grid;
+ /* Column count is set inline by the RadioGroup component to match
+ the option count; mobile breakpoint below collapses it to 1. */
+ grid-template-columns: repeat(var(--radio-columns, 3), 1fr);
+ gap: 10px;
+ margin-top: 4px;
+}
+
+.radio-card {
+ display: flex;
+ align-items: center;
+ gap: 12px;
+ background: var(--surface);
+ border: 1.5px solid var(--navy);
+ border-radius: 12px;
+ padding: 10px 14px;
+ cursor: pointer;
+ text-align: left;
+ font: inherit;
+ min-height: 56px;
+ color: var(--navy);
+ /* Hard offset shadow — navy block under each unselected card. */
+ box-shadow: 4px 4px 0 0 var(--navy);
+ transition: background-color 0.15s ease, color 0.15s ease,
+ box-shadow 0.15s ease, transform 0.15s ease;
+}
+
+/* Only the unselected cards behave like clickable buttons; the
+ selected one is the current state, so dim the affordance. */
+.radio-card:not(.radio-card--selected):hover {
+ transform: translate(1px, 1px);
+}
+
+.radio-card--selected {
+ background: var(--navy);
+ color: var(--cream);
+ cursor: default;
+ /* Selected card gets a green shadow instead of navy. */
+ box-shadow: 4px 4px 0 0 var(--green);
+}
+
+.radio-card__name {
+ font-size: 16px;
+ font-weight: 700;
+ letter-spacing: -0.01em;
+ color: inherit;
+ flex: 1;
+ text-align: center;
+}
+
+.radio-card__pip {
+ width: 16px;
+ height: 16px;
+ border-radius: 50%;
+ border: 1.5px solid var(--tan);
+ flex-shrink: 0;
+ position: relative;
+}
+
+.radio-card--selected .radio-card__pip {
+ border-color: var(--green);
+}
+
+.radio-card--selected .radio-card__pip::after {
+ content: "";
+ position: absolute;
+ inset: 3px;
+ border-radius: 50%;
+ background: var(--green);
+}
+
+/* ---------------- Substeps ---------------- */
+
+.substep {
+ background: var(--surface);
+ border: 1px solid var(--border);
+ border-radius: 16px;
+ padding: 22px 26px;
+ margin-top: 14px;
+}
+
+.substep__header {
+ display: flex;
+ align-items: flex-start;
+ gap: 14px;
+}
+
+.substep__header-body {
+ flex: 1;
+ min-width: 0;
+ /* Title and hint are ``s (so the interactive header can be
+ a real `