fastmcp 2.2.6__py3-none-any.whl → 2.2.8__py3-none-any.whl

fastmcp/client/client.py

@@ -1,7 +1,7 @@
 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
@@ -107,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()
@@ -128,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:
@@ -159,66 +237,191 @@ 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)
-        return result.messages
+    ) -> mcp.types.GetPromptResult:
+        """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:
+            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.get_prompt_mcp(name=name, arguments=arguments)
+        return result
+
+    # --- 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/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/__init__.py

@@ -1,4 +1,9 @@
-from .prompt import Prompt, Message, UserMessage, AssistantMessage
+from .prompt import Prompt, PromptMessage, Message
 from .prompt_manager import PromptManager
 
-__all__ = ["Prompt", "PromptManager", "Message", "UserMessage", "AssistantMessage"]
+__all__ = [
+    "Prompt",
+    "PromptManager",
+    "PromptMessage",
+    "Message",
+]

fastmcp/prompts/prompt.py

@@ -3,17 +3,21 @@
 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
+from typing import TYPE_CHECKING, Annotated, Any
 
 import pydantic_core
-from mcp.types import EmbeddedResource, ImageContent, TextContent
+from mcp.types import EmbeddedResource, ImageContent, PromptMessage, Role, TextContent
 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.json_schema import prune_params
+from fastmcp.utilities.types import (
+    _convert_set_defaults,
+    find_kwarg_by_type,
+    get_cached_typeadapter,
+)
 
 if TYPE_CHECKING:
     from mcp.server.session import ServerSessionT
@@ -24,32 +28,24 @@ if TYPE_CHECKING:
 CONTENT_TYPES = TextContent | ImageContent | EmbeddedResource
 
 
-class Message(BaseModel):
-    """Base class for all prompt messages."""
-
-    role: Literal["user", "assistant"]
-    content: CONTENT_TYPES
-
-    def __init__(self, content: str | CONTENT_TYPES, **kwargs: Any):
-        if isinstance(content, str):
-            content = TextContent(type="text", text=content)
-        super().__init__(content=content, **kwargs)
-
-
-def UserMessage(content: str | CONTENT_TYPES, **kwargs: Any) -> Message:
-    """A message from the user."""
-    return Message(content=content, role="user", **kwargs)
+def Message(
+    content: str | CONTENT_TYPES, role: Role | None = None, **kwargs: Any
+) -> PromptMessage:
+    """A user-friendly constructor for PromptMessage."""
+    if isinstance(content, str):
+        content = TextContent(type="text", text=content)
+    if role is None:
+        role = "user"
+    return PromptMessage(content=content, role=role, **kwargs)
 
 
-def AssistantMessage(content: str | CONTENT_TYPES, **kwargs: Any) -> Message:
-    """A message from the assistant."""
-    return Message(content=content, role="assistant", **kwargs)
-
-
-message_validator = TypeAdapter[Message](Message)
+message_validator = TypeAdapter[PromptMessage](PromptMessage)
 
 SyncPromptResult = (
-    str | Message | dict[str, Any] | Sequence[str | Message | dict[str, Any]]
+    str
+    | PromptMessage
+    | dict[str, Any]
+    | Sequence[str | PromptMessage | dict[str, Any]]
 )
 PromptResult = SyncPromptResult | Awaitable[SyncPromptResult]
 
@@ -107,35 +103,32 @@ class Prompt(BaseModel):
 
         if func_name == "<lambda>":
             raise ValueError("You must provide a name for lambda functions")
+            # Reject functions with *args or **kwargs
+        sig = inspect.signature(fn)
+        for param in sig.parameters.values():
+            if param.kind == inspect.Parameter.VAR_POSITIONAL:
+                raise ValueError("Functions with *args are not supported as prompts")
+            if param.kind == inspect.Parameter.VAR_KEYWORD:
+                raise ValueError("Functions with **kwargs are not supported as prompts")
+
+        type_adapter = get_cached_typeadapter(fn)
+        parameters = type_adapter.json_schema()
 
         # Auto-detect context parameter if not provided
         if context_kwarg is None:
-            if inspect.ismethod(fn) and hasattr(fn, "__func__"):
-                sig = inspect.signature(fn.__func__)
-            else:
-                sig = inspect.signature(fn)
-            for param_name, param in sig.parameters.items():
-                if param.annotation is Context:
-                    context_kwarg = param_name
-                    break
-
-        # Get schema from TypeAdapter - will fail if function isn't properly typed
-        parameters = TypeAdapter(fn).json_schema()
+            context_kwarg = find_kwarg_by_type(fn, kwarg_type=Context)
+        if context_kwarg:
+            parameters = prune_params(parameters, params=[context_kwarg])
 
         # Convert parameters to PromptArguments
         arguments: list[PromptArgument] = []
         if "properties" in parameters:
             for param_name, param in parameters["properties"].items():
-                # Skip context parameter
-                if param_name == context_kwarg:
-                    continue
-
-                required = param_name in parameters.get("required", [])
                 arguments.append(
                     PromptArgument(
                         name=param_name,
                         description=param.get("description"),
-                        required=required,
+                        required=param_name in parameters.get("required", []),
                     )
                 )
 
@@ -155,7 +148,7 @@ class Prompt(BaseModel):
         self,
         arguments: dict[str, Any] | None = None,
         context: Context[ServerSessionT, LifespanContextT] | None = None,
-    ) -> list[Message]:
+    ) -> list[PromptMessage]:
         """Render the prompt with arguments."""
         # Validate required arguments
         if self.arguments:
@@ -181,19 +174,28 @@ class Prompt(BaseModel):
                 result = [result]
 
             # Convert result to messages
-            messages: list[Message] = []
-            for msg in result:  # type: ignore[reportUnknownVariableType]
+            messages: list[PromptMessage] = []
+            for msg in result:
                 try:
-                    if isinstance(msg, Message):
+                    if isinstance(msg, PromptMessage):
                         messages.append(msg)
-                    elif isinstance(msg, dict):
-                        messages.append(message_validator.validate_python(msg))
                     elif isinstance(msg, str):
-                        content = TextContent(type="text", text=msg)
-                        messages.append(Message(role="user", content=content))
+                        messages.append(
+                            PromptMessage(
+                                role="user",
+                                content=TextContent(type="text", text=msg),
+                            )
+                        )
                     else:
-                        content = json.dumps(pydantic_core.to_jsonable_python(msg))
-                        messages.append(Message(role="user", content=content))
+                        content = pydantic_core.to_json(
+                            msg, fallback=str, indent=2
+                        ).decode()
+                        messages.append(
+                            PromptMessage(
+                                role="user",
+                                content=TextContent(type="text", text=content),
+                            )
+                        )
                 except Exception:
                     raise ValueError(
                         f"Could not convert prompt result to message: {msg}"

fastmcp/prompts/prompt_manager.py

@@ -5,8 +5,10 @@ from __future__ import annotations as _annotations
 from collections.abc import Awaitable, Callable
 from typing import TYPE_CHECKING, Any
 
+from mcp import GetPromptResult
+
 from fastmcp.exceptions import NotFoundError
-from fastmcp.prompts.prompt import Message, Prompt, PromptResult
+from fastmcp.prompts.prompt import Prompt, PromptResult
 from fastmcp.settings import DuplicateBehavior
 from fastmcp.utilities.logging import get_logger
 
@@ -81,13 +83,18 @@ class PromptManager:
         name: str,
         arguments: dict[str, Any] | None = None,
         context: Context[ServerSessionT, LifespanContextT] | None = None,
-    ) -> list[Message]:
+    ) -> GetPromptResult:
         """Render a prompt by name with arguments."""
         prompt = self.get_prompt(name)
         if not prompt:
             raise NotFoundError(f"Unknown prompt: {name}")
 
-        return await prompt.render(arguments, context=context)
+        messages = await prompt.render(arguments, context=context)
+
+        return GetPromptResult(
+            description=prompt.description,
+            messages=messages,
+        )
 
     def has_prompt(self, key: str) -> bool:
         """Check if a prompt exists."""

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,
+    find_kwarg_by_type,
+)
 
 if TYPE_CHECKING:
     from mcp.server.session import ServerSessionT
@@ -106,23 +109,25 @@ class ResourceTemplate(BaseModel):
         if func_name == "<lambda>":
             raise ValueError("You must provide a name for lambda functions")
 
+        # Reject functions with *args
+        # (**kwargs is allowed because the URI will define the parameter names)
+        sig = inspect.signature(fn)
+        for param in sig.parameters.values():
+            if param.kind == inspect.Parameter.VAR_POSITIONAL:
+                raise ValueError(
+                    "Functions with *args are not supported as resource templates"
+                )
+
         # Auto-detect context parameter if not provided
         if context_kwarg is None:
-            if inspect.ismethod(fn) and hasattr(fn, "__func__"):
-                sig = inspect.signature(fn.__func__)
-            else:
-                sig = inspect.signature(fn)
-            for param_name, param in sig.parameters.items():
-                if param.annotation is Context:
-                    context_kwarg = param_name
-                    break
+            context_kwarg = find_kwarg_by_type(fn, kwarg_type=Context)
 
         # Validate that URI params match function params
         uri_params = set(re.findall(r"{(\w+)(?:\*)?}", uri_template))
         if not uri_params:
             raise ValueError("URI template must contain at least one parameter")
 
-        func_params = set(inspect.signature(fn).parameters.keys())
+        func_params = set(sig.parameters.keys())
         if context_kwarg:
             func_params.discard(context_kwarg)
 
@@ -130,20 +135,26 @@ class ResourceTemplate(BaseModel):
         required_params = {
             p
             for p in func_params
-            if inspect.signature(fn).parameters[p].default is inspect.Parameter.empty
+            if sig.parameters[p].default is inspect.Parameter.empty
+            and sig.parameters[p].kind != inspect.Parameter.VAR_KEYWORD
+            and p != context_kwarg
         }
-        if context_kwarg and context_kwarg in required_params:
-            required_params.discard(context_kwarg)
 
+        # Check if required parameters are a subset of the URI parameters
         if not required_params.issubset(uri_params):
             raise ValueError(
-                f"URI parameters {uri_params} must be a subset of the required function arguments: {required_params}"
+                f"Required function arguments {required_params} must be a subset of the URI parameters {uri_params}"
             )
 
-        if not uri_params.issubset(func_params):
-            raise ValueError(
-                f"URI parameters {uri_params} must be a subset of the function arguments: {func_params}"
-            )
+        # Check if the URI parameters are a subset of the function parameters (skip if **kwargs present)
+        if not any(
+            param.kind == inspect.Parameter.VAR_KEYWORD
+            for param in sig.parameters.values()
+        ):
+            if not uri_params.issubset(func_params):
+                raise ValueError(
+                    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()