René's URL Explorer Experiment


Title: Give recursive tool return types an object-rooted output schema by maxisbey · Pull Request #3376 · modelcontextprotocol/python-sdk · GitHub

Open Graph Title: Give recursive tool return types an object-rooted output schema by maxisbey · Pull Request #3376 · modelcontextprotocol/python-sdk

X Title: Give recursive tool return types an object-rooted output schema by maxisbey · Pull Request #3376 · modelcontextprotocol/python-sdk

Description: Fixes #3337 When a tool's return type is self-referential, pydantic emits the output schema as {"$defs": {...}, "$ref": "#/$defs/Node"} with no type at the root. Tool.outputSchema requires type: "object" at the root on 2025-11-25 and earlier, so one such tool failed the entire tools/list result for every legacy-negotiated client (Handler returned an invalid result). This inlines the referenced definition onto the root and keeps $defs for the nested references. Motivation and Context The trigger is narrow (recursive BaseModel, recursive TypedDict since #3331, mutually recursive models, RootModel[Model]), but the blast radius when hit is the whole tool listing, and it isn't only this SDK's serializer that objects: TypeScript SDK 1.x, TypeScript SDK 2.x on pre-2026 sessions, and C# SDK 1.x clients all reject a listing containing a $ref-rooted outputSchema. FastMCP hit the same thing (PrefectHQ/fastmcp#2455) and it's cited in SEP-2106's rationale. The fix is unconditional rather than per-protocol-version: the schema is an object, pydantic just spells a recursive root as $ref (it only unpacks a root $ref when the definition is referenced exactly once). The resulting shape is what pydantic already produces for the non-recursive version of the same model, and docs/servers/structured-output.md already promises that model return types publish an object root. Other SDKs that can emit recursive roots (zod 4, schemars, System.Text.Json) all inline the root too. How Has This Been Tested? test_structured_output_self_referential_model_gets_an_object_root pins the generated shape and round-trips a nested result through convert_result. test_recursive_tool_return_type_lists_and_calls_on_legacy_session drives Client(mcp, mode="legacy") through tools/list and tools/call; both tests fail on main. Drove it by hand on both mode="legacy" and 2026-07-28 with self-referential, mutually recursive, and TypedDict return types, and validated the resulting wire ListToolsResult against the spec's schema/2025-11-25/schema.json (valid; the old shape fails with 'type' is a required property). Breaking Changes None. The only observable change is the JSON content of output_schema for recursive return types: the root gains the definition's keys, $defs is unchanged, structuredContent is unchanged. Types of changes Bug fix (non-breaking change which fixes an issue) New feature (non-breaking change which adds functionality) Breaking change (fix or feature that would cause existing functionality to change) Documentation update Checklist I have read the MCP Documentation My code follows the repository's style guidelines New and existing tests pass locally I have added appropriate error handling I have added or updated documentation as needed Additional context Deliberately out of scope: a RootModel whose root is not an object (RootModel[list[int]], RootModel[int]) still publishes a non-object root and non-dict structuredContent, which fails both tools/list and that tool's tools/call on legacy sessions. That one genuinely isn't an object, so it needs either reclassification as a wrapped output or per-version projection of schema and value; I'll open a separate issue. A v1.x backport follows — v1 ships the same shape silently and strict clients reject it there too. AI Disclaimer

Open Graph Description: Fixes #3337 When a tool's return type is self-referential, pydantic emits the output schema as {"$defs": {...}, "$ref": "#/$defs/Node"} with no type at the root. T...

X Description: Fixes #3337 When a tool's return type is self-referential, pydantic emits the output schema as {"$defs": {...}, "$ref": "#/$defs/Node"}...

Opengraph URL: https://github.com/modelcontextprotocol/python-sdk/pull/3376

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:84a26f3c-2cd4-629d-03b6-3f97ab654134
current-catalog-service-hashae870bc5e265a340912cde392f23dad3671a0a881730ffdadd82f2f57d81641b
request-idE360:305B07:A45B81:DAE706:6B00E974
html-safe-nonce77a2c10cfe4888dbb48a27c10f9fc8387353d6c1d18c455d5ab115d67f1eea6a
visitor-payloadeyJyZWZlcnJlciI6IiIsInJlcXVlc3RfaWQiOiJFMzYwOjMwNUIwNzpBNDVCODE6REFFNzA2OjZCMDBFOTc0IiwidmlzaXRvcl9pZCI6IjEzMDcyNzk5NTUyNTU2ODM0NDQiLCJyZWdpb25fZWRnZSI6ImlhZCIsInJlZ2lvbl9yZW5kZXIiOiJpYWQifQ==
visitor-hmac973f3cd254b25aefb816f9d9ece462d59a5f046450aa72c2509f776a134a3150
hovercard-subject-tagpull_request:4351032528
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/3376/files
twitter:imagehttps://avatars.githubusercontent.com/u/224885523?s=400&v=4
twitter:cardsummary_large_image
og:imagehttps://avatars.githubusercontent.com/u/224885523?s=400&v=4
og:image:altFixes #3337 When a tool's return type is self-referential, pydantic emits the output schema as {"$defs": {...}, "$ref": "#/$defs/Node"} with no type at the root. T...
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/3376/files#start-of-content
https://github.com/
Sign inhttps://github.com/login?return_to=https%3A%2F%2Fgithub.com%2Fmodelcontextprotocol%2Fpython-sdk%2Fpull%2F3376%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%2F3376%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/3376/files
Reloadhttps://github.com/modelcontextprotocol/python-sdk/pull/3376/files
Reloadhttps://github.com/modelcontextprotocol/python-sdk/pull/3376/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
maxisbeyhttps://github.com/maxisbey
mainhttps://github.com/modelcontextprotocol/python-sdk/tree/main
fix/recursive-output-schema-object-roothttps://github.com/modelcontextprotocol/python-sdk/tree/fix/recursive-output-schema-object-root
Conversation 2 https://github.com/modelcontextprotocol/python-sdk/pull/3376
Commits 1 https://github.com/modelcontextprotocol/python-sdk/pull/3376/commits
Checks 37 https://github.com/modelcontextprotocol/python-sdk/pull/3376/checks
Files changed https://github.com/modelcontextprotocol/python-sdk/pull/3376/files
Please reload this pagehttps://github.com/modelcontextprotocol/python-sdk/pull/3376/files
Give recursive tool return types an object-rooted output schema https://github.com/modelcontextprotocol/python-sdk/pull/3376/files#top
Show all changes 1 commit https://github.com/modelcontextprotocol/python-sdk/pull/3376/files
d56f6c1 Give recursive tool return types an object-rooted output schema maxisbey Aug 24, 2026 https://github.com/modelcontextprotocol/python-sdk/pull/3376/commits/d56f6c137c67709bdd8ed06d37e0e747763e86cc
Clear filters https://github.com/modelcontextprotocol/python-sdk/pull/3376/files
Please reload this pagehttps://github.com/modelcontextprotocol/python-sdk/pull/3376/files
Please reload this pagehttps://github.com/modelcontextprotocol/python-sdk/pull/3376/files
func_metadata.py https://github.com/modelcontextprotocol/python-sdk/pull/3376/files#diff-5584d2273ac6a270822fe54fb95a27e03d6895afd1216e8bd71d1850e8f09676
test_func_metadata.py https://github.com/modelcontextprotocol/python-sdk/pull/3376/files#diff-441229bc4427c8d5e50cc305a07b43d42f2a292682cf4b0161e59b4f4685e9b8
test_server.py https://github.com/modelcontextprotocol/python-sdk/pull/3376/files#diff-c191383f010475fc22bf69d35f14f16d7e45098b05a1a0f03ad66d6c151d1f34
src/mcp/server/mcpserver/utilities/func_metadata.pyhttps://github.com/modelcontextprotocol/python-sdk/pull/3376/files#diff-5584d2273ac6a270822fe54fb95a27e03d6895afd1216e8bd71d1850e8f09676
View file https://github.com/modelcontextprotocol/python-sdk/blob/d56f6c137c67709bdd8ed06d37e0e747763e86cc/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/3376/{{ revealButtonHref }}
https://github.com/modelcontextprotocol/python-sdk/pull/3376/files#diff-5584d2273ac6a270822fe54fb95a27e03d6895afd1216e8bd71d1850e8f09676
https://github.com/modelcontextprotocol/python-sdk/pull/3376/checks?check_run_id=97533795667
claudehttps://github.com/apps/claude
Aug 24, 2026https://github.com/modelcontextprotocol/python-sdk/pull/3376/files#r3846161895
Learn morehttps://docs.github.com/articles/managing-disruptive-comments/#hiding-a-comment
Please reload this pagehttps://github.com/modelcontextprotocol/python-sdk/pull/3376/files
https://github.com/modelcontextprotocol/python-sdk/pull/3376/files#diff-5584d2273ac6a270822fe54fb95a27e03d6895afd1216e8bd71d1850e8f09676
https://github.com/modelcontextprotocol/python-sdk/pull/3376/files#diff-5584d2273ac6a270822fe54fb95a27e03d6895afd1216e8bd71d1850e8f09676
https://github.com/modelcontextprotocol/python-sdk/pull/3376/files#diff-5584d2273ac6a270822fe54fb95a27e03d6895afd1216e8bd71d1850e8f09676
tests/server/mcpserver/test_func_metadata.pyhttps://github.com/modelcontextprotocol/python-sdk/pull/3376/files#diff-441229bc4427c8d5e50cc305a07b43d42f2a292682cf4b0161e59b4f4685e9b8
View file https://github.com/modelcontextprotocol/python-sdk/blob/d56f6c137c67709bdd8ed06d37e0e747763e86cc/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/3376/{{ revealButtonHref }}
https://github.com/modelcontextprotocol/python-sdk/pull/3376/files#diff-441229bc4427c8d5e50cc305a07b43d42f2a292682cf4b0161e59b4f4685e9b8
https://github.com/modelcontextprotocol/python-sdk/pull/3376/files#diff-441229bc4427c8d5e50cc305a07b43d42f2a292682cf4b0161e59b4f4685e9b8
tests/server/mcpserver/test_server.pyhttps://github.com/modelcontextprotocol/python-sdk/pull/3376/files#diff-c191383f010475fc22bf69d35f14f16d7e45098b05a1a0f03ad66d6c151d1f34
View file https://github.com/modelcontextprotocol/python-sdk/blob/d56f6c137c67709bdd8ed06d37e0e747763e86cc/tests/server/mcpserver/test_server.py
Open in desktop https://desktop.github.com
https://github.co/hiddenchars
https://github.com/modelcontextprotocol/python-sdk/pull/3376/{{ revealButtonHref }}
https://github.com/modelcontextprotocol/python-sdk/pull/3376/files#diff-c191383f010475fc22bf69d35f14f16d7e45098b05a1a0f03ad66d6c151d1f34
https://github.com/modelcontextprotocol/python-sdk/pull/3376/files#diff-c191383f010475fc22bf69d35f14f16d7e45098b05a1a0f03ad66d6c151d1f34
Please reload this pagehttps://github.com/modelcontextprotocol/python-sdk/pull/3376/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.