Add conformance tests for SEP-1699 SSE polling

Adds conformance tests for SEP-1699 (SSE Polling via Server-Side
Disconnect) which allows servers to close connections while maintaining
SSE streams for long-polling behavior.

New scenarios:
- server-sse-polling: Tests server sends priming event (id + empty data)
  and retry field before closing connection (SHOULD requirements)
- sse-retry: Tests client respects SSE retry field timing when
  reconnecting (MUST requirement)

These tests will initially fail for TypeScript SDK as it doesn't
currently respect the retry field from SSE events.

Author: felixweinberger

examples/clients/typescript/sse-retry-test.ts

@@ -0,0 +1,87 @@
+#!/usr/bin/env node
+
+/**
+ * SSE Retry Test Client
+ *
+ * Tests that the MCP client respects the SSE retry field when reconnecting.
+ * This client connects to a test server that sends retry: field and closes
+ * the connection, then validates that the client waits the appropriate time.
+ */
+
+import { Client } from '@modelcontextprotocol/sdk/client/index.js';
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
+
+async function main(): Promise<void> {
+  const serverUrl = process.argv[2];
+
+  if (!serverUrl) {
+    console.error('Usage: sse-retry-test <server-url>');
+    process.exit(1);
+  }
+
+  console.log(`Connecting to MCP server at: ${serverUrl}`);
+  console.log('This test validates SSE retry field compliance (SEP-1699)');
+
+  try {
+    const client = new Client(
+      {
+        name: 'sse-retry-test-client',
+        version: '1.0.0'
+      },
+      {
+        capabilities: {}
+      }
+    );
+
+    const transport = new StreamableHTTPClientTransport(new URL(serverUrl), {
+      reconnectionOptions: {
+        initialReconnectionDelay: 1000,
+        maxReconnectionDelay: 10000,
+        reconnectionDelayGrowFactor: 1.5,
+        maxRetries: 3
+      }
+    });
+
+    // Track reconnection events
+    transport.onerror = (error) => {
+      console.log(`Transport error: ${error.message}`);
+    };
+
+    transport.onclose = () => {
+      console.log('Transport closed');
+    };
+
+    console.log('Initiating connection...');
+    await client.connect(transport);
+    console.log('Connected to MCP server');
+
+    // Keep connection alive to observe reconnection behavior
+    // The server will disconnect and the client should reconnect
+    console.log('Waiting for reconnection cycle...');
+    console.log(
+      'Server will close connection and client should wait for retry field timing'
+    );
+
+    // Wait long enough for:
+    // 1. Server to send retry field and close (100ms)
+    // 2. Client to wait for retry period (2000ms expected)
+    // 3. Client to reconnect (100ms)
+    // 4. Second disconnect cycle (optional)
+    await new Promise((resolve) => setTimeout(resolve, 6000));
+
+    console.log('Test duration complete');
+
+    await transport.close();
+    console.log('Connection closed successfully');
+
+    process.exit(0);
+  } catch (error) {
+    console.error('Test failed:', error);
+    process.exit(1);
+  }
+}
+
+main().catch((error) => {
+  console.error('Unhandled error:', error);
+  process.exit(1);
+});

src/scenarios/client/sse-retry.ts

@@ -0,0 +1,305 @@
+/**
+ * SSE Retry conformance test scenarios for MCP clients (SEP-1699)
+ *
+ * Tests that clients properly respect the SSE retry field by:
+ * - Waiting the specified milliseconds before reconnecting
+ * - Sending Last-Event-ID header on reconnection
+ */
+
+import http from 'http';
+import { Scenario, ScenarioUrls, ConformanceCheck } from '../../types.js';
+
+export class SSERetryScenario implements Scenario {
+  name = 'sse-retry';
+  description = 'Tests that client respects SSE retry field timing (SEP-1699)';
+
+  private server: http.Server | null = null;
+  private checks: ConformanceCheck[] = [];
+  private port: number = 0;
+
+  // Timing tracking
+  private connectionTimestamps: number[] = [];
+  private lastEventIds: (string | undefined)[] = [];
+  private retryValue: number = 2000; // 2 seconds
+  private eventIdCounter: number = 0;
+
+  // Tolerances for timing validation
+  private readonly EARLY_TOLERANCE = 50; // Allow 50ms early for scheduler variance
+  private readonly LATE_TOLERANCE = 200; // Allow 200ms late for network/event loop
+
+  async start(): Promise<ScenarioUrls> {
+    return new Promise((resolve, reject) => {
+      this.server = http.createServer((req, res) => {
+        this.handleRequest(req, res);
+      });
+
+      this.server.on('error', reject);
+
+      this.server.listen(0, () => {
+        const address = this.server!.address();
+        if (address && typeof address === 'object') {
+          this.port = address.port;
+          resolve({
+            serverUrl: `http://localhost:${this.port}`
+          });
+        } else {
+          reject(new Error('Failed to get server address'));
+        }
+      });
+    });
+  }
+
+  async stop(): Promise<void> {
+    return new Promise((resolve, reject) => {
+      if (this.server) {
+        this.server.close((err) => {
+          if (err) {
+            reject(err);
+          } else {
+            this.server = null;
+            resolve();
+          }
+        });
+      } else {
+        resolve();
+      }
+    });
+  }
+
+  getChecks(): ConformanceCheck[] {
+    // Generate checks based on observed behavior
+    this.generateChecks();
+    return this.checks;
+  }
+
+  private handleRequest(
+    req: http.IncomingMessage,
+    res: http.ServerResponse
+  ): void {
+    const timestamp = performance.now();
+    this.connectionTimestamps.push(timestamp);
+
+    // Track Last-Event-ID header
+    const lastEventId = req.headers['last-event-id'] as string | undefined;
+    this.lastEventIds.push(lastEventId);
+
+    if (req.method === 'GET') {
+      // Handle SSE stream request
+      this.handleSSEStream(req, res);
+    } else if (req.method === 'POST') {
+      // Handle JSON-RPC requests (for initialization)
+      this.handleJSONRPC(req, res);
+    } else {
+      res.writeHead(405);
+      res.end('Method Not Allowed');
+    }
+  }
+
+  private handleSSEStream(
+    req: http.IncomingMessage,
+    res: http.ServerResponse
+  ): void {
+    // Set SSE headers
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache',
+      Connection: 'keep-alive'
+    });
+
+    // Generate event ID
+    this.eventIdCounter++;
+    const eventId = `event-${this.eventIdCounter}`;
+
+    // Send priming event with ID and empty data
+    res.write(`id: ${eventId}\n`);
+    res.write(`retry: ${this.retryValue}\n`);
+    res.write(`data: \n\n`);
+
+    // Close connection after a short delay to trigger client reconnection
+    setTimeout(() => {
+      res.end();
+    }, 100);
+  }
+
+  private handleJSONRPC(
+    req: http.IncomingMessage,
+    res: http.ServerResponse
+  ): void {
+    let body = '';
+
+    req.on('data', (chunk) => {
+      body += chunk.toString();
+    });
+
+    req.on('end', () => {
+      try {
+        const request = JSON.parse(body);
+
+        if (request.method === 'initialize') {
+          // Respond to initialize request with SSE stream
+          res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            Connection: 'keep-alive'
+          });
+
+          // Generate event ID
+          this.eventIdCounter++;
+          const eventId = `event-${this.eventIdCounter}`;
+
+          // Send priming event
+          res.write(`id: ${eventId}\n`);
+          res.write(`retry: ${this.retryValue}\n`);
+          res.write(`data: \n\n`);
+
+          // Send initialize response
+          const response = {
+            jsonrpc: '2.0',
+            id: request.id,
+            result: {
+              protocolVersion: '2025-06-18',
+              serverInfo: {
+                name: 'sse-retry-test-server',
+                version: '1.0.0'
+              },
+              capabilities: {}
+            }
+          };
+
+          res.write(`event: message\n`);
+          res.write(`id: event-${++this.eventIdCounter}\n`);
+          res.write(`data: ${JSON.stringify(response)}\n\n`);
+
+          // Close connection after sending response to trigger reconnection
+          setTimeout(() => {
+            res.end();
+          }, 100);
+        } else {
+          // For other requests, send a simple JSON response
+          res.writeHead(200, { 'Content-Type': 'application/json' });
+          res.end(
+            JSON.stringify({
+              jsonrpc: '2.0',
+              id: request.id,
+              result: {}
+            })
+          );
+        }
+      } catch (error) {
+        res.writeHead(400, { 'Content-Type': 'application/json' });
+        res.end(
+          JSON.stringify({
+            jsonrpc: '2.0',
+            error: {
+              code: -32700,
+              message: `Parse error: ${error}`
+            }
+          })
+        );
+      }
+    });
+  }
+
+  private generateChecks(): void {
+    // Check 1: Client should have reconnected
+    if (this.connectionTimestamps.length < 2) {
+      this.checks.push({
+        id: 'client-sse-retry-reconnect',
+        name: 'ClientReconnects',
+        description: 'Client reconnects after server disconnect',
+        status: 'FAILURE',
+        timestamp: new Date().toISOString(),
+        errorMessage: `Expected at least 2 connections, got ${this.connectionTimestamps.length}. Client may not have attempted to reconnect.`,
+        specReferences: [
+          {
+            id: 'SEP-1699',
+            url: 'https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1699'
+          }
+        ],
+        details: {
+          connectionCount: this.connectionTimestamps.length,
+          retryValue: this.retryValue
+        }
+      });
+      return;
+    }
+
+    // Check 2: Client MUST respect retry field timing
+    const actualDelay =
+      this.connectionTimestamps[1] - this.connectionTimestamps[0];
+    const minExpected = this.retryValue - this.EARLY_TOLERANCE;
+    const maxExpected = this.retryValue + this.LATE_TOLERANCE;
+
+    const tooEarly = actualDelay < minExpected;
+    const tooLate = actualDelay > maxExpected;
+    const withinTolerance = !tooEarly && !tooLate;
+
+    let status: 'SUCCESS' | 'FAILURE' | 'WARNING' = 'SUCCESS';
+    let errorMessage: string | undefined;
+
+    if (tooEarly) {
+      // Client reconnected too soon - MUST violation
+      status = 'FAILURE';
+      errorMessage = `Client reconnected too early (${actualDelay.toFixed(0)}ms instead of ${this.retryValue}ms). Client MUST respect the retry field and wait the specified time.`;
+    } else if (tooLate) {
+      // Client reconnected too late - not a spec violation but suspicious
+      status = 'WARNING';
+      errorMessage = `Client reconnected late (${actualDelay.toFixed(0)}ms instead of ${this.retryValue}ms). This is acceptable but may indicate the client is ignoring the retry field and using its own backoff.`;
+    }
+
+    this.checks.push({
+      id: 'client-sse-retry-timing',
+      name: 'ClientRespectsRetryField',
+      description:
+        'Client MUST respect the retry field, waiting the given number of milliseconds before attempting to reconnect',
+      status,
+      timestamp: new Date().toISOString(),
+      errorMessage,
+      specReferences: [
+        {
+          id: 'SEP-1699',
+          url: 'https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1699'
+        }
+      ],
+      details: {
+        expectedRetryMs: this.retryValue,
+        actualDelayMs: Math.round(actualDelay),
+        minAcceptableMs: minExpected,
+        maxAcceptableMs: maxExpected,
+        earlyToleranceMs: this.EARLY_TOLERANCE,
+        lateToleranceMs: this.LATE_TOLERANCE,
+        withinTolerance,
+        tooEarly,
+        tooLate,
+        connectionCount: this.connectionTimestamps.length
+      }
+    });
+
+    // Check 3: Client SHOULD send Last-Event-ID header on reconnection
+    const hasLastEventId =
+      this.lastEventIds.length > 1 && this.lastEventIds[1] !== undefined;
+
+    this.checks.push({
+      id: 'client-sse-last-event-id',
+      name: 'ClientSendsLastEventId',
+      description:
+        'Client SHOULD send Last-Event-ID header on reconnection for resumability',
+      status: hasLastEventId ? 'SUCCESS' : 'WARNING',
+      timestamp: new Date().toISOString(),
+      specReferences: [
+        {
+          id: 'SEP-1699',
+          url: 'https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1699'
+        }
+      ],
+      details: {
+        hasLastEventId,
+        lastEventIds: this.lastEventIds,
+        connectionCount: this.connectionTimestamps.length
+      },
+      errorMessage: !hasLastEventId
+        ? 'Client did not send Last-Event-ID header on reconnection. This is a SHOULD requirement for resumability.'
+        : undefined
+    });
+  }
+}