From 8ea1cc75c7027cee821ffb62409cde65e647e672 Mon Sep 17 00:00:00 2001 From: "marvin-context-protocol[bot]" <225465937+marvin-context-protocol[bot]@users.noreply.github.com> Date: Fri, 26 Sep 2025 18:28:43 -0400 Subject: [PATCH] chore: Update SDK documentation (#1783) Co-authored-by: marvin-context-protocol[bot] <225465937+marvin-context-protocol[bot]@users.noreply.github.com> --- docs/docs.json | 34 +++- docs/python-sdk/fastmcp-cli-cli.mdx | 4 +- .../fastmcp-cli-install-gemini_cli.mdx | 2 +- docs/python-sdk/fastmcp-client-auth-oauth.mdx | 37 ++-- docs/python-sdk/fastmcp-client-client.mdx | 18 +- docs/python-sdk/fastmcp-server-auth-auth.mdx | 10 +- .../fastmcp-server-auth-oauth_proxy.mdx | 26 +-- .../fastmcp-server-auth-oidc_proxy.mdx | 82 +++++++++ .../fastmcp-server-auth-providers-auth0.mdx | 47 ++++++ .../fastmcp-server-auth-providers-aws.mdx | 88 ++++++++++ .../fastmcp-server-auth-providers-azure.mdx | 8 +- .../fastmcp-server-auth-providers-descope.mdx | 62 +++++++ .../fastmcp-server-auth-providers-github.mdx | 8 +- .../fastmcp-server-auth-providers-google.mdx | 8 +- ...fastmcp-server-auth-providers-scalekit.mdx | 64 +++++++ .../fastmcp-server-auth-providers-workos.mdx | 14 +- docs/python-sdk/fastmcp-server-context.mdx | 72 ++++---- .../fastmcp-server-middleware-logging.mdx | 31 ++-- .../fastmcp-server-middleware-middleware.mdx | 32 ++-- docs/python-sdk/fastmcp-server-server.mdx | 66 ++++---- docs/python-sdk/fastmcp-settings.mdx | 26 +-- .../fastmcp-utilities-json_schema.mdx | 2 +- docs/python-sdk/fastmcp-utilities-logging.mdx | 22 ++- ...mcp_server_config-v1-mcp_server_config.mdx | 2 +- docs/python-sdk/fastmcp-utilities-storage.mdx | 158 ++++++++++++++++++ docs/python-sdk/fastmcp-utilities-tests.mdx | 8 +- 26 files changed, 737 insertions(+), 194 deletions(-) create mode 100644 docs/python-sdk/fastmcp-server-auth-oidc_proxy.mdx create mode 100644 docs/python-sdk/fastmcp-server-auth-providers-auth0.mdx create mode 100644 docs/python-sdk/fastmcp-server-auth-providers-aws.mdx create mode 100644 docs/python-sdk/fastmcp-server-auth-providers-descope.mdx create mode 100644 docs/python-sdk/fastmcp-server-auth-providers-scalekit.mdx create mode 100644 docs/python-sdk/fastmcp-utilities-storage.mdx diff --git a/docs/docs.json b/docs/docs.json index 8517207fd..758eca70f 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -11,9 +11,6 @@ }, "decoration": "windows" }, - "contextual": { - "options": ["copy", "view"] - }, "banner": { "content": "Host your server on [FastMCP Cloud](https://fastmcp.cloud) for free!" }, @@ -22,6 +19,12 @@ "light": "#4cc9f0", "primary": "#2d00f7" }, + "contextual": { + "options": [ + "copy", + "view" + ] + }, "description": "The fast, Pythonic way to build MCP servers and clients.", "favicon": { "dark": "/assets/brand/favicon.svg", @@ -51,8 +54,8 @@ "links": [ { "href": "https://fastmcp.cloud", - "label": "FastMCP Cloud", - "icon": "cloud" + "icon": "cloud", + "label": "FastMCP Cloud" } ], "primary": { @@ -129,7 +132,10 @@ { "group": "Essentials", "icon": "cube", - "pages": ["clients/client", "clients/transports"] + "pages": [ + "clients/client", + "clients/transports" + ] }, { "group": "Core Operations", @@ -155,7 +161,10 @@ { "group": "Authentication", "icon": "user-shield", - "pages": ["clients/auth/oauth", "clients/auth/bearer"] + "pages": [ + "clients/auth/oauth", + "clients/auth/bearer" + ] } ] }, @@ -238,7 +247,10 @@ "tab": "Documentation" }, { - "pages": ["updates", "changelog"], + "pages": [ + "updates", + "changelog" + ], "tab": "What's New" }, { @@ -322,16 +334,21 @@ "python-sdk/fastmcp-server-auth-__init__", "python-sdk/fastmcp-server-auth-auth", "python-sdk/fastmcp-server-auth-oauth_proxy", + "python-sdk/fastmcp-server-auth-oidc_proxy", { "group": "providers", "pages": [ "python-sdk/fastmcp-server-auth-providers-__init__", + "python-sdk/fastmcp-server-auth-providers-auth0", + "python-sdk/fastmcp-server-auth-providers-aws", "python-sdk/fastmcp-server-auth-providers-azure", "python-sdk/fastmcp-server-auth-providers-bearer", + "python-sdk/fastmcp-server-auth-providers-descope", "python-sdk/fastmcp-server-auth-providers-github", "python-sdk/fastmcp-server-auth-providers-google", "python-sdk/fastmcp-server-auth-providers-in_memory", "python-sdk/fastmcp-server-auth-providers-jwt", + "python-sdk/fastmcp-server-auth-providers-scalekit", "python-sdk/fastmcp-server-auth-providers-workos" ] }, @@ -412,6 +429,7 @@ ] }, "python-sdk/fastmcp-utilities-openapi", + "python-sdk/fastmcp-utilities-storage", "python-sdk/fastmcp-utilities-tests", "python-sdk/fastmcp-utilities-types" ] diff --git a/docs/python-sdk/fastmcp-cli-cli.mdx b/docs/python-sdk/fastmcp-cli-cli.mdx index 2e482fc7c..a6f4ee13b 100644 --- a/docs/python-sdk/fastmcp-cli-cli.mdx +++ b/docs/python-sdk/fastmcp-cli-cli.mdx @@ -74,7 +74,7 @@ fastmcp run server.py -- --config config.json --debug - `server_spec`: Python file, object specification (file\:obj), config file, URL, or None to auto-detect -### `inspect` +### `inspect` ```python inspect(server_spec: str | None = None) -> None @@ -105,7 +105,7 @@ fastmcp inspect # auto-detect fastmcp.json - `server_spec`: Python file to inspect, optionally with \:object suffix, or fastmcp.json -### `prepare` +### `prepare` ```python prepare(config_path: Annotated[str | None, cyclopts.Parameter(help='Path to fastmcp.json configuration file')] = None, output_dir: Annotated[str | None, cyclopts.Parameter(help='Directory to create the persistent environment in')] = None, skip_source: Annotated[bool, cyclopts.Parameter(help='Skip source preparation (e.g., git clone)')] = False) -> None diff --git a/docs/python-sdk/fastmcp-cli-install-gemini_cli.mdx b/docs/python-sdk/fastmcp-cli-install-gemini_cli.mdx index 1e2a647dd..7cbf60153 100644 --- a/docs/python-sdk/fastmcp-cli-install-gemini_cli.mdx +++ b/docs/python-sdk/fastmcp-cli-install-gemini_cli.mdx @@ -54,7 +54,7 @@ Install FastMCP server in Gemini CLI. - True if installation was successful, False otherwise -### `gemini_cli_command` +### `gemini_cli_command` ```python gemini_cli_command(server_spec: str) -> None diff --git a/docs/python-sdk/fastmcp-client-auth-oauth.mdx b/docs/python-sdk/fastmcp-client-auth-oauth.mdx index a5781a6aa..cc3dd7cf5 100644 --- a/docs/python-sdk/fastmcp-client-auth-oauth.mdx +++ b/docs/python-sdk/fastmcp-client-auth-oauth.mdx @@ -13,7 +13,7 @@ sidebarTitle: oauth default_cache_dir() -> Path ``` -### `check_if_auth_required` +### `check_if_auth_required` ```python check_if_auth_required(mcp_url: str, httpx_kwargs: dict[str, Any] | None = None) -> bool @@ -47,11 +47,12 @@ File-based token storage implementation for OAuth credentials and tokens. 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. **Methods:** -#### `get_base_url` +#### `get_base_url` ```python get_base_url(url: str) -> str @@ -60,16 +61,7 @@ get_base_url(url: str) -> str Extract the base URL (scheme + host) from a URL. -#### `get_cache_key` - -```python -get_cache_key(self) -> str -``` - -Generate a safe filesystem key from the server's base URL. - - -#### `get_tokens` +#### `get_tokens` ```python get_tokens(self) -> OAuthToken | None @@ -78,7 +70,7 @@ get_tokens(self) -> OAuthToken | None Load tokens from file storage. -#### `set_tokens` +#### `set_tokens` ```python set_tokens(self, tokens: OAuthToken) -> None @@ -87,7 +79,7 @@ set_tokens(self, tokens: OAuthToken) -> None Save tokens to file storage. -#### `get_client_info` +#### `get_client_info` ```python get_client_info(self) -> OAuthClientInformationFull | None @@ -96,7 +88,7 @@ get_client_info(self) -> OAuthClientInformationFull | None Load client information from file storage. -#### `set_client_info` +#### `set_client_info` ```python set_client_info(self, client_info: OAuthClientInformationFull) -> None @@ -105,7 +97,7 @@ set_client_info(self, client_info: OAuthClientInformationFull) -> None Save client information to file storage. -#### `clear` +#### `clear` ```python clear(self) -> None @@ -113,8 +105,11 @@ clear(self) -> None 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. -#### `clear_all` + +#### `clear_all` ```python clear_all(cls, cache_dir: Path | None = None) -> None @@ -123,7 +118,7 @@ clear_all(cls, cache_dir: Path | None = None) -> None Clear all cached data for all servers. -### `OAuth` +### `OAuth` OAuth client provider for MCP servers with browser-based authentication. @@ -134,7 +129,7 @@ a browser for user authorization and running a local callback server. **Methods:** -#### `redirect_handler` +#### `redirect_handler` ```python redirect_handler(self, authorization_url: str) -> None @@ -143,7 +138,7 @@ redirect_handler(self, authorization_url: str) -> None Open browser for authorization, with pre-flight check for invalid client. -#### `callback_handler` +#### `callback_handler` ```python callback_handler(self) -> tuple[str, str | None] @@ -152,7 +147,7 @@ callback_handler(self) -> tuple[str, str | None] Handle OAuth callback and return (auth_code, state). -#### `async_auth_flow` +#### `async_auth_flow` ```python async_auth_flow(self, request: httpx.Request) -> AsyncGenerator[httpx.Request, httpx.Response] diff --git a/docs/python-sdk/fastmcp-client-client.mdx b/docs/python-sdk/fastmcp-client-client.mdx index 87d8223d3..e089c8201 100644 --- a/docs/python-sdk/fastmcp-client-client.mdx +++ b/docs/python-sdk/fastmcp-client-client.mdx @@ -382,7 +382,8 @@ Send a completion request and return the complete MCP protocol result. **Args:** - `ref`: The reference to complete. - `argument`: Arguments to pass to the completion request. -- `context_arguments`: Optional context arguments to include with the completion request. Defaults to None. +- `context_arguments`: Optional context arguments to +include with the completion request. Defaults to None. **Returns:** - mcp.types.CompleteResult: The complete response object from the protocol, @@ -403,7 +404,8 @@ Send a completion request to the server. **Args:** - `ref`: The reference to complete. - `argument`: Arguments to pass to the completion request. -- `context_arguments`: Optional context arguments to include with the completion request. Defaults to None. +- `context_arguments`: Optional context arguments to +include with the completion request. Defaults to None. **Returns:** - mcp.types.Completion: The completion object. @@ -412,7 +414,7 @@ Send a completion request to the server. - `RuntimeError`: If called while the client is not connected. -#### `list_tools_mcp` +#### `list_tools_mcp` ```python list_tools_mcp(self) -> mcp.types.ListToolsResult @@ -428,7 +430,7 @@ containing the list of tools and any additional metadata. - `RuntimeError`: If called while the client is not connected. -#### `list_tools` +#### `list_tools` ```python list_tools(self) -> list[mcp.types.Tool] @@ -443,7 +445,7 @@ Retrieve a list of tools available on the server. - `RuntimeError`: If called while the client is not connected. -#### `call_tool_mcp` +#### `call_tool_mcp` ```python call_tool_mcp(self, name: str, arguments: dict[str, Any], progress_handler: ProgressHandler | None = None, timeout: datetime.timedelta | float | int | None = None) -> mcp.types.CallToolResult @@ -468,7 +470,7 @@ containing the tool result and any additional metadata. - `RuntimeError`: If called while the client is not connected. -#### `call_tool` +#### `call_tool` ```python call_tool(self, name: str, arguments: dict[str, Any] | None = None, timeout: datetime.timedelta | float | int | None = None, progress_handler: ProgressHandler | None = None, raise_on_error: bool = True) -> CallToolResult @@ -498,10 +500,10 @@ raw result object. - `RuntimeError`: If called while the client is not connected. -#### `generate_name` +#### `generate_name` ```python generate_name(cls, name: str | None = None) -> str ``` -### `CallToolResult` +### `CallToolResult` diff --git a/docs/python-sdk/fastmcp-server-auth-auth.mdx b/docs/python-sdk/fastmcp-server-auth-auth.mdx index 72525e8b3..d95e116d2 100644 --- a/docs/python-sdk/fastmcp-server-auth-auth.mdx +++ b/docs/python-sdk/fastmcp-server-auth-auth.mdx @@ -7,13 +7,13 @@ sidebarTitle: auth ## Classes -### `AccessToken` +### `AccessToken` AccessToken that includes all JWT claims. -### `AuthProvider` +### `AuthProvider` Base class for all FastMCP authentication providers. @@ -26,7 +26,7 @@ custom authentication routes. **Methods:** -#### `verify_token` +#### `verify_token` ```python verify_token(self, token: str) -> AccessToken | None @@ -43,7 +43,7 @@ All auth providers must implement token verification. - AccessToken object if valid, None if invalid or expired -#### `get_routes` +#### `get_routes` ```python get_routes(self, mcp_path: str | None = None, mcp_endpoint: Any | None = None) -> list[Route] @@ -65,7 +65,7 @@ Each provider is responsible for creating whatever routes it needs: - List of routes for this provider, including protected MCP endpoints if provided -#### `get_middleware` +#### `get_middleware` ```python get_middleware(self) -> list diff --git a/docs/python-sdk/fastmcp-server-auth-oauth_proxy.mdx b/docs/python-sdk/fastmcp-server-auth-oauth_proxy.mdx index 4117f6afb..df2a262ba 100644 --- a/docs/python-sdk/fastmcp-server-auth-oauth_proxy.mdx +++ b/docs/python-sdk/fastmcp-server-auth-oauth_proxy.mdx @@ -26,7 +26,7 @@ production use with enterprise identity providers. ## Classes -### `ProxyDCRClient` +### `ProxyDCRClient` Client for DCR proxy with configurable redirect URI validation. @@ -56,7 +56,7 @@ arise from accepting arbitrary redirect URIs. **Methods:** -#### `validate_redirect_uri` +#### `validate_redirect_uri` ```python validate_redirect_uri(self, redirect_uri: AnyUrl | None) -> AnyUrl @@ -70,7 +70,7 @@ This is essential for cached token scenarios where the client may reconnect with a different port. -### `OAuthProxy` +### `OAuthProxy` OAuth provider that presents a DCR-compliant interface while proxying to non-DCR IDPs. @@ -181,7 +181,7 @@ Handles provider-specific requirements: **Methods:** -#### `get_client` +#### `get_client` ```python get_client(self, client_id: str) -> OAuthClientInformationFull | None @@ -193,7 +193,7 @@ provided to the DCR client during registration, not the upstream client ID. For unregistered clients, returns None (which will raise an error in the SDK). -#### `register_client` +#### `register_client` ```python register_client(self, client_info: OAuthClientInformationFull) -> None @@ -207,7 +207,7 @@ redirect URI will likely be localhost or unknown to the proxied IDP. The proxied IDP only knows about this server's fixed redirect URI. -#### `authorize` +#### `authorize` ```python authorize(self, client: OAuthClientInformationFull, params: AuthorizationParams) -> str @@ -222,7 +222,7 @@ This implements the DCR-compliant proxy pattern: 4. Redirect to IdP with our fixed callback URL and proxy's PKCE -#### `load_authorization_code` +#### `load_authorization_code` ```python load_authorization_code(self, client: OAuthClientInformationFull, authorization_code: str) -> AuthorizationCode | None @@ -234,7 +234,7 @@ Look up our client code and return authorization code object with PKCE challenge for validation. -#### `exchange_authorization_code` +#### `exchange_authorization_code` ```python exchange_authorization_code(self, client: OAuthClientInformationFull, authorization_code: AuthorizationCode) -> OAuthToken @@ -246,7 +246,7 @@ For the DCR-compliant proxy flow, we return the IdP tokens that were obtained during the IdP callback exchange. PKCE validation is handled by the MCP framework. -#### `load_refresh_token` +#### `load_refresh_token` ```python load_refresh_token(self, client: OAuthClientInformationFull, refresh_token: str) -> RefreshToken | None @@ -255,7 +255,7 @@ load_refresh_token(self, client: OAuthClientInformationFull, refresh_token: str) Load refresh token from local storage. -#### `exchange_refresh_token` +#### `exchange_refresh_token` ```python exchange_refresh_token(self, client: OAuthClientInformationFull, refresh_token: RefreshToken, scopes: list[str]) -> OAuthToken @@ -264,7 +264,7 @@ exchange_refresh_token(self, client: OAuthClientInformationFull, refresh_token: Exchange refresh token for new access token using authlib. -#### `load_access_token` +#### `load_access_token` ```python load_access_token(self, token: str) -> AccessToken | None @@ -276,7 +276,7 @@ Delegates to the JWT verifier which handles signature validation, expiration checking, and claims validation using the upstream JWKS. -#### `revoke_token` +#### `revoke_token` ```python revoke_token(self, token: AccessToken | RefreshToken) -> None @@ -288,7 +288,7 @@ Removes tokens from local storage and attempts to revoke them with the upstream server if a revocation endpoint is configured. -#### `get_routes` +#### `get_routes` ```python get_routes(self, mcp_path: str | None = None, mcp_endpoint: Any | None = None) -> list[Route] diff --git a/docs/python-sdk/fastmcp-server-auth-oidc_proxy.mdx b/docs/python-sdk/fastmcp-server-auth-oidc_proxy.mdx new file mode 100644 index 000000000..f20b2dcdf --- /dev/null +++ b/docs/python-sdk/fastmcp-server-auth-oidc_proxy.mdx @@ -0,0 +1,82 @@ +--- +title: oidc_proxy +sidebarTitle: oidc_proxy +--- + +# `fastmcp.server.auth.oidc_proxy` + + +OIDC Proxy Provider for FastMCP. + +This provider acts as a transparent proxy to an upstream OIDC compliant Authorization +Server. It leverages the OAuthProxy class to handle Dynamic Client Registration and +forwarding of all OAuth flows. + +This implementation is based on: + OpenID Connect Discovery 1.0 - https://openid.net/specs/openid-connect-discovery-1_0.html + OAuth 2.0 Authorization Server Metadata - https://datatracker.ietf.org/doc/html/rfc8414 + + +## Classes + +### `OIDCConfiguration` + + +OIDC Configuration. + + +**Methods:** + +#### `get_oidc_configuration` + +```python +get_oidc_configuration(cls, config_url: AnyHttpUrl) -> Self +``` + +Get the OIDC configuration for the specified config URL. + +**Args:** +- `config_url`: The OIDC config URL +- `strict`: The strict flag for the configuration +- `timeout_seconds`: HTTP request timeout in seconds + + +### `OIDCProxy` + + +OAuth provider that wraps OAuthProxy to provide configuration via an OIDC configuration URL. + +This provider makes it easier to add OAuth protection for any upstream provider +that is OIDC compliant. + + +**Methods:** + +#### `get_oidc_configuration` + +```python +get_oidc_configuration(self, config_url: AnyHttpUrl, strict: bool | None, timeout_seconds: int | None) -> OIDCConfiguration +``` + +Gets the OIDC configuration for the specified configuration URL. + +**Args:** +- `config_url`: The OIDC configuration URL +- `strict`: The strict flag for the configuration +- `timeout_seconds`: HTTP request timeout in seconds + + +#### `get_token_verifier` + +```python +get_token_verifier(self) -> TokenVerifier +``` + +Creates the token verifier for the specified OIDC configuration and arguments. + +**Args:** +- `algorithm`: Optional token verifier algorithm +- `audience`: Optional token verifier audience +- `required_scopes`: Optional token verifier required_scopes +- `timeout_seconds`: HTTP request timeout in seconds + diff --git a/docs/python-sdk/fastmcp-server-auth-providers-auth0.mdx b/docs/python-sdk/fastmcp-server-auth-providers-auth0.mdx new file mode 100644 index 000000000..344f29b64 --- /dev/null +++ b/docs/python-sdk/fastmcp-server-auth-providers-auth0.mdx @@ -0,0 +1,47 @@ +--- +title: auth0 +sidebarTitle: auth0 +--- + +# `fastmcp.server.auth.providers.auth0` + + +Auth0 OAuth provider for FastMCP. + +This module provides a complete Auth0 integration that's ready to use with +just the configuration URL, client ID, client secret, audience, and base URL. + +Example: + ```python + from fastmcp import FastMCP + from fastmcp.server.auth.providers.auth0 import Auth0Provider + + # Simple Auth0 OAuth protection + auth = Auth0Provider( + config_url="https://auth0.config.url", + client_id="your-auth0-client-id", + client_secret="your-auth0-client-secret", + audience="your-auth0-api-audience", + base_url="http://localhost:8000", + ) + + mcp = FastMCP("My Protected Server", auth=auth) + ``` + + +## Classes + +### `Auth0ProviderSettings` + + +Settings for Auth0 OIDC provider. + + +### `Auth0Provider` + + +An Auth0 provider implementation for FastMCP. + +This provider is a complete Auth0 integration that's ready to use with +just the configuration URL, client ID, client secret, audience, and base URL. + diff --git a/docs/python-sdk/fastmcp-server-auth-providers-aws.mdx b/docs/python-sdk/fastmcp-server-auth-providers-aws.mdx new file mode 100644 index 000000000..290951a5a --- /dev/null +++ b/docs/python-sdk/fastmcp-server-auth-providers-aws.mdx @@ -0,0 +1,88 @@ +--- +title: aws +sidebarTitle: aws +--- + +# `fastmcp.server.auth.providers.aws` + + +AWS Cognito OAuth provider for FastMCP. + +This module provides a complete AWS Cognito OAuth integration that's ready to use +with a user pool ID, domain prefix, client ID and client secret. It handles all +the complexity of AWS Cognito's OAuth flow, token validation, and user management. + +Example: + ```python + from fastmcp import FastMCP + from fastmcp.server.auth.providers.aws_cognito import AWSCognitoProvider + + # Simple AWS Cognito OAuth protection + auth = AWSCognitoProvider( + user_pool_id="your-user-pool-id", + aws_region="eu-central-1", + client_id="your-cognito-client-id", + client_secret="your-cognito-client-secret" + ) + + mcp = FastMCP("My Protected Server", auth=auth) + ``` + + +## Classes + +### `AWSCognitoProviderSettings` + + +Settings for AWS Cognito OAuth provider. + + +### `AWSCognitoTokenVerifier` + + +Token verifier that filters claims to Cognito-specific subset. + + +**Methods:** + +#### `verify_token` + +```python +verify_token(self, token: str) -> AccessToken | None +``` + +Verify token and filter claims to Cognito-specific subset. + + +### `AWSCognitoProvider` + + +Complete AWS Cognito OAuth provider for FastMCP. + +This provider makes it trivial to add AWS Cognito OAuth protection to any +FastMCP server using OIDC Discovery. Just provide your Cognito User Pool details, +client credentials, and a base URL, and you're ready to go. + +Features: +- Automatic OIDC Discovery from AWS Cognito User Pool +- Automatic JWT token validation via Cognito's public keys +- Cognito-specific claim filtering (sub, username, cognito:groups) +- Support for Cognito User Pools + + +**Methods:** + +#### `get_token_verifier` + +```python +get_token_verifier(self) -> TokenVerifier +``` + +Creates a Cognito-specific token verifier with claim filtering. + +**Args:** +- `algorithm`: Optional token verifier algorithm +- `audience`: Optional token verifier audience +- `required_scopes`: Optional token verifier required_scopes +- `timeout_seconds`: HTTP request timeout in seconds + diff --git a/docs/python-sdk/fastmcp-server-auth-providers-azure.mdx b/docs/python-sdk/fastmcp-server-auth-providers-azure.mdx index d1fb83d83..463e5f731 100644 --- a/docs/python-sdk/fastmcp-server-auth-providers-azure.mdx +++ b/docs/python-sdk/fastmcp-server-auth-providers-azure.mdx @@ -14,13 +14,13 @@ using the OAuth Proxy pattern for non-DCR OAuth flows. ## Classes -### `AzureProviderSettings` +### `AzureProviderSettings` Settings for Azure OAuth provider. -### `AzureTokenVerifier` +### `AzureTokenVerifier` Token verifier for Azure OAuth tokens. @@ -31,7 +31,7 @@ to get user information and validate the token. **Methods:** -#### `verify_token` +#### `verify_token` ```python verify_token(self, token: str) -> AccessToken | None @@ -40,7 +40,7 @@ verify_token(self, token: str) -> AccessToken | None Verify Azure OAuth token by calling Microsoft Graph API. -### `AzureProvider` +### `AzureProvider` Azure (Microsoft Entra) OAuth provider for FastMCP. diff --git a/docs/python-sdk/fastmcp-server-auth-providers-descope.mdx b/docs/python-sdk/fastmcp-server-auth-providers-descope.mdx new file mode 100644 index 000000000..2064a25b1 --- /dev/null +++ b/docs/python-sdk/fastmcp-server-auth-providers-descope.mdx @@ -0,0 +1,62 @@ +--- +title: descope +sidebarTitle: descope +--- + +# `fastmcp.server.auth.providers.descope` + + +Descope authentication provider for FastMCP. + +This module provides DescopeProvider - a complete authentication solution that integrates +with Descope's OAuth 2.1 and OpenID Connect services, supporting Dynamic Client Registration (DCR) +for seamless MCP client authentication. + + +## Classes + +### `DescopeProviderSettings` + +### `DescopeProvider` + + +Descope metadata provider for DCR (Dynamic Client Registration). + +This provider implements Descope integration using metadata forwarding. +This is the recommended approach for Descope DCR +as it allows Descope to handle the OAuth flow directly while FastMCP acts +as a resource server. + +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 + +2. Note your Project ID: + - Save your Project ID from [Project Settings](https://app.descope.com/settings/project) + - Example: P2abc...123 + +For detailed setup instructions, see: +https://docs.descope.com/identity-federation/inbound-apps/creating-inbound-apps#method-2-dynamic-client-registration-dcr + + +**Methods:** + +#### `get_routes` + +```python +get_routes(self, mcp_path: str | None = None, mcp_endpoint: Any | None = None) -> list[Route] +``` + +Get OAuth routes including Descope authorization server metadata forwarding. + +This returns the standard protected resource routes plus an authorization server +metadata endpoint that forwards Descope's OAuth metadata to clients. + +**Args:** +- `mcp_path`: The path where the MCP endpoint is mounted (e.g., "/mcp") +- `mcp_endpoint`: The MCP endpoint handler to protect with auth + diff --git a/docs/python-sdk/fastmcp-server-auth-providers-github.mdx b/docs/python-sdk/fastmcp-server-auth-providers-github.mdx index 39ad189b0..e72034495 100644 --- a/docs/python-sdk/fastmcp-server-auth-providers-github.mdx +++ b/docs/python-sdk/fastmcp-server-auth-providers-github.mdx @@ -29,13 +29,13 @@ Example: ## Classes -### `GitHubProviderSettings` +### `GitHubProviderSettings` Settings for GitHub OAuth provider. -### `GitHubTokenVerifier` +### `GitHubTokenVerifier` Token verifier for GitHub OAuth tokens. @@ -46,7 +46,7 @@ by calling GitHub's API to check if they're valid and get user info. **Methods:** -#### `verify_token` +#### `verify_token` ```python verify_token(self, token: str) -> AccessToken | None @@ -55,7 +55,7 @@ verify_token(self, token: str) -> AccessToken | None Verify GitHub OAuth token by calling GitHub API. -### `GitHubProvider` +### `GitHubProvider` Complete GitHub OAuth provider for FastMCP. diff --git a/docs/python-sdk/fastmcp-server-auth-providers-google.mdx b/docs/python-sdk/fastmcp-server-auth-providers-google.mdx index 307246b15..20d3a63e9 100644 --- a/docs/python-sdk/fastmcp-server-auth-providers-google.mdx +++ b/docs/python-sdk/fastmcp-server-auth-providers-google.mdx @@ -29,13 +29,13 @@ Example: ## Classes -### `GoogleProviderSettings` +### `GoogleProviderSettings` Settings for Google OAuth provider. -### `GoogleTokenVerifier` +### `GoogleTokenVerifier` Token verifier for Google OAuth tokens. @@ -46,7 +46,7 @@ by calling Google's tokeninfo API to check if they're valid and get user info. **Methods:** -#### `verify_token` +#### `verify_token` ```python verify_token(self, token: str) -> AccessToken | None @@ -55,7 +55,7 @@ verify_token(self, token: str) -> AccessToken | None Verify Google OAuth token by calling Google's tokeninfo API. -### `GoogleProvider` +### `GoogleProvider` Complete Google OAuth provider for FastMCP. diff --git a/docs/python-sdk/fastmcp-server-auth-providers-scalekit.mdx b/docs/python-sdk/fastmcp-server-auth-providers-scalekit.mdx new file mode 100644 index 000000000..f1b9a5df0 --- /dev/null +++ b/docs/python-sdk/fastmcp-server-auth-providers-scalekit.mdx @@ -0,0 +1,64 @@ +--- +title: scalekit +sidebarTitle: scalekit +--- + +# `fastmcp.server.auth.providers.scalekit` + + +Scalekit authentication provider for FastMCP. + +This module provides ScalekitProvider - a complete authentication solution that integrates +with Scalekit's OAuth 2.1 and OpenID Connect services, supporting Resource Server +authentication for seamless MCP client authentication. + + +## Classes + +### `ScalekitProviderSettings` + +### `ScalekitProvider` + + +Scalekit resource server provider for OAuth 2.1 authentication. + +This provider implements Scalekit integration using resource server pattern. +FastMCP acts as a protected resource server that validates access tokens issued +by Scalekit's authorization server. + +IMPORTANT SETUP REQUIREMENTS: + +1. Create an MCP Server in Scalekit Dashboard: + - Go to your [Scalekit Dashboard](https://app.scalekit.com/) + - Navigate to MCP Servers section + - Register a new MCP Server with appropriate scopes + - Ensure the Resource Identifier matches exactly what you configure as MCP URL + - Note the Resource ID + +2. Environment Configuration: + - Set SCALEKIT_ENVIRONMENT_URL (e.g., https://your-env.scalekit.com) + - Set SCALEKIT_CLIENT_ID from your OAuth application + - Set SCALEKIT_RESOURCE_ID from your created resource + - Set MCP_URL to your FastMCP server's public URL + +For detailed setup instructions, see: +https://docs.scalekit.com/mcp/overview/ + + +**Methods:** + +#### `get_routes` + +```python +get_routes(self, mcp_path: str | None = None, mcp_endpoint: Any | None = None) -> list[Route] +``` + +Get OAuth routes including Scalekit authorization server metadata forwarding. + +This returns the standard protected resource routes plus an authorization server +metadata endpoint that forwards Scalekit's OAuth metadata to clients. + +**Args:** +- `mcp_path`: The path where the MCP endpoint is mounted (e.g., "/mcp") +- `mcp_endpoint`: The MCP endpoint handler to protect with auth + diff --git a/docs/python-sdk/fastmcp-server-auth-providers-workos.mdx b/docs/python-sdk/fastmcp-server-auth-providers-workos.mdx index 3132111f1..a4ac73e02 100644 --- a/docs/python-sdk/fastmcp-server-auth-providers-workos.mdx +++ b/docs/python-sdk/fastmcp-server-auth-providers-workos.mdx @@ -18,13 +18,13 @@ Choose based on your WorkOS setup and authentication requirements. ## Classes -### `WorkOSProviderSettings` +### `WorkOSProviderSettings` Settings for WorkOS OAuth provider. -### `WorkOSTokenVerifier` +### `WorkOSTokenVerifier` Token verifier for WorkOS OAuth tokens. @@ -35,7 +35,7 @@ the /oauth2/userinfo endpoint to check validity and get user info. **Methods:** -#### `verify_token` +#### `verify_token` ```python verify_token(self, token: str) -> AccessToken | None @@ -44,7 +44,7 @@ verify_token(self, token: str) -> AccessToken | None Verify WorkOS OAuth token by calling userinfo endpoint. -### `WorkOSProvider` +### `WorkOSProvider` Complete WorkOS OAuth provider for FastMCP. @@ -65,9 +65,9 @@ Setup Requirements: 4. Note your Client ID and Client Secret -### `AuthKitProviderSettings` +### `AuthKitProviderSettings` -### `AuthKitProvider` +### `AuthKitProvider` AuthKit metadata provider for DCR (Dynamic Client Registration). @@ -93,7 +93,7 @@ https://workos.com/docs/authkit/mcp/integrating/token-verification **Methods:** -#### `get_routes` +#### `get_routes` ```python get_routes(self, mcp_path: str | None = None, mcp_endpoint: Any | None = None) -> list[Route] diff --git a/docs/python-sdk/fastmcp-server-context.mdx b/docs/python-sdk/fastmcp-server-context.mdx index bbc14d0ee..f828d513f 100644 --- a/docs/python-sdk/fastmcp-server-context.mdx +++ b/docs/python-sdk/fastmcp-server-context.mdx @@ -7,7 +7,7 @@ sidebarTitle: context ## Functions -### `set_context` +### `set_context` ```python set_context(context: Context) -> Generator[Context, None, None] @@ -15,7 +15,7 @@ set_context(context: Context) -> Generator[Context, None, None] ## Classes -### `LogData` +### `LogData` Data object for passing log arguments to client-side handlers. @@ -24,7 +24,7 @@ This provides an interface to match the Python standard library logging, for compatibility with structured logging. -### `Context` +### `Context` Context object providing access to MCP capabilities. @@ -36,18 +36,18 @@ To use context in a tool function, add a parameter with the Context type annotat ```python @server.tool -def my_tool(x: int, ctx: Context) -> str: +async def my_tool(x: int, ctx: Context) -> str: # Log messages to the client - ctx.info(f"Processing {x}") - ctx.debug("Debug info") - ctx.warning("Warning message") - ctx.error("Error message") + await ctx.info(f"Processing {x}") + await ctx.debug("Debug info") + await ctx.warning("Warning message") + await ctx.error("Error message") # Report progress - ctx.report_progress(50, 100, "Processing") + await ctx.report_progress(50, 100, "Processing") # Access resources - data = ctx.read_resource("resource://data") + data = await ctx.read_resource("resource://data") # Get request info request_id = ctx.request_id @@ -72,7 +72,7 @@ The context is optional - tools that don't need it can omit the parameter. **Methods:** -#### `fastmcp` +#### `fastmcp` ```python fastmcp(self) -> FastMCP @@ -81,7 +81,7 @@ fastmcp(self) -> FastMCP Get the FastMCP instance. -#### `request_context` +#### `request_context` ```python request_context(self) -> RequestContext[ServerSession, Any, Request] @@ -92,7 +92,7 @@ Access to the underlying request context. If called outside of a request context, this will raise a ValueError. -#### `report_progress` +#### `report_progress` ```python report_progress(self, progress: float, total: float | None = None, message: str | None = None) -> None @@ -105,7 +105,7 @@ Report progress for the current operation. - `total`: Optional total value e.g. 100 -#### `read_resource` +#### `read_resource` ```python read_resource(self, uri: str | AnyUrl) -> list[ReadResourceContents] @@ -120,7 +120,7 @@ Read a resource by URI. - The resource content as either text or bytes -#### `log` +#### `log` ```python log(self, message: str, level: LoggingLevel | None = None, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None @@ -136,7 +136,7 @@ Send a log message to the client. - `extra`: Optional mapping for additional arguments -#### `client_id` +#### `client_id` ```python client_id(self) -> str | None @@ -145,7 +145,7 @@ client_id(self) -> str | None Get the client ID if available. -#### `request_id` +#### `request_id` ```python request_id(self) -> str @@ -154,7 +154,7 @@ request_id(self) -> str Get the unique ID for this request. -#### `session_id` +#### `session_id` ```python session_id(self) -> str @@ -171,7 +171,7 @@ the same client session. - for other transports. -#### `session` +#### `session` ```python session(self) -> ServerSession @@ -180,7 +180,7 @@ session(self) -> ServerSession Access to the underlying session for advanced usage. -#### `debug` +#### `debug` ```python debug(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None @@ -189,7 +189,7 @@ debug(self, message: str, logger_name: str | None = None, extra: Mapping[str, An Send a debug log message. -#### `info` +#### `info` ```python info(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None @@ -198,7 +198,7 @@ info(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any Send an info log message. -#### `warning` +#### `warning` ```python warning(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None @@ -207,7 +207,7 @@ warning(self, message: str, logger_name: str | None = None, extra: Mapping[str, Send a warning log message. -#### `error` +#### `error` ```python error(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None @@ -216,7 +216,7 @@ error(self, message: str, logger_name: str | None = None, extra: Mapping[str, An Send an error log message. -#### `list_roots` +#### `list_roots` ```python list_roots(self) -> list[Root] @@ -225,7 +225,7 @@ list_roots(self) -> list[Root] List the roots available to the server, as indicated by the client. -#### `send_tool_list_changed` +#### `send_tool_list_changed` ```python send_tool_list_changed(self) -> None @@ -234,7 +234,7 @@ send_tool_list_changed(self) -> None Send a tool list changed notification to the client. -#### `send_resource_list_changed` +#### `send_resource_list_changed` ```python send_resource_list_changed(self) -> None @@ -243,7 +243,7 @@ send_resource_list_changed(self) -> None Send a resource list changed notification to the client. -#### `send_prompt_list_changed` +#### `send_prompt_list_changed` ```python send_prompt_list_changed(self) -> None @@ -252,10 +252,10 @@ send_prompt_list_changed(self) -> None Send a prompt list changed notification to the client. -#### `sample` +#### `sample` ```python -sample(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) -> ContentBlock +sample(self, messages: str | Sequence[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) -> TextContent | ImageContent | AudioContent ``` Send a sampling request to the client and await the response. @@ -265,25 +265,25 @@ completion from the client. The client must be appropriately configured, or the request will error. -#### `elicit` +#### `elicit` ```python elicit(self, message: str, response_type: None) -> AcceptedElicitation[dict[str, Any]] | DeclinedElicitation | CancelledElicitation ``` -#### `elicit` +#### `elicit` ```python elicit(self, message: str, response_type: type[T]) -> AcceptedElicitation[T] | DeclinedElicitation | CancelledElicitation ``` -#### `elicit` +#### `elicit` ```python elicit(self, message: str, response_type: list[str]) -> AcceptedElicitation[str] | DeclinedElicitation | CancelledElicitation ``` -#### `elicit` +#### `elicit` ```python elicit(self, message: str, response_type: type[T] | list[str] | None = None) -> AcceptedElicitation[T] | AcceptedElicitation[dict[str, Any]] | AcceptedElicitation[str] | DeclinedElicitation | CancelledElicitation @@ -312,7 +312,7 @@ type or dataclass or BaseModel. If it is a primitive type, an object schema with a single "value" field will be generated. -#### `get_http_request` +#### `get_http_request` ```python get_http_request(self) -> Request @@ -321,7 +321,7 @@ get_http_request(self) -> Request Get the active starlette request. -#### `set_state` +#### `set_state` ```python set_state(self, key: str, value: Any) -> None @@ -330,7 +330,7 @@ set_state(self, key: str, value: Any) -> None Set a value in the context state. -#### `get_state` +#### `get_state` ```python get_state(self, key: str) -> Any diff --git a/docs/python-sdk/fastmcp-server-middleware-logging.mdx b/docs/python-sdk/fastmcp-server-middleware-logging.mdx index 853725a01..fd6ee041c 100644 --- a/docs/python-sdk/fastmcp-server-middleware-logging.mdx +++ b/docs/python-sdk/fastmcp-server-middleware-logging.mdx @@ -22,18 +22,15 @@ The default serializer for Payloads in the logging middleware. ## Classes -### `LoggingMiddleware` +### `BaseLoggingMiddleware` -Middleware that provides comprehensive request and response logging. - -Logs all MCP messages with configurable detail levels. Useful for debugging, -monitoring, and understanding server usage patterns. +Base class for logging middleware. **Methods:** -#### `on_message` +#### `on_message` ```python on_message(self, context: MiddlewareContext[Any], call_next: CallNext[Any, Any]) -> Any @@ -42,7 +39,16 @@ on_message(self, context: MiddlewareContext[Any], call_next: CallNext[Any, Any]) Log all messages. -### `StructuredLoggingMiddleware` +### `LoggingMiddleware` + + +Middleware that provides comprehensive request and response logging. + +Logs all MCP messages with configurable detail levels. Useful for debugging, +monitoring, and understanding server usage patterns. + + +### `StructuredLoggingMiddleware` Middleware that provides structured JSON logging for better log analysis. @@ -50,14 +56,3 @@ Middleware that provides structured JSON logging for better log analysis. Outputs structured logs that are easier to parse and analyze with log aggregation tools like ELK stack, Splunk, or cloud logging services. - -**Methods:** - -#### `on_message` - -```python -on_message(self, context: MiddlewareContext[Any], call_next: CallNext[Any, Any]) -> Any -``` - -Log structured message information. - diff --git a/docs/python-sdk/fastmcp-server-middleware-middleware.mdx b/docs/python-sdk/fastmcp-server-middleware-middleware.mdx index 806acaecc..a530af4b1 100644 --- a/docs/python-sdk/fastmcp-server-middleware-middleware.mdx +++ b/docs/python-sdk/fastmcp-server-middleware-middleware.mdx @@ -7,7 +7,7 @@ sidebarTitle: middleware ## Functions -### `make_middleware_wrapper` +### `make_middleware_wrapper` ```python make_middleware_wrapper(middleware: Middleware, call_next: CallNext[T, R]) -> CallNext[T, R] @@ -21,9 +21,9 @@ passed to other functions that expect a call_next function. ## Classes -### `CallNext` +### `CallNext` -### `MiddlewareContext` +### `MiddlewareContext` Unified context for all middleware operations. @@ -31,13 +31,13 @@ Unified context for all middleware operations. **Methods:** -#### `copy` +#### `copy` ```python copy(self, **kwargs: Any) -> MiddlewareContext[T] ``` -### `Middleware` +### `Middleware` Base class for FastMCP middleware with dispatching hooks. @@ -45,61 +45,61 @@ Base class for FastMCP middleware with dispatching hooks. **Methods:** -#### `on_message` +#### `on_message` ```python on_message(self, context: MiddlewareContext[Any], call_next: CallNext[Any, Any]) -> Any ``` -#### `on_request` +#### `on_request` ```python on_request(self, context: MiddlewareContext[mt.Request], call_next: CallNext[mt.Request, Any]) -> Any ``` -#### `on_notification` +#### `on_notification` ```python on_notification(self, context: MiddlewareContext[mt.Notification], call_next: CallNext[mt.Notification, Any]) -> Any ``` -#### `on_call_tool` +#### `on_call_tool` ```python on_call_tool(self, context: MiddlewareContext[mt.CallToolRequestParams], call_next: CallNext[mt.CallToolRequestParams, ToolResult]) -> ToolResult ``` -#### `on_read_resource` +#### `on_read_resource` ```python -on_read_resource(self, context: MiddlewareContext[mt.ReadResourceRequestParams], call_next: CallNext[mt.ReadResourceRequestParams, mt.ReadResourceResult]) -> mt.ReadResourceResult +on_read_resource(self, context: MiddlewareContext[mt.ReadResourceRequestParams], call_next: CallNext[mt.ReadResourceRequestParams, list[ReadResourceContents]]) -> list[ReadResourceContents] ``` -#### `on_get_prompt` +#### `on_get_prompt` ```python on_get_prompt(self, context: MiddlewareContext[mt.GetPromptRequestParams], call_next: CallNext[mt.GetPromptRequestParams, mt.GetPromptResult]) -> mt.GetPromptResult ``` -#### `on_list_tools` +#### `on_list_tools` ```python on_list_tools(self, context: MiddlewareContext[mt.ListToolsRequest], call_next: CallNext[mt.ListToolsRequest, list[Tool]]) -> list[Tool] ``` -#### `on_list_resources` +#### `on_list_resources` ```python on_list_resources(self, context: MiddlewareContext[mt.ListResourcesRequest], call_next: CallNext[mt.ListResourcesRequest, list[Resource]]) -> list[Resource] ``` -#### `on_list_resource_templates` +#### `on_list_resource_templates` ```python on_list_resource_templates(self, context: MiddlewareContext[mt.ListResourceTemplatesRequest], call_next: CallNext[mt.ListResourceTemplatesRequest, list[ResourceTemplate]]) -> list[ResourceTemplate] ``` -#### `on_list_prompts` +#### `on_list_prompts` ```python on_list_prompts(self, context: MiddlewareContext[mt.ListPromptsRequest], call_next: CallNext[mt.ListPromptsRequest, list[Prompt]]) -> list[Prompt] diff --git a/docs/python-sdk/fastmcp-server-server.mdx b/docs/python-sdk/fastmcp-server-server.mdx index dcaf8e12f..20b58f460 100644 --- a/docs/python-sdk/fastmcp-server-server.mdx +++ b/docs/python-sdk/fastmcp-server-server.mdx @@ -10,7 +10,7 @@ FastMCP - A more ergonomic interface for MCP servers. ## Functions -### `default_lifespan` +### `default_lifespan` ```python default_lifespan(server: FastMCP[LifespanResultT]) -> AsyncIterator[Any] @@ -26,7 +26,7 @@ Default lifespan context manager that does nothing. - An empty context object -### `add_resource_prefix` +### `add_resource_prefix` ```python add_resource_prefix(uri: str, prefix: str, prefix_format: Literal['protocol', 'path'] | None = None) -> str @@ -64,7 +64,7 @@ add_resource_prefix("resource:///absolute/path", "prefix") - `ValueError`: If the URI doesn't match the expected protocol\://path format -### `remove_resource_prefix` +### `remove_resource_prefix` ```python remove_resource_prefix(uri: str, prefix: str, prefix_format: Literal['protocol', 'path'] | None = None) -> str @@ -103,7 +103,7 @@ remove_resource_prefix("resource://prefix//absolute/path", "prefix") - `ValueError`: If the URI doesn't match the expected protocol\://path format -### `has_resource_prefix` +### `has_resource_prefix` ```python has_resource_prefix(uri: str, prefix: str, prefix_format: Literal['protocol', 'path'] | None = None) -> bool @@ -143,28 +143,34 @@ False ## Classes -### `FastMCP` +### `FastMCP` **Methods:** -#### `settings` +#### `settings` ```python settings(self) -> Settings ``` -#### `name` +#### `name` ```python name(self) -> str ``` -#### `instructions` +#### `instructions` ```python instructions(self) -> str | None ``` +#### `instructions` + +```python +instructions(self, value: str | None) -> None +``` + #### `version` ```python @@ -503,8 +509,8 @@ def get_weather(city: str) -> str: return f"Weather for {city}" @server.resource("resource://{city}/weather") -def get_weather_with_context(city: str, ctx: Context) -> str: - ctx.info(f"Fetching weather for {city}") +async def get_weather_with_context(city: str, ctx: Context) -> str: + await ctx.info(f"Fetching weather for {city}") return f"Weather for {city}" @server.resource("resource://{city}/weather") @@ -583,8 +589,8 @@ Decorator to register a prompt. ] @server.prompt() - def analyze_with_context(table_name: str, ctx: Context) -> list[Message]: - ctx.info(f"Analyzing table {table_name}") + async def analyze_with_context(table_name: str, ctx: Context) -> list[Message]: + await ctx.info(f"Analyzing table {table_name}") schema = read_table_schema(table_name) return [ { @@ -595,7 +601,7 @@ Decorator to register a prompt. ] @server.prompt("custom_name") - def analyze_file(path: str) -> list[Message]: + async def analyze_file(path: str) -> list[Message]: content = await read_file(path) return [ { @@ -622,13 +628,17 @@ Decorator to register a prompt. #### `run_stdio_async` ```python -run_stdio_async(self, show_banner: bool = True) -> None +run_stdio_async(self, show_banner: bool = True, log_level: str | None = None) -> None ``` Run the server using stdio transport. +**Args:** +- `show_banner`: Whether to display the server banner +- `log_level`: Log level for the server -#### `run_http_async` + +#### `run_http_async` ```python run_http_async(self, show_banner: bool = True, transport: Literal['http', 'streamable-http', 'sse'] = 'http', host: str | None = None, port: int | None = None, log_level: str | None = None, path: str | None = None, uvicorn_config: dict[str, Any] | None = None, middleware: list[ASGIMiddleware] | None = None, stateless_http: bool | None = None) -> None @@ -647,7 +657,7 @@ Run the server using HTTP transport. - `stateless_http`: Whether to use stateless HTTP (defaults to settings.stateless_http) -#### `run_sse_async` +#### `run_sse_async` ```python run_sse_async(self, host: str | None = None, port: int | None = None, log_level: str | None = None, path: str | None = None, uvicorn_config: dict[str, Any] | None = None) -> None @@ -656,7 +666,7 @@ run_sse_async(self, host: str | None = None, port: int | None = None, log_level: Run the server using SSE transport. -#### `sse_app` +#### `sse_app` ```python sse_app(self, path: str | None = None, message_path: str | None = None, middleware: list[ASGIMiddleware] | None = None) -> StarletteWithLifespan @@ -670,7 +680,7 @@ Create a Starlette app for the SSE server. - `middleware`: A list of middleware to apply to the app -#### `streamable_http_app` +#### `streamable_http_app` ```python streamable_http_app(self, path: str | None = None, middleware: list[ASGIMiddleware] | None = None) -> StarletteWithLifespan @@ -683,7 +693,7 @@ Create a Starlette app for the StreamableHTTP server. - `middleware`: A list of middleware to apply to the app -#### `http_app` +#### `http_app` ```python http_app(self, path: str | None = None, middleware: list[ASGIMiddleware] | None = None, json_response: bool | None = None, stateless_http: bool | None = None, transport: Literal['http', 'streamable-http', 'sse'] = 'http') -> StarletteWithLifespan @@ -700,13 +710,13 @@ Create a Starlette app using the specified HTTP transport. - A Starlette application configured with the specified transport -#### `run_streamable_http_async` +#### `run_streamable_http_async` ```python run_streamable_http_async(self, host: str | None = None, port: int | None = None, log_level: str | None = None, path: str | None = None, uvicorn_config: dict[str, Any] | None = None) -> None ``` -#### `mount` +#### `mount` ```python mount(self, server: FastMCP[LifespanResultT], prefix: str | None = None, as_proxy: bool | None = None) -> None @@ -760,7 +770,7 @@ automatically determined based on whether the server has a custom lifespan - `prompt_separator`: Deprecated. Separator character for prompt names. -#### `import_server` +#### `import_server` ```python import_server(self, server: FastMCP[LifespanResultT], prefix: str | None = None, tool_separator: str | None = None, resource_separator: str | None = None, prompt_separator: str | None = None) -> None @@ -801,7 +811,7 @@ applied using the protocol\://prefix/path format - `prompt_separator`: Deprecated. Separator for prompt names. -#### `from_openapi` +#### `from_openapi` ```python from_openapi(cls, openapi_spec: dict[str, Any], client: httpx.AsyncClient, route_maps: list[RouteMap] | list[RouteMapNew] | None = None, route_map_fn: OpenAPIRouteMapFn | OpenAPIRouteMapFnNew | None = None, mcp_component_fn: OpenAPIComponentFn | OpenAPIComponentFnNew | None = None, mcp_names: dict[str, str] | None = None, tags: set[str] | None = None, **settings: Any) -> FastMCPOpenAPI | FastMCPOpenAPINew @@ -810,7 +820,7 @@ from_openapi(cls, openapi_spec: dict[str, Any], client: httpx.AsyncClient, route Create a FastMCP server from an OpenAPI specification. -#### `from_fastapi` +#### `from_fastapi` ```python from_fastapi(cls, app: Any, name: str | None = None, route_maps: list[RouteMap] | list[RouteMapNew] | None = None, route_map_fn: OpenAPIRouteMapFn | OpenAPIRouteMapFnNew | None = None, mcp_component_fn: OpenAPIComponentFn | OpenAPIComponentFnNew | None = None, mcp_names: dict[str, str] | None = None, httpx_client_kwargs: dict[str, Any] | None = None, tags: set[str] | None = None, **settings: Any) -> FastMCPOpenAPI | FastMCPOpenAPINew @@ -819,7 +829,7 @@ from_fastapi(cls, app: Any, name: str | None = None, route_maps: list[RouteMap] Create a FastMCP server from a FastAPI application. -#### `as_proxy` +#### `as_proxy` ```python as_proxy(cls, backend: Client[ClientTransportT] | ClientTransport | FastMCP[Any] | AnyUrl | Path | MCPConfig | dict[str, Any] | str, **settings: Any) -> FastMCPProxy @@ -833,7 +843,7 @@ instance or any value accepted as the `transport` argument of `fastmcp.client.Client` constructor. -#### `from_client` +#### `from_client` ```python from_client(cls, client: Client[ClientTransportT], **settings: Any) -> FastMCPProxy @@ -842,10 +852,10 @@ from_client(cls, client: Client[ClientTransportT], **settings: Any) -> FastMCPPr Create a FastMCP proxy server from a FastMCP client. -#### `generate_name` +#### `generate_name` ```python generate_name(cls, name: str | None = None) -> str ``` -### `MountedServer` +### `MountedServer` diff --git a/docs/python-sdk/fastmcp-settings.mdx b/docs/python-sdk/fastmcp-settings.mdx index 185e05ab3..6f14415ec 100644 --- a/docs/python-sdk/fastmcp-settings.mdx +++ b/docs/python-sdk/fastmcp-settings.mdx @@ -7,7 +7,7 @@ sidebarTitle: settings ## Classes -### `ExtendedEnvSettingsSource` +### `ExtendedEnvSettingsSource` A special EnvSettingsSource that allows for multiple env var prefixes to be used. @@ -17,17 +17,17 @@ Raises a deprecation warning if the old `FASTMCP_SERVER_` prefix is used. **Methods:** -#### `get_field_value` +#### `get_field_value` ```python get_field_value(self, field: FieldInfo, field_name: str) -> tuple[Any, str, bool] ``` -### `ExtendedSettingsConfigDict` +### `ExtendedSettingsConfigDict` -### `ExperimentalSettings` +### `ExperimentalSettings` -### `Settings` +### `Settings` FastMCP settings. @@ -35,7 +35,7 @@ FastMCP settings. **Methods:** -#### `get_setting` +#### `get_setting` ```python get_setting(self, attr: str) -> Any @@ -45,7 +45,7 @@ Get a setting. If the setting contains one or more `__`, it will be treated as a nested setting. -#### `set_setting` +#### `set_setting` ```python set_setting(self, attr: str, value: Any) -> None @@ -55,13 +55,13 @@ Set a setting. If the setting contains one or more `__`, it will be treated as a nested setting. -#### `settings_customise_sources` +#### `settings_customise_sources` ```python settings_customise_sources(cls, settings_cls: type[BaseSettings], init_settings: PydanticBaseSettingsSource, env_settings: PydanticBaseSettingsSource, dotenv_settings: PydanticBaseSettingsSource, file_secret_settings: PydanticBaseSettingsSource) -> tuple[PydanticBaseSettingsSource, ...] ``` -#### `settings` +#### `settings` ```python settings(self) -> Self @@ -71,8 +71,14 @@ This property is for backwards compatibility with FastMCP < 2.8.0, which accessed fastmcp.settings.settings -#### `normalize_log_level` +#### `normalize_log_level` ```python normalize_log_level(cls, v) ``` + +#### `server_auth_class` + +```python +server_auth_class(self) -> AuthProvider | None +``` diff --git a/docs/python-sdk/fastmcp-utilities-json_schema.mdx b/docs/python-sdk/fastmcp-utilities-json_schema.mdx index b782a2668..a436dda8e 100644 --- a/docs/python-sdk/fastmcp-utilities-json_schema.mdx +++ b/docs/python-sdk/fastmcp-utilities-json_schema.mdx @@ -7,7 +7,7 @@ sidebarTitle: json_schema ## Functions -### `compress_schema` +### `compress_schema` ```python compress_schema(schema: dict, prune_params: list[str] | None = None, prune_defs: bool = True, prune_additional_properties: bool = True, prune_titles: bool = False) -> dict diff --git a/docs/python-sdk/fastmcp-utilities-logging.mdx b/docs/python-sdk/fastmcp-utilities-logging.mdx index 90564927c..f139db07a 100644 --- a/docs/python-sdk/fastmcp-utilities-logging.mdx +++ b/docs/python-sdk/fastmcp-utilities-logging.mdx @@ -10,7 +10,7 @@ Logging utilities for FastMCP. ## Functions -### `get_logger` +### `get_logger` ```python get_logger(name: str) -> logging.Logger @@ -26,10 +26,10 @@ Get a logger nested under FastMCP namespace. - a configured logger instance -### `configure_logging` +### `configure_logging` ```python -configure_logging(level: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] | int = 'INFO', logger: logging.Logger | None = None, enable_rich_tracebacks: bool = True, **rich_kwargs: Any) -> None +configure_logging(level: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] | int = 'INFO', logger: logging.Logger | None = None, enable_rich_tracebacks: bool | None = None, **rich_kwargs: Any) -> None ``` @@ -40,3 +40,19 @@ Configure logging for FastMCP. - `level`: the log level to use - `rich_kwargs`: the parameters to use for creating RichHandler + +### `temporary_log_level` + +```python +temporary_log_level(level: str | None, logger: logging.Logger | None = None, enable_rich_tracebacks: bool | None = None, **rich_kwargs: Any) +``` + + +Context manager to temporarily set log level and restore it afterwards. + +**Args:** +- `level`: The temporary log level to set (e.g., "DEBUG", "INFO") +- `logger`: Optional logger to configure (defaults to FastMCP logger) +- `enable_rich_tracebacks`: Whether to enable rich tracebacks +- `**rich_kwargs`: Additional parameters for RichHandler + diff --git a/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-mcp_server_config.mdx b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-mcp_server_config.mdx index 51409f3d7..391759bc0 100644 --- a/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-mcp_server_config.mdx +++ b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-mcp_server_config.mdx @@ -15,7 +15,7 @@ command-line arguments. ## Functions -### `generate_schema` +### `generate_schema` ```python generate_schema(output_path: Path | str | None = None) -> dict[str, Any] | None diff --git a/docs/python-sdk/fastmcp-utilities-storage.mdx b/docs/python-sdk/fastmcp-utilities-storage.mdx new file mode 100644 index 000000000..0d0ecd322 --- /dev/null +++ b/docs/python-sdk/fastmcp-utilities-storage.mdx @@ -0,0 +1,158 @@ +--- +title: storage +sidebarTitle: storage +--- + +# `fastmcp.utilities.storage` + + +Key-value storage utilities for persistent data management. + +## Classes + +### `KVStorage` + + +Protocol for key-value storage of JSON data. + + +**Methods:** + +#### `get` + +```python +get(self, key: str) -> dict[str, Any] | None +``` + +Get a JSON dict by key. + + +#### `set` + +```python +set(self, key: str, value: dict[str, Any]) -> None +``` + +Store a JSON dict by key. + + +#### `delete` + +```python +delete(self, key: str) -> None +``` + +Delete a value by key. + + +### `JSONFileStorage` + + +File-based key-value storage for JSON data with automatic metadata tracking. + +Each key-value pair is stored as a separate JSON file on disk. +Keys are sanitized to be filesystem-safe. + +The storage automatically wraps all data with metadata: +- timestamp: Timestamp when the entry was last written + +**Args:** +- `cache_dir`: Directory for storing JSON files + + +**Methods:** + +#### `get` + +```python +get(self, key: str) -> dict[str, Any] | None +``` + +Get a JSON dict from storage by key. + +**Args:** +- `key`: The key to retrieve + +**Returns:** +- The stored dict or None if not found + + +#### `set` + +```python +set(self, key: str, value: dict[str, Any]) -> None +``` + +Store a JSON dict with metadata. + +**Args:** +- `key`: The key to store under +- `value`: The dict to store + + +#### `delete` + +```python +delete(self, key: str) -> None +``` + +Delete a value from storage. + +**Args:** +- `key`: The key to delete + + +#### `cleanup_old_entries` + +```python +cleanup_old_entries(self, max_age_seconds: int = 30 * 24 * 60 * 60) -> int +``` + +Remove entries older than the specified age. + +Uses the timestamp field to determine age. + +**Args:** +- `max_age_seconds`: Maximum age in seconds (default 30 days) + +**Returns:** +- Number of entries removed + + +### `InMemoryStorage` + + +In-memory key-value storage for JSON data. + +Simple dict-based storage that doesn't persist across restarts. +Useful for testing or environments where file storage isn't available. + + +**Methods:** + +#### `get` + +```python +get(self, key: str) -> dict[str, Any] | None +``` + +Get a JSON dict from memory by key. + + +#### `set` + +```python +set(self, key: str, value: dict[str, Any]) -> None +``` + +Store a JSON dict in memory. + + +#### `delete` + +```python +delete(self, key: str) -> None +``` + +Delete a value from memory. + diff --git a/docs/python-sdk/fastmcp-utilities-tests.mdx b/docs/python-sdk/fastmcp-utilities-tests.mdx index ce6d3d761..669755575 100644 --- a/docs/python-sdk/fastmcp-utilities-tests.mdx +++ b/docs/python-sdk/fastmcp-utilities-tests.mdx @@ -43,7 +43,7 @@ not pickleable, so we need a function that creates and runs one. - The server URL. -### `caplog_for_fastmcp` +### `caplog_for_fastmcp` ```python caplog_for_fastmcp(caplog) @@ -55,7 +55,7 @@ Context manager to capture logs from FastMCP loggers even when propagation is di ## Classes -### `HeadlessOAuth` +### `HeadlessOAuth` OAuth provider that bypasses browser interaction for testing. @@ -66,7 +66,7 @@ instead of opening a browser and running a callback server. Useful for automated **Methods:** -#### `redirect_handler` +#### `redirect_handler` ```python redirect_handler(self, authorization_url: str) -> None @@ -75,7 +75,7 @@ redirect_handler(self, authorization_url: str) -> None Make HTTP request to authorization URL and store response for callback handler. -#### `callback_handler` +#### `callback_handler` ```python callback_handler(self) -> tuple[str, str | None]