Title: fix(mcpserver): omit unreturned TypedDict keys from structuredContent by sainikhiljuluri · Pull Request #3225 · modelcontextprotocol/python-sdk · GitHub
Open Graph Title: fix(mcpserver): omit unreturned TypedDict keys from structuredContent by sainikhiljuluri · Pull Request #3225 · modelcontextprotocol/python-sdk
X Title: fix(mcpserver): omit unreturned TypedDict keys from structuredContent by sainikhiljuluri · Pull Request #3225 · modelcontextprotocol/python-sdk
Description: Fixes #3224 Problem A tool returning a TypedDict with NotRequired keys (or total=False) publishes an outputSchema declaring those properties non-nullable, while convert_result materialises every key the tool did not return as an explicit null. The response violates the schema the same server advertised, so a conforming client rejects the call — including this SDK's own: RuntimeError: Invalid structured content returned by tool get_person: None is not of type 'string' Those tools are therefore unusable, though TypedDict is one of the documented structured-output return shapes. structuredContent and the unstructured text block also disagreed, so a client skipping validation saw two different answers. Solution _create_model_from_typeddict gives non-required keys a None default to make them optional on the generated model. The file's own comment already said such a model "should use exclude_unset=True when dumping to get TypedDict semantics" — nothing did. This marks those models with a private base class (_TypedDictOutputModel) and honours it in convert_result, so a key the tool omitted stays omitted. Two deliberate choices: Scoped to TypedDict-derived models. Applying exclude_unset to every output shape would change payloads for BaseModel, dataclass and wrapped ({"result": ...}) returns, where emitting defaults is correct. The marker base class keeps the blast radius to exactly the shape that is broken, and avoids threading another value out of _try_create_model_and_schema alongside wrap_output. The published outputSchema is unchanged. Widening the annotation to field_type | None would make the null legal, but absent and null are not the same thing for NotRequired, and it would alter the wire format of every existing TypedDict tool. Because only the dump side changes, no existing expectation moves — including test_structured_output_typeddict, which hard-codes the current schema. The default: null still present in the schema is now cosmetic (default does not constrain instances). Happy to strip it in a follow-up if you would rather the schema not advertise a default it can never legally take. A second, pre-existing bug this uncovered: NotRequired is unusable on Python 3.10 Tracked separately in #3227. Adding a test that actually builds a NotRequired TypedDict surfaced a separate defect. On Python 3.10 the tool does not merely return bad content — it cannot be registered at all: pydantic.errors.PydanticForbiddenQualifier: The annotation 'NotRequired[int]' contains the 'typing.NotRequired' type qualifier, which is invalid in the context it is defined. typing.get_type_hints only strips the Required/NotRequired qualifier from 3.11 onwards, so below that the bare qualifier reaches create_model and pydantic rejects it. func_metadata() raises, so the failure lands at decoration time, before the tool can ever be called. This predates this branch. I confirmed it by running the same reproducer against unmodified main (a4f4ccd0) in a separate worktree — identical crash. It is not introduced here; it is simply the first time the suite exercises the path, since test_structured_output_typeddict uses all-required keys and never instantiates the annotation. The fix is one import: typing_extensions.get_type_hints strips the qualifier on every supported version, so there is no version branch. That matters here — a sys.version_info branch would be one-sided on whichever interpreter is measuring, and coverage runs at fail_under = 100 independently on all five. Say the word if you would rather have this as its own PR and I will split it out; I kept them together because the new tests cannot pass on 3.10 without it, so landing them separately would knowingly leave main red on a supported version. How to test uv sync --frozen --all-extras --dev uv run --frozen pytest tests/server/mcpserver/test_func_metadata.py -q uv run --frozen --python 3.10 --all-extras --dev pytest -q -n auto # the version that was broken ./scripts/test # coverage + strict-no-cover Verified on this branch: Python 3.10 specifically → 5582 passed, 10 skipped, 1 xfailed. I ran the whole suite on a real 3.10 interpreter rather than trusting the default one; an earlier revision of this branch passed locally and still broke all four 3.10 jobs, which is what led to the section above. ./scripts/test → 5582 passed, TOTAL 49631 Stmts 0 Miss 3922 Branch 0 BrPart 100.00%, strict-no-cover clean uv run --frozen ruff check . / ruff format --check . → clean uv run --frozen pyright --pythonversion 3.10 → the only 2 errors are pre-existing and unrelated (tests/transports/stdio/test_lifecycle.py uses os.waitid, which does not exist on macOS) markdownlint with the repo's own config → clean, and clean on main too Red-before/green-after was verified rather than assumed — with git stash push -- src/ (tests kept, fix removed) both new tests fail on the injected nulls: Left contains 2 more items: {'age': None, 'name': None} Full diff: - {} + {...} End-to-end through a real Client(MCPServer(...)), the reproducer in the issue goes from RuntimeError: Invalid structured content ... to structuredContent: {'name': 'Dave'}, matching the text block. Tests added Two cases in tests/server/mcpserver/test_func_metadata.py: test_typeddict_output_omits_keys_the_tool_did_not_return — an omitted NotRequired key is absent, a returned one still travels (including a falsy 0) test_total_false_typeddict_output_omits_every_unreturned_key — the degenerate total=False case, where the old behaviour turned {} into a payload of nothing but nulls Both assert the payload against meta.output_schema with jsonschema.validate, so they pin the actual contract — structuredContent must satisfy the schema this server published — rather than just a dict shape. They also call the tool function instead of restating its return value, and add no # pragma: no cover. That is the point: the existing tests for this shape never invoke the tool body, which is why the bug survived — and building the annotation for real is what exposed the 3.10 crash as well. The test module now takes TypedDict from typing_extensions, which pydantic requires below 3.12 for a NotRequired qualifier to be honoured. Docs Per AGENTS.md ("update the relevant page(s) under docs/ in the same PR"), docs/servers/structured-output.md said a TypedDict's structured_content was "identical to the BaseModel version". That is no longer true for omitted keys, so the TypedDict section now states the omission rule and notes the typing_extensions import requirement below 3.12. Disclosure Written with AI assistance (Claude Code). Filed by me as the human contributor -- I own this change and will answer any questions on the implementation or the trade-offs above.
Open Graph Description: Fixes #3224 Problem A tool returning a TypedDict with NotRequired keys (or total=False) publishes an outputSchema declaring those properties non-nullable, while convert_result materialises every ke...
X Description: Fixes #3224 Problem A tool returning a TypedDict with NotRequired keys (or total=False) publishes an outputSchema declaring those properties non-nullable, while convert_result materialises every ke...
Opengraph URL: https://github.com/modelcontextprotocol/python-sdk/pull/3225
X: @github
Domain: github.com
| react-profiling | 0 |
| react-import-map | react,react-dom,react-dom/client,react-dom/profiling,react-is,react/compiler-runtime,react/jsx-dev-runtime,react/jsx-runtime,scheduler@b8488ee2c322 |
| route-pattern | /:user_id/:repository/pull/:id/files(.:format) |
| route-controller | pull_requests |
| route-action | files |
| fetch-nonce | v2:777bf0d4-598e-f866-ed7e-8de8d9134360 |
| current-catalog-service-hash | ae870bc5e265a340912cde392f23dad3671a0a881730ffdadd82f2f57d81641b |
| request-id | B620:14ECB:8530EE:AB5A96:6B00E96F |
| html-safe-nonce | b83ac780aa0206d65999032e0ad57e68388916877a15cf35d9ca32d357728cbb |
| visitor-payload | eyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJCNjIwOjE0RUNCOjg1MzBFRTpBQjVBOTY6NkIwMEU5NkYiLCJ2aXNpdG9yX2lkIjoiNTYxMjMxNTI2ODc3NzgzMDc2NyIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9 |
| visitor-hmac | 1e2a91ab313eaa33c659d85118ef7ac82db50bc89d021e7426e4589c4352df19 |
| hovercard-subject-tag | pull_request:4171732165 |
| github-keyboard-shortcuts | repository,pull-request-list,pull-request-conversation,pull-request-files-changed,copilot |
| google-site-verification | Apib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I |
| octolytics-url | https://collector.github.com/github/collect |
| analytics-location | / |
| fb:app_id | 1401488693436528 |
| apple-itunes-app | app-id=1477376905, app-argument=https://github.com/modelcontextprotocol/python-sdk/pull/3225/files |
| twitter:image | https://avatars.githubusercontent.com/u/67470882?s=400&v=4 |
| twitter:card | summary_large_image |
| og:image | https://avatars.githubusercontent.com/u/67470882?s=400&v=4 |
| og:image:alt | Fixes #3224 Problem A tool returning a TypedDict with NotRequired keys (or total=False) publishes an outputSchema declaring those properties non-nullable, while convert_result materialises every ke... |
| og:site_name | GitHub |
| og:type | object |
| hostname | github.com |
| expected-hostname | github.com |
| None | 4ef498cbabcbe3c50befc7a5b743e7072ee770b4daf0e15e54801180d1fa91fc |
| turbo-cache-control | no-preview |
| diff-view | unified |
| go-import | github.com/modelcontextprotocol/python-sdk git https://github.com/modelcontextprotocol/python-sdk.git |
| octolytics-dimension-user_id | 182288589 |
| octolytics-dimension-user_login | modelcontextprotocol |
| octolytics-dimension-repository_id | 862584018 |
| octolytics-dimension-repository_nwo | modelcontextprotocol/python-sdk |
| octolytics-dimension-repository_public | true |
| octolytics-dimension-repository_is_fork | false |
| octolytics-dimension-repository_network_root_id | 862584018 |
| octolytics-dimension-repository_network_root_nwo | modelcontextprotocol/python-sdk |
| turbo-body-classes | logged-out env-production page-responsive full-width |
| disable-turbo | true |
| browser-stats-url | https://api.github.com/_private/browser/stats |
| browser-errors-url | https://api.github.com/_private/browser/errors |
| release | 9983dd5da06943f833c971dd5b6bc988e2858be5 |
| ui-target | full |
| theme-color | #1e2327 |
| color-scheme | light dark |
Links:
Viewport: width=device-width