π The fast, Pythonic way to build MCP servers and clients.
Support from __future__ import annotations (#1199)
Jeremiah Lowinf950b8ca95a2
diff --git a/src/fastmcp/tools/tool.py b/src/fastmcp/tools/tool.pyindex ae07b6216..0cb31523f 100644--- a/src/fastmcp/tools/tool.py+++ b/src/fastmcp/tools/tool.py@@ -3,7 +3,15 @@ from __future__ import annotationsimport inspectfrom collections.abc import Callablefrom dataclasses import dataclass-from typing import TYPE_CHECKING, Annotated, Any, Generic, Literal, TypeVar+from typing import (+ TYPE_CHECKING,+ Annotated,+ Any,+ Generic,+ Literal,+ TypeVar,+ get_type_hints,+)import mcp.typesimport pydantic_core@@ -371,7 +379,20 @@ class ParsedFunction:input_schema = compress_schema(input_schema, prune_params=prune_params)output_schema = None- output_type = inspect.signature(fn).return_annotation+ # Get the return annotation from the signature+ sig = inspect.signature(fn)+ output_type = sig.return_annotation++ # If the annotation is a string (from __future__ annotations), resolve it+ if isinstance(output_type, str):+ try:+ # Use get_type_hints to resolve the return type+ # include_extras=True preserves Annotated metadata+ type_hints = get_type_hints(fn, include_extras=True)+ output_type = type_hints.get("return", output_type)+ except Exception:+ # If resolution fails, keep the string annotation+ passif output_type not in (inspect._empty, None, Any, ...):# there are a variety of types that we don't want to attempt todiff --git a/src/fastmcp/utilities/types.py b/src/fastmcp/utilities/types.pyindex add9fdc0f..d309f2af9 100644--- a/src/fastmcp/utilities/types.py+++ b/src/fastmcp/utilities/types.py@@ -8,7 +8,15 @@ from collections.abc import Callablefrom functools import lru_cachefrom pathlib import Pathfrom types import EllipsisType, UnionType-from typing import Annotated, TypeAlias, TypeVar, Union, get_args, get_origin+from typing import (+ Annotated,+ TypeAlias,+ TypeVar,+ Union,+ get_args,+ get_origin,+ get_type_hints,+)import mcp.typesfrom mcp.types import Annotations@@ -35,6 +43,54 @@ def get_cached_typeadapter(cls: T) -> TypeAdapter[T]:However, this isn't feasible for user-generated functions. Instead, we use acache to minimize the cost of creating them as much as possible."""+ # For functions, we need to ensure TypeAdapter can resolve forward+ # references+ # Normally this could be done by setting e.g. parent_depth=3 to reflect the+ # globals in the parent stack, but this utility function can't make that assumption.+ if inspect.isfunction(cls) or inspect.ismethod(cls):+ # Only try to resolve annotations if the function has them+ if hasattr(cls, "__annotations__") and cls.__annotations__:+ try:+ # Use include_extras=True to preserve Annotated metadata+ resolved_hints = get_type_hints(cls, include_extras=True)+ # Check if we need to create a new function with resolved annotations+ if resolved_hints != cls.__annotations__:+ # Create a new function object with resolved annotations+ import types++ # Handle both functions and methods+ if inspect.ismethod(cls):+ actual_func = cls.__func__+ code = actual_func.__code__+ globals_dict = actual_func.__globals__+ name = actual_func.__name__+ defaults = actual_func.__defaults__+ closure = actual_func.__closure__+ else:+ code = cls.__code__+ globals_dict = cls.__globals__+ name = cls.__name__+ defaults = cls.__defaults__+ closure = cls.__closure__++ new_func = types.FunctionType(+ code,+ globals_dict,+ name,+ defaults,+ closure,+ )+ new_func.__dict__.update(cls.__dict__)+ new_func.__module__ = cls.__module__+ new_func.__qualname__ = getattr(cls, "__qualname__", cls.__name__)+ new_func.__annotations__ = resolved_hints+ return TypeAdapter(new_func)+ except Exception:+ # If resolution fails, this might be due to closure-scoped types+ # that aren't available in the function's globals. In this case,+ # we'll let TypeAdapter handle the string annotations directly.+ pass+return TypeAdapter(cls)@@ -77,12 +133,21 @@ def find_kwarg_by_type(fn: Callable, kwarg_type: type) -> str | None:Includes union types that contain the kwarg_type, as well as Annotated types."""if inspect.ismethod(fn) and hasattr(fn, "__func__"):- sig = inspect.signature(fn.__func__)- else:- sig = inspect.signature(fn)+ fn = fn.__func__++ # Try to get resolved type hints+ try:+ # Use include_extras=True to preserve Annotated metadata+ type_hints = get_type_hints(fn, include_extras=True)+ except Exception:+ # If resolution fails, use raw annotations if they exist+ type_hints = getattr(fn, "__annotations__", {})+ sig = inspect.signature(fn)for name, param in sig.parameters.items():- if is_class_member_of_type(param.annotation, kwarg_type):+ # Use resolved hint if available, otherwise raw annotation+ annotation = type_hints.get(name, param.annotation)+ if is_class_member_of_type(annotation, kwarg_type):return namereturn Nonediff --git a/tests/server/test_server_interactions.py b/tests/server/test_server_interactions.pyindex 986fb275a..a04fa2515 100644--- a/tests/server/test_server_interactions.py+++ b/tests/server/test_server_interactions.py@@ -31,6 +31,20 @@ from fastmcp.utilities.json_schema import compress_schemafrom fastmcp.utilities.types import Audio, File, Image+def _normalize_anyof_order(schema):+ """Normalize the order of items in anyOf arrays for consistent comparison."""+ if isinstance(schema, dict):+ if "anyOf" in schema:+ # Sort anyOf items by their string representation for consistent ordering+ schema = schema.copy()+ schema["anyOf"] = sorted(schema["anyOf"], key=str)+ # Recursively normalize nested objects+ return {k: _normalize_anyof_order(v) for k, v in schema.items()}+ elif isinstance(schema, list):+ return [_normalize_anyof_order(item) for item in schema]+ return schema++class PersonTypedDict(TypedDict):name: strage: int@@ -917,7 +931,12 @@ class TestToolOutputSchema:type_schema = compress_schema(TypeAdapter(annotation).json_schema())assert len(tools) == 1- assert tools[0].outputSchema == type_schema++ # Normalize anyOf ordering for comparison since union type order+ # can vary between environments when using annotation resolution+ actual_schema = _normalize_anyof_order(tools[0].outputSchema)+ expected_schema = _normalize_anyof_order(type_schema)+ assert actual_schema == expected_schemaasync def test_disabled_output_schema_no_structured_content(self):mcp = FastMCP()diff --git a/tests/tools/test_tool_future_annotations.py b/tests/tools/test_tool_future_annotations.pynew file mode 100644index 000000000..a5d9d8c0d--- /dev/null+++ b/tests/tools/test_tool_future_annotations.py@@ -0,0 +1,170 @@+from __future__ import annotations++from typing import Any, cast++import mcp.types+import pytest++from fastmcp import Context, FastMCP+from fastmcp.client import Client+from fastmcp.tools.tool import ToolResult+from fastmcp.utilities.types import Image++fastmcp_server = FastMCP()+++@fastmcp_server.tool+def simple_with_context(ctx: Context) -> str:+ """Simple tool with context parameter."""+ return f"Request ID: {ctx.request_id}"+++@fastmcp_server.tool+def complex_types(+ data: dict[str, Any], items: list[int], ctx: Context+) -> dict[str, str | int]:+ """Tool with complex type annotations."""+ return {"count": len(items), "request_id": ctx.request_id}+++@fastmcp_server.tool+def optional_context(name: str, ctx: Context | None = None) -> str:+ """Tool with optional context."""+ if ctx:+ return f"Hello {name} from request {ctx.request_id}"+ return f"Hello {name}"+++@fastmcp_server.tool+def union_with_context(value: int | str, ctx: Context) -> ToolResult:+ """Tool returning ToolResult with context."""+ return ToolResult(content=f"Value: {value}, Request: {ctx.request_id}")+++@fastmcp_server.tool+def returns_image(ctx: Context) -> Image:+ """Tool that returns an Image."""+ # Create a simple 1x1 white pixel PNG+ png_data = b"\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR\x00\x00\x00\x01\x00\x00\x00\x01\x08\x02\x00\x00\x00\x90wS\xde\x00\x00\x00\x0cIDATx\x9cc\xf8\x0f\x00\x00\x01\x01\x00\x05\x18\xd4c\x00\x00\x00\x00IEND\xaeB`\x82"+ return Image(data=png_data, format="png")+++@fastmcp_server.tool+async def async_with_context(ctx: Context) -> str:+ """Async tool with context."""+ return f"Async request: {ctx.request_id}"+++class TestFutureAnnotations:+ async def test_simple_with_context(self):+ async with Client(fastmcp_server) as client:+ result = await client.call_tool("simple_with_context", {})+ assert "Request ID:" in cast(mcp.types.TextContent, result.content[0]).text++ async def test_complex_types(self):+ async with Client(fastmcp_server) as client:+ result = await client.call_tool(+ "complex_types", {"data": {"key": "value"}, "items": [1, 2, 3]}+ )+ # Check the result is valid JSON with expected values+ import json++ data = json.loads(cast(mcp.types.TextContent, result.content[0]).text)+ assert data["count"] == 3+ assert "request_id" in data++ async def test_optional_context(self):+ async with Client(fastmcp_server) as client:+ result = await client.call_tool("optional_context", {"name": "World"})+ assert (+ "Hello World from request"+ in cast(mcp.types.TextContent, result.content[0]).text+ )++ async def test_union_with_context(self):+ async with Client(fastmcp_server) as client:+ result = await client.call_tool("union_with_context", {"value": 42})+ assert (+ "Value: 42, Request:"+ in cast(mcp.types.TextContent, result.content[0]).text+ )++ async def test_returns_image(self):+ async with Client(fastmcp_server) as client:+ result = await client.call_tool("returns_image", {})+ assert result.content[0].type == "image"+ assert result.content[0].mimeType == "image/png"++ async def test_async_with_context(self):+ async with Client(fastmcp_server) as client:+ result = await client.call_tool("async_with_context", {})+ assert (+ "Async request:" in cast(mcp.types.TextContent, result.content[0]).text+ )++ async def test_modern_union_syntax_works(self):+ """Test that modern | union syntax works with future annotations."""+ # This demonstrates that our solution works with | syntax when types+ # are available in module globals++ # Define a tool with modern union syntax+ @fastmcp_server.tool+ def modern_union_tool(value: str | int | None) -> str | None:+ """Tool using modern | union syntax throughout."""+ if value is None:+ return None+ return f"processed: {value}"++ async with Client(fastmcp_server) as client:+ # Test with string+ result = await client.call_tool("modern_union_tool", {"value": "hello"})+ assert (+ "processed: hello"+ in cast(mcp.types.TextContent, result.content[0]).text+ )++ # Test with int+ result = await client.call_tool("modern_union_tool", {"value": 42})+ assert (+ "processed: 42" in cast(mcp.types.TextContent, result.content[0]).text+ )++ # Test with None+ result = await client.call_tool("modern_union_tool", {"value": None})+ # When function returns None, FastMCP returns empty content+ assert (+ len(result.content) == 0+ or cast(mcp.types.TextContent, result.content[0]).text == "null"+ )+++ reason="Closure-scoped types cannot be resolved with 'from __future__ import annotations'. "+ "When using future annotations, all type annotations become strings that need to be evaluated "+ "using eval() in the function's global namespace. Types defined only in closure scope "+ "(like local imports or type aliases) are not available in the function's __globals__ "+ "and therefore cannot be resolved by get_type_hints()."+)+def test_closure_scoped_types_limitation():+ """+ This test demonstrates that closure-scoped types don't work with future annotations.++ The fundamental issue is that 'from __future__ import annotations' converts all+ annotations to strings, and those strings can only be resolved using the function's+ global namespace, not local variables from closures.+ """++ def create_failing_closure():+ # This import is only available in the closure scope++ mcp = FastMCP()++ @mcp.tool+ def closure_tool(value: str | None) -> str:+ """This will fail because Optional can't be resolved from closure import."""+ return str(value)++ return mcp++ # This should raise an error during tool registration+ create_failing_closure()