diff --git a/.changeset/standalone-get-priming-event.md b/.changeset/standalone-get-priming-event.md new file mode 100644 index 0000000000..2c8074fcfb --- /dev/null +++ b/.changeset/standalone-get-priming-event.md @@ -0,0 +1,5 @@ +--- +'@modelcontextprotocol/server': patch +--- + +The standalone `GET` SSE stream now starts with a priming event (an event ID, plus `retry` when `retryInterval` is set), as POST streams already do. It is sent when an `eventStore` is configured and the request's `MCP-Protocol-Version` is `2025-11-25` or later. Before, a client whose GET stream was closed by `closeStandaloneSSEStream()` before it had received an event reconnected without `Last-Event-ID` and lost the notifications sent in between. Opening the GET stream now waits for `eventStore.storeEvent()`; if it throws, the stream opens without a priming event. Each GET stream stores one priming event (`{}`) under the standalone stream ID; replays skip these. diff --git a/packages/middleware/node/test/streamableHttp.test.ts b/packages/middleware/node/test/streamableHttp.test.ts index 901b78446f..f0bb1424a7 100644 --- a/packages/middleware/node/test/streamableHttp.test.ts +++ b/packages/middleware/node/test/streamableHttp.test.ts @@ -1444,6 +1444,8 @@ describe('Zod v4', () => { expect(sseResponse.status).toBe(200); expect(sseResponse.headers.get('content-type')).toBe('text/event-stream'); + const reader = sseResponse.body?.getReader(); + expect(new TextDecoder().decode((await reader!.read()).value)).toMatch(/^id: _GET_stream\S*\n(retry: \d+\n)?data: \n\n$/); // Send a notification that should be stored with an event ID const notification: JSONRPCMessage = { @@ -1456,7 +1458,6 @@ describe('Zod v4', () => { await transport.send(notification); // Read from the stream and verify we got the notification with an event ID - const reader = sseResponse.body?.getReader(); const { value } = await reader!.read(); const text = new TextDecoder().decode(value); @@ -1487,12 +1488,13 @@ describe('Zod v4', () => { } }); expect(sseResponse.status).toBe(200); + const reader = sseResponse.body?.getReader(); + expect(new TextDecoder().decode((await reader!.read()).value)).toMatch(/^id: _GET_stream\S*\n(retry: \d+\n)?data: \n\n$/); // Send a server notification through the MCP server await mcpServer.server.sendLoggingMessage({ level: 'info', data: 'First notification from MCP server' }); // Read the notification from the SSE stream - const reader = sseResponse.body?.getReader(); const { value } = await reader!.read(); const text = new TextDecoder().decode(value); @@ -2249,6 +2251,7 @@ describe('Zod v4', () => { expect(sseResponse.status).toBe(200); const getReader = sseResponse.body?.getReader(); + expect(new TextDecoder().decode((await getReader!.read()).value)).toMatch(/^id: _GET_stream\S*\n(retry: \d+\n)?data: \n\n$/); // Send a notification to confirm GET stream is established await mcpServer.server.sendLoggingMessage({ level: 'info', data: 'Stream established' }); @@ -2330,6 +2333,7 @@ describe('Zod v4', () => { expect(sseResponse.status).toBe(200); const getReader = sseResponse.body?.getReader(); + expect(new TextDecoder().decode((await getReader!.read()).value)).toMatch(/^id: _GET_stream\S*\n(retry: \d+\n)?data: \n\n$/); // Send a notification to get an event ID await mcpServer.server.sendLoggingMessage({ level: 'info', data: 'Initial message' }); diff --git a/packages/server/src/server/streamableHttp.ts b/packages/server/src/server/streamableHttp.ts index 2484ae19b0..cc8a0bcc6a 100644 --- a/packages/server/src/server/streamableHttp.ts +++ b/packages/server/src/server/streamableHttp.ts @@ -75,6 +75,8 @@ interface StreamMapping { * during the `storeEvent()` await and replay already delivered the event. */ replayedEventIds?: Set; + /** Settles once the stream's priming event, if any, has been written */ + primed?: Promise; /** Cleanup function to close stream and remove mapping */ cleanup: () => void; } @@ -469,35 +471,29 @@ export class WebStandardStreamableHTTPServerTransport implements Transport { } /** - * Writes a priming event to establish resumption capability. - * Only sends if `eventStore` is configured (opt-in for resumability) and + * Stores a priming event and returns its SSE frame, to establish resumption capability. + * Only does so if `eventStore` is configured (opt-in for resumability) and * the client's protocol version supports empty SSE data (a supported - * version that is >= `2025-11-25`). + * version that is >= `2025-11-25`). Returns `undefined` otherwise. */ - private async writePrimingEvent( - controller: ReadableStreamDefaultController, - encoder: InstanceType, - streamId: string, - protocolVersion: string - ): Promise { + private async createPrimingEvent(streamId: string, protocolVersion: string): Promise { if (!this._eventStore) { - return; + return undefined; } // Priming events have empty data which older clients cannot handle. // Only send priming events to clients whose protocol version includes // the fix for handling empty SSE data. if (!this.supportsEmptySSEData(protocolVersion)) { - return; + return undefined; } const primingEventId = await this._eventStore.storeEvent(streamId, {} as JSONRPCMessage); - let primingEvent = `id: ${primingEventId}\ndata: \n\n`; if (this._retryInterval !== undefined) { - primingEvent = `id: ${primingEventId}\nretry: ${this._retryInterval}\ndata: \n\n`; + return `id: ${primingEventId}\nretry: ${this._retryInterval}\ndata: \n\n`; } - controller.enqueue(encoder.encode(primingEvent)); + return `id: ${primingEventId}\ndata: \n\n`; } /** @@ -572,12 +568,27 @@ export class WebStandardStreamableHTTPServerTransport implements Transport { headers['mcp-session-id'] = this.sessionId; } + // Without a stored priming event the stream still opens, as it did before priming + const priming = this.createPrimingEvent( + this._standaloneSseStreamId, + req.headers.get('mcp-protocol-version') ?? DEFAULT_NEGOTIATED_PROTOCOL_VERSION + ).catch((error: unknown) => { + this.onerror?.(error as Error); + return; + }); + + let markPrimed!: () => void; // Store the stream mapping with the controller for pushing data - this._streamMapping.set(this._standaloneSseStreamId, { + const mapping: StreamMapping = { controller: streamController!, encoder, + // send() waits on this so nothing is written ahead of the priming event + primed: new Promise(resolve => { + markPrimed = resolve; + }), cleanup: () => { if (keepAliveTimer !== undefined) clearInterval(keepAliveTimer); + markPrimed(); this._streamMapping.delete(this._standaloneSseStreamId); try { streamController!.close(); @@ -585,7 +596,25 @@ export class WebStandardStreamableHTTPServerTransport implements Transport { // Controller might already be closed } } - }); + }; + this._streamMapping.set(this._standaloneSseStreamId, mapping); + + const primingEvent = await priming; + if (req.signal.aborted && this._streamMapping.get(this._standaloneSseStreamId) === mapping) { + mapping.cleanup(); + } + if (this._closed) { + return this.createJsonErrorResponse(404, -32_001, 'Session not found'); + } + // Closed while the priming event was being stored: hand back the ended stream so the client reconnects + if (this._streamMapping.get(this._standaloneSseStreamId) !== mapping) { + return new Response(readable, { headers }); + } + if (primingEvent !== undefined) { + streamController!.enqueue(encoder.encode(primingEvent)); + } + mapping.primed = undefined; + markPrimed(); keepAliveTimer = this.startKeepAlive(streamController!, encoder); return new Response(readable, { headers }); @@ -663,6 +692,10 @@ export class WebStandardStreamableHTTPServerTransport implements Transport { const replayedEventIds = new Set(); replayedStreamId = await this._eventStore.replayEventsAfter(lastEventId, { send: async (eventId: string, message: JSONRPCMessage) => { + // Skip priming events, stored as `{}`; a reopened GET stream can have them after lastEventId + if (!message || Object.keys(message).length === 0) { + return; + } replayedEventIds.add(eventId); const success = this.writeSSEEvent(streamController!, encoder, message, eventId); if (!success) { @@ -1005,7 +1038,10 @@ export class WebStandardStreamableHTTPServerTransport implements Transport { } // Write priming event if event store is configured (after mapping is set up) - await this.writePrimingEvent(streamController!, encoder, streamId, clientProtocolVersion); + const primingEvent = await this.createPrimingEvent(streamId, clientProtocolVersion); + if (primingEvent !== undefined) { + streamController!.enqueue(encoder.encode(primingEvent)); + } // handle each message for (const message of messages) { @@ -1185,7 +1221,11 @@ export class WebStandardStreamableHTTPServerTransport implements Transport { eventId = await this._eventStore.storeEvent(this._standaloneSseStreamId, message); } - const standaloneSse = this._streamMapping.get(this._standaloneSseStreamId); + let standaloneSse = this._streamMapping.get(this._standaloneSseStreamId); + while (standaloneSse?.primed) { + await standaloneSse.primed; + standaloneSse = this._streamMapping.get(this._standaloneSseStreamId); + } if (standaloneSse === undefined) { // Stream is disconnected - event is stored for replay, nothing more to do return; diff --git a/packages/server/test/server/streamableHttp.test.ts b/packages/server/test/server/streamableHttp.test.ts index 937316ebed..4f573368e9 100644 --- a/packages/server/test/server/streamableHttp.test.ts +++ b/packages/server/test/server/streamableHttp.test.ts @@ -1081,6 +1081,211 @@ describe('Zod v4', () => { // eslint-disable-next-line @typescript-eslint/no-explicit-any expect((transport as any)._requestToStreamMapping.has('stalecancel-1')).toBe(false); }); + + describe('standalone GET stream priming', () => { + const notification: JSONRPCMessage = { + jsonrpc: '2.0', + method: 'notifications/message', + params: { level: 'info', data: 'server notice' } + }; + + async function primingIdOf(response: Response): Promise { + const text = await readSSEEvent(response); + const id = /^id: (\S+)\n/.exec(text)?.[1]; + expect(id, `expected a priming event, got ${JSON.stringify(text)}`).toBeDefined(); + return id!; + } + + it('should send a priming event with retry so the client can poll after closeStandaloneSSEStream()', async () => { + await transport.close(); + transport = new WebStandardStreamableHTTPServerTransport({ + sessionIdGenerator: () => randomUUID(), + eventStore, + retryInterval: 1000 + }); + mcpServer = new McpServer({ name: 'test-server', version: '1.0.0' }); + await mcpServer.connect(transport); + sessionId = await initializeServer(); + + const response = await transport.handleRequest(createRequest('GET', undefined, { sessionId })); + expect(response.status).toBe(200); + const text = await readSSEEvent(response); + expect(text).toMatch(/^id: \S+\nretry: 1000\ndata: \n\n$/); + const primingId = /^id: (\S+)/.exec(text)![1]!; + + transport.closeStandaloneSSEStream(); + await transport.send(notification); + + const reconnect = await transport.handleRequest( + createRequest('GET', undefined, { sessionId, extraHeaders: { 'Last-Event-ID': primingId } }) + ); + expect(reconnect.status).toBe(200); + expect(await readSSEEvent(reconnect)).toContain('server notice'); + }); + + it('should not send a priming event to clients older than 2025-11-25', async () => { + sessionId = await initializeServer(); + + const response = await transport.handleRequest( + createRequest('GET', undefined, { sessionId, extraHeaders: { 'mcp-protocol-version': '2025-06-18' } }) + ); + expect(response.status).toBe(200); + await transport.send(notification); + const text = await readSSEEvent(response); + expect(text.startsWith('event: message\n')).toBe(true); + }); + + it('should not replay priming events of later GET streams as messages', async () => { + sessionId = await initializeServer(); + + // Both GET streams store a priming event under the same stream id + const first = await transport.handleRequest(createRequest('GET', undefined, { sessionId })); + const firstPrimingId = await primingIdOf(first); + transport.closeStandaloneSSEStream(); + const second = await transport.handleRequest(createRequest('GET', undefined, { sessionId })); + await primingIdOf(second); + transport.closeStandaloneSSEStream(); + await transport.send(notification); + + const reconnect = await transport.handleRequest( + createRequest('GET', undefined, { sessionId, extraHeaders: { 'Last-Event-ID': firstPrimingId } }) + ); + expect(reconnect.status).toBe(200); + const text = await readSSEEvent(reconnect); + expect(text).not.toContain('data: {}'); + expect(text).toContain('server notice'); + }); + + it('should write a notification sent during the priming store after the priming event', async () => { + sessionId = await initializeServer(); + + let release!: () => void; + const gate = new Promise(resolve => { + release = resolve; + }); + const realStoreEvent = eventStore.storeEvent.bind(eventStore); + let gated = true; + eventStore.storeEvent = async (sid, msg) => { + const id = await realStoreEvent(sid, msg); + if (gated) { + gated = false; + await gate; + } + return id; + }; + + const pending = transport.handleRequest(createRequest('GET', undefined, { sessionId })); + await new Promise(resolve => setTimeout(resolve, 5)); + const sent = transport.send(notification); + await new Promise(resolve => setTimeout(resolve, 5)); + release(); + await sent; + + const response = await pending; + const reader = response.body!.getReader(); + let text = ''; + while (!text.includes('server notice')) { + text += new TextDecoder().decode((await reader.read()).value); + } + expect(text).toMatch(/^id: \S+\ndata: \n\nevent: message\nid: \S+\ndata: .*server notice/); + await reader.cancel(); + }); + + it('should open the stream without a priming event when it cannot be stored', async () => { + sessionId = await initializeServer(); + const errors: Error[] = []; + transport.onerror = error => errors.push(error); + + const realStoreEvent = eventStore.storeEvent.bind(eventStore); + eventStore.storeEvent = async (sid, msg) => { + if (sid === '_GET_stream' && Object.keys(msg).length === 0) throw new Error('store down'); + return realStoreEvent(sid, msg); + }; + const response = await transport.handleRequest(createRequest('GET', undefined, { sessionId })); + expect(response.status).toBe(200); + expect(errors.map(e => e.message)).toContain('store down'); + + await transport.send(notification); + expect((await readSSEEvent(response)).startsWith('event: message\n')).toBe(true); + }); + + describe('while the priming event is being stored', () => { + let release: () => void; + + beforeEach(() => { + const gate = new Promise(resolve => { + release = resolve; + }); + const realStoreEvent = eventStore.storeEvent.bind(eventStore); + eventStore.storeEvent = async (sid, msg) => { + if (sid === '_GET_stream' && Object.keys(msg).length === 0) await gate; + return realStoreEvent(sid, msg); + }; + }); + + it('should unregister the stream when the client disconnects', async () => { + sessionId = await initializeServer(); + const abort = new AbortController(); + const request = createRequest('GET', undefined, { sessionId }); + + const pending = transport.handleRequest(new Request(request, { signal: abort.signal })); + abort.abort(); + release(); + await pending; + + const next = await transport.handleRequest(createRequest('GET', undefined, { sessionId })); + expect(next.status).toBe(200); + }); + + it('should end the stream, not answer 404, when closeStandaloneSSEStream() is called', async () => { + sessionId = await initializeServer(); + + const pending = transport.handleRequest(createRequest('GET', undefined, { sessionId })); + await new Promise(resolve => setTimeout(resolve, 5)); + transport.closeStandaloneSSEStream(); + release(); + + const response = await pending; + expect(response.status).toBe(200); + expect(await response.text()).toBe(''); + }); + + it('should not block send() after close()', async () => { + sessionId = await initializeServer(); + + void transport.handleRequest(createRequest('GET', undefined, { sessionId })); + await new Promise(resolve => setTimeout(resolve, 5)); + const sent = transport.send(notification); + await new Promise(resolve => setTimeout(resolve, 5)); + await transport.close(); + + await expect(sent).resolves.toBeUndefined(); + }); + }); + + it('should reject a second GET that arrives while the first is storing its priming event', async () => { + sessionId = await initializeServer(); + + let release!: () => void; + const gate = new Promise(resolve => { + release = resolve; + }); + const realStoreEvent = eventStore.storeEvent.bind(eventStore); + eventStore.storeEvent = async (sid, msg) => { + await gate; + return realStoreEvent(sid, msg); + }; + + const pending = [ + transport.handleRequest(createRequest('GET', undefined, { sessionId })), + transport.handleRequest(createRequest('GET', undefined, { sessionId })) + ]; + release(); + const responses = await Promise.all(pending); + expect(responses.map(r => r.status).toSorted()).toEqual([200, 409]); + await Promise.all(responses.map(r => r.body?.cancel())); + }); + }); }); describe('HTTPServerTransport - Protocol Version Validation', () => { diff --git a/test/e2e/requirements.ts b/test/e2e/requirements.ts index 5270df49b4..e14851ef44 100644 --- a/test/e2e/requirements.ts +++ b/test/e2e/requirements.ts @@ -1744,6 +1744,13 @@ export const REQUIREMENTS: Record = { transports: ['streamableHttp'], note: 'Resumability requires a per-session transport with an EventStore and a standalone GET stream; stateless hosting has neither.' }, + 'hosting:resume:priming-get': { + source: 'https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#listening-for-messages-from-the-server', + behavior: + 'With eventStore + new protocol, the standalone GET SSE stream begins with a priming event carrying the configured retry: interval, so a client can resume it with Last-Event-ID after the server closes it.', + transports: ['streamableHttp'], + note: 'Resumability requires a per-session transport with an EventStore and a standalone GET stream; stateless hosting has neither.' + }, 'hosting:resume:replay': { source: 'https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#resumability-and-redelivery', behavior: 'GET with Last-Event-ID replays stored events for that stream after the given id.', diff --git a/test/e2e/scenarios/hosting-resume.test.ts b/test/e2e/scenarios/hosting-resume.test.ts index 762c445b7e..fd0ad07954 100644 --- a/test/e2e/scenarios/hosting-resume.test.ts +++ b/test/e2e/scenarios/hosting-resume.test.ts @@ -559,6 +559,77 @@ verifies('hosting:resume:priming', async (_args: TestArgs) => { } }); +verifies('hosting:resume:priming-get', async (_args: TestArgs) => { + const RETRY_MS = 7331; + const eventStore = new InMemoryEventStore(); + + let serverRef: McpServer | undefined; + const makeServer = () => { + const s = new McpServer({ name: 's', version: '0' }, { capabilities: { logging: {} } }); + serverRef = s; + s.registerTool('close-standalone', { inputSchema: z.object({}) }, async (_input, ctx) => { + ctx.http?.closeStandaloneSSE?.(); + return { content: [{ type: 'text', text: 'closed' }] }; + }); + return s; + }; + + const handle = hostResumable(makeServer, { eventStore, retryInterval: RETRY_MS }); + + const url = new URL('http://in-process/mcp'); + const fetch = (u: URL | string, init?: RequestInit) => handle.handleRequest(new Request(u, init)); + + try { + const { baseHeaders } = await completeHandshake(url, fetch); + + const standaloneRes = await fetch(url, { + method: 'GET', + headers: { ...baseHeaders, accept: 'text/event-stream' } + }); + expect(standaloneRes.status).toBe(200); + + const postRes = await fetch(url, { + method: 'POST', + headers: { ...baseHeaders, 'content-type': 'application/json', accept: 'application/json, text/event-stream' }, + body: JSON.stringify({ + jsonrpc: '2.0', + id: 'close-standalone-1', + method: 'tools/call', + params: { name: 'close-standalone', arguments: {} } + }) + }); + expect(postRes.status).toBe(200); + await readSseBody(requireBody(postRes)); + + const standaloneBody = await readSseBody(requireBody(standaloneRes)); + const events = standaloneBody.split('\n\n').filter(e => e.trim().length > 0); + expect(events).toHaveLength(1); + const primingLines = events[0]!.split('\n'); + expect(primingLines).toContain(`retry: ${RETRY_MS}`); + expect(primingLines).toContain('data: '); + const primingId = primingLines + .find(l => l.startsWith('id:')) + ?.slice('id:'.length) + .trim(); + expect(primingId).toBeTruthy(); + if (!primingId) throw new Error('No priming event id in GET SSE body'); + + if (!serverRef) throw new Error('serverRef not set'); + await serverRef.server.sendLoggingMessage({ level: 'info', data: 'while-disconnected' }); + + const resumeRes = await fetch(url, { + method: 'GET', + headers: { ...baseHeaders, accept: 'text/event-stream', 'last-event-id': primingId } + }); + expect(resumeRes.status).toBe(200); + const resumed = parseSseFrames(await readSseFramesUntil(requireBody(resumeRes), 1)); + expect(resumed).toHaveLength(1); + expect(JSON.parse(resumed[0]!.data)).toMatchObject({ method: 'notifications/message', params: { data: 'while-disconnected' } }); + } finally { + await handle.close(); + } +}); + verifies('hosting:resume:stream-scoped', async (_args: TestArgs) => { const eventStore = new InMemoryEventStore(); @@ -821,7 +892,7 @@ verifies('hosting:resume:close-stream', async (_args: TestArgs) => { const postBody = await readSseBody(requireBody(postRes)); const standaloneBody = await readSseBody(requireBody(standaloneRes)); - expect(standaloneBody).toBe(''); + expect(standaloneBody).toMatch(/^id: \S+\ndata: \n\n$/); expect(postBody).not.toMatch(/^event: message$/m); const primingId = postBody.match(/^id:\s*(.+)$/m)?.[1]?.trim();