FastMCP: Improve structured output for dict and mixed lists

Author: SSOBHY2

src/mcp/server/fastmcp/utilities/func_metadata.py

@@ -14,6 +14,7 @@
     WithJsonSchema,
     create_model,
 )
+from pydantic.errors import PydanticSchemaGenerationError
 from pydantic.fields import FieldInfo
 from pydantic.json_schema import GenerateJsonSchema, JsonSchemaWarningKind
 from typing_extensions import is_typeddict
@@ -364,7 +365,7 @@ def _try_create_model_and_schema(
             if len(args) == 2 and args[0] is str:
                 # TODO: should we use the original annotation? We are loosing any potential `Annotated`
                 # metadata for Pydantic here:
-                model = _create_dict_model(func_name, type_expr)
+                model = _create_dict_model(func_name, original_annotation)
             else:
                 # dict with non-str keys needs wrapping
                 model = _create_wrapped_model(func_name, original_annotation)
@@ -411,12 +412,19 @@ def _try_create_model_and_schema(
         # Use StrictJsonSchema to raise exceptions instead of warnings
         try:
             schema = model.model_json_schema(schema_generator=StrictJsonSchema)
-        except (TypeError, ValueError, pydantic_core.SchemaError, pydantic_core.ValidationError) as e:
+        except (
+            TypeError,
+            ValueError,
+            pydantic_core.SchemaError,
+            pydantic_core.ValidationError,
+            PydanticSchemaGenerationError,
+        ) as e:
             # These are expected errors when a type can't be converted to a Pydantic schema
             # TypeError: When Pydantic can't handle the type
             # ValueError: When there are issues with the type definition (including our custom warnings)
             # SchemaError: When Pydantic can't build a schema
             # ValidationError: When validation fails
+            # PydanticSchemaGenerationError: When pydantic-core cannot generate a schema for a type
             logger.info(f"Cannot create schema for type {type_expr} in {func_name}: {type(e).__name__}: {e}")
             return None, None, False
 

tests/server/fastmcp/test_func_metadata.py

@@ -243,6 +243,16 @@ def func_dict_int_key() -> dict[int, str]:  # pragma: no cover
     assert meta.output_schema is not None
     assert "result" in meta.output_schema["properties"]
 
+    # Test Annotated dict[str, int] with Field metadata on the root type
+    def func_dict_annotated() -> Annotated[dict[str, int], Field(description="User scores")]:  # pragma: no cover
+        return {"alice": 10, "bob": 20}
+
+    meta = func_metadata(func_dict_annotated)
+    assert meta.output_schema is not None
+    assert meta.output_schema["type"] == "object"
+    assert meta.output_schema["title"] == "func_dict_annotatedDictOutput"
+    assert meta.output_schema.get("description") == "User scores"
+
 
 @pytest.mark.anyio
 async def test_lambda_function():

tests/server/fastmcp/test_server.py

@@ -403,7 +403,7 @@ async def test_tool_mixed_list_with_audio_and_image(self, tmp_path: Path):
 
         # TODO(Marcelo): It seems if we add the proper type hint, it generates an invalid JSON schema.
         # We need to fix this.
-        def mixed_list_fn() -> list:  # type: ignore
+        def mixed_list_fn() -> list[str | Image | Audio | dict[str, str] | TextContent]:  # type: ignore
             return [  # type: ignore
                 "text message",
                 Image(image_path),