fastmcp 2.2.5__py3-none-any.whl → 2.2.7__py3-none-any.whl

fastmcp/__init__.py

@@ -14,6 +14,7 @@ __all__ = [
     "FastMCP",
     "Context",
     "client",
+    "Client",
     "settings",
     "Image",
 ]

fastmcp/client/base.py

@@ -1 +0,0 @@
-

fastmcp/client/client.py

@@ -1,16 +1,13 @@
 import datetime
 from contextlib import AbstractAsyncContextManager
 from pathlib import Path
-from typing import Any, Literal, cast, overload
+from typing import Any, cast
 
 import mcp.types
 from mcp import ClientSession
-from mcp.client.session import (
-    LoggingFnT,
-    MessageHandlerFnT,
-)
 from pydantic import AnyUrl
 
+from fastmcp.client.logging import LogHandler, MessageHandler
 from fastmcp.client.roots import (
     RootsHandler,
     RootsList,
@@ -22,7 +19,14 @@ from fastmcp.server import FastMCP
 
 from .transports import ClientTransport, SessionKwargs, infer_transport
 
-__all__ = ["Client", "RootsHandler", "RootsList"]
+__all__ = [
+    "Client",
+    "RootsHandler",
+    "RootsList",
+    "LogHandler",
+    "MessageHandler",
+    "SamplingHandler",
+]
 
 
 class Client:
@@ -35,12 +39,12 @@ class Client:
 
     def __init__(
         self,
-        transport: ClientTransport | FastMCP | AnyUrl | Path | str,
+        transport: ClientTransport | FastMCP | AnyUrl | Path | dict[str, Any] | str,
         # Common args
         roots: RootsList | RootsHandler | None = None,
         sampling_handler: SamplingHandler | None = None,
-        log_handler: LoggingFnT | None = None,
-        message_handler: MessageHandlerFnT | None = None,
+        log_handler: LogHandler | None = None,
+        message_handler: MessageHandler | None = None,
         read_timeout_seconds: datetime.timedelta | None = None,
     ):
         self.transport = infer_transport(transport)
@@ -103,6 +107,7 @@ class Client:
             self._session = None
 
     # --- MCP Client Methods ---
+
     async def ping(self) -> None:
         """Send a ping request."""
         await self.session.send_ping()
@@ -124,23 +129,100 @@ class Client:
         """Send a roots/list_changed notification."""
         await self.session.send_roots_list_changed()
 
-    async def list_resources(self) -> list[mcp.types.Resource]:
-        """Send a resources/list request."""
+    # --- Resources ---
+
+    async def list_resources_mcp(self) -> mcp.types.ListResourcesResult:
+        """Send a resources/list request and return the complete MCP protocol result.
+
+        Returns:
+            mcp.types.ListResourcesResult: The complete response object from the protocol,
+                containing the list of resources and any additional metadata.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+        """
         result = await self.session.list_resources()
+        return result
+
+    async def list_resources(self) -> list[mcp.types.Resource]:
+        """Retrieve a list of resources available on the server.
+
+        Returns:
+            list[mcp.types.Resource]: A list of Resource objects.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+        """
+        result = await self.list_resources_mcp()
         return result.resources
 
-    async def list_resource_templates(self) -> list[mcp.types.ResourceTemplate]:
-        """Send a resources/listResourceTemplates request."""
+    async def list_resource_templates_mcp(
+        self,
+    ) -> mcp.types.ListResourceTemplatesResult:
+        """Send a resources/listResourceTemplates request and return the complete MCP protocol result.
+
+        Returns:
+            mcp.types.ListResourceTemplatesResult: The complete response object from the protocol,
+                containing the list of resource templates and any additional metadata.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+        """
         result = await self.session.list_resource_templates()
+        return result
+
+    async def list_resource_templates(
+        self,
+    ) -> list[mcp.types.ResourceTemplate]:
+        """Retrieve a list of resource templates available on the server.
+
+        Returns:
+            list[mcp.types.ResourceTemplate]: A list of ResourceTemplate objects.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+        """
+        result = await self.list_resource_templates_mcp()
         return result.resourceTemplates
 
+    async def read_resource_mcp(
+        self, uri: AnyUrl | str
+    ) -> mcp.types.ReadResourceResult:
+        """Send a resources/read request and return the complete MCP protocol result.
+
+        Args:
+            uri (AnyUrl | str): The URI of the resource to read. Can be a string or an AnyUrl object.
+
+        Returns:
+            mcp.types.ReadResourceResult: The complete response object from the protocol,
+                containing the resource contents and any additional metadata.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+        """
+        if isinstance(uri, str):
+            uri = AnyUrl(uri)  # Ensure AnyUrl
+        result = await self.session.read_resource(uri)
+        return result
+
     async def read_resource(
         self, uri: AnyUrl | str
     ) -> list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents]:
-        """Send a resources/read request."""
+        """Read the contents of a resource or resolved template.
+
+        Args:
+            uri (AnyUrl | str): The URI of the resource to read. Can be a string or an AnyUrl object.
+
+        Returns:
+            list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents]: A list of content
+                objects, typically containing either text or binary data.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+        """
         if isinstance(uri, str):
             uri = AnyUrl(uri)  # Ensure AnyUrl
-        result = await self.session.read_resource(uri)
+        result = await self.read_resource_mcp(uri)
         return result.contents
 
     # async def subscribe_resource(self, uri: AnyUrl | str) -> None:
@@ -155,66 +237,190 @@ class Client:
     #         uri = AnyUrl(uri)
     #     await self.session.unsubscribe_resource(uri)
 
-    async def list_prompts(self) -> list[mcp.types.Prompt]:
-        """Send a prompts/list request."""
+    # --- Prompts ---
+
+    async def list_prompts_mcp(self) -> mcp.types.ListPromptsResult:
+        """Send a prompts/list request and return the complete MCP protocol result.
+
+        Returns:
+            mcp.types.ListPromptsResult: The complete response object from the protocol,
+                containing the list of prompts and any additional metadata.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+        """
         result = await self.session.list_prompts()
+        return result
+
+    async def list_prompts(self) -> list[mcp.types.Prompt]:
+        """Retrieve a list of prompts available on the server.
+
+        Returns:
+            list[mcp.types.Prompt]: A list of Prompt objects.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+        """
+        result = await self.list_prompts_mcp()
         return result.prompts
 
+    # --- Prompt ---
+    async def get_prompt_mcp(
+        self, name: str, arguments: dict[str, str] | None = None
+    ) -> mcp.types.GetPromptResult:
+        """Send a prompts/get request and return the complete MCP protocol result.
+
+        Args:
+            name (str): The name of the prompt to retrieve.
+            arguments (dict[str, str] | None, optional): Arguments to pass to the prompt. Defaults to None.
+
+        Returns:
+            mcp.types.GetPromptResult: The complete response object from the protocol,
+                containing the prompt messages and any additional metadata.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+        """
+        result = await self.session.get_prompt(name=name, arguments=arguments)
+        return result
+
     async def get_prompt(
         self, name: str, arguments: dict[str, str] | None = None
     ) -> list[mcp.types.PromptMessage]:
-        """Send a prompts/get request."""
-        result = await self.session.get_prompt(name, arguments)
+        """Retrieve a rendered prompt message list from the server.
+
+        Args:
+            name (str): The name of the prompt to retrieve.
+            arguments (dict[str, str] | None, optional): Arguments to pass to the prompt. Defaults to None.
+
+        Returns:
+            list[mcp.types.PromptMessage]: A list of prompt messages.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+        """
+        result = await self.get_prompt_mcp(name=name, arguments=arguments)
         return result.messages
 
+    # --- Completion ---
+
+    async def complete_mcp(
+        self,
+        ref: mcp.types.ResourceReference | mcp.types.PromptReference,
+        argument: dict[str, str],
+    ) -> mcp.types.CompleteResult:
+        """Send a completion request and return the complete MCP protocol result.
+
+        Args:
+            ref (mcp.types.ResourceReference | mcp.types.PromptReference): The reference to complete.
+            argument (dict[str, str]): Arguments to pass to the completion request.
+
+        Returns:
+            mcp.types.CompleteResult: The complete response object from the protocol,
+                containing the completion and any additional metadata.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+        """
+        result = await self.session.complete(ref=ref, argument=argument)
+        return result
+
     async def complete(
         self,
         ref: mcp.types.ResourceReference | mcp.types.PromptReference,
         argument: dict[str, str],
     ) -> mcp.types.Completion:
-        """Send a completion request."""
-        result = await self.session.complete(ref, argument)
+        """Send a completion request to the server.
+
+        Args:
+            ref (mcp.types.ResourceReference | mcp.types.PromptReference): The reference to complete.
+            argument (dict[str, str]): Arguments to pass to the completion request.
+
+        Returns:
+            mcp.types.Completion: The completion object.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+        """
+        result = await self.complete_mcp(ref=ref, argument=argument)
         return result.completion
 
-    async def list_tools(self) -> list[mcp.types.Tool]:
-        """Send a tools/list request."""
+    # --- Tools ---
+
+    async def list_tools_mcp(self) -> mcp.types.ListToolsResult:
+        """Send a tools/list request and return the complete MCP protocol result.
+
+        Returns:
+            mcp.types.ListToolsResult: The complete response object from the protocol,
+                containing the list of tools and any additional metadata.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+        """
         result = await self.session.list_tools()
+        return result
+
+    async def list_tools(self) -> list[mcp.types.Tool]:
+        """Retrieve a list of tools available on the server.
+
+        Returns:
+            list[mcp.types.Tool]: A list of Tool objects.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+        """
+        result = await self.list_tools_mcp()
         return result.tools
 
-    @overload
+    # --- Call Tool ---
+
+    async def call_tool_mcp(
+        self, name: str, arguments: dict[str, Any]
+    ) -> mcp.types.CallToolResult:
+        """Send a tools/call request and return the complete MCP protocol result.
+
+        This method returns the raw CallToolResult object, which includes an isError flag
+        and other metadata. It does not raise an exception if the tool call results in an error.
+
+        Args:
+            name (str): The name of the tool to call.
+            arguments (dict[str, Any]): Arguments to pass to the tool.
+
+        Returns:
+            mcp.types.CallToolResult: The complete response object from the protocol,
+                containing the tool result and any additional metadata.
+
+        Raises:
+            RuntimeError: If called while the client is not connected.
+        """
+        result = await self.session.call_tool(name=name, arguments=arguments)
+        return result
+
     async def call_tool(
         self,
         name: str,
         arguments: dict[str, Any] | None = None,
-        _return_raw_result: Literal[False] = False,
     ) -> list[
         mcp.types.TextContent | mcp.types.ImageContent | mcp.types.EmbeddedResource
-    ]: ...
+    ]:
+        """Call a tool on the server.
 
-    @overload
-    async def call_tool(
-        self,
-        name: str,
-        arguments: dict[str, Any] | None = None,
-        _return_raw_result: Literal[True] = True,
-    ) -> mcp.types.CallToolResult: ...
+        Unlike call_tool_mcp, this method raises a ClientError if the tool call results in an error.
 
-    async def call_tool(
-        self,
-        name: str,
-        arguments: dict[str, Any] | None = None,
-        _return_raw_result: bool = False,
-    ) -> (
-        list[
-            mcp.types.TextContent | mcp.types.ImageContent | mcp.types.EmbeddedResource
-        ]
-        | mcp.types.CallToolResult
-    ):
-        """Send a tools/call request."""
-        result = await self.session.call_tool(name, arguments)
-        if _return_raw_result:
-            return result
-        elif result.isError:
+        Args:
+            name (str): The name of the tool to call.
+            arguments (dict[str, Any] | None, optional): Arguments to pass to the tool. Defaults to None.
+
+        Returns:
+            list[mcp.types.TextContent | mcp.types.ImageContent | mcp.types.EmbeddedResource]:
+                The content returned by the tool.
+
+        Raises:
+            ClientError: If the tool call results in an error.
+            RuntimeError: If called while the client is not connected.
+        """
+        result = await self.call_tool_mcp(name=name, arguments=arguments or {})
+        if result.isError:
             msg = cast(mcp.types.TextContent, result.content[0]).text
             raise ClientError(msg)
         return result.content

fastmcp/client/logging.py

@@ -0,0 +1,13 @@
+from typing import TypeAlias
+
+from mcp.client.session import (
+    LoggingFnT,
+    MessageHandlerFnT,
+)
+from mcp.types import LoggingMessageNotificationParams
+
+LogMessage: TypeAlias = LoggingMessageNotificationParams
+LogHandler: TypeAlias = LoggingFnT
+MessageHandler: TypeAlias = MessageHandlerFnT
+
+__all__ = ["LogMessage", "LogHandler", "MessageHandler"]

fastmcp/client/sampling.py

@@ -9,6 +9,8 @@ from mcp.shared.context import LifespanContextT, RequestContext
 from mcp.types import CreateMessageRequestParams as SamplingParams
 from mcp.types import SamplingMessage
 
+__all__ = ["SamplingMessage", "SamplingParams", "MessageResult", "SamplingHandler"]
+
 
 class MessageResult(CreateMessageResult):
     role: mcp.types.Role = "assistant"

fastmcp/client/transports.py

@@ -6,9 +6,7 @@ import shutil
 import sys
 from collections.abc import AsyncIterator
 from pathlib import Path
-from typing import (
-    TypedDict,
-)
+from typing import Any, TypedDict
 
 from exceptiongroup import BaseExceptionGroup, catch
 from mcp import ClientSession, McpError, StdioServerParameters
@@ -416,7 +414,7 @@ class FastMCPTransport(ClientTransport):
 
 
 def infer_transport(
-    transport: ClientTransport | FastMCPServer | AnyUrl | Path | str,
+    transport: ClientTransport | FastMCPServer | AnyUrl | Path | dict[str, Any] | str,
 ) -> ClientTransport:
     """
     Infer the appropriate transport type from the given transport argument.
@@ -450,6 +448,41 @@ def infer_transport(
     elif isinstance(transport, AnyUrl | str) and str(transport).startswith("ws"):
         return WSTransport(url=transport)
 
+    ## if the transport is a config dict
+    elif isinstance(transport, dict):
+        if "mcpServers" not in transport:
+            raise ValueError("Invalid transport dictionary: missing 'mcpServers' key")
+        else:
+            server = transport["mcpServers"]
+            if len(list(server.keys())) > 1:
+                raise ValueError(
+                    "Invalid transport dictionary: multiple servers found - only one expected"
+                )
+            server_name = list(server.keys())[0]
+            # Stdio transport
+            if "command" in server[server_name] and "args" in server[server_name]:
+                return StdioTransport(
+                    command=server[server_name]["command"],
+                    args=server[server_name]["args"],
+                    env=server[server_name].get("env", None),
+                    cwd=server[server_name].get("cwd", None),
+                )
+
+            # HTTP transport
+            elif "url" in server:
+                return SSETransport(
+                    url=server["url"],
+                    headers=server.get("headers", None),
+                )
+
+            # WebSocket transport
+            elif "ws_url" in server:
+                return WSTransport(
+                    url=server["ws_url"],
+                )
+
+            raise ValueError("Cannot determine transport type from dictionary")
+
     # the transport is an unknown type
     else:
         raise ValueError(f"Could not infer a valid transport from: {transport}")

fastmcp/contrib/bulk_tool_caller/bulk_tool_caller.py

@@ -123,9 +123,7 @@ class BulkToolCaller(MCPMixin):
         """
 
         async with Client(self.connection) as client:
-            result = await client.call_tool(
-                name=tool, arguments=arguments, _return_raw_result=True
-            )
+            result = await client.call_tool_mcp(name=tool, arguments=arguments)
 
             return CallToolRequestResult(
                 tool=tool,

fastmcp/prompts/prompt.py

@@ -3,7 +3,6 @@
 from __future__ import annotations as _annotations
 
 import inspect
-import json
 from collections.abc import Awaitable, Callable, Sequence
 from typing import TYPE_CHECKING, Annotated, Any, Literal
 
@@ -13,7 +12,10 @@ 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.utilities.types import _convert_set_defaults
+from fastmcp.utilities.types import (
+    _convert_set_defaults,
+    is_class_member_of_type,
+)
 
 if TYPE_CHECKING:
     from mcp.server.session import ServerSessionT
@@ -115,7 +117,7 @@ class Prompt(BaseModel):
             else:
                 sig = inspect.signature(fn)
             for param_name, param in sig.parameters.items():
-                if param.annotation is Context:
+                if is_class_member_of_type(param.annotation, Context):
                     context_kwarg = param_name
                     break
 
@@ -192,7 +194,9 @@ class Prompt(BaseModel):
                         content = TextContent(type="text", text=msg)
                         messages.append(Message(role="user", content=content))
                     else:
-                        content = json.dumps(pydantic_core.to_jsonable_python(msg))
+                        content = pydantic_core.to_json(
+                            msg, fallback=str, indent=2
+                        ).decode()
                         messages.append(Message(role="user", content=content))
                 except Exception:
                     raise ValueError(

fastmcp/resources/template.py

@@ -20,7 +20,10 @@ from pydantic import (
 )
 
 from fastmcp.resources.types import FunctionResource, Resource
-from fastmcp.utilities.types import _convert_set_defaults
+from fastmcp.utilities.types import (
+    _convert_set_defaults,
+    is_class_member_of_type,
+)
 
 if TYPE_CHECKING:
     from mcp.server.session import ServerSessionT
@@ -113,7 +116,7 @@ class ResourceTemplate(BaseModel):
             else:
                 sig = inspect.signature(fn)
             for param_name, param in sig.parameters.items():
-                if param.annotation is Context:
+                if is_class_member_of_type(param.annotation, Context):
                     context_kwarg = param_name
                     break
 

fastmcp/resources/types.py

@@ -97,15 +97,12 @@ class FunctionResource(Resource):
 
             if isinstance(result, Resource):
                 return await result.read(context=context)
-            if isinstance(result, bytes):
+            elif isinstance(result, bytes):
                 return result
-            if isinstance(result, str):
+            elif isinstance(result, str):
                 return result
-            try:
-                return json.dumps(pydantic_core.to_jsonable_python(result))
-            except (TypeError, pydantic_core.PydanticSerializationError):
-                # If JSON serialization fails, try str()
-                return str(result)
+            else:
+                return pydantic_core.to_json(result, fallback=str, indent=2).decode()
         except Exception as e:
             raise ValueError(f"Error reading resource {self.uri}: {e}")
 

fastmcp/server/context.py

@@ -1,7 +1,8 @@
 from __future__ import annotations as _annotations
 
-from typing import Any, Generic, Literal
+from typing import Any, Generic
 
+from mcp import LoggingLevel
 from mcp.server.lowlevel.helper_types import ReadResourceContents
 from mcp.server.session import ServerSessionT
 from mcp.shared.context import LifespanContextT, RequestContext
@@ -12,10 +13,12 @@ from mcp.types import (
     SamplingMessage,
     TextContent,
 )
-from pydantic import BaseModel
+from pydantic import BaseModel, ConfigDict
 from pydantic.networks import AnyUrl
+from starlette.requests import Request
 
 from fastmcp.server.server import FastMCP
+from fastmcp.utilities.http import get_current_starlette_request
 from fastmcp.utilities.logging import get_logger
 
 logger = get_logger(__name__)
@@ -58,6 +61,8 @@ class Context(BaseModel, Generic[ServerSessionT, LifespanContextT]):
     _request_context: RequestContext[ServerSessionT, LifespanContextT] | None
     _fastmcp: FastMCP | None
 
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
     def __init__(
         self,
         *,
@@ -122,19 +127,20 @@ class Context(BaseModel, Generic[ServerSessionT, LifespanContextT]):
 
     async def log(
         self,
-        level: Literal["debug", "info", "warning", "error"],
         message: str,
-        *,
+        level: LoggingLevel | None = None,
         logger_name: str | None = None,
     ) -> None:
         """Send a log message to the client.
 
         Args:
-            level: Log level (debug, info, warning, error)
             message: Log message
+            level: Optional log level. One of "debug", "info", "notice", "warning", "error", "critical",
+                "alert", or "emergency". Default is "info".
             logger_name: Optional logger name
-            **extra: Additional structured data to include
         """
+        if level is None:
+            level = "info"
         await self.request_context.session.send_log_message(
             level=level, data=message, logger=logger_name
         )
@@ -159,21 +165,21 @@ class Context(BaseModel, Generic[ServerSessionT, LifespanContextT]):
         return self.request_context.session
 
     # Convenience methods for common log levels
-    async def debug(self, message: str, **extra: Any) -> None:
+    async def debug(self, message: str, logger_name: str | None = None) -> None:
         """Send a debug log message."""
-        await self.log("debug", message, **extra)
+        await self.log(level="debug", message=message, logger_name=logger_name)
 
-    async def info(self, message: str, **extra: Any) -> None:
+    async def info(self, message: str, logger_name: str | None = None) -> None:
         """Send an info log message."""
-        await self.log("info", message, **extra)
+        await self.log(level="info", message=message, logger_name=logger_name)
 
-    async def warning(self, message: str, **extra: Any) -> None:
+    async def warning(self, message: str, logger_name: str | None = None) -> None:
         """Send a warning log message."""
-        await self.log("warning", message, **extra)
+        await self.log(level="warning", message=message, logger_name=logger_name)
 
-    async def error(self, message: str, **extra: Any) -> None:
+    async def error(self, message: str, logger_name: str | None = None) -> None:
         """Send an error log message."""
-        await self.log("error", message, **extra)
+        await self.log(level="error", message=message, logger_name=logger_name)
 
     async def list_roots(self) -> list[Root]:
         """List the roots available to the server, as indicated by the client."""
@@ -220,3 +226,10 @@ class Context(BaseModel, Generic[ServerSessionT, LifespanContextT]):
         )
 
         return result.content
+
+    def get_http_request(self) -> Request:
+        """Get the active starlette request."""
+        request = get_current_starlette_request()
+        if request is None:
+            raise ValueError("Request is not available outside a Starlette request")
+        return request