SEP-2792: Reference implementation for per-request language negotiation

[SamMorrowDrums]

Summary

Reference implementation for SEP-2792: Per-Request Language Negotiation, aligned to the authoritative specification at ce12e646 and the current TypeScript SDK v2 architecture.

This remains a draft while SEP-2792 is Draft. It implements language-preference propagation and reporting; it does not automatically translate SDK content or infer timezone, currency, formatting, collation, units, or other locale behavior.

Public API

Both @modelcontextprotocol/client and @modelcontextprotocol/server re-export:

• ACCEPT_LANGUAGE_META / CONTENT_LANGUAGE_META
• getAcceptLanguage, getRawAcceptLanguage, setAcceptLanguage
• getContentLanguage, getErrorContentLanguage, getMessageContentLanguage, setContentLanguage, setErrorContentLanguage
• isValidAcceptLanguage, negotiateLanguage, languageHeaderValueConflicts

RequestOptions.acceptLanguage makes the preference available on every request, including methods without explicit params and the connect-time server/discover/initialize exchange. It is request-scoped and is preserved across MRTR retry legs without becoming connection/session state.

Implementation helpers live once in @modelcontextprotocol/core-internal; obsolete duplicate v1 packages/core helpers and old example locations were removed.

Protocol and transport behavior

• Canonical request field: params._meta["io.modelcontextprotocol/acceptLanguage"].
• Canonical result/error/notification field: _meta["io.modelcontextprotocol/contentLanguage"], including error.data._meta and InputRequiredResult._meta.
• Strict RFC 9110 Accept-Language grammar validation plus weighted, wildcard-aware, case-insensitive RFC 4647 lookup. Malformed canonical values are treated as absent after mirror agreement and do not error by themselves.
• Unsupported preferences fall back without error to the server-defined default, which is reported as the actual contentLanguage.
• Streamable HTTP clients mirror one exact Accept-Language field line. Servers use Fetch's complete combined field value (repeated lines combine with ", "), tolerate a missing mirror, ignore a bare header, and return HTTP 400 / HeaderMismatch -32020 on exact disagreement before grammar validation.
• JSON success and object-shaped error responses mirror Content-Language; conflicting duplicated values are malformed. SSE remains canonical per message, omits a stream-wide header by default, and clients enforce agreement if a server does provide one.
• Language-dependent JSON responses include Vary: Accept-Language; stripped-header responses are Cache-Control: private when a shared HTTP cache cannot observe the canonical variant.

Caching and MRTR

The client response cache keys cacheable list/resource results by the exact request preference in addition to method/params/server/principal partition. Distinct preferences never share an entry even when they select the same language, and invalidations remove every language variant. Existing ttlMs and cacheScope semantics remain unchanged.

The runnable examples/i18n story uses a deployment approval workflow: stable deploy_release/environment identifiers with localized discovery title, progress text, elicitation message/schema labels, result/error display, default fallback, preference changes/omission, stdio carriage, HTTP mirroring, and current inputRequired/elicitation/create retry behavior. Its matrix is modern-only because legacy stateless HTTP cannot carry the MRTR return path.

Validation

• pnpm install --frozen-lockfile ✅
• pnpm build:all ✅
• pnpm test:all ✅
• pnpm -r typecheck ✅
• Changed workspace lint (core-internal, client, server, node, examples) ✅
• pnpm run run:examples — 77/77 legs passed ✅
• Independent code review plus two fix/re-review rounds — no remaining findings ✅

pnpm check:all completes snippet sync and all typechecks, then the clean current-main tree reports pre-existing import/no-extraneous-dependencies manifest classification errors in untouched test/helpers, test/conformance, and test/e2e workspaces. Those unrelated manifests are not changed by this PR.

Release and limitations

• Adds a minor changeset for @modelcontextprotocol/client and @modelcontextprotocol/server.
• Adds no runtime dependency; the stale @formatjs/intl-localematcher approach was removed in favor of the small standards-compatible implementation.
• Servers still own supported languages, defaults, translation catalogs, and semantic preservation. Explicit domain language arguments should take precedence for content they control; negotiated language remains fallback context.
• Unassociated server notifications have no inferred request language.
• Until released, consumers must use this branch/commit or the PR preview packages; the currently published 2.0.0 packages do not contain this API.

