Protocol types for 2026-07-28: superset monolith, committed per-version packages, and wire-method maps by maxisbey · Pull Request #2849 · modelcontextprotocol/python-sdk

maxisbey · 2026-06-12T12:33:06Z

Overview

Three type sets:

mcp.types.v2025_11_25 — generated from the 2025-11-25 schema; serves every version through 2025-11-25
mcp.types.v2026_07_28 — generated from the 2026-07-28 (draft) schema
mcp.types (the monolith) — hand-maintained superset of both; this is the public API

mcp.types.methods holds (method, version) → surface-type maps and the parse/validate/serialize helpers the runner and sessions call.

Generation

scripts/gen_surface_types.py runs datamodel-codegen over vendored schema/*.json, with a few mappings overridden (format: byte/uri/uri-template → str; number → int | float) and extra="ignore" everywhere except a per-version allow-list of spec-declared open types (_meta, Result, GetTaskPayloadResult, tool input/output schemas, etc.). CI regenerates with --check and fails on drift.

Wiring

ServerRunner and ClientSession consult the maps:

Inbound requests/notifications are validated against the negotiated version's surface row. A spec method that doesn't exist at that version is METHOD_NOT_FOUND even if a handler is registered; a malformed payload is INVALID_PARAMS (or dropped+logged for notifications). Non-spec methods registered on the server skip the gate.
Inbound results (send_request return path, both directions) are surface-validated before the monolith parse; mismatches raise at the call site.
Outbound server results are dumped from the monolith, then re-serialized through the surface row. Fields not in that version's schema are dropped, so 2026-only keys (resultType, ttlMs, cacheScope) never reach a pre-2026 peer.

SUPPORTED_PROTOCOL_VERSIONS is unchanged — 2026-07-28 is modeled, not yet negotiable.

Breaking changes

Server handlers must return spec-valid results; nonconforming output (e.g. Tool(inputSchema={}) — missing "type": "object") now produces INTERNAL_ERROR.
Clients now surface-validate inbound traffic; spec-invalid server output may raise where it was previously tolerated.
Elicitation schemas are now validated against PrimitiveSchemaDefinition; Optional[T] is unwrapped, bare list[str] (no enum) is rejected.

Documented in docs/migration.md.

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

…s, and wire-method maps One public type set (mcp.types) covering every protocol revision through 2026-07-28; two per-version model packages that act as the schema-exact validating layer; and plain (method, version) maps with two-step parse functions. Version gating is data: key absence is the gate. Outbound serialization is the model dump, with the new 2026-07-28 result fields as ordinary serialized defaults. Includes a surface-to-monolith field-parity test that asserts every wire alias in either per-version package is carried by the monolith.

Vendor schema/2025-11-25.json and schema/2026-07-28.json (pinned to spec SHA 6d441518), restore scripts/gen_surface_types.py to regenerate both src/mcp/types/v* packages from them, and run --check in CI so the committed files cannot drift from the schemas.

… generated-file pyright suppression

- Add validate_client_request/notification, validate_server_result to types.methods (surface-only siblings of the parse_* functions) - ServerRunner validates inbound requests/notifications against the negotiated version's surface schema; custom methods fall through to the registered params_type as before - Handler results are validated against the surface schema after dump; a spec-invalid result is logged and returns INTERNAL_ERROR to the client - Map JSON-Schema format byte/uri/uri-template to plain str in codegen (Base64Str and AnyUrl over-assert on annotation-only formats); regenerate both surface packages - Fix two test fixtures that built Tool(input_schema={}) without the spec-required type field - Document handler-result validation in migration.md

Generated surface types switch to extra="ignore" (with a per-version allow-list for spec-declared open types: Result, _meta, GetTaskPayloadResult, Tool input/output schemas, URLElicitationRequiredError data). The runner now serializes spec-method results by dumping the monolith model and re-dumping through the negotiated version's surface row, so 2026-only fields (resultType, ttlMs, cacheScope) never reach the wire on a pre-2026 session. - Monolith ttl_ms/cache_scope default to None; the SDK does not stamp a caching policy. EmptyResult.result_type stays None (deployed peer servers strict-validate ping responses). - Spec methods absent at the negotiated version reject with METHOD_NOT_FOUND even if a handler is registered; custom methods fall through unchanged. - Version fallback for pre-handshake/stateless is the literal 2025-11-25, not LATEST_PROTOCOL_VERSION. - Add serialize_server_result to types.methods; codegen drift-guard asserts the open-class substitution count. - Docstrings now say method-gating per version, shape per schema era.

Kludex · 2026-06-16T08:44:54Z

I think the best way to approach this is to use VCR infra, and the tests actually update the code.

…uest ServerSession.send_request and Connection.send_request now run the client's response through validate_client_result before parsing into the caller's result_type. KeyError (spec method without a row at the negotiated version, or a non-spec method on Connection) is tolerated and the existing model_validate proceeds; ValidationError propagates as today. Adds validate_client_result to types.methods and refactors parse_client_result to delegate its surface step to it.

…eration ClientSession now uses parse_server_request/notification for inbound dispatch (KeyError -> METHOD_NOT_FOUND), validates callback results against the surface schema before sending (ValidationError -> INTERNAL_ERROR), and gates server results through validate_server_result before parsing. Adds a protocol_version property. Surface codegen: SCHEMA_PATCHES targets ["integer", "number"] instead of bare "number" so generated types use int | float (pydantic smart-union preserves int through the sieve; previously coerced 37 -> 37.0). Regenerated both packages. elicitation.py: Optional[T] fields now emit {"type": ...} with the field omitted from required (was non-spec anyOf). Gate tightened to reject list[...] and multi-primitive unions; only T or T | None accepted. The interaction-suite divergence for nested requestedSchema is flipped (client now rejects with INVALID_PARAMS). Documented the elicit gate change in migration.md.

- Runner discriminator uses direction-specific SPEC_CLIENT_METHODS so server-direction methods (roots/list, sampling/createMessage, elicitation/create) registered via add_request_handler reach their handler instead of METHOD_NOT_FOUND - Elicit gate now validates the rendered schema property-by-property against PrimitiveSchemaDefinition (restores list[str] + json_schema_extra multi-select; bare list[str] without enum still rejected; Literal[...] now supported) - gen_surface_types.py always invokes datamodel-codegen via uv (the shutil.which() shortcut defeated the version pin) - RequestedSchema.properties relaxed to dict[str, Any] in the generated surfaces (older python-sdk releases emit anyOf for Optional fields); ElicitResult.content value union gains a null arm (monolith superset leniency) - Client _on_notify logs version-absent notifications at debug, malformed at warning (mirrors runner) - migration.md: fix the input_schema={} example; document client-side surface validation; correct the elicit-gate section

- JSONValue: the spec includes null but the ts-to-json render dropped it alongside number; the existing patch restored number only. Now restores both, with a post-process step to strip the redundant forward-ref | None codegen emits in the recursive definitions. - Tasks types: the 12 Tasks capability classes were defined in _types but not re-exported. Now in __all__, with a parity test that every public _types model is exported.

github-actions · 2026-06-16T21:54:10Z

This pull request is included in pre-release v2.0.0a2

maxisbey mentioned this pull request Jun 12, 2026
Two-surface protocol types: per-surface fact tables (candidate 2/2) #2850
Closed
9 tasks

maxisbey changed the title ~~Two-surface protocol types: validated model packages (candidate 1/2)~~Protocol types for 2026-07-28: superset monolith, committed per-version packages, and wire-method mapsJun 12, 2026

maxisbey force-pushed the maxisbey/types-two-surface-packages branch 2 times, most recently from 9a38b0d to 655c393Compare June 15, 2026 13:33

maxisbey commented Jun 15, 2026
View reviewed changes

Comment threadsrc/mcp/shared/version.py Outdated
Comment threadsrc/mcp/types/jsonrpc.py Outdated
Comment threadsrc/mcp/types/methods.py
Comment threadtests/interaction/_requirements.py Outdated

maxisbey force-pushed the maxisbey/types-two-surface-packages branch 4 times, most recently from 4913884 to d52fbc6Compare June 15, 2026 16:58

maxisbey added 2 commits June 15, 2026 17:07

maxisbey force-pushed the maxisbey/types-two-surface-packages branch from d52fbc6 to 408c56eCompare June 15, 2026 17:07

maxisbey added 3 commits June 15, 2026 17:21

Simplify surface-type generator to raw codegen output with minimal fixes
30ca8b9

Drop dead OpenWireModel; add --frozen to codegen invocations; tighten…
0c6211e
… generated-file pyright suppression

maxisbey marked this pull request as ready for review June 15, 2026 20:53

Kludex reviewed Jun 16, 2026
View reviewed changes

maxisbey added 6 commits June 16, 2026 09:03

Use single backticks in docstrings and comments
c00dd2f

Add --frozen to uv command in schema/README.md
d239f99

felixweinberger approved these changes Jun 16, 2026
View reviewed changes

maxisbey merged commit 65be5a7 into mainJun 16, 2026
31 checks passed

maxisbey deleted the maxisbey/types-two-surface-packages branch June 16, 2026 16:40

This was referenced Jun 16, 2026
Drop stale superset-leniency note from ElicitResult.content docstring #2884
Merged
Expand site-absolute spec links in generated docstrings to full URLs #2885
Merged

maxisbey mentioned this pull request Jun 16, 2026
Resolve protocol version per request and expose it as ctx.protocol_version #2886
Merged
9 tasks

Kludex mentioned this pull request Jun 20, 2026
Pass json-schema-ref-no-deref conformance scenario (SEP-2106) #2924
Merged

This was referenced Jun 26, 2026
Work through the spec-conformance gaps recorded by the interaction suite #2999
Draft
Implement SEP-1724: Extensions #1555
Closed
Implement SEP-1865: MCP Apps - Interactive User Interfaces for MCP #2791
Closed

This was referenced Jul 27, 2026
Make the per-version wire packages private (mcp_types._v*) #3191
Merged
feat(types): add SEP-2549 cache hints to result models #2824
Closed

Navigation Menu

Uh oh!

Protocol types for 2026-07-28: superset monolith, committed per-version packages, and wire-method maps - #2849

Protocol types for 2026-07-28: superset monolith, committed per-version packages, and wire-method maps#2849
maxisbey merged 12 commits into
mainfrom
maxisbey/types-two-surface-packages

maxisbey commented Jun 12, 2026•
edited
Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

KludexJun 16, 2026

Uh oh!

Uh oh!

github-actionsBot commented Jun 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Uh oh!

Conversation

maxisbey commented Jun 12, 2026• edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview

Generation

Wiring

Breaking changes

Types of changes

Checklist

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

KludexJun 16, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actionsBot commented Jun 16, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

maxisbey commented Jun 12, 2026•
edited
Loading