agents 0.14.4 → 0.15.0

package/dist/mcp/index.js

@@ -4,8 +4,9 @@ import { Agent, getAgentByName, getCurrentAgent } from "../index.js";
 import { AsyncLocalStorage } from "node:async_hooks";
 import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
-import { ElicitRequestSchema, InitializeRequestSchema, JSONRPCMessageSchema, SUPPORTED_PROTOCOL_VERSIONS, isInitializeRequest, isJSONRPCErrorResponse, isJSONRPCNotification, isJSONRPCRequest, isJSONRPCResultResponse } from "@modelcontextprotocol/sdk/types.js";
+import { ElicitRequestSchema, InitializeRequestSchema, JSONRPCMessageSchema, isInitializeRequest, isJSONRPCErrorResponse, isJSONRPCNotification, isJSONRPCRequest, isJSONRPCResultResponse } from "@modelcontextprotocol/sdk/types.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 //#region src/mcp/sse-keepalive.ts
 /**
 * Shared SSE keepalive utility for MCP transports.
@@ -1005,512 +1006,291 @@ var StreamableHTTPEdgeClientTransport = class extends StreamableHTTPClientTransp
 };
 //#endregion
 //#region src/mcp/worker-transport.ts
-const MCP_PROTOCOL_VERSION_HEADER = "MCP-Protocol-Version";
-const RESTORE_REQUEST_ID = "__restore__";
-var WorkerTransport = class {
-	constructor(options) {
-		this.started = false;
-		this.initialized = false;
-		this.enableJsonResponse = false;
-		this.standaloneSseStreamId = "_GET_stream";
-		this.streamMapping = /* @__PURE__ */ new Map();
-		this.requestToStreamMapping = /* @__PURE__ */ new Map();
-		this.requestResponseMap = /* @__PURE__ */ new Map();
-		this.stateRestored = false;
-		this.sessionIdGenerator = options?.sessionIdGenerator;
-		this.enableJsonResponse = options?.enableJsonResponse ?? false;
-		this.onsessioninitialized = options?.onsessioninitialized;
-		this.onsessionclosed = options?.onsessionclosed;
-		this.corsOptions = options?.corsOptions;
-		this.storage = options?.storage;
-		this.eventStore = options?.eventStore;
-		this.retryInterval = options?.retryInterval;
+/**
+* WorkerTransport
+*
+* Thin Cloudflare-Workers wrapper around the official MCP SDK
+* `WebStandardStreamableHTTPServerTransport`. The wrapper layers a couple of
+* Workers-specific concerns on top of the SDK transport without forking it:
+*
+*  1. **CORS** — preflight handling and response-header injection,
+*     configurable via `corsOptions`.
+*  2. **Persistent transport state** — when a `storage` adapter
+*     (`MCPStorageApi`) is supplied, the wrapper persists
+*     `{sessionId, initialized, initializeParams}` so that an MCP session can
+*     survive DO hibernation / eviction. On the first request after a cold
+*     start, the saved initialize params are replayed through the `Server`
+*     so client capabilities are re-established.
+*  3. **SSE keepalive** — SSE responses are wrapped in a TransformStream that
+*     injects a `: keepalive\n\n` comment frame every 25s so the Cloudflare
+*     edge ~5min idle-stream watchdog doesn't kill long-running tool calls.
+*     Disabled on the standalone GET stream when an `eventStore` is
+*     configured — clients recover idle drops via `Last-Event-ID` instead.
+*     POST response streams always keepalive (no resumption path during a
+*     mid-flight tool call). See cloudflare/agents#1583.
+*
+* Everything else (session validation, SSE streaming, protocol-version
+* negotiation, event-store resumability, etc.) is delegated to the SDK
+* transport.
+*/
+/** Sentinel id used when replaying the persisted initialize request. */
+const RESTORE_REQUEST_ID = "__worker_transport_restore__";
+const DEFAULT_CORS_OPTIONS = {
+	origin: "*",
+	headers: "Content-Type, Accept, Authorization, mcp-session-id, MCP-Protocol-Version",
+	methods: "GET, POST, DELETE, OPTIONS",
+	exposeHeaders: "mcp-session-id",
+	maxAge: 86400
+};
+var WorkerTransport = class extends WebStandardStreamableHTTPServerTransport {
+	constructor(options = {}) {
+		const { corsOptions, storage, onsessioninitialized, ...sdkOptions } = options;
+		super({
+			...sdkOptions,
+			onsessioninitialized: void 0
+		});
+		this._stateRestored = false;
+		this._bridgeInstalled = false;
+		this._keepaliveCleanups = /* @__PURE__ */ new Map();
+		this._closedRequestIds = /* @__PURE__ */ new Set();
+		this._corsOptions = corsOptions;
+		this._storage = storage;
+		this._userOnSessionInitialized = onsessioninitialized;
 	}
 	/**
-	* Restore transport state from persistent storage.
-	* This is automatically called on start.
+	* Backwards-compatible alias for the SDK's internal `_started` flag.
+	* Several callers and tests check `transport.started` directly.
 	*/
-	async restoreState() {
-		if (!this.storage || this.stateRestored) return;
-		const state = await Promise.resolve(this.storage.get());
-		if (state) {
-			this.sessionId = state.sessionId;
-			this.initialized = state.initialized;
-			if (state.initializeParams && this.onmessage) this.onmessage({
-				jsonrpc: "2.0",
-				id: RESTORE_REQUEST_ID,
-				method: "initialize",
-				params: state.initializeParams
-			});
-		}
-		this.stateRestored = true;
+	get started() {
+		return this._started;
 	}
 	/**
-	* Persist current transport state to storage.
+	* Top-level request entry point. Handles CORS preflight, restores any
+	* persisted state on first invocation, then delegates to the SDK transport
+	* and finally appends CORS headers + keepalive to whatever response comes
+	* back.
 	*/
-	async saveState() {
-		if (!this.storage) return;
-		const state = {
-			sessionId: this.sessionId,
-			initialized: this.initialized,
-			initializeParams: this.initializeParams
-		};
-		await Promise.resolve(this.storage.set(state));
+	async handleRequest(request, options) {
+		if (request.method === "OPTIONS") return new Response(null, { headers: this.getCorsHeaders({ forPreflight: true }) });
+		await this.restoreState();
+		this.installOnSessionInitializedBridge();
+		await this.captureInitializeParams(request, options);
+		const requestIdForKeepalive = request.method === "GET" ? "_standalone" : this._pendingRequestId;
+		const response = await super.handleRequest(request, options);
+		return this.withCorsHeaders(this.withKeepalive(this.normalizeAllowHeader(response), requestIdForKeepalive));
 	}
-	async start() {
-		if (this.started) throw new Error("Transport already started");
-		this.started = true;
+	/**
+	* The SDK's 405 responses advertise `Allow: GET, POST, DELETE` because
+	* OPTIONS is handled outside the SDK. Since our wrapper *does* handle
+	* OPTIONS, advertise it in `Allow` so clients can probe accurately.
+	*/
+	normalizeAllowHeader(response) {
+		if (response.status !== 405) return response;
+		const allow = response.headers.get("Allow");
+		if (!allow || allow.includes("OPTIONS")) return response;
+		const headers = new Headers(response.headers);
+		headers.set("Allow", `${allow}, OPTIONS`);
+		return new Response(response.body, {
+			status: response.status,
+			statusText: response.statusText,
+			headers
+		});
+	}
+	closeSSEStream(requestId) {
+		this._keepaliveCleanups.get(requestId)?.();
+		this._keepaliveCleanups.delete(requestId);
+		this._closedRequestIds.add(requestId);
+		super.closeSSEStream(requestId);
+	}
+	closeStandaloneSSEStream() {
+		this._keepaliveCleanups.get("_standalone")?.();
+		this._keepaliveCleanups.delete("_standalone");
+		super.closeStandaloneSSEStream();
+	}
+	async close() {
+		for (const cleanup of Array.from(this._keepaliveCleanups.values())) cleanup();
+		this._keepaliveCleanups.clear();
+		this._closedRequestIds.clear();
+		await super.close();
 	}
 	/**
-	* Validates the MCP-Protocol-Version header on incoming requests.
+	* Swallow two classes of message that would otherwise surface as
+	* unhandled rejections from the SDK transport's `send()`:
 	*
-	* This performs a simple check: if a version header is present, it must be
-	* in the SUPPORTED_PROTOCOL_VERSIONS list. We do not track the negotiated
-	* version or enforce version consistency across requests - the SDK handles
-	* version negotiation during initialization, and we simply reject any
-	* explicitly unsupported versions.
+	*   1. Replayed initialize responses (the `RESTORE_REQUEST_ID` sentinel)
+	*      — we synthesise these in `restoreState()` to rebuild server
+	*      capabilities; there's no real client waiting for the response.
+	*   2. Sends for a request id whose SSE stream has been deliberately
+	*      closed via `closeSSEStream`. The protocol layer's tool-handler
+	*      promise may settle after the close, and the SDK's `send()` throws
+	*      "No connection established" — a race the pre-refactor transport
+	*      silently swallowed.
 	*
-	* - Header present and supported: Accept
-	* - Header present and unsupported: 400 Bad Request
-	* - Header missing: Accept (version validation is optional)
+	* Everything else is delegated. We use `await super.send(...)` rather
+	* than `return super.send(...)` so any rejection is observed inside this
+	* async frame; without the await, the test runner's
+	* unhandled-rejection tracker can fire before the caller's own `await`
+	* observes it.
 	*/
-	validateProtocolVersion(request) {
-		const protocolVersion = request.headers.get(MCP_PROTOCOL_VERSION_HEADER);
-		if (protocolVersion !== null && !SUPPORTED_PROTOCOL_VERSIONS.includes(protocolVersion)) return new Response(JSON.stringify({
-			jsonrpc: "2.0",
-			error: {
-				code: -32e3,
-				message: `Bad Request: Unsupported protocol version: ${protocolVersion} (supported versions: ${SUPPORTED_PROTOCOL_VERSIONS.join(", ")})`
+	async send(message, options) {
+		let requestId = options?.relatedRequestId;
+		if (isJSONRPCResultResponse(message) || isJSONRPCErrorResponse(message)) requestId = message.id;
+		if (requestId === RESTORE_REQUEST_ID) return;
+		if (requestId !== void 0 && this._closedRequestIds.has(requestId)) return;
+		await super.send(message, options);
+	}
+	/**
+	* If the response is an SSE stream, tee the body through a TransformStream
+	* that injects a `: keepalive\n\n` comment frame every 25s. The interval
+	* is cleared when the wrapped stream closes — which happens both when the
+	* SDK ends the underlying stream naturally and when `closeSSEStream` is
+	* called.
+	*
+	* Keepalive policy:
+	*   - POST response streams (`key` is a request id): always keepalive.
+	*     In-progress tool calls have no recovery path — if the stream drops
+	*     mid-execution the result is lost — so we keep it under the
+	*     Cloudflare edge ~5min idle watchdog.
+	*   - Standalone GET stream (`key === "_standalone"`): keepalive only
+	*     when no `eventStore` is configured. When resumability is enabled,
+	*     clients reconnect with `Last-Event-ID` after an idle drop, so we
+	*     skip the keepalive and let the DO hibernate.
+	*
+	* Uses the shared `sse-keepalive` constants so both this wrapper and
+	* `McpAgent.serve()` write identical frames at the same cadence.
+	* See cloudflare/agents#1583.
+	*/
+	withKeepalive(response, key) {
+		if (!(response.headers.get("Content-Type") ?? "").includes("text/event-stream") || !response.body) return response;
+		if (key === "_standalone" && this.eventStoreConfigured()) return response;
+		const encoder = new TextEncoder();
+		let intervalId;
+		let controllerRef;
+		const clear = () => {
+			if (intervalId !== void 0) {
+				clearInterval(intervalId);
+				intervalId = void 0;
+			}
+			if (key !== void 0) this._keepaliveCleanups.delete(key);
+		};
+		const transform = new TransformStream({
+			start: (controller) => {
+				controllerRef = controller;
+				intervalId = setInterval(() => {
+					try {
+						controllerRef?.enqueue(encoder.encode(KEEPALIVE_FRAME));
+					} catch {
+						clear();
+					}
+				}, KEEPALIVE_INTERVAL_MS);
+				if (key !== void 0) this._keepaliveCleanups.set(key, clear);
 			},
-			id: null
-		}), {
-			status: 400,
-			headers: {
-				"Content-Type": "application/json",
-				...this.getHeaders()
+			transform(chunk, controller) {
+				controller.enqueue(chunk);
+			},
+			flush() {
+				clear();
+			},
+			cancel() {
+				clear();
 			}
 		});
+		const piped = response.body.pipeThrough(transform);
+		return new Response(piped, {
+			status: response.status,
+			statusText: response.statusText,
+			headers: response.headers
+		});
+	}
+	/**
+	* Does the SDK transport have an `eventStore`? Reaches into the SDK's
+	* private field because the option isn't surfaced on the public API —
+	* we only need a yes/no for keepalive policy.
+	*/
+	eventStoreConfigured() {
+		return this._eventStore !== void 0;
 	}
-	getHeaders({ forPreflight } = {}) {
-		const options = {
-			origin: "*",
-			headers: "Content-Type, Accept, Authorization, mcp-session-id, MCP-Protocol-Version",
-			methods: "GET, POST, DELETE, OPTIONS",
-			exposeHeaders: "mcp-session-id",
-			maxAge: 86400,
-			...this.corsOptions
+	getCorsHeaders({ forPreflight } = {}) {
+		const merged = {
+			...DEFAULT_CORS_OPTIONS,
+			...this._corsOptions
 		};
 		if (forPreflight) return {
-			"Access-Control-Allow-Origin": options.origin,
-			"Access-Control-Allow-Headers": options.headers,
-			"Access-Control-Allow-Methods": options.methods,
-			"Access-Control-Max-Age": options.maxAge.toString()
+			"Access-Control-Allow-Origin": merged.origin,
+			"Access-Control-Allow-Headers": merged.headers,
+			"Access-Control-Allow-Methods": merged.methods,
+			"Access-Control-Max-Age": String(merged.maxAge)
 		};
 		return {
-			"Access-Control-Allow-Origin": options.origin,
-			"Access-Control-Expose-Headers": options.exposeHeaders
+			"Access-Control-Allow-Origin": merged.origin,
+			"Access-Control-Expose-Headers": merged.exposeHeaders
 		};
 	}
-	async handleRequest(request, parsedBody) {
-		await this.restoreState();
-		switch (request.method) {
-			case "OPTIONS": return this.handleOptionsRequest(request);
-			case "GET": return this.handleGetRequest(request);
-			case "POST": return this.handlePostRequest(request, parsedBody);
-			case "DELETE": return this.handleDeleteRequest(request);
-			default: return this.handleUnsupportedRequest();
-		}
-	}
-	async handleGetRequest(request) {
-		if (!request.headers.get("Accept")?.includes("text/event-stream")) return new Response(JSON.stringify({
-			jsonrpc: "2.0",
-			error: {
-				code: -32e3,
-				message: "Not Acceptable: Client must accept text/event-stream"
-			},
-			id: null
-		}), {
-			status: 406,
-			headers: {
-				"Content-Type": "application/json",
-				...this.getHeaders()
-			}
+	withCorsHeaders(response) {
+		const headers = new Headers(response.headers);
+		for (const [k, v] of Object.entries(this.getCorsHeaders())) headers.set(k, v);
+		return new Response(response.body, {
+			status: response.status,
+			statusText: response.statusText,
+			headers
 		});
-		const sessionError = this.validateSession(request);
-		if (sessionError) return sessionError;
-		const versionError = this.validateProtocolVersion(request);
-		if (versionError) return versionError;
-		let streamId = this.standaloneSseStreamId;
-		const lastEventId = request.headers.get("Last-Event-ID");
-		if (lastEventId && this.eventStore) {
-			const eventStreamId = await this.eventStore.getStreamIdForEventId?.(lastEventId);
-			if (eventStreamId) streamId = eventStreamId;
-		}
-		if (this.streamMapping.get(streamId) !== void 0) return new Response(JSON.stringify({
-			jsonrpc: "2.0",
-			error: {
-				code: -32e3,
-				message: "Conflict: Only one SSE stream is allowed per session"
-			},
-			id: null
-		}), {
-			status: 409,
-			headers: {
-				"Content-Type": "application/json",
-				...this.getHeaders()
-			}
-		});
-		const { readable, writable } = new TransformStream();
-		const writer = writable.getWriter();
-		const encoder = new TextEncoder();
-		const headers = new Headers({
-			"Content-Type": "text/event-stream",
-			"Cache-Control": "no-cache",
-			Connection: "keep-alive",
-			...this.getHeaders()
-		});
-		if (this.sessionId !== void 0) headers.set("mcp-session-id", this.sessionId);
-		const keepAlive = this.eventStore ? void 0 : startKeepalive(writer, encoder);
-		const cleanup = () => {
-			if (keepAlive !== void 0) clearInterval(keepAlive);
-			this.streamMapping.delete(streamId);
-			writer.close().catch(() => {});
+	}
+	installOnSessionInitializedBridge() {
+		if (this._bridgeInstalled) return;
+		const sdk = this;
+		sdk._onsessioninitialized = async (sessionId) => {
+			if (this._userOnSessionInitialized) await Promise.resolve(this._userOnSessionInitialized(sessionId));
+			await this.saveState();
 		};
-		this.streamMapping.set(streamId, {
-			writer,
-			encoder,
-			cleanup
-		});
-		if (this.retryInterval !== void 0) await writer.write(encoder.encode(`retry: ${this.retryInterval}\n\n`));
-		if (lastEventId && this.eventStore) {
-			const replayedStreamId = await this.eventStore.replayEventsAfter(lastEventId, { send: async (eventId, message) => {
-				const data = `id: ${eventId}\nevent: message\ndata: ${JSON.stringify(message)}\n\n`;
-				await writer.write(encoder.encode(data));
-			} });
-			if (replayedStreamId !== streamId) {
-				this.streamMapping.delete(streamId);
-				streamId = replayedStreamId;
-				this.streamMapping.set(streamId, {
-					writer,
-					encoder,
-					cleanup
-				});
-			}
-		}
-		return new Response(readable, { headers });
+		this._bridgeInstalled = true;
 	}
-	async handlePostRequest(request, parsedBody) {
-		const acceptHeader = request.headers.get("Accept");
-		if (!acceptHeader?.includes("application/json") || !acceptHeader?.includes("text/event-stream")) return new Response(JSON.stringify({
-			jsonrpc: "2.0",
-			error: {
-				code: -32e3,
-				message: "Not Acceptable: Client must accept both application/json and text/event-stream"
-			},
-			id: null
-		}), {
-			status: 406,
-			headers: {
-				"Content-Type": "application/json",
-				...this.getHeaders()
-			}
-		});
-		if (!request.headers.get("Content-Type")?.includes("application/json")) return new Response(JSON.stringify({
-			jsonrpc: "2.0",
-			error: {
-				code: -32e3,
-				message: "Unsupported Media Type: Content-Type must be application/json"
-			},
-			id: null
-		}), {
-			status: 415,
-			headers: {
-				"Content-Type": "application/json",
-				...this.getHeaders()
-			}
-		});
-		let rawMessage = parsedBody;
-		if (rawMessage === void 0) try {
-			rawMessage = await request.json();
-		} catch {
-			return new Response(JSON.stringify({
-				jsonrpc: "2.0",
-				error: {
-					code: -32700,
-					message: "Parse error: Invalid JSON"
-				},
-				id: null
-			}), {
-				status: 400,
-				headers: {
-					"Content-Type": "application/json",
-					...this.getHeaders()
-				}
-			});
-		}
-		let messages;
+	async captureInitializeParams(request, handleOptions) {
+		this._pendingRequestId = void 0;
+		if (request.method !== "POST") return;
 		try {
-			if (Array.isArray(rawMessage)) messages = rawMessage.map((msg) => JSONRPCMessageSchema.parse(msg));
-			else messages = [JSONRPCMessageSchema.parse(rawMessage)];
-		} catch {
-			return new Response(JSON.stringify({
-				jsonrpc: "2.0",
-				error: {
-					code: -32700,
-					message: "Parse error: Invalid JSON-RPC message"
-				},
-				id: null
-			}), {
-				status: 400,
-				headers: {
-					"Content-Type": "application/json",
-					...this.getHeaders()
-				}
-			});
-		}
-		const requestInfo = {
-			headers: Object.fromEntries(request.headers.entries()),
-			url: new URL(request.url)
-		};
-		const isInitializationRequest = messages.some(isInitializeRequest);
-		if (isInitializationRequest) {
-			if (this.initialized && this.sessionId !== void 0) return new Response(JSON.stringify({
-				jsonrpc: "2.0",
-				error: {
-					code: -32600,
-					message: "Invalid Request: Server already initialized"
-				},
-				id: null
-			}), {
-				status: 400,
-				headers: {
-					"Content-Type": "application/json",
-					...this.getHeaders()
-				}
-			});
-			if (messages.length > 1) return new Response(JSON.stringify({
-				jsonrpc: "2.0",
-				error: {
-					code: -32600,
-					message: "Invalid Request: Only one initialization request is allowed"
-				},
-				id: null
-			}), {
-				status: 400,
-				headers: {
-					"Content-Type": "application/json",
-					...this.getHeaders()
-				}
-			});
-			this.sessionId = this.sessionIdGenerator?.();
-			this.initialized = true;
-			const initMessage = messages.find(isInitializeRequest);
-			if (initMessage && isInitializeRequest(initMessage)) this.initializeParams = {
-				capabilities: initMessage.params.capabilities,
-				clientInfo: initMessage.params.clientInfo,
-				protocolVersion: initMessage.params.protocolVersion
+			const parsed = handleOptions?.parsedBody ?? await request.clone().json();
+			const messages = Array.isArray(parsed) ? parsed : [parsed];
+			const init = messages.find((m) => typeof m === "object" && m !== null && isInitializeRequest(m));
+			if (init && isInitializeRequest(init)) this._capturedInitializeParams = {
+				capabilities: init.params.capabilities,
+				clientInfo: init.params.clientInfo,
+				protocolVersion: init.params.protocolVersion
 			};
-			await this.saveState();
-			if (this.sessionId && this.onsessioninitialized) this.onsessioninitialized(this.sessionId);
-		}
-		if (!isInitializationRequest) {
-			const sessionError = this.validateSession(request);
-			if (sessionError) return sessionError;
-			const versionError = this.validateProtocolVersion(request);
-			if (versionError) return versionError;
-		}
-		if (!messages.some(isJSONRPCRequest)) {
-			for (const message of messages) this.onmessage?.(message, { requestInfo });
-			return new Response(null, {
-				status: 202,
-				headers: { ...this.getHeaders() }
-			});
-		}
-		const streamId = crypto.randomUUID();
-		if (this.enableJsonResponse) return new Promise((resolve) => {
-			this.streamMapping.set(streamId, {
-				resolveJson: resolve,
-				cleanup: () => {
-					this.streamMapping.delete(streamId);
-				}
-			});
-			for (const message of messages) if (isJSONRPCRequest(message)) this.requestToStreamMapping.set(message.id, streamId);
-			for (const message of messages) this.onmessage?.(message, { requestInfo });
-		});
-		const { readable, writable } = new TransformStream();
-		const writer = writable.getWriter();
-		const encoder = new TextEncoder();
-		const headers = new Headers({
-			"Content-Type": "text/event-stream",
-			"Cache-Control": "no-cache",
-			Connection: "keep-alive",
-			...this.getHeaders()
-		});
-		if (this.sessionId !== void 0) headers.set("mcp-session-id", this.sessionId);
-		const keepAlive = startKeepalive(writer, encoder);
-		this.streamMapping.set(streamId, {
-			writer,
-			encoder,
-			cleanup: () => {
-				clearInterval(keepAlive);
-				this.streamMapping.delete(streamId);
-				writer.close().catch(() => {});
-			}
-		});
-		for (const message of messages) if (isJSONRPCRequest(message)) this.requestToStreamMapping.set(message.id, streamId);
-		for (const message of messages) this.onmessage?.(message, { requestInfo });
-		return new Response(readable, { headers });
-	}
-	async handleDeleteRequest(request) {
-		const sessionError = this.validateSession(request);
-		if (sessionError) return sessionError;
-		const versionError = this.validateProtocolVersion(request);
-		if (versionError) return versionError;
-		const closedSessionId = this.sessionId;
-		await this.close();
-		if (closedSessionId && this.onsessionclosed) this.onsessionclosed(closedSessionId);
-		return new Response(null, {
-			status: 200,
-			headers: { ...this.getHeaders() }
-		});
-	}
-	handleOptionsRequest(_request) {
-		return new Response(null, {
-			status: 200,
-			headers: { ...this.getHeaders({ forPreflight: true }) }
-		});
+			const firstRequest = messages.find((m) => typeof m === "object" && m !== null && "id" in m && "method" in m);
+			if (firstRequest) this._pendingRequestId = firstRequest.id;
+		} catch {}
 	}
-	handleUnsupportedRequest() {
-		return new Response(JSON.stringify({
-			jsonrpc: "2.0",
-			error: {
-				code: -32e3,
-				message: "Method not allowed."
-			},
-			id: null
-		}), {
-			status: 405,
-			headers: {
-				Allow: "GET, POST, DELETE, OPTIONS",
-				"Content-Type": "application/json"
-			}
-		});
-	}
-	validateSession(request) {
-		if (this.sessionIdGenerator === void 0) return;
-		if (!this.initialized) return new Response(JSON.stringify({
-			jsonrpc: "2.0",
-			error: {
-				code: -32e3,
-				message: "Bad Request: Server not initialized"
-			},
-			id: null
-		}), {
-			status: 400,
-			headers: {
-				"Content-Type": "application/json",
-				...this.getHeaders()
-			}
-		});
-		const sessionId = request.headers.get("mcp-session-id");
-		if (!sessionId) return new Response(JSON.stringify({
-			jsonrpc: "2.0",
-			error: {
-				code: -32e3,
-				message: "Bad Request: Mcp-Session-Id header is required"
-			},
-			id: null
-		}), {
-			status: 400,
-			headers: {
-				"Content-Type": "application/json",
-				...this.getHeaders()
-			}
-		});
-		if (sessionId !== this.sessionId) return new Response(JSON.stringify({
+	async restoreState() {
+		if (!this._storage || this._stateRestored) return;
+		this._stateRestored = true;
+		let state;
+		try {
+			state = await Promise.resolve(this._storage.get());
+		} catch (error) {
+			this._stateRestored = false;
+			throw error;
+		}
+		if (!state) return;
+		const sdk = this;
+		sdk.sessionId = state.sessionId;
+		sdk._initialized = state.initialized;
+		this._capturedInitializeParams = state.initializeParams;
+		if (state.initializeParams && this.onmessage) this.onmessage({
 			jsonrpc: "2.0",
-			error: {
-				code: -32001,
-				message: "Session not found"
-			},
-			id: null
-		}), {
-			status: 404,
-			headers: {
-				"Content-Type": "application/json",
-				...this.getHeaders()
-			}
+			id: RESTORE_REQUEST_ID,
+			method: "initialize",
+			params: state.initializeParams
 		});
 	}
-	async close() {
-		for (const { cleanup } of this.streamMapping.values()) cleanup();
-		this.streamMapping.clear();
-		this.requestResponseMap.clear();
-		this.onclose?.();
-	}
-	/**
-	* Close an SSE stream for a specific request, triggering client reconnection.
-	* Use this to implement polling behavior during long-running operations -
-	* client will reconnect after the retry interval specified in the priming event.
-	*/
-	closeSSEStream(requestId) {
-		const streamId = this.requestToStreamMapping.get(requestId);
-		if (!streamId) return;
-		const stream = this.streamMapping.get(streamId);
-		if (stream) stream.cleanup();
-		for (const [reqId, sid] of this.requestToStreamMapping.entries()) if (sid === streamId) {
-			this.requestToStreamMapping.delete(reqId);
-			this.requestResponseMap.delete(reqId);
-		}
-	}
-	async send(message, options) {
-		let requestId = options?.relatedRequestId;
-		if (isJSONRPCResultResponse(message) || isJSONRPCErrorResponse(message)) requestId = message.id;
-		if (requestId === RESTORE_REQUEST_ID) return;
-		if (requestId === void 0) {
-			if (isJSONRPCResultResponse(message) || isJSONRPCErrorResponse(message)) throw new Error("Cannot send a response on a standalone SSE stream unless resuming a previous client request");
-			const standaloneSse = this.streamMapping.get(this.standaloneSseStreamId);
-			if (standaloneSse === void 0) return;
-			if (standaloneSse.writer && standaloneSse.encoder) {
-				let eventId;
-				if (this.eventStore) eventId = await this.eventStore.storeEvent(this.standaloneSseStreamId, message);
-				const data = `${eventId ? `id: ${eventId}\n` : ""}event: message\ndata: ${JSON.stringify(message)}\n\n`;
-				await standaloneSse.writer.write(standaloneSse.encoder.encode(data));
-			}
-			return;
-		}
-		const streamId = this.requestToStreamMapping.get(requestId);
-		if (!streamId) throw new Error(`No connection established for request ID: ${String(requestId)}`);
-		const response = this.streamMapping.get(streamId);
-		if (!response) throw new Error(`No connection established for request ID: ${String(requestId)}`);
-		if (!this.enableJsonResponse) {
-			if (response.writer && response.encoder) {
-				let eventId;
-				if (this.eventStore) eventId = await this.eventStore.storeEvent(streamId, message);
-				const data = `${eventId ? `id: ${eventId}\n` : ""}event: message\ndata: ${JSON.stringify(message)}\n\n`;
-				await response.writer.write(response.encoder.encode(data));
-			}
-		}
-		if (isJSONRPCResultResponse(message) || isJSONRPCErrorResponse(message)) {
-			this.requestResponseMap.set(requestId, message);
-			const relatedIds = Array.from(this.requestToStreamMapping.entries()).filter(([, sid]) => sid === streamId).map(([id]) => id);
-			if (relatedIds.every((id) => this.requestResponseMap.has(id))) {
-				if (this.enableJsonResponse && response.resolveJson) {
-					const responses = relatedIds.map((id) => this.requestResponseMap.get(id));
-					const headers = new Headers({
-						"Content-Type": "application/json",
-						...this.getHeaders()
-					});
-					if (this.sessionId !== void 0) headers.set("mcp-session-id", this.sessionId);
-					const body = responses.length === 1 ? responses[0] : responses;
-					response.resolveJson(new Response(JSON.stringify(body), { headers }));
-				} else response.cleanup();
-				for (const id of relatedIds) {
-					this.requestResponseMap.delete(id);
-					this.requestToStreamMapping.delete(id);
-				}
-			}
-		}
+	async saveState() {
+		if (!this._storage) return;
+		const sdk = this;
+		const state = {
+			sessionId: sdk.sessionId,
+			initialized: sdk._initialized,
+			initializeParams: this._capturedInitializeParams
+		};
+		await Promise.resolve(this._storage.set(state));
 	}
 };
 //#endregion
@@ -1526,30 +1306,25 @@ function runWithAuthContext(context, fn) {
 //#region src/mcp/handler.ts
 function createMcpHandler(server, options = {}) {
 	const route = options.route ?? "/mcp";
+	const { route: _route, authContext, transport: providedTransport, ...transportOptions } = options;
 	return async (request, _env, ctx) => {
 		const url = new URL(request.url);
 		if (route && url.pathname !== route) return new Response("Not Found", { status: 404 });
-		const transport = options.transport ?? new WorkerTransport({
-			sessionIdGenerator: options.sessionIdGenerator,
-			enableJsonResponse: options.enableJsonResponse,
-			onsessioninitialized: options.onsessioninitialized,
-			corsOptions: options.corsOptions,
-			storage: options.storage
-		});
+		const transport = providedTransport ?? new WorkerTransport(transportOptions);
 		const buildAuthContext = () => {
-			if (options.authContext) return options.authContext;
+			if (authContext) return authContext;
 			if (ctx.props && Object.keys(ctx.props).length > 0) return { props: ctx.props };
 		};
 		const handleRequest = async () => {
 			return await transport.handleRequest(request);
 		};
-		const authContext = buildAuthContext();
+		const resolvedAuthContext = buildAuthContext();
 		if (!transport.started) {
 			if (server instanceof McpServer ? server.isConnected() : server.transport !== void 0) throw new Error("Server is already connected to a transport. Create a new McpServer instance per request for stateless handlers.");
 			await server.connect(transport);
 		}
 		try {
-			if (authContext) return await runWithAuthContext(authContext, handleRequest);
+			if (resolvedAuthContext) return await runWithAuthContext(resolvedAuthContext, handleRequest);
 			else return await handleRequest();
 		} catch (error) {
 			console.error("MCP handler error:", error);