Skip to content

docs(core): note that the protocol version constants are legacy-era only - #2585

Open
katayama8000 wants to merge 1 commit into
modelcontextprotocol:mainfrom
katayama8000:docs/legacy-era-protocol-constants
Open

docs(core): note that the protocol version constants are legacy-era only#2585
katayama8000 wants to merge 1 commit into
modelcontextprotocol:mainfrom
katayama8000:docs/legacy-era-protocol-constants

Conversation

@katayama8000

Copy link
Copy Markdown

Problem

@modelcontextprotocol/core exports three protocol-version constants from its package root — and @modelcontextprotocol/server re-exports all three — with no TSDoc on any of them:

export const LATEST_PROTOCOL_VERSION = '2025-11-25';
export const DEFAULT_NEGOTIATED_PROTOCOL_VERSION = '2025-03-26';
export const SUPPORTED_PROTOCOL_VERSIONS = [LATEST_PROTOCOL_VERSION, '2025-06-18', '2025-03-26', '2024-11-05', '2024-10-07'];

They describe the legacy initialize era only, but nothing on the public surface says so. From outside the SDK, LATEST_PROTOCOL_VERSION === '2025-11-25' in a v2.0.0 install reads as "v2 does not implement 2026-07-28" — which is wrong, since createMcpHandler classifies inbound requests via classifyInboundRequest and never consults SUPPORTED_PROTOCOL_VERSIONS at all. Only WebStandardStreamableHTTPServerTransport.validateProtocolVersion() does.

This is not hypothetical: while planning a v1 → v2 migration we read these constants as an era signal and initially concluded v2 lacked 2026-07-28 support, before finding server/discover and the Mcp-Method / Mcp-Name handling in the shipped tarballs.

Change

Comments only — no behaviour, API, or value changes.

The two-era model is already stated precisely in packages/core-internal/src/shared/protocolEras.ts:

Deliberately separate from SUPPORTED_PROTOCOL_VERSIONS (the legacy initialize list), so adding a revision here can never leak a modern version string into a 2025-era handshake. Internal — not part of the public API surface.

This PR carries that same reasoning onto the three public constants, so consumers reading the published .d.ts see it too. RELATED_TASK_META_KEY in the same file already carries a similar clarifying note; these three were the remaining undocumented exports there.

Formatting verified with the repo's Prettier config.

LATEST_PROTOCOL_VERSION, DEFAULT_NEGOTIATED_PROTOCOL_VERSION and
SUPPORTED_PROTOCOL_VERSIONS are exported from the package root but carry no
TSDoc, so nothing on the public surface says they describe only the legacy
`initialize` era. Reading LATEST_PROTOCOL_VERSION === '2025-11-25' therefore
looks like "v2 does not implement 2026-07-28".

The two-era split is already documented internally, in
packages/core-internal/src/shared/protocolEras.ts. This copies that reasoning
onto the public constants. Comments only; no behaviour or API change.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@katayama8000
katayama8000 requested a review from a team as a code owner July 30, 2026 13:56
@changeset-bot

changeset-bot Bot commented Jul 30, 2026

Copy link
Copy Markdown

⚠️ No Changeset found

Latest commit: 408ff15

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

@pkg-pr-new

pkg-pr-new Bot commented Jul 30, 2026

Copy link
Copy Markdown

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/@modelcontextprotocol/client@2585

@modelcontextprotocol/codemod

npm i https://pkg.pr.new/@modelcontextprotocol/codemod@2585

@modelcontextprotocol/core

npm i https://pkg.pr.new/@modelcontextprotocol/core@2585

@modelcontextprotocol/server

npm i https://pkg.pr.new/@modelcontextprotocol/server@2585

@modelcontextprotocol/server-legacy

npm i https://pkg.pr.new/@modelcontextprotocol/server-legacy@2585

@modelcontextprotocol/express

npm i https://pkg.pr.new/@modelcontextprotocol/express@2585

@modelcontextprotocol/fastify

npm i https://pkg.pr.new/@modelcontextprotocol/fastify@2585

@modelcontextprotocol/hono

npm i https://pkg.pr.new/@modelcontextprotocol/hono@2585

@modelcontextprotocol/node

npm i https://pkg.pr.new/@modelcontextprotocol/node@2585

commit: 408ff15

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant