diff --git a/docs/development/v3-notes/v3-features.mdx b/docs/development/v3-notes/v3-features.mdx index 516d14b8b..9ef32f9c4 100644 --- a/docs/development/v3-notes/v3-features.mdx +++ b/docs/development/v3-notes/v3-features.mdx @@ -4,7 +4,25 @@ title: v3.0 Feature Tracking This document tracks major features in FastMCP v3.0 for release notes preparation. -## Provider-Based Architecture +## 3.0.0beta2 + +### CLI: `fastmcp install stdio` + +The new `fastmcp install stdio` command ([#3032](https://github.com/jlowin/fastmcp/pull/3032)) generates the full `uv run` command needed to run a FastMCP server over stdio, making it easy to paste into Claude Desktop or other MCP client configurations. + +```bash +$ fastmcp install stdio server.py +uv run --with fastmcp fastmcp run /absolute/path/to/server.py + +$ fastmcp install stdio fastmcp.json +uv run --with fastmcp --with pillow --with 'qrcode[pil]>=8.0' fastmcp run /absolute/path/to/qr_server.py +``` + +When given a `fastmcp.json` config file, dependencies are automatically included. The `--copy` flag sends the command directly to the clipboard. + +## 3.0.0beta1 + +#### Provider-Based Architecture v3.0 introduces a provider-based component system that replaces v2's static-only registration ([#2622](https://github.com/jlowin/fastmcp/pull/2622)). Providers dynamically source tools, resources, templates, and prompts at runtime. @@ -26,7 +44,7 @@ Providers support: - **Visibility control**: `enable()` / `disable()` with name, version, tags, components, and allowlist mode - **Transform stacking**: `provider.add_transform(Namespace(...))`, `provider.add_transform(ToolTransform(...))` -### LocalProvider +#### LocalProvider `LocalProvider` (`src/fastmcp/server/providers/local_provider.py`) manages components registered via decorators. Can be used standalone and attached to multiple servers: @@ -44,7 +62,7 @@ server1 = FastMCP("Server1", providers=[provider]) server2 = FastMCP("Server2", providers=[provider]) ``` -### ProxyProvider +#### ProxyProvider `ProxyProvider` (`src/fastmcp/server/providers/proxy.py`) proxies components from remote MCP servers via a client factory. Used by `create_proxy()` and `FastMCP.mount()` for remote server integration. @@ -55,7 +73,7 @@ from fastmcp.server import create_proxy server = create_proxy("http://remote-server/mcp") ``` -### OpenAPIProvider +#### OpenAPIProvider `OpenAPIProvider` (`src/fastmcp/server/providers/openapi/provider.py`) creates MCP components from OpenAPI specifications. Routes map HTTP operations to tools, resources, or templates based on configurable rules. @@ -75,7 +93,7 @@ Features: - Component customization via `mcp_component_fn` - Name collision detection and handling -### FastMCPProvider +#### FastMCPProvider `FastMCPProvider` (`src/fastmcp/server/providers/fastmcp_provider.py`) wraps a FastMCP server to enable mounting one server onto another. Components delegate execution through the wrapped server's middleware chain. @@ -98,7 +116,7 @@ main.add_provider(provider) # Tool accessible as "sub_greet" ``` -### Transforms +#### Transforms Transforms modify components (tools, resources, prompts) as they flow from providers to clients ([#2836](https://github.com/jlowin/fastmcp/pull/2836)). They use a middleware pattern where each transform receives a `call_next` callable to continue the chain. @@ -151,7 +169,7 @@ Transforms apply at two levels: Documentation: `docs/servers/transforms/transforms.mdx`, `docs/servers/visibility.mdx` -### ResourcesAsTools and PromptsAsTools +#### ResourcesAsTools and PromptsAsTools These transforms expose resources and prompts as tools for clients that only support the tools protocol. Each transform generates two tools that provide listing and access functionality. @@ -201,7 +219,7 @@ Documentation: `docs/servers/transforms/resources-as-tools.mdx`, `docs/servers/t --- -## Session-Scoped State +### Session-Scoped State v3.0 changes context state from request-scoped to session-scoped. State now persists across multiple tool calls within the same MCP session. @@ -232,7 +250,7 @@ Documentation: `docs/servers/context.mdx` --- -## Visibility System +### Visibility System Components can be enabled/disabled using the visibility system. Each `enable()` or `disable()` call adds a stateless Visibility transform that marks components via internal metadata. Later transforms override earlier ones. @@ -263,7 +281,7 @@ Works at both server and provider level. Supports: - **Override semantics**: Later transforms override earlier marks (enable after disable = enabled) - **Transform ordering**: Visibility transforms are injected at the point you call them, so component state is known -### Per-Session Visibility +#### Per-Session Visibility Server-level visibility changes affect all connected clients. For per-session control, use `Context` methods that apply rules only to the current session ([#2917](https://github.com/jlowin/fastmcp/pull/2917)): @@ -304,7 +322,7 @@ Documentation: `docs/servers/visibility.mdx` --- -## Component Versioning +### Component Versioning v3.0 introduces versioning support for tools, resources, and prompts. Components can declare a version, and when multiple versions of the same component exist, the highest version is automatically exposed to clients. @@ -422,11 +440,11 @@ The `@` is always present (even for unversioned components) to enable unambiguou --- -## Type-Safe Canonical Results +### Type-Safe Canonical Results v3.0 introduces type-safe result classes that provide explicit control over component responses while supporting MCP runtime metadata: `ToolResult` ([#2736](https://github.com/jlowin/fastmcp/pull/2736)), `ResourceResult` ([#2734](https://github.com/jlowin/fastmcp/pull/2734)), and `PromptResult` ([#2738](https://github.com/jlowin/fastmcp/pull/2738)). -### ToolResult +#### ToolResult `ToolResult` (`src/fastmcp/tools/tool.py:79`) provides structured tool responses: @@ -447,7 +465,7 @@ Fields: - `structured_content`: Dict matching tool's output schema - `meta`: Runtime metadata passed to MCP as `_meta` -### ResourceResult +#### ResourceResult `ResourceResult` (`src/fastmcp/resources/resource.py:117`) provides structured resource responses: @@ -467,7 +485,7 @@ def get_items() -> ResourceResult: Accepts strings, bytes, or `list[ResourceContent]` for flexible content handling. -### PromptResult +#### PromptResult `PromptResult` (`src/fastmcp/prompts/prompt.py:109`) provides structured prompt responses: @@ -487,7 +505,7 @@ def conversation() -> PromptResult: --- -## Background Tasks (SEP-1686) +### Background Tasks (SEP-1686) v3.0 implements MCP SEP-1686 for background task execution via Docket integration. @@ -520,7 +538,7 @@ Requires Docket server for task scheduling and result polling. --- -## Decorators Return Functions +### Decorators Return Functions v3.0 changes what decorators (`@tool`, `@resource`, `@prompt`) return ([#2856](https://github.com/jlowin/fastmcp/pull/2856)). Decorators now return the original function unchanged, rather than transforming it into a component object. @@ -552,7 +570,7 @@ Environment variable: `FASTMCP_DECORATOR_MODE=object` --- -## CLI Auto-Reload +### CLI Auto-Reload The `--reload` flag enables file watching with automatic server restarts for development ([#2816](https://github.com/jlowin/fastmcp/pull/2816)). @@ -581,7 +599,7 @@ fastmcp dev server.py # Includes --reload by default --- -## Component Authorization +### Component Authorization v3.0 introduces callable-based authorization for tools, resources, and prompts ([#2855](https://github.com/jlowin/fastmcp/pull/2855)). @@ -634,7 +652,7 @@ STDIO transport bypasses all auth checks (no OAuth concept). --- -## MCP Apps (SDK Compatibility) +### MCP Apps (SDK Compatibility) v3.0 adds Phase 1 support for [MCP Apps](https://modelcontextprotocol.io/specification/2025-06-18/server/apps) — the spec extension that lets MCP servers deliver interactive UIs via sandboxed iframes. Phase 1 is SDK compatibility only: extension negotiation, typed UI metadata on tools and resources, and the `ui://` resource scheme. No component DSL, renderer, or `FastMCPApp` class yet — those are future phases. @@ -698,7 +716,7 @@ Implementation: `src/fastmcp/server/apps.py` (models and constants), with integr --- -## FileSystemProvider +### FileSystemProvider v3.0 introduces `FileSystemProvider`, a fundamentally different approach to organizing MCP servers. Instead of importing a server instance and decorating functions with `@server.tool`, you use standalone decorators in separate files and let the provider discover them. @@ -736,7 +754,7 @@ Documentation: [FileSystemProvider](/servers/providers/filesystem) --- -## SkillsProvider +### SkillsProvider v3.0 introduces `SkillsProvider` for exposing agent skills as MCP resources ([#2944](https://github.com/jlowin/fastmcp/pull/2944)). Skills are directories containing instructions and supporting files that teach AI assistants how to perform tasks—used by Claude Code, Cursor, VS Code Copilot, and other AI coding tools. @@ -779,7 +797,7 @@ Documentation: [Skills Provider](/servers/providers/skills) --- -## OpenTelemetry Tracing +### OpenTelemetry Tracing v3.0 adds OpenTelemetry instrumentation for observability into server and client operations ([#2869](https://github.com/jlowin/fastmcp/pull/2869)). @@ -807,7 +825,7 @@ Documentation: [Telemetry](/servers/telemetry) --- -## Pagination +### Pagination v3.0 adds pagination support for list operations when servers expose many components ([#2903](https://github.com/jlowin/fastmcp/pull/2903)). @@ -833,7 +851,7 @@ Documentation: [Pagination](/servers/pagination) --- -## Composable Lifespans +### Composable Lifespans Lifespans can be combined with the `|` operator for modular setup/teardown ([#2828](https://github.com/jlowin/fastmcp/pull/2828)): @@ -874,7 +892,7 @@ Documentation: [Lifespan](/servers/lifespan) --- -## Tool Timeout +### Tool Timeout Tools can limit foreground execution time with a `timeout` parameter ([#2872](https://github.com/jlowin/fastmcp/pull/2872)): @@ -891,7 +909,7 @@ Note: This timeout applies to foreground execution only. Background tasks (`task --- -## PingMiddleware +### PingMiddleware Sends periodic server-to-client pings to keep long-lived connections alive ([#2838](https://github.com/jlowin/fastmcp/pull/2838)): @@ -907,7 +925,7 @@ The middleware starts a background ping task on first message from each session, --- -## Context.transport Property +### Context.transport Property Tools can detect which transport is active ([#2850](https://github.com/jlowin/fastmcp/pull/2850)): @@ -927,7 +945,7 @@ Returns `Literal["stdio", "sse", "streamable-http"]` when running, or `None` out --- -## Automatic Threadpool for Sync Functions +### Automatic Threadpool for Sync Functions Synchronous tools, resources, and prompts now automatically run in a threadpool, preventing event loop blocking during concurrent requests ([#2865](https://github.com/jlowin/fastmcp/pull/2865)): @@ -944,7 +962,7 @@ Three concurrent calls now execute in parallel (~10s) rather than sequentially ( --- -## CLI Update Notifications +### CLI Update Notifications The CLI notifies users when a newer FastMCP version is available on PyPI ([#2840](https://github.com/jlowin/fastmcp/pull/2840)). @@ -957,11 +975,11 @@ The CLI notifies users when a newer FastMCP version is available on PyPI ([#2840 --- -## Deprecated Features +### Deprecated Features These emit deprecation warnings but continue to work. -### Mount Prefix Parameter +#### Mount Prefix Parameter The `prefix` parameter for `mount()` renamed to `namespace`: @@ -973,7 +991,7 @@ main.mount(subserver, prefix="api") main.mount(subserver, namespace="api") ``` -### Tag Filtering Init Parameters +#### Tag Filtering Init Parameters `FastMCP(include_tags=..., exclude_tags=...)` deprecated. Use `enable()`/`disable()` methods: @@ -986,11 +1004,11 @@ mcp = FastMCP("server") mcp.disable(tags={"internal"}) ``` -### Tool Serializer Parameter +#### Tool Serializer Parameter The `tool_serializer` parameter on `FastMCP` is deprecated. Return `ToolResult` for explicit serialization control. -### Tool Transformation Methods +#### Tool Transformation Methods `add_tool_transformation()`, `remove_tool_transformation()`, and `tool_transformations` constructor parameter are deprecated. Use `add_transform(ToolTransform({...}))` instead: @@ -1005,13 +1023,13 @@ mcp.add_transform(ToolTransform({"name": config})) --- -## Breaking Changes +### Breaking Changes -### WSTransport Removed +#### WSTransport Removed The deprecated `WSTransport` client transport has been removed ([#2826](https://github.com/jlowin/fastmcp/pull/2826)). Use `StreamableHttpTransport` instead. -### Decorators Return Functions +#### Decorators Return Functions Decorators (`@tool`, `@resource`, `@prompt`) now return the original function instead of component objects. Code that treats the decorated function as a `FunctionTool`, `FunctionResource`, or `FunctionPrompt` will break. @@ -1035,7 +1053,7 @@ greet("World") # "Hello, World!" Set `FASTMCP_DECORATOR_MODE=object` or `fastmcp.settings.decorator_mode = "object"` for v2 behavior. -### Component Enable/Disable Moved to Server/Provider +#### Component Enable/Disable Moved to Server/Provider The `enabled` field and `enable()`/`disable()` methods removed from component objects: @@ -1048,7 +1066,7 @@ tool.disable() server.disable(names={"my_tool"}, components=["tool"]) ``` -### Component Lookup Methods +#### Component Lookup Methods Server lookup and listing methods have updated signatures: @@ -1065,7 +1083,7 @@ tools = await server.get_tools() tool = next((t for t in tools if t.name == "my_tool"), None) ``` -### Prompt Return Types +#### Prompt Return Types Prompt functions now use `Message` instead of `mcp.types.PromptMessage`: @@ -1085,7 +1103,7 @@ def my_prompt() -> Message: return Message("Hello") # role defaults to "user" ``` -### Auth Provider Environment Variables Removed +#### Auth Provider Environment Variables Removed Auth providers no longer auto-load from environment variables ([#2752](https://github.com/jlowin/fastmcp/pull/2752)): @@ -1103,13 +1121,13 @@ auth = GitHubProvider( See `docs/development/v3-notes/auth-provider-env-vars.mdx` for rationale. -### Server Banner Environment Variable +#### Server Banner Environment Variable `FASTMCP_SHOW_CLI_BANNER` → `FASTMCP_SHOW_SERVER_BANNER` ([#2771](https://github.com/jlowin/fastmcp/pull/2771)) Now applies to all server startup methods, not just the CLI. -### Context State Methods Are Async +#### Context State Methods Are Async `ctx.set_state()` and `ctx.get_state()` are now async and session-scoped: