fastmcp 2.12.3__py3-none-any.whl → 2.12.4__py3-none-any.whl

fastmcp/cli/install/gemini_cli.py

@@ -104,7 +104,6 @@ def install_gemini_cli(
         )
         return False
 
-    # Build uv run command using Environment.build_uv_run_command()
     env_config = UVEnvironment(
         python=python_version,
         dependencies=(with_packages or []) + ["fastmcp"],

fastmcp/cli/run.py

@@ -184,8 +184,8 @@ async def run_command(
         kwargs["port"] = port
     if path:
         kwargs["path"] = path
-    # Note: log_level is not currently supported by run_async
-    # TODO: Add log_level support to server.run_async
+    if log_level:
+        kwargs["log_level"] = log_level
 
     if not show_banner:
         kwargs["show_banner"] = False

fastmcp/client/auth/oauth.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import asyncio
-import json
 import webbrowser
 from asyncio import Future
 from collections.abc import AsyncGenerator
@@ -29,6 +28,7 @@ from fastmcp.client.oauth_callback import (
 )
 from fastmcp.utilities.http import find_available_port
 from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.storage import JSONFileStorage
 
 __all__ = ["OAuth"]
 
@@ -62,13 +62,14 @@ class FileTokenStorage(TokenStorage):
     Implements the mcp.client.auth.TokenStorage protocol.
 
     Each instance is tied to a specific server URL for proper token isolation.
+    Uses JSONFileStorage internally for consistent file handling.
     """
 
     def __init__(self, server_url: str, cache_dir: Path | None = None):
         """Initialize storage for a specific server URL."""
         self.server_url = server_url
-        self.cache_dir = cache_dir or default_cache_dir()
-        self.cache_dir.mkdir(exist_ok=True, parents=True)
+        # Use JSONFileStorage for actual file operations
+        self._storage = JSONFileStorage(cache_dir or default_cache_dir())
 
     @staticmethod
     def get_base_url(url: str) -> str:
@@ -76,28 +77,33 @@ class FileTokenStorage(TokenStorage):
         parsed = urlparse(url)
         return f"{parsed.scheme}://{parsed.netloc}"
 
-    def get_cache_key(self) -> str:
-        """Generate a safe filesystem key from the server's base URL."""
+    def _get_storage_key(self, file_type: Literal["client_info", "tokens"]) -> str:
+        """Get the storage key for the specified data type.
+
+        JSONFileStorage will handle making the key filesystem-safe.
+        """
         base_url = self.get_base_url(self.server_url)
-        return (
-            base_url.replace("://", "_")
-            .replace(".", "_")
-            .replace("/", "_")
-            .replace(":", "_")
-        )
+        return f"{base_url}_{file_type}"
 
     def _get_file_path(self, file_type: Literal["client_info", "tokens"]) -> Path:
-        """Get the file path for the specified cache file type."""
-        key = self.get_cache_key()
-        return self.cache_dir / f"{key}_{file_type}.json"
+        """Get the file path for the specified cache file type.
+
+        This method is kept for backward compatibility with tests that access _get_file_path.
+        """
+        key = self._get_storage_key(file_type)
+        return self._storage._get_file_path(key)
 
     async def get_tokens(self) -> OAuthToken | None:
         """Load tokens from file storage."""
-        path = self._get_file_path("tokens")
+        key = self._get_storage_key("tokens")
+        data = await self._storage.get(key)
+
+        if data is None:
+            return None
 
         try:
-            # Parse JSON and validate as StoredToken
-            stored = stored_token_adapter.validate_json(path.read_text())
+            # Parse and validate as StoredToken
+            stored = stored_token_adapter.validate_python(data)
 
             # Check if token is expired
             if stored.expires_at is not None:
@@ -117,15 +123,15 @@ class FileTokenStorage(TokenStorage):
 
             return stored.token_payload
 
-        except (FileNotFoundError, ValidationError) as e:
+        except ValidationError as e:
             logger.debug(
-                f"Could not load tokens for {self.get_base_url(self.server_url)}: {e}"
+                f"Could not validate tokens for {self.get_base_url(self.server_url)}: {e}"
             )
             return None
 
     async def set_tokens(self, tokens: OAuthToken) -> None:
         """Save tokens to file storage."""
-        path = self._get_file_path("tokens")
+        key = self._get_storage_key("tokens")
 
         # Calculate absolute expiry time if expires_in is present
         expires_at = None
@@ -134,19 +140,22 @@ class FileTokenStorage(TokenStorage):
                 seconds=tokens.expires_in
             )
 
-        # Create StoredToken and save using Pydantic serialization
+        # Create StoredToken and save using storage
+        # Note: JSONFileStorage will wrap this in {"data": ..., "timestamp": ...}
         stored = StoredToken(token_payload=tokens, expires_at=expires_at)
-
-        path.write_text(stored.model_dump_json(indent=2))
+        await self._storage.set(key, stored.model_dump(mode="json"))
         logger.debug(f"Saved tokens for {self.get_base_url(self.server_url)}")
 
     async def get_client_info(self) -> OAuthClientInformationFull | None:
         """Load client information from file storage."""
-        path = self._get_file_path("client_info")
+        key = self._get_storage_key("client_info")
+        data = await self._storage.get(key)
+
+        if data is None:
+            return None
+
         try:
-            client_info = OAuthClientInformationFull.model_validate_json(
-                path.read_text()
-            )
+            client_info = OAuthClientInformationFull.model_validate(data)
             # Check if we have corresponding valid tokens
             # If no tokens exist, the OAuth flow was incomplete and we should
             # force a fresh client registration
@@ -157,27 +166,31 @@ class FileTokenStorage(TokenStorage):
                     "OAuth flow may have been incomplete. Clearing client info to force fresh registration."
                 )
                 # Clear the incomplete client info
-                client_info_path = self._get_file_path("client_info")
-                client_info_path.unlink(missing_ok=True)
+                await self._storage.delete(key)
                 return None
 
             return client_info
-        except (FileNotFoundError, json.JSONDecodeError, ValidationError) as e:
+        except ValidationError as e:
             logger.debug(
-                f"Could not load client info for {self.get_base_url(self.server_url)}: {e}"
+                f"Could not validate client info for {self.get_base_url(self.server_url)}: {e}"
             )
             return None
 
     async def set_client_info(self, client_info: OAuthClientInformationFull) -> None:
         """Save client information to file storage."""
-        path = self._get_file_path("client_info")
-        path.write_text(client_info.model_dump_json(indent=2))
+        key = self._get_storage_key("client_info")
+        await self._storage.set(key, client_info.model_dump(mode="json"))
         logger.debug(f"Saved client info for {self.get_base_url(self.server_url)}")
 
     def clear(self) -> None:
-        """Clear all cached data for this server."""
+        """Clear all cached data for this server.
+
+        Note: This is a synchronous method for backward compatibility.
+        Uses direct file operations instead of async storage methods.
+        """
         file_types: list[Literal["client_info", "tokens"]] = ["client_info", "tokens"]
         for file_type in file_types:
+            # Use the file path directly for synchronous deletion
             path = self._get_file_path(file_type)
             path.unlink(missing_ok=True)
         logger.debug(f"Cleared OAuth cache for {self.get_base_url(self.server_url)}")
@@ -318,8 +331,8 @@ class OAuth(OAuthClientProvider):
                     "OAuth client not found - cached credentials may be stale"
                 )
 
-            # For any non-redirect response, something is wrong
-            if response.status_code not in (302, 303, 307, 308):
+            # OAuth typically returns redirects, but some providers return 200 with HTML login pages
+            if response.status_code not in (200, 302, 303, 307, 308):
                 raise RuntimeError(
                     f"Unexpected authorization response: {response.status_code}"
                 )

fastmcp/client/client.py

@@ -745,12 +745,15 @@ class Client(Generic[ClientTransportT]):
         self,
         ref: mcp.types.ResourceTemplateReference | mcp.types.PromptReference,
         argument: dict[str, str],
+        context_arguments: dict[str, Any] | None = None,
     ) -> mcp.types.CompleteResult:
         """Send a completion request and return the complete MCP protocol result.
 
         Args:
             ref (mcp.types.ResourceTemplateReference | mcp.types.PromptReference): The reference to complete.
             argument (dict[str, str]): Arguments to pass to the completion request.
+            context_arguments (dict[str, Any] | None, optional): Optional context arguments to
+                include with the completion request. Defaults to None.
 
         Returns:
             mcp.types.CompleteResult: The complete response object from the protocol,
@@ -761,19 +764,24 @@ class Client(Generic[ClientTransportT]):
         """
         logger.debug(f"[{self.name}] called complete: {ref}")
 
-        result = await self.session.complete(ref=ref, argument=argument)
+        result = await self.session.complete(
+            ref=ref, argument=argument, context_arguments=context_arguments
+        )
         return result
 
     async def complete(
         self,
         ref: mcp.types.ResourceTemplateReference | mcp.types.PromptReference,
         argument: dict[str, str],
+        context_arguments: dict[str, Any] | None = None,
     ) -> mcp.types.Completion:
         """Send a completion request to the server.
 
         Args:
             ref (mcp.types.ResourceTemplateReference | mcp.types.PromptReference): The reference to complete.
             argument (dict[str, str]): Arguments to pass to the completion request.
+            context_arguments (dict[str, Any] | None, optional): Optional context arguments to
+                include with the completion request. Defaults to None.
 
         Returns:
             mcp.types.Completion: The completion object.
@@ -781,7 +789,9 @@ class Client(Generic[ClientTransportT]):
         Raises:
             RuntimeError: If called while the client is not connected.
         """
-        result = await self.complete_mcp(ref=ref, argument=argument)
+        result = await self.complete_mcp(
+            ref=ref, argument=argument, context_arguments=context_arguments
+        )
         return result.completion
 
     # --- Tools ---

fastmcp/contrib/mcp_mixin/README.md

@@ -91,12 +91,12 @@ class MyComponent(MCPMixin):
     # prompt
     @mcp_prompt(name="A prompt")
     def prompt_method(self, name):
-        return f"Whats up {name}?"
+        return f"What's up {name}?"
 
     # disabled prompt
     @mcp_prompt(name="A prompt", enabled=False)
     def prompt_method(self, name):
-        return f"Whats up {name}?"
+        return f"What's up {name}?"
 
 mcp_server = FastMCP()
 component = MyComponent()

fastmcp/experimental/utilities/openapi/schemas.py

