π The fast, Pythonic way to build MCP servers and clients.
Make deprecation warnings visible and controllable
Jeremiah Lowine82cd9f74228
diff --git a/src/fastmcp/__init__.py b/src/fastmcp/__init__.pyindex 3e706880d..8685ee767 100644--- a/src/fastmcp/__init__.py+++ b/src/fastmcp/__init__.py@@ -25,7 +25,6 @@ __all__ = []+# ensure deprecation warnings are displayedby defaultif settings.deprecation_warnings:warnings.simplefilter("default", DeprecationWarning)-else:- warnings.simplefilter("ignore", DeprecationWarning)diff --git a/src/fastmcp/client/transports.py b/src/fastmcp/client/transports.pyindex 162c82844..778c58447 100644--- a/src/fastmcp/client/transports.py+++ b/src/fastmcp/client/transports.py@@ -20,6 +20,7 @@ from mcp.shared.memory import create_client_server_memory_streamsfrom pydantic import AnyUrlfrom typing_extensions import Unpack+import fastmcpfrom fastmcp.client.auth.bearer import BearerAuthfrom fastmcp.client.auth.oauth import OAuthfrom fastmcp.server.dependencies import get_http_headers@@ -109,11 +110,12 @@ class WSTransport(ClientTransport):def __init__(self, url: str | AnyUrl):# we never really used this transport, so it can be removed at any time- warnings.warn(- "WSTransport is a deprecated MCP transport and will be removed in a future version. Use StreamableHttpTransport instead.",- DeprecationWarning,- stacklevel=2,- )+ if fastmcp.settings.deprecation_warnings:+ warnings.warn(+ "WSTransport is a deprecated MCP transport and will be removed in a future version. Use StreamableHttpTransport instead.",+ DeprecationWarning,+ stacklevel=2,+ )if isinstance(url, AnyUrl):url = str(url)if not isinstance(url, str) or not url.startswith("ws"):diff --git a/src/fastmcp/prompts/prompt_manager.py b/src/fastmcp/prompts/prompt_manager.pyindex f2f706c5b..10805f5e6 100644--- a/src/fastmcp/prompts/prompt_manager.py+++ b/src/fastmcp/prompts/prompt_manager.py@@ -60,11 +60,12 @@ class PromptManager:) -> FunctionPrompt:"""Create a prompt from a function."""# deprecated in 2.7.0- warnings.warn(- "PromptManager.add_prompt_from_fn() is deprecated. Use Prompt.from_function() and call add_prompt() instead.",- DeprecationWarning,- stacklevel=2,- )+ if settings.deprecation_warnings:+ warnings.warn(+ "PromptManager.add_prompt_from_fn() is deprecated. Use Prompt.from_function() and call add_prompt() instead.",+ DeprecationWarning,+ stacklevel=2,+ )prompt = FunctionPrompt.from_function(fn, name=name, description=description, tags=tags)diff --git a/src/fastmcp/resources/resource_manager.py b/src/fastmcp/resources/resource_manager.pyindex ed299d0c0..64a11aae1 100644--- a/src/fastmcp/resources/resource_manager.py+++ b/src/fastmcp/resources/resource_manager.py@@ -123,11 +123,12 @@ class ResourceManager:returns the existing resource."""# deprecated in 2.7.0- warnings.warn(- "add_resource_from_fn is deprecated. Use Resource.from_function() and call add_resource() instead.",- DeprecationWarning,- stacklevel=2,- )+ if settings.deprecation_warnings:+ warnings.warn(+ "add_resource_from_fn is deprecated. Use Resource.from_function() and call add_resource() instead.",+ DeprecationWarning,+ stacklevel=2,+ )resource = Resource.from_function(fn=fn,uri=uri,@@ -180,11 +181,12 @@ class ResourceManager:) -> ResourceTemplate:"""Create a template from a function."""# deprecated in 2.7.0- warnings.warn(- "add_template_from_fn is deprecated. Use ResourceTemplate.from_function() and call add_template() instead.",- DeprecationWarning,- stacklevel=2,- )+ if settings.deprecation_warnings:+ warnings.warn(+ "add_template_from_fn is deprecated. Use ResourceTemplate.from_function() and call add_template() instead.",+ DeprecationWarning,+ stacklevel=2,+ )template = ResourceTemplate.from_function(fn,uri_template=uri_template,diff --git a/src/fastmcp/server/context.py b/src/fastmcp/server/context.pyindex 97a05c672..92f725db7 100644--- a/src/fastmcp/server/context.py+++ b/src/fastmcp/server/context.py@@ -22,6 +22,7 @@ from pydantic.networks import AnyUrlfrom starlette.requests import Requestimport fastmcp.server.dependencies+from fastmcp import settingsfrom fastmcp.server.server import FastMCPfrom fastmcp.utilities.logging import get_logger@@ -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()diff --git a/src/fastmcp/server/openapi.py b/src/fastmcp/server/openapi.pyindex 7ee675d8c..315b7bf8d 100644--- a/src/fastmcp/server/openapi.py+++ b/src/fastmcp/server/openapi.py@@ -16,6 +16,7 @@ import httpxfrom mcp.types import EmbeddedResource, ImageContent, TextContent, ToolAnnotationsfrom pydantic.networks import AnyUrl+import fastmcpfrom fastmcp.exceptions import ToolErrorfrom fastmcp.resources import Resource, ResourceTemplatefrom fastmcp.server.dependencies import get_http_headers@@ -129,27 +130,30 @@ class RouteMap:"""Validate and process the route map after initialization."""# Handle backward compatibility for route_type, deprecated in 2.5.0if 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 valueif 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 neededif isinstance(self.route_type, RouteType):diff --git a/src/fastmcp/server/server.py b/src/fastmcp/server/server.pyindex 33a0088e7..b3051c91d 100644--- a/src/fastmcp/server/server.py+++ b/src/fastmcp/server/server.py@@ -242,11 +242,12 @@ class FastMCP(Generic[LifespanResultT]):]:if arg is not None:# Deprecated in 2.8.0- warnings.warn(- f"Providing `{name}` when creating a server is deprecated. Provide it when calling `run` or as a global setting instead.",- DeprecationWarning,- stacklevel=2,- )+ if fastmcp.settings.deprecation_warnings:+ warnings.warn(+ f"Providing `{name}` when creating a server is deprecated. Provide it when calling `run` or as a global setting instead.",+ DeprecationWarning,+ stacklevel=2,+ )deprecated_settings[name] = argcombined_settings = fastmcp.settings.model_dump() | deprecated_settings@@ -254,11 +255,13 @@ class FastMCP(Generic[LifespanResultT]):@propertydef settings(self) -> Settings:- warnings.warn(- "Accessing `.settings` on a FastMCP instance is deprecated. Use the global `fastmcp.settings` instead.",- DeprecationWarning,- stacklevel=2,- )+ # Deprecated in 2.8.0+ if fastmcp.settings.deprecation_warnings:+ warnings.warn(+ "Accessing `.settings` on a FastMCP instance is deprecated. Use the global `fastmcp.settings` instead.",+ DeprecationWarning,+ stacklevel=2,+ )return self._deprecated_settings@property@@ -865,11 +868,12 @@ class FastMCP(Generic[LifespanResultT]):tags: Optional set of tags for categorizing the resource"""# deprecated since 2.7.0- warnings.warn(- "The add_resource_fn method is deprecated. Use the resource decorator instead.",- DeprecationWarning,- stacklevel=2,- )+ if fastmcp.settings.deprecation_warnings:+ warnings.warn(+ "The add_resource_fn method is deprecated. Use the resource decorator instead.",+ DeprecationWarning,+ stacklevel=2,+ )self._resource_manager.add_resource_or_template_from_fn(fn=fn,uri=uri,@@ -1233,13 +1237,14 @@ class FastMCP(Generic[LifespanResultT]):"""Run the server using SSE transport."""# Deprecated since 2.3.2- warnings.warn(- "The run_sse_async method is deprecated (as of 2.3.2). Use run_http_async for a "- "modern (non-SSE) alternative, or create an SSE app with "- "`fastmcp.server.http.create_sse_app` and run it directly.",- DeprecationWarning,- stacklevel=2,- )+ if fastmcp.settings.deprecation_warnings:+ warnings.warn(+ "The run_sse_async method is deprecated (as of 2.3.2). Use run_http_async for a "+ "modern (non-SSE) alternative, or create an SSE app with "+ "`fastmcp.server.http.create_sse_app` and run it directly.",+ DeprecationWarning,+ stacklevel=2,+ )await self.run_http_async(transport="sse",host=host,@@ -1264,12 +1269,13 @@ class FastMCP(Generic[LifespanResultT]):middleware: A list of middleware to apply to the app"""# Deprecated since 2.3.2- warnings.warn(- "The sse_app method is deprecated (as of 2.3.2). Use http_app as a modern (non-SSE) "- "alternative, or call `fastmcp.server.http.create_sse_app` directly.",- DeprecationWarning,- stacklevel=2,- )+ if fastmcp.settings.deprecation_warnings:+ warnings.warn(+ "The sse_app method is deprecated (as of 2.3.2). Use http_app as a modern (non-SSE) "+ "alternative, or call `fastmcp.server.http.create_sse_app` directly.",+ DeprecationWarning,+ stacklevel=2,+ )return create_sse_app(server=self,message_path=message_path or self._deprecated_settings.message_path,@@ -1292,11 +1298,12 @@ class FastMCP(Generic[LifespanResultT]):middleware: A list of middleware to apply to the app"""# Deprecated since 2.3.2- warnings.warn(- "The streamable_http_app method is deprecated (as of 2.3.2). Use http_app() instead.",- DeprecationWarning,- stacklevel=2,- )+ if fastmcp.settings.deprecation_warnings:+ warnings.warn(+ "The streamable_http_app method is deprecated (as of 2.3.2). Use http_app() instead.",+ DeprecationWarning,+ stacklevel=2,+ )return self.http_app(path=path, middleware=middleware)def http_app(@@ -1349,12 +1356,13 @@ class FastMCP(Generic[LifespanResultT]):uvicorn_config: dict[str, Any] | None = None,) -> None:# Deprecated since 2.3.2- warnings.warn(- "The run_streamable_http_async method is deprecated (as of 2.3.2). "- "Use run_http_async instead.",- DeprecationWarning,- stacklevel=2,- )+ if fastmcp.settings.deprecation_warnings:+ warnings.warn(+ "The run_streamable_http_async method is deprecated (as of 2.3.2). "+ "Use run_http_async instead.",+ DeprecationWarning,+ stacklevel=2,+ )await self.run_http_async(transport="streamable-http",host=host,@@ -1422,30 +1430,33 @@ class FastMCP(Generic[LifespanResultT]):if tool_separator is not None:# Deprecated since 2.4.0- warnings.warn(- "The tool_separator parameter is deprecated and will be removed in a future version. "- "Tools are now prefixed using 'prefix_toolname' format.",- DeprecationWarning,- stacklevel=2,- )+ if fastmcp.settings.deprecation_warnings:+ warnings.warn(+ "The tool_separator parameter is deprecated and will be removed in a future version. "+ "Tools are now prefixed using 'prefix_toolname' format.",+ DeprecationWarning,+ stacklevel=2,+ )if resource_separator is not None:# Deprecated since 2.4.0- warnings.warn(- "The resource_separator parameter is deprecated and ignored. "- "Resource prefixes are now added using the protocol://prefix/path format.",- DeprecationWarning,- stacklevel=2,- )+ if fastmcp.settings.deprecation_warnings:+ warnings.warn(+ "The resource_separator parameter is deprecated and ignored. "+ "Resource prefixes are now added using the protocol://prefix/path format.",+ DeprecationWarning,+ stacklevel=2,+ )if prompt_separator is not None:# Deprecated since 2.4.0- warnings.warn(- "The prompt_separator parameter is deprecated and will be removed in a future version. "- "Prompts are now prefixed using 'prefix_promptname' format.",- DeprecationWarning,- stacklevel=2,- )+ if fastmcp.settings.deprecation_warnings:+ warnings.warn(+ "The prompt_separator parameter is deprecated and will be removed in a future version. "+ "Prompts are now prefixed using 'prefix_promptname' format.",+ DeprecationWarning,+ stacklevel=2,+ )# if as_proxy is not specified and the server has a custom lifespan,# we should treat it as a proxy@@ -1507,30 +1518,33 @@ class FastMCP(Generic[LifespanResultT]):"""if tool_separator is not None:# Deprecated since 2.4.0- warnings.warn(- "The tool_separator parameter is deprecated and will be removed in a future version. "- "Tools are now prefixed using 'prefix_toolname' format.",- DeprecationWarning,- stacklevel=2,- )+ if fastmcp.settings.deprecation_warnings:+ warnings.warn(+ "The tool_separator parameter is deprecated and will be removed in a future version. "+ "Tools are now prefixed using 'prefix_toolname' format.",+ DeprecationWarning,+ stacklevel=2,+ )if resource_separator is not None:# Deprecated since 2.4.0- warnings.warn(- "The resource_separator parameter is deprecated and ignored. "- "Resource prefixes are now added using the protocol://prefix/path format.",- DeprecationWarning,- stacklevel=2,- )+ if fastmcp.settings.deprecation_warnings:+ warnings.warn(+ "The resource_separator parameter is deprecated and ignored. "+ "Resource prefixes are now added using the protocol://prefix/path format.",+ DeprecationWarning,+ stacklevel=2,+ )if prompt_separator is not None:# Deprecated since 2.4.0- warnings.warn(- "The prompt_separator parameter is deprecated and will be removed in a future version. "- "Prompts are now prefixed using 'prefix_promptname' format.",- DeprecationWarning,- stacklevel=2,- )+ if fastmcp.settings.deprecation_warnings:+ warnings.warn(+ "The prompt_separator parameter is deprecated and will be removed in a future version. "+ "Prompts are now prefixed using 'prefix_promptname' format.",+ DeprecationWarning,+ stacklevel=2,+ )# Import tools from the mounted servertool_prefix = f"{prefix}_"@@ -1666,11 +1680,12 @@ class FastMCP(Generic[LifespanResultT]):Create a FastMCP proxy server from a FastMCP client."""# Deprecated since 2.3.5- warnings.warn(- "FastMCP.from_client() is deprecated; use FastMCP.as_proxy() instead.",- DeprecationWarning,- stacklevel=2,- )+ if fastmcp.settings.deprecation_warnings:+ warnings.warn(+ "FastMCP.from_client() is deprecated; use FastMCP.as_proxy() instead.",+ DeprecationWarning,+ stacklevel=2,+ )return cls.as_proxy(client, **settings)diff --git a/src/fastmcp/settings.py b/src/fastmcp/settings.pyindex b6cdc18a4..96fd657b3 100644--- a/src/fastmcp/settings.py+++ b/src/fastmcp/settings.py@@ -1,7 +1,6 @@from __future__ import annotations as _annotationsimport inspect-import warningsfrom pathlib import Pathfrom typing import Annotated, Any, Literal@@ -15,6 +14,10 @@ from pydantic_settings import ()from typing_extensions import Self+from fastmcp.utilities.logging import get_logger++logger = get_logger(__name__)+LOG_LEVEL = Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]DuplicateBehavior = Literal["warn", "error", "replace", "ignore"]@@ -39,10 +42,8 @@ class ExtendedEnvSettingsSource(EnvSettingsSource):if env_val is not None:if prefix == "FASTMCP_SERVER_":# Deprecated in 2.8.0- warnings.warn(+ logger.warning("Using `FASTMCP_SERVER_` environment variables is deprecated. Use `FASTMCP_` instead.",- DeprecationWarning,- stacklevel=2,)return env_val, field_key, value_is_complex@@ -89,10 +90,8 @@ class Settings(BaseSettings):which accessed fastmcp.settings.settings"""# Deprecated in 2.8.0- warnings.warn(+ logger.warning("Using fastmcp.settings.settings is deprecated. Use fastmcp.settings instead.",- DeprecationWarning,- stacklevel=2,)return selfdiff --git a/src/fastmcp/tools/tool_manager.py b/src/fastmcp/tools/tool_manager.pyindex fe9eeb14c..3a1d04e73 100644--- a/src/fastmcp/tools/tool_manager.py+++ b/src/fastmcp/tools/tool_manager.py@@ -71,11 +71,12 @@ class ToolManager:) -> Tool:"""Add a tool to the server."""# deprecated in 2.7.0- warnings.warn(- "ToolManager.add_tool_from_fn() is deprecated. Use Tool.from_function() and call add_tool() instead.",- DeprecationWarning,- stacklevel=2,- )+ if settings.deprecation_warnings:+ warnings.warn(+ "ToolManager.add_tool_from_fn() is deprecated. Use Tool.from_function() and call add_tool() instead.",+ DeprecationWarning,+ stacklevel=2,+ )tool = Tool.from_function(fn,name=name,diff --git a/tests/deprecated/test_deprecated.py b/tests/deprecated/test_deprecated.pyindex a48e7c216..a20b970bb 100644--- a/tests/deprecated/test_deprecated.py+++ b/tests/deprecated/test_deprecated.py@@ -5,11 +5,34 @@ import pytestfrom starlette.applications import Starlettefrom fastmcp import Client, FastMCP+from fastmcp.utilities.tests import temporary_settings# reset deprecation warnings for this modulepytestmark = pytest.mark.filterwarnings("default::DeprecationWarning")+class TestDeprecationWarningsSetting:+ def test_deprecation_warnings_setting_true(self):+ with temporary_settings(deprecation_warnings=True):+ with pytest.warns(DeprecationWarning) as recorded_warnings:+ # will warn once for providing deprecated arg+ mcp = FastMCP(host="1.2.3.4")+ # will warn once for accessing deprecated property+ mcp.settings++ assert len(recorded_warnings) == 2++ def test_deprecation_warnings_setting_false(self):+ with temporary_settings(deprecation_warnings=False):+ # will error if a warning is raised+ with warnings.catch_warnings():+ warnings.simplefilter("error")+ # will warn once for providing deprecated arg+ mcp = FastMCP(host="1.2.3.4")+ # will warn once for accessing deprecated property+ mcp.settings++def test_sse_app_deprecation_warning():"""Test that sse_app raises a deprecation warning."""server = FastMCP("TestServer")diff --git a/tests/deprecated/test_settings.py b/tests/deprecated/test_settings.pyindex 490b88c1a..6c8fc9862 100644--- a/tests/deprecated/test_settings.py+++ b/tests/deprecated/test_settings.py@@ -305,7 +305,7 @@ class TestDeprecatedServerInitKwargs:class TestDeprecatedEnvironmentVariables:"""Test deprecated environment variable prefixes."""- def test_fastmcp_server_env_var_deprecation_warning(self):+ def test_fastmcp_server_env_var_deprecation_warning(self, caplog):"""Test that FASTMCP_SERVER_ environment variables emit deprecation warnings."""env_var_name = "FASTMCP_SERVER_HOST"original_value = os.environ.get(env_var_name)@@ -313,11 +313,15 @@ class TestDeprecatedEnvironmentVariables:try:os.environ[env_var_name] = "192.168.1.1"- with pytest.warns(- DeprecationWarning,- match=r"Using `FASTMCP_SERVER_` environment variables is deprecated\. Use `FASTMCP_` instead\.",- ):- settings = Settings()+ settings = Settings()++ # Check that a warning was logged+ assert any(+ "Using `FASTMCP_SERVER_` environment variables is deprecated. Use `FASTMCP_` instead."+ in record.message+ for record in caplog.records+ if record.levelname == "WARNING"+ )# Verify the setting is still appliedassert settings.host == "192.168.1.1"@@ -333,16 +337,20 @@ class TestDeprecatedEnvironmentVariables:class TestDeprecatedSettingsProperty:"""Test deprecated settings property access."""- def test_settings_property_deprecation_warning(self):- """Test that accessing fastmcp.settings.settings raises a deprecation warning."""+ def test_settings_property_deprecation_warning(self, caplog):+ """Test that accessing fastmcp.settings.settings logs a deprecation warning."""from fastmcp import settings- with pytest.warns(- DeprecationWarning,- match=r"Using fastmcp\.settings\.settings is deprecated\. Use fastmcp\.settings instead\.",- ):- # Access the deprecated property- deprecated_settings = settings.settings+ # Access the deprecated property+ deprecated_settings = settings.settings++ # Check that a warning was logged+ assert any(+ "Using fastmcp.settings.settings is deprecated. Use fastmcp.settings instead."+ in record.message+ for record in caplog.records+ if record.levelname == "WARNING"+ )# Verify it still returns the same settings objectassert deprecated_settings is settings