yera 0.11.1

yera.tools.mcp.oauth_callback

OAuth callback parsing for MCP authorization.

Symbols

class LoopbackOAuthCallbackServer — Serve one OAuth callback on a temporary loopback port.
class OAuthCallbackReceiver — Coordinate one OAuth callback with a waiting authorization flow.
class OAuthCallbackSession — Expose an OAuth redirect destination and its eventual result.
def parse_oauth_callback — Validate callback parameters returned by an authorization server.
def register_oauth_callback_route — Register an OAuth redirect endpoint on a FastAPI application.

LoopbackOAuthCallbackServer

Serve one OAuth callback on a temporary loopback port.

Methods

__init__ — Configure a temporary OAuth callback server.
__aenter__ — Start the temporary callback server.
__aexit__ — Stop the callback server and release its socket.
await_result — Wait for the OAuth callback.

LoopbackOAuthCallbackServer.__init__

__init__(
    timeout_seconds: float,
    host: str = '127.0.0.1',
    port: int = 0,
) → None

Configure a temporary OAuth callback server.

Parameters

timeout_seconds
type: float

Maximum time to wait for authorization.

host
type: str = '127.0.0.1'

Loopback interface on which to listen.

port
type: int = 0

Fixed loopback port, or 0 to allocate an ephemeral port.

Raises

ValueError

If host is not a loopback address or port is outside the valid TCP port range.

LoopbackOAuthCallbackServer.__aenter__

__aenter__() → Self

Start the temporary callback server.

Returns

type: Self

The running callback server.

Raises

MCPOAuthCallbackUnavailableError

If the requested loopback endpoint cannot be opened.

LoopbackOAuthCallbackServer.__aexit__

__aexit__(
    exc_type: type[BaseException] | None,
    exc_value: BaseException | None,
    traceback: TracebackType | None,
) → None

Stop the callback server and release its socket.

Parameters

exc_type
type: type[BaseException] | None

Type of exception leaving the managed context, if any.

exc_value
type: BaseException | None

Exception leaving the managed context, if any.

traceback
type: TracebackType | None

Traceback associated with the exception, if any.

LoopbackOAuthCallbackServer.await_result

await_result() → OAuthAuthorizationResult

Wait for the OAuth callback.

Returns

type: OAuthAuthorizationResult

Validated callback values.

OAuthCallbackReceiver

Coordinate one OAuth callback with a waiting authorization flow.

Methods

__init__ — Configure the callback deadline.
capture — Capture callback parameters and release the waiter.
await_result — Wait for the captured callback result.

OAuthCallbackReceiver.__init__

__init__(
    timeout_seconds: float,
) → None

Configure the callback deadline.

Parameters

timeout_seconds
type: float

Maximum time to wait for a callback.

OAuthCallbackReceiver.capture

capture(
    parameters: Mapping[str, str],
) → None

Capture callback parameters and release the waiter.

Parameters

parameters
type: Mapping[str, str]

Decoded OAuth callback query parameters.

OAuthCallbackReceiver.await_result

await_result() → OAuthAuthorizationResult

Wait for the captured callback result.

Returns

type: OAuthAuthorizationResult

Validated authorization callback values.

Raises

MCPOAuthCallbackTimeoutError

If no callback arrives in time.

RuntimeError

If callback processing finishes without a result or captured error.

Exception

If callback validation failed.

OAuthCallbackSession

Inherits: Protocol

Expose an OAuth redirect destination and its eventual result.

Methods

await_result — Wait for the authorization callback.

OAuthCallbackSession.await_result

await_result() → OAuthAuthorizationResult

Wait for the authorization callback.

Returns

type: OAuthAuthorizationResult

The captured authorization code and state.

parse_oauth_callback

parse_oauth_callback(
    parameters: Mapping[str, str],
) → OAuthAuthorizationResult

Validate callback parameters returned by an authorization server.

Parameters

parameters
type: Mapping[str, str]

Decoded OAuth callback query parameters.

Returns

type: OAuthAuthorizationResult

Authorization values required by the MCP SDK.

Raises

MCPOAuthCallbackError

If the authorization server reports failure.

ValueError

If the callback omits its authorization code or state.

register_oauth_callback_route

register_oauth_callback_route(
    app: FastAPI,
    receiver: OAuthCallbackReceiver,
    path: str = '/oauth/callback',
) → None

Register an OAuth redirect endpoint on a FastAPI application.

Parameters

app
type: FastAPI

Application receiving the callback route.

receiver
type: OAuthCallbackReceiver

Receiver coordinating the callback with OAuth setup.

path
type: str = '/oauth/callback'

URL path registered for the authorization redirect.