fix: handle Image helpers in mixed return annotations

[pragnyanramtha]

Summary

Fixes #1060.

Image and Audio are MCPServer helper wrappers, not protocol content Pydantic models. When they appeared inside mixed return annotations such as tuple[str, Image, AudioContent], the structured-output schema generator tried to build a Pydantic schema for the helper class and raised PydanticSchemaGenerationError.

This detects helper wrapper types recursively inside return annotations and keeps those tools on the existing unstructured content conversion path, matching the current top-level Image/Audio behavior. Protocol content types such as ImageContent, AudioContent, and ContentBlock keep their existing structured-output behavior.

Validation

• uv run --frozen --python 3.12 pytest tests/server/mcpserver/test_server.py::test_tool_mixed_content_with_image_helper_annotation tests/server/mcpserver/test_func_metadata.py::test_unstructured_output_content_helper_annotations tests/server/mcpserver/test_server.py::TestServerTools::test_tool_image_helper tests/server/mcpserver/test_server.py::TestServerTools::test_tool_audio_helper tests/server/mcpserver/test_server.py::TestServerTools::test_tool_mixed_content tests/server/mcpserver/test_func_metadata.py::test_structured_output_generic_types -q
• uv run --frozen --python 3.12 pytest tests/server/mcpserver/test_server.py
• uv run --frozen --python 3.12 ruff check src/mcp/server/mcpserver/utilities/func_metadata.py tests/server/mcpserver/test_server.py tests/server/mcpserver/test_func_metadata.py
• uv run --frozen --python 3.12 ruff format --check src/mcp/server/mcpserver/utilities/func_metadata.py tests/server/mcpserver/test_server.py tests/server/mcpserver/test_func_metadata.py
• uv run --frozen --python 3.12 pyright src/mcp/server/mcpserver/utilities/func_metadata.py tests/server/mcpserver/test_server.py tests/server/mcpserver/test_func_metadata.py
• git diff --check

[Copilot]

Pull request overview

Fixes a structured-output schema generation failure when MCPServer helper wrappers (Image, Audio) appear nested inside mixed return annotations (e.g., tuple[str, Image, AudioContent]). The change ensures these helpers always follow the existing unstructured content conversion path, while protocol content models (e.g., ImageContent, AudioContent, ContentBlock) retain their structured-output behavior.

Changes:

• Added recursive detection of Image/Audio helper types inside return annotations to disable structured output schema generation for those tools.
• Added unit tests covering helper wrappers in top-level, container, union, and Annotated[...] return annotations.
• Added an integration-style server test validating mixed return annotations with an Image helper produce unstructured content and no output_schema.

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated no comments.

File	Description
src/mcp/server/mcpserver/utilities/func_metadata.py	Skips structured-output model/schema creation when return annotations contain Image/Audio helpers (recursively).
tests/server/mcpserver/test_func_metadata.py	Adds regression tests ensuring helper wrapper annotations do not generate schemas (including nested/annotated cases).
tests/server/mcpserver/test_server.py	Adds a server-level regression test for mixed return annotations including an Image helper.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[maxisbey]

Thanks for the PR, and sorry it sat here without a proper review. This has since landed via #3320.

We're closing most of the open PR backlog. v2 is out and changed a lot of the SDK, so many older PRs no longer apply as written, and we're a small team that realistically doesn't have the capacity to work through the rest.

If this still matters to you on v2, the most useful thing you can do is open an issue (or comment on the existing one) with your use case and a repro. Hearing why it matters to you is what we use to decide what to prioritise.

_{AI Disclaimer}