fastmcp 2.4.0__py3-none-any.whl → 2.5.0__py3-none-any.whl

fastmcp/client/client.py

@@ -210,6 +210,23 @@ class Client:
         result = await self.session.send_ping()
         return isinstance(result, mcp.types.EmptyResult)
 
+    async def cancel(
+        self,
+        request_id: str | int,
+        reason: str | None = None,
+    ) -> None:
+        """Send a cancellation notification for an in-progress request."""
+        notification = mcp.types.ClientNotification(
+            mcp.types.CancelledNotification(
+                method="notifications/cancelled",
+                params=mcp.types.CancelledNotificationParams(
+                    requestId=request_id,
+                    reason=reason,
+                ),
+            )
+        )
+        await self.session.send_notification(notification)
+
     async def progress(
         self,
         progress_token: str | int,
@@ -322,7 +339,12 @@ class Client:
             RuntimeError: If called while the client is not connected.
         """
         if isinstance(uri, str):
-            uri = AnyUrl(uri)  # Ensure AnyUrl
+            try:
+                uri = AnyUrl(uri)  # Ensure AnyUrl
+            except Exception as e:
+                raise ValueError(
+                    f"Provided resource URI is invalid: {str(uri)!r}"
+                ) from e
         result = await self.read_resource_mcp(uri)
         return result.contents
 

fastmcp/client/transports.py

@@ -19,11 +19,13 @@ from mcp.client.sse import sse_client
 from mcp.client.stdio import stdio_client
 from mcp.client.streamable_http import streamablehttp_client
 from mcp.client.websocket import websocket_client
+from mcp.server.fastmcp import FastMCP as FastMCP1Server
 from mcp.shared.memory import create_connected_server_and_client_session
 from pydantic import AnyUrl
 from typing_extensions import Unpack
 
 from fastmcp.server import FastMCP as FastMCPServer
+from fastmcp.server.dependencies import get_http_request
 from fastmcp.server.server import FastMCP
 from fastmcp.utilities.logging import get_logger
 from fastmcp.utilities.mcp_config import MCPConfig, infer_transport_type_from_url
@@ -33,6 +35,11 @@ if TYPE_CHECKING:
 
 logger = get_logger(__name__)
 
+# these headers, when forwarded to the remote server, can cause issues
+EXCLUDE_HEADERS = {
+    "content-length",
+}
+
 
 class SessionKwargs(TypedDict, total=False):
     """Keyword arguments for the MCP ClientSession constructor."""
@@ -131,7 +138,24 @@ class SSETransport(ClientTransport):
     async def connect_session(
         self, **session_kwargs: Unpack[SessionKwargs]
     ) -> AsyncIterator[ClientSession]:
-        client_kwargs = {}
+        client_kwargs: dict[str, Any] = {
+            "headers": self.headers,
+        }
+
+        # load headers from an active HTTP request, if available. This will only be true
+        # if the client is used in a FastMCP Proxy, in which case the MCP client headers
+        # need to be forwarded to the remote server.
+        try:
+            active_request = get_http_request()
+            for name, value in active_request.headers.items():
+                name = name.lower()
+                if name not in self.headers and name not in {
+                    h.lower() for h in EXCLUDE_HEADERS
+                }:
+                    client_kwargs["headers"][name] = str(value)
+        except RuntimeError:
+            client_kwargs["headers"] = self.headers
+
         # sse_read_timeout has a default value set, so we can't pass None without overriding it
         # instead we simply leave the kwarg out if it's not provided
         if self.sse_read_timeout is not None:
@@ -142,9 +166,7 @@ class SSETransport(ClientTransport):
             )
             client_kwargs["timeout"] = read_timeout_seconds.total_seconds()
 
-        async with sse_client(
-            self.url, headers=self.headers, **client_kwargs
-        ) as transport:
+        async with sse_client(self.url, **client_kwargs) as transport:
             read_stream, write_stream = transport
             async with ClientSession(
                 read_stream, write_stream, **session_kwargs
@@ -179,7 +201,26 @@ class StreamableHttpTransport(ClientTransport):
     async def connect_session(
         self, **session_kwargs: Unpack[SessionKwargs]
     ) -> AsyncIterator[ClientSession]:
-        client_kwargs = {}
+        client_kwargs: dict[str, Any] = {
+            "headers": self.headers,
+        }
+
+        # load headers from an active HTTP request, if available. This will only be true
+        # if the client is used in a FastMCP Proxy, in which case the MCP client headers
+        # need to be forwarded to the remote server.
+        try:
+            active_request = get_http_request()
+            for name, value in active_request.headers.items():
+                name = name.lower()
+                if name not in self.headers and name not in {
+                    h.lower() for h in EXCLUDE_HEADERS
+                }:
+                    client_kwargs["headers"][name] = str(value)
+
+        except RuntimeError:
+            client_kwargs["headers"] = self.headers
+        print(client_kwargs)
+
         # sse_read_timeout has a default value set, so we can't pass None without overriding it
         # instead we simply leave the kwarg out if it's not provided
         if self.sse_read_timeout is not None:
@@ -187,9 +228,7 @@ class StreamableHttpTransport(ClientTransport):
         if session_kwargs.get("read_timeout_seconds", None) is not None:
             client_kwargs["timeout"] = session_kwargs.get("read_timeout_seconds")
 
-        async with streamablehttp_client(
-            self.url, headers=self.headers, **client_kwargs
-        ) as transport:
+        async with streamablehttp_client(self.url, **client_kwargs) as transport:
             read_stream, write_stream, _ = transport
             async with ClientSession(
                 read_stream, write_stream, **session_kwargs
@@ -448,15 +487,21 @@ class NpxStdioTransport(StdioTransport):
 
 
 class FastMCPTransport(ClientTransport):
-    """
-    Special transport for in-memory connections to an MCP server.
+    """In-memory transport for FastMCP servers.
 
-    This is particularly useful for testing or when client and server
-    are in the same process.
+    This transport connects directly to a FastMCP server instance in the same
+    Python process. It works with both FastMCP 2.x servers and FastMCP 1.0
+    servers from the low-level MCP SDK. This is particularly useful for unit
+    tests or scenarios where client and server run in the same runtime.
     """
 
-    def __init__(self, mcp: FastMCPServer):
-        self.server = mcp  # Can be FastMCP or MCPServer
+    def __init__(self, mcp: FastMCPServer | FastMCP1Server):
+        """Initialize a FastMCPTransport from a FastMCP server instance."""
+
+        # Accept both FastMCP 2.x and FastMCP 1.0 servers. Both expose a
+        # ``_mcp_server`` attribute pointing to the underlying MCP server
+        # implementation, so we can treat them identically.
+        self.server = mcp
 
     @contextlib.asynccontextmanager
     async def connect_session(
@@ -528,8 +573,12 @@ class MCPConfigTransport(ClientTransport):
             config = MCPConfig.from_dict(config)
         self.config = config
 
+        # if there are no servers, raise an error
+        if len(self.config.mcpServers) == 0:
+            raise ValueError("No MCP servers defined in the config")
+
         # if there's exactly one server, create a client for that server
-        if len(self.config.mcpServers) == 1:
+        elif len(self.config.mcpServers) == 1:
             self.transport = list(self.config.mcpServers.values())[0].to_transport()
 
         # otherwise create a composite client
@@ -558,6 +607,7 @@ class MCPConfigTransport(ClientTransport):
 def infer_transport(
     transport: ClientTransport
     | FastMCPServer
+    | FastMCP1Server
     | AnyUrl
     | Path
     | MCPConfig
@@ -573,7 +623,7 @@ def infer_transport(
 
     The function supports these input types:
     - ClientTransport: Used directly without modification
-    - FastMCPServer: Creates an in-memory FastMCPTransport
+    - FastMCPServer or FastMCP1Server: Creates an in-memory FastMCPTransport
     - Path or str (file path): Creates PythonStdioTransport (.py) or NodeStdioTransport (.js)
     - AnyUrl or str (URL): Creates StreamableHttpTransport (default) or SSETransport (for /sse endpoints)
     - MCPConfig or dict: Creates MCPConfigTransport, potentially connecting to multiple servers
@@ -610,8 +660,8 @@ def infer_transport(
     if isinstance(transport, ClientTransport):
         return transport
 
-    # the transport is a FastMCP server
-    elif isinstance(transport, FastMCPServer):
+    # the transport is a FastMCP server (2.x or 1.0)
+    elif isinstance(transport, FastMCPServer | FastMCP1Server):
         inferred_transport = FastMCPTransport(mcp=transport)
 
     # the transport is a path to a script

fastmcp/prompts/prompt.py

@@ -12,6 +12,7 @@ from mcp.types import Prompt as MCPPrompt
 from mcp.types import PromptArgument as MCPPromptArgument
 from pydantic import BaseModel, BeforeValidator, Field, TypeAdapter, validate_call
 
+from fastmcp.exceptions import PromptError
 from fastmcp.server.dependencies import get_context
 from fastmcp.utilities.json_schema import compress_schema
 from fastmcp.utilities.logging import get_logger
@@ -96,7 +97,7 @@ class Prompt(BaseModel):
         """
         from fastmcp.server.context import Context
 
-        func_name = name or fn.__name__
+        func_name = name or getattr(fn, "__name__", None) or fn.__class__.__name__
 
         if func_name == "<lambda>":
             raise ValueError("You must provide a name for lambda functions")
@@ -108,6 +109,12 @@ class Prompt(BaseModel):
             if param.kind == inspect.Parameter.VAR_KEYWORD:
                 raise ValueError("Functions with **kwargs are not supported as prompts")
 
+        description = description or fn.__doc__
+
+        # if the fn is a callable class, we need to get the __call__ method from here out
+        if not inspect.isroutine(fn):
+            fn = fn.__call__
+
         type_adapter = get_cached_typeadapter(fn)
         parameters = type_adapter.json_schema()
 
@@ -138,7 +145,7 @@ class Prompt(BaseModel):
 
         return cls(
             name=func_name,
-            description=description or fn.__doc__,
+            description=description,
             arguments=arguments,
             fn=fn,
             tags=tags or set(),
@@ -199,12 +206,12 @@ class Prompt(BaseModel):
                             )
                         )
                 except Exception:
-                    raise ValueError("Could not convert prompt result to message.")
+                    raise PromptError("Could not convert prompt result to message.")
 
             return messages
         except Exception as e:
             logger.exception(f"Error rendering prompt {self.name}: {e}")
-            raise ValueError(f"Error rendering prompt {self.name}.")
+            raise PromptError(f"Error rendering prompt {self.name}.")
 
     def __eq__(self, other: object) -> bool:
         if not isinstance(other, Prompt):

fastmcp/prompts/prompt_manager.py

@@ -7,7 +7,7 @@ from typing import TYPE_CHECKING, Any
 
 from mcp import GetPromptResult
 
-from fastmcp.exceptions import NotFoundError
+from fastmcp.exceptions import NotFoundError, PromptError
 from fastmcp.prompts.prompt import Prompt, PromptResult
 from fastmcp.settings import DuplicateBehavior
 from fastmcp.utilities.logging import get_logger
@@ -21,8 +21,13 @@ logger = get_logger(__name__)
 class PromptManager:
     """Manages FastMCP prompts."""
 
-    def __init__(self, duplicate_behavior: DuplicateBehavior | None = None):
+    def __init__(
+        self,
+        duplicate_behavior: DuplicateBehavior | None = None,
+        mask_error_details: bool = False,
+    ):
         self._prompts: dict[str, Prompt] = {}
+        self.mask_error_details = mask_error_details
 
         # Default to "warn" if None is provided
         if duplicate_behavior is None:
@@ -85,9 +90,24 @@ class PromptManager:
         if not prompt:
             raise NotFoundError(f"Unknown prompt: {name}")
 
-        messages = await prompt.render(arguments)
-
-        return GetPromptResult(description=prompt.description, messages=messages)
+        try:
+            messages = await prompt.render(arguments)
+            return GetPromptResult(description=prompt.description, messages=messages)
+
+        # Pass through PromptErrors as-is
+        except PromptError as e:
+            logger.exception(f"Error rendering prompt {name!r}: {e}")
+            raise e
+
+        # Handle other exceptions
+        except Exception as e:
+            logger.exception(f"Error rendering prompt {name!r}: {e}")
+            if self.mask_error_details:
+                # Mask internal details
+                raise PromptError(f"Error rendering prompt {name!r}")
+            else:
+                # Include original error details
+                raise PromptError(f"Error rendering prompt {name!r}: {e}")
 
     def has_prompt(self, key: str) -> bool:
         """Check if a prompt exists."""

fastmcp/resources/resource_manager.py

@@ -22,9 +22,22 @@ logger = get_logger(__name__)
 class ResourceManager:
     """Manages FastMCP resources."""
 
-    def __init__(self, duplicate_behavior: DuplicateBehavior | None = None):
+    def __init__(
+        self,
+        duplicate_behavior: DuplicateBehavior | None = None,
+        mask_error_details: bool = False,
+    ):
+        """Initialize the ResourceManager.
+
+        Args:
+            duplicate_behavior: How to handle duplicate resources
+                (warn, error, replace, ignore)
+            mask_error_details: Whether to mask error details from exceptions
+                other than ResourceError
+        """
         self._resources: dict[str, Resource] = {}
         self._templates: dict[str, ResourceTemplate] = {}
+        self.mask_error_details = mask_error_details
 
         # Default to "warn" if None is provided
         if duplicate_behavior is None:
@@ -35,7 +48,6 @@ class ResourceManager:
                 f"Invalid duplicate_behavior: {duplicate_behavior}. "
                 f"Must be one of: {', '.join(DuplicateBehavior.__args__)}"
             )
-
         self.duplicate_behavior = duplicate_behavior
 
     def add_resource_or_template_from_fn(
@@ -244,12 +256,21 @@ class ResourceManager:
                         uri_str,
                         params=params,
                     )
+                # Pass through ResourceErrors as-is
                 except ResourceError as e:
                     logger.error(f"Error creating resource from template: {e}")
                     raise e
+                # Handle other exceptions
                 except Exception as e:
                     logger.error(f"Error creating resource from template: {e}")
-                    raise ValueError(f"Error creating resource from template: {e}")
+                    if self.mask_error_details:
+                        # Mask internal details
+                        raise ValueError("Error creating resource from template") from e
+                    else:
+                        # Include original error details
+                        raise ValueError(
+                            f"Error creating resource from template: {e}"
+                        ) from e
 
         raise NotFoundError(f"Unknown resource: {uri_str}")
 
@@ -265,10 +286,15 @@ class ResourceManager:
             logger.error(f"Error reading resource {uri!r}: {e}")
             raise e
 
-        # raise other exceptions as ResourceErrors without revealing internal details
+        # Handle other exceptions
         except Exception as e:
             logger.error(f"Error reading resource {uri!r}: {e}")
-            raise ResourceError(f"Error reading resource {uri!r}") from e
+            if self.mask_error_details:
+                # Mask internal details
+                raise ResourceError(f"Error reading resource {uri!r}") from e
+            else:
+                # Include original error details
+                raise ResourceError(f"Error reading resource {uri!r}: {e}") from e
 
     def get_resources(self) -> dict[str, Resource]:
         """Get all registered resources, keyed by URI."""

fastmcp/resources/template.py

@@ -14,7 +14,6 @@ from pydantic import (
     BaseModel,
     BeforeValidator,
     Field,
-    TypeAdapter,
     field_validator,
     validate_call,
 )
@@ -25,6 +24,7 @@ from fastmcp.utilities.json_schema import compress_schema
 from fastmcp.utilities.types import (
     _convert_set_defaults,
     find_kwarg_by_type,
+    get_cached_typeadapter,
 )
 
 
@@ -97,7 +97,7 @@ class ResourceTemplate(BaseModel):
         """Create a template from a function."""
         from fastmcp.server.context import Context
 
-        func_name = name or fn.__name__
+        func_name = name or getattr(fn, "__name__", None) or fn.__class__.__name__
         if func_name == "<lambda>":
             raise ValueError("You must provide a name for lambda functions")
 
@@ -148,8 +148,13 @@ class ResourceTemplate(BaseModel):
                     f"URI parameters {uri_params} must be a subset of the function arguments: {func_params}"
                 )
 
-        # Get schema from TypeAdapter - will fail if function isn't properly typed
-        parameters = TypeAdapter(fn).json_schema()
+        description = description or fn.__doc__ or ""
+
+        if not inspect.isroutine(fn):
+            fn = fn.__call__
+
+        type_adapter = get_cached_typeadapter(fn)
+        parameters = type_adapter.json_schema()
 
         # compress the schema
         prune_params = [context_kwarg] if context_kwarg else None
@@ -161,7 +166,7 @@ class ResourceTemplate(BaseModel):
         return cls(
             uri_template=uri_template,
             name=func_name,
-            description=description or fn.__doc__ or "",
+            description=description,
             mime_type=mime_type or "text/plain",
             fn=fn,
             parameters=parameters,

fastmcp/server/context.py

@@ -12,6 +12,8 @@ from mcp.shared.context import RequestContext
 from mcp.types import (
     CreateMessageResult,
     ImageContent,
+    ModelHint,
+    ModelPreferences,
     Root,
     SamplingMessage,
     TextContent,
@@ -200,6 +202,7 @@ class Context:
         system_prompt: str | None = None,
         temperature: float | None = None,
         max_tokens: int | None = None,
+        model_preferences: ModelPreferences | str | list[str] | None = None,
     ) -> TextContent | ImageContent:
         """
         Send a sampling request to the client and await the response.
@@ -231,6 +234,7 @@ class Context:
             system_prompt=system_prompt,
             temperature=temperature,
             max_tokens=max_tokens,
+            model_preferences=self._parse_model_preferences(model_preferences),
         )
 
         return result.content
@@ -248,3 +252,45 @@ class Context:
         )
 
         return fastmcp.server.dependencies.get_http_request()
+
+    def _parse_model_preferences(
+        self, model_preferences: ModelPreferences | str | list[str] | None
+    ) -> ModelPreferences | None:
+        """
+        Validates and converts user input for model_preferences into a ModelPreferences object.
+
+        Args:
+            model_preferences (ModelPreferences | str | list[str] | None):
+                The model preferences to use. Accepts:
+                - ModelPreferences (returns as-is)
+                - str (single model hint)
+                - list[str] (multiple model hints)
+                - None (no preferences)
+
+        Returns:
+            ModelPreferences | None: The parsed ModelPreferences object, or None if not provided.
+
+        Raises:
+            ValueError: If the input is not a supported type or contains invalid values.
+        """
+        if model_preferences is None:
+            return None
+        elif isinstance(model_preferences, ModelPreferences):
+            return model_preferences
+        elif isinstance(model_preferences, str):
+            # Single model hint
+            return ModelPreferences(hints=[ModelHint(name=model_preferences)])
+        elif isinstance(model_preferences, list):
+            # List of model hints (strings)
+            if not all(isinstance(h, str) for h in model_preferences):
+                raise ValueError(
+                    "All elements of model_preferences list must be"
+                    " strings (model name hints)."
+                )
+            return ModelPreferences(
+                hints=[ModelHint(name=h) for h in model_preferences]
+            )
+        else:
+            raise ValueError(
+                "model_preferences must be one of: ModelPreferences, str, list[str], or None."
+            )

fastmcp/server/http.py

@@ -241,6 +241,7 @@ def create_sse_app(
     # Add custom routes with lowest precedence
     if routes:
         server_routes.extend(routes)
+    server_routes.extend(server._additional_http_routes)
 
     # Add middleware
     if middleware:
@@ -359,6 +360,7 @@ def create_streamable_http_app(
     # Add custom routes with lowest precedence
     if routes:
         server_routes.extend(routes)
+    server_routes.extend(server._additional_http_routes)
 
     # Add middleware
     if middleware: