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

[SamMorrowDrums]

SEP-2792: Reference Implementation

This PR implements the reference implementation for SEP-2792: Internationalization via Per-Request Language Negotiation.

Note: This is a reference implementation intended to demonstrate the SEP's feasibility. It is not intended to merge until SEP-2792 reaches Accepted status.

What shipped in the SDK

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

• Constants: ACCEPT_LANGUAGE_META / CONTENT_LANGUAGE_META (using io.modelcontextprotocol/ vendor prefix)
• Getter/setter helpers: getAcceptLanguage, setAcceptLanguage, getContentLanguage, setContentLanguage
• negotiateLanguage(acceptLanguage, available, defaultLocale?) — thin wrapper around @formatjs/intl-localematcher for RFC 4647 matching

Client Streamable HTTP transport (packages/client/src/client/streamableHttp.ts):

• Mirrors _meta[acceptLanguage] → Accept-Language HTTP header on outbound requests
• Throws on mismatch if header is manually set to a conflicting value (SEP-2243 strict-mismatch pattern)

Server Streamable HTTP transport (packages/server/src/server/streamableHttp.ts):

• Validates Accept-Language header vs _meta on inbound POST (returns HTTP 400 on mismatch)
• Copies header → _meta when only header is present (transparent to handler code)
• Mirrors _meta[contentLanguage] → Content-Language response header

Example server & client

• examples/server/src/i18nExample.ts: A get_greeting tool localized in en/fr/de, supporting both stdio and HTTP
• examples/client/src/i18nClient.ts: Exercises three scenarios — explicit English, French-Canadian with quality-value fallback, and Japanese (forces fallback to English)

Sample client output (stdio transport):

=== SEP-2792 i18n Client Demo ===

--- Accept-Language: "en" ---
  tools/list → title: "Get Greeting", description: "Returns a greeting in the negotiated language"
              contentLanguage: "en"
  tools/call → text: "Hello, World! Welcome."
              contentLanguage: "en"

--- Accept-Language: "fr-CA,fr;q=0.9,en;q=0.5" ---
  tools/list → title: "Obtenir un salut", description: "Retourne un salut dans la langue négociée"
              contentLanguage: "fr"
  tools/call → text: "Bonjour, World ! Bienvenue."
              contentLanguage: "fr"

--- Accept-Language: "ja" ---
  tools/list → title: "Get Greeting", description: "Returns a greeting in the negotiated language"
              contentLanguage: "en"
  tools/call → text: "Hello, World! Welcome."
              contentLanguage: "en"

AI Disclosure

This PR was authored with assistance from GitHub Copilot (claude-opus-4.6).

---

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

[changeset-bot]

⚠️ No Changeset found

Latest commit: 13be363

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]

Open in StackBlitz

@modelcontextprotocol/client

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

@modelcontextprotocol/codemod

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

@modelcontextprotocol/server

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

@modelcontextprotocol/express

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

@modelcontextprotocol/fastify

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

@modelcontextprotocol/hono

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

@modelcontextprotocol/node

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

commit: 13be363

[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).