mirror of
https://github.com/PrefectHQ/fastmcp.git
synced 2026-08-09 07:09:11 +02:00
docs: separate beta1 and beta2 features in v3-features
- Add H2 section for 3.0.0beta2 with expanded reload feature - Add H2 section for 3.0.0beta1 - Bump all beta1 features from H2 to H3 - Bump all subsections from H3 to H4 Co-authored-by: Jeremiah Lowin <jlowin@users.noreply.github.com>
This commit is contained in:
claude[bot]
parent
d52534ae32
commit
2d6db48ac8
1 changed files with 54 additions and 44 deletions
|
|
@ -4,7 +4,17 @@ title: v3.0 Feature Tracking
|
|||
|
||||
This document tracks major features in FastMCP v3.0 for release notes preparation.
|
||||
|
||||
## Provider-Based Architecture
|
||||
## 3.0.0beta2
|
||||
|
||||
### Expanded CLI Auto-Reload
|
||||
|
||||
The `--reload` flag now watches a variety of file types beyond Python files ([#3028](https://github.com/jlowin/fastmcp/pull/3028)), enabling seamless development for MCP apps that include frontend bundles. The implementation automatically detects changes to JavaScript, TypeScript, CSS, HTML, and other common web development file types, triggering server restarts when needed.
|
||||
|
||||
---
|
||||
|
||||
## 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 +36,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 +54,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 +65,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 +85,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 +108,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 +161,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 +211,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 +242,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 +273,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 +314,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 +432,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 +457,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 +477,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 +497,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 +530,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 +562,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 +591,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 +644,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 +708,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 +746,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 +789,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 +817,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 +843,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 +884,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 +901,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 +917,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 +937,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 +954,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 +967,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 +983,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 +996,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 +1015,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 +1045,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 +1058,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 +1075,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 +1095,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 +1113,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:
|
||||
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue