From 145dbbfb4c3b2ed833a2d994735a2d706f050def Mon Sep 17 00:00:00 2001 From: "marvin-context-protocol[bot]" <225465937+marvin-context-protocol[bot]@users.noreply.github.com> Date: Wed, 25 Mar 2026 10:58:34 -0400 Subject: [PATCH] chore: Update SDK documentation (#3615) Co-authored-by: marvin-context-protocol[bot] <225465937+marvin-context-protocol[bot]@users.noreply.github.com> --- docs/docs.json | 9 ++ docs/python-sdk/fastmcp-apps-__init__.mdx | 16 ++ docs/python-sdk/fastmcp-apps-app.mdx | 146 ++++++++++++++++++ docs/python-sdk/fastmcp-apps-config.mdx | 64 ++++++++ docs/python-sdk/fastmcp-server-app.mdx | 139 +---------------- docs/python-sdk/fastmcp-server-apps.mdx | 79 +--------- .../fastmcp-server-auth-providers-google.mdx | 18 ++- docs/python-sdk/fastmcp-server-context.mdx | 2 +- docs/python-sdk/fastmcp-utilities-mime.mdx | 35 +++++ 9 files changed, 290 insertions(+), 218 deletions(-) create mode 100644 docs/python-sdk/fastmcp-apps-__init__.mdx create mode 100644 docs/python-sdk/fastmcp-apps-app.mdx create mode 100644 docs/python-sdk/fastmcp-apps-config.mdx create mode 100644 docs/python-sdk/fastmcp-utilities-mime.mdx diff --git a/docs/docs.json b/docs/docs.json index 91fef7409..1770ff0a1 100644 --- a/docs/docs.json +++ b/docs/docs.json @@ -368,6 +368,14 @@ "python-sdk/fastmcp-settings", "python-sdk/fastmcp-telemetry", "python-sdk/fastmcp-types", + { + "group": "fastmcp.apps", + "pages": [ + "python-sdk/fastmcp-apps-__init__", + "python-sdk/fastmcp-apps-app", + "python-sdk/fastmcp-apps-config" + ] + }, { "group": "fastmcp.cli", "pages": [ @@ -742,6 +750,7 @@ } ] }, + "python-sdk/fastmcp-utilities-mime", { "group": "openapi", "pages": [ diff --git a/docs/python-sdk/fastmcp-apps-__init__.mdx b/docs/python-sdk/fastmcp-apps-__init__.mdx new file mode 100644 index 000000000..5f69a4b59 --- /dev/null +++ b/docs/python-sdk/fastmcp-apps-__init__.mdx @@ -0,0 +1,16 @@ +--- +title: __init__ +sidebarTitle: __init__ +--- + +# `fastmcp.apps` + + +FastMCP Apps — interactive UIs for MCP tools. + +This package contains the app-related components: + +- ``FastMCPApp`` — composable provider for interactive apps with backend tools +- ``AppConfig`` — configuration for MCP App tools and resources +- ``ResourceCSP`` / ``ResourcePermissions`` — security configuration + diff --git a/docs/python-sdk/fastmcp-apps-app.mdx b/docs/python-sdk/fastmcp-apps-app.mdx new file mode 100644 index 000000000..93f93f3e3 --- /dev/null +++ b/docs/python-sdk/fastmcp-apps-app.mdx @@ -0,0 +1,146 @@ +--- +title: app +sidebarTitle: app +--- + +# `fastmcp.apps.app` + + +FastMCPApp — a Provider that represents a composable MCP application. + +FastMCPApp binds entry-point tools (model calls these) together with backend +tools (the UI calls these via CallTool). Backend tools are tagged with +``meta["fastmcp"]["app"]`` so they can be found through the provider chain +even when transforms (namespace, visibility, etc.) have renamed or hidden +them — the server sets a context var that tells ``Provider.get_tool`` to +fall back to a direct lookup for app-visible tools. + +Usage:: + + from fastmcp import FastMCP, FastMCPApp + + app = FastMCPApp("Dashboard") + + @app.ui() + def show_dashboard() -> Component: + return Column(...) + + @app.tool() + def save_contact(name: str, email: str) -> dict: + return {"name": name, "email": email} + + server = FastMCP("Platform") + server.add_provider(app) + + +## Classes + +### `FastMCPApp` + + +A Provider that represents an MCP application. + +Binds together entry-point tools (``@app.ui``), backend tools +(``@app.tool``), and the Prefab renderer resource. Backend tools +are tagged with ``meta["fastmcp"]["app"]`` so ``Provider.get_tool`` +can find them by original name even when transforms have been applied. + + +**Methods:** + +#### `tool` + +```python +tool(self, name_or_fn: F) -> F +``` + +#### `tool` + +```python +tool(self, name_or_fn: str | None = None) -> Callable[[F], F] +``` + +#### `tool` + +```python +tool(self, name_or_fn: str | AnyFunction | None = None) -> Any +``` + +Register a backend tool that the UI calls via CallTool. + +Backend tools default to ``visibility=["app"]``. Pass ``model=True`` +to also expose the tool to the model (``visibility=["app", "model"]``). + +Supports multiple calling patterns:: + + @app.tool + def save(name: str): ... + + @app.tool() + def save(name: str): ... + + @app.tool("custom_name") + def save(name: str): ... + + +#### `ui` + +```python +ui(self, name_or_fn: F) -> F +``` + +#### `ui` + +```python +ui(self, name_or_fn: str | None = None) -> Callable[[F], F] +``` + +#### `ui` + +```python +ui(self, name_or_fn: str | AnyFunction | None = None) -> Any +``` + +Register a UI entry-point tool that the model calls. + +Entry-point tools default to ``visibility=["model"]`` and auto-wire +the Prefab renderer resource and CSP. They are tagged with the app +name so structured content includes ``_meta.fastmcp.app``. + +Supports multiple calling patterns:: + + @app.ui + def dashboard() -> Component: ... + + @app.ui() + def dashboard() -> Component: ... + + @app.ui("my_dashboard") + def dashboard() -> Component: ... + + +#### `add_tool` + +```python +add_tool(self, tool: Tool | Callable[..., Any]) -> Tool +``` + +Add a tool to this app programmatically. + +The tool is tagged with this app's name for routing. + + +#### `lifespan` + +```python +lifespan(self) -> AsyncIterator[None] +``` + +#### `run` + +```python +run(self, transport: Literal['stdio', 'http', 'sse', 'streamable-http'] | None = None, **kwargs: Any) -> None +``` + +Create a temporary FastMCP server and run this app standalone. + diff --git a/docs/python-sdk/fastmcp-apps-config.mdx b/docs/python-sdk/fastmcp-apps-config.mdx new file mode 100644 index 000000000..aba84b288 --- /dev/null +++ b/docs/python-sdk/fastmcp-apps-config.mdx @@ -0,0 +1,64 @@ +--- +title: config +sidebarTitle: config +--- + +# `fastmcp.apps.config` + + +MCP Apps support — extension negotiation and typed UI metadata models. + +Provides constants and Pydantic models for the MCP Apps extension +(io.modelcontextprotocol/ui), enabling tools and resources to carry +UI metadata for clients that support interactive app rendering. + + +## Functions + +### `app_config_to_meta_dict` + +```python +app_config_to_meta_dict(app: AppConfig | dict[str, Any]) -> dict[str, Any] +``` + + +Convert an AppConfig or dict to the wire-format dict for ``meta["ui"]``. + + +## Classes + +### `ResourceCSP` + + +Content Security Policy for MCP App resources. + +Declares which external origins the app is allowed to connect to or +load resources from. Hosts use these declarations to build the +``Content-Security-Policy`` header for the sandboxed iframe. + + +### `ResourcePermissions` + + +Iframe sandbox permissions for MCP App resources. + +Each field, when set (typically to ``{}``), requests that the host +grant the corresponding Permission Policy feature to the sandboxed +iframe. Hosts MAY honour these; apps should use JS feature detection +as a fallback. + + +### `AppConfig` + + +Configuration for MCP App tools and resources. + +Controls how a tool or resource participates in the MCP Apps extension. +On tools, ``resource_uri`` and ``visibility`` specify which UI resource +to render and where the tool appears. On resources, those fields must +be left unset (the resource itself is the UI). + +All fields use ``exclude_none`` serialization so only explicitly-set +values appear on the wire. Aliases match the MCP Apps wire format +(camelCase). + diff --git a/docs/python-sdk/fastmcp-server-app.mdx b/docs/python-sdk/fastmcp-server-app.mdx index 7e1532394..7f99ecb53 100644 --- a/docs/python-sdk/fastmcp-server-app.mdx +++ b/docs/python-sdk/fastmcp-server-app.mdx @@ -6,141 +6,8 @@ sidebarTitle: app # `fastmcp.server.app` -FastMCPApp — a Provider that represents a composable MCP application. +Backward-compatible re-exports from fastmcp.apps.app. -FastMCPApp binds entry-point tools (model calls these) together with backend -tools (the UI calls these via CallTool). Backend tools are tagged with -``meta["fastmcp"]["app"]`` so they can be found through the provider chain -even when transforms (namespace, visibility, etc.) have renamed or hidden -them — the server sets a context var that tells ``Provider.get_tool`` to -fall back to a direct lookup for app-visible tools. - -Usage:: - - from fastmcp import FastMCP, FastMCPApp - - app = FastMCPApp("Dashboard") - - @app.ui() - def show_dashboard() -> Component: - return Column(...) - - @app.tool() - def save_contact(name: str, email: str) -> dict: - return {"name": name, "email": email} - - server = FastMCP("Platform") - server.add_provider(app) - - -## Classes - -### `FastMCPApp` - - -A Provider that represents an MCP application. - -Binds together entry-point tools (``@app.ui``), backend tools -(``@app.tool``), and the Prefab renderer resource. Backend tools -are tagged with ``meta["fastmcp"]["app"]`` so ``Provider.get_tool`` -can find them by original name even when transforms have been applied. - - -**Methods:** - -#### `tool` - -```python -tool(self, name_or_fn: F) -> F -``` - -#### `tool` - -```python -tool(self, name_or_fn: str | None = None) -> Callable[[F], F] -``` - -#### `tool` - -```python -tool(self, name_or_fn: str | AnyFunction | None = None) -> Any -``` - -Register a backend tool that the UI calls via CallTool. - -Backend tools default to ``visibility=["app"]``. Pass ``model=True`` -to also expose the tool to the model (``visibility=["app", "model"]``). - -Supports multiple calling patterns:: - - @app.tool - def save(name: str): ... - - @app.tool() - def save(name: str): ... - - @app.tool("custom_name") - def save(name: str): ... - - -#### `ui` - -```python -ui(self, name_or_fn: F) -> F -``` - -#### `ui` - -```python -ui(self, name_or_fn: str | None = None) -> Callable[[F], F] -``` - -#### `ui` - -```python -ui(self, name_or_fn: str | AnyFunction | None = None) -> Any -``` - -Register a UI entry-point tool that the model calls. - -Entry-point tools default to ``visibility=["model"]`` and auto-wire -the Prefab renderer resource and CSP. They are tagged with the app -name so structured content includes ``_meta.fastmcp.app``. - -Supports multiple calling patterns:: - - @app.ui - def dashboard() -> Component: ... - - @app.ui() - def dashboard() -> Component: ... - - @app.ui("my_dashboard") - def dashboard() -> Component: ... - - -#### `add_tool` - -```python -add_tool(self, tool: Tool | Callable[..., Any]) -> Tool -``` - -Add a tool to this app programmatically. - -The tool is tagged with this app's name for routing. - - -#### `lifespan` - -```python -lifespan(self) -> AsyncIterator[None] -``` - -#### `run` - -```python -run(self, transport: Literal['stdio', 'http', 'sse', 'streamable-http'] | None = None, **kwargs: Any) -> None -``` - -Create a temporary FastMCP server and run this app standalone. +.. deprecated:: 3.2.0 + Import from ``fastmcp.apps.app`` or ``fastmcp`` instead. diff --git a/docs/python-sdk/fastmcp-server-apps.mdx b/docs/python-sdk/fastmcp-server-apps.mdx index 00e53eafe..df7d64d44 100644 --- a/docs/python-sdk/fastmcp-server-apps.mdx +++ b/docs/python-sdk/fastmcp-server-apps.mdx @@ -6,81 +6,8 @@ sidebarTitle: apps # `fastmcp.server.apps` -MCP Apps support — extension negotiation and typed UI metadata models. +Backward-compatible re-exports from fastmcp.apps. -Provides constants and Pydantic models for the MCP Apps extension -(io.modelcontextprotocol/ui), enabling tools and resources to carry -UI metadata for clients that support interactive app rendering. - - -## Functions - -### `app_config_to_meta_dict` - -```python -app_config_to_meta_dict(app: AppConfig | dict[str, Any]) -> dict[str, Any] -``` - - -Convert an AppConfig or dict to the wire-format dict for ``meta["ui"]``. - - -### `resolve_ui_mime_type` - -```python -resolve_ui_mime_type(uri: str, explicit_mime_type: str | None) -> str | None -``` - - -Return the appropriate MIME type for a resource URI. - -For ``ui://`` scheme resources, defaults to ``UI_MIME_TYPE`` when no -explicit MIME type is provided. This ensures UI resources are correctly -identified regardless of how they're registered (via FastMCP.resource, -the standalone @resource decorator, or resource templates). - -**Args:** -- `uri`: The resource URI string -- `explicit_mime_type`: The MIME type explicitly provided by the user - -**Returns:** -- The resolved MIME type (explicit value, UI default, or None) - - -## Classes - -### `ResourceCSP` - - -Content Security Policy for MCP App resources. - -Declares which external origins the app is allowed to connect to or -load resources from. Hosts use these declarations to build the -``Content-Security-Policy`` header for the sandboxed iframe. - - -### `ResourcePermissions` - - -Iframe sandbox permissions for MCP App resources. - -Each field, when set (typically to ``{}``), requests that the host -grant the corresponding Permission Policy feature to the sandboxed -iframe. Hosts MAY honour these; apps should use JS feature detection -as a fallback. - - -### `AppConfig` - - -Configuration for MCP App tools and resources. - -Controls how a tool or resource participates in the MCP Apps extension. -On tools, ``resource_uri`` and ``visibility`` specify which UI resource -to render and where the tool appears. On resources, those fields must -be left unset (the resource itself is the UI). - -All fields use ``exclude_none`` serialization so only explicitly-set -values appear on the wire. Aliases match the MCP Apps wire format -(camelCase). +.. deprecated:: 3.2.0 + Import from ``fastmcp.apps`` instead. diff --git a/docs/python-sdk/fastmcp-server-auth-providers-google.mdx b/docs/python-sdk/fastmcp-server-auth-providers-google.mdx index b9568dbf9..05f2400b0 100644 --- a/docs/python-sdk/fastmcp-server-auth-providers-google.mdx +++ b/docs/python-sdk/fastmcp-server-auth-providers-google.mdx @@ -34,22 +34,30 @@ Example: Token verifier for Google OAuth tokens. -Google OAuth tokens are opaque (not JWTs), so we verify them -by calling Google's tokeninfo API to check if they're valid and get user info. +Google OAuth tokens are opaque (not JWTs), so we verify them by calling +Google's tokeninfo endpoint with the access token as a query parameter. +This returns the OAuth app ID (``aud``), granted scopes, and expiry time. +User profile data (name, picture, etc.) is fetched separately from the +v2 userinfo endpoint when the token is valid. **Methods:** -#### `verify_token` +#### `verify_token` ```python verify_token(self, token: str) -> AccessToken | None ``` -Verify Google OAuth token by calling Google's tokeninfo API. +Verify a Google OAuth token using the tokeninfo endpoint. + +Calls ``https://oauth2.googleapis.com/tokeninfo?access_token=TOKEN`` +to validate the token and retrieve the OAuth app ID (``aud``), granted +scopes, and expiry time. On success, fetches user profile data from +the v2 userinfo endpoint to populate name, picture, and locale claims. -### `GoogleProvider` +### `GoogleProvider` Complete Google OAuth provider for FastMCP. diff --git a/docs/python-sdk/fastmcp-server-context.mdx b/docs/python-sdk/fastmcp-server-context.mdx index 58a916faf..78371e393 100644 --- a/docs/python-sdk/fastmcp-server-context.mdx +++ b/docs/python-sdk/fastmcp-server-context.mdx @@ -319,7 +319,7 @@ request context) or when the client did not advertise the extension. Example:: - from fastmcp.server.apps import UI_EXTENSION_ID + from fastmcp.apps.config import UI_EXTENSION_ID @mcp.tool async def my_tool(ctx: Context) -> str: diff --git a/docs/python-sdk/fastmcp-utilities-mime.mdx b/docs/python-sdk/fastmcp-utilities-mime.mdx new file mode 100644 index 000000000..b823d447b --- /dev/null +++ b/docs/python-sdk/fastmcp-utilities-mime.mdx @@ -0,0 +1,35 @@ +--- +title: mime +sidebarTitle: mime +--- + +# `fastmcp.utilities.mime` + + +MIME type constants and helpers for MCP Apps UI resources. + +This module has no dependencies on the server or resource packages, +so it can be safely imported from anywhere. + + +## Functions + +### `resolve_ui_mime_type` + +```python +resolve_ui_mime_type(uri: str, explicit_mime_type: str | None) -> str | None +``` + + +Return the appropriate MIME type for a resource URI. + +For ``ui://`` scheme resources, defaults to ``UI_MIME_TYPE`` when no +explicit MIME type is provided. + +**Args:** +- `uri`: The resource URI string +- `explicit_mime_type`: The MIME type explicitly provided by the user + +**Returns:** +- The resolved MIME type (explicit value, UI default, or None) +