Re-vendor 2026-07-28 schema and absorb spec #2907 error-code renumber

Merged
MA
4mo ago
+469-356

Re-vendors the draft (2026-07-28) schema and absorbs the spec's error-code allocation policy from modelcontextprotocol#2907. Part of #2891.

Motivation and Context

schema/PINNED.json was at spec commit 6d441518 (2026-06-05); spec PRs #2889, #2890, #2891 and #2907 have all merged since. The hand-written mcp.types.jsonrpc constants still carried the pre-#2907 numerals.

Pinned spec commit: 2852f30e (current main HEAD at the time of this PR). The draft schema is byte-identical from f817239f (the #2907 merge) through 2852f30e — the three commits in between are docs/blog only — so any commit in that range would do; pinning at HEAD avoids an immediate re-bump.

What changed

  • schema/PINNED.json + schema/2026-07-28.json: bumped to 2852f30e, regenerated src/mcp/types/v2026_07_28/__init__.py.
  • scripts/gen_surface_types.py: added NotificationMetaObject (new in spec #2889) to the 2026 OPEN_CLASSES set so it keeps extra="allow" like the other _meta carriers.
  • src/mcp/types/jsonrpc.py: MISSING_REQUIRED_CLIENT_CAPABILITY -32003 → -32021, UNSUPPORTED_PROTOCOL_VERSION -32004 → -32022, new HEADER_MISMATCH = -32020, and the allocation-policy comment rewritten to match #2907 (-32000..-32019 implementation-defined, -32020..-32099 spec-reserved, -32002/-32042 reserved-never-reused). CONNECTION_CLOSED/REQUEST_TIMEOUT stay in the implementation-defined band.
  • src/mcp/types/__init__.py: re-export HEADER_MISMATCH.
  • src/mcp/types/_types.py: docstring numerals updated on the two error-data models.
  • src/mcp/types/methods.py: dropped the ("notifications/elicitation/complete", "2026-07-28") and ("notifications/progress", "2026-07-28") rows — both removed from the draft ClientNotification/ServerNotification unions by spec #2889/#2891.
  • .github/actions/conformance/expected-failures*.yml: stale -32001 HeaderMismatch comment → -32020.
  • Tests: tests/types/{test_methods.py,test_parity.py} updated for the regen delta (ElicitationCompleteNotification removed; HeaderMismatchError/NotificationMetaObject/Error3 added; ClientNotification collapsed to single-arm). tests/server/test_runner.py switches its post-drop barrier from notifications/progress (no longer a 2026 client notification) to a custom non-spec method.

SUPPORTED_PROTOCOL_VERSIONS and LATEST_PROTOCOL_VERSION are untouched; the renumbered constants are not referenced on any 2025-era code path, so this is a no-op for unpinned clients and legacy servers.

Not in this PR: the elicit_url / send_elicit_complete helpers in peer.py, server/session.py and server/mcpserver/context.py still take a mandatory elicitation_id and emit notifications/elicitation/complete. Those are 2025-11-25 API built on the monolith types (which are a superset and keep the field); at 2026-07-28 the URL-elicitation flow is replaced by MRTR input_required results, so version-gating or deprecating those helpers belongs with #2898 / #2904, not the schema bump.

How Has This Been Tested?

gen_surface_types.py --check, pyright, ruff, and ./scripts/test (full suite, 100% coverage, strict-no-cover clean).

Breaking Changes

The numeric values of mcp.types.MISSING_REQUIRED_CLIENT_CAPABILITY and mcp.types.UNSUPPORTED_PROTOCOL_VERSION change. These constants were added for the unreleased 2026-07-28 surface and are not emitted on any current code path, so there's no migration entry.

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

The published @modelcontextprotocol/conformance@0.2.0-alpha.4 (this repo's current pin, set by #2911) was cut from 7a620cb1, which predates conformance#353 — the harness's http-standard-headers scenario still asserts the old codes. That's fine for this PR (nothing here emits these codes yet), but the conformance pin will need a bump to a post-#353 alpha before the server-stateless and header-validation implementations can assert -32020..-32022 without a waiver.

AI Disclaimer