Merge branch 'main' into praboud/auth

Author: ihrpr

pyproject.toml

@@ -53,6 +53,7 @@ dev = [
     "pytest-flakefinder>=1.1.0",
     "pytest-xdist>=3.6.1",
     "pytest-examples>=0.0.14",
+    "pytest-pretty>=1.2.0",
 ]
 docs = [
     "mkdocs>=1.6.1",

src/mcp/client/session.py

@@ -254,7 +254,10 @@ async def unsubscribe_resource(self, uri: AnyUrl) -> types.EmptyResult:
         )
 
     async def call_tool(
-        self, name: str, arguments: dict[str, Any] | None = None
+        self,
+        name: str,
+        arguments: dict[str, Any] | None = None,
+        read_timeout_seconds: timedelta | None = None,
     ) -> types.CallToolResult:
         """Send a tools/call request."""
         return await self.send_request(
@@ -265,6 +268,7 @@ async def call_tool(
                 )
             ),
             types.CallToolResult,
+            request_read_timeout_seconds=read_timeout_seconds,
         )
 
     async def list_prompts(self) -> types.ListPromptsResult:

src/mcp/server/fastmcp/prompts/base.py

@@ -1,7 +1,6 @@
 """Base classes for FastMCP prompts."""
 
 import inspect
-import json
 from collections.abc import Awaitable, Callable, Sequence
 from typing import Any, Literal
 
@@ -155,7 +154,9 @@ async def render(self, arguments: dict[str, Any] | None = None) -> list[Message]
                         content = TextContent(type="text", text=msg)
                         messages.append(UserMessage(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(

src/mcp/server/fastmcp/resources/types.py

@@ -9,7 +9,7 @@
 import anyio
 import anyio.to_thread
 import httpx
-import pydantic.json
+import pydantic
 import pydantic_core
 from pydantic import Field, ValidationInfo
 
@@ -59,15 +59,12 @@ async def read(self) -> str | bytes:
             )
             if isinstance(result, Resource):
                 return await result.read()
-            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}")
 

src/mcp/server/fastmcp/server.py

@@ -3,7 +3,6 @@
 from __future__ import annotations as _annotations
 
 import inspect
-import json
 import re
 from collections.abc import AsyncIterator, Awaitable, Callable, Iterable, Sequence
 from contextlib import (
@@ -55,6 +54,7 @@
     GetPromptResult,
     ImageContent,
     TextContent,
+    ToolAnnotations,
 )
 from mcp.types import Prompt as MCPPrompt
 from mcp.types import PromptArgument as MCPPromptArgument
@@ -210,6 +210,7 @@ async def list_tools(self) -> list[MCPTool]:
                 name=info.name,
                 description=info.description,
                 inputSchema=info.parameters,
+                annotations=info.annotations,
             )
             for info in tools
         ]
@@ -278,6 +279,7 @@ def add_tool(
         fn: AnyFunction,
         name: str | None = None,
         description: str | None = None,
+        annotations: ToolAnnotations | None = None,
     ) -> None:
         """Add a tool to the server.
 
@@ -288,11 +290,17 @@ def add_tool(
             fn: The function to register as a tool
             name: Optional name for the tool (defaults to function name)
             description: Optional description of what the tool does
+            annotations: Optional ToolAnnotations providing additional tool information
         """
-        self._tool_manager.add_tool(fn, name=name, description=description)
+        self._tool_manager.add_tool(
+            fn, name=name, description=description, annotations=annotations
+        )
 
     def tool(
-        self, name: str | None = None, description: str | None = None
+        self,
+        name: str | None = None,
+        description: str | None = None,
+        annotations: ToolAnnotations | None = None,
     ) -> Callable[[AnyFunction], AnyFunction]:
         """Decorator to register a tool.
 
@@ -303,6 +311,7 @@ def tool(
         Args:
             name: Optional name for the tool (defaults to function name)
             description: Optional description of what the tool does
+            annotations: Optional ToolAnnotations providing additional tool information
 
         Example:
             @server.tool()
@@ -327,7 +336,9 @@ async def async_tool(x: int, context: Context) -> str:
             )
 
         def decorator(fn: AnyFunction) -> AnyFunction:
-            self.add_tool(fn, name=name, description=description)
+            self.add_tool(
+                fn, name=name, description=description, annotations=annotations
+            )
             return fn
 
         return decorator
@@ -685,10 +696,7 @@ def _convert_to_content(
         return list(chain.from_iterable(_convert_to_content(item) for item in result))  # type: ignore[reportUnknownVariableType]
 
     if not isinstance(result, str):
-        try:
-            result = json.dumps(pydantic_core.to_jsonable_python(result))
-        except Exception:
-            result = str(result)
+        result = pydantic_core.to_json(result, fallback=str, indent=2).decode()
 
     return [TextContent(type="text", text=result)]
 

src/mcp/server/fastmcp/tools/base.py

@@ -8,6 +8,7 @@
 
 from mcp.server.fastmcp.exceptions import ToolError
 from mcp.server.fastmcp.utilities.func_metadata import FuncMetadata, func_metadata
+from mcp.types import ToolAnnotations
 
 if TYPE_CHECKING:
     from mcp.server.fastmcp.server import Context
@@ -30,6 +31,9 @@ class Tool(BaseModel):
     context_kwarg: str | None = Field(
         None, description="Name of the kwarg that should receive context"
     )
+    annotations: ToolAnnotations | None = Field(
+        None, description="Optional annotations for the tool"
+    )
 
     @classmethod
     def from_function(
@@ -38,9 +42,10 @@ def from_function(
         name: str | None = None,
         description: str | None = None,
         context_kwarg: str | None = None,
+        annotations: ToolAnnotations | None = None,
     ) -> Tool:
         """Create a Tool from a function."""
-        from mcp.server.fastmcp import Context
+        from mcp.server.fastmcp.server import Context
 
         func_name = name or fn.__name__
 
@@ -73,6 +78,7 @@ def from_function(
             fn_metadata=func_arg_metadata,
             is_async=is_async,
             context_kwarg=context_kwarg,
+            annotations=annotations,
         )
 
     async def run(

src/mcp/server/fastmcp/tools/tool_manager.py

@@ -7,6 +7,7 @@
 from mcp.server.fastmcp.tools.base import Tool
 from mcp.server.fastmcp.utilities.logging import get_logger
 from mcp.shared.context import LifespanContextT
+from mcp.types import ToolAnnotations
 
 if TYPE_CHECKING:
     from mcp.server.fastmcp.server import Context
@@ -35,9 +36,12 @@ def add_tool(
         fn: Callable[..., Any],
         name: str | None = None,
         description: str | None = None,
+        annotations: ToolAnnotations | None = None,
     ) -> Tool:
         """Add a tool to the server."""
-        tool = Tool.from_function(fn, name=name, description=description)
+        tool = Tool.from_function(
+            fn, name=name, description=description, annotations=annotations
+        )
         existing = self._tools.get(tool.name)
         if existing:
             if self.warn_on_duplicate_tools:

src/mcp/shared/session.py

@@ -185,7 +185,7 @@ def __init__(
         self._request_id = 0
         self._receive_request_type = receive_request_type
         self._receive_notification_type = receive_notification_type
-        self._read_timeout_seconds = read_timeout_seconds
+        self._session_read_timeout_seconds = read_timeout_seconds
         self._in_flight = {}
 
         self._exit_stack = AsyncExitStack()
@@ -213,10 +213,12 @@ async def send_request(
         self,
         request: SendRequestT,
         result_type: type[ReceiveResultT],
+        request_read_timeout_seconds: timedelta | None = None,
     ) -> ReceiveResultT:
         """
         Sends a request and wait for a response. Raises an McpError if the
-        response contains an error.
+        response contains an error. If a request read timeout is provided, it
+        will take precedence over the session read timeout.
 
         Do not use this method to emit notifications! Use send_notification()
         instead.
@@ -243,12 +245,15 @@ async def send_request(
 
         await self._write_stream.send(JSONRPCMessage(jsonrpc_request))
 
+        # request read timeout takes precedence over session read timeout
+        timeout = None
+        if request_read_timeout_seconds is not None:
+            timeout = request_read_timeout_seconds.total_seconds()
+        elif self._session_read_timeout_seconds is not None:
+            timeout = self._session_read_timeout_seconds.total_seconds()
+
         try:
-            with anyio.fail_after(
-                None
-                if self._read_timeout_seconds is None
-                else self._read_timeout_seconds.total_seconds()
-            ):
+            with anyio.fail_after(timeout):
                 response_or_error = await response_stream_reader.receive()
         except TimeoutError:
             raise McpError(
@@ -257,7 +262,7 @@ async def send_request(
                     message=(
                         f"Timed out while waiting for response to "
                         f"{request.__class__.__name__}. Waited "
-                        f"{self._read_timeout_seconds} seconds."
+                        f"{timeout} seconds."
                     ),
                 )
             )

src/mcp/types.py

@@ -705,6 +705,54 @@ class ListToolsRequest(PaginatedRequest[RequestParams | None, Literal["tools/lis
     params: RequestParams | None = None
 
 
+class ToolAnnotations(BaseModel):
+    """
+    Additional properties describing a Tool to clients.
+
+    NOTE: all properties in ToolAnnotations are **hints**.
+    They are not guaranteed to provide a faithful description of
+    tool behavior (including descriptive properties like `title`).
+
+    Clients should never make tool use decisions based on ToolAnnotations
+    received from untrusted servers.
+    """
+
+    title: str | None = None
+    """A human-readable title for the tool."""
+
+    readOnlyHint: bool | None = None
+    """
+    If true, the tool does not modify its environment.
+    Default: false
+    """
+
+    destructiveHint: bool | None = None
+    """
+    If true, the tool may perform destructive updates to its environment.
+    If false, the tool performs only additive updates.
+    (This property is meaningful only when `readOnlyHint == false`)
+    Default: true
+    """
+
+    idempotentHint: bool | None = None
+    """
+    If true, calling the tool repeatedly with the same arguments 
+    will have no additional effect on the its environment.
+    (This property is meaningful only when `readOnlyHint == false`)
+    Default: false
+    """
+
+    openWorldHint: bool | None = None
+    """
+    If true, this tool may interact with an "open world" of external
+    entities. If false, the tool's domain of interaction is closed.
+    For example, the world of a web search tool is open, whereas that
+    of a memory tool is not.
+    Default: true
+    """
+    model_config = ConfigDict(extra="allow")
+
+
 class Tool(BaseModel):
     """Definition for a tool the client can call."""
 
@@ -714,6 +762,8 @@ class Tool(BaseModel):
     """A human-readable description of the tool."""
     inputSchema: dict[str, Any]
     """A JSON Schema object defining the expected parameters for the tool."""
+    annotations: ToolAnnotations | None = None
+    """Optional additional tool information."""
     model_config = ConfigDict(extra="allow")
 
 

tests/server/fastmcp/resources/test_function_resources.py

@@ -100,7 +100,7 @@ class MyModel(BaseModel):
             fn=lambda: MyModel(name="test"),
         )
         content = await resource.read()
-        assert content == '{"name": "test"}'
+        assert content == '{\n  "name": "test"\n}'
 
     @pytest.mark.anyio
     async def test_custom_type_conversion(self):

tests/server/fastmcp/resources/test_resource_template.py

@@ -185,4 +185,4 @@ def get_data(value: str) -> CustomData:
 
         assert isinstance(resource, FunctionResource)
         content = await resource.read()
-        assert content == "hello"
+        assert content == '"hello"'