use ToolAnnotations instead of dict throughout

Author: bhosmer-ant

pyproject.toml

@@ -29,7 +29,7 @@ dependencies = [
     "starlette>=0.27",
     "sse-starlette>=1.6.1",
     "pydantic-settings>=2.5.2",
-    "uvicorn>=0.23.1",
+    "uvicorn>=0.23.1; sys_platform != 'emscripten'",
 ]
 
 [project.optional-dependencies]
@@ -89,8 +89,8 @@ venv = ".venv"
 strict = ["src/mcp/**/*.py"]
 
 [tool.ruff.lint]
-select = ["E", "F", "I", "UP"]
-ignore = []
+select = ["C4", "E", "F", "I", "PERF", "UP"]
+ignore = ["PERF203"]
 
 [tool.ruff]
 line-length = 88
@@ -113,5 +113,7 @@ filterwarnings = [
     # This should be fixed on Uvicorn's side.
     "ignore::DeprecationWarning:websockets",
     "ignore:websockets.server.WebSocketServerProtocol is deprecated:DeprecationWarning",
-    "ignore:Returning str or bytes.*:DeprecationWarning:mcp.server.lowlevel"
+    "ignore:Returning str or bytes.*:DeprecationWarning:mcp.server.lowlevel",
+    # this is a problem in starlette 0.27, which we're currently pinned to
+    "ignore:Please use `import python_multipart` instead.:PendingDeprecationWarning",
 ]

src/mcp/server/fastmcp/server.py

@@ -43,6 +43,7 @@
     GetPromptResult,
     ImageContent,
     TextContent,
+    ToolAnnotations,
 )
 from mcp.types import Prompt as MCPPrompt
 from mcp.types import PromptArgument as MCPPromptArgument
@@ -172,17 +173,13 @@ def _setup_handlers(self) -> None:
 
     async def list_tools(self) -> list[MCPTool]:
         """List all available tools."""
-        from mcp.types import ToolAnnotations
-
         tools = self._tool_manager.list_tools()
         return [
             MCPTool(
                 name=info.name,
                 description=info.description,
                 inputSchema=info.parameters,
-                annotations=ToolAnnotations.model_validate(info.annotations)
-                if info.annotations
-                else None,
+                annotations=info.annotations,
             )
             for info in tools
         ]
@@ -251,7 +248,7 @@ def add_tool(
         fn: AnyFunction,
         name: str | None = None,
         description: str | None = None,
-        annotations: dict[str, Any] | None = None,
+        annotations: ToolAnnotations | None = None,
     ) -> None:
         """Add a tool to the server.
 
@@ -262,7 +259,7 @@ 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 annotations providing additional tool information
+            annotations: Optional ToolAnnotations providing additional tool information
         """
         self._tool_manager.add_tool(
             fn, name=name, description=description, annotations=annotations
@@ -272,7 +269,7 @@ def tool(
         self,
         name: str | None = None,
         description: str | None = None,
-        annotations: dict[str, Any] | None = None,
+        annotations: ToolAnnotations | None = None,
     ) -> Callable[[AnyFunction], AnyFunction]:
         """Decorator to register a tool.
 
@@ -283,7 +280,7 @@ def tool(
         Args:
             name: Optional name for the tool (defaults to function name)
             description: Optional description of what the tool does
-            annotations: Optional annotations providing additional tool information
+            annotations: Optional ToolAnnotations providing additional tool information
 
         Example:
             @server.tool()

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,7 +31,7 @@ class Tool(BaseModel):
     context_kwarg: str | None = Field(
         None, description="Name of the kwarg that should receive context"
     )
-    annotations: dict[str, Any] | None = Field(
+    annotations: ToolAnnotations | None = Field(
         None, description="Optional annotations for the tool"
     )
 
@@ -41,10 +42,10 @@ def from_function(
         name: str | None = None,
         description: str | None = None,
         context_kwarg: str | None = None,
-        annotations: dict[str, Any] | 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__
 

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,7 +36,7 @@ def add_tool(
         fn: Callable[..., Any],
         name: str | None = None,
         description: str | None = None,
-        annotations: dict[str, Any] | None = None,
+        annotations: ToolAnnotations | None = None,
     ) -> Tool:
         """Add a tool to the server."""
         tool = Tool.from_function(

tests/server/fastmcp/test_tool_manager.py

@@ -9,6 +9,7 @@
 from mcp.server.fastmcp.tools import ToolManager
 from mcp.server.session import ServerSessionT
 from mcp.shared.context import LifespanContextT
+from mcp.types import ToolAnnotations
 
 
 class TestAddTools:
@@ -331,27 +332,27 @@ def read_data(path: str) -> str:
             """Read data from a file."""
             return f"Data from {path}"
 
-        annotations = {
-            "title": "File Reader",
-            "readOnlyHint": True,
-            "openWorldHint": False,
-        }
+        annotations = ToolAnnotations(
+            title="File Reader",
+            readOnlyHint=True,
+            openWorldHint=False,
+        )
 
         manager = ToolManager()
         tool = manager.add_tool(read_data, annotations=annotations)
 
         assert tool.annotations is not None
-        assert tool.annotations["title"] == "File Reader"
-        assert tool.annotations["readOnlyHint"] is True
-        assert tool.annotations["openWorldHint"] is False
+        assert tool.annotations.title == "File Reader"
+        assert tool.annotations.readOnlyHint is True
+        assert tool.annotations.openWorldHint is False
 
     @pytest.mark.anyio
     async def test_tool_annotations_in_fastmcp(self):
         """Test that tool annotations are included in MCPTool conversion."""
 
         app = FastMCP()
 
-        @app.tool(annotations={"title": "Echo Tool", "readOnlyHint": True})
+        @app.tool(annotations=ToolAnnotations(title="Echo Tool", readOnlyHint=True))
         def echo(message: str) -> str:
             """Echo a message back."""
             return message