@mcp-ts/sdk 1.3.3 → 1.3.5

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

@@ -1,207 +1,204 @@
-/**
- * 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
- */
-
+/**
+ * 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 { isConnectionEvent, isRpcResponseEvent } from '../../shared/event-routing.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),
+
+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) {
+          } else if (isConnectionEvent(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 };
-}
+        }
+      );
+
+      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

@@ -13,8 +13,8 @@
  */
 
 import type { McpConnectionEvent, McpObservabilityEvent } from '../../shared/events.js';
-import type {
-  McpRpcRequest,
+import type {
+  McpRpcRequest,
   McpRpcResponse,
   ConnectParams,
   DisconnectParams,
@@ -32,10 +32,12 @@ import type {
   ListPromptsResult,
   ListResourcesResult,
   CallToolResult,
-} from '../../shared/types.js';
-import { RpcErrorCodes } from '../../shared/errors.js';
-import { MCPClient } from '../mcp/oauth-client.js';
-import { storage } from '../storage/index.js';
+} from '../../shared/types.js';
+import { RpcErrorCodes } from '../../shared/errors.js';
+import { UnauthorizedError } from '../../shared/errors.js';
+import { isConnectionEvent, isRpcResponseEvent } from '../../shared/event-routing.js';
+import { MCPClient } from '../mcp/oauth-client.js';
+import { storage } from '../storage/index.js';
 
 // ============================================
 // Types & Interfaces
@@ -79,7 +81,7 @@ const DEFAULT_HEARTBEAT_INTERVAL = 30000;
  * Manages a single SSE connection and handles MCP operations.
  * Each instance corresponds to one connected browser client.
  */
-export class SSEConnectionManager {
+export class SSEConnectionManager {
   private readonly identity: string;
   private readonly clients = new Map<string, MCPClient>();
   private heartbeatTimer?: NodeJS.Timeout;
@@ -234,7 +236,7 @@ export class SSEConnectionManager {
   /**
    * Connect to an MCP server
    */
-  private async connect(params: ConnectParams): Promise<ConnectResult> {
+  private async connect(params: ConnectParams): Promise<ConnectResult> {
     const { serverName, serverUrl, callbackUrl, transportType } = params;
 
     // Normalize serverId to max 12 chars to keep tool names under 64 chars (DeepSeek/OpenAI limits)
@@ -265,43 +267,21 @@ export class SSEConnectionManager {
     // Generate session ID
     const sessionId = await storage.generateSessionId();
 
-    // Emit connecting state
-    this.emitConnectionEvent({
-      type: 'state_changed',
-      sessionId,
-      serverId,
-      serverName,
-      serverUrl,
-      state: 'CONNECTING',
-      previousState: 'DISCONNECTED',
-      timestamp: Date.now(),
-    });
-
-    try {
+    try {
       // Get resolved client metadata
       const clientMetadata = await this.getResolvedClientMetadata();
 
       // Create MCP client
-      const client = new MCPClient({
-        identity: this.identity,
-        sessionId,
-        serverId,
-        serverName,
-        serverUrl,
-        callbackUrl,
-        transportType,
-        ...clientMetadata, // Spread client metadata (clientName, clientUri, logoUri, policyUri)
-        onRedirect: (authUrl) => {
-          // Emit auth required event
-          this.emitConnectionEvent({
-            type: 'auth_required',
-            sessionId,
-            serverId,
-            authUrl,
-            timestamp: Date.now(),
-          });
-        },
-      });
+      const client = new MCPClient({
+        identity: this.identity,
+        sessionId,
+        serverId,
+        serverName,
+        serverUrl,
+        callbackUrl,
+        transportType,
+        ...clientMetadata, // Spread client metadata (clientName, clientUri, logoUri, policyUri)
+      });
 
       // Note: Session will be created by MCPClient after successful connection
       // This ensures sessions only exist for successful or OAuth-pending connections
@@ -322,25 +302,25 @@ export class SSEConnectionManager {
       await client.connect();
 
       // Fetch tools
-      const tools = await client.listTools();
-
-      this.emitConnectionEvent({
-        type: 'tools_discovered',
-        sessionId,
-        serverId,
-        toolCount: tools.tools.length,
-        tools: tools.tools,
-        timestamp: Date.now(),
-      });
+      await client.listTools();
 
       return {
         sessionId,
         success: true,
       };
-    } catch (error) {
-      this.emitConnectionEvent({
-        type: 'error',
-        sessionId,
+    } catch (error) {
+      if (error instanceof UnauthorizedError) {
+        // OAuth-required is a pending-auth state, not a failed connection.
+        this.clients.delete(sessionId);
+        return {
+          sessionId,
+          success: true,
+        };
+      }
+
+      this.emitConnectionEvent({
+        type: 'error',
+        sessionId,
         serverId,
         error: error instanceof Error ? error.message : 'Connection failed',
         errorType: 'connection',
@@ -468,15 +448,6 @@ export class SSEConnectionManager {
 
       const tools = await client.listTools();
 
-      this.emitConnectionEvent({
-        type: 'tools_discovered',
-        sessionId,
-        serverId: session.serverId ?? 'unknown',
-        toolCount: tools.tools.length,
-        tools: tools.tools,
-        timestamp: Date.now(),
-      });
-
       return { success: true, toolCount: tools.tools.length };
     } catch (error) {
       this.emitConnectionEvent({
@@ -495,29 +466,18 @@ export class SSEConnectionManager {
   /**
    * Complete OAuth authorization flow
    */
-  private async finishAuth(params: FinishAuthParams): Promise<FinishAuthResult> {
-    const { sessionId, code } = params;
-
-    const session = await storage.getSession(this.identity, sessionId);
-    if (!session) {
-      throw new Error('Session not found');
-    }
-
-    this.emitConnectionEvent({
-      type: 'state_changed',
-      sessionId,
-      serverId: session.serverId ?? 'unknown',
-      serverName: session.serverName ?? 'Unknown',
-      serverUrl: session.serverUrl,
-      state: 'AUTHENTICATING',
-      previousState: 'DISCONNECTED',
-      timestamp: Date.now(),
-    });
-
-    try {
-      const client = new MCPClient({
-        identity: this.identity,
-        sessionId,
+  private async finishAuth(params: FinishAuthParams): Promise<FinishAuthResult> {
+    const { sessionId, code } = params;
+
+    const session = await storage.getSession(this.identity, sessionId);
+    if (!session) {
+      throw new Error('Session not found');
+    }
+
+    try {
+      const client = new MCPClient({
+        identity: this.identity,
+        sessionId,
       });
 
       client.onConnectionEvent((event) => this.emitConnectionEvent(event));
@@ -527,15 +487,6 @@ export class SSEConnectionManager {
 
       const tools = await client.listTools();
 
-      this.emitConnectionEvent({
-        type: 'tools_discovered',
-        sessionId,
-        serverId: session.serverId ?? 'unknown',
-        toolCount: tools.tools.length,
-        tools: tools.tools,
-        timestamp: Date.now(),
-      });
-
       return { success: true, toolCount: tools.tools.length };
     } catch (error) {
       this.emitConnectionEvent({
@@ -622,8 +573,8 @@ export class SSEConnectionManager {
  * Create an SSE endpoint handler compatible with Node.js HTTP frameworks.
  * Handles both SSE streaming (GET) and RPC requests (POST).
  */
-export function createSSEHandler(options: SSEHandlerOptions) {
-  return async (req: { method?: string; on: Function }, res: { writeHead: Function; write: Function }) => {
+export function createSSEHandler(options: SSEHandlerOptions) {
+  return async (req: { method?: string; on: Function }, res: { writeHead: Function; write: Function }) => {
     // Set SSE headers
     res.writeHead(200, {
       'Content-Type': 'text/event-stream',
@@ -635,15 +586,15 @@ export function createSSEHandler(options: SSEHandlerOptions) {
     // Send initial connection acknowledgment
     writeSSEEvent(res, 'connected', { timestamp: Date.now() });
 
-    // Create connection manager with event routing
-    const manager = new SSEConnectionManager(options, (event) => {
-      if ('id' in event) {
-        writeSSEEvent(res, 'rpc-response', event);
-      } else if ('type' in event && 'sessionId' in event) {
-        writeSSEEvent(res, 'connection', event);
-      } else {
-        writeSSEEvent(res, 'observability', event);
-      }
+    // Create connection manager with event routing
+    const manager = new SSEConnectionManager(options, (event) => {
+      if (isRpcResponseEvent(event)) {
+        writeSSEEvent(res, 'rpc-response', event);
+      } else if (isConnectionEvent(event)) {
+        writeSSEEvent(res, 'connection', event);
+      } else {
+        writeSSEEvent(res, 'observability', event);
+      }
     });
 
     // Cleanup on client disconnect
@@ -674,7 +625,7 @@ export function createSSEHandler(options: SSEHandlerOptions) {
 /**
  * Write an SSE event to the response stream
  */
-function writeSSEEvent(res: { write: Function }, event: string, data: unknown): void {
-  res.write(`event: ${event}\n`);
-  res.write(`data: ${JSON.stringify(data)}\n\n`);
-}
+function writeSSEEvent(res: { write: Function }, event: string, data: unknown): void {
+  res.write(`event: ${event}\n`);
+  res.write(`data: ${JSON.stringify(data)}\n\n`);
+}