Prompt render: let conversion errors surface; validate dict messages once

- Drop the per-item try/except in render(): it only re-raised as 'Could not convert
  prompt result to message: <repr>' and hid the real error (e.g. a missing media file)
  one level deeper; the outer handler already reports 'Error rendering prompt X: ...'.
- message_validator validates the UserMessage | AssistantMessage union left to right.
  Both classes accept either role, so smart mode always landed on the first arm anyway,
  after converting (and, for path-backed Image/Audio, reading) the content for both.
- Docs: the content rule sentence names Sequence alongside list/tuple.

Author: maxisbey

docs/servers/structured-output.md

@@ -210,7 +210,7 @@ The opposite, `structured_output=True`, turns the automatic detection into a req
 
 ## Content blocks and media
 
-Content blocks and media (`TextContent`, `EmbeddedResource`, `Image`, `Audio` and friends, on their own or as the items of a `list` or `tuple` or the arms of a union) are opted out for you: they are for the model to read, so auto-detection derives no schema from them (**[Images, audio & icons](media.md)** covers `Image` and `Audio`). `structured_output=True` still forces one for the content-block classes.
+Content blocks and media (`TextContent`, `EmbeddedResource`, `Image`, `Audio` and friends, on their own, as the items of a `list`, `tuple` or `Sequence`, or as the arms of a union) are opted out for you: they are for the model to read, so auto-detection derives no schema from them (**[Images, audio & icons](media.md)** covers `Image` and `Audio`). `structured_output=True` still forces one for the content-block classes.
 
 ## A class without type hints
 

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

@@ -4,7 +4,7 @@
 
 import functools
 from collections.abc import Awaitable, Callable, Sequence
-from typing import TYPE_CHECKING, Any, Literal
+from typing import TYPE_CHECKING, Annotated, Any, Literal
 
 import anyio.to_thread
 import pydantic_core
@@ -60,7 +60,11 @@ def __init__(self, content: str | ContentBlock | Image | Audio, **kwargs: Any):
         super().__init__(content=content, **kwargs)
 
 
-message_validator = TypeAdapter[UserMessage | AssistantMessage](UserMessage | AssistantMessage)
+# Both classes accept either role, so the first arm always matches: validate left to right rather than
+# trying both (which converted - and for path-backed Image/Audio, read - the content twice).
+message_validator: TypeAdapter[UserMessage | AssistantMessage] = TypeAdapter(
+    Annotated[UserMessage | AssistantMessage, Field(union_mode="left_to_right")]
+)
 
 _PromptResultItem = str | ContentBlock | Image | Audio | Message | dict[str, Any]
 SyncPromptResult = _PromptResultItem | InputRequiredResult | Sequence[_PromptResultItem]
@@ -188,18 +192,15 @@ async def render(
             # Convert result to messages
             messages: list[Message] = []
             for msg in result:  # type: ignore[reportUnknownVariableType]
-                try:
-                    if isinstance(msg, Message):
-                        messages.append(msg)
-                    elif isinstance(msg, dict):
-                        messages.append(message_validator.validate_python(msg))
-                    elif isinstance(msg, str | ContentBlock | Image | Audio):  # bare content is one user message
-                        messages.append(UserMessage(msg))
-                    else:  # pragma: no cover
-                        content = pydantic_core.to_json(msg, fallback=str, indent=2).decode()
-                        messages.append(Message(role="user", content=content))
-                except Exception:  # pragma: no cover
-                    raise ValueError(f"Could not convert prompt result to message: {msg}")
+                if isinstance(msg, Message):
+                    messages.append(msg)
+                elif isinstance(msg, dict):
+                    messages.append(message_validator.validate_python(msg))
+                elif isinstance(msg, str | ContentBlock | Image | Audio):  # bare content is one user message
+                    messages.append(UserMessage(msg))
+                else:  # pragma: no cover
+                    content = pydantic_core.to_json(msg, fallback=str, indent=2).decode()
+                    messages.append(Message(role="user", content=content))
 
             return messages
         except MCPError:

tests/server/mcpserver/prompts/test_base.py

@@ -1,4 +1,5 @@
 import threading
+from pathlib import Path
 from typing import Any
 
 import pytest
@@ -316,3 +317,15 @@ def fn() -> Any:
         return returned
 
     assert await Prompt.from_function(fn).render(None, Context()) == expected
+
+
+@pytest.mark.anyio
+async def test_prompt_returning_media_with_an_unreadable_file_fails_to_render(tmp_path: Path) -> None:
+    """SDK-defined: a bare `Image` whose file cannot be read fails the render (an error for the client)
+    instead of degrading to a text message."""
+
+    def fn() -> Image:
+        return Image(path=tmp_path / "missing.png")
+
+    with pytest.raises(ValueError):
+        await Prompt.from_function(fn).render(None, Context())