@@ -79,6 +79,7 @@ def _replace_ref_with_defs(
 
     Examples:
     - {"type": "object", "properties": {"$ref": "#/components/schemas/..."}}
+    - {"type": "object", "additionalProperties": {"$ref": "#/components/schemas/..."}, "properties": {...}}
     - {"$ref": "#/components/schemas/..."}
     - {"items": {"$ref": "#/components/schemas/..."}}
     - {"anyOf": [{"$ref": "#/components/schemas/..."}]}
@@ -117,6 +118,11 @@ def _replace_ref_with_defs(
     for section in ["anyOf", "allOf", "oneOf"]:
         for i, item in enumerate(schema.get(section, [])):
             schema[section][i] = _replace_ref_with_defs(item)
+    if additionalProperties := schema.get("additionalProperties"):
+        if not isinstance(additionalProperties, bool):
+            schema["additionalProperties"] = _replace_ref_with_defs(
+                additionalProperties
+            )
     if info.get("description", description) and not schema.get("description"):
         schema["description"] = description
     return schema
@@ -297,9 +303,11 @@ def _combine_schemas_and_map_params(
 
             # Convert refs if needed
             if convert_refs:
-                param_schema = _replace_ref_with_defs(param.schema_)
+                param_schema = _replace_ref_with_defs(param.schema_, param.description)
             else:
-                param_schema = param.schema_
+                param_schema = param.schema_.copy()
+                if param.description and not param_schema.get("description"):
+                    param_schema["description"] = param.description
             original_desc = param_schema.get("description", "")
             location_desc = f"({param.location.capitalize()} parameter)"
             if original_desc:
@@ -324,9 +332,11 @@ def _combine_schemas_and_map_params(
 
             # Convert refs if needed
             if convert_refs:
-                param_schema = _replace_ref_with_defs(param.schema_)
+                param_schema = _replace_ref_with_defs(param.schema_, param.description)
             else:
-                param_schema = param.schema_
+                param_schema = param.schema_.copy()
+                if param.description and not param_schema.get("description"):
+                    param_schema["description"] = param.description
 
             # Don't make optional parameters nullable - they can simply be omitted
             # The OpenAPI specification doesn't require optional parameters to accept null values
@@ -344,7 +354,7 @@ def _combine_schemas_and_map_params(
             if route.request_body.required:
                 required.append("body")
             parameter_map["body"] = {"location": "body", "openapi_name": "body"}
-        else:
+        elif body_props:
             # Normal case: body has properties
             for prop_name, prop_schema in body_props.items():
                 properties[prop_name] = prop_schema
@@ -357,6 +367,22 @@ def _combine_schemas_and_map_params(
 
             if route.request_body.required:
                 required.extend(body_schema.get("required", []))
+        else:
+            # Handle direct array/primitive schemas (like list[str] parameters from FastAPI)
+            # Use the schema title as parameter name, fall back to generic name
+            param_name = body_schema.get("title", "body").lower()
+
+            # Clean the parameter name to be valid
+            import re
+
+            param_name = re.sub(r"[^a-zA-Z0-9_]", "_", param_name)
+            if not param_name or param_name[0].isdigit():
+                param_name = "body_data"
+
+            properties[param_name] = body_schema
+            if route.request_body.required:
+                required.append(param_name)
+            parameter_map[param_name] = {"location": "body", "openapi_name": param_name}
 
     result = {
         "type": "object",

fastmcp/server/auth/auth.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 from typing import Any
-from urllib.parse import urljoin
 
 from mcp.server.auth.middleware.auth_context import AuthContextMiddleware
 from mcp.server.auth.middleware.bearer_auth import (
@@ -146,8 +145,9 @@ class AuthProvider(TokenVerifierProtocol):
             return None
 
         if path:
-            return AnyHttpUrl(urljoin(str(self.base_url), path))
-
+            prefix = str(self.base_url).rstrip("/")
+            suffix = path.lstrip("/")
+            return AnyHttpUrl(f"{prefix}/{suffix}")
         return self.base_url
 
 

fastmcp/server/auth/oauth_proxy.py

@@ -45,9 +45,11 @@ from starlette.requests import Request
 from starlette.responses import RedirectResponse
 from starlette.routing import Route
 
+import fastmcp
 from fastmcp.server.auth.auth import OAuthProvider, TokenVerifier
 from fastmcp.server.auth.redirect_validation import validate_redirect_uri
 from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.storage import JSONFileStorage, KVStorage
 
 if TYPE_CHECKING:
     pass
@@ -240,7 +242,7 @@ class OAuthProxy(OAuthProvider):
         token_verifier: TokenVerifier,
         # FastMCP server configuration
         base_url: AnyHttpUrl | str,
-        redirect_path: str = "/auth/callback",
+        redirect_path: str | None = None,
         issuer_url: AnyHttpUrl | str | None = None,
         service_documentation_url: AnyHttpUrl | str | None = None,
         # Client redirect URI validation
@@ -254,6 +256,8 @@ class OAuthProxy(OAuthProvider):
         extra_authorize_params: dict[str, str] | None = None,
         # Extra parameters to forward to token endpoint
         extra_token_params: dict[str, str] | None = None,
+        # Client storage
+        client_storage: KVStorage | None = None,
     ):
         """Initialize the OAuth proxy provider.
 
@@ -277,7 +281,7 @@ class OAuthProxy(OAuthProvider):
             valid_scopes: List of all the possible valid scopes for a client.
                 These are advertised to clients through the `/.well-known` endpoints. Defaults to `required_scopes` if not provided.
             forward_pkce: Whether to forward PKCE to upstream server (default True).
-                Enable for providers that support/require PKCE (Google, Azure, etc.).
+                Enable for providers that support/require PKCE (Google, Azure, AWS, etc.).
                 Disable only if upstream provider doesn't support PKCE.
             token_endpoint_auth_method: Token endpoint authentication method for upstream server.
                 Common values: "client_secret_basic", "client_secret_post", "none".
@@ -287,6 +291,9 @@ class OAuthProxy(OAuthProvider):
                 Example: {"audience": "https://api.example.com"}
             extra_token_params: Additional parameters to forward to the upstream token endpoint.
                 Useful for provider-specific parameters during token exchange.
+            client_storage: Storage implementation for OAuth client registrations.
+                Defaults to file-based storage in ~/.fastmcp/oauth-proxy-clients/ if not specified.
+                Pass any KVStorage implementation for custom storage backends.
         """
         # Always enable DCR since we implement it locally for MCP clients
         client_registration_options = ClientRegistrationOptions(
@@ -317,9 +324,12 @@ class OAuthProxy(OAuthProvider):
         self._default_scope_str = " ".join(self.required_scopes or [])
 
         # Store redirect configuration
-        self._redirect_path = (
-            redirect_path if redirect_path.startswith("/") else f"/{redirect_path}"
-        )
+        if not redirect_path:
+            self._redirect_path = "/auth/callback"
+        else:
+            self._redirect_path = (
+                redirect_path if redirect_path.startswith("/") else f"/{redirect_path}"
+            )
         self._allowed_client_redirect_uris = allowed_client_redirect_uris
 
         # PKCE configuration
@@ -332,8 +342,13 @@ class OAuthProxy(OAuthProvider):
         self._extra_authorize_params = extra_authorize_params or {}
         self._extra_token_params = extra_token_params or {}
 
-        # Local state for DCR and token bookkeeping
-        self._clients: dict[str, OAuthClientInformationFull] = {}
+        # Initialize client storage (default to file-based if not provided)
+        if client_storage is None:
+            cache_dir = fastmcp.settings.home / "oauth-proxy-clients"
+            client_storage = JSONFileStorage(cache_dir)
+        self._client_storage = client_storage
+
+        # Local state for token bookkeeping only (no client caching)
         self._access_tokens: dict[str, AccessToken] = {}
         self._refresh_tokens: dict[str, RefreshToken] = {}
 
@@ -384,9 +399,20 @@ class OAuthProxy(OAuthProvider):
 
         For unregistered clients, returns None (which will raise an error in the SDK).
         """
-        client = self._clients.get(client_id)
+        # Load from storage
+        data = await self._client_storage.get(client_id)
+        if not data:
+            return None
+
+        if client_data := data.get("client", None):
+            return ProxyDCRClient(
+                allowed_redirect_uri_patterns=data.get(
+                    "allowed_redirect_uri_patterns", self._allowed_client_redirect_uris
+                ),
+                **client_data,
+            )
 
-        return client
+        return None
 
     async def register_client(self, client_info: OAuthClientInformationFull) -> None:
         """Register a client locally
@@ -404,13 +430,17 @@ class OAuthProxy(OAuthProvider):
             redirect_uris=client_info.redirect_uris or [AnyUrl("http://localhost")],
             grant_types=client_info.grant_types
             or ["authorization_code", "refresh_token"],
-            scope=self._default_scope_str,
+            scope=client_info.scope or self._default_scope_str,
             token_endpoint_auth_method="none",
             allowed_redirect_uri_patterns=self._allowed_client_redirect_uris,
         )
 
-        # Store the ProxyDCRClient
-        self._clients[client_info.client_id] = proxy_client
+        # Store as structured dict with all needed metadata
+        storage_data = {
+            "client": proxy_client.model_dump(mode="json"),
+            "allowed_redirect_uri_patterns": self._allowed_client_redirect_uris,
+        }
+        await self._client_storage.set(client_info.client_id, storage_data)
 
         # Log redirect URIs to help users discover what patterns they might need
         if client_info.redirect_uris: