René's URL Explorer Experiment


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

direct link

Domain: github.com

react-profiling0
react-import-mapreact,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-controllerpull_requests
route-actionfiles
fetch-noncev2:777bf0d4-598e-f866-ed7e-8de8d9134360
current-catalog-service-hashae870bc5e265a340912cde392f23dad3671a0a881730ffdadd82f2f57d81641b
request-idB620:14ECB:8530EE:AB5A96:6B00E96F
html-safe-nonceb83ac780aa0206d65999032e0ad57e68388916877a15cf35d9ca32d357728cbb
visitor-payloadeyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJCNjIwOjE0RUNCOjg1MzBFRTpBQjVBOTY6NkIwMEU5NkYiLCJ2aXNpdG9yX2lkIjoiNTYxMjMxNTI2ODc3NzgzMDc2NyIsInJlZ2lvbl9lZGdlIjoiaWFkIiwicmVnaW9uX3JlbmRlciI6ImlhZCJ9
visitor-hmac1e2a91ab313eaa33c659d85118ef7ac82db50bc89d021e7426e4589c4352df19
hovercard-subject-tagpull_request:4171732165
github-keyboard-shortcutsrepository,pull-request-list,pull-request-conversation,pull-request-files-changed,copilot
google-site-verificationApib7-x98H0j5cPqHWwSMm6dNU4GmODRoqxLiDzdx9I
octolytics-urlhttps://collector.github.com/github/collect
analytics-location///pull_requests/show/files
fb:app_id1401488693436528
apple-itunes-appapp-id=1477376905, app-argument=https://github.com/modelcontextprotocol/python-sdk/pull/3225/files
twitter:imagehttps://avatars.githubusercontent.com/u/67470882?s=400&v=4
twitter:cardsummary_large_image
og:imagehttps://avatars.githubusercontent.com/u/67470882?s=400&v=4
og:image:altFixes #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_nameGitHub
og:typeobject
hostnamegithub.com
expected-hostnamegithub.com
None4ef498cbabcbe3c50befc7a5b743e7072ee770b4daf0e15e54801180d1fa91fc
turbo-cache-controlno-preview
diff-viewunified
go-importgithub.com/modelcontextprotocol/python-sdk git https://github.com/modelcontextprotocol/python-sdk.git
octolytics-dimension-user_id182288589
octolytics-dimension-user_loginmodelcontextprotocol
octolytics-dimension-repository_id862584018
octolytics-dimension-repository_nwomodelcontextprotocol/python-sdk
octolytics-dimension-repository_publictrue
octolytics-dimension-repository_is_forkfalse
octolytics-dimension-repository_network_root_id862584018
octolytics-dimension-repository_network_root_nwomodelcontextprotocol/python-sdk
turbo-body-classeslogged-out env-production page-responsive full-width
disable-turbotrue
browser-stats-urlhttps://api.github.com/_private/browser/stats
browser-errors-urlhttps://api.github.com/_private/browser/errors
release9983dd5da06943f833c971dd5b6bc988e2858be5
ui-targetfull
theme-color#1e2327
color-schemelight dark

Links:

