Add isError support for non-text tool results (Fixes #348)

- Add CallToolResult.create_error() classmethod for convenient error results with non-text content
- Add model_validator to auto-convert SDK Image/Audio helpers to wire content types
- Allow Image/Audio helpers directly in CallToolResult.content
- Add tests for image, audio, and structured content error results

Author: mukktinaadh

src/mcp-types/mcp_types/_types.py

@@ -1483,6 +1483,60 @@ class CallToolResult(Result):
     result_type: ResultType = "complete"
     """See `ResultType`. Always serialized; older peers ignore it."""
 
+    @model_validator(mode="before")
+    @classmethod
+    def _convert_helpers(cls, data: Any) -> Any:
+        """Auto-convert SDK Image/Audio helpers to wire content types.
+
+        This allows users to pass SDK helper objects (which have `to_image_content()`
+        or `to_audio_content()` methods) directly in `content` without manual conversion.
+        """
+        if isinstance(data, dict) and "content" in data:
+            content = data["content"]
+            if isinstance(content, list):
+                converted = []
+                for item in content:
+                    if hasattr(item, "to_image_content"):
+                        converted.append(item.to_image_content())
+                    elif hasattr(item, "to_audio_content"):
+                        converted.append(item.to_audio_content())
+                    else:
+                        converted.append(item)
+                data["content"] = converted
+        return data
+
+    @classmethod
+    def create_error(
+        cls,
+        content: list[ContentBlock],
+        *,
+        structured_content: Any = None,
+    ) -> Self:
+        """Create a CallToolResult with is_error=True.
+
+        This is a convenience method for returning tool errors with non-text content
+        (images, audio, structured data) without raising an exception.
+
+        Args:
+            content: List of content blocks (text, image, audio, etc.)
+            structured_content: Optional structured data payload
+
+        Returns:
+            CallToolResult with is_error=True
+
+        Example:
+            ```python
+            from mcp.server.mcpserver.utilities.types import Image
+            from mcp.types import CallToolResult
+
+            @mcp.tool()
+            async def my_tool() -> CallToolResult:
+                img = Image(data=b'...', format='png')
+                return CallToolResult.create_error(content=[img])
+            ```
+        """
+        return cls(content=content, structured_content=structured_content, is_error=True)
+
 
 class ToolListChangedNotification(Notification[NotificationParams | None, Literal["notifications/tools/list_changed"]]):
     """An optional notification from the server to the client, informing it that the list

src/mcp-types/mcp_types/_v2025_11_25/__init__.py

@@ -6,7 +6,7 @@
 
 from __future__ import annotations
 
-from typing import Annotated, Any, Literal
+from typing import Annotated, Any, Literal, Self
 
 from mcp_types._wire_base import WireModel
 from pydantic import ConfigDict, Field, RootModel
@@ -3172,6 +3172,20 @@ class CallToolResult(WireModel):
     An optional JSON object that represents the structured result of the tool call.
     """
 
+    @classmethod
+    def create_error(
+        cls,
+        content: list[ContentBlock],
+        *,
+        structured_content: Any = None,
+    ) -> Self:
+        """Create a CallToolResult with isError=True.
+
+        This is a convenience method for returning tool errors with non-text content
+        (images, audio, structured data) without raising an exception.
+        """
+        return cls(content=content, structured_content=structured_content, is_error=True)
+
 
 class ClientNotification(
     RootModel[

src/mcp-types/mcp_types/_v2026_07_28/__init__.py

@@ -6,7 +6,7 @@
 
 from __future__ import annotations
 
-from typing import Annotated, Any, Literal, Union
+from typing import Annotated, Any, Literal, Self, Union
 
 from mcp_types._wire_base import WireModel
 from pydantic import ConfigDict, Field, RootModel
@@ -2730,6 +2730,20 @@ class CallToolResult(WireModel):
     that conforms to the tool's outputSchema if one is defined.
     """
 
+    @classmethod
+    def create_error(
+        cls,
+        content: list[ContentBlock],
+        *,
+        structured_content: Any = None,
+    ) -> Self:
+        """Create a CallToolResult with isError=True.
+
+        This is a convenience method for returning tool errors with non-text content
+        (images, audio, structured data) without raising an exception.
+        """
+        return cls(content=content, structured_content=structured_content, is_error=True)
+
 
 class CancelledNotification(WireModel):
     """

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

@@ -174,6 +174,22 @@ def convert_result(self, result: Any) -> CallToolResult | InputRequiredResult:
         if isinstance(result, CallToolResult):
             if output_model is not None:
                 self._output_adapter(output_model).validate_python(result.structured_content)
+            # Convert any Image/Audio helpers in content to their wire types
+            converted_content = []
+            for block in result.content:
+                if isinstance(block, Image):
+                    converted_content.append(block.to_image_content())
+                elif isinstance(block, Audio):
+                    converted_content.append(block.to_audio_content())
+                else:
+                    converted_content.append(block)
+            if converted_content != list(result.content):
+                return CallToolResult(
+                    content=converted_content,
+                    structured_content=result.structured_content,
+                    is_error=result.is_error,
+                    result_type=result.result_type,
+                )
             return result
 
         unstructured_content = _convert_to_content(result)

tests/server/mcpserver/tools/test_base.py

@@ -55,3 +55,63 @@ async def boom() -> str:
 
     assert isinstance(result, types.CallToolResult)
     assert result.is_error is True
+
+
+@pytest.mark.anyio
+async def test_call_tool_result_create_error_with_image():
+    """A tool can return CallToolResult.create_error() with Image helper for non-text error content."""
+    mcp = MCPServer(name="srv")
+
+    @mcp.tool()
+    async def image_error() -> types.CallToolResult:
+        from mcp.server.mcpserver.utilities.types import Image
+        img = Image(data=b"fake-png", format="png")
+        return types.CallToolResult.create_error(content=[img])
+
+    async with Client(mcp) as client:
+        result = await client.call_tool("image_error", {})
+
+    assert isinstance(result, types.CallToolResult)
+    assert result.is_error is True
+    assert len(result.content) == 1
+    assert isinstance(result.content[0], types.ImageContent)
+
+
+@pytest.mark.anyio
+async def test_call_tool_result_create_error_with_audio():
+    """A tool can return CallToolResult.create_error() with Audio helper for non-text error content."""
+    mcp = MCPServer(name="srv")
+
+    @mcp.tool()
+    async def audio_error() -> types.CallToolResult:
+        from mcp.server.mcpserver.utilities.types import Audio
+        aud = Audio(data=b"fake-wav", format="wav")
+        return types.CallToolResult.create_error(content=[aud])
+
+    async with Client(mcp) as client:
+        result = await client.call_tool("audio_error", {})
+
+    assert isinstance(result, types.CallToolResult)
+    assert result.is_error is True
+    assert len(result.content) == 1
+    assert isinstance(result.content[0], types.AudioContent)
+
+
+@pytest.mark.anyio
+async def test_call_tool_result_create_error_with_structured_content():
+    """A tool can return CallToolResult.create_error() with structured content."""
+    mcp = MCPServer(name="srv")
+
+    @mcp.tool()
+    async def structured_error() -> types.CallToolResult:
+        return types.CallToolResult.create_error(
+            content=[types.TextContent(type="text", text="Something went wrong")],
+            structured_content={"error_code": "INVALID_INPUT", "details": {"field": "email"}},
+        )
+
+    async with Client(mcp) as client:
+        result = await client.call_tool("structured_error", {})
+
+    assert isinstance(result, types.CallToolResult)
+    assert result.is_error is True
+    assert result.structured_content == {"error_code": "INVALID_INPUT", "details": {"field": "email"}}