You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
Bare dict / list / tuple return annotations silently produce no structured output #3725
A tool annotated with a bare dict (or list / tuple) gets no outputSchema and no structuredContent. The result only arrives as JSON text. -> dict[str, Any] works, and -> str gets {"result": ...}. With structured_output=True the bare annotation raises InvalidSignature: Function f: return type <class 'dict'> is not serializable for structured output, which reads as if a dict weren't serializable.
Expected:-> dict behaves like dict[str, Any], and -> list / -> tuple like list[Any] (wrapped in {"result": ...}). Failing that, the structured-output docs could say that bare containers opt out.
Cause:_create_output_model sends bare dict / list / tuple to the "other class types" case. get_type_hints(dict) is empty, so the model stays None: the silent opt-out documented for classes without type hints, which isn't obvious for builtins. We hit it while building an MCP server: our tools were -> dict, and our client code expected structured_content that was always None.
Proposed fix: a case before the class fallback that sends bare dict down the dict[str, ...] path and wraps bare list / tuple like their generic forms, plus a test and one sentence in docs/servers/structured-output.md. It's about 10 lines of code, and the full suite passes (6206 passed). One behaviour change to weigh: existing bare -> dict / -> list tools would start publishing an outputSchema and validating their results.
I'd like to send this as a PR if you're open to it. It's on a branch: g-s-jithesh@6ecfa04
I used an AI coding assistant (Claude Code) to help investigate this and draft the fix. I reproduced the bug myself and reviewed the change.
I was able to reproduce this. In _create_output_model (src/mcp/server/mcpserver/utilities/func_metadata.py), bare dict, list, tuple, and set fall through to the ordinary class inspection where get_type_hints() returns {}, leaving output_model as None (or raising InvalidSignature when structured_output=True).
I've verified a minimal fix and test coverage locally:
Treat bare dict (and typing.Dict) as Annotated[dict[str, Any], Field(title=f"{func_name}DictOutput")] without wrapping (matching dict[str, Any] behavior).
Route bare collections (list, tuple, set, frozenset, and typing.List) through _create_wrapped_model with wrap_output=True.
All 642 existing mcpserver tests plus regression tests for all bare containers pass cleanly (uv run pytest tests/server/mcpserver/), and ruff check / ruff format are clean.
Happy to open a PR for this if this matches the intended design and you'd like to assign the issue.
typing.Dict / typing.List without parameters already produce structured output today (wrapped in {"result": ...}), so they aren't part of the silent None. What's left is an inconsistency: a bare typing.Dict is wrapped while dict / dict[str, Any] aren't. Changing that would alter existing output, so I've left it for maintainers to decide.
As the reporter, I'd still like to send the PR from that branch if a maintainer is happy to assign this.
(Investigated and drafted with an AI coding assistant.)
Also hit this on 2.3.0. Plain list and tuple return annotations take the same path: they fall through to the "other class types" branch in _create_output_model, get_type_hints() returns {}, and the tool silently ends up with no output schema. Annotating dict[str, Any] / list[...] works around it.
Activity
xuilen commentedon Oct 17, 2026
I was able to reproduce this. In
_create_output_model(src/mcp/server/mcpserver/utilities/func_metadata.py), baredict,list,tuple, andsetfall through to the ordinary class inspection whereget_type_hints()returns{}, leavingoutput_modelasNone(or raisingInvalidSignaturewhenstructured_output=True).I've verified a minimal fix and test coverage locally:
dict(andtyping.Dict) asAnnotated[dict[str, Any], Field(title=f"{func_name}DictOutput")]without wrapping (matchingdict[str, Any]behavior).list,tuple,set,frozenset, andtyping.List) through_create_wrapped_modelwithwrap_output=True.All 642 existing mcpserver tests plus regression tests for all bare containers pass cleanly (
uv run pytest tests/server/mcpserver/), andruff check/ruff formatare clean.Happy to open a PR for this if this matches the intended design and you'd like to assign the issue.
(AI-assisted investigation & implementation)
g-s-jithesh commentedon Oct 17, 2026
Thanks for confirming the reproduction. Good catch on
set/frozenset: they take the same path, and I've added them to the branch with tests (all 642 tests intests/server/mcpserver/pass): main...g-s-jithesh:python-sdk:fix/bare-container-structured-outputtyping.Dict/typing.Listwithout parameters already produce structured output today (wrapped in{"result": ...}), so they aren't part of the silentNone. What's left is an inconsistency: a baretyping.Dictis wrapped whiledict/dict[str, Any]aren't. Changing that would alter existing output, so I've left it for maintainers to decide.As the reporter, I'd still like to send the PR from that branch if a maintainer is happy to assign this.
(Investigated and drafted with an AI coding assistant.)
xuilen commentedon Oct 17, 2026
Sounds great! Glad the
set/frozensetedge cases were helpful. Best of luck with the PR!adilKhan72 commentedon Oct 18, 2026
Also hit this on 2.3.0. Plain
listandtuplereturn annotations take the same path: they fall through to the "other class types" branch in_create_output_model,get_type_hints()returns{}, and the tool silently ends up with no output schema. Annotatingdict[str, Any]/list[...]works around it.