@daloyjs/core 1.0.0-rc.6 → 1.0.0-rc.8

package/dist/ip-restriction.d.ts

@@ -7,7 +7,7 @@
  *
  * @since 0.19.0
  */
-import type { BaseContext, Hooks } from "./types.js";
+import type { Hooks, IdentityGateContext } from "./types.js";
 /**
  * Options for {@link ipRestriction}. At least one of `allow` or `deny` must
  * be provided; supplying both runs deny-first then allow-otherwise (deny
@@ -36,14 +36,28 @@ export interface IpRestrictionOptions {
      * Provide a function to read adapter connection metadata or a trusted
      * custom header (e.g. a CDN-specific identifier).
      */
-    resolveIp?: (ctx: BaseContext<any, any>) => string | undefined;
+    resolveIp?: (ctx: IdentityGateContext) => string | undefined;
     /**
      * Read `X-Forwarded-For` / `X-Real-IP` in the default resolver. Defaults
      * to `false` because those headers are client-spoofable unless every
      * request reaches Daloy through a proxy chain you control. Pair with
      * `new App({ trustProxy: true })` in production.
+     *
+     * When enabled, the resolver reads the **rightmost** `X-Forwarded-For`
+     * entry — the one your immediate proxy appended — never the
+     * attacker-influenceable leftmost one, so a spoofed left entry cannot
+     * bypass an allow-list or dodge a deny. Behind more than one proxy hop,
+     * set {@link trustedHops} instead.
      */
     trustProxyHeaders?: boolean;
+    /**
+     * Declare exactly how many proxy hops sit between Daloy and the public
+     * internet. Implies proxy-header trust and reads the client IP that many
+     * entries from the right of `X-Forwarded-For` via
+     * {@link "./conn-info.js".resolveForwardedClientIp}. Must be an integer in
+     * [1, 64]; validated at construction.
+     */
+    trustedHops?: number;
     /**
      * Response message when a request is rejected. Defaults to
      * `"IP address not permitted"`. Avoid echoing the client IP back —
@@ -87,7 +101,7 @@ export interface IpMatcher {
  *
  * @param opts Allow/deny lists plus IP-resolution options; see
  *   {@link IpRestrictionOptions}. Deny matches always win over allow.
- * @returns A {@link Hooks} object whose `beforeHandle` enforces the lists,
+ * @returns A {@link Hooks} object whose `preBody` hook enforces the lists,
  *   failing closed (403) when the client IP cannot be resolved or parsed.
  * @throws Error at setup time when neither `allow` nor `deny` is provided,
  *   or when a pattern is not a valid IP/CIDR.

package/dist/ip-restriction.js

@@ -8,6 +8,7 @@
  * @since 0.19.0
  */
 import { ForbiddenError } from "./errors.js";
+import { resolveForwardedClientIp, resolveForwardedTrust } from "./conn-info.js";
 /**
  * Block or allow requests by source IP / CIDR range. In direct Web-standard
  * runtimes, pass `resolveIp` from the adapter-specific connection metadata.
@@ -28,7 +29,7 @@ import { ForbiddenError } from "./errors.js";
  *
  * @param opts Allow/deny lists plus IP-resolution options; see
  *   {@link IpRestrictionOptions}. Deny matches always win over allow.
- * @returns A {@link Hooks} object whose `beforeHandle` enforces the lists,
+ * @returns A {@link Hooks} object whose `preBody` hook enforces the lists,
  *   failing closed (403) when the client IP cannot be resolved or parsed.
  * @throws Error at setup time when neither `allow` nor `deny` is provided,
  *   or when a pattern is not a valid IP/CIDR.
@@ -40,10 +41,16 @@ export function ipRestriction(opts) {
     }
     const allow = (opts.allow ?? []).map(compileCidrMatcher);
     const deny = (opts.deny ?? []).map(compileCidrMatcher);
-    const resolveIp = opts.resolveIp ?? (opts.trustProxyHeaders ? forwardedIpResolver : noIpResolver);
+    const hops = resolveForwardedTrust("ipRestriction()", opts);
+    const resolveIp = opts.resolveIp ?? (hops !== undefined ? forwardedIpResolver(hops) : noIpResolver);
     const message = opts.message ?? "IP address not permitted";
     return {
-        beforeHandle(ctx) {
+        // `preBody`, not `beforeHandle`: a gate that returns a Response from
+        // `beforeHandle` can be preempted by any earlier `beforeHandle` middleware
+        // that short-circuits first — a `responseCache()` HIT mounted above it would
+        // serve a deny-listed address the cached body. `preBody` always runs first,
+        // so the allow/deny lists hold regardless of mount order.
+        preBody(ctx) {
             const raw = resolveIp(ctx);
             if (!raw)
                 throw new ForbiddenError(message);
@@ -62,12 +69,8 @@ export function ipRestriction(opts) {
 function noIpResolver(_ctx) {
     return undefined;
 }
-function forwardedIpResolver(ctx) {
-    const headers = ctx.request.headers;
-    const forwarded = headers.get("x-forwarded-for");
-    if (forwarded)
-        return forwarded.split(",")[0]?.trim();
-    return headers.get("x-real-ip") ?? undefined;
+function forwardedIpResolver(hops) {
+    return (ctx) => resolveForwardedClientIp(ctx.request, hops);
 }
 /**
  * Test whether a parsed IP falls inside a compiled CIDR matcher, comparing

package/dist/mcp.d.ts

@@ -2,17 +2,57 @@ import type { PathString, RouteDefinition } from "./types.js";
 /**
  * Latest MCP protocol version DaloyJS negotiates by default.
  *
- * @see https://modelcontextprotocol.io/specification/2025-11-25
+ * @see https://modelcontextprotocol.io/specification/2026-07-28
  * @since 1.0.0
  */
-export declare const MCP_PROTOCOL_VERSION = "2025-11-25";
+export declare const MCP_PROTOCOL_VERSION = "2026-07-28";
+/**
+ * First MCP revision of the *stateless* ("modern") era: version, client
+ * identity, and client capabilities travel in each request's `_meta` instead
+ * of being established once by an `initialize` handshake.
+ *
+ * Revisions are `YYYY-MM-DD` strings, so a lexicographic comparison against
+ * this constant correctly classifies every past and future revision.
+ *
+ * @since 1.0.0
+ */
+export declare const MCP_MODERN_ERA_MIN_VERSION = "2026-07-28";
 /**
  * Protocol revisions accepted by {@link createMcpHandler} unless the caller
  * provides an explicit `protocolVersions` list.
  *
+ * The list spans both protocol eras: the stateless `2026-07-28` revision and
+ * the older handshake-based revisions, so one endpoint serves modern and
+ * legacy MCP clients at the same time.
+ *
  * @since 1.0.0
  */
 export declare const MCP_PROTOCOL_VERSIONS: readonly string[];
+/**
+ * Reserved `_meta` keys defined by MCP `2026-07-28` for per-request protocol
+ * metadata. Exported so applications and tests can build spec-compliant
+ * requests without hard-coding string literals.
+ *
+ * @since 1.0.0
+ */
+export declare const MCP_META_KEYS: {
+    readonly protocolVersion: "io.modelcontextprotocol/protocolVersion";
+    readonly clientInfo: "io.modelcontextprotocol/clientInfo";
+    readonly clientCapabilities: "io.modelcontextprotocol/clientCapabilities";
+    readonly logLevel: "io.modelcontextprotocol/logLevel";
+    readonly serverInfo: "io.modelcontextprotocol/serverInfo";
+};
+/**
+ * JSON-RPC error codes defined by the MCP specification in its reserved
+ * `-32020`..`-32099` sub-range.
+ *
+ * @since 1.0.0
+ */
+export declare const MCP_ERROR_CODES: {
+    readonly headerMismatch: -32020;
+    readonly missingRequiredClientCapability: -32021;
+    readonly unsupportedProtocolVersion: -32022;
+};
 /**
  * Default maximum accepted JSON-RPC request body for a DaloyJS MCP endpoint.
  * The cap is intentionally small because MCP calls should carry parameters,
@@ -21,6 +61,30 @@ export declare const MCP_PROTOCOL_VERSIONS: readonly string[];
  * @since 1.0.0
  */
 export declare const MCP_DEFAULT_MAX_BODY_BYTES: number;
+/**
+ * Maximum accepted length of a client-supplied `params.requestState` string.
+ *
+ * `requestState` is opaque server state that round-trips through an untrusted
+ * client during a multi round-trip request, so it is bounded independently of
+ * the body cap to keep a hostile client from forcing large state parsing.
+ *
+ * @since 1.0.0
+ */
+export declare const MCP_MAX_REQUEST_STATE_LENGTH = 8192;
+/**
+ * Report whether a protocol revision belongs to the stateless ("modern") MCP
+ * era introduced by {@link MCP_MODERN_ERA_MIN_VERSION}.
+ *
+ * Modern requests carry their protocol version, client identity, and client
+ * capabilities in `_meta` and are validated against the standard
+ * `MCP-Protocol-Version` / `Mcp-Method` / `Mcp-Name` HTTP headers. Older
+ * revisions keep the `initialize` handshake instead.
+ *
+ * @param version - A protocol revision string such as `"2026-07-28"`.
+ * @returns `true` when the revision uses per-request metadata.
+ * @since 1.0.0
+ */
+export declare function isModernProtocolVersion(version: string): boolean;
 /**
  * JSON value accepted in MCP schemas, structured results, and metadata.
  *
@@ -94,6 +158,34 @@ export interface McpServerInfo {
     /** Optional icons clients may display for this server (MCP 2025-11-25). */
     icons?: McpIcon[];
 }
+/**
+ * Self-reported implementation identity (`serverInfo` / `clientInfo`).
+ *
+ * Values are supplied by the peer and are **not** verified by the protocol.
+ * Use them for display, logging, and debugging only — never for authorization
+ * or any other security decision.
+ *
+ * @since 1.0.0
+ */
+export interface McpImplementation {
+    /** Stable machine-readable implementation name. */
+    name: string;
+    /** Implementation version string. */
+    version: string;
+    /** Optional human-readable display title. */
+    title?: string;
+}
+/**
+ * Protocol era a request was served under.
+ *
+ * - `"modern"`: MCP `2026-07-28` and later. Stateless; version, identity, and
+ *   capabilities arrive in `_meta` and are mirrored into HTTP headers.
+ * - `"legacy"`: MCP `2025-11-25` and earlier. Established by an `initialize`
+ *   handshake.
+ *
+ * @since 1.0.0
+ */
+export type McpProtocolEra = "modern" | "legacy";
 /**
  * Per-request context passed to tool, resource, and prompt handlers.
  *
@@ -103,16 +195,57 @@ export interface McpRequestContext {
     /** The original HTTP request received by the DaloyJS route. */
     request: Request;
     /**
-     * Protocol version selected for this call. `initialize` negotiates it from
-     * `params.protocolVersion`; other calls take the `MCP-Protocol-Version`
-     * header, falling back to `2025-03-26` (the spec's assumption for
-     * headerless requests) when supported, otherwise the preferred version.
+     * Protocol version selected for this call. On a modern request this is the
+     * verified `io.modelcontextprotocol/protocolVersion` from `_meta`. On a
+     * legacy request, `initialize` negotiates it from `params.protocolVersion`
+     * and other calls take the `MCP-Protocol-Version` header, falling back to
+     * `2025-03-26` (the spec's assumption for headerless requests) when
+     * supported, otherwise the preferred version.
      */
     protocolVersion: string;
+    /**
+     * Protocol era this request was served under. Handlers that emit multi
+     * round-trip results must check this: `input_required` only exists in the
+     * `"modern"` era.
+     */
+    era: McpProtocolEra;
     /** JSON-RPC id for request/response correlation. */
     id: McpJsonRpcId;
     /** Raw MCP method name, such as `"tools/call"` or `"resources/read"`. */
     method: string;
+    /**
+     * Capabilities the client declared for this request
+     * (`io.modelcontextprotocol/clientCapabilities`). Empty on legacy requests,
+     * which declare capabilities once during `initialize` instead.
+     */
+    clientCapabilities: McpJsonObject;
+    /**
+     * Self-reported client identity (`io.modelcontextprotocol/clientInfo`), when
+     * the client sent one. Advisory metadata — never a security input.
+     */
+    clientInfo?: McpImplementation;
+    /**
+     * Minimum log level the client asked the server to emit for this request
+     * (`io.modelcontextprotocol/logLevel`), when supplied.
+     */
+    logLevel?: string;
+    /**
+     * Client answers to a previous {@link McpInputRequiredResult}, keyed by the
+     * identifiers the server assigned in `inputRequests`. Present only on a
+     * multi round-trip retry.
+     */
+    inputResponses?: McpInputResponses;
+    /**
+     * Opaque state the server emitted on a previous
+     * {@link McpInputRequiredResult} and the client echoed back.
+     *
+     * Security: this value round-trips through an untrusted client. If it
+     * influences authorization, resource access, or business logic, integrity-
+     * protect it (HMAC or AEAD), bind it to the authenticated principal and the
+     * originating request, give it a short expiry, and reject anything that
+     * fails verification.
+     */
+    requestState?: string;
 }
 /**
  * Text content block returned from an MCP tool, resource, or prompt.
@@ -179,6 +312,69 @@ export interface McpToolResult {
     /** Set to `true` for domain/tool errors the model may recover from. */
     isError?: boolean;
 }
+/**
+ * Server-to-client request embedded in an {@link McpInputRequiredResult}.
+ *
+ * MCP `2026-07-28` removed server-initiated JSON-RPC requests. A server that
+ * needs elicitation, sampling, or the client's roots returns them here and the
+ * client supplies the answers on a retry of the original request.
+ *
+ * @since 1.0.0
+ */
+export interface McpInputRequest {
+    /** The client-side method being requested. */
+    method: "elicitation/create" | "sampling/createMessage" | "roots/list";
+    /** Method parameters, as defined by the MCP client-features specification. */
+    params?: McpJsonObject;
+}
+/**
+ * Map of server-assigned identifiers to server-to-client requests.
+ *
+ * @since 1.0.0
+ */
+export type McpInputRequests = {
+    [id: string]: McpInputRequest;
+};
+/**
+ * Map of the same identifiers to the client's answers, echoed back on the
+ * retry of the original request.
+ *
+ * @since 1.0.0
+ */
+export type McpInputResponses = {
+    [id: string]: McpJsonValue;
+};
+/**
+ * Interim result telling the client that more input is required before the
+ * call can complete (MCP `2026-07-28` multi round-trip requests).
+ *
+ * Return this from a tool, resource, or prompt handler instead of a final
+ * result. The client gathers the requested input and retries the original
+ * request — with a **new** JSON-RPC id — carrying `inputResponses` and, when
+ * present, the exact `requestState` string it received.
+ *
+ * At least one of `inputRequests` or `requestState` must be set. DaloyJS
+ * refuses to emit an `inputRequests` entry whose method the client did not
+ * declare support for, answering `-32021` instead of leaking a request the
+ * client cannot fulfil.
+ *
+ * @since 1.0.0
+ */
+export interface McpInputRequiredResult {
+    /** Discriminator literal identifying this as a multi round-trip result. */
+    resultType: "input_required";
+    /** Requests the client must fulfil before retrying. */
+    inputRequests?: McpInputRequests;
+    /**
+     * Opaque state the client must echo back verbatim on the retry.
+     *
+     * Security: it passes through an untrusted client. Integrity-protect it
+     * (HMAC or AEAD) whenever it influences authorization, resource access, or
+     * business logic, bind it to the authenticated principal and originating
+     * request, and give it a short expiry.
+     */
+    requestState?: string;
+}
 /**
  * Behavioral hints a tool can advertise to MCP clients. Hints are untrusted
  * metadata for UX decisions (confirmation prompts, badges); clients must not
@@ -208,13 +404,15 @@ export interface McpToolAnnotations {
  *   declared shape holds at runtime. Constraints expressed only through
  *   unsupported schema keywords (e.g. `pattern`) remain the handler's job.
  * @param ctx - Request metadata and the original HTTP request.
- * @returns Text shorthand or a full {@link McpToolResult}.
+ * @returns Text shorthand, a full {@link McpToolResult}, or an
+ *   {@link McpInputRequiredResult} to ask the client for more input first
+ *   (modern protocol era only).
  * @throws {McpToolError} for caller-correctable failures that should be
  *   returned as an MCP tool error result.
  *
  * @since 1.0.0
  */
-export type McpToolHandler<TArgs extends Record<string, unknown> = Record<string, unknown>> = (args: TArgs, ctx: McpRequestContext) => string | McpToolResult | Promise<string | McpToolResult>;
+export type McpToolHandler<TArgs extends Record<string, unknown> = Record<string, unknown>> = (args: TArgs, ctx: McpRequestContext) => string | McpToolResult | McpInputRequiredResult | Promise<string | McpToolResult | McpInputRequiredResult>;
 /**
  * Definition of a callable MCP tool.
  *
@@ -301,9 +499,11 @@ export interface McpResourceDefinition extends McpResource {
      * Read the resource contents for `resources/read`.
      *
      * @param ctx - Request metadata and the original HTTP request.
-     * @returns One or more content entries for this resource.
+     * @returns One or more content entries for this resource, or an
+     *   {@link McpInputRequiredResult} to ask the client for more input first
+     *   (modern protocol era only).
      */