Skip to contenthttps://github.com/modelcontextprotocol/python-sdk/pull/3225/files#start-of-content
https://github.com/
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fmodelcontextprotocol%2Fpython-sdk%2Fpull%2F3225%2Ffiles
GitHubRepository hosting, code review, and collaborationhttps://github.com/platform
CopilotAI coding agent for tasks, projects, and automated workhttps://github.com/features/copilot
ActionsCI/CD and automationhttps://github.com/features/actions
Code QualityQuality analysis, fixes, and enforcementhttps://github.com/features/code-quality
CodespacesCloud development environmentshttps://github.com/features/codespaces
Code SecurityVulnerability detection and remediationhttps://github.com/security/advanced-security/code-security
Secret ProtectionSecret scanning and leak preventionhttps://github.com/security/advanced-security/secret-protection
All Featureshttps://github.com/features
Documentationhttps://docs.github.com/en
Traininghttps://learn.github.com/skills
Certificationshttps://learn.github.com/credentials
Build with Copilothttps://github.com/features/ai
Customize Copilothttps://docs.github.com/en/copilot/how-tos/copilot-on-github/customize-copilot/customize-copilot-overview
Integrationshttps://github.com/marketplace
Trending reposhttps://github.com/trending
GitHub Sponsorshttps://github.com/open-source/sponsors
Developer articleshttps://github.com/resources/articles
ChangelogYour source for the latest features, improvements, and fixes across GitHub products, all in one place.https://github.blog/changelog/
Enterpriseshttps://github.com/enterprise
Teamhttps://github.com/team
Startupshttps://github.com/enterprise/startups
Nonprofitshttps://github.com/solutions/industry/nonprofits
Healthcarehttps://github.com/solutions/industry/healthcare
Financial serviceshttps://github.com/solutions/industry/financial-services
Manufacturinghttps://github.com/solutions/industry/manufacturing
Governmenthttps://github.com/solutions/industry/government
See all industrieshttps://github.com/solutions/industry
Why GitHubhttps://github.com/why-github
Customer Storieshttps://github.com/customer-stories
Business insightshttps://github.com/solutions/executive-insights
Trust Centerhttps://github.com/trust-center
GitHub Advanced SecurityEnterprise-grade code securityhttps://github.com/security/advanced-security
Copilot for businessEnterprise-grade AI featureshttps://github.com/features/copilot/copilot-business
Premium SupportEnterprise-grade 24/7 supporthttps://github.com/enterprise/premium-support
Documentationhttps://docs.github.com/en
Resource centerhttps://github.com/resources
Bloghttps://github.blog/
Events & webinarshttps://github.com/resources/events
Community Forumhttps://github.com/orgs/community/discussions
Customer Storieshttps://github.com/customer-stories
Integrationshttps://github.com/marketplace
Customer supporthttps://help.github.com/
Traininghttps://learn.github.com/skills
GitHub Statushttps://www.githubstatus.com/
Abouthttps://github.com/about
Partnershttps://github.com/partners
Changeloghttps://github.blog/changelog/
GitHub UniverseThe event for developers, by developers — talks, workshops, and what’s next for GitHub.https://githubuniverse.com/
Pricinghttps://github.com/pricing
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fmodelcontextprotocol%2Fpython-sdk%2Fpull%2F3225%2Ffiles
Sign uphttps://github.com/signup?ref_cta=Sign+up&ref_loc=header+logged+out&ref_page=%2F%3Cuser-name%3E%2F%3Crepo-name%3E%2Fpull_requests%2Fshow%2Ffiles&source=header-repo&source_repo=modelcontextprotocol%2Fpython-sdk
Reloadhttps://github.com/modelcontextprotocol/python-sdk/pull/3225/files
Reloadhttps://github.com/modelcontextprotocol/python-sdk/pull/3225/files
Reloadhttps://github.com/modelcontextprotocol/python-sdk/pull/3225/files
modelcontextprotocolhttps://github.com/modelcontextprotocol
python-sdkhttps://github.com/modelcontextprotocol/python-sdk
Codehttps://github.com/modelcontextprotocol/python-sdk
Issues308 (308)https://github.com/modelcontextprotocol/python-sdk/issues
Pull requests112 (112)https://github.com/modelcontextprotocol/python-sdk/pulls
Actionshttps://github.com/modelcontextprotocol/python-sdk/actions
Projectshttps://github.com/modelcontextprotocol/python-sdk/projects
Security and quality12 (12)https://github.com/modelcontextprotocol/python-sdk/security
Insightshttps://github.com/modelcontextprotocol/python-sdk/insights
Sign up for GitHub https://github.com/signup?return_to=%2Fmodelcontextprotocol%2Fpython-sdk%2Fissues%2Fnew%2Fchoose
terms of servicehttps://docs.github.com/terms
privacy statementhttps://docs.github.com/privacy
Sign inhttps://github.com/login?return_to=%2Fmodelcontextprotocol%2Fpython-sdk%2Fissues%2Fnew%2Fchoose
sainikhiljulurihttps://github.com/sainikhiljuluri
modelcontextprotocol:mainhttps://github.com/modelcontextprotocol/python-sdk/tree/main
sainikhiljuluri:fix/typeddict-notrequired-structured-outputhttps://github.com/sainikhiljuluri/python-sdk/tree/fix/typeddict-notrequired-structured-output
Conversation 3 https://github.com/modelcontextprotocol/python-sdk/pull/3225
Commits 5 https://github.com/modelcontextprotocol/python-sdk/pull/3225/commits
Checks 33 https://github.com/modelcontextprotocol/python-sdk/pull/3225/checks
Files changed https://github.com/modelcontextprotocol/python-sdk/pull/3225/files
Please reload this pagehttps://github.com/modelcontextprotocol/python-sdk/pull/3225/files
fix(mcpserver): omit unreturned TypedDict keys from structuredContent https://github.com/modelcontextprotocol/python-sdk/pull/3225/files#top
Show all changes 5 commits https://github.com/modelcontextprotocol/python-sdk/pull/3225/files
cad7cd6 fix(mcpserver): omit unreturned TypedDict keys from structuredContent sainikhiljuluri Jul 30, 2026 https://github.com/modelcontextprotocol/python-sdk/pull/3225/commits/cad7cd627a7247457106254aed2e6f2bb9bcf070
8d306c0 fix(tests): import NotRequired from typing_extensions for Python 3.10 sainikhiljuluri Jul 30, 2026 https://github.com/modelcontextprotocol/python-sdk/pull/3225/commits/8d306c064262a838dfcfa624017c231d801bcc1e
826bde0 fix(mcpserver): resolve TypedDict hints via typing_extensions for Pyt… sainikhiljuluri Jul 30, 2026 https://github.com/modelcontextprotocol/python-sdk/pull/3225/commits/826bde01869cacb237858a5787c81bf7a527402f
ec734d1 docs(structured-output): document NotRequired key omission sainikhiljuluri Jul 30, 2026 https://github.com/modelcontextprotocol/python-sdk/pull/3225/commits/ec734d15be54358a7a3b1a7069cfe10dc8a1c92a
e8cc6f6 test(mcpserver): pin nested TypedDict and explicit-None omission beha… sainikhiljuluri Jul 31, 2026 https://github.com/modelcontextprotocol/python-sdk/pull/3225/commits/e8cc6f6cfc898eabcda77c5fb6a485588a93ec61
Clear filters https://github.com/modelcontextprotocol/python-sdk/pull/3225/files
Please reload this pagehttps://github.com/modelcontextprotocol/python-sdk/pull/3225/files
Please reload this pagehttps://github.com/modelcontextprotocol/python-sdk/pull/3225/files
structured-output.md https://github.com/modelcontextprotocol/python-sdk/pull/3225/files#diff-6cdb67ce182e70a37d1f810c4d392afc68e9dcd0e7b7904fe608e6e33ce42b92
func_metadata.py https://github.com/modelcontextprotocol/python-sdk/pull/3225/files#diff-5584d2273ac6a270822fe54fb95a27e03d6895afd1216e8bd71d1850e8f09676
test_func_metadata.py https://github.com/modelcontextprotocol/python-sdk/pull/3225/files#diff-441229bc4427c8d5e50cc305a07b43d42f2a292682cf4b0161e59b4f4685e9b8
docs/servers/structured-output.mdhttps://github.com/modelcontextprotocol/python-sdk/pull/3225/files#diff-6cdb67ce182e70a37d1f810c4d392afc68e9dcd0e7b7904fe608e6e33ce42b92
View file https://github.com/sainikhiljuluri/python-sdk/blob/e8cc6f6cfc898eabcda77c5fb6a485588a93ec61/docs/servers/structured-output.md
Open in desktop https://desktop.github.com
https://github.co/hiddenchars
https://github.com/modelcontextprotocol/python-sdk/pull/3225/{{ revealButtonHref }}
https://github.com/modelcontextprotocol/python-sdk/pull/3225/files#diff-6cdb67ce182e70a37d1f810c4d392afc68e9dcd0e7b7904fe608e6e33ce42b92
https://github.com/modelcontextprotocol/python-sdk/pull/3225/files#diff-6cdb67ce182e70a37d1f810c4d392afc68e9dcd0e7b7904fe608e6e33ce42b92
src/mcp/server/mcpserver/utilities/func_metadata.pyhttps://github.com/modelcontextprotocol/python-sdk/pull/3225/files#diff-5584d2273ac6a270822fe54fb95a27e03d6895afd1216e8bd71d1850e8f09676
View file https://github.com/sainikhiljuluri/python-sdk/blob/e8cc6f6cfc898eabcda77c5fb6a485588a93ec61/src/mcp/server/mcpserver/utilities/func_metadata.py
Open in desktop https://desktop.github.com
https://github.co/hiddenchars
https://github.com/modelcontextprotocol/python-sdk/pull/3225/{{ revealButtonHref }}
https://github.com/modelcontextprotocol/python-sdk/pull/3225/files#diff-5584d2273ac6a270822fe54fb95a27e03d6895afd1216e8bd71d1850e8f09676
https://github.com/modelcontextprotocol/python-sdk/pull/3225/files#diff-5584d2273ac6a270822fe54fb95a27e03d6895afd1216e8bd71d1850e8f09676
https://github.com/modelcontextprotocol/python-sdk/pull/3225/files#diff-5584d2273ac6a270822fe54fb95a27e03d6895afd1216e8bd71d1850e8f09676
https://github.com/modelcontextprotocol/python-sdk/pull/3225/files#diff-5584d2273ac6a270822fe54fb95a27e03d6895afd1216e8bd71d1850e8f09676
https://github.com/modelcontextprotocol/python-sdk/pull/3225/files#diff-5584d2273ac6a270822fe54fb95a27e03d6895afd1216e8bd71d1850e8f09676
https://github.com/modelcontextprotocol/python-sdk/pull/3225/files#diff-5584d2273ac6a270822fe54fb95a27e03d6895afd1216e8bd71d1850e8f09676
https://github.com/modelcontextprotocol/python-sdk/pull/3225/files#diff-5584d2273ac6a270822fe54fb95a27e03d6895afd1216e8bd71d1850e8f09676
https://github.com/modelcontextprotocol/python-sdk/pull/3225/files#diff-5584d2273ac6a270822fe54fb95a27e03d6895afd1216e8bd71d1850e8f09676
tests/server/mcpserver/test_func_metadata.pyhttps://github.com/modelcontextprotocol/python-sdk/pull/3225/files#diff-441229bc4427c8d5e50cc305a07b43d42f2a292682cf4b0161e59b4f4685e9b8
View file https://github.com/sainikhiljuluri/python-sdk/blob/e8cc6f6cfc898eabcda77c5fb6a485588a93ec61/tests/server/mcpserver/test_func_metadata.py
Open in desktop https://desktop.github.com
https://github.co/hiddenchars
https://github.com/modelcontextprotocol/python-sdk/pull/3225/{{ revealButtonHref }}
https://github.com/modelcontextprotocol/python-sdk/pull/3225/files#diff-441229bc4427c8d5e50cc305a07b43d42f2a292682cf4b0161e59b4f4685e9b8
https://github.com/modelcontextprotocol/python-sdk/pull/3225/files#diff-441229bc4427c8d5e50cc305a07b43d42f2a292682cf4b0161e59b4f4685e9b8
https://github.com/modelcontextprotocol/python-sdk/pull/3225/files#diff-441229bc4427c8d5e50cc305a07b43d42f2a292682cf4b0161e59b4f4685e9b8
https://github.com/modelcontextprotocol/python-sdk/pull/3225/files#diff-441229bc4427c8d5e50cc305a07b43d42f2a292682cf4b0161e59b4f4685e9b8
Please reload this pagehttps://github.com/modelcontextprotocol/python-sdk/pull/3225/files
https://github.com
Termshttps://docs.github.com/site-policy/github-terms/github-terms-of-service
Privacyhttps://docs.github.com/site-policy/privacy-policies/github-privacy-statement
Securityhttps://github.com/security
Statushttps://www.githubstatus.com/
Communityhttps://github.community/
Docshttps://docs.github.com/
Contacthttps://support.github.com?tags=dotcom-footer

Viewport: width=device-width


URLs of crawlers that visited me.