@mcp-ts/sdk 1.3.2 → 1.3.3

package/src/server/handlers/nextjs-handler.ts

@@ -1,217 +1,207 @@
-/**
- * Next.js App Router Handler for MCP SSE
- * Provides a clean, zero-boilerplate API for Next.js applications
- */
-
-import { SSEConnectionManager, type ClientMetadata } from './sse-handler.js';
-import type { McpConnectionEvent, McpObservabilityEvent } from '../../shared/events.js';
-import type { McpRpcResponse } from '../../shared/types.js';
-
-export interface NextMcpHandlerOptions {
-  /**
-   * Extract identity from request (default: from 'identity' query param)
-   */
-  getIdentity?: (request: Request) => string | null;
-
-  /**
-   * Extract auth token from request (default: from 'token' query param or Authorization header)
-   */
-  getAuthToken?: (request: Request) => string | null;
-
-  /**
-   * Authenticate user and verify access (optional)
-   * Return true if user is authenticated, false otherwise
-   */
-  authenticate?: (identity: string, token: string | null) => Promise<boolean> | boolean;
-
-  /**
-   * Heartbeat interval in milliseconds (default: 30000)
-   */
-  heartbeatInterval?: number;
-
-  /**
-   * Static OAuth client metadata defaults (for all connections)
-   * Use this for single-tenant applications with fixed branding
-   */
-  clientDefaults?: ClientMetadata;
-
-  /**
-   * Dynamic OAuth client metadata getter (per-request, useful for multi-tenant)
-   * Use this when you need different branding based on request (tenant, domain, etc.)
-   * Takes precedence over clientDefaults
-   */
-  getClientMetadata?: (request: Request) => ClientMetadata | Promise<ClientMetadata>;
-}
-
-// Global manager store - shared across requests for the same user
-const managers = new Map<string, SSEConnectionManager>();
-
-/**
- * Creates Next.js App Router handlers (GET and POST) for MCP SSE endpoint
- *
- * @example
- * ```typescript
- * // app/api/mcp/route.ts
- * import { createNextMcpHandler } from '@mcp-ts/core/server';
- *
- * export const { GET, POST } = createNextMcpHandler();
- * ```
- */
-export function createNextMcpHandler(options: NextMcpHandlerOptions = {}) {
-  const {
-    getIdentity = (request: Request) => new URL(request.url).searchParams.get('identity'),
-    getAuthToken = (request: Request) => {
-      const url = new URL(request.url);
-      return url.searchParams.get('token') || request.headers.get('authorization');
-    },
-    authenticate = () => true,
-    heartbeatInterval = 30000,
-    clientDefaults,
-    getClientMetadata,
-  } = options;
-
-  /**
-   * GET handler - Establishes SSE connection
-   */
-  async function GET(request: Request): Promise<Response> {
-    const identity = getIdentity(request);
-    const authToken = getAuthToken(request);
-
-    if (!identity) {
-      return new Response('Missing identity', { status: 400 });
-    }
-
-    // Validate auth
-    const isAuthorized = await authenticate(identity, authToken);
-    if (!isAuthorized) {
-      return new Response('Unauthorized', { status: 401 });
-    }
-
-    // Create TransformStream for SSE
-    const stream = new TransformStream();
-    const writer = stream.writable.getWriter();
-    const encoder = new TextEncoder();
-
-    // Helper to send SSE events
-    const sendSSE = (event: string, data: any) => {
-      const message = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
-      writer.write(encoder.encode(message)).catch(() => {
-        // Client disconnected, ignore write errors
-      });
-    };
-
-    // Clean up previous manager if exists (prevents memory leaks on reconnect)
-    const previousManager = managers.get(identity);
-    if (previousManager) {
-      previousManager.dispose();
-    }
-
-    // Resolve client metadata (dynamic takes precedence over static)
-    const resolvedClientMetadata = getClientMetadata
-      ? await getClientMetadata(request)
-      : clientDefaults;
-
-    // Create new manager
-    const manager = new SSEConnectionManager(
-      {
-        identity,
-        heartbeatInterval,
-        clientDefaults: resolvedClientMetadata, // Pass resolved metadata
-      },
-      (event: McpConnectionEvent | McpObservabilityEvent | McpRpcResponse) => {
-        // Determine event type and send via SSE
-        if ('id' in event) {
-          // RPC response
-          sendSSE('rpc-response', event);
-        } else if ('type' in event && 'sessionId' in event) {
-          // Connection event
-          sendSSE('connection', event);
-        } else {
-          // Observability event
-          sendSSE('observability', event);
-        }
-      }
-    );
-
-    managers.set(identity, manager);
-
-    // Send connected event AFTER manager is registered (prevents race condition
-    // where client sends POST before manager is available)
-    sendSSE('connected', { timestamp: Date.now() });
-
-    // Handle client disconnect
-    const abortController = new AbortController();
-    request.signal?.addEventListener('abort', () => {
-      manager.dispose();
-      managers.delete(identity);
-      writer.close().catch(() => { });
-      abortController.abort();
-    });
-
-    // Return SSE response
-    return new Response(stream.readable, {
-      status: 200,
-      headers: {
-        'Content-Type': 'text/event-stream',
-        'Cache-Control': 'no-cache, no-transform',
-        'Connection': 'keep-alive',
-        'X-Accel-Buffering': 'no',
-      },
-    });
-  }
-
-  /**
-   * POST handler - Handles RPC requests
-   */
-  async function POST(request: Request): Promise<Response> {
-    const identity = getIdentity(request);
-    const authToken = getAuthToken(request);
-
-    if (!identity) {
-      return Response.json({ error: { code: 'MISSING_IDENTITY', message: 'Missing identity' } }, { status: 400 });
-    }
-
-    // Validate auth
-    const isAuthorized = await authenticate(identity, authToken);
-    if (!isAuthorized) {
-      return Response.json({ error: { code: 'UNAUTHORIZED', message: 'Unauthorized' } }, { status: 401 });
-    }
-
-    try {
-      const body = await request.json();
-
-      // Get existing manager (created by GET endpoint)
-      const manager = managers.get(identity);
-
-      if (!manager) {
-        return Response.json(
-          {
-            error: {
-              code: 'NO_CONNECTION',
-              message: 'No SSE connection found. Please establish SSE connection first.',
-            },
-          },
-          { status: 400 }
-        );
-      }
-
-      // Handle the request and return response directly (bypasses SSE latency)
-      const response = await manager.handleRequest(body);
-
-      // Return the actual RPC response for immediate use by client
-      return Response.json(response);
-    } catch (error) {
-      return Response.json(
-        {
-          error: {
-            code: 'EXECUTION_ERROR',
-            message: error instanceof Error ? error.message : 'Unknown error',
-          },
-        },
-        { status: 500 }
-      );
-    }
-  }
-
-  return { GET, POST };
-}
+/**
+ * Next.js App Router Handler for MCP
+ * Stateless transport for serverless environments:
+ * - POST + `Accept: text/event-stream` streams progress + rpc-response
+ * - POST + JSON accepts direct RPC result response
+ */
+
+import { SSEConnectionManager, type ClientMetadata } from './sse-handler.js';
+import type { McpConnectionEvent, McpObservabilityEvent } from '../../shared/events.js';
+import type { McpRpcResponse } from '../../shared/types.js';
+
+function isRpcResponseEvent(event: McpConnectionEvent | McpObservabilityEvent | McpRpcResponse): event is McpRpcResponse {
+  return 'id' in event && ('result' in event || 'error' in event);
+}
+
+export interface NextMcpHandlerOptions {
+  /**
+   * Extract identity from request (default: from 'identity' query param)
+   */
+  getIdentity?: (request: Request) => string | null;
+
+  /**
+   * Extract auth token from request (default: from 'token' query param or Authorization header)
+   */
+  getAuthToken?: (request: Request) => string | null;
+
+  /**
+   * Authenticate user and verify access (optional)
+   * Return true if user is authenticated, false otherwise
+   */
+  authenticate?: (identity: string, token: string | null) => Promise<boolean> | boolean;
+
+  /**
+   * Heartbeat interval in milliseconds (default: 30000)
+   */
+  heartbeatInterval?: number;
+
+  /**
+   * Static OAuth client metadata defaults (for all connections)
+   */
+  clientDefaults?: ClientMetadata;
+
+  /**
+   * Dynamic OAuth client metadata getter (per-request)
+   */
+  getClientMetadata?: (request: Request) => ClientMetadata | Promise<ClientMetadata>;
+}
+
+export function createNextMcpHandler(options: NextMcpHandlerOptions = {}) {
+  const {
+    getIdentity = (request: Request) => new URL(request.url).searchParams.get('identity'),
+    getAuthToken = (request: Request) => {
+      const url = new URL(request.url);
+      return url.searchParams.get('token') || request.headers.get('authorization');
+    },
+    authenticate = () => true,
+    heartbeatInterval = 30000,
+    clientDefaults,
+    getClientMetadata,
+  } = options;
+
+  const toManagerOptions = (identity: string, resolvedClientMetadata?: ClientMetadata) => ({
+    identity,
+    heartbeatInterval,
+    clientDefaults: resolvedClientMetadata,
+  });
+
+  async function resolveClientMetadata(request: Request): Promise<ClientMetadata | undefined> {
+    return getClientMetadata ? await getClientMetadata(request) : clientDefaults;
+  }
+
+  async function GET(): Promise<Response> {
+    return Response.json(
+      {
+        error: {
+          code: 'METHOD_NOT_ALLOWED',
+          message: 'Use POST /api/mcp. For streaming use Accept: text/event-stream.',
+        },
+      },
+      { status: 405 }
+    );
+  }
+
+  async function POST(request: Request): Promise<Response> {
+    const identity = getIdentity(request);
+    const authToken = getAuthToken(request);
+    const acceptsEventStream = (request.headers.get('accept') || '').toLowerCase().includes('text/event-stream');
+
+    if (!identity) {
+      return Response.json({ error: { code: 'MISSING_IDENTITY', message: 'Missing identity' } }, { status: 400 });
+    }
+
+    const isAuthorized = await authenticate(identity, authToken);
+    if (!isAuthorized) {
+      return Response.json({ error: { code: 'UNAUTHORIZED', message: 'Unauthorized' } }, { status: 401 });
+    }
+
+    let rawBody = '';
+    try {
+      rawBody = await request.text();
+      const body = rawBody ? JSON.parse(rawBody) : null;
+
+      if (!body || typeof body !== 'object') {
+        return Response.json(
+          {
+            error: {
+              code: 'INVALID_REQUEST',
+              message: 'Invalid JSON-RPC request body',
+            },
+          },
+          { status: 400 }
+        );
+      }
+
+      const resolvedClientMetadata = await resolveClientMetadata(request);
+
+      if (!acceptsEventStream) {
+        const manager = new SSEConnectionManager(
+          toManagerOptions(identity, resolvedClientMetadata),
+          () => { }
+        );
+        try {
+          const response = await manager.handleRequest(body as any);
+          return Response.json(response);
+        } finally {
+          manager.dispose();
+        }
+      }
+
+      const stream = new TransformStream();
+      const writer = stream.writable.getWriter();
+      const encoder = new TextEncoder();
+      let streamWritable = true;
+
+      const sendSSE = (event: string, data: unknown) => {
+        if (!streamWritable) return;
+        const message = `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`;
+        writer.write(encoder.encode(message)).catch(() => {
+          streamWritable = false;
+        });
+      };
+
+      const manager = new SSEConnectionManager(
+        toManagerOptions(identity, resolvedClientMetadata),
+        (event: McpConnectionEvent | McpObservabilityEvent | McpRpcResponse) => {
+          if (isRpcResponseEvent(event)) {
+            sendSSE('rpc-response', event);
+          } else if ('type' in event && 'sessionId' in event) {
+            sendSSE('connection', event);
+          } else {
+            sendSSE('observability', event);
+          }
+        }
+      );
+
+      sendSSE('connected', { timestamp: Date.now() });
+
+      void (async () => {
+        try {
+          await manager.handleRequest(body as any);
+        } catch (error) {
+          const err = error instanceof Error ? error : new Error('Unknown error');
+          sendSSE('rpc-response', {
+            id: (body as any).id || 'unknown',
+            error: {
+              code: 'EXECUTION_ERROR',
+              message: err.message,
+            },
+          } satisfies McpRpcResponse);
+        } finally {
+          streamWritable = false;
+          manager.dispose();
+          writer.close().catch(() => { });
+        }
+      })();
+
+      return new Response(stream.readable, {
+        status: 200,
+        headers: {
+          'Content-Type': 'text/event-stream',
+          'Cache-Control': 'no-cache, no-transform',
+          'Connection': 'keep-alive',
+          'X-Accel-Buffering': 'no',
+        },
+      });
+    } catch (error) {
+      const err = error instanceof Error ? error : new Error('Unknown error');
+      console.error('[MCP Next Handler] Failed to handle RPC', {
+        identity,
+        message: err.message,
+        stack: err.stack,
+        rawBody: rawBody.slice(0, 500),
+      });
+      return Response.json(
+        {
+          error: {
+            code: 'EXECUTION_ERROR',
+            message: err.message,
+          },
+        },
+        { status: 500 }
+      );
+    }
+  }
+
+  return { GET, POST };
+}

package/src/server/handlers/sse-handler.ts

@@ -226,6 +226,7 @@ export class SSEConnectionManager {
         serverUrl: s.serverUrl,
         transport: s.transportType,
         createdAt: s.createdAt,
+        active: s.active !== false,
       })),
     };
   }
@@ -249,6 +250,15 @@ export class SSEConnectionManager {
     );
 
     if (duplicate) {
+      // If the existing session is still pending OAuth, treat connect as "resume auth"
+      // instead of failing with duplicate connection error.
+      if (duplicate.active === false) {
+        await this.restoreSession({ sessionId: duplicate.sessionId });
+        return {
+          sessionId: duplicate.sessionId,
+          success: true,
+        };
+      }
       throw new Error(`Connection already exists for server: ${duplicate.serverUrl || duplicate.serverId} (${duplicate.serverName})`);
     }
 

package/src/server/mcp/oauth-client.ts

@@ -363,29 +363,34 @@ export class MCPClient {
     if (!existingSession && this.serverId && this.serverUrl && this.callbackUrl) {
       this.createdAt = Date.now();
       console.log(`[MCPClient] Creating initial session ${this.sessionId} for OAuth flow`);
-      await storage.createSession({
-        sessionId: this.sessionId,
-        identity: this.identity,
-        serverId: this.serverId,
-        serverName: this.serverName,
-        serverUrl: this.serverUrl,
-        callbackUrl: this.callbackUrl,
-        transportType: this.transportType || 'streamable_http',
-        createdAt: this.createdAt,
-      }, Math.floor(STATE_EXPIRATION_MS / 1000)); // Short TTL until connection succeeds
-    }
-  }
+      await storage.createSession({
+        sessionId: this.sessionId,
+        identity: this.identity,
+        serverId: this.serverId,
+        serverName: this.serverName,
+        serverUrl: this.serverUrl,
+        callbackUrl: this.callbackUrl,
+        transportType: this.transportType || 'streamable_http',
+        createdAt: this.createdAt,
+        active: false,
+      }, Math.floor(STATE_EXPIRATION_MS / 1000)); // Short TTL until connection succeeds
+    }
+  }
 
   /**
    * Saves current session state to storage
    * Creates new session if it doesn't exist, updates if it does
-   * @param ttl - Time-to-live in seconds (defaults to 12hr for connected sessions)
-   * @private
-   */
-  private async saveSession(ttl: number = SESSION_TTL_SECONDS): Promise<void> {
-    if (!this.sessionId || !this.serverId || !this.serverUrl || !this.callbackUrl) {
-      return;
-    }
+   * @param ttl - Time-to-live in seconds (defaults to 12hr for connected sessions)
+   * @param active - Session status marker used to avoid unnecessary TTL rewrites
+   * @private
+   */
+  private async saveSession(
+    ttl: number = SESSION_TTL_SECONDS,
+    active: boolean = true
+  ): Promise<void> {
+    if (!this.sessionId || !this.serverId || !this.serverUrl || !this.callbackUrl) {
+      return;
+    }
 
     const sessionData = {
       sessionId: this.sessionId,
@@ -393,10 +398,11 @@ export class MCPClient {
       serverId: this.serverId,
       serverName: this.serverName,
       serverUrl: this.serverUrl,
-      callbackUrl: this.callbackUrl,
-      transportType: (this.transportType || 'streamable_http') as TransportType,
-      createdAt: this.createdAt || Date.now(),
-    };
+      callbackUrl: this.callbackUrl,
+      transportType: (this.transportType || 'streamable_http') as TransportType,
+      createdAt: this.createdAt || Date.now(),
+      active,
+    };
 
     // Try to update first, create if doesn't exist
     const existingSession = await storage.getSession(this.identity, this.sessionId);
@@ -506,13 +512,16 @@ export class MCPClient {
       this.emitStateChange('CONNECTED');
       this.emitProgress('Connected successfully');
 
-      // Only save/update session if transport type changed (connection negotiation)
-      // This avoids unnecessary writes to storage on every connect
-      const existingSession = await storage.getSession(this.identity, this.sessionId);
-      if (!existingSession || existingSession.transportType !== this.transportType) {
-        console.log(`[MCPClient] Saving session ${this.sessionId} (new or transport changed)`);
-        await this.saveSession(SESSION_TTL_SECONDS);
-      }
+      // Promote short-lived OAuth-pending session TTL to long-lived active TTL once.
+      // Also persist when transport negotiation changed the effective transport.
+      const existingSession = await storage.getSession(this.identity, this.sessionId);
+      const needsTransportUpdate = !existingSession || existingSession.transportType !== this.transportType;
+      const needsTtlPromotion = !existingSession || existingSession.active !== true;
+
+      if (needsTransportUpdate || needsTtlPromotion) {
+        console.log(`[MCPClient] Saving session ${this.sessionId} with 12hr TTL (connect success)`);
+        await this.saveSession(SESSION_TTL_SECONDS, true);
+      }
     } catch (error) {
       /** Handle Authentication Errors */
       if (
@@ -522,7 +531,7 @@ export class MCPClient {
         this.emitStateChange('AUTHENTICATING');
         // Save session with 10min TTL for OAuth pending state
         console.log(`[MCPClient] Saving session ${this.sessionId} with 10min TTL (OAuth pending)`);
-        await this.saveSession(Math.floor(STATE_EXPIRATION_MS / 1000));
+        await this.saveSession(Math.floor(STATE_EXPIRATION_MS / 1000), false);
 
         /** Get OAuth authorization URL if available */
         let authUrl = '';
@@ -633,7 +642,7 @@ export class MCPClient {
         this.emitStateChange('CONNECTED');
         // Update session with 12hr TTL after successful OAuth
         console.log(`[MCPClient] Updating session ${this.sessionId} to 12hr TTL (OAuth complete)`);
-        await this.saveSession(SESSION_TTL_SECONDS);
+        await this.saveSession(SESSION_TTL_SECONDS, true);
 
         return; // Success, exit function
 

package/src/server/storage/types.ts

@@ -5,8 +5,8 @@ import type {
     OAuthClientInformationMixed,
 } from '@modelcontextprotocol/sdk/shared/auth.js';
 
-export interface SessionData {
-    sessionId: string;
+export interface SessionData {
+    sessionId: string;
     serverId?: string; // Database server ID for mapping
     serverName?: string;
     serverUrl: string;
@@ -14,9 +14,16 @@ export interface SessionData {
     callbackUrl: string;
     createdAt: number;
     identity: string;
-    headers?: Record<string, string>;
-    // OAuth data (consolidated)
-    clientInformation?: OAuthClientInformationMixed;
+    headers?: Record<string, string>;
+    /**
+     * Session status marker used for TTL transitions:
+     * - false: short-lived intermediate/error/auth-pending session state
+     *          (keep this value when connection/auth is incomplete or failed)
+     * - true: active long-lived session state after successful connection/auth completion
+     */
+    active?: boolean;
+    // OAuth data (consolidated)
+    clientInformation?: OAuthClientInformationMixed;
     tokens?: OAuthTokens;
     codeVerifier?: string;
     clientId?: string;

package/src/shared/types.ts

@@ -224,6 +224,11 @@ export interface SessionInfo {
   serverUrl: string;
   transport: TransportType;
   createdAt: number;
+  /**
+   * Session readiness for auto-restore.
+   * false means auth is pending and should be resumed explicitly by user action.
+   */
+  active?: boolean;
 }
 
 export interface SessionListResult {