AI disclosure

Authored with GitHub Copilot assistance.

Co-authored-by: Copilot App 223556219+Copilot@users.noreply.github.com

[changeset-bot]

🦋 Changeset detected

Latest commit: 0ca56be

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 10 packages

Name	Type
@modelcontextprotocol/client	Minor
@modelcontextprotocol/server	Minor
@modelcontextprotocol/express	Major
@modelcontextprotocol/fastify	Major
@modelcontextprotocol/hono	Major
@modelcontextprotocol/node	Major
@modelcontextprotocol/core	Minor
@modelcontextprotocol/server-legacy	Minor
@modelcontextprotocol/codemod	Minor
@modelcontextprotocol/core-internal	Patch

Not sure what this means? Click here to learn what changesets are.

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

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/client

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

@modelcontextprotocol/codemod

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

@modelcontextprotocol/core

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

@modelcontextprotocol/server

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

@modelcontextprotocol/server-legacy

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

@modelcontextprotocol/express

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

@modelcontextprotocol/fastify

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

@modelcontextprotocol/hono

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

@modelcontextprotocol/node

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

commit: 0ca56be

[SamMorrowDrums]

Update: Review feedback addressed (commit 5a5f548)

Following @pja-ant's review on the SEP (modelcontextprotocol/modelcontextprotocol#2792), three changes applied per SEP commit b5667477:

1. -32001 HeaderMismatch error code

• Defined HEADER_MISMATCH_ERROR_CODE = -32001 constant in packages/core/src/shared/i18n.ts with JSDoc pointing at SEP-2243
• Server: mismatch response now uses -32001 (was -32000)
• Client: mismatch error message references HeaderMismatch code (still uses SdkErrorCode.SendFailed for the throw since SdkErrorCode has no -32001 variant; message is clear)
• Tests assert on -32001

2. Error-response localization

• Added getErrorContentLanguage(errorData) and setErrorContentLanguage(data, lang) helpers for error.data._meta
• Server transport _extractContentLanguage() now checks both JSONRPCResultResponse and JSONRPCErrorResponse for Content-Language mirroring
• Example server: empty name input now throws a localized ProtocolError with error.data._meta[contentLanguage]
• Example client: demonstrates catching and reading the localized error
• New unit tests (6) and integration test (1) for the error path

3. No batching

• Client _extractAcceptLanguage() simplified: no longer unions across batch items. Takes first message only (array param kept for type compatibility with existing _send signature, but no batch-specific logic).

Test counts

• Core: 582 passed (+10 new)
• Server: 71 passed (+1 new)
• Client: 364 passed (unchanged)
• Build: ✅
• Lint: ✅ (all modified packages)

[SamMorrowDrums]

Remove header/body mismatch rejection (SEP commit 63dc3e1a)

Per @pja-ant's review on SEP-2792: intermediaries (CloudFront, Fastly/accept.language_lookup, Varnish/vmod_accept) routinely strip or rewrite Accept-Language, making byte-equality enforcement between header and _meta unreliable. The strict mismatch rule is dropped.

Changes in commit cdb62fb:

1. Server: no mismatch rejection — validateAndCopyAcceptLanguage renamed to copyAcceptLanguageFromHeader. When both header and _meta are present, _meta is canonical (header ignored). Header only used as fallback when _meta is absent.

2. Client: no mismatch throw — _meta[acceptLanguage] is always mirrored to Accept-Language header unconditionally, regardless of any pre-existing header value.

3. Deleted HEADER_MISMATCH_ERROR_CODE constant — no longer needed anywhere.

4. New positive tests — "intermediary stripped/rewrote header" scenarios: server succeeds and honors _meta value even when header disagrees or is absent.

5. Kept as-is — best-effort header mirroring, error-response localization via error.data._meta, negotiateLanguage helpers, examples, stdio behavior.

All builds, typecheck, lint, and tests pass (core 581, server 72, client 364).

[SamMorrowDrums]

Remove bare-header fallback (SEP commit 8e1b6f4d)

_meta[acceptLanguage] is now the only canonical carrier. Servers MUST NOT treat a bare Accept-Language header (without _meta) as an MCP language preference.

Changes in commit 13be363:

• Removed copyAcceptLanguageFromHeader method and its call site from the server Streamable HTTP transport. The server no longer reads the inbound Accept-Language header at all.
• Updated test: "mirrors Accept-Language header into _meta when only header is present" → now asserts server returns default language (en) when only header is present without _meta.
• Kept as-is: client best-effort mirror of _meta → Accept-Language outbound; server mirror of _meta[contentLanguage] → Content-Language response header.

All builds, typecheck, lint, and tests pass (server 72 tests).

[SamMorrowDrums]

Reinstate byte-equality mismatch rule (SEP commit 4e2a5be9)

Per WG feedback (Kurtis / pja-ant), the strict byte-equality design is reinstated. Commit effa20d.

Summary of changes:

HEADER_MISMATCH_ERROR_CODE = -32005 (not -32001; avoids conflict with Python/Kotlin REQUEST_TIMEOUT). Provisional — will migrate once SEP-2243/SEP-2678/PR #2642 ratify the final code.

Server request path:

• Both Accept-Language header and _meta[acceptLanguage] present → byte-equality comparison, no normalization. Mismatch → HTTP 400 + JSON-RPC -32005.
• _meta present, header absent → use _meta (CDN-strip tolerance).
• Header present, _meta absent → ignore header (not MCP preference).

Client response path (new):

• JSON response with both Content-Language header and _meta[contentLanguage] → byte-equality check. Mismatch → throws as malformed response.

Tests (11 i18n tests):

• Byte-identical → success
• Mismatch: different tag, lowercased, reordered ranges, extra spacing, q-value format → all reject with -32005
• _meta-only (header absent) → success
• Header-only (_meta absent) → server ignores header
• Response Content-Language mirror
• Error response Content-Language mirror
• stdio mid-session switch

All builds, typecheck, lint, and tests pass (core 582, server 76, client 364).

[SamMorrowDrums]

SEP-2792 Reference Implementation — Complete Rewrite on Current Main

This PR has been completely rebuilt on the current modelcontextprotocol/typescript-sdk main architecture (July 2026). The implementation now conforms to the settled SEP-2792 contract from transports-wg PR #42 (commit c85169e8).

What's implemented:

Core (packages/core-internal/src/shared/i18n.ts):

• Constants: ACCEPT_LANGUAGE_META, CONTENT_LANGUAGE_META
• Helpers: get/setAcceptLanguage, get/setContentLanguage
• negotiateLanguage() — thin wrapper around @formatjs/intl-localematcher (RFC 4647)
• Exported via core-internal/public and re-exported by both client and server packages

Server (createMcpHandler.ts):

• Accept-Language byte-equality validation (header vs _meta, uses existing HEADER_MISMATCH_ERROR_CODE = -32020)
• CDN-strip tolerance: _meta present + header absent → accepted
• Bare header ignored: header present + _meta absent → no language preference
• Content-Language / Vary: Accept-Language / Cache-Control: private response headers

Client (streamableHttp.ts):

• Accept-Language header emission (mirrors _meta[acceptLanguage])
• Content-Language response mismatch detection (JSON responses)

Tests (14 passing):

• Byte-equality matrix (case, spacing, q-formatting, reordered ranges)
• CDN-strip tolerance and bare-header ignore
• Content-Language/Vary/Cache-Control response headers
• Error response path
• stdio per-request language switch (en → de without reinitialize)

Example (examples/i18n/):

• server.ts: get_greeting tool with en/fr/de translations
• client.ts: demonstrates language preference switching via HTTP and stdio

Architecture notes:

• Uses existing HEADER_MISMATCH_ERROR_CODE = -32020 from inboundClassification.ts
• No changes to @modelcontextprotocol/core (stays runtime-neutral)
• @formatjs/intl-localematcher added as dependency to core-internal only

Known limitations (draft):

• Branch is based on old fork state; transport file diffs show full-file replacement against the old PR HEAD. The PR target (upstream main) has the correct base.
• pnpm-lock.yaml not pushed via API (too large); will be regenerated on merge.

Refs: SEP-2792 (transports-wg PR #42, commit c85169e8)