fastmcp 2.7.1__py3-none-any.whl → 2.8.1__py3-none-any.whl

fastmcp/resources/template.py

@@ -5,12 +5,11 @@ from __future__ import annotations
 import inspect
 import re
 from collections.abc import Callable
-from typing import Annotated, Any
+from typing import Any
 from urllib.parse import unquote
 
 from mcp.types import ResourceTemplate as MCPResourceTemplate
 from pydantic import (
-    BeforeValidator,
     Field,
     field_validator,
     validate_call,
@@ -18,10 +17,9 @@ from pydantic import (
 
 from fastmcp.resources.types import Resource
 from fastmcp.server.dependencies import get_context
+from fastmcp.utilities.components import FastMCPComponent
 from fastmcp.utilities.json_schema import compress_schema
 from fastmcp.utilities.types import (
-    FastMCPBaseModel,
-    _convert_set_defaults,
     find_kwarg_by_type,
     get_cached_typeadapter,
 )
@@ -51,17 +49,12 @@ def match_uri_template(uri: str, uri_template: str) -> dict[str, str] | None:
     return None
 
 
-class ResourceTemplate(FastMCPBaseModel):
+class ResourceTemplate(FastMCPComponent):
     """A template for dynamically creating resources."""
 
     uri_template: str = Field(
         description="URI template with parameters (e.g. weather://{city}/current)"
     )
-    name: str = Field(description="Name of the resource")
-    description: str | None = Field(description="Description of what the resource does")
-    tags: Annotated[set[str], BeforeValidator(_convert_set_defaults)] = Field(
-        default_factory=set, description="Tags for the resource"
-    )
     mime_type: str = Field(
         default="text/plain", description="MIME type of the resource content"
     )
@@ -77,6 +70,7 @@ class ResourceTemplate(FastMCPBaseModel):
         description: str | None = None,
         mime_type: str | None = None,
         tags: set[str] | None = None,
+        enabled: bool | None = None,
     ) -> FunctionResourceTemplate:
         return FunctionResourceTemplate.from_function(
             fn=fn,
@@ -85,6 +79,7 @@ class ResourceTemplate(FastMCPBaseModel):
             description=description,
             mime_type=mime_type,
             tags=tags,
+            enabled=enabled,
         )
 
     @field_validator("mime_type", mode="before")
@@ -120,14 +115,9 @@ class ResourceTemplate(FastMCPBaseModel):
             description=self.description,
             mime_type=self.mime_type,
             tags=self.tags,
+            enabled=self.enabled,
         )
 
-    def __eq__(self, other: object) -> bool:
-        if type(self) is not type(other):
-            return False
-        assert isinstance(other, type(self))
-        return self.model_dump() == other.model_dump()
-
     def to_mcp_template(self, **overrides: Any) -> MCPResourceTemplate:
         """Convert the resource template to an MCPResourceTemplate."""
         kwargs = {
@@ -168,6 +158,7 @@ class FunctionResourceTemplate(ResourceTemplate):
         description: str | None = None,
         mime_type: str | None = None,
         tags: set[str] | None = None,
+        enabled: bool | None = None,
     ) -> FunctionResourceTemplate:
         """Create a template from a function."""
         from fastmcp.server.context import Context
@@ -250,4 +241,5 @@ class FunctionResourceTemplate(ResourceTemplate):
             fn=fn,
             parameters=parameters,
             tags=tags or set(),
+            enabled=enabled if enabled is not None else True,
         )

fastmcp/server/auth/providers/bearer_env.py

@@ -1,13 +1,10 @@
+from types import EllipsisType
+
 from pydantic_settings import BaseSettings, SettingsConfigDict
 
 from fastmcp.server.auth.providers.bearer import BearerAuthProvider
 
 
-# Sentinel object to indicate that a setting is not set
-class _NotSet:
-    pass
-
-
 class EnvBearerAuthProviderSettings(BaseSettings):
     """Settings for the BearerAuthProvider."""
 
@@ -33,11 +30,11 @@ class EnvBearerAuthProvider(BearerAuthProvider):
 
     def __init__(
         self,
-        public_key: str | None | type[_NotSet] = _NotSet,
-        jwks_uri: str | None | type[_NotSet] = _NotSet,
-        issuer: str | None | type[_NotSet] = _NotSet,
-        audience: str | None | type[_NotSet] = _NotSet,
-        required_scopes: list[str] | None | type[_NotSet] = _NotSet,
+        public_key: str | None | EllipsisType = ...,
+        jwks_uri: str | None | EllipsisType = ...,
+        issuer: str | None | EllipsisType = ...,
+        audience: str | None | EllipsisType = ...,
+        required_scopes: list[str] | None | EllipsisType = ...,
     ):
         """
         Initialize the provider.
@@ -57,6 +54,6 @@ class EnvBearerAuthProvider(BearerAuthProvider):
             "required_scopes": required_scopes,
         }
         settings = EnvBearerAuthProviderSettings(
-            **{k: v for k, v in kwargs.items() if v is not _NotSet}
+            **{k: v for k, v in kwargs.items() if v is not ...}
         )
         super().__init__(**settings.model_dump())

fastmcp/server/auth/providers/in_memory.py

@@ -184,7 +184,7 @@ class InMemoryOAuthProvider(OAuthProvider):
 
         return OAuthToken(
             access_token=access_token_value,
-            token_type="bearer",
+            token_type="Bearer",
             expires_in=DEFAULT_ACCESS_TOKEN_EXPIRY_SECONDS,
             refresh_token=refresh_token_value,
             scope=" ".join(authorization_code.scopes),
@@ -254,7 +254,7 @@ class InMemoryOAuthProvider(OAuthProvider):
 
         return OAuthToken(
             access_token=new_access_token_value,
-            token_type="bearer",
+            token_type="Bearer",
             expires_in=DEFAULT_ACCESS_TOKEN_EXPIRY_SECONDS,
             refresh_token=new_refresh_token_value,
             scope=" ".join(scopes),

fastmcp/server/context.py

@@ -11,7 +11,6 @@ from mcp.server.lowlevel.helper_types import ReadResourceContents
 from mcp.shared.context import RequestContext
 from mcp.types import (
     CreateMessageResult,
-    ImageContent,
     ModelHint,
     ModelPreferences,
     Root,
@@ -22,8 +21,10 @@ from pydantic.networks import AnyUrl
 from starlette.requests import Request
 
 import fastmcp.server.dependencies
+from fastmcp import settings
 from fastmcp.server.server import FastMCP
 from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.types import MCPContent
 
 logger = get_logger(__name__)
 
@@ -203,7 +204,7 @@ class Context:
         temperature: float | None = None,
         max_tokens: int | None = None,
         model_preferences: ModelPreferences | str | list[str] | None = None,
-    ) -> TextContent | ImageContent:
+    ) -> MCPContent:
         """
         Send a sampling request to the client and await the response.
 
@@ -242,14 +243,15 @@ class Context:
     def get_http_request(self) -> Request:
         """Get the active starlette request."""
 
-        # Deprecation warning, added in FastMCP 2.2.11
-        warnings.warn(
-            "Context.get_http_request() is deprecated and will be removed in a future version. "
-            "Use get_http_request() from fastmcp.server.dependencies instead. "
-            "See https://gofastmcp.com/patterns/http-requests for more details.",
-            DeprecationWarning,
-            stacklevel=2,
-        )
+        # Deprecated in 2.2.11
+        if settings.deprecation_warnings:
+            warnings.warn(
+                "Context.get_http_request() is deprecated and will be removed in a future version. "
+                "Use get_http_request() from fastmcp.server.dependencies instead. "
+                "See https://gofastmcp.com/patterns/http-requests for more details.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
 
         return fastmcp.server.dependencies.get_http_request()
 

fastmcp/server/openapi.py

@@ -13,9 +13,10 @@ from re import Pattern
 from typing import TYPE_CHECKING, Any, Literal
 
 import httpx
-from mcp.types import EmbeddedResource, ImageContent, TextContent, ToolAnnotations
+from mcp.types import ToolAnnotations
 from pydantic.networks import AnyUrl
 
+import fastmcp
 from fastmcp.exceptions import ToolError
 from fastmcp.resources import Resource, ResourceTemplate
 from fastmcp.server.dependencies import get_http_headers
@@ -28,6 +29,7 @@ from fastmcp.utilities.openapi import (
     _combine_schemas,
     format_description_with_responses,
 )
+from fastmcp.utilities.types import MCPContent
 
 if TYPE_CHECKING:
     from fastmcp.server import Context
@@ -103,41 +105,56 @@ class RouteType(enum.Enum):
     IGNORE = "IGNORE"
 
 
-@dataclass
+@dataclass(kw_only=True)
 class RouteMap:
     """Mapping configuration for HTTP routes to FastMCP component types."""
 
     methods: list[HttpMethod] | Literal["*"] = field(default="*")
     pattern: Pattern[str] | str = field(default=r".*")
-    mcp_type: MCPType | None = field(default=None)
     route_type: RouteType | MCPType | None = field(default=None)
-    tags: set[str] = field(default_factory=set)
+    tags: set[str] = field(
+        default_factory=set,
+        metadata={"description": "A set of tags to match. All tags must match."},
+    )
+    mcp_type: MCPType | None = field(
+        default=None,
+        metadata={"description": "The type of FastMCP component to create."},
+    )
+    mcp_tags: set[str] = field(
+        default_factory=set,
+        metadata={
+            "description": "A set of tags to apply to the generated FastMCP component."
+        },
+    )
 
     def __post_init__(self):
         """Validate and process the route map after initialization."""
         # Handle backward compatibility for route_type, deprecated in 2.5.0
         if self.mcp_type is None and self.route_type is not None:
-            warnings.warn(
-                "The 'route_type' parameter is deprecated and will be removed in a future version. "
-                "Use 'mcp_type' instead with the appropriate MCPType value.",
-                DeprecationWarning,
-                stacklevel=2,
-            )
-            if isinstance(self.route_type, RouteType):
+            if fastmcp.settings.deprecation_warnings:
                 warnings.warn(
-                    "The RouteType class is deprecated and will be removed in a future version. "
-                    "Use MCPType instead.",
+                    "The 'route_type' parameter is deprecated and will be removed in a future version. "
+                    "Use 'mcp_type' instead with the appropriate MCPType value.",
                     DeprecationWarning,
                     stacklevel=2,
                 )
+            if isinstance(self.route_type, RouteType):
+                if fastmcp.settings.deprecation_warnings:
+                    warnings.warn(
+                        "The RouteType class is deprecated and will be removed in a future version. "
+                        "Use MCPType instead.",
+                        DeprecationWarning,
+                        stacklevel=2,
+                    )
             # Check for the deprecated IGNORE value
             if self.route_type == RouteType.IGNORE:
-                warnings.warn(
-                    "RouteType.IGNORE is deprecated and will be removed in a future version. "
-                    "Use MCPType.EXCLUDE instead.",
-                    DeprecationWarning,
-                    stacklevel=2,
-                )
+                if fastmcp.settings.deprecation_warnings:
+                    warnings.warn(
+                        "RouteType.IGNORE is deprecated and will be removed in a future version. "
+                        "Use MCPType.EXCLUDE instead.",
+                        DeprecationWarning,
+                        stacklevel=2,
+                    )
 
             # Convert from RouteType to MCPType if needed
             if isinstance(self.route_type, RouteType):
@@ -155,23 +172,17 @@ class RouteMap:
             self.route_type = self.mcp_type
 
 
-# Default route mappings as a list, where order determines priority
+# Default route mapping: all routes become tools.
+# Users can provide custom route_maps to override this behavior.
 DEFAULT_ROUTE_MAPPINGS = [
-    # GET requests with path parameters go to ResourceTemplate
-    RouteMap(
-        methods=["GET"], pattern=r".*\{.*\}.*", mcp_type=MCPType.RESOURCE_TEMPLATE
-    ),
-    # GET requests without path parameters go to Resource
-    RouteMap(methods=["GET"], pattern=r".*", mcp_type=MCPType.RESOURCE),
-    # All other HTTP methods go to Tool
-    RouteMap(methods="*", pattern=r".*", mcp_type=MCPType.TOOL),
+    RouteMap(mcp_type=MCPType.TOOL),
 ]
 
 
 def _determine_route_type(
     route: openapi.HTTPRoute,
     mappings: list[RouteMap],
-) -> MCPType:
+) -> RouteMap:
     """
     Determines the FastMCP component type based on the route and mappings.
 
@@ -180,7 +191,7 @@ def _determine_route_type(
         mappings: List of RouteMap objects in priority order
 
     Returns:
-        MCPType for this route
+        The RouteMap that matches the route, or a catchall "Tool" RouteMap if no match is found.
     """
     # Check mappings in priority order (first match wins)
     for route_map in mappings:
@@ -207,10 +218,10 @@ def _determine_route_type(
                 logger.debug(
                     f"Route {route.method} {route.path} matched mapping to {route_map.mcp_type.name}"
                 )
-                return route_map.mcp_type
+                return route_map
 
     # Default fallback
-    return MCPType.TOOL
+    return RouteMap(mcp_type=MCPType.TOOL)
 
 
 class OpenAPITool(Tool):
@@ -223,19 +234,17 @@ class OpenAPITool(Tool):
         name: str,
         description: str,
         parameters: dict[str, Any],
-        tags: set[str] = set(),
+        tags: set[str] | None = None,
         timeout: float | None = None,
         annotations: ToolAnnotations | None = None,
-        exclude_args: list[str] | None = None,
         serializer: Callable[[Any], str] | None = None,
     ):
         super().__init__(
             name=name,
             description=description,
             parameters=parameters,
-            tags=tags,
+            tags=tags or set(),
             annotations=annotations,
-            exclude_args=exclude_args,
             serializer=serializer,
         )
         self._client = client
@@ -246,9 +255,7 @@ class OpenAPITool(Tool):
         """Custom representation to prevent recursion errors when printing."""
         return f"OpenAPITool(name={self.name!r}, method={self._route.method}, path={self._route.path})"
 
-    async def run(
-        self, arguments: dict[str, Any]
-    ) -> list[TextContent | ImageContent | EmbeddedResource]:
+    async def run(self, arguments: dict[str, Any]) -> list[MCPContent]:
         """Execute the HTTP request based on the route configuration."""
 
         # Prepare URL
@@ -688,6 +695,7 @@ class FastMCPOpenAPI(FastMCP):
         route_map_fn: RouteMapFn | None = None,
         mcp_component_fn: ComponentFn | None = None,
         mcp_names: dict[str, str] | None = None,
+        tags: set[str] | None = None,
         timeout: float | None = None,
         **settings: Any,
     ):
@@ -710,6 +718,8 @@ class FastMCPOpenAPI(FastMCP):
                 operationId up to the first double underscore. If no operationId exists,
                 falls back to slugified summary or path-based naming.
                 All names are truncated to 56 characters maximum.
+            tags: Optional set of tags to add to all components. Components always receive any tags
+                from the route.
             timeout: Optional timeout (in seconds) for all requests
             **settings: Additional settings for FastMCP
         """
@@ -717,9 +727,7 @@ class FastMCPOpenAPI(FastMCP):
 
         self._client = client
         self._timeout = timeout
-        self._route_map_fn = route_map_fn
         self._mcp_component_fn = mcp_component_fn
-        self._mcp_names = mcp_names or {}
 
         # Keep track of names to detect collisions
         self._used_names = {
@@ -735,12 +743,16 @@ class FastMCPOpenAPI(FastMCP):
         route_maps = (route_maps or []) + DEFAULT_ROUTE_MAPPINGS
         for route in http_routes:
             # Determine route type based on mappings or default rules
-            route_type = _determine_route_type(route, route_maps)
+            route_map = _determine_route_type(route, route_maps)
+
+            # TODO: remove this once RouteType is removed and mcp_type is typed as MCPType without | None
+            assert route_map.mcp_type is not None
+            route_type = route_map.mcp_type
 
             # Call route_map_fn if provided
-            if self._route_map_fn is not None:
+            if route_map_fn is not None:
                 try:
-                    result = self._route_map_fn(route, route_type)
+                    result = route_map_fn(route, route_type)
                     if result is not None:
                         route_type = result
                         logger.debug(
@@ -754,29 +766,32 @@ class FastMCPOpenAPI(FastMCP):
                     )
 
             # Generate a default name from the route
-            component_name = self._generate_default_name(route, route_type)
+            component_name = self._generate_default_name(route, mcp_names)
+
+            route_tags = set(route.tags) | route_map.mcp_tags | (tags or set())
 
             if route_type == MCPType.TOOL:
-                self._create_openapi_tool(route, component_name)
+                self._create_openapi_tool(route, component_name, tags=route_tags)
             elif route_type == MCPType.RESOURCE:
-                self._create_openapi_resource(route, component_name)
+                self._create_openapi_resource(route, component_name, tags=route_tags)
             elif route_type == MCPType.RESOURCE_TEMPLATE:
-                self._create_openapi_template(route, component_name)
+                self._create_openapi_template(route, component_name, tags=route_tags)
             elif route_type == MCPType.EXCLUDE:
                 logger.info(f"Excluding route: {route.method} {route.path}")
 
         logger.info(f"Created FastMCP OpenAPI server with {len(http_routes)} routes")
 
     def _generate_default_name(
-        self, route: openapi.HTTPRoute, mcp_type: MCPType
+        self, route: openapi.HTTPRoute, mcp_names_map: dict[str, str] | None = None
     ) -> str:
         """Generate a default name from the route using the configured strategy."""
         name = ""
+        mcp_names_map = mcp_names_map or {}
 
         # First check if there's a custom mapping for this operationId
         if route.operation_id:
-            if route.operation_id in self._mcp_names:
-                name = self._mcp_names[route.operation_id]
+            if route.operation_id in mcp_names_map:
+                name = mcp_names_map[route.operation_id]
             else:
                 # If there's a double underscore in the operationId, use the first part
                 name = route.operation_id.split("__")[0]
@@ -821,7 +836,12 @@ class FastMCPOpenAPI(FastMCP):
 
         return new_name
 
-    def _create_openapi_tool(self, route: openapi.HTTPRoute, name: str):
+    def _create_openapi_tool(
+        self,
+        route: openapi.HTTPRoute,
+        name: str,
+        tags: set[str],
+    ):
         """Creates and registers an OpenAPITool with enhanced description."""
         combined_schema = _combine_schemas(route)
 
@@ -848,7 +868,7 @@ class FastMCPOpenAPI(FastMCP):
             name=tool_name,
             description=enhanced_description,
             parameters=combined_schema,
-            tags=set(route.tags or []),
+            tags=set(route.tags or []) | tags,
             timeout=self._timeout,
         )
 
@@ -869,7 +889,12 @@ class FastMCPOpenAPI(FastMCP):
             f"Registered TOOL: {tool_name} ({route.method} {route.path}) with tags: {route.tags}"
         )
 
-    def _create_openapi_resource(self, route: openapi.HTTPRoute, name: str):
+    def _create_openapi_resource(
+        self,
+        route: openapi.HTTPRoute,
+        name: str,
+        tags: set[str],
+    ):
         """Creates and registers an OpenAPIResource with enhanced description."""
         # Get a unique resource name
         resource_name = self._get_unique_name(name, "resource")
@@ -893,7 +918,7 @@ class FastMCPOpenAPI(FastMCP):
             uri=resource_uri,
             name=resource_name,
             description=enhanced_description,
-            tags=set(route.tags or []),
+            tags=set(route.tags or []) | tags,
             timeout=self._timeout,
         )
 
@@ -914,7 +939,12 @@ class FastMCPOpenAPI(FastMCP):
             f"Registered RESOURCE: {resource_uri} ({route.method} {route.path}) with tags: {route.tags}"
         )
 
-    def _create_openapi_template(self, route: openapi.HTTPRoute, name: str):
+    def _create_openapi_template(
+        self,
+        route: openapi.HTTPRoute,
+        name: str,
+        tags: set[str],
+    ):
         """Creates and registers an OpenAPIResourceTemplate with enhanced description."""
         # Get a unique template name
         template_name = self._get_unique_name(name, "resource_template")
@@ -967,7 +997,7 @@ class FastMCPOpenAPI(FastMCP):
             name=template_name,
             description=enhanced_description,
             parameters=template_params_schema,
-            tags=set(route.tags or []),
+            tags=set(route.tags or []) | tags,
             timeout=self._timeout,
         )
 

fastmcp/server/proxy.py

@@ -9,10 +9,7 @@ from mcp.shared.exceptions import McpError
 from mcp.types import (
     METHOD_NOT_FOUND,
     BlobResourceContents,
-    EmbeddedResource,
     GetPromptResult,
-    ImageContent,
-    TextContent,
     TextResourceContents,
 )
 from pydantic.networks import AnyUrl
@@ -25,6 +22,7 @@ from fastmcp.server.context import Context
 from fastmcp.server.server import FastMCP
 from fastmcp.tools.tool import Tool
 from fastmcp.utilities.logging import get_logger
+from fastmcp.utilities.types import MCPContent
 
 if TYPE_CHECKING:
     from fastmcp.server import Context
@@ -50,7 +48,7 @@ class ProxyTool(Tool):
         self,
         arguments: dict[str, Any],
         context: Context | None = None,
-    ) -> list[TextContent | ImageContent | EmbeddedResource]:
+    ) -> list[MCPContent]:
         # the client context manager will swallow any exceptions inside a TaskGroup
         # so we return the raw result and raise an exception ourselves
         async with self._client:
@@ -186,8 +184,10 @@ class FastMCPProxy(FastMCP):
                 else:
                     raise e
             for tool in client_tools:
-                tool_proxy = await ProxyTool.from_client(self.client, tool)
-                tools[tool_proxy.name] = tool_proxy
+                # don't overwrite tools defined in the server
+                if tool.name not in tools:
+                    tool_proxy = await ProxyTool.from_client(self.client, tool)
+                    tools[tool_proxy.name] = tool_proxy
 
         return tools
 
@@ -203,8 +203,12 @@ class FastMCPProxy(FastMCP):
                 else:
                     raise e
             for resource in client_resources:
-                resource_proxy = await ProxyResource.from_client(self.client, resource)
-                resources[str(resource_proxy.uri)] = resource_proxy
+                # don't overwrite resources defined in the server
+                if str(resource.uri) not in resources:
+                    resource_proxy = await ProxyResource.from_client(
+                        self.client, resource
+                    )
+                    resources[str(resource_proxy.uri)] = resource_proxy
 
         return resources
 
@@ -220,8 +224,12 @@ class FastMCPProxy(FastMCP):
                 else:
                     raise e
             for template in client_templates:
-                template_proxy = await ProxyTemplate.from_client(self.client, template)
-                templates[template_proxy.uri_template] = template_proxy
+                # don't overwrite templates defined in the server
+                if template.uriTemplate not in templates:
+                    template_proxy = await ProxyTemplate.from_client(
+                        self.client, template
+                    )
+                    templates[template_proxy.uri_template] = template_proxy
 
         return templates
 
@@ -237,24 +245,25 @@ class FastMCPProxy(FastMCP):
                 else:
                     raise e
             for prompt in client_prompts:
-                prompt_proxy = await ProxyPrompt.from_client(self.client, prompt)
-                prompts[prompt_proxy.name] = prompt_proxy
+                # don't overwrite prompts defined in the server
+                if prompt.name not in prompts:
+                    prompt_proxy = await ProxyPrompt.from_client(self.client, prompt)
+                    prompts[prompt_proxy.name] = prompt_proxy
+
         return prompts
 
-    async def _mcp_call_tool(
-        self, key: str, arguments: dict[str, Any]
-    ) -> list[TextContent | ImageContent | EmbeddedResource]:
+    async def _call_tool(self, key: str, arguments: dict[str, Any]) -> list[MCPContent]:
         try:
-            result = await super()._mcp_call_tool(key, arguments)
+            result = await super()._call_tool(key, arguments)
             return result
         except NotFoundError:
             async with self.client:
                 result = await self.client.call_tool(key, arguments)
             return result
 
-    async def _mcp_read_resource(self, uri: AnyUrl | str) -> list[ReadResourceContents]:
+    async def _read_resource(self, uri: AnyUrl | str) -> list[ReadResourceContents]:
         try:
-            result = await super()._mcp_read_resource(uri)
+            result = await super()._read_resource(uri)
             return result
         except NotFoundError:
             async with self.client:
@@ -270,11 +279,11 @@ class FastMCPProxy(FastMCP):
                 ReadResourceContents(content=content, mime_type=resource[0].mimeType)
             ]
 
-    async def _mcp_get_prompt(
+    async def _get_prompt(
         self, name: str, arguments: dict[str, Any] | None = None
     ) -> GetPromptResult:
         try:
-            result = await super()._mcp_get_prompt(name, arguments)
+            result = await super()._get_prompt(name, arguments)
             return result
         except NotFoundError:
             async with self.client: