@modelcontextprotocol/[email protected]：新增OAuth scope挑战

Minor Changes

• #1624 6032170 Thanks @SamMorrowDrums! - Add request-time OAuth scope challenges for tools, resources, resource templates,
• and prompts. Each primitive's scopeChallenge callback receives the parsed
• request and verified authentication info, then either continues or returns the
• exact scope set for an insufficient_scope response. requireScopes provides a
• small helper for static all-of checks.
• createMcpHandler and Streamable HTTP transports return HTTP 403 with an
• insufficient_scope challenge before handler execution or SSE setup. The
• preflight is active whenever a registered primitive carries a scopeChallenge
• callback — there is no handler- or transport-level configuration. The
• challenge's WWW-Authenticate header is built by the same formatter as the
• bearer-auth 401/403 answers, and its resource_metadata parameter is derived
• from the verified AuthInfo: requireBearerAuth / verifyBearerToken now
• stamp their configured resourceMetadataUrl onto the AuthInfo they return
• (new optional AuthInfo.resourceMetadataUrl field), with a fallback to the
• well-known location for an HTTP(S) RFC 8707 resource identifier; the
• parameter is omitted when neither is available.

Patch Changes

• #2726 6fa4227 Thanks @LuckTerence! - SdkError and SdkHttpError accept standard ErrorOptions as an optional fourth constructor argument and forward it to Error, so a wrapped error is reachable through the standard Error.cause chain. Version-negotiation probe failures (SdkErrorCode.EraNegotiationFailed) now use it: the underlying TypeError: fetch failed and the DNS or socket error beneath it surface via error.cause, so pino, Sentry, and util.inspect render ENOTFOUND / ECONNREFUSED / ETIMEDOUT instead of stopping at the SdkError (#2657). The previous error.data.cause slot is still populated for compatibility but is deprecated and slated for removal; read error.cause instead.
• #2654 03842cd Thanks @pshah19! - Treat request id 0 as a real id. Two guards tested a RequestId for truthiness, so the legal JSON-RPC ids 0 and '' were read as absent. Id 0 is not a corner case: the outbound request counter is zero-based, so it is the first id every peer assigns, which on the server→client leg is the first sampling/createMessage, elicitation/create, or roots/list a server sends.
• notifications/cancelled carrying id 0 was ignored, and the in-flight handler ran to completion with its AbortSignal never fired.
• A notification sent with relatedRequestId: 0 wrongly passed the debounce gate (for methods opted into debouncedNotificationMethods). Because the pending set is keyed by method alone, a second such notification in the same tick was silently dropped rather than sent.
• Absent is now the only value that means "no id".
• #2668 3e90449 Thanks @KKonstantinov! - Stop sending notifications/cancelled for the initialize handshake. The spec is explicit that a client MUST NOT attempt to cancel its initialize request, but the outbound cancel path fired for any in-flight request: aborting the AbortSignal passed to connect(), or letting the handshake hit its timeout, put a forbidden cancellation on the wire naming the initialize request id.
• The local behaviour is unchanged — the caller's promise still rejects with the same abort/timeout error, and connect() still tears the connection down. Only the wire notification is suppressed. Every other method keeps the existing cancellation path.
• #2698 7b781ed Thanks @maxisbey! - Read Streamable HTTP request bodies with a size limit. Every SDK-owned body read —
• WebStandardStreamableHTTPServerTransport (and the Node transport built on it),
• createMcpHandler, toNodeHandler, and createMcpHonoApp's JSON pre-parse — now stops at
• 4 MiB by default (the limit the legacy SSE transport already uses; the Express adapter and stdio
• bound their reads too) and answers 413 Payload Too Large before anything is parsed.
• toWebRequest (when it reads the Node stream itself) now rejects once the body exceeds the
• limit with an error whose name is 'RequestBodyTooLargeError' and status is 413, and
• toNodeHandler answers that with 413; hand-wired callers of toWebRequest should handle the
• rejection or pass a pre-parsed body, and isLegacyRequest reports such a request as non-legacy
• so the modern handler answers it. JSON-RPC batch arrays are limited to 100 messages; a longer
• batch is answered 400 / -32600 and none of it is dispatched.
• The limit is configurable with a new maxRequestBodySize option (bytes, default
• DEFAULT_MAX_REQUEST_BODY_SIZE = 4 MiB, exported from @modelcontextprotocol/server) on
• WebStandardStreamableHTTPServerTransportOptions, CreateMcpHandlerOptions (forwarded to its
• stateless legacy leg; isLegacyRequest and legacyStatelessFallback take the same option),
• CreateMcpHonoAppOptions, and ToNodeHandlerOptions / ToWebRequestOptions (the adapter's
• bound applies before the handler's, so raise both). The bounded reader is exported as
• readRequestBody for adapter authors. Hosts that pre-parse the body and pass it as
• parsedBody skip the SDK's read and its size limit entirely; the batch bound applies either way.
• createMcpHonoApp and createMcpExpressApp now run their Host/Origin validation before the
• JSON body parser, so a request from a disallowed Host or Origin with an invalid JSON body is
• answered 403 rather than 400, and its body is not read.
• #2590 75dc7ea Thanks @davidpavlovschi! - Reject a modern (2026-07-28) POST that omits the required MCP-Protocol-Version header.
• createMcpHandler accepted a request whose body carried a valid per-request _meta
• envelope but whose MCP-Protocol-Version header was absent: the request was classified
• modern, dispatched, and answered 200 — tool handlers ran. Only the mismatch case
• (header present, disagreeing with the body) was rejected, so of the standard headers
• SEP-2243 requires on a modern POST, presence was enforced for Mcp-Method (and for
• Mcp-Name on the methods that mirror params.name / params.uri) but not for
• MCP-Protocol-Version.
• Such a request is now refused with 400 Bad Request and JSON-RPC -32020
• (HeaderMismatch), matching the shape the sibling missing-header cells already emit and
• echoing the request id — per the Streamable HTTP spec, which requires the header on every
• POST and lists a missing required standard header as a HeaderMismatch failure. The
• spec's allowance to treat a header-less request as 2025-03-26 is available only to a
• server that also serves pre-2025-06-18 clients, and permits routing it to legacy
• handling — never serving it as 2026-07-28; under legacy: 'reject' the requirement is
• unconditional.
• Era classification is deliberately unchanged and stays body-primary: a proxy that strips
• the header still must not change the era, so such a request is still classified modern
• and is refused one rung later, at standard-header-validation — the same rung that
• already answers a missing Mcp-Method. Legacy-era traffic is untouched, notifications
• are unaffected, body-less GET / DELETE session operations are method-routed before
• any header validation, and stdio serving (which has no HTTP headers) is not involved.
• Clients built with this SDK always send the header, so no first-party client is affected;
• hand-rolled clients that omitted it must add it.