Two-surface protocol types: per-surface fact tables (candidate 2/2)

[maxisbey]

Draft — not intended to merge as-is. This is one of two candidate implementations of the same design, pushed side by side so the approaches can be compared concretely. The companion draft is #2849: identical public surface, identical wire behavior, differing only in how the per-surface knowledge is represented — declarative fact rows here, committed model packages in the companion. The pair supersedes the earlier per-version-factored drafts #2843, #2844, and #2845, which stay open for comparison. Once a direction is chosen, the selected approach would be re-cut as a reviewable PR series.

The design

Protocol types are organized as two wire surfaces plus one user-facing type set:

• mcp.types — the single public type set (the "monolith" throughout the source): one class per protocol construct, a superset covering every released protocol revision plus the upcoming 2026-07-28 revision. Existing names are unchanged; everything new is additive.
• A v2025_11_25 surface serving every released revision (2024-11-05 through 2025-11-25). The released schemas evolved strictly additively — each defines a subset of the newest one — and tests/types/test_version_facts_oracle.py proves that coverage field-by-field against generated oracles of all four schemas.
• A v2026_07_28 surface carrying strict typing for the upcoming revision.

The wire boundary — mcp.types.wire.serialize_for(model, version) / parse_as(type, data, version) — is additive-only. Serializing dumps the model; on a 2026-07-28 session it additionally injects the fields that revision requires when the caller left them unset (resultType, the ttlMs/cacheScope don't-cache defaults, the reserved protocolVersion _meta entry) and validates strictly. Nothing is ever removed from a payload at any version: deployed peers ignore unknown fields, so a newer field flowing to an older peer is harmless, while silently deleting a caller's field never is. Parsing is one lenient superset parse at every version, plus the checks the 2026-07-28 revision mandates.

This candidate: declarative fact rows

The per-surface knowledge is data: src/mcp/types/_version_facts.py holds the per-version method tables plus two surface fact blocks of inject/refuse/mandate rows, applied by one small engine (src/mcp/types/_shaping.py) that carries no per-version knowledge of its own. The v2025_11_25 block is empty by design — emitting to a released-revision peer is the plain dump, by construction rather than by check — and the v2026_07_28 block carries the new revision's required-field injections, its emission refusals, and its inbound mandates. An oracle test pins the fact blocks against the generated schemas, including the additive-evolution claim that lets one empty block serve all four released revisions.

Motivation and Context

The SDK models one protocol revision at a time, but every session negotiates its own version, and the upcoming 2026-07-28 revision changes wire shapes materially: a required resultType on results, required reserved _meta entries on client requests, the initialize handshake and the server→client request channel removed in favor of server/discover and embedded input requests, resource subscriptions, and tasks continuing as an extension. One type set can carry all of that only if something version-aware sits at the wire boundary. Keying that boundary on two surfaces instead of five versions follows from a property of the released schemas: from 2024-11-05 to 2025-11-25 they only ever added, so one lenient surface serves all of them and only the upcoming revision needs strict treatment.

How Has This Been Tested?

• Full suite passes at 100% line + branch coverage (./scripts/test); pyright in strict mode and ruff are clean.
• A 185-case wire-fixture corpus exercises serialization and parsing at every protocol revision, in both directions (client→server and server→client).
• tests/spec_oracles/ holds per-version schema oracles regenerated verbatim from the pinned public schemas; tests/types/test_version_facts_oracle.py pins the fact blocks against them, oracle by oracle.

Breaking Changes

None — additive only. Existing mcp.types names and shapes are unchanged (pinned by tests/types/test_public_surface.py), and mcp.types.wire is new API.

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

Reading order

1. src/mcp/types/_types.py — the monolith: one class per protocol construct, every revision's fields, removed-construct sections marked in place. (src/mcp/types/jsonrpc.py is the version-independent envelope; src/mcp/types/_spec_names.py records the deliberate SDK↔schema naming divergences.)
2. src/mcp/types/_version_facts.py — the mechanism: per-version method tables as literal frozensets, then the two surface fact blocks; the released-revisions block is empty on purpose, with the reasoning stated in the module docstring.
3. src/mcp/types/_shaping.py — the one interpreter for the fact rows; fixed order refuse → dump → inject → required-_meta, with the parse mandates on the inbound side.
4. src/mcp/types/wire.py — the public boundary: version registry, method-table re-exports, serialize_for / parse_as, and the two error types.
5. tests/types/test_version_facts_oracle.py — pins the fact blocks against the generated schema oracles, including the proof that one surface covers all four released schemas.
6. tests/types/test_wire_boundary.py and tests/types/test_wire_parse.py — emission and parse behavior across versions (alongside test_shaping_engine.py, test_unions.py, test_version_registry.py, test_public_surface.py, and test_import_budget.py).
7. tests/spec_oracles/ — the generated per-version oracles and the burn-down comparison; regenerated by scripts/update_spec_types.py.

Decision markers

Source comments tagged OD-n / M-n flag open decisions at the line where they bite. They are records of considered alternatives, not TODOs, and are resolved before release. Index:

• OD-1 src/mcp/types/_types.py:1981 — structured_content ships as plain Any = None, vs a sentinel distinguishing wire-absent from explicit null.
• OD-2 src/mcp/types/_types.py:704 — types removed in 2026-07-28 stay in mcp.types in marked sections, vs moving to a lazily-aliased legacy module.
• OD-3 src/mcp/types/_types.py:1547 — the 2025-11-25 task types are kept for those sessions (their tasks/* methods stay out of the unions and method tables); the extension's own task types are not built.
• OD-5 src/mcp/types/_version_facts.py:376 — when a handler leaves the required caching fields unset on 2026-07-28 emission, the boundary injects the don't-cache pair (ttlMs=0, cacheScope="private"), vs requiring handlers to set both fields.
• OD-9 src/mcp/types/_types.py:1165 — one extra="allow" carve-out on SubscriptionFilter (extensions merge keys into it on the wire), vs a parse-side allow layer on every extension-carrying model.
• OD-11 src/mcp/types/wire.py:81 — no outbound narrowing when emitting to released revisions; pass-through chosen over stripping content a peer's revision predates.
• OD-13 src/mcp/types/_spec_names.py:67 — elicitation requestedSchema stays an untyped dict; the restricted-schema vocabulary is not modeled.
• M-2 src/mcp/types/jsonrpc.py:207 — JSONRPCError.id keeps the required-but-nullable shape; the 2025-11-25 schema reading that allows an absent id would give the field a None default.

_{AI Disclaimer}