fastmcp 2.13.1__py3-none-any.whl → 2.13.3__py3-none-any.whl

fastmcp/server/auth/providers/descope.py

@@ -7,8 +7,10 @@ for seamless MCP client authentication.
 
 from __future__ import annotations
 
+from urllib.parse import urlparse
+
 import httpx
-from pydantic import AnyHttpUrl
+from pydantic import AnyHttpUrl, field_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
 from starlette.responses import JSONResponse
 from starlette.routing import Route
@@ -16,6 +18,7 @@ from starlette.routing import Route
 from fastmcp.server.auth import RemoteAuthProvider, TokenVerifier
 from fastmcp.server.auth.providers.jwt import JWTVerifier
 from fastmcp.settings import ENV_FILE
+from fastmcp.utilities.auth import parse_scopes
 from fastmcp.utilities.logging import get_logger
 from fastmcp.utilities.types import NotSet, NotSetT
 
@@ -29,9 +32,16 @@ class DescopeProviderSettings(BaseSettings):
         extra="ignore",
     )
 
-    project_id: str
+    config_url: AnyHttpUrl | None = None
+    project_id: str | None = None
+    descope_base_url: AnyHttpUrl | str | None = None
     base_url: AnyHttpUrl
-    descope_base_url: AnyHttpUrl = AnyHttpUrl("https://api.descope.com")
+    required_scopes: list[str] | None = None
+
+    @field_validator("required_scopes", mode="before")
+    @classmethod
+    def _parse_scopes(cls, v):
+        return parse_scopes(v)
 
 
 class DescopeProvider(RemoteAuthProvider):
@@ -44,15 +54,15 @@ class DescopeProvider(RemoteAuthProvider):
 
     IMPORTANT SETUP REQUIREMENTS:
 
-    1. Enable Dynamic Client Registration in Descope Console:
-       - Go to the [Inbound Apps page](https://app.descope.com/apps/inbound) of the Descope Console
-       - Click **DCR Settings**
-       - Enable **Dynamic Client Registration (DCR)**
-       - Define allowed scopes
+    1. Create an MCP Server in Descope Console:
+       - Go to the [MCP Servers page](https://app.descope.com/mcp-servers) of the Descope Console
+       - Create a new MCP Server
+       - Ensure that **Dynamic Client Registration (DCR)** is enabled
+       - Note your Well-Known URL
 
-    2. Note your Project ID:
-       - Save your Project ID from [Project Settings](https://app.descope.com/settings/project)
-       - Example: P2abc...123
+    2. Note your Well-Known URL:
+       - Save your Well-Known URL from [MCP Server Settings](https://app.descope.com/mcp-servers)
+       - Format: ``https://.../v1/apps/agentic/P.../M.../.well-known/openid-configuration``
 
     For detailed setup instructions, see:
     https://docs.descope.com/identity-federation/inbound-apps/creating-inbound-apps#method-2-dynamic-client-registration-dcr
@@ -63,9 +73,8 @@ class DescopeProvider(RemoteAuthProvider):
 
         # Create Descope metadata provider (JWT verifier created automatically)
         descope_auth = DescopeProvider(
-            project_id="P2abc...123",
+            config_url="https://.../v1/apps/agentic/P.../M.../.well-known/openid-configuration",
             base_url="https://your-fastmcp-server.com",
-            descope_base_url="https://api.descope.com",
         )
 
         # Use with FastMCP
@@ -76,50 +85,100 @@ class DescopeProvider(RemoteAuthProvider):
     def __init__(
         self,
         *,
+        config_url: AnyHttpUrl | str | NotSetT = NotSet,
         project_id: str | NotSetT = NotSet,
-        base_url: AnyHttpUrl | str | NotSetT = NotSet,
         descope_base_url: AnyHttpUrl | str | NotSetT = NotSet,
+        base_url: AnyHttpUrl | str | NotSetT = NotSet,
+        required_scopes: list[str] | NotSetT | None = NotSet,
         token_verifier: TokenVerifier | None = None,
     ):
         """Initialize Descope metadata provider.
 
         Args:
-            project_id: Your Descope Project ID (e.g., "P2abc...123")
+            config_url: Your Descope Well-Known URL (e.g., "https://.../v1/apps/agentic/P.../M.../.well-known/openid-configuration")
+                This is the new recommended way. If provided, project_id and descope_base_url are ignored.
+            project_id: Your Descope Project ID (e.g., "P2abc123"). Used with descope_base_url for backwards compatibility.
+            descope_base_url: Your Descope base URL (e.g., "https://api.descope.com"). Used with project_id for backwards compatibility.
             base_url: Public URL of this FastMCP server
-            descope_base_url: Descope API base URL (defaults to https://api.descope.com)
+            required_scopes: Optional list of scopes that must be present in validated tokens.
+                These scopes will be included in the protected resource metadata.
             token_verifier: Optional token verifier. If None, creates JWT verifier for Descope
         """
         settings = DescopeProviderSettings.model_validate(
             {
                 k: v
                 for k, v in {
+                    "config_url": config_url,
                     "project_id": project_id,
-                    "base_url": base_url,
                     "descope_base_url": descope_base_url,
+                    "base_url": base_url,
+                    "required_scopes": required_scopes,
                 }.items()
                 if v is not NotSet
             }
         )
 
-        self.project_id = settings.project_id
         self.base_url = AnyHttpUrl(str(settings.base_url).rstrip("/"))
-        self.descope_base_url = str(settings.descope_base_url).rstrip("/")
+
+        # Determine which API is being used
+        if settings.config_url is not None:
+            # New API: use config_url
+            # Strip /.well-known/openid-configuration from config_url if present
+            issuer_url = str(settings.config_url)
+            if issuer_url.endswith("/.well-known/openid-configuration"):
+                issuer_url = issuer_url[: -len("/.well-known/openid-configuration")]
+
+            # Parse the issuer URL to extract descope_base_url and project_id for other uses
+            parsed_url = urlparse(issuer_url)
+            path_parts = parsed_url.path.strip("/").split("/")
+
+            # Extract project_id from path (format: /v1/apps/agentic/P.../M...)
+            if "agentic" in path_parts:
+                agentic_index = path_parts.index("agentic")
+                if agentic_index + 1 < len(path_parts):
+                    self.project_id = path_parts[agentic_index + 1]
+                else:
+                    raise ValueError(
+                        f"Could not extract project_id from config_url: {issuer_url}"
+                    )
+            else:
+                raise ValueError(
+                    f"Could not find 'agentic' in config_url path: {issuer_url}"
+                )
+
+            # Extract descope_base_url (scheme + netloc)
+            self.descope_base_url = f"{parsed_url.scheme}://{parsed_url.netloc}".rstrip(
+                "/"
+            )
+        elif settings.project_id is not None and settings.descope_base_url is not None:
+            # Old API: use project_id and descope_base_url
+            self.project_id = settings.project_id
+            descope_base_url_str = str(settings.descope_base_url).rstrip("/")
+            # Ensure descope_base_url has a scheme
+            if not descope_base_url_str.startswith(("http://", "https://")):
+                descope_base_url_str = f"https://{descope_base_url_str}"
+            self.descope_base_url = descope_base_url_str
+            # Old issuer format
+            issuer_url = f"{self.descope_base_url}/v1/apps/{self.project_id}"
+        else:
+            raise ValueError(
+                "Either config_url (new API) or both project_id and descope_base_url (old API) must be provided"
+            )
 
         # Create default JWT verifier if none provided
         if token_verifier is None:
             token_verifier = JWTVerifier(
                 jwks_uri=f"{self.descope_base_url}/{self.project_id}/.well-known/jwks.json",
-                issuer=f"{self.descope_base_url}/v1/apps/{self.project_id}",
+                issuer=issuer_url,
                 algorithm="RS256",
                 audience=self.project_id,
+                required_scopes=settings.required_scopes,
             )
 
         # Initialize RemoteAuthProvider with Descope as the authorization server
         super().__init__(
             token_verifier=token_verifier,
-            authorization_servers=[
-                AnyHttpUrl(f"{self.descope_base_url}/v1/apps/{self.project_id}")
-            ],
+            authorization_servers=[AnyHttpUrl(issuer_url)],
             base_url=self.base_url,
         )
 

fastmcp/server/auth/providers/discord.py

@@ -0,0 +1,308 @@
+"""Discord OAuth provider for FastMCP.
+
+This module provides a complete Discord OAuth integration that's ready to use
+with just a client ID and client secret. It handles all the complexity of
+Discord's OAuth flow, token validation, and user management.
+
+Example:
+    ```python
+    from fastmcp import FastMCP
+    from fastmcp.server.auth.providers.discord import DiscordProvider
+
+    # Simple Discord OAuth protection
+    auth = DiscordProvider(
+        client_id="your-discord-client-id",
+        client_secret="your-discord-client-secret"
+    )
+
+    mcp = FastMCP("My Protected Server", auth=auth)
+    ```
+"""
+
+from __future__ import annotations
+
+import time
+from datetime import datetime
+
+import httpx
+from key_value.aio.protocols import AsyncKeyValue
+from pydantic import AnyHttpUrl, SecretStr, field_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from fastmcp.server.auth import TokenVerifier
+from fastmcp.server.auth.auth import AccessToken
+from fastmcp.server.auth.oauth_proxy import OAuthProxy
+from fastmcp.settings import ENV_FILE
+from fastmcp.utilities.auth import parse_scopes
+from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.types import NotSet, NotSetT
+
+logger = get_logger(__name__)
+
+
+class DiscordProviderSettings(BaseSettings):
+    """Settings for Discord OAuth provider."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="FASTMCP_SERVER_AUTH_DISCORD_",
+        env_file=ENV_FILE,
+        extra="ignore",
+    )
+
+    client_id: str | None = None
+    client_secret: SecretStr | None = None
+    base_url: AnyHttpUrl | str | None = None
+    issuer_url: AnyHttpUrl | str | None = None
+    redirect_path: str | None = None
+    required_scopes: list[str] | None = None
+    timeout_seconds: int | None = None
+    allowed_client_redirect_uris: list[str] | None = None
+    jwt_signing_key: str | None = None
+
+    @field_validator("required_scopes", mode="before")
+    @classmethod
+    def _parse_scopes(cls, v):
+        return parse_scopes(v)
+
+
+class DiscordTokenVerifier(TokenVerifier):
+    """Token verifier for Discord OAuth tokens.
+
+    Discord OAuth tokens are opaque (not JWTs), so we verify them
+    by calling Discord's tokeninfo API to check if they're valid and get user info.
+    """
+
+    def __init__(
+        self,
+        *,
+        required_scopes: list[str] | None = None,
+        timeout_seconds: int = 10,
+    ):
+        """Initialize the Discord token verifier.
+
+        Args:
+            required_scopes: Required OAuth scopes (e.g., ['email'])
+            timeout_seconds: HTTP request timeout
+        """
+        super().__init__(required_scopes=required_scopes)
+        self.timeout_seconds = timeout_seconds
+
+    async def verify_token(self, token: str) -> AccessToken | None:
+        """Verify Discord OAuth token by calling Discord's tokeninfo API."""
+        try:
+            async with httpx.AsyncClient(timeout=self.timeout_seconds) as client:
+                # Use Discord's tokeninfo endpoint to validate the token
+                headers = {
+                    "Authorization": f"Bearer {token}",
+                    "User-Agent": "FastMCP-Discord-OAuth",
+                }
+                response = await client.get(
+                    "https://discord.com/api/oauth2/@me",
+                    headers=headers,
+                )
+
+                if response.status_code != 200:
+                    logger.debug(
+                        "Discord token verification failed: %d",
+                        response.status_code,
+                    )
+                    return None
+
+                token_info = response.json()
+
+                # Check if token is expired (Discord returns ISO timestamp)
+                expires_str = token_info.get("expires")
+                expires_at = None
+                if expires_str:
+                    expires_dt = datetime.fromisoformat(
+                        expires_str.replace("Z", "+00:00")
+                    )
+                    expires_at = int(expires_dt.timestamp())
+                    if expires_at <= int(time.time()):
+                        logger.debug("Discord token has expired")
+                        return None
+
+                token_scopes = token_info.get("scopes", [])
+
+                # Check required scopes
+                if self.required_scopes:
+                    token_scopes_set = set(token_scopes)
+                    required_scopes_set = set(self.required_scopes)
+                    if not required_scopes_set.issubset(token_scopes_set):
+                        logger.debug(
+                            "Discord token missing required scopes. Has %d, needs %d",
+                            len(token_scopes_set),
+                            len(required_scopes_set),
+                        )
+                        return None
+
+                user_data = token_info.get("user", {})
+                application = token_info.get("application") or {}
+                client_id = str(application.get("id", "unknown"))
+
+                # Create AccessToken with Discord user info
+                access_token = AccessToken(
+                    token=token,
+                    client_id=client_id,
+                    scopes=token_scopes,
+                    expires_at=expires_at,
+                    claims={
+                        "sub": user_data.get("id"),
+                        "username": user_data.get("username"),
+                        "discriminator": user_data.get("discriminator"),
+                        "avatar": user_data.get("avatar"),
+                        "email": user_data.get("email"),
+                        "verified": user_data.get("verified"),
+                        "locale": user_data.get("locale"),
+                        "discord_user": user_data,
+                        "discord_token_info": token_info,
+                    },
+                )
+                logger.debug("Discord token verified successfully")
+                return access_token
+
+        except httpx.RequestError as e:
+            logger.debug("Failed to verify Discord token: %s", e)
+            return None
+        except Exception as e:
+            logger.debug("Discord token verification error: %s", e)
+            return None
+
+
+class DiscordProvider(OAuthProxy):
+    """Complete Discord OAuth provider for FastMCP.
+
+    This provider makes it trivial to add Discord OAuth protection to any
+    FastMCP server. Just provide your Discord OAuth app credentials and
+    a base URL, and you're ready to go.
+
+    Features:
+    - Transparent OAuth proxy to Discord
+    - Automatic token validation via Discord's API
+    - User information extraction from Discord APIs
+    - Minimal configuration required
+
+    Example:
+        ```python
+        from fastmcp import FastMCP
+        from fastmcp.server.auth.providers.discord import DiscordProvider
+
+        auth = DiscordProvider(
+            client_id="123456789",
+            client_secret="discord-client-secret-abc123...",
+            base_url="https://my-server.com"
+        )
+
+        mcp = FastMCP("My App", auth=auth)
+        ```
+    """
+
+    def __init__(
+        self,
+        *,
+        client_id: str | NotSetT = NotSet,
+        client_secret: str | NotSetT = NotSet,
+        base_url: AnyHttpUrl | str | NotSetT = NotSet,
+        issuer_url: AnyHttpUrl | str | NotSetT = NotSet,
+        redirect_path: str | NotSetT = NotSet,
+        required_scopes: list[str] | NotSetT = NotSet,
+        timeout_seconds: int | NotSetT = NotSet,
+        allowed_client_redirect_uris: list[str] | NotSetT = NotSet,
+        client_storage: AsyncKeyValue | None = None,
+        jwt_signing_key: str | bytes | NotSetT = NotSet,
+        require_authorization_consent: bool = True,
+    ):
+        """Initialize Discord OAuth provider.
+
+        Args:
+            client_id: Discord OAuth client ID (e.g., "123456789")
+            client_secret: Discord OAuth client secret (e.g., "S....")
+            base_url: Public URL where OAuth endpoints will be accessible (includes any mount path)
+            issuer_url: Issuer URL for OAuth metadata (defaults to base_url). Use root-level URL
+                to avoid 404s during discovery when mounting under a path.
+            redirect_path: Redirect path configured in Discord OAuth app (defaults to "/auth/callback")
+            required_scopes: Required Discord scopes (defaults to ["identify"]). Common scopes include:
+                - "identify" for profile info (default)
+                - "email" for email access
+                - "guilds" for server membership info
+            timeout_seconds: HTTP request timeout for Discord API calls
+            allowed_client_redirect_uris: List of allowed redirect URI patterns for MCP clients.
+                If None (default), all URIs are allowed. If empty list, no URIs are allowed.
+            client_storage: Storage backend for OAuth state (client registrations, encrypted tokens).
+                If None, a DiskStore will be created in the data directory (derived from `platformdirs`). The
+                disk store will be encrypted using a key derived from the JWT Signing Key.
+            jwt_signing_key: Secret for signing FastMCP JWT tokens (any string or bytes). If bytes are provided,
+                they will be used as is. If a string is provided, it will be derived into a 32-byte key. If not
+                provided, the upstream client secret will be used to derive a 32-byte key using PBKDF2.
+            require_authorization_consent: Whether to require user consent before authorizing clients (default True).
+                When True, users see a consent screen before being redirected to Discord.
+                When False, authorization proceeds directly without user confirmation.
+                SECURITY WARNING: Only disable for local development or testing environments.
+        """
+
+        settings = DiscordProviderSettings.model_validate(
+            {
+                k: v
+                for k, v in {
+                    "client_id": client_id,
+                    "client_secret": client_secret,
+                    "base_url": base_url,
+                    "issuer_url": issuer_url,
+                    "redirect_path": redirect_path,
+                    "required_scopes": required_scopes,
+                    "timeout_seconds": timeout_seconds,
+                    "allowed_client_redirect_uris": allowed_client_redirect_uris,
+                    "jwt_signing_key": jwt_signing_key,
+                }.items()
+                if v is not NotSet
+            }
+        )
+
+        # Validate required settings
+        if not settings.client_id:
+            raise ValueError(
+                "client_id is required - set via parameter or FASTMCP_SERVER_AUTH_DISCORD_CLIENT_ID"
+            )
+        if not settings.client_secret:
+            raise ValueError(
+                "client_secret is required - set via parameter or FASTMCP_SERVER_AUTH_DISCORD_CLIENT_SECRET"
+            )
+
+        # Apply defaults
+        timeout_seconds_final = settings.timeout_seconds or 10
+        required_scopes_final = settings.required_scopes or ["identify"]
+        allowed_client_redirect_uris_final = settings.allowed_client_redirect_uris
+
+        # Create Discord token verifier
+        token_verifier = DiscordTokenVerifier(
+            required_scopes=required_scopes_final,
+            timeout_seconds=timeout_seconds_final,
+        )
+
+        # Extract secret string from SecretStr
+        client_secret_str = (
+            settings.client_secret.get_secret_value() if settings.client_secret else ""
+        )
+
+        # Initialize OAuth proxy with Discord endpoints
+        super().__init__(
+            upstream_authorization_endpoint="https://discord.com/oauth2/authorize",
+            upstream_token_endpoint="https://discord.com/api/oauth2/token",
+            upstream_client_id=settings.client_id,
+            upstream_client_secret=client_secret_str,
+            token_verifier=token_verifier,
+            base_url=settings.base_url,
+            redirect_path=settings.redirect_path,
+            issuer_url=settings.issuer_url
+            or settings.base_url,  # Default to base_url if not specified
+            allowed_client_redirect_uris=allowed_client_redirect_uris_final,
+            client_storage=client_storage,
+            jwt_signing_key=settings.jwt_signing_key,
+            require_authorization_consent=require_authorization_consent,
+        )
+
+        logger.debug(
+            "Initialized Discord OAuth provider for client %s with scopes: %s",
+            settings.client_id,
+            required_scopes_final,
+        )

fastmcp/server/auth/providers/google.py

@@ -225,6 +225,7 @@ class GoogleProvider(OAuthProxy):
         client_storage: AsyncKeyValue | None = None,
         jwt_signing_key: str | bytes | NotSetT = NotSet,
         require_authorization_consent: bool = True,
+        extra_authorize_params: dict[str, str] | None = None,
     ):
         """Initialize Google OAuth provider.
 
@@ -252,6 +253,10 @@ class GoogleProvider(OAuthProxy):
                 When True, users see a consent screen before being redirected to Google.
                 When False, authorization proceeds directly without user confirmation.
                 SECURITY WARNING: Only disable for local development or testing environments.
+            extra_authorize_params: Additional parameters to forward to Google's authorization endpoint.
+                By default, GoogleProvider sets {"access_type": "offline", "prompt": "consent"} to ensure
+                refresh tokens are returned. You can override these defaults or add additional parameters.
+                Example: {"prompt": "select_account"} to let users choose their Google account.
         """
 
         settings = GoogleProviderSettings.model_validate(
@@ -299,6 +304,18 @@ class GoogleProvider(OAuthProxy):
             settings.client_secret.get_secret_value() if settings.client_secret else ""
         )
 
+        # Set Google-specific defaults for extra authorize params
+        # access_type=offline ensures refresh tokens are returned
+        # prompt=consent forces consent screen to get refresh token (Google only issues on first auth otherwise)
+        google_defaults = {
+            "access_type": "offline",
+            "prompt": "consent",
+        }
+        # User-provided params override defaults
+        if extra_authorize_params:
+            google_defaults.update(extra_authorize_params)
+        extra_authorize_params_final = google_defaults
+
         # Initialize OAuth proxy with Google endpoints
         super().__init__(
             upstream_authorization_endpoint="https://accounts.google.com/o/oauth2/v2/auth",
@@ -314,6 +331,7 @@ class GoogleProvider(OAuthProxy):
             client_storage=client_storage,
             jwt_signing_key=settings.jwt_signing_key,
             require_authorization_consent=require_authorization_consent,
+            extra_authorize_params=extra_authorize_params_final,
         )
 
         logger.debug(