fastmcp 2.10.5__py3-none-any.whl → 2.11.0__py3-none-any.whl

fastmcp/server/auth/providers/workos.py

@@ -0,0 +1,170 @@
+from __future__ import annotations
+
+import httpx
+from mcp.server.auth.provider import (
+    AccessToken,
+)
+from pydantic import AnyHttpUrl
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from starlette.responses import JSONResponse
+from starlette.routing import BaseRoute, Route
+
+from fastmcp.server.auth.auth import AuthProvider, TokenVerifier
+from fastmcp.server.auth.providers.jwt import JWTVerifier
+from fastmcp.server.auth.registry import register_provider
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.types import NotSet, NotSetT
+
+logger = get_logger(__name__)
+
+
+class AuthKitProviderSettings(BaseSettings):
+    model_config = SettingsConfigDict(
+        env_prefix="FASTMCP_SERVER_AUTH_AUTHKITPROVIDER_",
+        env_file=".env",
+        extra="ignore",
+    )
+
+    authkit_domain: AnyHttpUrl
+    base_url: AnyHttpUrl
+    required_scopes: list[str] | None = None
+
+
+@register_provider("AUTHKIT")
+class AuthKitProvider(AuthProvider):
+    """WorkOS AuthKit metadata provider for DCR (Dynamic Client Registration).
+
+    This provider implements WorkOS AuthKit integration using metadata forwarding
+    instead of OAuth proxying. This is the recommended approach for WorkOS DCR
+    as it allows WorkOS to handle the OAuth flow directly while FastMCP acts
+    as a resource server.
+
+    IMPORTANT SETUP REQUIREMENTS:
+
+    1. Enable Dynamic Client Registration in WorkOS Dashboard:
+       - Go to Applications → Configuration
+       - Toggle "Dynamic Client Registration" to enabled
+
+    2. Configure your FastMCP server URL as a callback:
+       - Add your server URL to the Redirects tab in WorkOS dashboard
+       - Example: https://your-fastmcp-server.com/oauth2/callback
+
+    For detailed setup instructions, see:
+    https://workos.com/docs/authkit/mcp/integrating/token-verification
+
+    Example:
+        ```python
+        from fastmcp.server.auth.providers.workos import AuthKitProvider
+
+        # Create WorkOS metadata provider (JWT verifier created automatically)
+        workos_auth = AuthKitProvider(
+            authkit_domain="https://your-workos-domain.authkit.app",
+            base_url="https://your-fastmcp-server.com",
+        )
+
+        # Use with FastMCP
+        mcp = FastMCP("My App", auth=workos_auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        authkit_domain: AnyHttpUrl | str | NotSetT = NotSet,
+        base_url: AnyHttpUrl | str | NotSetT = NotSet,
+        required_scopes: list[str] | None | NotSetT = NotSet,
+        token_verifier: TokenVerifier | None = None,
+    ):
+        """Initialize WorkOS metadata provider.
+
+        Args:
+            authkit_domain: Your WorkOS AuthKit domain (e.g., "https://your-app.authkit.app")
+            base_url: Public URL of this FastMCP server
+            required_scopes: Optional list of scopes to require for all requests
+            token_verifier: Optional token verifier. If None, creates JWT verifier for WorkOS
+        """
+        super().__init__()
+
+        settings = AuthKitProviderSettings.model_validate(
+            {
+                k: v
+                for k, v in {
+                    "authkit_domain": authkit_domain,
+                    "base_url": base_url,
+                    "required_scopes": required_scopes,
+                }.items()
+                if v is not NotSet
+            }
+        )
+
+        self.authkit_domain = str(settings.authkit_domain).rstrip("/")
+        self.base_url = str(settings.base_url).rstrip("/")
+
+        # Create default JWT verifier if none provided
+        if token_verifier is None:
+            token_verifier = JWTVerifier(
+                jwks_uri=f"{self.authkit_domain}/oauth2/jwks",
+                issuer=self.authkit_domain,
+                algorithm="RS256",
+                required_scopes=settings.required_scopes,
+            )
+
+        self.token_verifier = token_verifier
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify a WorkOS token using the configured token verifier."""
+        return await self.token_verifier.verify_token(token)
+
+    def customize_auth_routes(self, routes: list[BaseRoute]) -> list[BaseRoute]:
+        """Add AuthKit metadata endpoints.
+
+        This adds:
+        - /.well-known/oauth-authorization-server (forwards AuthKit metadata)
+        - /.well-known/oauth-protected-resource (returns FastMCP resource info)
+        """
+
+        async def oauth_authorization_server_metadata(request):
+            """Forward AuthKit OAuth authorization server metadata with FastMCP customizations."""
+            try:
+                async with httpx.AsyncClient() as client:
+                    response = await client.get(
+                        f"{self.authkit_domain}/.well-known/oauth-authorization-server"
+                    )
+                    response.raise_for_status()
+                    metadata = response.json()
+                    return JSONResponse(metadata)
+            except Exception as e:
+                return JSONResponse(
+                    {
+                        "error": "server_error",
+                        "error_description": f"Failed to fetch AuthKit metadata: {e}",
+                    },
+                    status_code=500,
+                )
+
+        async def oauth_protected_resource_metadata(request):
+            """Return FastMCP resource server metadata."""
+            return JSONResponse(
+                {
+                    "resource": self.base_url,
+                    "authorization_servers": [self.authkit_domain],
+                    "bearer_methods_supported": ["header"],
+                }
+            )
+
+        routes.extend(
+            [
+                Route(
+                    "/.well-known/oauth-authorization-server",
+                    endpoint=oauth_authorization_server_metadata,
+                    methods=["GET"],
+                ),
+                Route(
+                    "/.well-known/oauth-protected-resource",
+                    endpoint=oauth_protected_resource_metadata,
+                    methods=["GET"],
+                ),
+            ]
+        )
+
+        return routes

