From ef4afe40614314f388cfd07adda4308dbb508eb1 Mon Sep 17 00:00:00 2001 From: "marvin-context-protocol[bot]" <225465937+marvin-context-protocol[bot]@users.noreply.github.com> Date: Thu, 16 Oct 2025 21:18:01 -0400 Subject: [PATCH] chore: Update SDK documentation (#1950) Co-authored-by: marvin-context-protocol[bot] <225465937+marvin-context-protocol[bot]@users.noreply.github.com> --- docs/docs.json | 38 +++-- docs/python-sdk/fastmcp-cli-claude.mdx | 43 ----- docs/python-sdk/fastmcp-cli-cli.mdx | 12 +- docs/python-sdk/fastmcp-cli-run.mdx | 14 +- docs/python-sdk/fastmcp-client-auth-oauth.mdx | 108 +++--------- docs/python-sdk/fastmcp-client-logging.mdx | 4 +- .../fastmcp-client-oauth_callback.mdx | 10 +- docs/python-sdk/fastmcp-client-transports.mdx | 32 ++-- docs/python-sdk/fastmcp-prompts-prompt.mdx | 25 +-- .../fastmcp-prompts-prompt_manager.mdx | 34 +--- .../python-sdk/fastmcp-resources-resource.mdx | 27 +-- .../fastmcp-resources-resource_manager.mdx | 49 ++---- .../python-sdk/fastmcp-resources-template.mdx | 59 +++++-- docs/python-sdk/fastmcp-server-auth-auth.mdx | 40 ++--- .../fastmcp-server-auth-oauth_proxy.mdx | 104 +++++++++--- .../fastmcp-server-auth-oidc_proxy.mdx | 4 +- .../fastmcp-server-auth-providers-auth0.mdx | 4 +- .../fastmcp-server-auth-providers-aws.mdx | 10 +- .../fastmcp-server-auth-providers-azure.mdx | 65 +++---- .../fastmcp-server-auth-providers-descope.mdx | 10 +- .../fastmcp-server-auth-providers-github.mdx | 8 +- .../fastmcp-server-auth-providers-google.mdx | 8 +- ...cp-server-auth-providers-introspection.mdx | 77 +++++++++ .../fastmcp-server-auth-providers-jwt.mdx | 22 +-- ...fastmcp-server-auth-providers-scalekit.mdx | 10 +- ...fastmcp-server-auth-providers-supabase.mdx | 62 +++++++ .../fastmcp-server-auth-providers-workos.mdx | 18 +- docs/python-sdk/fastmcp-server-context.mdx | 74 ++++---- docs/python-sdk/fastmcp-server-http.mdx | 2 +- docs/python-sdk/fastmcp-server-low_level.mdx | 39 ++++- .../fastmcp-server-middleware-logging.mdx | 12 +- .../fastmcp-server-middleware-middleware.mdx | 40 +++-- docs/python-sdk/fastmcp-server-server.mdx | 117 ++++++------- docs/python-sdk/fastmcp-settings.mdx | 22 +-- .../python-sdk/fastmcp-tools-tool_manager.mdx | 42 ++--- .../fastmcp-tools-tool_transform.mdx | 4 +- docs/python-sdk/fastmcp-utilities-inspect.mdx | 12 +- docs/python-sdk/fastmcp-utilities-logging.mdx | 6 +- docs/python-sdk/fastmcp-utilities-storage.mdx | 158 ------------------ docs/python-sdk/fastmcp-utilities-tests.mdx | 12 +- docs/python-sdk/fastmcp-utilities-types.mdx | 2 +- docs/python-sdk/fastmcp-utilities-ui.mdx | 131 +++++++++++++++ 42 files changed, 844 insertions(+), 726 deletions(-) delete mode 100644 docs/python-sdk/fastmcp-cli-claude.mdx create mode 100644 docs/python-sdk/fastmcp-server-auth-providers-introspection.mdx create mode 100644 docs/python-sdk/fastmcp-server-auth-providers-supabase.mdx delete mode 100644 docs/python-sdk/fastmcp-utilities-storage.mdx create mode 100644 docs/python-sdk/fastmcp-utilities-ui.mdx diff --git a/docs/docs.json b/docs/docs.json index 334804ca5..625faac80 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -20,9 +20,19 @@ "primary": "#2d00f7" }, "contextual": { - "options": ["copy", "view"] + "options": [ + "copy", + "view" + ] }, "description": "The fast, Pythonic way to build MCP servers and clients.", + "errors": { + "404": { + "description": "You\u2019ve wandered outside the context.", + "redirect": false, + "title": "Don't panic." + } + }, "favicon": { "dark": "/assets/brand/favicon.svg", "light": "/assets/brand/favicon.svg" @@ -69,6 +79,7 @@ "navigation": { "dropdowns": [ { + "dropdown": "Documentation", "groups": [ { "group": "Get Started", @@ -136,7 +147,10 @@ { "group": "Essentials", "icon": "cube", - "pages": ["clients/client", "clients/transports"] + "pages": [ + "clients/client", + "clients/transports" + ] }, { "group": "Core Operations", @@ -162,7 +176,10 @@ { "group": "Authentication", "icon": "user-shield", - "pages": ["clients/auth/oauth", "clients/auth/bearer"] + "pages": [ + "clients/auth/oauth", + "clients/auth/bearer" + ] } ] }, @@ -243,7 +260,6 @@ ] } ], - "dropdown": "Documentation", "icon": "book" }, { @@ -259,7 +275,6 @@ "group": "fastmcp.cli", "pages": [ "python-sdk/fastmcp-cli-__init__", - "python-sdk/fastmcp-cli-claude", "python-sdk/fastmcp-cli-cli", { "group": "install", @@ -340,8 +355,10 @@ "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-introspection", "python-sdk/fastmcp-server-auth-providers-jwt", "python-sdk/fastmcp-server-auth-providers-scalekit", + "python-sdk/fastmcp-server-auth-providers-supabase", "python-sdk/fastmcp-server-auth-providers-workos" ] }, @@ -422,9 +439,9 @@ ] }, "python-sdk/fastmcp-utilities-openapi", - "python-sdk/fastmcp-utilities-storage", "python-sdk/fastmcp-utilities-tests", - "python-sdk/fastmcp-utilities-types" + "python-sdk/fastmcp-utilities-types", + "python-sdk/fastmcp-utilities-ui" ] } ] @@ -449,13 +466,6 @@ "prompt": "Search the docs..." }, "theme": "almond", - "errors": { - "404": { - "redirect": false, - "title": "Don't panic.", - "description": "You’ve wandered outside the context." - } - }, "thumbnails": { "appearance": "light", "background": "/assets/brand/thumbnail-background.png" diff --git a/docs/python-sdk/fastmcp-cli-claude.mdx b/docs/python-sdk/fastmcp-cli-claude.mdx deleted file mode 100644 index 82eb6e881..000000000 --- a/docs/python-sdk/fastmcp-cli-claude.mdx +++ /dev/null @@ -1,43 +0,0 @@ ---- -title: claude -sidebarTitle: claude ---- - -# `fastmcp.cli.claude` - - -Claude app integration utilities. - -## Functions - -### `get_claude_config_path` - -```python -get_claude_config_path() -> Path | None -``` - - -Get the Claude config directory based on platform. - - -### `update_claude_config` - -```python -update_claude_config(file_spec: str, server_name: str) -> bool -``` - - -Add or update a FastMCP server in Claude's configuration. - -**Args:** -- `file_spec`: Path to the server file, optionally with \:object suffix -- `server_name`: Name for the server in Claude's config -- `with_editable`: Optional list of directories to install in editable mode -- `with_packages`: Optional list of additional packages to install -- `env_vars`: Optional dictionary of environment variables. These are merged with -any existing variables, with new values taking precedence. - -**Raises:** -- `RuntimeError`: If Claude Desktop's config directory is not found, indicating -Claude Desktop may not be installed or properly set up. - diff --git a/docs/python-sdk/fastmcp-cli-cli.mdx b/docs/python-sdk/fastmcp-cli-cli.mdx index a6f4ee13b..c913c5cf7 100644 --- a/docs/python-sdk/fastmcp-cli-cli.mdx +++ b/docs/python-sdk/fastmcp-cli-cli.mdx @@ -10,7 +10,7 @@ FastMCP CLI tools using Cyclopts. ## Functions -### `with_argv` +### `with_argv` ```python with_argv(args: list[str] | None) @@ -27,7 +27,7 @@ Args are provided without the script name, so we preserve sys.argv[0] and replace the rest. -### `version` +### `version` ```python version() @@ -37,7 +37,7 @@ version() Display version information and platform details. -### `dev` +### `dev` ```python dev(server_spec: str | None = None) -> None @@ -50,7 +50,7 @@ Run an MCP server with the MCP Inspector for development. - `server_spec`: Python file to run, optionally with \:object suffix, or None to auto-detect fastmcp.json -### `run` +### `run` ```python run(server_spec: str | None = None, *server_args: str) -> None @@ -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-run.mdx b/docs/python-sdk/fastmcp-cli-run.mdx index f9a5f874d..2909c19a8 100644 --- a/docs/python-sdk/fastmcp-cli-run.mdx +++ b/docs/python-sdk/fastmcp-cli-run.mdx @@ -84,8 +84,18 @@ Run a MCP server or connect to a remote one. - `skip_source`: Whether to skip source preparation step -### `run_v1_server` +### `run_v1_server_async` ```python -run_v1_server(server: FastMCP1x, host: str | None = None, port: int | None = None, transport: TransportType | None = None) -> None +run_v1_server_async(server: FastMCP1x, host: str | None = None, port: int | None = None, transport: TransportType | None = None) -> None ``` + + +Run a FastMCP 1.x server using async methods. + +**Args:** +- `server`: FastMCP 1.x server instance +- `host`: Host to bind to +- `port`: Port to bind to +- `transport`: Transport protocol to use + diff --git a/docs/python-sdk/fastmcp-client-auth-oauth.mdx b/docs/python-sdk/fastmcp-client-auth-oauth.mdx index cc3dd7cf5..7574d7a29 100644 --- a/docs/python-sdk/fastmcp-client-auth-oauth.mdx +++ b/docs/python-sdk/fastmcp-client-auth-oauth.mdx @@ -7,13 +7,7 @@ sidebarTitle: oauth ## Functions -### `default_cache_dir` - -```python -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 @@ -28,97 +22,47 @@ Check if the MCP endpoint requires authentication by making a test request. ## Classes -### `ClientNotFoundError` +### `ClientNotFoundError` Raised when OAuth client credentials are not found on the server. -### `StoredToken` - - -Token storage format with absolute expiry time. - - -### `FileTokenStorage` - - -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. - +### `TokenStorageAdapter` **Methods:** -#### `get_base_url` - -```python -get_base_url(url: str) -> str -``` - -Extract the base URL (scheme + host) from a URL. - - -#### `get_tokens` - -```python -get_tokens(self) -> OAuthToken | None -``` - -Load tokens from file storage. - - -#### `set_tokens` - -```python -set_tokens(self, tokens: OAuthToken) -> None -``` - -Save tokens to file storage. - - -#### `get_client_info` - -```python -get_client_info(self) -> OAuthClientInformationFull | None -``` - -Load client information from file storage. - - -#### `set_client_info` - -```python -set_client_info(self, client_info: OAuthClientInformationFull) -> None -``` - -Save client information to file storage. - - -#### `clear` +#### `clear` ```python 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` +#### `get_tokens` ```python -clear_all(cls, cache_dir: Path | None = None) -> None +get_tokens(self) -> OAuthToken | None ``` -Clear all cached data for all servers. +#### `set_tokens` +```python +set_tokens(self, tokens: OAuthToken) -> None +``` -### `OAuth` +#### `get_client_info` + +```python +get_client_info(self) -> OAuthClientInformationFull | None +``` + +#### `set_client_info` + +```python +set_client_info(self, client_info: OAuthClientInformationFull) -> None +``` + +### `OAuth` OAuth client provider for MCP servers with browser-based authentication. @@ -129,7 +73,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 @@ -138,7 +82,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] @@ -147,7 +91,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-logging.mdx b/docs/python-sdk/fastmcp-client-logging.mdx index 8d9176ea8..b2f8d250d 100644 --- a/docs/python-sdk/fastmcp-client-logging.mdx +++ b/docs/python-sdk/fastmcp-client-logging.mdx @@ -7,7 +7,7 @@ sidebarTitle: logging ## Functions -### `default_log_handler` +### `default_log_handler` ```python default_log_handler(message: LogMessage) -> None @@ -17,7 +17,7 @@ default_log_handler(message: LogMessage) -> None Default handler that properly routes server log messages to appropriate log levels. -### `create_log_callback` +### `create_log_callback` ```python create_log_callback(handler: LogHandler | None = None) -> LoggingFnT diff --git a/docs/python-sdk/fastmcp-client-oauth_callback.mdx b/docs/python-sdk/fastmcp-client-oauth_callback.mdx index beddcd64f..87e667b76 100644 --- a/docs/python-sdk/fastmcp-client-oauth_callback.mdx +++ b/docs/python-sdk/fastmcp-client-oauth_callback.mdx @@ -15,7 +15,7 @@ and display styled responses to users. ## Functions -### `create_callback_html` +### `create_callback_html` ```python create_callback_html(message: str, is_success: bool = True, title: str = 'FastMCP OAuth', server_url: str | None = None) -> str @@ -25,7 +25,7 @@ create_callback_html(message: str, is_success: bool = True, title: str = 'FastMC Create a styled HTML response for OAuth callbacks. -### `create_oauth_callback_server` +### `create_oauth_callback_server` ```python create_oauth_callback_server(port: int, callback_path: str = '/callback', server_url: str | None = None, response_future: asyncio.Future | None = None) -> Server @@ -46,17 +46,17 @@ Create an OAuth callback server. ## Classes -### `CallbackResponse` +### `CallbackResponse` **Methods:** -#### `from_dict` +#### `from_dict` ```python from_dict(cls, data: dict[str, str]) -> CallbackResponse ``` -#### `to_dict` +#### `to_dict` ```python to_dict(self) -> dict[str, str] diff --git a/docs/python-sdk/fastmcp-client-transports.mdx b/docs/python-sdk/fastmcp-client-transports.mdx index af31fb50e..f403c6a35 100644 --- a/docs/python-sdk/fastmcp-client-transports.mdx +++ b/docs/python-sdk/fastmcp-client-transports.mdx @@ -7,7 +7,7 @@ sidebarTitle: transports ## Functions -### `infer_transport` +### `infer_transport` ```python infer_transport(transport: ClientTransport | FastMCP | FastMCP1Server | AnyUrl | Path | MCPConfig | dict[str, Any] | str) -> ClientTransport @@ -155,67 +155,67 @@ transports like Python, Node, Uvx, etc. **Methods:** -#### `connect_session` +#### `connect_session` ```python connect_session(self, **session_kwargs: Unpack[SessionKwargs]) -> AsyncIterator[ClientSession] ``` -#### `connect` +#### `connect` ```python connect(self, **session_kwargs: Unpack[SessionKwargs]) -> ClientSession | None ``` -#### `disconnect` +#### `disconnect` ```python disconnect(self) ``` -#### `close` +#### `close` ```python close(self) ``` -### `PythonStdioTransport` +### `PythonStdioTransport` Transport for running Python scripts. -### `FastMCPStdioTransport` +### `FastMCPStdioTransport` Transport for running FastMCP servers using the FastMCP CLI. -### `NodeStdioTransport` +### `NodeStdioTransport` Transport for running Node.js scripts. -### `UvStdioTransport` +### `UvStdioTransport` Transport for running commands via the uv tool. -### `UvxStdioTransport` +### `UvxStdioTransport` Transport for running commands via the uvx tool. -### `NpxStdioTransport` +### `NpxStdioTransport` Transport for running commands via the npx tool. -### `FastMCPTransport` +### `FastMCPTransport` In-memory transport for FastMCP servers. @@ -228,13 +228,13 @@ tests or scenarios where client and server run in the same runtime. **Methods:** -#### `connect_session` +#### `connect_session` ```python connect_session(self, **session_kwargs: Unpack[SessionKwargs]) -> AsyncIterator[ClientSession] ``` -### `MCPConfigTransport` +### `MCPConfigTransport` Transport for connecting to one or more MCP servers defined in an MCPConfig. @@ -287,13 +287,13 @@ async with client: **Methods:** -#### `connect_session` +#### `connect_session` ```python connect_session(self, **session_kwargs: Unpack[SessionKwargs]) -> AsyncIterator[ClientSession] ``` -#### `close` +#### `close` ```python close(self) diff --git a/docs/python-sdk/fastmcp-prompts-prompt.mdx b/docs/python-sdk/fastmcp-prompts-prompt.mdx index 075ff97e1..c1d5d0a4d 100644 --- a/docs/python-sdk/fastmcp-prompts-prompt.mdx +++ b/docs/python-sdk/fastmcp-prompts-prompt.mdx @@ -10,7 +10,7 @@ Base classes for FastMCP prompts. ## Functions -### `Message` +### `Message` ```python Message(content: str | ContentBlock, role: Role | None = None, **kwargs: Any) -> PromptMessage @@ -22,13 +22,13 @@ A user-friendly constructor for PromptMessage. ## Classes -### `PromptArgument` +### `PromptArgument` An argument that can be passed to a prompt. -### `Prompt` +### `Prompt` A prompt template that can be rendered with parameters. @@ -36,19 +36,19 @@ A prompt template that can be rendered with parameters. **Methods:** -#### `enable` +#### `enable` ```python enable(self) -> None ``` -#### `disable` +#### `disable` ```python disable(self) -> None ``` -#### `to_mcp_prompt` +#### `to_mcp_prompt` ```python to_mcp_prompt(self, **overrides: Any) -> MCPPrompt @@ -57,7 +57,7 @@ to_mcp_prompt(self, **overrides: Any) -> MCPPrompt Convert the prompt to an MCP prompt. -#### `from_function` +#### `from_function` ```python from_function(fn: Callable[..., PromptResult | Awaitable[PromptResult]], name: str | None = None, title: str | None = None, description: str | None = None, tags: set[str] | None = None, enabled: bool | None = None, meta: dict[str, Any] | None = None) -> FunctionPrompt @@ -72,7 +72,7 @@ The function can return: - A sequence of any of the above -#### `render` +#### `render` ```python render(self, arguments: dict[str, Any] | None = None) -> list[PromptMessage] @@ -80,8 +80,11 @@ render(self, arguments: dict[str, Any] | None = None) -> list[PromptMessage] Render the prompt with arguments. +This method is not implemented in the base Prompt class and must be +implemented by subclasses. -### `FunctionPrompt` + +### `FunctionPrompt` A prompt that is a function. @@ -89,7 +92,7 @@ A prompt that is a function. **Methods:** -#### `from_function` +#### `from_function` ```python from_function(cls, fn: Callable[..., PromptResult | Awaitable[PromptResult]], name: str | None = None, title: str | None = None, description: str | None = None, tags: set[str] | None = None, enabled: bool | None = None, meta: dict[str, Any] | None = None) -> FunctionPrompt @@ -104,7 +107,7 @@ The function can return: - A sequence of any of the above -#### `render` +#### `render` ```python render(self, arguments: dict[str, Any] | None = None) -> list[PromptMessage] diff --git a/docs/python-sdk/fastmcp-prompts-prompt_manager.mdx b/docs/python-sdk/fastmcp-prompts-prompt_manager.mdx index d0fcfae56..30f85c18d 100644 --- a/docs/python-sdk/fastmcp-prompts-prompt_manager.mdx +++ b/docs/python-sdk/fastmcp-prompts-prompt_manager.mdx @@ -7,7 +7,7 @@ sidebarTitle: prompt_manager ## Classes -### `PromptManager` +### `PromptManager` Manages FastMCP prompts. @@ -15,16 +15,7 @@ Manages FastMCP prompts. **Methods:** -#### `mount` - -```python -mount(self, server: MountedServer) -> None -``` - -Adds a mounted server as a source for prompts. - - -#### `has_prompt` +#### `has_prompt` ```python has_prompt(self, key: str) -> bool @@ -33,7 +24,7 @@ has_prompt(self, key: str) -> bool Check if a prompt exists. -#### `get_prompt` +#### `get_prompt` ```python get_prompt(self, key: str) -> Prompt @@ -42,25 +33,16 @@ get_prompt(self, key: str) -> Prompt Get prompt by key. -#### `get_prompts` +#### `get_prompts` ```python get_prompts(self) -> dict[str, Prompt] ``` -Gets the complete, unfiltered inventory of all prompts. +Gets the complete, unfiltered inventory of local prompts. -#### `list_prompts` - -```python -list_prompts(self) -> list[Prompt] -``` - -Lists all prompts, applying protocol filtering. - - -#### `add_prompt_from_fn` +#### `add_prompt_from_fn` ```python add_prompt_from_fn(self, fn: Callable[..., PromptResult | Awaitable[PromptResult]], name: str | None = None, description: str | None = None, tags: set[str] | None = None) -> FunctionPrompt @@ -69,7 +51,7 @@ add_prompt_from_fn(self, fn: Callable[..., PromptResult | Awaitable[PromptResult Create a prompt from a function. -#### `add_prompt` +#### `add_prompt` ```python add_prompt(self, prompt: Prompt) -> Prompt @@ -78,7 +60,7 @@ add_prompt(self, prompt: Prompt) -> Prompt Add a prompt to the manager. -#### `render_prompt` +#### `render_prompt` ```python render_prompt(self, name: str, arguments: dict[str, Any] | None = None) -> GetPromptResult diff --git a/docs/python-sdk/fastmcp-resources-resource.mdx b/docs/python-sdk/fastmcp-resources-resource.mdx index 6acd375af..94a0cf2f7 100644 --- a/docs/python-sdk/fastmcp-resources-resource.mdx +++ b/docs/python-sdk/fastmcp-resources-resource.mdx @@ -10,7 +10,7 @@ Base classes and interfaces for FastMCP resources. ## Classes -### `Resource` +### `Resource` Base class for all resources. @@ -18,25 +18,25 @@ Base class for all resources. **Methods:** -#### `enable` +#### `enable` ```python enable(self) -> None ``` -#### `disable` +#### `disable` ```python disable(self) -> None ``` -#### `from_function` +#### `from_function` ```python from_function(fn: Callable[..., Any], uri: str | AnyUrl, name: str | None = None, title: str | None = None, description: str | None = None, mime_type: str | None = None, tags: set[str] | None = None, enabled: bool | None = None, annotations: Annotations | None = None, meta: dict[str, Any] | None = None) -> FunctionResource ``` -#### `set_default_mime_type` +#### `set_default_mime_type` ```python set_default_mime_type(cls, mime_type: str | None) -> str @@ -45,7 +45,7 @@ set_default_mime_type(cls, mime_type: str | None) -> str Set default MIME type if not provided. -#### `set_default_name` +#### `set_default_name` ```python set_default_name(self) -> Self @@ -54,7 +54,7 @@ set_default_name(self) -> Self Set default name from URI if not provided. -#### `read` +#### `read` ```python read(self) -> str | bytes @@ -62,8 +62,11 @@ read(self) -> str | bytes Read the resource content. +This method is not implemented in the base Resource class and must be +implemented by subclasses. -#### `to_mcp_resource` + +#### `to_mcp_resource` ```python to_mcp_resource(self, **overrides: Any) -> MCPResource @@ -72,7 +75,7 @@ to_mcp_resource(self, **overrides: Any) -> MCPResource Convert the resource to an MCPResource. -#### `key` +#### `key` ```python key(self) -> str @@ -84,7 +87,7 @@ keys having a certain value, as the same tool loaded from different hierarchies of servers may have different keys. -### `FunctionResource` +### `FunctionResource` A resource that defers data loading by wrapping a function. @@ -101,7 +104,7 @@ The function can return: **Methods:** -#### `from_function` +#### `from_function` ```python from_function(cls, fn: Callable[..., Any], uri: str | AnyUrl, name: str | None = None, title: str | None = None, description: str | None = None, mime_type: str | None = None, tags: set[str] | None = None, enabled: bool | None = None, annotations: Annotations | None = None, meta: dict[str, Any] | None = None) -> FunctionResource @@ -110,7 +113,7 @@ from_function(cls, fn: Callable[..., Any], uri: str | AnyUrl, name: str | None = Create a FunctionResource from a function. -#### `read` +#### `read` ```python read(self) -> str | bytes diff --git a/docs/python-sdk/fastmcp-resources-resource_manager.mdx b/docs/python-sdk/fastmcp-resources-resource_manager.mdx index 3a4c7c59c..c977132ba 100644 --- a/docs/python-sdk/fastmcp-resources-resource_manager.mdx +++ b/docs/python-sdk/fastmcp-resources-resource_manager.mdx @@ -10,7 +10,7 @@ Resource manager functionality. ## Classes -### `ResourceManager` +### `ResourceManager` Manages FastMCP resources. @@ -18,16 +18,7 @@ Manages FastMCP resources. **Methods:** -#### `mount` - -```python -mount(self, server: MountedServer) -> None -``` - -Adds a mounted server as a source for resources and templates. - - -#### `get_resources` +#### `get_resources` ```python get_resources(self) -> dict[str, Resource] @@ -36,7 +27,7 @@ get_resources(self) -> dict[str, Resource] Get all registered resources, keyed by URI. -#### `get_resource_templates` +#### `get_resource_templates` ```python get_resource_templates(self) -> dict[str, ResourceTemplate] @@ -45,25 +36,7 @@ get_resource_templates(self) -> dict[str, ResourceTemplate] Get all registered templates, keyed by URI template. -#### `list_resources` - -```python -list_resources(self) -> list[Resource] -``` - -Lists all resources, applying protocol filtering. - - -#### `list_resource_templates` - -```python -list_resource_templates(self) -> list[ResourceTemplate] -``` - -Lists all templates, applying protocol filtering. - - -#### `add_resource_or_template_from_fn` +#### `add_resource_or_template_from_fn` ```python add_resource_or_template_from_fn(self, fn: Callable[..., Any], uri: str, name: str | None = None, description: str | None = None, mime_type: str | None = None, tags: set[str] | None = None) -> Resource | ResourceTemplate @@ -84,7 +57,7 @@ Add a resource or template to the manager from a function. - returns the existing resource or template. -#### `add_resource_from_fn` +#### `add_resource_from_fn` ```python add_resource_from_fn(self, fn: Callable[..., Any], uri: str, name: str | None = None, description: str | None = None, mime_type: str | None = None, tags: set[str] | None = None) -> Resource @@ -105,7 +78,7 @@ Add a resource to the manager from a function. - returns the existing resource. -#### `add_resource` +#### `add_resource` ```python add_resource(self, resource: Resource) -> Resource @@ -119,7 +92,7 @@ will be used as the storage key. To overwrite it, call Resource.model_copy(key=new_key) before calling this method. -#### `add_template_from_fn` +#### `add_template_from_fn` ```python add_template_from_fn(self, fn: Callable[..., Any], uri_template: str, name: str | None = None, description: str | None = None, mime_type: str | None = None, tags: set[str] | None = None) -> ResourceTemplate @@ -128,7 +101,7 @@ add_template_from_fn(self, fn: Callable[..., Any], uri_template: str, name: str Create a template from a function. -#### `add_template` +#### `add_template` ```python add_template(self, template: ResourceTemplate) -> ResourceTemplate @@ -146,7 +119,7 @@ ResourceTemplate.model_copy(key=new_key) before calling this method. - returns the existing template. -#### `has_resource` +#### `has_resource` ```python has_resource(self, uri: AnyUrl | str) -> bool @@ -155,7 +128,7 @@ has_resource(self, uri: AnyUrl | str) -> bool Check if a resource exists. -#### `get_resource` +#### `get_resource` ```python get_resource(self, uri: AnyUrl | str) -> Resource @@ -170,7 +143,7 @@ Get resource by URI, checking concrete resources first, then templates. - `NotFoundError`: If no resource or template matching the URI is found. -#### `read_resource` +#### `read_resource` ```python read_resource(self, uri: AnyUrl | str) -> str | bytes diff --git a/docs/python-sdk/fastmcp-resources-template.mdx b/docs/python-sdk/fastmcp-resources-template.mdx index f67ac5e14..3ea550b0b 100644 --- a/docs/python-sdk/fastmcp-resources-template.mdx +++ b/docs/python-sdk/fastmcp-resources-template.mdx @@ -10,21 +10,48 @@ Resource template functionality. ## Functions -### `build_regex` +### `extract_query_params` + +```python +extract_query_params(uri_template: str) -> set[str] +``` + + +Extract query parameter names from RFC 6570 {?param1,param2} syntax. + + +### `build_regex` ```python build_regex(template: str) -> re.Pattern ``` -### `match_uri_template` + +Build regex pattern for URI template, handling RFC 6570 syntax. + +Supports: +- {var} - simple path parameter +- {var*} - wildcard path parameter (captures multiple segments) +- {?var1,var2} - query parameters (ignored in path matching) + + +### `match_uri_template` ```python match_uri_template(uri: str, uri_template: str) -> dict[str, str] | None ``` + +Match URI against template and extract both path and query parameters. + +Supports RFC 6570 URI templates: +- Path params: {var}, {var*} +- Query params: {?var1,var2} + + ## Classes -### `ResourceTemplate` +### `ResourceTemplate` A template for dynamically creating resources. @@ -32,25 +59,25 @@ A template for dynamically creating resources. **Methods:** -#### `enable` +#### `enable` ```python enable(self) -> None ``` -#### `disable` +#### `disable` ```python disable(self) -> None ``` -#### `from_function` +#### `from_function` ```python from_function(fn: Callable[..., Any], uri_template: str, name: str | None = None, title: str | None = None, description: str | None = None, mime_type: str | None = None, tags: set[str] | None = None, enabled: bool | None = None, annotations: Annotations | None = None, meta: dict[str, Any] | None = None) -> FunctionResourceTemplate ``` -#### `set_default_mime_type` +#### `set_default_mime_type` ```python set_default_mime_type(cls, mime_type: str | None) -> str @@ -59,7 +86,7 @@ set_default_mime_type(cls, mime_type: str | None) -> str Set default MIME type if not provided. -#### `matches` +#### `matches` ```python matches(self, uri: str) -> dict[str, Any] | None @@ -68,7 +95,7 @@ matches(self, uri: str) -> dict[str, Any] | None Check if URI matches template and extract parameters. -#### `read` +#### `read` ```python read(self, arguments: dict[str, Any]) -> str | bytes @@ -77,7 +104,7 @@ read(self, arguments: dict[str, Any]) -> str | bytes Read the resource content. -#### `create_resource` +#### `create_resource` ```python create_resource(self, uri: str, params: dict[str, Any]) -> Resource @@ -86,7 +113,7 @@ create_resource(self, uri: str, params: dict[str, Any]) -> Resource Create a resource from the template with the given parameters. -#### `to_mcp_template` +#### `to_mcp_template` ```python to_mcp_template(self, **overrides: Any) -> MCPResourceTemplate @@ -95,7 +122,7 @@ to_mcp_template(self, **overrides: Any) -> MCPResourceTemplate Convert the resource template to an MCPResourceTemplate. -#### `from_mcp_template` +#### `from_mcp_template` ```python from_mcp_template(cls, mcp_template: MCPResourceTemplate) -> ResourceTemplate @@ -104,7 +131,7 @@ from_mcp_template(cls, mcp_template: MCPResourceTemplate) -> ResourceTemplate Creates a FastMCP ResourceTemplate from a raw MCP ResourceTemplate object. -#### `key` +#### `key` ```python key(self) -> str @@ -116,7 +143,7 @@ keys having a certain value, as the same tool loaded from different hierarchies of servers may have different keys. -### `FunctionResourceTemplate` +### `FunctionResourceTemplate` A template for dynamically creating resources. @@ -124,7 +151,7 @@ A template for dynamically creating resources. **Methods:** -#### `read` +#### `read` ```python read(self, arguments: dict[str, Any]) -> str | bytes @@ -133,7 +160,7 @@ read(self, arguments: dict[str, Any]) -> str | bytes Read the resource content. -#### `from_function` +#### `from_function` ```python from_function(cls, fn: Callable[..., Any], uri_template: str, name: str | None = None, title: str | None = None, description: str | None = None, mime_type: str | None = None, tags: set[str] | None = None, enabled: bool | None = None, annotations: Annotations | None = None, meta: dict[str, Any] | None = None) -> FunctionResourceTemplate diff --git a/docs/python-sdk/fastmcp-server-auth-auth.mdx b/docs/python-sdk/fastmcp-server-auth-auth.mdx index d95e116d2..ae7f2f543 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,10 +43,10 @@ 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] +get_routes(self, mcp_path: str | None = None) -> list[Route] ``` Get the routes for this authentication provider. @@ -59,13 +59,14 @@ Each provider is responsible for creating whatever routes it needs: **Args:** - `mcp_path`: The path where the MCP endpoint is mounted (e.g., "/mcp") -- `mcp_endpoint`: The MCP endpoint handler to protect with auth +This is used to advertise the resource URL in metadata, but the +provider does not create the actual MCP endpoint route. **Returns:** -- List of routes for this provider, including protected MCP endpoints if provided +- List of routes for this provider (excluding the MCP endpoint itself) -#### `get_middleware` +#### `get_middleware` ```python get_middleware(self) -> list @@ -77,7 +78,7 @@ Get HTTP application-level middleware for this auth provider. - List of Starlette Middleware instances to apply to the HTTP app -### `TokenVerifier` +### `TokenVerifier` Base class for token verifiers (Resource Servers). @@ -88,7 +89,7 @@ Token verifiers typically don't provide authentication routes by default. **Methods:** -#### `verify_token` +#### `verify_token` ```python verify_token(self, token: str) -> AccessToken | None @@ -97,7 +98,7 @@ verify_token(self, token: str) -> AccessToken | None Verify a bearer token and return access info if valid. -### `RemoteAuthProvider` +### `RemoteAuthProvider` Authentication provider for resource servers that verify tokens from known authorization servers. @@ -114,7 +115,7 @@ the authorization servers that issue valid tokens. **Methods:** -#### `verify_token` +#### `verify_token` ```python verify_token(self, token: str) -> AccessToken | None @@ -123,18 +124,18 @@ verify_token(self, token: str) -> AccessToken | None Verify token using the configured token verifier. -#### `get_routes` +#### `get_routes` ```python -get_routes(self, mcp_path: str | None = None, mcp_endpoint: Any | None = None) -> list[Route] +get_routes(self, mcp_path: str | None = None) -> list[Route] ``` Get OAuth routes for this provider. -Creates protected resource metadata routes and optionally wraps MCP endpoints with auth. +Creates protected resource metadata routes. -### `OAuthProvider` +### `OAuthProvider` OAuth Authorization Server provider. @@ -145,7 +146,7 @@ authorization flows, token issuance, and token verification. **Methods:** -#### `verify_token` +#### `verify_token` ```python verify_token(self, token: str) -> AccessToken | None @@ -163,10 +164,10 @@ to our existing load_access_token method. - 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] +get_routes(self, mcp_path: str | None = None) -> list[Route] ``` Get OAuth authorization server routes and optional protected resource routes. @@ -174,7 +175,6 @@ Get OAuth authorization server routes and optional protected resource routes. This method creates the full set of OAuth routes including: - Standard OAuth authorization server routes (/.well-known/oauth-authorization-server, /authorize, /token, etc.) - Optional protected resource routes -- Protected MCP endpoints if provided **Returns:** - List of OAuth routes diff --git a/docs/python-sdk/fastmcp-server-auth-oauth_proxy.mdx b/docs/python-sdk/fastmcp-server-auth-oauth_proxy.mdx index df2a262ba..9b363a46d 100644 --- a/docs/python-sdk/fastmcp-server-auth-oauth_proxy.mdx +++ b/docs/python-sdk/fastmcp-server-auth-oauth_proxy.mdx @@ -24,9 +24,39 @@ This implementation is based on the OAuth 2.1 specification and is designed for production use with enterprise identity providers. +## Functions + +### `create_consent_html` + +```python +create_consent_html(client_id: str, redirect_uri: str, scopes: list[str], txn_id: str, csrf_token: str, client_name: str | None = None, title: str = 'Authorization Consent') -> str +``` + + +Create a styled HTML consent page for OAuth authorization requests. + + ## Classes -### `ProxyDCRClient` +### `OAuthTransaction` + + +OAuth transaction state for consent flow. + +Stored server-side to track active authorization flows with client context. +Includes CSRF tokens for consent protection per MCP security best practices. + + +### `ClientCode` + + +Client authorization code with PKCE and upstream tokens. + +Stored server-side after upstream IdP callback. Contains the upstream +tokens bound to the client's PKCE challenge for secure token exchange. + + +### `ProxyDCRClient` Client for DCR proxy with configurable redirect URI validation. @@ -56,7 +86,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 +100,39 @@ This is essential for cached token scenarios where the client may reconnect with a different port. -### `OAuthProxy` +### `TokenHandler` + + +TokenHandler that returns OAuth 2.1 compliant error responses. + +The MCP SDK always returns HTTP 400 for all client authentication issues. +However, OAuth 2.1 Section 5.3 and the MCP specification require that +invalid or expired tokens MUST receive a HTTP 401 response. + +This handler extends the base MCP SDK TokenHandler to transform client +authentication failures into OAuth 2.1 compliant responses: +- Changes 'unauthorized_client' to 'invalid_client' error code +- Returns HTTP 401 status code instead of 400 for client auth failures + +Per OAuth 2.1 Section 5.3: "The authorization server MAY return an HTTP 401 +(Unauthorized) status code to indicate which HTTP authentication schemes +are supported." + +Per MCP spec: "Invalid or expired tokens MUST receive a HTTP 401 response." + + +**Methods:** + +#### `response` + +```python +response(self, obj: TokenSuccessResponse | TokenErrorResponse) +``` + +Override response method to provide OAuth 2.1 compliant error handling. + + +### `OAuthProxy` OAuth provider that presents a DCR-compliant interface while proxying to non-DCR IDPs. @@ -151,7 +213,6 @@ OAuth Flow Implementation State Management --------------- The proxy maintains minimal but crucial state: -- _clients: DCR registrations (all use ProxyDCRClient for flexibility) - _oauth_transactions: Active authorization flows with client context - _client_codes: Authorization codes with PKCE challenges and upstream tokens - _access_tokens, _refresh_tokens: Token storage for revocation @@ -181,7 +242,7 @@ Handles provider-specific requirements: **Methods:** -#### `get_client` +#### `get_client` ```python get_client(self, client_id: str) -> OAuthClientInformationFull | None @@ -193,7 +254,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,22 +268,21 @@ 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 ``` -Start OAuth transaction and redirect to upstream IdP. +Start OAuth transaction and route through consent interstitial. -This implements the DCR-compliant proxy pattern: -1. Store transaction with client details and PKCE challenge -2. Generate proxy's own PKCE parameters if forwarding is enabled -3. Use transaction ID as state for IdP -4. Redirect to IdP with our fixed callback URL and proxy's PKCE +Flow: +1. Store transaction with client details and PKCE (if forwarding) +2. Return local /consent URL; browser visits consent first +3. Consent handler redirects to upstream IdP if approved/already approved -#### `load_authorization_code` +#### `load_authorization_code` ```python load_authorization_code(self, client: OAuthClientInformationFull, authorization_code: str) -> AuthorizationCode | None @@ -234,7 +294,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 +306,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 +315,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 +324,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 +336,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,10 +348,10 @@ 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] +get_routes(self, mcp_path: str | None = None) -> list[Route] ``` Get OAuth routes with custom proxy token handler. @@ -301,5 +361,5 @@ with our proxy handler that forwards requests to the upstream OAuth server. **Args:** - `mcp_path`: The path where the MCP endpoint is mounted (e.g., "/mcp") -- `mcp_endpoint`: The MCP endpoint handler to protect with auth +This is used to advertise the resource URL in metadata. diff --git a/docs/python-sdk/fastmcp-server-auth-oidc_proxy.mdx b/docs/python-sdk/fastmcp-server-auth-oidc_proxy.mdx index f20b2dcdf..ed0df1307 100644 --- a/docs/python-sdk/fastmcp-server-auth-oidc_proxy.mdx +++ b/docs/python-sdk/fastmcp-server-auth-oidc_proxy.mdx @@ -52,7 +52,7 @@ that is OIDC compliant. **Methods:** -#### `get_oidc_configuration` +#### `get_oidc_configuration` ```python get_oidc_configuration(self, config_url: AnyHttpUrl, strict: bool | None, timeout_seconds: int | None) -> OIDCConfiguration @@ -66,7 +66,7 @@ Gets the OIDC configuration for the specified configuration URL. - `timeout_seconds`: HTTP request timeout in seconds -#### `get_token_verifier` +#### `get_token_verifier` ```python get_token_verifier(self) -> TokenVerifier diff --git a/docs/python-sdk/fastmcp-server-auth-providers-auth0.mdx b/docs/python-sdk/fastmcp-server-auth-providers-auth0.mdx index 344f29b64..fc58544d5 100644 --- a/docs/python-sdk/fastmcp-server-auth-providers-auth0.mdx +++ b/docs/python-sdk/fastmcp-server-auth-providers-auth0.mdx @@ -31,13 +31,13 @@ Example: ## Classes -### `Auth0ProviderSettings` +### `Auth0ProviderSettings` Settings for Auth0 OIDC provider. -### `Auth0Provider` +### `Auth0Provider` An Auth0 provider implementation for FastMCP. diff --git a/docs/python-sdk/fastmcp-server-auth-providers-aws.mdx b/docs/python-sdk/fastmcp-server-auth-providers-aws.mdx index 290951a5a..cf8063a9d 100644 --- a/docs/python-sdk/fastmcp-server-auth-providers-aws.mdx +++ b/docs/python-sdk/fastmcp-server-auth-providers-aws.mdx @@ -31,13 +31,13 @@ Example: ## Classes -### `AWSCognitoProviderSettings` +### `AWSCognitoProviderSettings` Settings for AWS Cognito OAuth provider. -### `AWSCognitoTokenVerifier` +### `AWSCognitoTokenVerifier` Token verifier that filters claims to Cognito-specific subset. @@ -45,7 +45,7 @@ Token verifier that filters claims to Cognito-specific subset. **Methods:** -#### `verify_token` +#### `verify_token` ```python verify_token(self, token: str) -> AccessToken | None @@ -54,7 +54,7 @@ verify_token(self, token: str) -> AccessToken | None Verify token and filter claims to Cognito-specific subset. -### `AWSCognitoProvider` +### `AWSCognitoProvider` Complete AWS Cognito OAuth provider for FastMCP. @@ -72,7 +72,7 @@ Features: **Methods:** -#### `get_token_verifier` +#### `get_token_verifier` ```python get_token_verifier(self) -> TokenVerifier diff --git a/docs/python-sdk/fastmcp-server-auth-providers-azure.mdx b/docs/python-sdk/fastmcp-server-auth-providers-azure.mdx index 463e5f731..d44054dc7 100644 --- a/docs/python-sdk/fastmcp-server-auth-providers-azure.mdx +++ b/docs/python-sdk/fastmcp-server-auth-providers-azure.mdx @@ -14,33 +14,13 @@ using the OAuth Proxy pattern for non-DCR OAuth flows. ## Classes -### `AzureProviderSettings` +### `AzureProviderSettings` Settings for Azure OAuth provider. -### `AzureTokenVerifier` - - -Token verifier for Azure OAuth tokens. - -Azure tokens are JWTs, but we verify them by calling the Microsoft Graph API -to get user information and validate the token. - - -**Methods:** - -#### `verify_token` - -```python -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. @@ -50,14 +30,37 @@ OAuth Proxy pattern. It supports both organizational accounts and personal Microsoft accounts depending on the tenant configuration. Features: -- Transparent OAuth proxy to Azure/Microsoft identity platform -- Automatic token validation via Microsoft Graph API -- User information extraction -- Support for different tenant configurations (common, organizations, consumers) +- OAuth proxy to Azure/Microsoft identity platform +- JWT validation using tenant issuer and JWKS +- Supports tenant configurations: specific tenant ID, "organizations", or "consumers" -Setup Requirements: -1. Register an application in Azure Portal (portal.azure.com) -2. Configure redirect URI as: http://localhost:8000/auth/callback -3. Note your Application (client) ID and create a client secret -4. Optionally note your Directory (tenant) ID for single-tenant apps +Setup: +1. Create an App registration in Azure Portal +2. Configure Web platform redirect URI: http://localhost:8000/auth/callback (or your custom path) +3. Add an Application ID URI. Either use the default (api://{client_id}) or set a custom one. +4. Add a custom scope. +5. Create a client secret. +6. Get Application (client) ID, Directory (tenant) ID, and client secret + + +**Methods:** + +#### `authorize` + +```python +authorize(self, client: OAuthClientInformationFull, params: AuthorizationParams) -> str +``` + +Start OAuth transaction and redirect to Azure AD. + +Override parent's authorize method to filter out the 'resource' parameter +which is not supported by Azure AD v2.0 endpoints. The v2.0 endpoints use +scopes to determine the resource/audience instead of a separate parameter. + +**Args:** +- `client`: OAuth client information +- `params`: Authorization parameters from the client + +**Returns:** +- Authorization URL to redirect the user to Azure AD diff --git a/docs/python-sdk/fastmcp-server-auth-providers-descope.mdx b/docs/python-sdk/fastmcp-server-auth-providers-descope.mdx index 2064a25b1..9d14c4964 100644 --- a/docs/python-sdk/fastmcp-server-auth-providers-descope.mdx +++ b/docs/python-sdk/fastmcp-server-auth-providers-descope.mdx @@ -15,9 +15,9 @@ for seamless MCP client authentication. ## Classes -### `DescopeProviderSettings` +### `DescopeProviderSettings` -### `DescopeProvider` +### `DescopeProvider` Descope metadata provider for DCR (Dynamic Client Registration). @@ -45,10 +45,10 @@ https://docs.descope.com/identity-federation/inbound-apps/creating-inbound-apps# **Methods:** -#### `get_routes` +#### `get_routes` ```python -get_routes(self, mcp_path: str | None = None, mcp_endpoint: Any | None = None) -> list[Route] +get_routes(self, mcp_path: str | None = None) -> list[Route] ``` Get OAuth routes including Descope authorization server metadata forwarding. @@ -58,5 +58,5 @@ 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 +This is used to advertise the resource URL in metadata. diff --git a/docs/python-sdk/fastmcp-server-auth-providers-github.mdx b/docs/python-sdk/fastmcp-server-auth-providers-github.mdx index e72034495..0a93964b3 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 20d3a63e9..90ae29dab 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-introspection.mdx b/docs/python-sdk/fastmcp-server-auth-providers-introspection.mdx new file mode 100644 index 000000000..1d7eeda22 --- /dev/null +++ b/docs/python-sdk/fastmcp-server-auth-providers-introspection.mdx @@ -0,0 +1,77 @@ +--- +title: introspection +sidebarTitle: introspection +--- + +# `fastmcp.server.auth.providers.introspection` + + +OAuth 2.0 Token Introspection (RFC 7662) provider for FastMCP. + +This module provides token verification for opaque tokens using the OAuth 2.0 +Token Introspection protocol defined in RFC 7662. It allows FastMCP servers to +validate tokens issued by authorization servers that don't use JWT format. + +Example: + ```python + from fastmcp import FastMCP + from fastmcp.server.auth.providers.introspection import IntrospectionTokenVerifier + + # Verify opaque tokens via RFC 7662 introspection + verifier = IntrospectionTokenVerifier( + introspection_url="https://auth.example.com/oauth/introspect", + client_id="your-client-id", + client_secret="your-client-secret", + required_scopes=["read", "write"] + ) + + mcp = FastMCP("My Protected Server", auth=verifier) + ``` + + +## Classes + +### `IntrospectionTokenVerifierSettings` + + +Settings for OAuth 2.0 Token Introspection verification. + + +### `IntrospectionTokenVerifier` + + +OAuth 2.0 Token Introspection verifier (RFC 7662). + +This verifier validates opaque tokens by calling an OAuth 2.0 token introspection +endpoint. Unlike JWT verification which is stateless, token introspection requires +a network call to the authorization server for each token validation. + +The verifier authenticates to the introspection endpoint using HTTP Basic Auth +with the provided client_id and client_secret, as specified in RFC 7662. + +Use this when: +- Your authorization server issues opaque (non-JWT) tokens +- You need to validate tokens from Auth0, Okta, Keycloak, or other OAuth servers +- Your tokens require real-time revocation checking +- Your authorization server supports RFC 7662 introspection + + +**Methods:** + +#### `verify_token` + +```python +verify_token(self, token: str) -> AccessToken | None +``` + +Verify a bearer token using OAuth 2.0 Token Introspection (RFC 7662). + +This method makes a POST request to the introspection endpoint with the token, +authenticated using HTTP Basic Auth with the client credentials. + +**Args:** +- `token`: The opaque token string to validate + +**Returns:** +- AccessToken object if valid and active, None if invalid, inactive, or expired + diff --git a/docs/python-sdk/fastmcp-server-auth-providers-jwt.mdx b/docs/python-sdk/fastmcp-server-auth-providers-jwt.mdx index e46059402..345ec7b95 100644 --- a/docs/python-sdk/fastmcp-server-auth-providers-jwt.mdx +++ b/docs/python-sdk/fastmcp-server-auth-providers-jwt.mdx @@ -10,19 +10,19 @@ TokenVerifier implementations for FastMCP. ## Classes -### `JWKData` +### `JWKData` JSON Web Key data structure. -### `JWKSData` +### `JWKSData` JSON Web Key Set data structure. -### `RSAKeyPair` +### `RSAKeyPair` RSA key pair for JWT testing. @@ -30,7 +30,7 @@ RSA key pair for JWT testing. **Methods:** -#### `generate` +#### `generate` ```python generate(cls) -> RSAKeyPair @@ -42,7 +42,7 @@ Generate an RSA key pair for testing. - Generated key pair -#### `create_token` +#### `create_token` ```python create_token(self, subject: str = 'fastmcp-user', issuer: str = 'https://fastmcp.example.com', audience: str | list[str] | None = None, scopes: list[str] | None = None, expires_in_seconds: int = 3600, additional_claims: dict[str, Any] | None = None, kid: str | None = None) -> str @@ -60,13 +60,13 @@ Generate a test JWT token for testing purposes. - `kid`: Key ID to include in header -### `JWTVerifierSettings` +### `JWTVerifierSettings` Settings for JWT token verification. -### `JWTVerifier` +### `JWTVerifier` JWT token verifier supporting both asymmetric (RSA/ECDSA) and symmetric (HMAC) algorithms. @@ -88,7 +88,7 @@ Use this when: **Methods:** -#### `load_access_token` +#### `load_access_token` ```python load_access_token(self, token: str) -> AccessToken | None @@ -103,7 +103,7 @@ Validates the provided JWT bearer token. - AccessToken object if valid, None if invalid or expired -#### `verify_token` +#### `verify_token` ```python verify_token(self, token: str) -> AccessToken | None @@ -121,7 +121,7 @@ to our existing load_access_token method. - AccessToken object if valid, None if invalid or expired -### `StaticTokenVerifier` +### `StaticTokenVerifier` Simple static token verifier for testing and development. @@ -142,7 +142,7 @@ WARNING: Never use this in production - tokens are stored in plain text! **Methods:** -#### `verify_token` +#### `verify_token` ```python verify_token(self, token: str) -> AccessToken | None diff --git a/docs/python-sdk/fastmcp-server-auth-providers-scalekit.mdx b/docs/python-sdk/fastmcp-server-auth-providers-scalekit.mdx index f1b9a5df0..7dd465a29 100644 --- a/docs/python-sdk/fastmcp-server-auth-providers-scalekit.mdx +++ b/docs/python-sdk/fastmcp-server-auth-providers-scalekit.mdx @@ -15,9 +15,9 @@ authentication for seamless MCP client authentication. ## Classes -### `ScalekitProviderSettings` +### `ScalekitProviderSettings` -### `ScalekitProvider` +### `ScalekitProvider` Scalekit resource server provider for OAuth 2.1 authentication. @@ -47,10 +47,10 @@ https://docs.scalekit.com/mcp/overview/ **Methods:** -#### `get_routes` +#### `get_routes` ```python -get_routes(self, mcp_path: str | None = None, mcp_endpoint: Any | None = None) -> list[Route] +get_routes(self, mcp_path: str | None = None) -> list[Route] ``` Get OAuth routes including Scalekit authorization server metadata forwarding. @@ -60,5 +60,5 @@ 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 +This is used to advertise the resource URL in metadata. diff --git a/docs/python-sdk/fastmcp-server-auth-providers-supabase.mdx b/docs/python-sdk/fastmcp-server-auth-providers-supabase.mdx new file mode 100644 index 000000000..603672d13 --- /dev/null +++ b/docs/python-sdk/fastmcp-server-auth-providers-supabase.mdx @@ -0,0 +1,62 @@ +--- +title: supabase +sidebarTitle: supabase +--- + +# `fastmcp.server.auth.providers.supabase` + + +Supabase authentication provider for FastMCP. + +This module provides SupabaseProvider - a complete authentication solution that integrates +with Supabase Auth's JWT verification, supporting Dynamic Client Registration (DCR) +for seamless MCP client authentication. + + +## Classes + +### `SupabaseProviderSettings` + +### `SupabaseProvider` + + +Supabase metadata provider for DCR (Dynamic Client Registration). + +This provider implements Supabase Auth integration using metadata forwarding. +This approach allows Supabase to handle the OAuth flow directly while FastMCP acts +as a resource server, verifying JWTs issued by Supabase Auth. + +IMPORTANT SETUP REQUIREMENTS: + +1. Supabase Project Setup: + - Create a Supabase project at https://supabase.com + - Note your project URL (e.g., "https://abc123.supabase.co") + - For projects created after May 1st, 2025, asymmetric RS256 keys are used by default + - For older projects, consider migrating to asymmetric keys for better security + +2. JWT Verification: + - FastMCP verifies JWTs using the JWKS endpoint at {project_url}/auth/v1/.well-known/jwks.json + - JWTs are issued by {project_url}/auth/v1 + - Tokens are cached for up to 10 minutes by Supabase's edge servers + +For detailed setup instructions, see: +https://supabase.com/docs/guides/auth/jwts + + +**Methods:** + +#### `get_routes` + +```python +get_routes(self, mcp_path: str | None = None) -> list[Route] +``` + +Get OAuth routes including Supabase authorization server metadata forwarding. + +This returns the standard protected resource routes plus an authorization server +metadata endpoint that forwards Supabase's OAuth metadata to clients. + +**Args:** +- `mcp_path`: The path where the MCP endpoint is mounted (e.g., "/mcp") +This is used to advertise the resource URL in metadata. + diff --git a/docs/python-sdk/fastmcp-server-auth-providers-workos.mdx b/docs/python-sdk/fastmcp-server-auth-providers-workos.mdx index a4ac73e02..e38942ee1 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,10 +93,10 @@ 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] +get_routes(self, mcp_path: str | None = None) -> list[Route] ``` Get OAuth routes including AuthKit authorization server metadata forwarding. @@ -106,5 +106,5 @@ metadata endpoint that forwards AuthKit'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 +This is used to advertise the resource URL in metadata. diff --git a/docs/python-sdk/fastmcp-server-context.mdx b/docs/python-sdk/fastmcp-server-context.mdx index f828d513f..13b6e18ca 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. @@ -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 @@ -128,6 +128,8 @@ log(self, message: str, level: LoggingLevel | None = None, logger_name: str | No Send a log message to the client. +Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`. + **Args:** - `message`: Log message - `level`: Optional log level. One of "debug", "info", "notice", "warning", "error", "critical", @@ -136,7 +138,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 +147,7 @@ client_id(self) -> str | None Get the client ID if available. -#### `request_id` +#### `request_id` ```python request_id(self) -> str @@ -154,7 +156,7 @@ request_id(self) -> str Get the unique ID for this request. -#### `session_id` +#### `session_id` ```python session_id(self) -> str @@ -171,7 +173,7 @@ the same client session. - for other transports. -#### `session` +#### `session` ```python session(self) -> ServerSession @@ -180,43 +182,51 @@ 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 ``` -Send a debug log message. +Send a `DEBUG`-level message to the connected MCP Client. + +Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`. -#### `info` +#### `info` ```python info(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None ``` -Send an info log message. +Send a `INFO`-level message to the connected MCP Client. + +Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`. -#### `warning` +#### `warning` ```python warning(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None ``` -Send a warning log message. +Send a `WARNING`-level message to the connected MCP Client. + +Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`. -#### `error` +#### `error` ```python error(self, message: str, logger_name: str | None = None, extra: Mapping[str, Any] | None = None) -> None ``` -Send an error log message. +Send a `ERROR`-level message to the connected MCP Client. + +Messages sent to Clients are also logged to the `fastmcp.server.context.to_client` logger with a level of `DEBUG`. -#### `list_roots` +#### `list_roots` ```python list_roots(self) -> list[Root] @@ -225,7 +235,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 +244,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 +253,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,7 +262,7 @@ send_prompt_list_changed(self) -> None Send a prompt list changed notification to the client. -#### `sample` +#### `sample` ```python 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 @@ -265,25 +275,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 +322,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 +331,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 +340,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-http.mdx b/docs/python-sdk/fastmcp-server-http.mdx index 0a7ee46ca..6ded1069f 100644 --- a/docs/python-sdk/fastmcp-server-http.mdx +++ b/docs/python-sdk/fastmcp-server-http.mdx @@ -54,7 +54,7 @@ Returns: A Starlette application with RequestContextMiddleware -### `create_streamable_http_app` +### `create_streamable_http_app` ```python create_streamable_http_app(server: FastMCP[LifespanResultT], streamable_http_path: str, event_store: EventStore | None = None, auth: AuthProvider | None = None, json_response: bool = False, stateless_http: bool = False, debug: bool = False, routes: list[BaseRoute] | None = None, middleware: list[Middleware] | None = None) -> StarletteWithLifespan diff --git a/docs/python-sdk/fastmcp-server-low_level.mdx b/docs/python-sdk/fastmcp-server-low_level.mdx index 2f7197358..fd3dcaeec 100644 --- a/docs/python-sdk/fastmcp-server-low_level.mdx +++ b/docs/python-sdk/fastmcp-server-low_level.mdx @@ -7,12 +7,47 @@ sidebarTitle: low_level ## Classes -### `LowLevelServer` +### `MiddlewareServerSession` + + +ServerSession that routes initialization requests through FastMCP middleware. + **Methods:** -#### `create_initialization_options` +#### `fastmcp` + +```python +fastmcp(self) -> FastMCP +``` + +Get the FastMCP instance. + + +### `LowLevelServer` + +**Methods:** + +#### `fastmcp` + +```python +fastmcp(self) -> FastMCP +``` + +Get the FastMCP instance. + + +#### `create_initialization_options` ```python create_initialization_options(self, notification_options: NotificationOptions | None = None, experimental_capabilities: dict[str, dict[str, Any]] | None = None, **kwargs: Any) -> InitializationOptions ``` + +#### `run` + +```python +run(self, read_stream: MemoryObjectReceiveStream[SessionMessage | Exception], write_stream: MemoryObjectSendStream[SessionMessage], initialization_options: InitializationOptions, raise_exceptions: bool = False, stateless: bool = False) +``` + +Overrides the run method to use the MiddlewareServerSession. + diff --git a/docs/python-sdk/fastmcp-server-middleware-logging.mdx b/docs/python-sdk/fastmcp-server-middleware-logging.mdx index fd6ee041c..292d55583 100644 --- a/docs/python-sdk/fastmcp-server-middleware-logging.mdx +++ b/docs/python-sdk/fastmcp-server-middleware-logging.mdx @@ -10,7 +10,7 @@ Comprehensive logging middleware for FastMCP servers. ## Functions -### `default_serializer` +### `default_serializer` ```python default_serializer(data: Any) -> str @@ -22,7 +22,7 @@ The default serializer for Payloads in the logging middleware. ## Classes -### `BaseLoggingMiddleware` +### `BaseLoggingMiddleware` Base class for logging middleware. @@ -30,16 +30,16 @@ Base class for logging middleware. **Methods:** -#### `on_message` +#### `on_message` ```python on_message(self, context: MiddlewareContext[Any], call_next: CallNext[Any, Any]) -> Any ``` -Log all messages. +Log messages for configured methods. -### `LoggingMiddleware` +### `LoggingMiddleware` Middleware that provides comprehensive request and response logging. @@ -48,7 +48,7 @@ Logs all MCP messages with configurable detail levels. Useful for debugging, monitoring, and understanding server usage patterns. -### `StructuredLoggingMiddleware` +### `StructuredLoggingMiddleware` Middleware that provides structured JSON logging for better log analysis. diff --git a/docs/python-sdk/fastmcp-server-middleware-middleware.mdx b/docs/python-sdk/fastmcp-server-middleware-middleware.mdx index a530af4b1..428c7e260 100644 --- a/docs/python-sdk/fastmcp-server-middleware-middleware.mdx +++ b/docs/python-sdk/fastmcp-server-middleware-middleware.mdx @@ -45,62 +45,68 @@ 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_request(self, context: MiddlewareContext[mt.Request[Any, Any]], call_next: CallNext[mt.Request[Any, Any], Any]) -> Any ``` -#### `on_notification` +#### `on_notification` ```python -on_notification(self, context: MiddlewareContext[mt.Notification], call_next: CallNext[mt.Notification, Any]) -> Any +on_notification(self, context: MiddlewareContext[mt.Notification[Any, Any]], call_next: CallNext[mt.Notification[Any, Any], Any]) -> Any ``` -#### `on_call_tool` +#### `on_initialize` + +```python +on_initialize(self, context: MiddlewareContext[mt.InitializeRequestParams], call_next: CallNext[mt.InitializeRequestParams, None]) -> None +``` + +#### `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, list[ReadResourceContents]]) -> list[ReadResourceContents] +on_read_resource(self, context: MiddlewareContext[mt.ReadResourceRequestParams], call_next: CallNext[mt.ReadResourceRequestParams, Sequence[ReadResourceContents]]) -> Sequence[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_tools(self, context: MiddlewareContext[mt.ListToolsRequest], call_next: CallNext[mt.ListToolsRequest, Sequence[Tool]]) -> Sequence[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_resources(self, context: MiddlewareContext[mt.ListResourcesRequest], call_next: CallNext[mt.ListResourcesRequest, Sequence[Resource]]) -> Sequence[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_resource_templates(self, context: MiddlewareContext[mt.ListResourceTemplatesRequest], call_next: CallNext[mt.ListResourceTemplatesRequest, Sequence[ResourceTemplate]]) -> Sequence[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] +on_list_prompts(self, context: MiddlewareContext[mt.ListPromptsRequest], call_next: CallNext[mt.ListPromptsRequest, Sequence[Prompt]]) -> Sequence[Prompt] ``` diff --git a/docs/python-sdk/fastmcp-server-server.mdx b/docs/python-sdk/fastmcp-server-server.mdx index 20b58f460..0c25c2d8d 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] @@ -23,10 +23,10 @@ Default lifespan context manager that does nothing. - `server`: The server instance this lifespan is managing **Returns:** -- An empty context object +- An empty dictionary as the lifespan result. -### `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,41 +143,41 @@ 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` +#### `instructions` ```python instructions(self, value: str | None) -> None ``` -#### `version` +#### `version` ```python version(self) -> str | None ``` -#### `run_async` +#### `run_async` ```python run_async(self, transport: Transport | None = None, show_banner: bool = True, **transport_kwargs: Any) -> None @@ -189,7 +189,7 @@ Run the FastMCP server asynchronously. - `transport`: Transport protocol to use ("stdio", "sse", or "streamable-http") -#### `run` +#### `run` ```python run(self, transport: Transport | None = None, show_banner: bool = True, **transport_kwargs: Any) -> None @@ -201,52 +201,52 @@ Run the FastMCP server. Note this is a synchronous function. - `transport`: Transport protocol to use ("stdio", "sse", or "streamable-http") -#### `add_middleware` +#### `add_middleware` ```python add_middleware(self, middleware: Middleware) -> None ``` -#### `get_tools` +#### `get_tools` ```python get_tools(self) -> dict[str, Tool] ``` -Get all registered tools, indexed by registered key. +Get all tools (unfiltered), including mounted servers, indexed by key. -#### `get_tool` +#### `get_tool` ```python get_tool(self, key: str) -> Tool ``` -#### `get_resources` +#### `get_resources` ```python get_resources(self) -> dict[str, Resource] ``` -Get all registered resources, indexed by registered key. +Get all resources (unfiltered), including mounted servers, indexed by key. -#### `get_resource` +#### `get_resource` ```python get_resource(self, key: str) -> Resource ``` -#### `get_resource_templates` +#### `get_resource_templates` ```python get_resource_templates(self) -> dict[str, ResourceTemplate] ``` -Get all registered resource templates, indexed by registered key. +Get all resource templates (unfiltered), including mounted servers, indexed by key. -#### `get_resource_template` +#### `get_resource_template` ```python get_resource_template(self, key: str) -> ResourceTemplate @@ -255,22 +255,22 @@ get_resource_template(self, key: str) -> ResourceTemplate Get a registered resource template by key. -#### `get_prompts` +#### `get_prompts` ```python get_prompts(self) -> dict[str, Prompt] ``` -List all available prompts. +Get all prompts (unfiltered), including mounted servers, indexed by key. -#### `get_prompt` +#### `get_prompt` ```python get_prompt(self, key: str) -> Prompt ``` -#### `custom_route` +#### `custom_route` ```python custom_route(self, path: str, methods: list[str], name: str | None = None, include_in_schema: bool = True) -> Callable[[Callable[[Request], Awaitable[Response]]], Callable[[Request], Awaitable[Response]]] @@ -291,7 +291,7 @@ Starlette's reverse URL lookup feature) - `include_in_schema`: Whether to include in OpenAPI schema, defaults to True -#### `add_tool` +#### `add_tool` ```python add_tool(self, tool: Tool) -> Tool @@ -309,7 +309,7 @@ with the Context type annotation. See the @tool decorator for examples. - The tool instance that was added to the server. -#### `remove_tool` +#### `remove_tool` ```python remove_tool(self, name: str) -> None @@ -324,7 +324,7 @@ Remove a tool from the server. - `NotFoundError`: If the tool is not found -#### `add_tool_transformation` +#### `add_tool_transformation` ```python add_tool_transformation(self, tool_name: str, transformation: ToolTransformConfig) -> None @@ -333,7 +333,7 @@ add_tool_transformation(self, tool_name: str, transformation: ToolTransformConfi Add a tool transformation. -#### `remove_tool_transformation` +#### `remove_tool_transformation` ```python remove_tool_transformation(self, tool_name: str) -> None @@ -342,19 +342,19 @@ remove_tool_transformation(self, tool_name: str) -> None Remove a tool transformation. -#### `tool` +#### `tool` ```python tool(self, name_or_fn: AnyFunction) -> FunctionTool ``` -#### `tool` +#### `tool` ```python tool(self, name_or_fn: str | None = None) -> Callable[[AnyFunction], FunctionTool] ``` -#### `tool` +#### `tool` ```python tool(self, name_or_fn: str | AnyFunction | None = None) -> Callable[[AnyFunction], FunctionTool] | FunctionTool @@ -410,7 +410,7 @@ server.tool(my_function, name="custom_name") ``` -#### `add_resource` +#### `add_resource` ```python add_resource(self, resource: Resource) -> Resource @@ -425,7 +425,7 @@ Add a resource to the server. - The resource instance that was added to the server. -#### `add_template` +#### `add_template` ```python add_template(self, template: ResourceTemplate) -> ResourceTemplate @@ -440,7 +440,7 @@ Add a resource template to the server. - The template instance that was added to the server. -#### `add_resource_fn` +#### `add_resource_fn` ```python add_resource_fn(self, fn: AnyFunction, uri: str, name: str | None = None, description: str | None = None, mime_type: str | None = None, tags: set[str] | None = None) -> None @@ -460,7 +460,7 @@ has parameters, it will be registered as a template resource. - `tags`: Optional set of tags for categorizing the resource -#### `resource` +#### `resource` ```python resource(self, uri: str) -> Callable[[AnyFunction], Resource | ResourceTemplate] @@ -520,7 +520,7 @@ async def get_weather(city: str) -> str: ``` -#### `add_prompt` +#### `add_prompt` ```python add_prompt(self, prompt: Prompt) -> Prompt @@ -535,19 +535,19 @@ Add a prompt to the server. - The prompt instance that was added to the server. -#### `prompt` +#### `prompt` ```python prompt(self, name_or_fn: AnyFunction) -> FunctionPrompt ``` -#### `prompt` +#### `prompt` ```python prompt(self, name_or_fn: str | None = None) -> Callable[[AnyFunction], FunctionPrompt] ``` -#### `prompt` +#### `prompt` ```python prompt(self, name_or_fn: str | AnyFunction | None = None) -> Callable[[AnyFunction], FunctionPrompt] | FunctionPrompt @@ -625,7 +625,7 @@ Decorator to register a prompt. ``` -#### `run_stdio_async` +#### `run_stdio_async` ```python run_stdio_async(self, show_banner: bool = True, log_level: str | None = None) -> None @@ -638,10 +638,10 @@ Run the server using stdio transport. - `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 +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, json_response: bool | None = None, stateless_http: bool | None = None) -> None ``` Run the server using HTTP transport. @@ -654,10 +654,11 @@ Run the server using HTTP transport. - `path`: Path for the endpoint (defaults to settings.streamable_http_path or settings.sse_path) - `uvicorn_config`: Additional configuration for the Uvicorn server - `middleware`: A list of middleware to apply to the app +- `json_response`: Whether to use JSON response format (defaults to settings.json_response) - `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 @@ -666,7 +667,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 @@ -680,7 +681,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 @@ -693,7 +694,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 @@ -710,13 +711,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 @@ -770,7 +771,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 @@ -811,7 +812,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 @@ -820,7 +821,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 @@ -829,7 +830,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 @@ -843,7 +844,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 @@ -852,10 +853,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 6f14415ec..4a0bb8448 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,13 +71,13 @@ 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` +#### `server_auth_class` ```python server_auth_class(self) -> AuthProvider | None diff --git a/docs/python-sdk/fastmcp-tools-tool_manager.mdx b/docs/python-sdk/fastmcp-tools-tool_manager.mdx index 15cbee1db..bf07cb0fd 100644 --- a/docs/python-sdk/fastmcp-tools-tool_manager.mdx +++ b/docs/python-sdk/fastmcp-tools-tool_manager.mdx @@ -7,7 +7,7 @@ sidebarTitle: tool_manager ## Classes -### `ToolManager` +### `ToolManager` Manages FastMCP tools. @@ -15,16 +15,7 @@ Manages FastMCP tools. **Methods:** -#### `mount` - -```python -mount(self, server: MountedServer) -> None -``` - -Adds a mounted server as a source for tools. - - -#### `has_tool` +#### `has_tool` ```python has_tool(self, key: str) -> bool @@ -33,7 +24,7 @@ has_tool(self, key: str) -> bool Check if a tool exists. -#### `get_tool` +#### `get_tool` ```python get_tool(self, key: str) -> Tool @@ -42,25 +33,16 @@ get_tool(self, key: str) -> Tool Get tool by key. -#### `get_tools` +#### `get_tools` ```python get_tools(self) -> dict[str, Tool] ``` -Gets the complete, unfiltered inventory of all tools. +Gets the complete, unfiltered inventory of local tools. -#### `list_tools` - -```python -list_tools(self) -> list[Tool] -``` - -Lists all tools, applying protocol filtering. - - -#### `add_tool_from_fn` +#### `add_tool_from_fn` ```python add_tool_from_fn(self, fn: Callable[..., Any], name: str | None = None, description: str | None = None, tags: set[str] | None = None, annotations: ToolAnnotations | None = None, serializer: Callable[[Any], str] | None = None, exclude_args: list[str] | None = None) -> Tool @@ -69,7 +51,7 @@ add_tool_from_fn(self, fn: Callable[..., Any], name: str | None = None, descript Add a tool to the server. -#### `add_tool` +#### `add_tool` ```python add_tool(self, tool: Tool) -> Tool @@ -78,7 +60,7 @@ add_tool(self, tool: Tool) -> Tool Register a tool with the server. -#### `add_tool_transformation` +#### `add_tool_transformation` ```python add_tool_transformation(self, tool_name: str, transformation: ToolTransformConfig) -> None @@ -87,7 +69,7 @@ add_tool_transformation(self, tool_name: str, transformation: ToolTransformConfi Add a tool transformation. -#### `get_tool_transformation` +#### `get_tool_transformation` ```python get_tool_transformation(self, tool_name: str) -> ToolTransformConfig | None @@ -96,7 +78,7 @@ get_tool_transformation(self, tool_name: str) -> ToolTransformConfig | None Get a tool transformation. -#### `remove_tool_transformation` +#### `remove_tool_transformation` ```python remove_tool_transformation(self, tool_name: str) -> None @@ -105,7 +87,7 @@ remove_tool_transformation(self, tool_name: str) -> None Remove a tool transformation. -#### `remove_tool` +#### `remove_tool` ```python remove_tool(self, key: str) -> None @@ -120,7 +102,7 @@ Remove a tool from the server. - `NotFoundError`: If the tool is not found -#### `call_tool` +#### `call_tool` ```python call_tool(self, key: str, arguments: dict[str, Any]) -> ToolResult diff --git a/docs/python-sdk/fastmcp-tools-tool_transform.mdx b/docs/python-sdk/fastmcp-tools-tool_transform.mdx index ea8652fab..e3d856876 100644 --- a/docs/python-sdk/fastmcp-tools-tool_transform.mdx +++ b/docs/python-sdk/fastmcp-tools-tool_transform.mdx @@ -10,7 +10,7 @@ sidebarTitle: tool_transform ### `forward` ```python -forward(**kwargs) -> ToolResult +forward(**kwargs: Any) -> ToolResult ``` @@ -39,7 +39,7 @@ tool has args `a` and `b`, and an `transform_args` was provided that maps `x` to ### `forward_raw` ```python -forward_raw(**kwargs) -> ToolResult +forward_raw(**kwargs: Any) -> ToolResult ``` diff --git a/docs/python-sdk/fastmcp-utilities-inspect.mdx b/docs/python-sdk/fastmcp-utilities-inspect.mdx index b48e52a5c..80a66b749 100644 --- a/docs/python-sdk/fastmcp-utilities-inspect.mdx +++ b/docs/python-sdk/fastmcp-utilities-inspect.mdx @@ -26,7 +26,7 @@ Extract information from a FastMCP v2.x instance. - FastMCPInfo dataclass containing the extracted information -### `inspect_fastmcp_v1` +### `inspect_fastmcp_v1` ```python inspect_fastmcp_v1(mcp: FastMCP1x) -> FastMCPInfo @@ -42,7 +42,7 @@ Extract information from a FastMCP v1.x instance using a Client. - FastMCPInfo dataclass containing the extracted information -### `inspect_fastmcp` +### `inspect_fastmcp` ```python inspect_fastmcp(mcp: FastMCP[Any] | FastMCP1x) -> FastMCPInfo @@ -61,7 +61,7 @@ and uses the appropriate extraction method. - FastMCPInfo dataclass containing the extracted information -### `format_fastmcp_info` +### `format_fastmcp_info` ```python format_fastmcp_info(info: FastMCPInfo) -> bytes @@ -73,7 +73,7 @@ Format FastMCPInfo as FastMCP-specific JSON. This includes FastMCP-specific fields like tags, enabled, annotations, etc. -### `format_mcp_info` +### `format_mcp_info` ```python format_mcp_info(mcp: FastMCP[Any] | FastMCP1x) -> bytes @@ -86,7 +86,7 @@ Uses Client to get the standard MCP protocol format with camelCase fields. Includes version metadata at the top level. -### `format_info` +### `format_info` ```python format_info(mcp: FastMCP[Any] | FastMCP1x, format: InspectFormat | Literal['fastmcp', 'mcp'], info: FastMCPInfo | None = None) -> bytes @@ -136,7 +136,7 @@ Information about a resource template. Information extracted from a FastMCP instance. -### `InspectFormat` +### `InspectFormat` Output format for inspect command. diff --git a/docs/python-sdk/fastmcp-utilities-logging.mdx b/docs/python-sdk/fastmcp-utilities-logging.mdx index f139db07a..fe976dcad 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,7 +26,7 @@ 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 | None = None, **rich_kwargs: Any) -> None @@ -41,7 +41,7 @@ Configure logging for FastMCP. - `rich_kwargs`: the parameters to use for creating RichHandler -### `temporary_log_level` +### `temporary_log_level` ```python temporary_log_level(level: str | None, logger: logging.Logger | None = None, enable_rich_tracebacks: bool | None = None, **rich_kwargs: Any) diff --git a/docs/python-sdk/fastmcp-utilities-storage.mdx b/docs/python-sdk/fastmcp-utilities-storage.mdx deleted file mode 100644 index 0d0ecd322..000000000 --- a/docs/python-sdk/fastmcp-utilities-storage.mdx +++ /dev/null @@ -1,158 +0,0 @@ ---- -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 669755575..dbe05bde5 100644 --- a/docs/python-sdk/fastmcp-utilities-tests.mdx +++ b/docs/python-sdk/fastmcp-utilities-tests.mdx @@ -20,10 +20,10 @@ Temporarily override FastMCP setting values. - `**kwargs`: The settings to override, including nested settings. -### `run_server_in_process` +### `run_server_in_process` ```python -run_server_in_process(server_fn: Callable[..., None], *args, **kwargs) -> Generator[str, None, None] +run_server_in_process(server_fn: Callable[..., None], *args: Any, **kwargs: Any) -> Generator[str, None, None] ``` @@ -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] diff --git a/docs/python-sdk/fastmcp-utilities-types.mdx b/docs/python-sdk/fastmcp-utilities-types.mdx index 288191eb9..8b6cf44ca 100644 --- a/docs/python-sdk/fastmcp-utilities-types.mdx +++ b/docs/python-sdk/fastmcp-utilities-types.mdx @@ -133,7 +133,7 @@ to_audio_content(self, mime_type: str | None = None, annotations: Annotations | ### `File` -Helper class for returning audio from tools. +Helper class for returning file data from tools. **Methods:** diff --git a/docs/python-sdk/fastmcp-utilities-ui.mdx b/docs/python-sdk/fastmcp-utilities-ui.mdx new file mode 100644 index 000000000..77fd80184 --- /dev/null +++ b/docs/python-sdk/fastmcp-utilities-ui.mdx @@ -0,0 +1,131 @@ +--- +title: ui +sidebarTitle: ui +--- + +# `fastmcp.utilities.ui` + + + +Shared UI utilities for FastMCP HTML pages. + +This module provides reusable HTML/CSS components for OAuth callbacks, +consent pages, and other user-facing interfaces. + + +## Functions + +### `create_page` + +```python +create_page(content: str, title: str = 'FastMCP', additional_styles: str = '', csp_policy: str = "default-src 'none'; style-src 'unsafe-inline'; img-src https:; base-uri 'none'") -> str +``` + + +Create a complete HTML page with FastMCP styling. + +**Args:** +- `content`: HTML content to place inside the page +- `title`: Page title +- `additional_styles`: Extra CSS to include +- `csp_policy`: Content Security Policy header value + +**Returns:** +- Complete HTML page as string + + +### `create_logo` + +```python +create_logo() -> str +``` + + +Create FastMCP logo HTML. + + +### `create_status_message` + +```python +create_status_message(message: str, is_success: bool = True) -> str +``` + + +Create a status message with icon. + +**Args:** +- `message`: Status message text +- `is_success`: True for success (✓), False for error (✕) + +**Returns:** +- HTML for status message + + +### `create_info_box` + +```python +create_info_box(content: str, is_error: bool = False, centered: bool = False) -> str +``` + + +Create an info box. + +**Args:** +- `content`: HTML content for the info box +- `is_error`: True for error styling, False for normal +- `centered`: True to center the text, False for left-aligned + +**Returns:** +- HTML for info box + + +### `create_detail_box` + +```python +create_detail_box(rows: list[tuple[str, str]]) -> str +``` + + +Create a detail box with key-value pairs. + +**Args:** +- `rows`: List of (label, value) tuples + +**Returns:** +- HTML for detail box + + +### `create_button_group` + +```python +create_button_group(buttons: list[tuple[str, str, str]]) -> str +``` + + +Create a group of buttons. + +**Args:** +- `buttons`: List of (text, value, css_class) tuples + +**Returns:** +- HTML for button group + + +### `create_secure_html_response` + +```python +create_secure_html_response(html: str, status_code: int = 200) -> HTMLResponse +``` + + +Create an HTMLResponse with security headers. + +Adds X-Frame-Options: DENY to prevent clickjacking attacks per MCP security best practices. + +**Args:** +- `html`: HTML content to return +- `status_code`: HTTP status code + +**Returns:** +- HTMLResponse with security headers +