fastmcp 2.3.3__py3-none-any.whl → 2.3.4__py3-none-any.whl

fastmcp/server/proxy.py

@@ -18,7 +18,7 @@ from mcp.types import (
 from pydantic.networks import AnyUrl
 
 from fastmcp.client import Client
-from fastmcp.exceptions import NotFoundError
+from fastmcp.exceptions import NotFoundError, ResourceError, ToolError
 from fastmcp.prompts import Prompt, PromptMessage
 from fastmcp.resources import Resource, ResourceTemplate
 from fastmcp.server.context import Context
@@ -64,7 +64,7 @@ class ProxyTool(Tool):
                 arguments=arguments,
             )
         if result.isError:
-            raise ValueError(cast(mcp.types.TextContent, result.content[0]).text)
+            raise ToolError(cast(mcp.types.TextContent, result.content[0]).text)
         return result.content
 
 
@@ -97,7 +97,7 @@ class ProxyResource(Resource):
         elif isinstance(result[0], BlobResourceContents):
             return result[0].blob
         else:
-            raise ValueError(f"Unsupported content type: {type(result[0])}")
+            raise ResourceError(f"Unsupported content type: {type(result[0])}")
 
 
 class ProxyTemplate(ResourceTemplate):
@@ -138,7 +138,7 @@ class ProxyTemplate(ResourceTemplate):
         elif isinstance(result[0], BlobResourceContents):
             value = result[0].blob
         else:
-            raise ValueError(f"Unsupported content type: {type(result[0])}")
+            raise ResourceError(f"Unsupported content type: {type(result[0])}")
 
         return ProxyResource(
             client=self._client,

fastmcp/server/server.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import datetime
-import inspect
 import warnings
 from collections.abc import AsyncIterator, Awaitable, Callable
 from contextlib import (
@@ -20,7 +19,7 @@ import pydantic
 import uvicorn
 from mcp.server.auth.provider import OAuthAuthorizationServerProvider
 from mcp.server.lowlevel.helper_types import ReadResourceContents
-from mcp.server.lowlevel.server import LifespanResultT
+from mcp.server.lowlevel.server import LifespanResultT, NotificationOptions
 from mcp.server.lowlevel.server import Server as MCPServer
 from mcp.server.stdio import stdio_server
 from mcp.types import (
@@ -44,7 +43,7 @@ from starlette.routing import BaseRoute, Route
 
 import fastmcp.server
 import fastmcp.settings
-from fastmcp.exceptions import NotFoundError, ResourceError
+from fastmcp.exceptions import NotFoundError
 from fastmcp.prompts import Prompt, PromptManager
 from fastmcp.prompts.prompt import PromptResult
 from fastmcp.resources import Resource, ResourceManager
@@ -54,7 +53,7 @@ from fastmcp.tools import ToolManager
 from fastmcp.tools.tool import Tool
 from fastmcp.utilities.cache import TimedCache
 from fastmcp.utilities.decorators import DecoratedFunction
-from fastmcp.utilities.logging import configure_logging, get_logger
+from fastmcp.utilities.logging import get_logger
 
 if TYPE_CHECKING:
     from fastmcp.client import Client
@@ -63,6 +62,8 @@ if TYPE_CHECKING:
 
 logger = get_logger(__name__)
 
+DuplicateBehavior = Literal["warn", "error", "replace", "ignore"]
+
 
 @asynccontextmanager
 async def default_lifespan(server: FastMCP) -> AsyncIterator[Any]:
@@ -107,40 +108,52 @@ class FastMCP(Generic[LifespanResultT]):
             | None
         ) = None,
         tags: set[str] | None = None,
+        dependencies: list[str] | None = None,
         tool_serializer: Callable[[Any], str] | None = None,
+        cache_expiration_seconds: float | None = None,
+        on_duplicate_tools: DuplicateBehavior | None = None,
+        on_duplicate_resources: DuplicateBehavior | None = None,
+        on_duplicate_prompts: DuplicateBehavior | None = None,
         **settings: Any,
     ):
-        self.tags: set[str] = tags or set()
+        if settings:
+            # TODO: remove settings. Deprecated since 2.3.4
+            warnings.warn(
+                "Passing runtime and transport-specific settings as kwargs "
+                "to the FastMCP constructor is deprecated (as of 2.3.4), "
+                "including most transport settings. If possible, provide settings when calling "
+                "run() instead.",
+                DeprecationWarning,
+                stacklevel=2,
+            )
         self.settings = fastmcp.settings.ServerSettings(**settings)
+
+        self.tags: set[str] = tags or set()
+        self.dependencies = dependencies
         self._cache = TimedCache(
-            expiration=datetime.timedelta(
-                seconds=self.settings.cache_expiration_seconds
-            )
+            expiration=datetime.timedelta(seconds=cache_expiration_seconds or 0)
         )
-
         self._mounted_servers: dict[str, MountedServer] = {}
+        self._additional_http_routes: list[BaseRoute] = []
+        self._tool_manager = ToolManager(
+            duplicate_behavior=on_duplicate_tools,
+            serializer=tool_serializer,
+        )
+        self._resource_manager = ResourceManager(
+            duplicate_behavior=on_duplicate_resources
+        )
+        self._prompt_manager = PromptManager(duplicate_behavior=on_duplicate_prompts)
 
         if lifespan is None:
             self._has_lifespan = False
             lifespan = default_lifespan
         else:
             self._has_lifespan = True
-
         self._mcp_server = MCPServer[LifespanResultT](
             name=name or "FastMCP",
             instructions=instructions,
             lifespan=_lifespan_wrapper(self, lifespan),
         )
-        self._tool_manager = ToolManager(
-            duplicate_behavior=self.settings.on_duplicate_tools,
-            serializer=tool_serializer,
-        )
-        self._resource_manager = ResourceManager(
-            duplicate_behavior=self.settings.on_duplicate_resources
-        )
-        self._prompt_manager = PromptManager(
-            duplicate_behavior=self.settings.on_duplicate_prompts
-        )
 
         if (self.settings.auth is not None) != (auth_server_provider is not None):
             # TODO: after we support separate authorization servers (see
@@ -150,15 +163,9 @@ class FastMCP(Generic[LifespanResultT]):
             )
         self._auth_server_provider = auth_server_provider
 
