@mcp-ts/sdk 1.5.0 → 1.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-ts/sdk",
-  "version": "1.5.0",
+  "version": "1.5.1",
   "publishConfig": {
     "access": "public"
   },

package/src/client/react/index.ts

@@ -6,6 +6,20 @@
 // Core MCP Hook
 export { useMcp, type UseMcpOptions, type McpClient, type McpConnection } from './use-mcp.js';
 
+// Optional OAuth popup conveniences. These are not required for auth:
+// consumers can still provide their own onRedirect handler, callback page UI,
+// or complete `finishAuth(sessionId, code)` from a normal redirect flow.
+export {
+  useMcpOAuthPopup,
+  openCenteredPopup,
+  createOAuthPopupRedirectHandler,
+  McpOAuthCallbackContent,
+  McpOAuthCallbackFallback,
+  type OAuthPopupConnectionLike,
+  type OAuthPopupRedirectOptions,
+  type McpOAuthCallbackContentProps,
+} from './oauth-popup.js';
+
 // App Host (internal use)
 export { useAppHost } from './use-app-host.js';
 

package/src/client/react/oauth-popup.tsx

@@ -0,0 +1,446 @@
+import { useEffect, useRef, useState, type CSSProperties, type ReactNode } from 'react';
+
+export interface OAuthPopupConnectionLike {
+  sessionId: string;
+  state: string;
+  error?: string;
+}
+
+/**
+ * Optional helpers for popup-based OAuth UX.
+ *
+ * These utilities sit on top of the core MCP auth primitives:
+ * - `useMcp({ onRedirect })` to decide how auth navigation happens
+ * - `finishAuth(sessionId, code)` to complete code exchange
+ *
+ * Consumers are free to:
+ * - use these helpers as-is for a turnkey popup flow
+ * - build their own popup UI/message bridge
+ * - skip popups entirely and handle auth in a normal callback page
+ */
+export interface OAuthPopupRedirectOptions {
+  width?: number;
+  height?: number;
+  windowName?: string;
+  features?: string[];
+  onBlocked?: (url: string) => void;
+}
+
+export interface McpOAuthCallbackContentProps {
+  code?: string | null;
+  sessionId?: string | null;
+  title?: ReactNode;
+  initialStatus?: string;
+  loadingFallback?: ReactNode;
+  rootStyle?: CSSProperties;
+  cardStyle?: CSSProperties;
+  titleStyle?: CSSProperties;
+  messageStyle?: CSSProperties;
+  renderContainer?: (content: ReactNode) => ReactNode;
+  debugPhase?: 'loading' | 'success' | 'error';
+}
+
+const AUTH_CODE_MESSAGE = 'MCP_AUTH_CODE';
+const AUTH_RESULT_MESSAGE = 'MCP_AUTH_RESULT';
+
+function postPopupResult(
+  popupWindow: WindowProxy | null,
+  result: {
+    sessionId?: string;
+    success: boolean;
+    error?: string;
+  }
+): void {
+  popupWindow?.postMessage(
+    {
+      type: AUTH_RESULT_MESSAGE,
+      ...result,
+    },
+    window.location.origin
+  );
+}
+
+/**
+ * Opens a centered popup window for OAuth.
+ *
+ * Convenience only: callers can replace this entirely with their own popup,
+ * modal, redirect, or router-based navigation strategy.
+ */
+export function openCenteredPopup(url: string, options: OAuthPopupRedirectOptions = {}): Window | null {
+  const {
+    width = 600,
+    height = 700,
+    windowName = 'mcp-auth-popup',
+    features = [],
+    onBlocked,
+  } = options;
+
+  const left = window.screenX + (window.outerWidth - width) / 2;
+  const top = window.screenY + (window.outerHeight - height) / 2;
+  const featureList = [
+    `width=${width}`,
+    `height=${height}`,
+    `left=${left}`,
+    `top=${top}`,
+    'resizable=yes',
+    'scrollbars=yes',
+    'status=yes',
+    ...features,
+  ].join(',');
+
+  const popup = window.open(url, windowName, featureList);
+  if (!popup) {
+    onBlocked?.(url);
+  }
+
+  return popup;
+}
+
+/**
+ * Creates an `onRedirect` handler suitable for `useMcp({ onRedirect })`.
+ *
+ * This is the simplest popup entry point, but it is intentionally optional.
+ * Applications can provide any redirect handler they want, including full-page
+ * navigation or a completely custom popup implementation.
+ */
+export function createOAuthPopupRedirectHandler(
+  options: OAuthPopupRedirectOptions = {}
+): (url: string) => void {
+  return (url: string) => {
+    openCenteredPopup(url, {
+      ...options,
+      onBlocked: options.onBlocked ?? ((blockedUrl) => {
+        window.alert('Popup blocked! Allow popups for this site to complete authentication.');
+        window.location.href = blockedUrl;
+      }),
+    });
+  };
+}
+
+/**
+ * Handles opener-side popup coordination for OAuth code exchange.
+ *
+ * Use this when you want popup auth but do not want to reimplement the
+ * postMessage wiring between the main app window and the popup callback page.
+ *
+ * If you are not using a popup flow, you do not need this hook.
+ */
+export function useMcpOAuthPopup<TConnection extends OAuthPopupConnectionLike>(
+  connections: TConnection[],
+  finishAuth: (sessionId: string, code: string) => Promise<unknown>
+): void {
+  const pendingPopupsRef = useRef<Map<string, WindowProxy>>(new Map());
+
+  useEffect(() => {
+    const handleMessage = async (event: MessageEvent) => {
+      if (event.origin !== window.location.origin) {
+        return;
+      }
+
+      if (event.data?.type !== AUTH_CODE_MESSAGE || !event.data.code) {
+        return;
+      }
+
+      const popupWindow = event.source && 'postMessage' in event.source
+        ? event.source as WindowProxy
+        : null;
+      const targetSessionId = typeof event.data.sessionId === 'string' ? event.data.sessionId : '';
+
+      if (!targetSessionId) {
+        postPopupResult(popupWindow, {
+          success: false,
+          error: 'Missing OAuth session identifier',
+        });
+        return;
+      }
+
+      const targetSession = connections.find((connection) => connection.sessionId === targetSessionId);
+      if (!targetSession) {
+        postPopupResult(popupWindow, {
+          sessionId: targetSessionId,
+          success: false,
+          error: 'OAuth session not found in the current client state',
+        });
+        return;
+      }
+
+      if (popupWindow) {
+        pendingPopupsRef.current.set(targetSession.sessionId, popupWindow);
+      }
+
+      try {
+        await finishAuth(targetSession.sessionId, event.data.code);
+      } catch (error) {
+        pendingPopupsRef.current.delete(targetSession.sessionId);
+        postPopupResult(popupWindow, {
+          sessionId: targetSession.sessionId,
+          success: false,
+          error: error instanceof Error ? error.message : 'Failed to finish auth',
+        });
+      }
+    };
+
+    window.addEventListener('message', handleMessage);
+    return () => window.removeEventListener('message', handleMessage);
+  }, [connections, finishAuth]);
+
+  useEffect(() => {
+    for (const connection of connections) {
+      const popupWindow = pendingPopupsRef.current.get(connection.sessionId);
+      if (!popupWindow) {
+        continue;
+      }
+
+      if (connection.state === 'AUTHENTICATED') {
+        postPopupResult(popupWindow, {
+          sessionId: connection.sessionId,
+          success: true,
+        });
+        pendingPopupsRef.current.delete(connection.sessionId);
+        continue;
+      }
+
+      if (connection.state === 'FAILED') {
+        postPopupResult(popupWindow, {
+          sessionId: connection.sessionId,
+          success: false,
+          error: connection.error || 'Failed to complete authorization',
+        });
+        pendingPopupsRef.current.delete(connection.sessionId);
+      }
+    }
+  }, [connections]);
+}
+
+/**
+ * Default popup callback UI for popup-based OAuth flows.
+ *
+ * This component reads the OAuth `code` and `state/sessionId`, notifies the
+ * opener window, waits for success/failure, and closes the popup on success.
+ *
+ * It is intentionally optional: apps can replace it with their own callback
+ * page UI or skip popup auth entirely and call `finishAuth(sessionId, code)`
+ * from any callback route they control.
+ */
+export function McpOAuthCallbackContent({
+  code,
+  sessionId,
+  title = 'Verifying Authorization',
+  initialStatus = 'Completing your authorization...',
+  loadingFallback = 'Loading...',
+  rootStyle,
+  cardStyle,
+  titleStyle,
+  messageStyle,
+  renderContainer,
+  debugPhase,
+}: McpOAuthCallbackContentProps): JSX.Element {
+  const [phase, setPhase] = useState<'loading' | 'success' | 'error'>(debugPhase || 'loading');
+  const [errorMessage, setErrorMessage] = useState('');
+
+  const openerMissing = typeof window !== 'undefined' ? !window.opener : false;
+  const missingCode = !code;
+  const missingSessionId = !sessionId;
+  const blockingError = openerMissing
+    ? 'Error: No opener window found. This window should be opened from the app.'
+    : missingCode
+      ? 'Error: No authorization code received.'
+      : missingSessionId
+        ? 'Error: No OAuth state received.'
+        : null;
+
+  useEffect(() => {
+    if (debugPhase) {
+      setPhase(debugPhase);
+      if (debugPhase === 'error') setErrorMessage('Test error message representing a real failure.');
+      return;
+    }
+
+    if (blockingError) {
+      setPhase('error');
+      setErrorMessage(blockingError);
+      return;
+    }
+
+    let closed = false;
+
+    const handleResult = (event: MessageEvent) => {
+      if (event.origin !== window.location.origin) {
+        return;
+      }
+
+      if (event.data?.type !== AUTH_RESULT_MESSAGE) {
+        return;
+      }
+
+      if (event.data.sessionId !== sessionId) {
+        return;
+      }
+
+      if (event.data.success) {
+        setPhase('success');
+        window.removeEventListener('message', handleResult);
+        closed = true;
+        window.setTimeout(() => window.close(), 1200);
+        return;
+      }
+
+      const message =
+        typeof event.data.error === 'string' && event.data.error.length > 0
+          ? event.data.error
+          : 'Failed to complete authorization.';
+      setPhase('error');
+      setErrorMessage(message);
+    };
+
+    window.addEventListener('message', handleResult);
+
+    try {
+      window.opener.postMessage(
+        { type: AUTH_CODE_MESSAGE, code, sessionId },
+        window.location.origin
+      );
+    } catch (error) {
+      console.error('Failed to communicate with opener:', error);
+      window.setTimeout(() => {
+        setPhase('error');
+        setErrorMessage('Error: Could not communicate with main window.');
+      }, 0);
+    }
+
+    return () => {
+      if (!closed) {
+        window.removeEventListener('message', handleResult);
+      }
+    };
+  }, [blockingError, code, sessionId, debugPhase]);
+
+  const loadingBubbles = (
+    <div style={{ display: 'flex', gap: '8px', justifyContent: 'center', height: '12px', alignItems: 'center' }}>
+      {[0, 150, 300].map((delay) => (
+        <span
+          key={delay}
+          style={{
+            width: '8px',
+            height: '8px',
+            borderRadius: '50%',
+            backgroundColor: 'currentColor',
+            opacity: 0.3,
+            animation: `mcp-pulse 1.2s ease-in-out infinite`,
+            animationDelay: `${delay}ms`,
+          }}
+        />
+      ))}
+    </div>
+  );
+
+  const content = (
+    <div
+      style={{
+        display: 'flex',
+        justifyContent: 'center',
+        alignItems: 'center',
+        minHeight: '100vh',
+        fontFamily: 'system-ui, -apple-system, sans-serif',
+        flexDirection: 'column',
+        backgroundColor: '#fafafa',
+        color: '#18181b',
+        boxSizing: 'border-box',
+        padding: '1.5rem',
+        ...rootStyle,
+      }}
+    >
+      <style>
+        {`
+          @keyframes mcp-pulse { 0%, 100% { transform: scale(0.8); opacity: 0.4; } 50% { transform: scale(1.2); opacity: 1; } }
+          @keyframes mcp-fade-up { from { opacity: 0; transform: translateY(10px); } to { opacity: 1; transform: translateY(0); } }
+        `}
+      </style>
+      <div
+        style={{
+          backgroundColor: '#fff',
+          borderRadius: '20px',
+          boxShadow: '0 20px 25px -5px rgba(0, 0, 0, 0.05), 0 8px 10px -6px rgba(0, 0, 0, 0.05)',
+          width: '100%',
+          maxWidth: '400px',
+          overflow: 'hidden',
+          border: '1px solid #f4f4f5',
+          display: 'flex',
+          flexDirection: 'column',
+          ...cardStyle,
+        }}
+      >
+        <div style={{ padding: '3rem 2rem', textAlign: 'center', animation: 'mcp-fade-up 0.4s ease-out' }}>
+          {phase === 'loading' && (
+            <div style={{ display: 'flex', flexDirection: 'column', gap: '1.5rem', alignItems: 'center' }}>
+              <div style={{ display: 'flex', alignItems: 'center', justifyContent: 'center', height: '48px', width: '48px', background: '#f8fafc', borderRadius: '12px', border: '1px solid #f1f5f9', color: '#64748b' }}>
+                <svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" strokeLinejoin="round">
+                  <path d="M12 22s8-4 8-10V5l-8-3-8 3v7c0 6 8 10 8 10z" />
+                </svg>
+              </div>
+              <div style={{ display: 'flex', flexDirection: 'column', gap: '0.5rem' }}>
+                <h2 style={{ margin: 0, fontSize: '1.125rem', fontWeight: 600, ...titleStyle }}>{title}</h2>
+                <p style={{ margin: 0, fontSize: '0.9rem', color: '#71717a', lineHeight: 1.5, ...messageStyle }}>
+                  {initialStatus}
+                </p>
+              </div>
+              {loadingBubbles}
+            </div>
+          )}
+
+          {phase === 'success' && (
+            <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem', alignItems: 'center' }}>
+              <svg style={{ color: '#10b981' }} width="48" height="48" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round">
+                <circle cx="12" cy="12" r="10" />
+                <path d="M8 12l3 3 5-5" />
+              </svg>
+              <h2 style={{ margin: 0, fontSize: '1.25rem', fontWeight: 600, ...titleStyle }}>Connected</h2>
+              <p style={{ margin: 0, fontSize: '0.9rem', color: '#71717a', lineHeight: 1.5, ...messageStyle }}>
+                Authorization complete. This window will close automatically.
+              </p>
+            </div>
+          )}
+
+          {phase === 'error' && (
+            <div style={{ display: 'flex', flexDirection: 'column', gap: '1rem', alignItems: 'center' }}>
+              <svg style={{ color: '#ef4444' }} width="48" height="48" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2.5" strokeLinecap="round" strokeLinejoin="round">
+                <circle cx="12" cy="12" r="10" />
+                <path d="M15 9l-6 6M9 9l6 6" />
+              </svg>
+              <h2 style={{ margin: 0, fontSize: '1.25rem', fontWeight: 600, ...titleStyle }}>Connection Failed</h2>
+              <p style={{ margin: 0, fontSize: '0.9rem', color: '#ef4444', fontWeight: 500, ...messageStyle }}>
+                {errorMessage}
+              </p>
+              <button
+                onClick={() => window.close()}
+                style={{
+                  marginTop: '0.5rem', padding: '0.625rem 1.25rem', border: 'none', borderRadius: '8px',
+                  backgroundColor: '#fef2f2', color: '#ef4444', cursor: 'pointer', fontWeight: 600, fontSize: '0.875rem'
+                }}
+              >
+                Close Window
+              </button>
+            </div>
+          )}
+        </div>
+      </div>
+    </div>
+  );
+
+  if (renderContainer) {
+    return <>{renderContainer(content)}</>;
+  }
+
+  return content;
+}
+
+/**
+ * Tiny fallback component for Suspense-wrapped callback pages.
+ */
+export function McpOAuthCallbackFallback({
+  children = 'Loading...',
+}: {
+  children?: ReactNode;
+}): JSX.Element {
+  return <>{children || 'Loading...'}</>;
+}

package/src/client/react/use-mcp.ts

@@ -290,17 +290,48 @@ export function useMcp(options: UseMcpOptions): McpClient {
       state === 'CONNECTED' ||
       state === 'DISCOVERING';
 
+    const getVisibleState = (
+      incomingState: McpConnectionState,
+      existingState?: McpConnectionState,
+      previousState?: McpConnectionState
+    ): McpConnectionState => {
+      // `INITIALIZING` has two meanings in practice:
+      // 1. genuine cold start / reconnect work
+      // 2. an internal setup step that happens mid-OAuth completion
+      //
+      // For case (2), showing raw `INITIALIZING` creates a confusing user-facing
+      // sequence like AUTHENTICATING -> INITIALIZING -> AUTHENTICATED.
+      // We keep the raw event stream intact for observability, but collapse the
+      // visible state back into the current auth phase in the UI.
+      if (
+        incomingState === 'INITIALIZING' &&
+        (existingState === 'AUTHENTICATING' ||
+          existingState === 'AUTHENTICATED' ||
+          previousState === 'AUTHENTICATING' ||
+          previousState === 'AUTHENTICATED')
+      ) {
+        return existingState === 'AUTHENTICATED' || previousState === 'AUTHENTICATED'
+          ? 'AUTHENTICATED'
+          : 'AUTHENTICATING';
+      }
+
+      return incomingState;
+    };
+
     setConnections((prev: McpConnection[]) => {
       switch (event.type) {
         case 'state_changed': {
           const existing = prev.find((c: McpConnection) => c.sessionId === event.sessionId);
           if (existing) {
+            // Normalize the incoming backend state into the smoother user-facing
+            // state we want to render for this existing connection.
+            const normalizedState = getVisibleState(event.state, existing.state, event.previousState);
             // In stateless per-request transport, tool calls can emit transient reconnect states.
             // Keep READY sticky to avoid UI flicker from READY -> CONNECTING -> CONNECTED.
             const nextState =
-              existing.state === 'READY' && isTransientReconnectState(event.state)
+              existing.state === 'READY' && isTransientReconnectState(normalizedState)
                 ? existing.state
-                : event.state;
+                : normalizedState;
 
             return prev.map((c: McpConnection) =>
               c.sessionId === event.sessionId ? {
@@ -323,7 +354,9 @@ export function useMcp(options: UseMcpOptions): McpClient {
                 serverId: event.serverId,
                 serverName: event.serverName,
                 serverUrl: event.serverUrl,
-                state: event.state,
+                // New connections do not have prior local state, so we normalize
+                // only against the server-reported previous state.
+                state: getVisibleState(event.state, undefined, event.previousState),
                 createdAt: event.createdAt ? new Date(event.createdAt) : undefined,
                 tools: [],
               },

package/src/client/vue/use-mcp.ts

@@ -240,16 +240,49 @@ export function useMcp(options: UseMcpOptions): McpClient {
             state === 'CONNECTED' ||
             state === 'DISCOVERING';
 
+        const getVisibleState = (
+            incomingState: McpConnectionState,
+            existingState?: McpConnectionState,
+            previousState?: McpConnectionState
+        ): McpConnectionState => {
+            // `INITIALIZING` has two meanings in practice:
+            // 1. genuine cold start / reconnect work
+            // 2. an internal setup step that happens mid-OAuth completion
+            //
+            // For case (2), showing raw `INITIALIZING` creates a confusing user-facing
+            // sequence like AUTHENTICATING -> INITIALIZING -> AUTHENTICATED.
+            // We keep the raw event stream intact for observability, but collapse the
+            // visible state back into the current auth phase in the UI.
+            if (
+                incomingState === 'INITIALIZING' &&
+                (
+                    existingState === 'AUTHENTICATING' ||
+                    existingState === 'AUTHENTICATED' ||
+                    previousState === 'AUTHENTICATING' ||
+                    previousState === 'AUTHENTICATED'
+                )
+            ) {
+                return existingState === 'AUTHENTICATED' || previousState === 'AUTHENTICATED'
+                    ? 'AUTHENTICATED'
+                    : 'AUTHENTICATING';
+            }
+
+            return incomingState;
+        };
+
         switch (event.type) {
             case 'state_changed': {
                 const existing = connections.value.find((c) => c.sessionId === event.sessionId);
                 if (existing) {
+                    // Normalize the incoming backend state into the smoother user-facing
+                    // state we want to render for this existing connection.
+                    const normalizedState = getVisibleState(event.state, existing.state, event.previousState);
                     // In stateless per-request transport, tool calls can emit transient reconnect states.
                     // Keep READY sticky to avoid UI flicker from READY -> CONNECTING -> CONNECTED.
                     const nextState =
-                        existing.state === 'READY' && isTransientReconnectState(event.state)
+                        existing.state === 'READY' && isTransientReconnectState(normalizedState)
                             ? existing.state
-                            : event.state;
+                            : normalizedState;
 
                     const index = connections.value.indexOf(existing);
                     connections.value[index] = {
@@ -268,7 +301,9 @@ export function useMcp(options: UseMcpOptions): McpClient {
                         sessionId: event.sessionId,
                         serverId: event.serverId,
                         serverName: event.serverName,
-                        state: event.state,
+                        // New connections do not have prior local state, so we normalize
+                        // only against the server-reported previous state.
+                        state: getVisibleState(event.state, undefined, event.previousState),
                         createdAt: event.createdAt ? new Date(event.createdAt) : undefined,
                         tools: [],
                     }];

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

@@ -363,9 +363,24 @@ export class SSEConnectionManager {
       return existing;
     }
 
+    const session = await storage.getSession(this.identity, sessionId);
+    if (!session) {
+      throw new Error('Session not found');
+    }
+
     const client = new MCPClient({
       identity: this.identity,
       sessionId,
+      // These fields are optional in MCPClient, but when rehydrating a known
+      // stored session on the server we pass them explicitly to preserve the
+      // original transport/connection metadata instead of relying on lazy
+      // reloading during initialize().
+      serverId: session.serverId,
+      serverName: session.serverName,
+      serverUrl: session.serverUrl,
+      callbackUrl: session.callbackUrl,
+      transportType: session.transportType,
+      headers: session.headers,
     });
 
     // Subscribe to events before connecting
@@ -437,6 +452,16 @@ export class SSEConnectionManager {
       const client = new MCPClient({
         identity: this.identity,
         sessionId,
+        // These fields are optional in MCPClient, but when rehydrating a known
+        // stored session on the server we pass them explicitly to preserve the
+        // original transport/connection metadata instead of relying on lazy
+        // reloading during initialize().
+        serverId: session.serverId,
+        serverName: session.serverName,
+        serverUrl: session.serverUrl,
+        callbackUrl: session.callbackUrl,
+        transportType: session.transportType,
+        headers: session.headers,
         ...clientMetadata,
       });
 
@@ -478,6 +503,20 @@ export class SSEConnectionManager {
       const client = new MCPClient({
         identity: this.identity,
         sessionId,
+        // These fields are optional in MCPClient, but when rehydrating a known
+        // stored session on the server we pass them explicitly to preserve the
+        // original connection metadata instead of relying on lazy
+        // reloading during initialize().
+        serverId: session.serverId,
+        serverName: session.serverName,
+        serverUrl: session.serverUrl,
+        callbackUrl: session.callbackUrl,
+        // NOTE: transportType is intentionally omitted here.
+        // The session's stored transportType is a placeholder ('streamable_http')
+        // set before transport negotiation. Omitting it lets MCPClient auto-negotiate
+        // (try streamable_http → SSE fallback), which is critical for servers like
+        // Neon that only support SSE transport.
+        headers: session.headers,
       });
 
       client.onConnectionEvent((event) => this.emitConnectionEvent(event));