From f7d7303dee9154fcea96161abe1da646eaa9366a Mon Sep 17 00:00:00 2001 From: "marvin-context-protocol[bot]" <225465937+marvin-context-protocol[bot]@users.noreply.github.com> Date: Sat, 30 Aug 2025 10:36:31 -0400 Subject: [PATCH] chore: Update SDK documentation (#1679) Co-authored-by: marvin-context-protocol[bot] <225465937+marvin-context-protocol[bot]@users.noreply.github.com> --- .../fastmcp-server-auth-oauth_proxy.mdx | 20 +++++----- .../fastmcp-server-auth-providers-azure.mdx | 6 +-- .../fastmcp-server-auth-providers-github.mdx | 6 +-- .../fastmcp-server-auth-providers-google.mdx | 6 +-- .../fastmcp-server-auth-providers-workos.mdx | 12 +++--- ...mcp_server_config-v1-environments-base.mdx | 4 +- ...s-mcp_server_config-v1-environments-uv.mdx | 12 +++--- ...mcp_server_config-v1-mcp_server_config.mdx | 38 +++++++++---------- ...ties-mcp_server_config-v1-sources-base.mdx | 2 +- ...cp_server_config-v1-sources-filesystem.mdx | 4 +- 10 files changed, 54 insertions(+), 56 deletions(-) diff --git a/docs/python-sdk/fastmcp-server-auth-oauth_proxy.mdx b/docs/python-sdk/fastmcp-server-auth-oauth_proxy.mdx index 163843467..6d261e0a4 100644 --- a/docs/python-sdk/fastmcp-server-auth-oauth_proxy.mdx +++ b/docs/python-sdk/fastmcp-server-auth-oauth_proxy.mdx @@ -182,7 +182,7 @@ Handles provider-specific requirements: **Methods:** -#### `get_client` +#### `get_client` ```python get_client(self, client_id: str) -> OAuthClientInformationFull | None @@ -199,7 +199,7 @@ handles the case where a client with cached tokens reconnects on a different port. -#### `register_client` +#### `register_client` ```python register_client(self, client_info: OAuthClientInformationFull) -> None @@ -226,7 +226,7 @@ The flow: 4. When client reconnects with a different port, ProxyDCRClient accepts it -#### `authorize` +#### `authorize` ```python authorize(self, client: OAuthClientInformationFull, params: AuthorizationParams) -> str @@ -240,7 +240,7 @@ This implements the DCR-compliant proxy pattern: 3. Redirect to IdP with our fixed callback URL -#### `load_authorization_code` +#### `load_authorization_code` ```python load_authorization_code(self, client: OAuthClientInformationFull, authorization_code: str) -> AuthorizationCode | None @@ -252,7 +252,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 @@ -264,7 +264,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 @@ -273,7 +273,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 @@ -282,7 +282,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 @@ -294,7 +294,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 @@ -306,7 +306,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) -> list[Route] diff --git a/docs/python-sdk/fastmcp-server-auth-providers-azure.mdx b/docs/python-sdk/fastmcp-server-auth-providers-azure.mdx index ed66062f9..343128eba 100644 --- a/docs/python-sdk/fastmcp-server-auth-providers-azure.mdx +++ b/docs/python-sdk/fastmcp-server-auth-providers-azure.mdx @@ -20,7 +20,7 @@ using the OAuth Proxy pattern for non-DCR OAuth flows. 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-github.mdx b/docs/python-sdk/fastmcp-server-auth-providers-github.mdx index e6f23ab15..91d86fa87 100644 --- a/docs/python-sdk/fastmcp-server-auth-providers-github.mdx +++ b/docs/python-sdk/fastmcp-server-auth-providers-github.mdx @@ -35,7 +35,7 @@ Example: 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 4f4d4688b..2eaf874cc 100644 --- a/docs/python-sdk/fastmcp-server-auth-providers-google.mdx +++ b/docs/python-sdk/fastmcp-server-auth-providers-google.mdx @@ -35,7 +35,7 @@ Example: 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-workos.mdx b/docs/python-sdk/fastmcp-server-auth-providers-workos.mdx index 31d0145d2..fdacdf859 100644 --- a/docs/python-sdk/fastmcp-server-auth-providers-workos.mdx +++ b/docs/python-sdk/fastmcp-server-auth-providers-workos.mdx @@ -24,7 +24,7 @@ Choose based on your WorkOS setup and authentication requirements. 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) -> list[Route] diff --git a/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-environments-base.mdx b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-environments-base.mdx index 52b0de9a8..3a97b5d9e 100644 --- a/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-environments-base.mdx +++ b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-environments-base.mdx @@ -15,7 +15,7 @@ Base class for environment configuration. **Methods:** -#### `build_command` +#### `build_command` ```python build_command(self, command: list[str]) -> list[str] @@ -30,7 +30,7 @@ Build the full command with environment setup. - Full command ready for subprocess execution -#### `prepare` +#### `prepare` ```python prepare(self, output_dir: Path | None = None) -> None diff --git a/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-environments-uv.mdx b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-environments-uv.mdx index 84d117078..de51b8098 100644 --- a/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-environments-uv.mdx +++ b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-environments-uv.mdx @@ -7,7 +7,7 @@ sidebarTitle: uv ## Classes -### `UVEnvironment` +### `UVEnvironment` Configuration for Python environment setup. @@ -15,7 +15,7 @@ Configuration for Python environment setup. **Methods:** -#### `build_command` +#### `build_command` ```python build_command(self, command: list[str]) -> list[str] @@ -31,7 +31,7 @@ Build complete uv run command with environment args and command to execute. - If no environment configuration is set, returns the command unchanged. -#### `run_with_uv` +#### `run_with_uv` ```python run_with_uv(self, command: list[str]) -> None @@ -43,7 +43,7 @@ Execute a command using uv run with this environment configuration. - `command`: Command and arguments to execute (e.g., ["fastmcp", "run", "server.py"]) -#### `needs_uv` +#### `needs_uv` ```python needs_uv(self) -> bool @@ -52,7 +52,7 @@ needs_uv(self) -> bool Deprecated: Use _needs_setup() internally or check if build_command modifies the command. -#### `build_uv_run_command` +#### `build_uv_run_command` ```python build_uv_run_command(self, command: list[str]) -> list[str] @@ -61,7 +61,7 @@ build_uv_run_command(self, command: list[str]) -> list[str] Deprecated: Use build_command() instead. -#### `prepare` +#### `prepare` ```python prepare(self, output_dir: Path | None = None) -> None 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 7096185a0..e9d8c398d 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 @@ -38,7 +38,7 @@ validation and auto-completion. ## Classes -### `Deployment` +### `Deployment` Configuration for server deployment and runtime settings. @@ -46,7 +46,7 @@ Configuration for server deployment and runtime settings. **Methods:** -#### `apply_runtime_settings` +#### `apply_runtime_settings` ```python apply_runtime_settings(self, config_path: Path | None = None) -> None @@ -62,7 +62,7 @@ For example: "API_URL": "https://api.${ENVIRONMENT}.example.com" will substitute the value of the ENVIRONMENT variable at runtime. -### `MCPServerConfig` +### `MCPServerConfig` Configuration for a FastMCP server. @@ -73,10 +73,10 @@ a FastMCP server in a declarative format. **Methods:** -#### `validate_source` +#### `validate_source` ```python -validate_source(cls, v: dict | FileSystemSource) -> FileSystemSource +validate_source(cls, v: dict | Source) -> SourceType ``` Validate and convert source to proper format. @@ -89,20 +89,18 @@ No string parsing happens here - that's only at CLI boundaries. MCPServerConfig works only with properly typed objects. -#### `validate_environment` +#### `validate_environment` ```python -validate_environment(cls, v: dict | UVEnvironment) -> UVEnvironment +validate_environment(cls, v: dict | Any) -> EnvironmentType ``` -Validate and convert environment to Environment. +Ensure environment has a type field for discrimination. -Accepts: -- Environment instance -- dict that can be converted to Environment +For backward compatibility, if no type is specified, default to "uv". -#### `validate_deployment` +#### `validate_deployment` ```python validate_deployment(cls, v: dict | Deployment) -> Deployment @@ -115,7 +113,7 @@ Accepts: - dict that can be converted to Deployment -#### `from_file` +#### `from_file` ```python from_file(cls, file_path: Path) -> MCPServerConfig @@ -135,7 +133,7 @@ Load configuration from a JSON file. - `pydantic.ValidationError`: If the configuration is invalid -#### `from_cli_args` +#### `from_cli_args` ```python from_cli_args(cls, source: FileSystemSource, transport: Literal['stdio', 'http', 'sse', 'streamable-http'] | None = None, host: str | None = None, port: int | None = None, path: str | None = None, log_level: Literal['DEBUG', 'INFO', 'WARNING', 'ERROR', 'CRITICAL'] | None = None, python: str | None = None, dependencies: list[str] | None = None, requirements: str | None = None, project: str | None = None, editable: str | None = None, env: dict[str, str] | None = None, cwd: str | None = None, args: list[str] | None = None) -> MCPServerConfig @@ -166,7 +164,7 @@ goes through a config object. - MCPServerConfig instance -#### `find_config` +#### `find_config` ```python find_config(cls, start_path: Path | None = None) -> Path | None @@ -181,7 +179,7 @@ Find a fastmcp.json file in the specified directory. - Path to the configuration file, or None if not found -#### `prepare` +#### `prepare` ```python prepare(self, skip_source: bool = False, output_dir: Path | None = None) -> None @@ -197,7 +195,7 @@ When output_dir is None, does ephemeral caching (for backwards compatibility). - `output_dir`: Directory to create the persistent uv project in (optional) -#### `prepare_environment` +#### `prepare_environment` ```python prepare_environment(self, output_dir: Path | None = None) -> None @@ -212,7 +210,7 @@ Prepare the Python environment. Delegates to the environment's prepare() method -#### `prepare_source` +#### `prepare_source` ```python prepare_source(self) -> None @@ -223,7 +221,7 @@ Prepare the source for loading. Delegates to the source's prepare() method. -#### `run_server` +#### `run_server` ```python run_server(self, **kwargs: Any) -> None diff --git a/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-sources-base.mdx b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-sources-base.mdx index bf80ca1d6..0a2aa84ac 100644 --- a/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-sources-base.mdx +++ b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-sources-base.mdx @@ -7,7 +7,7 @@ sidebarTitle: base ## Classes -### `BaseSource` +### `Source` Abstract base class for all source types. diff --git a/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-sources-filesystem.mdx b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-sources-filesystem.mdx index 9ff83063b..b557613c8 100644 --- a/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-sources-filesystem.mdx +++ b/docs/python-sdk/fastmcp-utilities-mcp_server_config-v1-sources-filesystem.mdx @@ -15,7 +15,7 @@ Source for local Python files. **Methods:** -#### `parse_path_with_object` +#### `parse_path_with_object` ```python parse_path_with_object(cls, v: str) -> str @@ -27,7 +27,7 @@ This validator runs before the model is created, allowing us to handle the "file.py:object" syntax at the model boundary. -#### `load_server` +#### `load_server` ```python load_server(self) -> Any