-        self._additional_http_routes: list[BaseRoute] = []
-        self.dependencies = self.settings.dependencies
-
         # Set up MCP protocol handlers
         self._setup_handlers()
 
-        # Configure logging
-        configure_logging(self.settings.log_level)
-
     def __repr__(self) -> str:
         return f"{type(self).__name__}({self.name!r})"
 
@@ -378,16 +385,13 @@ class FastMCP(Generic[LifespanResultT]):
         with fastmcp.server.context.Context(fastmcp=self):
             if self._resource_manager.has_resource(uri):
                 resource = await self._resource_manager.get_resource(uri)
-                try:
-                    content = await resource.read()
-                    return [
-                        ReadResourceContents(
-                            content=content, mime_type=resource.mime_type
-                        )
-                    ]
-                except Exception as e:
-                    logger.error(f"Error reading resource {uri}: {e}")
-                    raise ResourceError(str(e))
+                content = await self._resource_manager.read_resource(uri)
+                return [
+                    ReadResourceContents(
+                        content=content,
+                        mime_type=resource.mime_type,
+                    )
+                ]
             else:
                 for server in self._mounted_servers.values():
                     if server.match_resource(str(uri)):
@@ -414,7 +418,7 @@ class FastMCP(Generic[LifespanResultT]):
                 for server in self._mounted_servers.values():
                     if server.match_prompt(name):
                         new_key = server.strip_prompt_prefix(name)
-                    return await server.server._mcp_get_prompt(new_key, arguments)
+                        return await server.server._mcp_get_prompt(new_key, arguments)
                 else:
                     raise NotFoundError(f"Unknown prompt: {name}")
 
@@ -450,6 +454,18 @@ class FastMCP(Generic[LifespanResultT]):
         )
         self._cache.clear()
 
+    def remove_tool(self, name: str) -> None:
+        """Remove a tool from the server.
+
+        Args:
+            name: The name of the tool to remove
+
+        Raises:
+            NotFoundError: If the tool is not found
+        """
+        self._tool_manager.remove_tool(name)
+        self._cache.clear()
+
     def tool(
         self,
         name: str | None = None,
@@ -715,7 +731,9 @@ class FastMCP(Generic[LifespanResultT]):
             await self._mcp_server.run(
                 read_stream,
                 write_stream,
-                self._mcp_server.create_initialization_options(),
+                self._mcp_server.create_initialization_options(
+                    NotificationOptions(tools_changed=True)
+                ),
             )
 
     async def run_http_async(
@@ -764,15 +782,14 @@ class FastMCP(Generic[LifespanResultT]):
         uvicorn_config: dict | None = None,
     ) -> None:
         """Run the server using SSE transport."""
+
+        # Deprecated since 2.3.2
         warnings.warn(
-            inspect.cleandoc(
-                """
-                The run_sse_async method is deprecated. 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.
-                """
-            ),
+            "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",
@@ -797,14 +814,12 @@ class FastMCP(Generic[LifespanResultT]):
             message_path: The path to the message endpoint
             middleware: A list of middleware to apply to the app
         """
+        # Deprecated since 2.3.2
         warnings.warn(
-            inspect.cleandoc(
-                """
-                The sse_app method is deprecated. Use http_app as a modern (non-SSE)
-                alternative, or call `fastmcp.server.http.create_sse_app` directly.
-                """
-            ),
+            "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,
@@ -829,9 +844,11 @@ class FastMCP(Generic[LifespanResultT]):
             path: The path to the StreamableHTTP endpoint
             middleware: A list of middleware to apply to the app
         """
+        # Deprecated since 2.3.2
         warnings.warn(
-            "The streamable_http_app method is deprecated. Use http_app() instead.",
+            "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)
 
@@ -886,9 +903,12 @@ class FastMCP(Generic[LifespanResultT]):
         path: str | None = None,
         uvicorn_config: dict | None = None,
     ) -> None:
+        # Deprecated since 2.3.2
         warnings.warn(
-            "The run_streamable_http_async method is deprecated. Use run_http_async instead.",
+            "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",

fastmcp/settings.py

@@ -1,10 +1,12 @@
 from __future__ import annotations as _annotations
 
-from typing import TYPE_CHECKING, Literal
+import inspect
+from typing import TYPE_CHECKING, Annotated, Literal
 
 from mcp.server.auth.settings import AuthSettings
-from pydantic import Field
+from pydantic import Field, model_validator
 from pydantic_settings import BaseSettings, SettingsConfigDict
+from typing_extensions import Self
 
 if TYPE_CHECKING:
     pass
@@ -27,16 +29,46 @@ class Settings(BaseSettings):
 
     test_mode: bool = False
     log_level: LOG_LEVEL = "INFO"
-    tool_attempt_parse_json_args: bool = Field(
-        default=False,
-        description="""
-        Note: this enables a legacy behavior. If True, will attempt to parse
-        stringified JSON lists and objects strings in tool arguments before
-        passing them to the tool. This is an old behavior that can create
-        unexpected type coercion issues, but may be helpful for less powerful
-        LLMs that stringify JSON instead of passing actual lists and objects.
-        Defaults to False.""",
-    )
+    client_raise_first_exceptiongroup_error: Annotated[
+        bool,
+        Field(
+            default=True,
+            description=inspect.cleandoc(
+                """
+                Many MCP components operate in anyio taskgroups, and raise
+                ExceptionGroups instead of exceptions. If this setting is True, FastMCP Clients
+                will `raise` the first error in any ExceptionGroup instead of raising
+                the ExceptionGroup as a whole. This is useful for debugging, but may
+                mask other errors.
+                """
+            ),
+        ),
+    ] = True
+    tool_attempt_parse_json_args: Annotated[
+        bool,
+        Field(
+            default=False,
+            description=inspect.cleandoc(
+                """
+                Note: this enables a legacy behavior. If True, will attempt to parse
+                stringified JSON lists and objects strings in tool arguments before
+                passing them to the tool. This is an old behavior that can create
+                unexpected type coercion issues, but may be helpful for less powerful
+                LLMs that stringify JSON instead of passing actual lists and objects.
+                Defaults to False.
+                """
+            ),
+        ),
+    ] = False
+
+    @model_validator(mode="after")
+    def setup_logging(self) -> Self:
+        """Finalize the settings."""
+        from fastmcp.utilities.logging import configure_logging
+
+        configure_logging(self.log_level)
+
+        return self
 
 
 class ServerSettings(BaseSettings):
@@ -54,7 +86,10 @@ class ServerSettings(BaseSettings):
         nested_model_default_partial_update=True,
     )
 
-    log_level: LOG_LEVEL = Field(default_factory=lambda: Settings().log_level)
+    log_level: Annotated[
+        LOG_LEVEL,
+        Field(default_factory=lambda: Settings().log_level),
+    ]
 
     # HTTP settings
     host: str = "127.0.0.1"
@@ -73,10 +108,13 @@ class ServerSettings(BaseSettings):
     # prompt settings
     on_duplicate_prompts: DuplicateBehavior = "warn"
 
-    dependencies: list[str] = Field(
-        default_factory=list,
-        description="List of dependencies to install in the server environment",
-    )
+    dependencies: Annotated[
+        list[str],
+        Field(
+            default_factory=list,
+            description="List of dependencies to install in the server environment",
+        ),
+    ] = []
 
     # cache settings (for checking mounted servers)
     cache_expiration_seconds: float = 0
@@ -90,16 +128,4 @@ class ServerSettings(BaseSettings):
     )
 
 
-class ClientSettings(BaseSettings):
-    """FastMCP client settings."""
-
-    model_config = SettingsConfigDict(
-        env_prefix="FASTMCP_CLIENT_",
-        env_file=".env",
-        extra="ignore",
-    )
-
-    log_level: LOG_LEVEL = Field(default_factory=lambda: Settings().log_level)
-
-
 settings = Settings()

fastmcp/tools/tool.py

@@ -11,9 +11,8 @@ from mcp.types import Tool as MCPTool
 from pydantic import BaseModel, BeforeValidator, Field
 
 import fastmcp
-from fastmcp.exceptions import ToolError
 from fastmcp.server.dependencies import get_context
-from fastmcp.utilities.json_schema import prune_params
+from fastmcp.utilities.json_schema import compress_schema
 from fastmcp.utilities.logging import get_logger
 from fastmcp.utilities.types import (
     Image,
@@ -82,7 +81,11 @@ class Tool(BaseModel):
 
         context_kwarg = find_kwarg_by_type(fn, kwarg_type=Context)
         if context_kwarg:
-            schema = prune_params(schema, params=[context_kwarg])
+            prune_params = [context_kwarg]
+        else:
+            prune_params = None
+
+        schema = compress_schema(schema, prune_params=prune_params)
 
         return cls(
             fn=fn,
@@ -102,48 +105,45 @@ class Tool(BaseModel):
 
         arguments = arguments.copy()
 
-        try:
-            context_kwarg = find_kwarg_by_type(self.fn, kwarg_type=Context)
-            if context_kwarg and context_kwarg not in arguments:
-                arguments[context_kwarg] = get_context()
-
-            if fastmcp.settings.settings.tool_attempt_parse_json_args:
-                # Pre-parse data from JSON in order to handle cases like `["a", "b", "c"]`
-                # being passed in as JSON inside a string rather than an actual list.
-                #
-                # Claude desktop is prone to this - in fact it seems incapable of NOT doing
-                # this. For sub-models, it tends to pass dicts (JSON objects) as JSON strings,
-                # which can be pre-parsed here.
-                signature = inspect.signature(self.fn)
-                for param_name in self.parameters["properties"]:
-                    arg = arguments.get(param_name, None)
-                    # if not in signature, we won't have annotations, so skip logic
-                    if param_name not in signature.parameters:
-                        continue
-                    # if not a string, we won't have a JSON to parse, so skip logic
-                    if not isinstance(arg, str):
-                        continue
-                    # skip if the type is a simple type (int, float, bool)
-                    if signature.parameters[param_name].annotation in (
-                        int,
-                        float,
-                        bool,
-                    ):
-                        continue
-                    try:
-                        arguments[param_name] = json.loads(arg)
-
-                    except json.JSONDecodeError:
-                        pass
-
-            type_adapter = get_cached_typeadapter(self.fn)
-            result = type_adapter.validate_python(arguments)
-            if inspect.isawaitable(result):
-                result = await result
-
-            return _convert_to_content(result, serializer=self.serializer)
-        except Exception as e:
-            raise ToolError(f"Error executing tool {self.name}: {e}") from e
+        context_kwarg = find_kwarg_by_type(self.fn, kwarg_type=Context)
+        if context_kwarg and context_kwarg not in arguments:
+            arguments[context_kwarg] = get_context()
+
+        if fastmcp.settings.settings.tool_attempt_parse_json_args:
+            # Pre-parse data from JSON in order to handle cases like `["a", "b", "c"]`
+            # being passed in as JSON inside a string rather than an actual list.
+            #
+            # Claude desktop is prone to this - in fact it seems incapable of NOT doing
+            # this. For sub-models, it tends to pass dicts (JSON objects) as JSON strings,
+            # which can be pre-parsed here.
+            signature = inspect.signature(self.fn)
+            for param_name in self.parameters["properties"]:
+                arg = arguments.get(param_name, None)
+                # if not in signature, we won't have annotations, so skip logic
+                if param_name not in signature.parameters:
+                    continue
+                # if not a string, we won't have a JSON to parse, so skip logic
+                if not isinstance(arg, str):
+                    continue
+                # skip if the type is a simple type (int, float, bool)
+                if signature.parameters[param_name].annotation in (
+                    int,
+                    float,
+                    bool,
+                ):
+                    continue
+                try:
+                    arguments[param_name] = json.loads(arg)
+
+                except json.JSONDecodeError:
+                    pass
+
+        type_adapter = get_cached_typeadapter(self.fn)
+        result = type_adapter.validate_python(arguments)
+        if inspect.isawaitable(result):
+            result = await result
+
+        return _convert_to_content(result, serializer=self.serializer)
 
     def to_mcp_tool(self, **overrides: Any) -> MCPTool:
         kwargs = {

fastmcp/tools/tool_manager.py

@@ -5,7 +5,7 @@ from typing import TYPE_CHECKING, Any
 
 from mcp.types import EmbeddedResource, ImageContent, TextContent, ToolAnnotations
 
-from fastmcp.exceptions import NotFoundError
+from fastmcp.exceptions import NotFoundError, ToolError
 from fastmcp.settings import DuplicateBehavior
 from fastmcp.tools.tool import Tool
 from fastmcp.utilities.logging import get_logger
@@ -94,6 +94,20 @@ class ToolManager:
             self._tools[key] = tool
         return tool
 
+    def remove_tool(self, key: str) -> None:
+        """Remove a tool from the server.
+
+        Args:
+            key: The key of the tool to remove
+
+        Raises:
+            NotFoundError: If the tool is not found
+        """
+        if key in self._tools:
+            del self._tools[key]
+        else:
+            raise NotFoundError(f"Unknown tool: {key}")
+
     async def call_tool(
         self, key: str, arguments: dict[str, Any]
     ) -> list[TextContent | ImageContent | EmbeddedResource]:
@@ -102,4 +116,15 @@ class ToolManager:
         if not tool:
             raise NotFoundError(f"Unknown tool: {key}")
 
-        return await tool.run(arguments)
+        try:
+            return await tool.run(arguments)
+
+        # raise ToolErrors as-is
+        except ToolError as e:
+            logger.exception(f"Error calling tool {key!r}: {e}")
+            raise e
+
+        # raise other exceptions as ToolErrors without revealing internal details
+        except Exception as e:
+            logger.exception(f"Error calling tool {key!r}: {e}")
+            raise ToolError(f"Error calling tool {key!r}") from e

fastmcp/utilities/exceptions.py

@@ -0,0 +1,49 @@
+from collections.abc import Callable, Iterable, Mapping
+from typing import Any
+
+import httpx
+import mcp.types
+from exceptiongroup import BaseExceptionGroup
+from mcp import McpError
+
+import fastmcp
+
+
+def iter_exc(group: BaseExceptionGroup):
+    for exc in group.exceptions:
+        if isinstance(exc, BaseExceptionGroup):
+            yield from iter_exc(exc)
+        else:
+            yield exc
+
+
+def _exception_handler(group: BaseExceptionGroup):
+    for leaf in iter_exc(group):
+        if isinstance(leaf, httpx.ConnectTimeout):
+            raise McpError(
+                error=mcp.types.ErrorData(
+                    code=httpx.codes.REQUEST_TIMEOUT,
+                    message="Timed out while waiting for response.",
+                )
+            )
+        raise leaf
+
+
+# this catch handler is used to catch taskgroup exception groups and raise the
+# first exception. This allows more sane debugging.
+_catch_handlers: Mapping[
+    type[BaseException] | Iterable[type[BaseException]],
+    Callable[[BaseExceptionGroup[Any]], Any],
+] = {
+    Exception: _exception_handler,
+}
+
+
+def get_catch_handlers() -> Mapping[
+    type[BaseException] | Iterable[type[BaseException]],
+    Callable[[BaseExceptionGroup[Any]], Any],
+]:
+    if fastmcp.settings.settings.client_raise_first_exceptiongroup_error:
+        return _catch_handlers
+    else:
+        return {}