-    read: (ctx: McpRequestContext) => McpResourceContents | McpResourceContents[] | Promise<McpResourceContents | McpResourceContents[]>;
+    read: (ctx: McpRequestContext) => McpResourceContents | McpResourceContents[] | McpInputRequiredResult | Promise<McpResourceContents | McpResourceContents[] | McpInputRequiredResult>;
 }
 /**
  * Resource template metadata returned from `resources/templates/list`.
@@ -344,11 +544,13 @@ export interface McpResourceTemplateDefinition extends McpResourceTemplate {
      * @param uri - The full resource URI requested by the client.
      * @param variables - Template variable values extracted from `uri`.
      * @param ctx - Request metadata and the original HTTP request.
-     * @returns One or more content entries for this resource.
+     * @returns One or more content entries for this resource, or an
+     *   {@link McpInputRequiredResult} to ask the client for more input first
+     *   (modern protocol era only).
      * @throws {McpToolError} for caller-correctable failures such as an unknown
      *   record id; these become JSON-RPC invalid-params errors.
      */
-    read: (uri: string, variables: Record<string, string>, ctx: McpRequestContext) => McpResourceContents | McpResourceContents[] | Promise<McpResourceContents | McpResourceContents[]>;
+    read: (uri: string, variables: Record<string, string>, ctx: McpRequestContext) => McpResourceContents | McpResourceContents[] | McpInputRequiredResult | Promise<McpResourceContents | McpResourceContents[] | McpInputRequiredResult>;
 }
 /**
  * Argument metadata for an MCP prompt.
@@ -417,9 +619,10 @@ export interface McpPromptDefinition extends McpPrompt {
      *
      * @param args - Prompt arguments supplied by the MCP client.
      * @param ctx - Request metadata and the original HTTP request.
-     * @returns Prompt messages.
+     * @returns Prompt messages, or an {@link McpInputRequiredResult} to ask the
+     *   client for more input first (modern protocol era only).
      */
-    get: (args: Record<string, unknown>, ctx: McpRequestContext) => McpPromptResult | Promise<McpPromptResult>;
+    get: (args: Record<string, unknown>, ctx: McpRequestContext) => McpPromptResult | McpInputRequiredResult | Promise<McpPromptResult | McpInputRequiredResult>;
 }
 /**
  * Caller-correctable MCP tool/resource/prompt error.
@@ -440,6 +643,31 @@ export declare class McpToolError extends Error {
      */
     constructor(message: string);
 }
+/**
+ * Client-side caching hints attached to every cacheable modern result
+ * (`server/discover`, the four list methods, and `resources/read`).
+ *
+ * @since 1.0.0
+ */
+export interface McpCacheHints {
+    /**
+     * Freshness hint in milliseconds. `0` (the default) tells clients to
+     * revalidate on every call.
+     *
+     * @defaultValue 0
+     */
+    ttlMs?: number;
+    /**
+     * Whether shared intermediaries may cache the response. DaloyJS defaults to
+     * `"private"` because MCP list results legitimately vary by the credential
+     * presented on the request — a `"public"` scope on an authorization-scoped
+     * tool list would let a proxy serve one caller's tools to another. Only set
+     * `"public"` for a server whose results are identical for every caller.
+     *
+     * @defaultValue "private"
+     */
+    scope?: "public" | "private";
+}
 /**
  * Options for {@link createMcpHandler}.
  *
@@ -473,6 +701,21 @@ export interface McpHandlerOptions {
      * other origin is rejected with `403` unless listed here.
      */
     allowedOrigins?: readonly string[];
+    /**
+     * Optional extensions advertised in `capabilities.extensions`, keyed by
+     * extension identifier (for example `"io.modelcontextprotocol/tasks"`), with
+     * each value the extension's settings object. Identifiers must carry a
+     * reverse-DNS prefix, per the `_meta` key naming rules.
+     *
+     * DaloyJS core implements no extension itself; declaring one here advertises
+     * that *your* handlers implement it.
+     */
+    extensions?: Record<string, McpJsonObject>;
+    /**
+     * Caching hints returned on cacheable modern results. Defaults to
+     * `{ ttlMs: 0, scope: "private" }` — no caching, no sharing.
+     */
+    cache?: McpCacheHints;
     /** Accepted MCP protocol versions. Defaults to {@link MCP_PROTOCOL_VERSIONS}. */
     protocolVersions?: readonly string[];
     /**
@@ -532,31 +775,51 @@ export declare function validateMcpInput(schema: McpJsonSchema, value: unknown):
 /**
  * Create a dependency-free MCP Streamable HTTP endpoint handler.
  *
- * The handler implements the server side of MCP over one HTTP endpoint:
- * `initialize`, `ping`, `tools/list`, `tools/call`, `resources/list`,
- * `resources/templates/list`, `resources/read`, `prompts/list`, and
- * `prompts/get`. It accepts JSON-RPC requests over `POST`, acknowledges
- * notifications with `202`, validates the `MCP-Protocol-Version` header,
- * bounds request bodies, enforces required prompt arguments, and returns
- * JSON-RPC errors for malformed input.
- *
- * Security: per the Streamable HTTP spec's DNS-rebinding guidance, every
- * request bearing an `Origin` header is validated. Same-origin and loopback
- * origins pass; anything else is rejected with `403` unless listed in
- * {@link McpHandlerOptions.allowedOrigins}.
- *
- * It intentionally does not spawn stdio servers, manage OAuth metadata, keep
- * durable sessions, or open server-initiated SSE streams. Use DaloyJS
- * middleware for authentication and authorization, and run this on a dedicated
- * Daloy app when your MCP server has a different trust boundary than your REST
- * API.
+ * The handler serves **both MCP protocol eras** on one endpoint:
+ *
+ * - **Modern (`2026-07-28`+, stateless).** No handshake. Every request carries
+ *   its protocol version, client identity, and client capabilities in `_meta`,
+ *   mirrored into the required `MCP-Protocol-Version`, `Mcp-Method`, and
+ *   `Mcp-Name` headers. Methods: `server/discover`, `tools/list`,
+ *   `tools/call`, `resources/list`, `resources/templates/list`,
+ *   `resources/read`, `prompts/list`, `prompts/get`. Every result carries
+ *   `resultType`, the server identity in `_meta`, and — on cacheable methods —
+ *   `ttlMs` / `cacheScope`. Handlers may return an
+ *   {@link McpInputRequiredResult} to run a multi round-trip request.
+ * - **Legacy (`2025-11-25` and earlier).** The `initialize` / `ping` handshake
+ *   protocol, unchanged, so existing clients keep working.
+ *
+ * A request is served as modern when its `_meta` protocol version (or the
+ * `MCP-Protocol-Version` header) is `2026-07-28` or later; otherwise it takes
+ * the legacy path.
+ *
+ * Security, on top of the era-independent body cap, prototype-pollution-safe
+ * parsing, and `inputSchema` enforcement:
+ *
+ * - Per the Streamable HTTP spec's DNS-rebinding guidance, every request
+ *   bearing an `Origin` header is validated. Loopback origins pass; anything
+ *   else is rejected with `403` unless listed in
+ *   {@link McpHandlerOptions.allowedOrigins}.
+ * - Modern requests are rejected with `400` and `-32020` (`HeaderMismatch`)
+ *   when a required standard header is missing or disagrees with the body.
+ *   This closes the header/body confusion gap that lets a gateway route on one
+ *   value while the server executes another.
+ * - `Mcp-Session-Id` and `Last-Event-ID` are ignored; no session is ever minted
+ *   or echoed.
+ *
+ * It intentionally does not spawn stdio servers, manage OAuth metadata, open
+ * `subscriptions/listen` notification streams, or implement the tasks
+ * extension. Use DaloyJS middleware for authentication and authorization, and
+ * run this on a dedicated Daloy app when your MCP server has a different trust
+ * boundary than your REST API.
  *
  * @param options - Server identity, capabilities, limits, and response headers.
  * @returns A Fetch-compatible request handler suitable for {@link mcpRoutes}
  *   or for direct use in any web-standard runtime.
  * @throws {TypeError} at construction for invalid serverInfo, protocol
- *   versions, body limits, duplicate names/URIs, malformed `allowedOrigins`
- *   entries, or unsupported URI template expressions.
+ *   versions, body limits, cache hints, extension identifiers, duplicate
+ *   names/URIs, malformed `allowedOrigins` entries, invalid `x-mcp-header`
+ *   annotations, or unsupported URI template expressions.
  *
  * @example
  * ```ts