fastmcp/server/auth/registry.py

@@ -0,0 +1,52 @@
+"""Provider registry for FastMCP auth providers."""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, TypeVar
+
+if TYPE_CHECKING:
+    from fastmcp.server.auth.auth import AuthProvider
+
+# Type variable for auth providers
+T = TypeVar("T", bound="AuthProvider")
+
+
+# Provider Registry
+_PROVIDER_REGISTRY: dict[str, type[AuthProvider]] = {}
+
+
+def register_provider(name: str) -> Callable[[type[T]], type[T]]:
+    """Decorator to register an auth provider with a given name.
+
+    Args:
+        name: The name to register the provider under (e.g., 'AUTHKIT')
+
+    Returns:
+        The decorated class
+
+    Example:
+        @register_provider('AUTHKIT')
+        class AuthKitProvider(AuthProvider):
+            ...
+    """
+
+    def decorator(cls: type[T]) -> type[T]:
+        _PROVIDER_REGISTRY[name.upper()] = cls
+        return cls
+
+    return decorator
+
+
+def get_registered_provider(name: str) -> type[AuthProvider]:
+    """Get a registered provider by name.
+
+    Args:
+        name: The provider name (case-insensitive)
+
+    Returns:
+        The provider class if found, None otherwise
+    """
+    if name.upper() in _PROVIDER_REGISTRY:
+        return _PROVIDER_REGISTRY[name.upper()]
+    raise ValueError(f"Provider {name!r} has not been registered.")

fastmcp/server/context.py

@@ -1,8 +1,9 @@
 from __future__ import annotations
 
 import asyncio
+import copy
 import warnings
-from collections.abc import Generator
+from collections.abc import Generator, Mapping
 from contextlib import contextmanager
 from contextvars import ContextVar, Token
 from dataclasses import dataclass
@@ -16,6 +17,7 @@ from mcp.shared.context import RequestContext
 from mcp.types import (
     ContentBlock,
     CreateMessageResult,
+    IncludeContext,
     ModelHint,
     ModelPreferences,
     Root,
@@ -45,6 +47,18 @@ _current_context: ContextVar[Context | None] = ContextVar("context", default=Non
 _flush_lock = asyncio.Lock()
 
 
+@dataclass
+class LogData:
+    """Data object for passing log arguments to client-side handlers.
+
+    This provides an interface to match the Python standard library logging,
+    for compatibility with structured logging.
+    """
+
+    msg: str
+    extra: Mapping[str, Any] | None = None
+
+
 @contextmanager
 def set_context(context: Context) -> Generator[Context, None, None]:
     token = _current_context.set(context)
@@ -82,9 +96,19 @@ class Context:
         request_id = ctx.request_id
         client_id = ctx.client_id
 
+        # Manage state across the request
+        ctx.set_state("key", "value")
+        value = ctx.get_state("key")
+
         return str(x)
     ```
 
+    State Management:
+    Context objects maintain a state dictionary that can be used to store and share
+    data across middleware and tool calls within a request. When a new context
+    is created (nested contexts), it inherits a copy of its parent's state, ensuring
+    that modifications in child contexts don't affect parent contexts.
+
     The context parameter name can be anything as long as it's annotated with Context.
     The context is optional - tools that don't need it can omit the parameter.
 
@@ -94,9 +118,15 @@ class Context:
         self.fastmcp = fastmcp
         self._tokens: list[Token] = []
         self._notification_queue: set[str] = set()  # Dedupe notifications
+        self._state: dict[str, Any] = {}
 
     async def __aenter__(self) -> Context:
         """Enter the context manager and set this context as the current context."""
+        parent_context = _current_context.get(None)
+        if parent_context is not None:
+            # Inherit state from parent context
+            self._state = copy.deepcopy(parent_context._state)
+
         # Always set this context and save the token
         token = _current_context.set(self)
         self._tokens.append(token)
@@ -112,7 +142,7 @@ class Context:
             _current_context.reset(token)
 
     @property
-    def request_context(self) -> RequestContext:
+    def request_context(self) -> RequestContext[ServerSession, Any, Request]:
         """Access to the underlying request context.
 
         If called outside of a request context, this will raise a ValueError.
@@ -166,6 +196,7 @@ class Context:
         message: str,
         level: LoggingLevel | None = None,
         logger_name: str | None = None,
+        extra: Mapping[str, Any] | None = None,
     ) -> None:
         """Send a log message to the client.
 
@@ -174,12 +205,14 @@ class Context:
             level: Optional log level. One of "debug", "info", "notice", "warning", "error", "critical",
                 "alert", or "emergency". Default is "info".
             logger_name: Optional logger name
+            extra: Optional mapping for additional arguments
         """
         if level is None:
             level = "info"
+        data = LogData(msg=message, extra=extra)
         await self.session.send_log_message(
             level=level,
-            data=message,
+            data=data,
             logger=logger_name,
             related_request_id=self.request_id,
         )
@@ -199,35 +232,48 @@ class Context:
         return str(self.request_context.request_id)
 
     @property
-    def session_id(self) -> str | None:
-        """Get the MCP session ID for HTTP transports.
+    def session_id(self) -> str:
+        """Get the MCP session ID for ALL transports.
 
         Returns the session ID that can be used as a key for session-based
         data storage (e.g., Redis) to share data between tool calls within
         the same client session.
 
         Returns:
-            The session ID for HTTP transports (SSE, StreamableHTTP), or None
-            for stdio and in-memory transports which don't use session IDs.
+            The session ID for StreamableHTTP transports, or a generated ID
+            for other transports.
 
         Example:
             ```python
             @server.tool
             def store_data(data: dict, ctx: Context) -> str:
-                if session_id := ctx.session_id:
-                    redis_client.set(f"session:{session_id}:data", json.dumps(data))
-                    return f"Data stored for session {session_id}"
-                return "No session ID available (stdio/memory transport)"
+                session_id = ctx.session_id
+                redis_client.set(f"session:{session_id}:data", json.dumps(data))
+                return f"Data stored for session {session_id}"
             ```
         """
-        try:
-            from fastmcp.server.dependencies import get_http_headers
+        request_ctx = self.request_context
+        session = request_ctx.session
 
-            headers = get_http_headers(include_all=True)
-            return headers.get("mcp-session-id")
-        except RuntimeError:
-            # No HTTP context available (stdio/in-memory transport)
-            return None
+        # Try to get the session ID from the session attributes
+        session_id = getattr(session, "_fastmcp_id", None)
+        if session_id is not None:
+            return session_id
+
+        # Try to get the session ID from the http request headers
+        request = request_ctx.request
+        if request:
+            session_id = request.headers.get("mcp-session-id")
+
+        # Generate a session ID if it doesn't exist.
+        if session_id is None:
+            from uuid import uuid4
+
+            session_id = str(uuid4())
+
+        # Save the session id to the session attributes
+        setattr(session, "_fastmcp_id", session_id)
+        return session_id
 
     @property
     def session(self) -> ServerSession:
@@ -235,21 +281,49 @@ class Context:
         return self.request_context.session
 
     # Convenience methods for common log levels
-    async def debug(self, message: str, logger_name: str | None = None) -> None:
+    async def debug(
+        self,
+        message: str,
+        logger_name: str | None = None,
+        extra: Mapping[str, Any] | None = None,
+    ) -> None:
         """Send a debug log message."""
-        await self.log(level="debug", message=message, logger_name=logger_name)
+        await self.log(
+            level="debug", message=message, logger_name=logger_name, extra=extra
+        )
 
-    async def info(self, message: str, logger_name: str | None = None) -> None:
+    async def info(
+        self,
+        message: str,
+        logger_name: str | None = None,
+        extra: Mapping[str, Any] | None = None,
+    ) -> None:
         """Send an info log message."""
-        await self.log(level="info", message=message, logger_name=logger_name)
+        await self.log(
+            level="info", message=message, logger_name=logger_name, extra=extra
+        )
 
-    async def warning(self, message: str, logger_name: str | None = None) -> None:
+    async def warning(
+        self,
+        message: str,
+        logger_name: str | None = None,
+        extra: Mapping[str, Any] | None = None,
+    ) -> None:
         """Send a warning log message."""
-        await self.log(level="warning", message=message, logger_name=logger_name)
+        await self.log(
+            level="warning", message=message, logger_name=logger_name, extra=extra
+        )
 
-    async def error(self, message: str, logger_name: str | None = None) -> None:
+    async def error(
+        self,
+        message: str,
+        logger_name: str | None = None,
+        extra: Mapping[str, Any] | None = None,
+    ) -> None:
         """Send an error log message."""
-        await self.log(level="error", message=message, logger_name=logger_name)
+        await self.log(
+            level="error", message=message, logger_name=logger_name, extra=extra
+        )
 
     async def list_roots(self) -> list[Root]:
         """List the roots available to the server, as indicated by the client."""
@@ -272,6 +346,7 @@ class Context:
         self,
         messages: str | list[str | SamplingMessage],
         system_prompt: str | None = None,
+        include_context: IncludeContext | None = None,
         temperature: float | None = None,
         max_tokens: int | None = None,
         model_preferences: ModelPreferences | str | list[str] | None = None,
@@ -304,6 +379,7 @@ class Context:
         result: CreateMessageResult = await self.session.create_message(
             messages=sampling_messages,
             system_prompt=system_prompt,
+            include_context=include_context,
             temperature=temperature,
             max_tokens=max_tokens,
             model_preferences=self._parse_model_preferences(model_preferences),
@@ -452,6 +528,14 @@ class Context:
 
         return fastmcp.server.dependencies.get_http_request()
 
+    def set_state(self, key: str, value: Any) -> None:
+        """Set a value in the context state."""
+        self._state[key] = value
+
+    def get_state(self, key: str) -> Any:
+        """Get a value from the context state. Returns None if the key is not found."""
+        return self._state.get(key)
+
     def _queue_tool_list_changed(self) -> None:
         """Queue a tool list changed notification."""
         self._notification_queue.add("notifications/tools/list_changed")

fastmcp/server/dependencies.py

@@ -37,9 +37,14 @@ def get_context() -> Context:
 
 
 def get_http_request() -> Request:
-    from fastmcp.server.http import _current_http_request
+    from mcp.server.lowlevel.server import request_ctx
+
+    request = None
+    try:
+        request = request_ctx.get().request
+    except LookupError:
+        pass
 
-    request = _current_http_request.get()
     if request is None:
         raise RuntimeError("No active HTTP request found.")
     return request
@@ -72,6 +77,8 @@ def get_http_headers(include_all: bool = False) -> dict[str, str]:
             "proxy-authenticate",
             "proxy-authorization",
             "proxy-connection",
+            # MCP-related headers
+            "mcp-session-id",
         }
         # (just in case)
         if not all(h.lower() == h for h in exclude_headers):