diff --git a/docs/docs.json b/docs/docs.json index be0b82944..f84e9b09b 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -257,7 +257,17 @@ "python-sdk/fastmcp-server-context", "python-sdk/fastmcp-server-dependencies", "python-sdk/fastmcp-server-http", - "python-sdk/fastmcp-server-middleware", + { + "group": "middleware", + "pages": [ + "python-sdk/fastmcp-server-middleware-__init__", + "python-sdk/fastmcp-server-middleware-error_handling", + "python-sdk/fastmcp-server-middleware-logging", + "python-sdk/fastmcp-server-middleware-middleware", + "python-sdk/fastmcp-server-middleware-rate_limiting", + "python-sdk/fastmcp-server-middleware-timing" + ] + }, "python-sdk/fastmcp-server-openapi", "python-sdk/fastmcp-server-proxy", "python-sdk/fastmcp-server-server" diff --git a/docs/python-sdk/fastmcp-cli-claude.mdx b/docs/python-sdk/fastmcp-cli-claude.mdx index 6ea44b33e..0f8b035fb 100644 --- a/docs/python-sdk/fastmcp-cli-claude.mdx +++ b/docs/python-sdk/fastmcp-cli-claude.mdx @@ -10,7 +10,7 @@ Claude app integration utilities. ## Functions -### `get_claude_config_path` +### `get_claude_config_path` ↗ ```python get_claude_config_path() -> Path | None @@ -20,7 +20,7 @@ get_claude_config_path() -> Path | None Get the Claude config directory based on platform. -### `update_claude_config` +### `update_claude_config` ↗ ```python update_claude_config(file_spec: str, server_name: str) -> bool diff --git a/docs/python-sdk/fastmcp-cli-cli.mdx b/docs/python-sdk/fastmcp-cli-cli.mdx index 60c24c556..f682abafe 100644 --- a/docs/python-sdk/fastmcp-cli-cli.mdx +++ b/docs/python-sdk/fastmcp-cli-cli.mdx @@ -10,13 +10,13 @@ FastMCP CLI tools. ## Functions -### `version` +### `version` ↗ ```python version(ctx: Context) ``` -### `dev` +### `dev` ↗ ```python dev(server_spec: str = typer.Argument(..., help='Python file to run, optionally with :object suffix'), with_editable: Annotated[Path | None, typer.Option('--with-editable', '-e', help='Directory containing pyproject.toml to install in editable mode', exists=True, file_okay=False, resolve_path=True)] = None, with_packages: Annotated[list[str], typer.Option('--with', help='Additional packages to install')] = [], inspector_version: Annotated[str | None, typer.Option('--inspector-version', help='Version of the MCP Inspector to use')] = None, ui_port: Annotated[int | None, typer.Option('--ui-port', help='Port for the MCP Inspector UI')] = None, server_port: Annotated[int | None, typer.Option('--server-port', help='Port for the MCP Inspector Proxy server')] = None) -> None @@ -26,10 +26,10 @@ dev(server_spec: str = typer.Argument(..., help='Python file to run, optionally Run a MCP server with the MCP Inspector. -### `run` +### `run` ↗ ```python -run(ctx: typer.Context, server_spec: str = typer.Argument(..., help='Python file, object specification (file:obj), or URL'), transport: Annotated[str | None, typer.Option('--transport', '-t', help='Transport protocol to use (stdio, streamable-http, or sse)')] = None, host: Annotated[str | None, typer.Option('--host', help='Host to bind to when using http transport (default: 127.0.0.1)')] = None, port: Annotated[int | None, typer.Option('--port', '-p', help='Port to bind to when using http transport (default: 8000)')] = None, log_level: Annotated[str | None, typer.Option('--log-level', '-l', help='Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)')] = None) -> None +run(ctx: typer.Context, server_spec: str = typer.Argument(..., help='Python file, object specification (file:obj), or URL'), transport: Annotated[str | None, typer.Option('--transport', '-t', help='Transport protocol to use (stdio, http, or sse)')] = None, host: Annotated[str | None, typer.Option('--host', help='Host to bind to when using http transport (default: 127.0.0.1)')] = None, port: Annotated[int | None, typer.Option('--port', '-p', help='Port to bind to when using http transport (default: 8000)')] = None, log_level: Annotated[str | None, typer.Option('--log-level', '-l', help='Log level (DEBUG, INFO, WARNING, ERROR, CRITICAL)')] = None) -> None ``` @@ -51,7 +51,7 @@ Server arguments can be passed after -- : fastmcp run server.py -- --config config.json --debug -### `install` +### `install` ↗ ```python install(server_spec: str = typer.Argument(..., help='Python file to run, optionally with :object suffix'), server_name: Annotated[str | None, typer.Option('--name', '-n', help="Custom name for the server (defaults to server's name attribute or file name)")] = None, with_editable: Annotated[Path | None, typer.Option('--with-editable', '-e', help='Directory containing pyproject.toml to install in editable mode', exists=True, file_okay=False, resolve_path=True)] = None, with_packages: Annotated[list[str], typer.Option('--with', help='Additional packages to install')] = [], env_vars: Annotated[list[str], typer.Option('--env-var', '-v', help='Environment variables in KEY=VALUE format')] = [], env_file: Annotated[Path | None, typer.Option('--env-file', '-f', help='Load environment variables from a .env file', exists=True, file_okay=True, dir_okay=False, resolve_path=True)] = None) -> None @@ -64,7 +64,7 @@ Environment variables are preserved once added and only updated if new values are explicitly provided. -### `inspect` +### `inspect` ↗ ```python inspect(server_spec: str = typer.Argument(..., help='Python file to inspect, optionally with :object suffix'), output: Annotated[Path, typer.Option('--output', '-o', help='Output file path for the JSON report (default: server-info.json)')] = Path('server-info.json')) -> None @@ -73,14 +73,15 @@ inspect(server_spec: str = typer.Argument(..., help='Python file to inspect, opt Inspect a FastMCP server and generate a JSON report. - This command analyzes a FastMCP server (v1.x or v2.x) and generates - a comprehensive JSON report containing information about the server's - name, instructions, version, tools, prompts, resources, templates, - and capabilities. +This command analyzes a FastMCP server (v1.x or v2.x) and generates +a comprehensive JSON report containing information about the server's +name, instructions, version, tools, prompts, resources, templates, +and capabilities. + +**Examples:** + +fastmcp inspect server.py +fastmcp inspect server.py -o report.json +fastmcp inspect server.py:mcp -o analysis.json +fastmcp inspect path/to/server.py:app -o /tmp/server-info.json - Examples: - fastmcp inspect server.py - fastmcp inspect server.py -o report.json - fastmcp inspect server.py:mcp -o analysis.json - fastmcp inspect path/to/server.py:app -o /tmp/server-info.json - diff --git a/docs/python-sdk/fastmcp-cli-run.mdx b/docs/python-sdk/fastmcp-cli-run.mdx index 7505c7fb4..6c2c90686 100644 --- a/docs/python-sdk/fastmcp-cli-run.mdx +++ b/docs/python-sdk/fastmcp-cli-run.mdx @@ -10,7 +10,7 @@ FastMCP run command implementation. ## Functions -### `is_url` +### `is_url` ↗ ```python is_url(path: str) -> bool @@ -20,7 +20,7 @@ is_url(path: str) -> bool Check if a string is a URL. -### `parse_file_path` +### `parse_file_path` ↗ ```python parse_file_path(server_spec: str) -> tuple[Path, str | None] @@ -36,7 +36,7 @@ Parse a file path that may include a server object specification. - Tuple of (file_path, server_object) -### `import_server` +### `import_server` ↗ ```python import_server(file: Path, server_object: str | None = None) -> Any @@ -53,7 +53,7 @@ Import a MCP server from a file. - The server object -### `create_client_server` +### `create_client_server` ↗ ```python create_client_server(url: str) -> Any @@ -69,7 +69,7 @@ Create a FastMCP server from a client URL. - A FastMCP server instance -### `import_server_with_args` +### `import_server_with_args` ↗ ```python import_server_with_args(file: Path, server_object: str | None = None, server_args: list[str] | None = None) -> Any @@ -87,7 +87,7 @@ Import a server with optional command line arguments. - The imported server object -### `run_command` +### `run_command` ↗ ```python run_command(server_spec: str, transport: str | None = None, host: str | None = None, port: int | None = None, log_level: str | None = None, server_args: list[str] | None = None) -> None diff --git a/docs/python-sdk/fastmcp-client-auth-bearer.mdx b/docs/python-sdk/fastmcp-client-auth-bearer.mdx index ab0c15240..d8a1c2df5 100644 --- a/docs/python-sdk/fastmcp-client-auth-bearer.mdx +++ b/docs/python-sdk/fastmcp-client-auth-bearer.mdx @@ -7,11 +7,11 @@ sidebarTitle: bearer ## Classes -### `BearerAuth` +### `BearerAuth` ↗ **Methods:** -#### `auth_flow` +#### `auth_flow` ↗ ```python auth_flow(self, request) diff --git a/docs/python-sdk/fastmcp-client-auth-oauth.mdx b/docs/python-sdk/fastmcp-client-auth-oauth.mdx index f10afba36..c1973ff59 100644 --- a/docs/python-sdk/fastmcp-client-auth-oauth.mdx +++ b/docs/python-sdk/fastmcp-client-auth-oauth.mdx @@ -7,13 +7,13 @@ sidebarTitle: oauth ## Functions -### `default_cache_dir` +### `default_cache_dir` ↗ ```python default_cache_dir() -> Path ``` -### `OAuth` +### `OAuth` ↗ ```python OAuth(mcp_url: str, scopes: str | list[str] | None = None, client_name: str = 'FastMCP Client', token_storage_cache_dir: Path | None = None, additional_client_metadata: dict[str, Any] | None = None) -> _MCPOAuthClientProvider @@ -38,7 +38,7 @@ httpx.AsyncClient (or appropriate FastMCP client/transport instance) ## Classes -### `ServerOAuthMetadata` +### `ServerOAuthMetadata` ↗ More flexible OAuth metadata model that accepts broader ranges of values @@ -48,13 +48,13 @@ This handles real-world OAuth servers like PayPal that may support additional methods not in the MCP specification. -### `OAuthClientProvider` +### `OAuthClientProvider` ↗ OAuth client provider with more flexible OAuth metadata discovery. -### `FileTokenStorage` +### `FileTokenStorage` ↗ File-based token storage implementation for OAuth credentials and tokens. @@ -65,7 +65,7 @@ Each instance is tied to a specific server URL for proper token isolation. **Methods:** -#### `get_base_url` +#### `get_base_url` ↗ ```python get_base_url(url: str) -> str @@ -74,7 +74,7 @@ get_base_url(url: str) -> str Extract the base URL (scheme + host) from a URL. -#### `get_cache_key` +#### `get_cache_key` ↗ ```python get_cache_key(self) -> str @@ -83,7 +83,7 @@ get_cache_key(self) -> str Generate a safe filesystem key from the server's base URL. -#### `clear` +#### `clear` ↗ ```python clear(self) -> None @@ -92,7 +92,7 @@ clear(self) -> None Clear all cached data for this server. -#### `clear_all` +#### `clear_all` ↗ ```python clear_all(cls, cache_dir: Path | None = None) -> None diff --git a/docs/python-sdk/fastmcp-client-client.mdx b/docs/python-sdk/fastmcp-client-client.mdx index 4c3f252bf..09c17155c 100644 --- a/docs/python-sdk/fastmcp-client-client.mdx +++ b/docs/python-sdk/fastmcp-client-client.mdx @@ -7,48 +7,48 @@ sidebarTitle: client ## Classes -### `Client` +### `Client` ↗ +MCP client that delegates connection management to a Transport instance. - MCP client that delegates connection management to a Transport instance. +The Client class is responsible for MCP protocol logic, while the Transport +handles connection establishment and management. Client provides methods for +working with resources, prompts, tools and other MCP capabilities. - The Client class is responsible for MCP protocol logic, while the Transport - handles connection establishment and management. Client provides methods for - working with resources, prompts, tools and other MCP capabilities. +**Args:** +- `transport`: Connection source specification, which can be\: +- ClientTransport\: Direct transport instance +- FastMCP\: In-process FastMCP server +- AnyUrl | str\: URL to connect to +- Path\: File path for local socket +- MCPConfig\: MCP server configuration +- dict\: Transport configuration +- `roots`: Optional RootsList or RootsHandler for filesystem access +- `sampling_handler`: Optional handler for sampling requests +- `log_handler`: Optional handler for log messages +- `message_handler`: Optional handler for protocol messages +- `progress_handler`: Optional handler for progress notifications +- `timeout`: Optional timeout for requests (seconds or timedelta) +- `init_timeout`: Optional timeout for initial connection (seconds or timedelta). +Set to 0 to disable. If None, uses the value in the FastMCP global settings. - Args: - transport: Connection source specification, which can be: - - ClientTransport: Direct transport instance - - FastMCP: In-process FastMCP server - - AnyUrl | str: URL to connect to - - Path: File path for local socket - - MCPConfig: MCP server configuration - - dict: Transport configuration - roots: Optional RootsList or RootsHandler for filesystem access - sampling_handler: Optional handler for sampling requests - log_handler: Optional handler for log messages - message_handler: Optional handler for protocol messages - progress_handler: Optional handler for progress notifications - timeout: Optional timeout for requests (seconds or timedelta) - init_timeout: Optional timeout for initial connection (seconds or timedelta). - Set to 0 to disable. If None, uses the value in the FastMCP global settings. +**Examples:** - Examples: - ```python # Connect to FastMCP server client = - Client("http://localhost:8080") +```python # Connect to FastMCP server client = +Client("http://localhost:8080") - async with client: - # List available resources resources = await client.list_resources() +async with client: + # List available resources resources = await client.list_resources() + + # Call a tool result = await client.call_tool("my_tool", {"param": + "value"}) +``` - # Call a tool result = await client.call_tool("my_tool", {"param": - "value"}) - ``` - **Methods:** -#### `session` +#### `session` ↗ ```python session(self) -> ClientSession @@ -57,7 +57,7 @@ session(self) -> ClientSession Get the current active session. Raises RuntimeError if not connected. -#### `initialize_result` +#### `initialize_result` ↗ ```python initialize_result(self) -> mcp.types.InitializeResult @@ -66,7 +66,7 @@ initialize_result(self) -> mcp.types.InitializeResult Get the result of the initialization request. -#### `set_roots` +#### `set_roots` ↗ ```python set_roots(self, roots: RootsList | RootsHandler) -> None @@ -75,7 +75,7 @@ set_roots(self, roots: RootsList | RootsHandler) -> None Set the roots for the client. This does not automatically call `send_roots_list_changed`. -#### `set_sampling_callback` +#### `set_sampling_callback` ↗ ```python set_sampling_callback(self, sampling_callback: SamplingHandler) -> None @@ -84,7 +84,7 @@ set_sampling_callback(self, sampling_callback: SamplingHandler) -> None Set the sampling callback for the client. -#### `is_connected` +#### `is_connected` ↗ ```python is_connected(self) -> bool diff --git a/docs/python-sdk/fastmcp-client-logging.mdx b/docs/python-sdk/fastmcp-client-logging.mdx index 84d201db7..07bf911dd 100644 --- a/docs/python-sdk/fastmcp-client-logging.mdx +++ b/docs/python-sdk/fastmcp-client-logging.mdx @@ -7,7 +7,7 @@ sidebarTitle: logging ## Functions -### `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 6eab9de3a..8ae599c7d 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-roots.mdx b/docs/python-sdk/fastmcp-client-roots.mdx index 820e1d0a7..b61c561a9 100644 --- a/docs/python-sdk/fastmcp-client-roots.mdx +++ b/docs/python-sdk/fastmcp-client-roots.mdx @@ -7,13 +7,13 @@ sidebarTitle: roots ## Functions -### `convert_roots_list` +### `convert_roots_list` ↗ ```python convert_roots_list(roots: RootsList) -> list[mcp.types.Root] ``` -### `create_roots_callback` +### `create_roots_callback` ↗ ```python create_roots_callback(handler: RootsList | RootsHandler) -> ListRootsFnT diff --git a/docs/python-sdk/fastmcp-client-sampling.mdx b/docs/python-sdk/fastmcp-client-sampling.mdx index be78badeb..dc2912fb9 100644 --- a/docs/python-sdk/fastmcp-client-sampling.mdx +++ b/docs/python-sdk/fastmcp-client-sampling.mdx @@ -7,7 +7,7 @@ sidebarTitle: sampling ## Functions -### `create_sampling_callback` +### `create_sampling_callback` ↗ ```python create_sampling_callback(sampling_handler: SamplingHandler) -> SamplingFnT diff --git a/docs/python-sdk/fastmcp-client-transports.mdx b/docs/python-sdk/fastmcp-client-transports.mdx index 08910b09c..f83a119fe 100644 --- a/docs/python-sdk/fastmcp-client-transports.mdx +++ b/docs/python-sdk/fastmcp-client-transports.mdx @@ -7,63 +7,63 @@ sidebarTitle: transports ## Functions -### `infer_transport` +### `infer_transport` ↗ ```python infer_transport(transport: ClientTransport | FastMCP | FastMCP1Server | AnyUrl | Path | MCPConfig | dict[str, Any] | str) -> ClientTransport ``` +Infer the appropriate transport type from the given transport argument. - Infer the appropriate transport type from the given transport argument. +This function attempts to infer the correct transport type from the provided +argument, handling various input types and converting them to the appropriate +ClientTransport subclass. - This function attempts to infer the correct transport type from the provided - argument, handling various input types and converting them to the appropriate - ClientTransport subclass. +The function supports these input types: +- ClientTransport: Used directly without modification +- FastMCP or FastMCP1Server: Creates an in-memory FastMCPTransport +- Path or str (file path): Creates PythonStdioTransport (.py) or NodeStdioTransport (.js) +- AnyUrl or str (URL): Creates StreamableHttpTransport (default) or SSETransport (for /sse endpoints) +- MCPConfig or dict: Creates MCPConfigTransport, potentially connecting to multiple servers - The function supports these input types: - - ClientTransport: Used directly without modification - - FastMCP or FastMCP1Server: Creates an in-memory FastMCPTransport - - Path or str (file path): Creates PythonStdioTransport (.py) or NodeStdioTransport (.js) - - AnyUrl or str (URL): Creates StreamableHttpTransport (default) or SSETransport (for /sse endpoints) - - MCPConfig or dict: Creates MCPConfigTransport, potentially connecting to multiple servers +For HTTP URLs, they are assumed to be Streamable HTTP URLs unless they end in `/sse`. - For HTTP URLs, they are assumed to be Streamable HTTP URLs unless they end in `/sse`. +For MCPConfig with multiple servers, a composite client is created where each server +is mounted with its name as prefix. This allows accessing tools and resources from multiple +servers through a single unified client interface, using naming patterns like +`servername_toolname` for tools and `protocol://servername/path` for resources. +If the MCPConfig contains only one server, a direct connection is established without prefixing. - For MCPConfig with multiple servers, a composite client is created where each server - is mounted with its name as prefix. This allows accessing tools and resources from multiple - servers through a single unified client interface, using naming patterns like - `servername_toolname` for tools and `protocol://servername/path` for resources. - If the MCPConfig contains only one server, a direct connection is established without prefixing. +**Examples:** - Examples: - ```python - # Connect to a local Python script - transport = infer_transport("my_script.py") +```python +# Connect to a local Python script +transport = infer_transport("my_script.py") - # Connect to a remote server via HTTP - transport = infer_transport("http://example.com/mcp") +# Connect to a remote server via HTTP +transport = infer_transport("http://example.com/mcp") + +# Connect to multiple servers using MCPConfig +config = { + "mcpServers": { + "weather": {"url": "http://weather.example.com/mcp"}, + "calendar": {"url": "http://calendar.example.com/mcp"} + } +} +transport = infer_transport(config) +``` - # Connect to multiple servers using MCPConfig - config = { - "mcpServers": { - "weather": {"url": "http://weather.example.com/mcp"}, - "calendar": {"url": "http://calendar.example.com/mcp"} - } - } - transport = infer_transport(config) - ``` - ## Classes -### `SessionKwargs` +### `SessionKwargs` ↗ Keyword arguments for the MCP ClientSession constructor. -### `ClientTransport` +### `ClientTransport` ↗ Abstract base class for different MCP client transport mechanisms. @@ -72,25 +72,25 @@ A Transport is responsible for establishing and managing connections to an MCP server, and providing a ClientSession within an async context. -### `WSTransport` +### `WSTransport` ↗ Transport implementation that connects to an MCP server via WebSockets. -### `SSETransport` +### `SSETransport` ↗ Transport implementation that connects to an MCP server via Server-Sent Events. -### `StreamableHttpTransport` +### `StreamableHttpTransport` ↗ Transport implementation that connects to an MCP server via Streamable HTTP Requests. -### `StdioTransport` +### `StdioTransport` ↗ Base transport for connecting to an MCP server via subprocess with stdio. @@ -99,37 +99,37 @@ This is a base class that can be subclassed for specific command-based transports like Python, Node, Uvx, etc. -### `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. -### `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. @@ -140,52 +140,53 @@ servers from the low-level MCP SDK. This is particularly useful for unit tests or scenarios where client and server run in the same runtime. -### `MCPConfigTransport` +### `MCPConfigTransport` ↗ Transport for connecting to one or more MCP servers defined in an MCPConfig. - This transport provides a unified interface to multiple MCP servers defined in an MCPConfig - object or dictionary matching the MCPConfig schema. It supports two key scenarios: +This transport provides a unified interface to multiple MCP servers defined in an MCPConfig +object or dictionary matching the MCPConfig schema. It supports two key scenarios: - 1. If the MCPConfig contains exactly one server, it creates a direct transport to that server. - 2. If the MCPConfig contains multiple servers, it creates a composite client by mounting - all servers on a single FastMCP instance, with each server's name used as its mounting prefix. +1. If the MCPConfig contains exactly one server, it creates a direct transport to that server. +2. If the MCPConfig contains multiple servers, it creates a composite client by mounting + all servers on a single FastMCP instance, with each server's name used as its mounting prefix. - In the multi-server case, tools are accessible with the prefix pattern `{server_name}_{tool_name}` - and resources with the pattern `protocol://{server_name}/path/to/resource`. +In the multi-server case, tools are accessible with the prefix pattern `{server_name}_{tool_name}` +and resources with the pattern `protocol://{server_name}/path/to/resource`. - This is particularly useful for creating clients that need to interact with multiple specialized - MCP servers through a single interface, simplifying client code. +This is particularly useful for creating clients that need to interact with multiple specialized +MCP servers through a single interface, simplifying client code. - Examples: - ```python - from fastmcp import Client - from fastmcp.utilities.mcp_config import MCPConfig +**Examples:** - # Create a config with multiple servers - config = { - "mcpServers": { - "weather": { - "url": "https://weather-api.example.com/mcp", - "transport": "http" - }, - "calendar": { - "url": "https://calendar-api.example.com/mcp", - "transport": "http" - } - } +```python +from fastmcp import Client +from fastmcp.utilities.mcp_config import MCPConfig + +# Create a config with multiple servers +config = { + "mcpServers": { + "weather": { + "url": "https://weather-api.example.com/mcp", + "transport": "http" + }, + "calendar": { + "url": "https://calendar-api.example.com/mcp", + "transport": "http" } + } +} - # Create a client with the config - client = Client(config) +# Create a client with the config +client = Client(config) - async with client: - # Access tools with prefixes - weather = await client.call_tool("weather_get_forecast", {"city": "London"}) - events = await client.call_tool("calendar_list_events", {"date": "2023-06-01"}) +async with client: + # Access tools with prefixes + weather = await client.call_tool("weather_get_forecast", {"city": "London"}) + events = await client.call_tool("calendar_list_events", {"date": "2023-06-01"}) + + # Access resources with prefixed URIs + icons = await client.read_resource("weather://weather/icons/sunny") +``` - # Access resources with prefixed URIs - icons = await client.read_resource("weather://weather/icons/sunny") - ``` - diff --git a/docs/python-sdk/fastmcp-exceptions.mdx b/docs/python-sdk/fastmcp-exceptions.mdx index 9726d1cde..b7930d0ac 100644 --- a/docs/python-sdk/fastmcp-exceptions.mdx +++ b/docs/python-sdk/fastmcp-exceptions.mdx @@ -10,55 +10,55 @@ Custom exceptions for FastMCP. ## Classes -### `FastMCPError` +### `FastMCPError` ↗ Base error for FastMCP. -### `ValidationError` +### `ValidationError` ↗ Error in validating parameters or return values. -### `ResourceError` +### `ResourceError` ↗ Error in resource operations. -### `ToolError` +### `ToolError` ↗ Error in tool operations. -### `PromptError` +### `PromptError` ↗ Error in prompt operations. -### `InvalidSignature` +### `InvalidSignature` ↗ Invalid signature for use with FastMCP. -### `ClientError` +### `ClientError` ↗ Error in client operations. -### `NotFoundError` +### `NotFoundError` ↗ Object not found. -### `DisabledError` +### `DisabledError` ↗ Object is disabled. diff --git a/docs/python-sdk/fastmcp-prompts-prompt.mdx b/docs/python-sdk/fastmcp-prompts-prompt.mdx index 60028f316..90e83def3 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 | MCPContent, 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,7 +36,7 @@ A prompt template that can be rendered with parameters. **Methods:** -#### `to_mcp_prompt` +#### `to_mcp_prompt` ↗ ```python to_mcp_prompt(self, **overrides: Any) -> MCPPrompt @@ -45,7 +45,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, description: str | None = None, tags: set[str] | None = None, enabled: bool | None = None) -> FunctionPrompt @@ -60,7 +60,7 @@ The function can return: - A sequence of any of the above -### `FunctionPrompt` +### `FunctionPrompt` ↗ A prompt that is a function. @@ -68,7 +68,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, description: str | None = None, tags: set[str] | None = None, enabled: bool | None = None) -> FunctionPrompt diff --git a/docs/python-sdk/fastmcp-prompts-prompt_manager.mdx b/docs/python-sdk/fastmcp-prompts-prompt_manager.mdx index 041337c28..e4f9dc68e 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,7 +15,7 @@ Manages FastMCP prompts. **Methods:** -#### `mount` +#### `mount` ↗ ```python mount(self, server: MountedServer) -> None @@ -24,7 +24,7 @@ mount(self, server: MountedServer) -> None Adds a mounted server as a source for prompts. -#### `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 @@ -33,7 +33,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 diff --git a/docs/python-sdk/fastmcp-resources-resource.mdx b/docs/python-sdk/fastmcp-resources-resource.mdx index dcfc51f00..e649ff1ec 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,13 +18,13 @@ Base class for all resources. **Methods:** -#### `from_function` +#### `from_function` ↗ ```python from_function(fn: Callable[[], Any], uri: str | AnyUrl, name: str | None = None, description: str | None = None, mime_type: str | None = None, tags: set[str] | None = None, enabled: bool | None = None) -> FunctionResource ``` -#### `set_default_mime_type` +#### `set_default_mime_type` ↗ ```python set_default_mime_type(cls, mime_type: str | None) -> str @@ -33,7 +33,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 @@ -42,7 +42,7 @@ set_default_name(self) -> Self Set default name from URI if not provided. -#### `to_mcp_resource` +#### `to_mcp_resource` ↗ ```python to_mcp_resource(self, **overrides: Any) -> MCPResource @@ -51,7 +51,7 @@ to_mcp_resource(self, **overrides: Any) -> MCPResource Convert the resource to an MCPResource. -#### `key` +#### `key` ↗ ```python key(self) -> str @@ -63,7 +63,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. @@ -80,7 +80,7 @@ The function can return: **Methods:** -#### `from_function` +#### `from_function` ↗ ```python from_function(cls, fn: Callable[[], Any], uri: str | AnyUrl, name: str | None = None, description: str | None = None, mime_type: str | None = None, tags: set[str] | None = None, enabled: bool | None = None) -> FunctionResource diff --git a/docs/python-sdk/fastmcp-resources-resource_manager.mdx b/docs/python-sdk/fastmcp-resources-resource_manager.mdx index 9adb43e83..da08b45a7 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,7 +18,7 @@ Manages FastMCP resources. **Methods:** -#### `mount` +#### `mount` ↗ ```python mount(self, server: MountedServer) -> None @@ -27,7 +27,7 @@ mount(self, server: MountedServer) -> None Adds a mounted server as a source for resources and templates. -#### `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 @@ -48,7 +48,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 @@ -69,7 +69,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 @@ -83,7 +83,7 @@ will be used as the storage key. To overwrite it, call Resource.with_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 @@ -92,7 +92,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 diff --git a/docs/python-sdk/fastmcp-resources-template.mdx b/docs/python-sdk/fastmcp-resources-template.mdx index c1810f097..1f21f3d3a 100644 --- a/docs/python-sdk/fastmcp-resources-template.mdx +++ b/docs/python-sdk/fastmcp-resources-template.mdx @@ -10,13 +10,13 @@ Resource template functionality. ## Functions -### `build_regex` +### `build_regex` ↗ ```python build_regex(template: str) -> re.Pattern ``` -### `match_uri_template` +### `match_uri_template` ↗ ```python match_uri_template(uri: str, uri_template: str) -> dict[str, str] | None @@ -24,7 +24,7 @@ match_uri_template(uri: str, uri_template: str) -> dict[str, str] | None ## Classes -### `ResourceTemplate` +### `ResourceTemplate` ↗ A template for dynamically creating resources. @@ -32,13 +32,13 @@ A template for dynamically creating resources. **Methods:** -#### `from_function` +#### `from_function` ↗ ```python from_function(fn: Callable[..., Any], uri_template: str, name: str | None = None, description: str | None = None, mime_type: str | None = None, tags: set[str] | None = None, enabled: bool | None = None) -> FunctionResourceTemplate ``` -#### `set_default_mime_type` +#### `set_default_mime_type` ↗ ```python set_default_mime_type(cls, mime_type: str | None) -> str @@ -47,7 +47,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 @@ -56,7 +56,7 @@ matches(self, uri: str) -> dict[str, Any] | None Check if URI matches template and extract parameters. -#### `to_mcp_template` +#### `to_mcp_template` ↗ ```python to_mcp_template(self, **overrides: Any) -> MCPResourceTemplate @@ -65,7 +65,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 @@ -74,7 +74,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 @@ -86,7 +86,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. @@ -94,7 +94,7 @@ A template for dynamically creating resources. **Methods:** -#### `from_function` +#### `from_function` ↗ ```python from_function(cls, fn: Callable[..., Any], uri_template: str, name: str | None = None, description: str | None = None, mime_type: str | None = None, tags: set[str] | None = None, enabled: bool | None = None) -> FunctionResourceTemplate diff --git a/docs/python-sdk/fastmcp-resources-types.mdx b/docs/python-sdk/fastmcp-resources-types.mdx index 675b44cc1..67caa4744 100644 --- a/docs/python-sdk/fastmcp-resources-types.mdx +++ b/docs/python-sdk/fastmcp-resources-types.mdx @@ -10,19 +10,19 @@ Concrete resource implementations. ## Classes -### `TextResource` +### `TextResource` ↗ A resource that reads from a string. -### `BinaryResource` +### `BinaryResource` ↗ A resource that reads from bytes. -### `FileResource` +### `FileResource` ↗ A resource that reads from a file. @@ -32,7 +32,7 @@ Set is_binary=True to read file as binary data instead of text. **Methods:** -#### `validate_absolute_path` +#### `validate_absolute_path` ↗ ```python validate_absolute_path(cls, path: Path) -> Path @@ -41,7 +41,7 @@ validate_absolute_path(cls, path: Path) -> Path Ensure path is absolute. -#### `set_binary_from_mime_type` +#### `set_binary_from_mime_type` ↗ ```python set_binary_from_mime_type(cls, is_binary: bool, info: ValidationInfo) -> bool @@ -50,13 +50,13 @@ set_binary_from_mime_type(cls, is_binary: bool, info: ValidationInfo) -> bool Set is_binary based on mime_type if not explicitly set. -### `HttpResource` +### `HttpResource` ↗ A resource that reads from an HTTP endpoint. -### `DirectoryResource` +### `DirectoryResource` ↗ A resource that lists files in a directory. @@ -64,7 +64,7 @@ A resource that lists files in a directory. **Methods:** -#### `validate_absolute_path` +#### `validate_absolute_path` ↗ ```python validate_absolute_path(cls, path: Path) -> Path @@ -73,7 +73,7 @@ validate_absolute_path(cls, path: Path) -> Path Ensure path is absolute. -#### `list_files` +#### `list_files` ↗ ```python list_files(self) -> list[Path] diff --git a/docs/python-sdk/fastmcp-server-auth-auth.mdx b/docs/python-sdk/fastmcp-server-auth-auth.mdx index 8a20aa716..7401e82fb 100644 --- a/docs/python-sdk/fastmcp-server-auth-auth.mdx +++ b/docs/python-sdk/fastmcp-server-auth-auth.mdx @@ -7,4 +7,4 @@ sidebarTitle: auth ## Classes -### `OAuthProvider` +### `OAuthProvider` ↗ diff --git a/docs/python-sdk/fastmcp-server-auth-providers-bearer.mdx b/docs/python-sdk/fastmcp-server-auth-providers-bearer.mdx index 5e85ee1e9..666b90405 100644 --- a/docs/python-sdk/fastmcp-server-auth-providers-bearer.mdx +++ b/docs/python-sdk/fastmcp-server-auth-providers-bearer.mdx @@ -7,23 +7,23 @@ sidebarTitle: bearer ## Classes -### `JWKData` +### `JWKData` ↗ JSON Web Key data structure. -### `JWKSData` +### `JWKSData` ↗ JSON Web Key Set data structure. -### `RSAKeyPair` +### `RSAKeyPair` ↗ **Methods:** -#### `generate` +#### `generate` ↗ ```python generate(cls) -> 'RSAKeyPair' @@ -35,7 +35,7 @@ Generate an RSA key pair for testing. - (private_key_pem, public_key_pem) -#### `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 @@ -57,7 +57,7 @@ Generate a test JWT token for testing purposes. - Signed JWT token string -### `BearerAuthProvider` +### `BearerAuthProvider` ↗ Simple JWT Bearer Token validator for hosted MCP servers. diff --git a/docs/python-sdk/fastmcp-server-auth-providers-bearer_env.mdx b/docs/python-sdk/fastmcp-server-auth-providers-bearer_env.mdx index f64c65c84..9acb518de 100644 --- a/docs/python-sdk/fastmcp-server-auth-providers-bearer_env.mdx +++ b/docs/python-sdk/fastmcp-server-auth-providers-bearer_env.mdx @@ -7,13 +7,13 @@ sidebarTitle: bearer_env ## Classes -### `EnvBearerAuthProviderSettings` +### `EnvBearerAuthProviderSettings` ↗ Settings for the BearerAuthProvider. -### `EnvBearerAuthProvider` +### `EnvBearerAuthProvider` ↗ A BearerAuthProvider that loads settings from environment variables. Any diff --git a/docs/python-sdk/fastmcp-server-auth-providers-in_memory.mdx b/docs/python-sdk/fastmcp-server-auth-providers-in_memory.mdx index ef34ce2fb..2f8b21b61 100644 --- a/docs/python-sdk/fastmcp-server-auth-providers-in_memory.mdx +++ b/docs/python-sdk/fastmcp-server-auth-providers-in_memory.mdx @@ -7,7 +7,7 @@ sidebarTitle: in_memory ## Classes -### `InMemoryOAuthProvider` +### `InMemoryOAuthProvider` ↗ An in-memory OAuth provider for testing purposes. diff --git a/docs/python-sdk/fastmcp-server-context.mdx b/docs/python-sdk/fastmcp-server-context.mdx index ea1d92643..005b4f7c7 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 -### `Context` +### `Context` ↗ Context object providing access to MCP capabilities. @@ -53,7 +53,7 @@ The context is optional - tools that don't need it can omit the parameter. **Methods:** -#### `request_context` +#### `request_context` ↗ ```python request_context(self) -> RequestContext @@ -64,7 +64,7 @@ Access to the underlying request context. If called outside of a request context, this will raise a ValueError. -#### `client_id` +#### `client_id` ↗ ```python client_id(self) -> str | None @@ -73,7 +73,7 @@ client_id(self) -> str | None Get the client ID if available. -#### `request_id` +#### `request_id` ↗ ```python request_id(self) -> str @@ -82,7 +82,7 @@ request_id(self) -> str Get the unique ID for this request. -#### `session_id` +#### `session_id` ↗ ```python session_id(self) -> str | None @@ -99,7 +99,7 @@ the same client session. - for stdio and in-memory transports which don't use session IDs. -#### `session` +#### `session` ↗ ```python session(self) @@ -108,7 +108,7 @@ session(self) Access to the underlying session for advanced usage. -#### `get_http_request` +#### `get_http_request` ↗ ```python get_http_request(self) -> Request diff --git a/docs/python-sdk/fastmcp-server-dependencies.mdx b/docs/python-sdk/fastmcp-server-dependencies.mdx index 0d6c37074..c082a1b35 100644 --- a/docs/python-sdk/fastmcp-server-dependencies.mdx +++ b/docs/python-sdk/fastmcp-server-dependencies.mdx @@ -7,19 +7,19 @@ sidebarTitle: dependencies ## Functions -### `get_context` +### `get_context` ↗ ```python get_context() -> Context ``` -### `get_http_request` +### `get_http_request` ↗ ```python get_http_request() -> Request ``` -### `get_http_headers` +### `get_http_headers` ↗ ```python get_http_headers(include_all: bool = False) -> dict[str, str] diff --git a/docs/python-sdk/fastmcp-server-http.mdx b/docs/python-sdk/fastmcp-server-http.mdx index 63f2768cb..86624d867 100644 --- a/docs/python-sdk/fastmcp-server-http.mdx +++ b/docs/python-sdk/fastmcp-server-http.mdx @@ -7,13 +7,13 @@ sidebarTitle: http ## Functions -### `set_http_request` +### `set_http_request` ↗ ```python set_http_request(request: Request) -> Generator[Request, None, None] ``` -### `setup_auth_middleware_and_routes` +### `setup_auth_middleware_and_routes` ↗ ```python setup_auth_middleware_and_routes(auth: OAuthProvider) -> tuple[list[Middleware], list[BaseRoute], list[str]] @@ -29,7 +29,7 @@ Set up authentication middleware and routes if auth is enabled. - Tuple of (middleware, auth_routes, required_scopes) -### `create_base_app` +### `create_base_app` ↗ ```python create_base_app(routes: list[BaseRoute], middleware: list[Middleware], debug: bool = False, lifespan: Callable | None = None) -> StarletteWithLifespan @@ -48,7 +48,7 @@ Create a base Starlette app with common middleware and routes. - A Starlette application -### `create_sse_app` +### `create_sse_app` ↗ ```python create_sse_app(server: FastMCP[LifespanResultT], message_path: str, sse_path: str, auth: OAuthProvider | None = None, debug: bool = False, routes: list[BaseRoute] | None = None, middleware: list[Middleware] | None = None) -> StarletteWithLifespan @@ -70,7 +70,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: OAuthProvider | None = None, json_response: bool = False, stateless_http: bool = False, debug: bool = False, routes: list[BaseRoute] | None = None, middleware: list[Middleware] | None = None) -> StarletteWithLifespan @@ -96,17 +96,17 @@ Return an instance of the StreamableHTTP server app. ## Classes -### `StarletteWithLifespan` +### `StarletteWithLifespan` ↗ **Methods:** -#### `lifespan` +#### `lifespan` ↗ ```python lifespan(self) -> Lifespan ``` -### `RequestContextMiddleware` +### `RequestContextMiddleware` ↗ Middleware that stores each request in a ContextVar diff --git a/docs/python-sdk/fastmcp-server-middleware-__init__.mdx b/docs/python-sdk/fastmcp-server-middleware-__init__.mdx new file mode 100644 index 000000000..8583b1df9 --- /dev/null +++ b/docs/python-sdk/fastmcp-server-middleware-__init__.mdx @@ -0,0 +1,8 @@ +--- +title: __init__ +sidebarTitle: __init__ +--- + +# `fastmcp.server.middleware` + +*This module is empty or contains only private/internal implementations.* diff --git a/docs/python-sdk/fastmcp-server-middleware-error_handling.mdx b/docs/python-sdk/fastmcp-server-middleware-error_handling.mdx new file mode 100644 index 000000000..79836b772 --- /dev/null +++ b/docs/python-sdk/fastmcp-server-middleware-error_handling.mdx @@ -0,0 +1,40 @@ +--- +title: error_handling +sidebarTitle: error_handling +--- + +# `fastmcp.server.middleware.error_handling` + + +Error handling middleware for consistent error responses and tracking. + +## Classes + +### `ErrorHandlingMiddleware` ↗ + + +Middleware that provides consistent error handling and logging. + +Catches exceptions, logs them appropriately, and converts them to +proper MCP error responses. Also tracks error patterns for monitoring. + + +**Methods:** + +#### `get_error_stats` ↗ + +```python +get_error_stats(self) -> dict[str, int] +``` + +Get error statistics for monitoring. + + +### `RetryMiddleware` ↗ + + +Middleware that implements automatic retry logic for failed requests. + +Retries requests that fail with transient errors, using exponential +backoff to avoid overwhelming the server or external dependencies. + diff --git a/docs/python-sdk/fastmcp-server-middleware-logging.mdx b/docs/python-sdk/fastmcp-server-middleware-logging.mdx new file mode 100644 index 000000000..74d5599b1 --- /dev/null +++ b/docs/python-sdk/fastmcp-server-middleware-logging.mdx @@ -0,0 +1,29 @@ +--- +title: logging +sidebarTitle: logging +--- + +# `fastmcp.server.middleware.logging` + + +Comprehensive logging middleware for FastMCP servers. + +## Classes + +### `LoggingMiddleware` ↗ + + +Middleware that provides comprehensive request and response logging. + +Logs all MCP messages with configurable detail levels. Useful for debugging, +monitoring, and understanding server usage patterns. + + +### `StructuredLoggingMiddleware` ↗ + + +Middleware that provides structured JSON logging for better log analysis. + +Outputs structured logs that are easier to parse and analyze with log +aggregation tools like ELK stack, Splunk, or cloud logging services. + diff --git a/docs/python-sdk/fastmcp-server-middleware-middleware.mdx b/docs/python-sdk/fastmcp-server-middleware-middleware.mdx new file mode 100644 index 000000000..60ffe3c74 --- /dev/null +++ b/docs/python-sdk/fastmcp-server-middleware-middleware.mdx @@ -0,0 +1,56 @@ +--- +title: middleware +sidebarTitle: middleware +--- + +# `fastmcp.server.middleware.middleware` + +## Functions + +### `make_middleware_wrapper` ↗ + +```python +make_middleware_wrapper(middleware: Middleware, call_next: CallNext[T, R]) -> CallNext[T, R] +``` + + +Create a wrapper that applies a single middleware to a context. The +closure bakes in the middleware and call_next function, so it can be +passed to other functions that expect a call_next function. + + +## Classes + +### `CallNext` ↗ + +### `CallToolResult` ↗ + +### `ListToolsResult` ↗ + +### `ListResourcesResult` ↗ + +### `ListResourceTemplatesResult` ↗ + +### `ListPromptsResult` ↗ + +### `ServerResultProtocol` ↗ + +### `MiddlewareContext` ↗ + + +Unified context for all middleware operations. + + +**Methods:** + +#### `copy` ↗ + +```python +copy(self, **kwargs: Any) -> MiddlewareContext[T] +``` + +### `Middleware` ↗ + + +Base class for FastMCP middleware with dispatching hooks. + diff --git a/docs/python-sdk/fastmcp-server-middleware-rate_limiting.mdx b/docs/python-sdk/fastmcp-server-middleware-rate_limiting.mdx new file mode 100644 index 000000000..43a90a95b --- /dev/null +++ b/docs/python-sdk/fastmcp-server-middleware-rate_limiting.mdx @@ -0,0 +1,47 @@ +--- +title: rate_limiting +sidebarTitle: rate_limiting +--- + +# `fastmcp.server.middleware.rate_limiting` + + +Rate limiting middleware for protecting FastMCP servers from abuse. + +## Classes + +### `RateLimitError` ↗ + + +Error raised when rate limit is exceeded. + + +### `TokenBucketRateLimiter` ↗ + + +Token bucket implementation for rate limiting. + + +### `SlidingWindowRateLimiter` ↗ + + +Sliding window rate limiter implementation. + + +### `RateLimitingMiddleware` ↗ + + +Middleware that implements rate limiting to prevent server abuse. + +Uses a token bucket algorithm by default, allowing for burst traffic +while maintaining a sustainable long-term rate. + + +### `SlidingWindowRateLimitingMiddleware` ↗ + + +Middleware that implements sliding window rate limiting. + +Uses a sliding window approach which provides more precise rate limiting +but uses more memory to track individual request timestamps. + diff --git a/docs/python-sdk/fastmcp-server-middleware-timing.mdx b/docs/python-sdk/fastmcp-server-middleware-timing.mdx new file mode 100644 index 000000000..3d448ffff --- /dev/null +++ b/docs/python-sdk/fastmcp-server-middleware-timing.mdx @@ -0,0 +1,29 @@ +--- +title: timing +sidebarTitle: timing +--- + +# `fastmcp.server.middleware.timing` + + +Timing middleware for measuring and logging request performance. + +## Classes + +### `TimingMiddleware` ↗ + + +Middleware that logs the execution time of requests. + +Only measures and logs timing for request messages (not notifications). +Provides insights into performance characteristics of your MCP server. + + +### `DetailedTimingMiddleware` ↗ + + +Enhanced timing middleware with per-operation breakdowns. + +Provides detailed timing information for different types of MCP operations, +allowing you to identify performance bottlenecks in specific operations. + diff --git a/docs/python-sdk/fastmcp-server-openapi.mdx b/docs/python-sdk/fastmcp-server-openapi.mdx index d2490cea7..ad670dcd7 100644 --- a/docs/python-sdk/fastmcp-server-openapi.mdx +++ b/docs/python-sdk/fastmcp-server-openapi.mdx @@ -10,13 +10,13 @@ FastMCP server implementation for OpenAPI integration. ## Classes -### `MCPType` +### `MCPType` ↗ Type of FastMCP component to create from a route. -### `RouteType` +### `RouteType` ↗ Deprecated: Use MCPType instead. @@ -24,31 +24,31 @@ Deprecated: Use MCPType instead. This enum is kept for backward compatibility and will be removed in a future version. -### `RouteMap` +### `RouteMap` ↗ Mapping configuration for HTTP routes to FastMCP component types. -### `OpenAPITool` +### `OpenAPITool` ↗ Tool implementation for OpenAPI endpoints. -### `OpenAPIResource` +### `OpenAPIResource` ↗ Resource implementation for OpenAPI endpoints. -### `OpenAPIResourceTemplate` +### `OpenAPIResourceTemplate` ↗ Resource template implementation for OpenAPI endpoints. -### `FastMCPOpenAPI` +### `FastMCPOpenAPI` ↗ FastMCP server implementation that creates components from an OpenAPI schema. diff --git a/docs/python-sdk/fastmcp-server-proxy.mdx b/docs/python-sdk/fastmcp-server-proxy.mdx index bad549605..b363b853c 100644 --- a/docs/python-sdk/fastmcp-server-proxy.mdx +++ b/docs/python-sdk/fastmcp-server-proxy.mdx @@ -7,25 +7,25 @@ sidebarTitle: proxy ## Classes -### `ProxyToolManager` +### `ProxyToolManager` ↗ A ToolManager that sources its tools from a remote client in addition to local and mounted tools. -### `ProxyResourceManager` +### `ProxyResourceManager` ↗ A ResourceManager that sources its resources from a remote client in addition to local and mounted resources. -### `ProxyPromptManager` +### `ProxyPromptManager` ↗ A PromptManager that sources its prompts from a remote client in addition to local and mounted prompts. -### `ProxyTool` +### `ProxyTool` ↗ A Tool that represents and executes a tool on a remote server. @@ -33,7 +33,7 @@ A Tool that represents and executes a tool on a remote server. **Methods:** -#### `from_mcp_tool` +#### `from_mcp_tool` ↗ ```python from_mcp_tool(cls, client: Client, mcp_tool: mcp.types.Tool) -> ProxyTool @@ -42,7 +42,7 @@ from_mcp_tool(cls, client: Client, mcp_tool: mcp.types.Tool) -> ProxyTool Factory method to create a ProxyTool from a raw MCP tool schema. -### `ProxyResource` +### `ProxyResource` ↗ A Resource that represents and reads a resource from a remote server. @@ -50,7 +50,7 @@ A Resource that represents and reads a resource from a remote server. **Methods:** -#### `from_mcp_resource` +#### `from_mcp_resource` ↗ ```python from_mcp_resource(cls, client: Client, mcp_resource: mcp.types.Resource) -> ProxyResource @@ -59,7 +59,7 @@ from_mcp_resource(cls, client: Client, mcp_resource: mcp.types.Resource) -> Prox Factory method to create a ProxyResource from a raw MCP resource schema. -### `ProxyTemplate` +### `ProxyTemplate` ↗ A ResourceTemplate that represents and creates resources from a remote server template. @@ -67,7 +67,7 @@ A ResourceTemplate that represents and creates resources from a remote server te **Methods:** -#### `from_mcp_template` +#### `from_mcp_template` ↗ ```python from_mcp_template(cls, client: Client, mcp_template: mcp.types.ResourceTemplate) -> ProxyTemplate @@ -76,7 +76,7 @@ from_mcp_template(cls, client: Client, mcp_template: mcp.types.ResourceTemplate) Factory method to create a ProxyTemplate from a raw MCP template schema. -### `ProxyPrompt` +### `ProxyPrompt` ↗ A Prompt that represents and renders a prompt from a remote server. @@ -84,7 +84,7 @@ A Prompt that represents and renders a prompt from a remote server. **Methods:** -#### `from_mcp_prompt` +#### `from_mcp_prompt` ↗ ```python from_mcp_prompt(cls, client: Client, mcp_prompt: mcp.types.Prompt) -> ProxyPrompt @@ -93,7 +93,7 @@ from_mcp_prompt(cls, client: Client, mcp_prompt: mcp.types.Prompt) -> ProxyPromp Factory method to create a ProxyPrompt from a raw MCP prompt schema. -### `FastMCPProxy` +### `FastMCPProxy` ↗ A FastMCP server that acts as a proxy to a remote MCP-compliant server. diff --git a/docs/python-sdk/fastmcp-server-server.mdx b/docs/python-sdk/fastmcp-server-server.mdx index 2b3c1ed83..c89bb0152 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 -### `add_resource_prefix` +### `add_resource_prefix` ↗ ```python add_resource_prefix(uri: str, prefix: str, prefix_format: Literal['protocol', 'path'] | None = None) -> str @@ -19,26 +19,27 @@ add_resource_prefix(uri: str, prefix: str, prefix_format: Literal['protocol', 'p Add a prefix to a resource URI. - Args: - uri: The original resource URI - prefix: The prefix to add +**Args:** +- `uri`: The original resource URI +- `prefix`: The prefix to add - Returns: - The resource URI with the prefix added +**Returns:** +- The resource URI with the prefix added - Examples: - >>> add_resource_prefix("resource://path/to/resource", "prefix") - "resource://prefix/path/to/resource" # with new style - >>> add_resource_prefix("resource://path/to/resource", "prefix") - "prefix+resource://path/to/resource" # with legacy style - >>> add_resource_prefix("resource:///absolute/path", "prefix") - "resource://prefix//absolute/path" # with new style +**Examples:** - Raises: - ValueError: If the URI doesn't match the expected protocol://path format - +>>> add_resource_prefix("resource://path/to/resource", "prefix") +"resource://prefix/path/to/resource" # with new style +>>> add_resource_prefix("resource://path/to/resource", "prefix") +"prefix+resource://path/to/resource" # with legacy style +>>> add_resource_prefix("resource:///absolute/path", "prefix") +"resource://prefix//absolute/path" # with new style -### `remove_resource_prefix` +**Raises:** +- `ValueError`: If the URI doesn't match the expected protocol\://path format + + +### `remove_resource_prefix` ↗ ```python remove_resource_prefix(uri: str, prefix: str, prefix_format: Literal['protocol', 'path'] | None = None) -> str @@ -47,26 +48,28 @@ remove_resource_prefix(uri: str, prefix: str, prefix_format: Literal['protocol', Remove a prefix from a resource URI. - Args: - uri: The resource URI with a prefix - prefix: The prefix to remove - prefix_format: The format of the prefix to remove - Returns: - The resource URI with the prefix removed +**Args:** +- `uri`: The resource URI with a prefix +- `prefix`: The prefix to remove +- `prefix_format`: The format of the prefix to remove - Examples: - >>> remove_resource_prefix("resource://prefix/path/to/resource", "prefix") - "resource://path/to/resource" # with new style - >>> remove_resource_prefix("prefix+resource://path/to/resource", "prefix") - "resource://path/to/resource" # with legacy style - >>> remove_resource_prefix("resource://prefix//absolute/path", "prefix") - "resource:///absolute/path" # with new style +Returns: + The resource URI with the prefix removed - Raises: - ValueError: If the URI doesn't match the expected protocol://path format - +**Examples:** -### `has_resource_prefix` +>>> remove_resource_prefix("resource://prefix/path/to/resource", "prefix") +"resource://path/to/resource" # with new style +>>> remove_resource_prefix("prefix+resource://path/to/resource", "prefix") +"resource://path/to/resource" # with legacy style +>>> remove_resource_prefix("resource://prefix//absolute/path", "prefix") +"resource:///absolute/path" # with new style + +**Raises:** +- `ValueError`: If the URI doesn't match the expected protocol\://path format + + +### `has_resource_prefix` ↗ ```python has_resource_prefix(uri: str, prefix: str, prefix_format: Literal['protocol', 'path'] | None = None) -> bool @@ -75,53 +78,54 @@ has_resource_prefix(uri: str, prefix: str, prefix_format: Literal['protocol', 'p Check if a resource URI has a specific prefix. - Args: - uri: The resource URI to check - prefix: The prefix to look for +**Args:** +- `uri`: The resource URI to check +- `prefix`: The prefix to look for - Returns: - True if the URI has the specified prefix, False otherwise +**Returns:** +- True if the URI has the specified prefix, False otherwise - Examples: - >>> has_resource_prefix("resource://prefix/path/to/resource", "prefix") - True # with new style - >>> has_resource_prefix("prefix+resource://path/to/resource", "prefix") - True # with legacy style - >>> has_resource_prefix("resource://other/path/to/resource", "prefix") - False +**Examples:** + +>>> has_resource_prefix("resource://prefix/path/to/resource", "prefix") +True # with new style +>>> has_resource_prefix("prefix+resource://path/to/resource", "prefix") +True # with legacy style +>>> has_resource_prefix("resource://other/path/to/resource", "prefix") +False + +**Raises:** +- `ValueError`: If the URI doesn't match the expected protocol\://path format - Raises: - ValueError: If the URI doesn't match the expected protocol://path format - ## Classes -### `FastMCP` +### `FastMCP` ↗ **Methods:** -#### `settings` +#### `settings` ↗ ```python settings(self) -> Settings ``` -#### `name` +#### `name` ↗ ```python name(self) -> str ``` -#### `instructions` +#### `instructions` ↗ ```python instructions(self) -> str | None ``` -#### `run` +#### `run` ↗ ```python -run(self, transport: Literal['stdio', 'streamable-http', 'sse'] | None = None, **transport_kwargs: Any) -> None +run(self, transport: Transport | None = None, **transport_kwargs: Any) -> None ``` Run the FastMCP server. Note this is a synchronous function. @@ -130,13 +134,13 @@ 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 ``` -#### `custom_route` +#### `custom_route` ↗ ```python custom_route(self, path: str, methods: list[str], name: str | None = None, include_in_schema: bool = True) @@ -157,7 +161,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) -> None @@ -172,7 +176,7 @@ with the Context type annotation. See the @tool decorator for examples. - `tool`: The Tool instance to register -#### `remove_tool` +#### `remove_tool` ↗ ```python remove_tool(self, name: str) -> None @@ -187,19 +191,19 @@ Remove a tool from the server. - `NotFoundError`: If the tool is not found -#### `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 @@ -228,7 +232,7 @@ This decorator supports multiple calling patterns: - `enabled`: Optional boolean to enable or disable the tool -#### `add_resource` +#### `add_resource` ↗ ```python add_resource(self, resource: Resource) -> None @@ -240,7 +244,7 @@ Add a resource to the server. - `resource`: A Resource instance to add -#### `add_template` +#### `add_template` ↗ ```python add_template(self, template: ResourceTemplate) -> None @@ -252,7 +256,7 @@ Add a resource template to the server. - `template`: A ResourceTemplate instance to add -#### `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 @@ -272,7 +276,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] @@ -302,7 +306,7 @@ has parameters, it will be registered as a template resource. - `enabled`: Optional boolean to enable or disable the resource -#### `add_prompt` +#### `add_prompt` ↗ ```python add_prompt(self, prompt: Prompt) -> None @@ -314,19 +318,19 @@ Add a prompt to the server. - `prompt`: A Prompt instance to add -#### `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 @@ -400,7 +404,7 @@ Decorator to register a prompt. server.prompt(my_function, name="custom_name") -#### `sse_app` +#### `sse_app` ↗ ```python sse_app(self, path: str | None = None, message_path: str | None = None, middleware: list[ASGIMiddleware] | None = None) -> StarletteWithLifespan @@ -414,7 +418,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 @@ -427,10 +431,10 @@ 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['streamable-http', 'sse'] = 'streamable-http') -> StarletteWithLifespan +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 ``` Create a Starlette app using the specified HTTP transport. @@ -444,7 +448,7 @@ Create a Starlette app using the specified HTTP transport. - A Starlette application configured with the specified transport -#### `mount` +#### `mount` ↗ ```python mount(self, server: FastMCP[LifespanResultT], prefix: str | None = None, as_proxy: bool | None = None) -> None @@ -498,7 +502,7 @@ automatically determined based on whether the server has a custom lifespan - `prompt_separator`: Deprecated. Separator character for prompt names. -#### `from_openapi` +#### `from_openapi` ↗ ```python from_openapi(cls, openapi_spec: dict[str, Any], client: httpx.AsyncClient, route_maps: list[RouteMap] | None = None, route_map_fn: OpenAPIRouteMapFn | None = None, mcp_component_fn: OpenAPIComponentFn | None = None, mcp_names: dict[str, str] | None = None, tags: set[str] | None = None, **settings: Any) -> FastMCPOpenAPI @@ -507,7 +511,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] | None = None, route_map_fn: OpenAPIRouteMapFn | None = None, mcp_component_fn: OpenAPIComponentFn | 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 @@ -516,7 +520,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 @@ -530,7 +534,7 @@ instance or any value accepted as the ``transport`` argument of ``Client`` constructor. -#### `from_client` +#### `from_client` ↗ ```python from_client(cls, client: Client[ClientTransportT], **settings: Any) -> FastMCPProxy @@ -539,4 +543,4 @@ from_client(cls, client: Client[ClientTransportT], **settings: Any) -> FastMCPPr Create a FastMCP proxy server from a FastMCP client. -### `MountedServer` +### `MountedServer` ↗ diff --git a/docs/python-sdk/fastmcp-settings.mdx b/docs/python-sdk/fastmcp-settings.mdx index fd3e3d791..9f1319e27 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,15 +17,15 @@ 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` ↗ -### `Settings` +### `Settings` ↗ FastMCP settings. @@ -33,13 +33,13 @@ FastMCP settings. **Methods:** -#### `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 @@ -49,7 +49,7 @@ This property is for backwards compatibility with FastMCP < 2.8.0, which accessed fastmcp.settings.settings -#### `setup_logging` +#### `setup_logging` ↗ ```python setup_logging(self) -> Self diff --git a/docs/python-sdk/fastmcp-tools-tool.mdx b/docs/python-sdk/fastmcp-tools-tool.mdx index 7cae406aa..18b4fb688 100644 --- a/docs/python-sdk/fastmcp-tools-tool.mdx +++ b/docs/python-sdk/fastmcp-tools-tool.mdx @@ -7,7 +7,7 @@ sidebarTitle: tool ## Functions -### `default_serializer` +### `default_serializer` ↗ ```python default_serializer(data: Any) -> str @@ -15,7 +15,7 @@ default_serializer(data: Any) -> str ## Classes -### `Tool` +### `Tool` ↗ Internal tool registration info. @@ -23,13 +23,13 @@ Internal tool registration info. **Methods:** -#### `to_mcp_tool` +#### `to_mcp_tool` ↗ ```python to_mcp_tool(self, **overrides: Any) -> MCPTool ``` -#### `from_function` +#### `from_function` ↗ ```python from_function(fn: Callable[..., Any], name: str | None = None, description: str | None = None, tags: set[str] | None = None, annotations: ToolAnnotations | None = None, exclude_args: list[str] | None = None, serializer: Callable[[Any], str] | None = None, enabled: bool | None = None) -> FunctionTool @@ -38,17 +38,17 @@ from_function(fn: Callable[..., Any], name: str | None = None, description: str Create a Tool from a function. -#### `from_tool` +#### `from_tool` ↗ ```python from_tool(cls, tool: Tool, transform_fn: Callable[..., Any] | None = None, name: str | None = None, transform_args: dict[str, ArgTransform] | None = None, description: str | None = None, tags: set[str] | None = None, annotations: ToolAnnotations | None = None, serializer: Callable[[Any], str] | None = None, enabled: bool | None = None) -> TransformedTool ``` -### `FunctionTool` +### `FunctionTool` ↗ **Methods:** -#### `from_function` +#### `from_function` ↗ ```python from_function(cls, fn: Callable[..., Any], name: str | None = None, description: str | None = None, tags: set[str] | None = None, annotations: ToolAnnotations | None = None, exclude_args: list[str] | None = None, serializer: Callable[[Any], str] | None = None, enabled: bool | None = None) -> FunctionTool @@ -57,11 +57,11 @@ from_function(cls, fn: Callable[..., Any], name: str | None = None, description: Create a Tool from a function. -### `ParsedFunction` +### `ParsedFunction` ↗ **Methods:** -#### `from_function` +#### `from_function` ↗ ```python from_function(cls, fn: Callable[..., Any], exclude_args: list[str] | None = None, validate: bool = True) -> ParsedFunction diff --git a/docs/python-sdk/fastmcp-tools-tool_manager.mdx b/docs/python-sdk/fastmcp-tools-tool_manager.mdx index fad031d72..a44178e0d 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,7 +15,7 @@ Manages FastMCP tools. **Methods:** -#### `mount` +#### `mount` ↗ ```python mount(self, server: MountedServer) -> None @@ -24,7 +24,7 @@ mount(self, server: MountedServer) -> None Adds a mounted server as a source for tools. -#### `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 @@ -33,7 +33,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 @@ -42,7 +42,7 @@ add_tool(self, tool: Tool) -> Tool Register a tool with the server. -#### `remove_tool` +#### `remove_tool` ↗ ```python remove_tool(self, key: str) -> None diff --git a/docs/python-sdk/fastmcp-tools-tool_transform.mdx b/docs/python-sdk/fastmcp-tools-tool_transform.mdx index abee7d5eb..66a319619 100644 --- a/docs/python-sdk/fastmcp-tools-tool_transform.mdx +++ b/docs/python-sdk/fastmcp-tools-tool_transform.mdx @@ -7,58 +7,49 @@ sidebarTitle: tool_transform ## Classes -### `ArgTransform` +### `ArgTransform` ↗ Configuration for transforming a parent tool's argument. - This class allows fine-grained control over how individual arguments are transformed - when creating a new tool from an existing one. You can rename arguments, change their - descriptions, add default values, or hide them from clients while passing constants. +This class allows fine-grained control over how individual arguments are transformed +when creating a new tool from an existing one. You can rename arguments, change their +descriptions, add default values, or hide them from clients while passing constants. - Attributes: - name: New name for the argument. Use None to keep original name, or ... for no change. - description: New description for the argument. Use None to remove description, or ... for no change. - default: New default value for the argument. Use ... for no change. - default_factory: Callable that returns a default value. Cannot be used with default. - type: New type for the argument. Use ... for no change. - hide: If True, hide this argument from clients but pass a constant value to parent. - required: If True, make argument required (remove default). Use ... for no change. - examples: Examples for the argument. Use ... for no change. +**Examples:** - Examples: - # Rename argument 'old_name' to 'new_name' - ArgTransform(name="new_name") +# Rename argument 'old_name' to 'new_name' +ArgTransform(name="new_name") - # Change description only - ArgTransform(description="Updated description") +# Change description only +ArgTransform(description="Updated description") - # Add a default value (makes argument optional) - ArgTransform(default=42) +# Add a default value (makes argument optional) +ArgTransform(default=42) - # Add a default factory (makes argument optional) - ArgTransform(default_factory=lambda: time.time()) +# Add a default factory (makes argument optional) +ArgTransform(default_factory=lambda: time.time()) - # Change the type - ArgTransform(type=str) +# Change the type +ArgTransform(type=str) - # Hide the argument entirely from clients - ArgTransform(hide=True) +# Hide the argument entirely from clients +ArgTransform(hide=True) - # Hide argument but pass a constant value to parent - ArgTransform(hide=True, default="constant_value") +# Hide argument but pass a constant value to parent +ArgTransform(hide=True, default="constant_value") - # Hide argument but pass a factory-generated value to parent - ArgTransform(hide=True, default_factory=lambda: uuid.uuid4().hex) +# Hide argument but pass a factory-generated value to parent +ArgTransform(hide=True, default_factory=lambda: uuid.uuid4().hex) - # Make an optional parameter required (removes any default) - ArgTransform(required=True) +# Make an optional parameter required (removes any default) +ArgTransform(required=True) - # Combine multiple transformations - ArgTransform(name="new_name", description="New desc", default=None, type=int) - +# Combine multiple transformations +ArgTransform(name="new_name", description="New desc", default=None, type=int) -### `TransformedTool` + +### `TransformedTool` ↗ A tool that is transformed from another tool. @@ -74,7 +65,7 @@ with transformed arguments. **Methods:** -#### `from_tool` +#### `from_tool` ↗ ```python from_tool(cls, tool: Tool, name: str | None = None, description: str | None = None, tags: set[str] | None = None, transform_fn: Callable[..., Any] | None = None, transform_args: dict[str, ArgTransform] | None = None, annotations: ToolAnnotations | None = None, serializer: Callable[[Any], str] | None = None, enabled: bool | None = None) -> TransformedTool diff --git a/docs/python-sdk/fastmcp-utilities-cache.mdx b/docs/python-sdk/fastmcp-utilities-cache.mdx index ab41395d9..e81db5b33 100644 --- a/docs/python-sdk/fastmcp-utilities-cache.mdx +++ b/docs/python-sdk/fastmcp-utilities-cache.mdx @@ -7,23 +7,23 @@ sidebarTitle: cache ## Classes -### `TimedCache` +### `TimedCache` ↗ **Methods:** -#### `set` +#### `set` ↗ ```python set(self, key: Any, value: Any) -> None ``` -#### `get` +#### `get` ↗ ```python get(self, key: Any) -> Any ``` -#### `clear` +#### `clear` ↗ ```python clear(self) -> None diff --git a/docs/python-sdk/fastmcp-utilities-components.mdx b/docs/python-sdk/fastmcp-utilities-components.mdx index 61434c7d5..12cb11e5c 100644 --- a/docs/python-sdk/fastmcp-utilities-components.mdx +++ b/docs/python-sdk/fastmcp-utilities-components.mdx @@ -7,7 +7,7 @@ sidebarTitle: components ## Classes -### `FastMCPComponent` +### `FastMCPComponent` ↗ Base class for FastMCP tools, prompts, resources, and resource templates. @@ -15,7 +15,7 @@ Base class for FastMCP tools, prompts, resources, and resource templates. **Methods:** -#### `key` +#### `key` ↗ ```python key(self) -> str @@ -27,13 +27,13 @@ keys having a certain value, as the same tool loaded from different hierarchies of servers may have different keys. -#### `with_key` +#### `with_key` ↗ ```python with_key(self, key: str) -> Self ``` -#### `enable` +#### `enable` ↗ ```python enable(self) -> None @@ -42,7 +42,7 @@ enable(self) -> None Enable the component. -#### `disable` +#### `disable` ↗ ```python disable(self) -> None diff --git a/docs/python-sdk/fastmcp-utilities-exceptions.mdx b/docs/python-sdk/fastmcp-utilities-exceptions.mdx index 2d480a146..d5e406b5e 100644 --- a/docs/python-sdk/fastmcp-utilities-exceptions.mdx +++ b/docs/python-sdk/fastmcp-utilities-exceptions.mdx @@ -7,13 +7,13 @@ sidebarTitle: exceptions ## Functions -### `iter_exc` +### `iter_exc` ↗ ```python iter_exc(group: BaseExceptionGroup) ``` -### `get_catch_handlers` +### `get_catch_handlers` ↗ ```python get_catch_handlers() -> Mapping[type[BaseException] | Iterable[type[BaseException]], Callable[[BaseExceptionGroup[Any]], Any]] diff --git a/docs/python-sdk/fastmcp-utilities-http.mdx b/docs/python-sdk/fastmcp-utilities-http.mdx index 6e5e4b75f..55a5a2e92 100644 --- a/docs/python-sdk/fastmcp-utilities-http.mdx +++ b/docs/python-sdk/fastmcp-utilities-http.mdx @@ -7,7 +7,7 @@ sidebarTitle: http ## Functions -### `find_available_port` +### `find_available_port` ↗ ```python find_available_port() -> int diff --git a/docs/python-sdk/fastmcp-utilities-inspect.mdx b/docs/python-sdk/fastmcp-utilities-inspect.mdx index 0f12cd8a0..860043529 100644 --- a/docs/python-sdk/fastmcp-utilities-inspect.mdx +++ b/docs/python-sdk/fastmcp-utilities-inspect.mdx @@ -10,31 +10,31 @@ Utilities for inspecting FastMCP instances. ## Classes -### `ToolInfo` +### `ToolInfo` ↗ Information about a tool. -### `PromptInfo` +### `PromptInfo` ↗ Information about a prompt. -### `ResourceInfo` +### `ResourceInfo` ↗ Information about a resource. -### `TemplateInfo` +### `TemplateInfo` ↗ Information about a resource template. -### `FastMCPInfo` +### `FastMCPInfo` ↗ Information extracted from a FastMCP instance. diff --git a/docs/python-sdk/fastmcp-utilities-json_schema.mdx b/docs/python-sdk/fastmcp-utilities-json_schema.mdx index ad68473a0..c0b87d3c1 100644 --- a/docs/python-sdk/fastmcp-utilities-json_schema.mdx +++ b/docs/python-sdk/fastmcp-utilities-json_schema.mdx @@ -7,7 +7,7 @@ sidebarTitle: json_schema ## Functions -### `compress_schema` +### `compress_schema` ↗ ```python compress_schema(schema: dict, prune_params: list[str] | None = None, prune_defs: bool = True, prune_additional_properties: bool = True, prune_titles: bool = False) -> dict diff --git a/docs/python-sdk/fastmcp-utilities-logging.mdx b/docs/python-sdk/fastmcp-utilities-logging.mdx index 90e294f6a..306d0b39f 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 = True) -> None diff --git a/docs/python-sdk/fastmcp-utilities-mcp_config.mdx b/docs/python-sdk/fastmcp-utilities-mcp_config.mdx index b74dfcfa0..5731b6566 100644 --- a/docs/python-sdk/fastmcp-utilities-mcp_config.mdx +++ b/docs/python-sdk/fastmcp-utilities-mcp_config.mdx @@ -7,10 +7,10 @@ sidebarTitle: mcp_config ## Functions -### `infer_transport_type_from_url` +### `infer_transport_type_from_url` ↗ ```python -infer_transport_type_from_url(url: str | AnyUrl) -> Literal['streamable-http', 'sse'] +infer_transport_type_from_url(url: str | AnyUrl) -> Literal['http', 'sse'] ``` @@ -19,31 +19,31 @@ Infer the appropriate transport type from the given URL. ## Classes -### `StdioMCPServer` +### `StdioMCPServer` ↗ **Methods:** -#### `to_transport` +#### `to_transport` ↗ ```python to_transport(self) -> StdioTransport ``` -### `RemoteMCPServer` +### `RemoteMCPServer` ↗ **Methods:** -#### `to_transport` +#### `to_transport` ↗ ```python to_transport(self) -> StreamableHttpTransport | SSETransport ``` -### `MCPConfig` +### `MCPConfig` ↗ **Methods:** -#### `from_dict` +#### `from_dict` ↗ ```python from_dict(cls, config: dict[str, Any]) -> MCPConfig diff --git a/docs/python-sdk/fastmcp-utilities-openapi.mdx b/docs/python-sdk/fastmcp-utilities-openapi.mdx index 7b7d0aa62..942668c33 100644 --- a/docs/python-sdk/fastmcp-utilities-openapi.mdx +++ b/docs/python-sdk/fastmcp-utilities-openapi.mdx @@ -7,7 +7,7 @@ sidebarTitle: openapi ## Functions -### `parse_openapi_to_http_routes` +### `parse_openapi_to_http_routes` ↗ ```python parse_openapi_to_http_routes(openapi_dict: dict[str, Any]) -> list[HTTPRoute] @@ -20,7 +20,7 @@ using the openapi-pydantic library. Supports both OpenAPI 3.0.x and 3.1.x versions. -### `clean_schema_for_display` +### `clean_schema_for_display` ↗ ```python clean_schema_for_display(schema: JsonSchema | None) -> JsonSchema | None @@ -30,7 +30,7 @@ clean_schema_for_display(schema: JsonSchema | None) -> JsonSchema | None Clean up a schema dictionary for display by removing internal/complex fields. -### `generate_example_from_schema` +### `generate_example_from_schema` ↗ ```python generate_example_from_schema(schema: JsonSchema | None) -> Any @@ -41,7 +41,7 @@ Generate a simple example value from a JSON schema dictionary. Very basic implementation focusing on types. -### `format_json_for_description` +### `format_json_for_description` ↗ ```python format_json_for_description(data: Any, indent: int = 2) -> str @@ -51,7 +51,7 @@ format_json_for_description(data: Any, indent: int = 2) -> str Formats Python data as a JSON string block for markdown. -### `format_description_with_responses` +### `format_description_with_responses` ↗ ```python format_description_with_responses(base_description: str, responses: dict[str, Any], parameters: list[ParameterInfo] | None = None, request_body: RequestBodyInfo | None = None) -> str @@ -76,31 +76,31 @@ including its description, whether it is required, and its content schema. ## Classes -### `ParameterInfo` +### `ParameterInfo` ↗ Represents a single parameter for an HTTP operation in our IR. -### `RequestBodyInfo` +### `RequestBodyInfo` ↗ Represents the request body for an HTTP operation in our IR. -### `ResponseInfo` +### `ResponseInfo` ↗ Represents response information in our IR. -### `HTTPRoute` +### `HTTPRoute` ↗ Intermediate Representation for a single OpenAPI operation. -### `OpenAPIParser` +### `OpenAPIParser` ↗ Unified parser for OpenAPI schemas with generic type parameters to handle both 3.0 and 3.1. @@ -108,7 +108,7 @@ Unified parser for OpenAPI schemas with generic type parameters to handle both 3 **Methods:** -#### `parse` +#### `parse` ↗ ```python parse(self) -> list[HTTPRoute] diff --git a/docs/python-sdk/fastmcp-utilities-tests.mdx b/docs/python-sdk/fastmcp-utilities-tests.mdx index 817f113d0..f19af5a24 100644 --- a/docs/python-sdk/fastmcp-utilities-tests.mdx +++ b/docs/python-sdk/fastmcp-utilities-tests.mdx @@ -7,20 +7,20 @@ sidebarTitle: tests ## Functions -### `temporary_settings` +### `temporary_settings` ↗ ```python temporary_settings(**kwargs: Any) ``` -Temporarily override ControlFlow setting values. +Temporarily override FastMCP setting values. **Args:** - `**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] diff --git a/docs/python-sdk/fastmcp-utilities-types.mdx b/docs/python-sdk/fastmcp-utilities-types.mdx index 3810bb878..662fd66b0 100644 --- a/docs/python-sdk/fastmcp-utilities-types.mdx +++ b/docs/python-sdk/fastmcp-utilities-types.mdx @@ -10,7 +10,7 @@ Common types used across FastMCP. ## Functions -### `get_cached_typeadapter` +### `get_cached_typeadapter` ↗ ```python get_cached_typeadapter(cls: T) -> TypeAdapter[T] @@ -23,7 +23,7 @@ However, this isn't feasible for user-generated functions. Instead, we use a cache to minimize the cost of creating them as much as possible. -### `issubclass_safe` +### `issubclass_safe` ↗ ```python issubclass_safe(cls: type, base: type) -> bool @@ -33,7 +33,7 @@ issubclass_safe(cls: type, base: type) -> bool Check if cls is a subclass of base, even if cls is a type variable. -### `is_class_member_of_type` +### `is_class_member_of_type` ↗ ```python is_class_member_of_type(cls: type, base: type) -> bool @@ -46,7 +46,7 @@ Base can be a type, a UnionType, or an Annotated type. Generic types are not considered members (e.g. T is not a member of list\[T]). -### `find_kwarg_by_type` +### `find_kwarg_by_type` ↗ ```python find_kwarg_by_type(fn: Callable, kwarg_type: type) -> str | None @@ -60,13 +60,13 @@ Includes union types that contain the kwarg_type, as well as Annotated types. ## Classes -### `FastMCPBaseModel` +### `FastMCPBaseModel` ↗ Base model for FastMCP models. -### `Image` +### `Image` ↗ Helper class for returning images from tools. @@ -74,7 +74,7 @@ Helper class for returning images from tools. **Methods:** -#### `to_image_content` +#### `to_image_content` ↗ ```python to_image_content(self, mime_type: str | None = None, annotations: Annotations | None = None) -> ImageContent @@ -83,7 +83,7 @@ to_image_content(self, mime_type: str | None = None, annotations: Annotations | Convert to MCP ImageContent. -### `Audio` +### `Audio` ↗ Helper class for returning audio from tools. @@ -91,13 +91,13 @@ Helper class for returning audio from tools. **Methods:** -#### `to_audio_content` +#### `to_audio_content` ↗ ```python to_audio_content(self, mime_type: str | None = None, annotations: Annotations | None = None) -> AudioContent ``` -### `File` +### `File` ↗ Helper class for returning audio from tools. @@ -105,7 +105,7 @@ Helper class for returning audio from tools. **Methods:** -#### `to_resource_content` +#### `to_resource_content` ↗ ```python to_resource_content(self, mime_type: str | None = None, annotations: Annotations | None = None) -> EmbeddedResource