chore: renumber draft error codes per modelcontextprotocol#2907

Merged
FE
4mo ago
+73-57

Renumbers the draft-revision error codes to match the allocation policy that landed in modelcontextprotocol/modelcontextprotocol#2907:

ErrorOldNew
HeaderMismatch-32001-32020
MissingRequiredClientCapability-32003-32021
UnsupportedProtocolVersion-32004-32022

Motivation and Context

modelcontextprotocol/modelcontextprotocol#2907 partitions the JSON-RPC server-error range (-32000..-32019 legacy/implementation-defined, -32020..-32099 reserved for the MCP spec) and renumbers the draft-only codes accordingly. The conformance suite still pinned the pre-policy numbers, so a server returning the now-spec-mandated -32020/-32021/-32022 would fail checks that expect the old values, and the suite's own mocks and fixtures would emit codes the new spec text reserves for legacy implementation use.

What changed

  • npm run sync-schema -- f817239f re-vendors src/spec-types/draft.ts (the schema diff between the previous pin and f817239f is exactly the renumber plus the new allocation-policy doc comment). src/scenarios/server/http-standard-headers.ts already imported HEADER_MISMATCH from the vendored types, so its assertion picks up the new value automatically.
  • Every literal -32001/-32003/-32004 reference across the stateless mock, the everything-server fixture, the server-stateless and SEP-2243 server scenarios, the request-metadata client scenario, all affected tests, and the sep-2243.yaml/sep-2575.yaml requirement rows is updated to the new code.
  • The everything-client's negotiation retry now checks for -32022 only (the previous -32004 || -32001 tolerance for pre-dedicated-code servers is dropped — those numbers are now in the legacy sub-range and the paired mocks emit -32022).
  • src/seps/traceability.json is generated; it still carries the old text and is left for the scheduled refresh workflow per AGENTS.md.

How Has This Been Tested?

  • npm run check, npm run build, npm test — all green (293 tests).
  • node dist/index.js client --command "npx tsx examples/clients/typescript/everything-client.ts" --suite draft: identical to pre-change baseline (request-metadata 7/7 confirms the everything-client's -32022 retry check works against the mock's new emission).

Breaking Changes

For draft-revision servers under test: the suite now requires the post-#2907 codes. Servers still emitting the pre-policy -32001/-32003/-32004 values will fail the corresponding checks (or need an expected-failures entry) until they update — that's the intended outcome of the spec renumber. Dated 2025-x revisions are unaffected.

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

  • This is the "conformance pins for SEP-2243/SEP-2575 codes" follow-up named in modelcontextprotocol/modelcontextprotocol#2907's description.
  • #336 (the draft re-derivation of the server-stateless error-code table) should be rebased on top of this; its remaining content is then purely the precedence questions #2907 did not settle (which code applies when a missing _meta field and a present header overlap, and HeaderMismatch vs UnsupportedProtocolVersion precedence when both rules trigger).
  • No check ids or severities change here; the SHOULD/MUST split in sep-2243.yaml for the standard- vs custom-header error-code requirement is unchanged (renumber only).