@mcp-ts/sdk 1.5.0 → 1.5.2

package/src/adapters/ai-adapter.ts

@@ -137,11 +137,11 @@ export class AIAdapter {
         // @ts-ignore: ToolSet type inference can be tricky with dynamic imports
         return Object.fromEntries(
             filteredTools.map((tool) => {
-                const routedTool = tool as typeof tool & { sessionId?: string; serverName?: string };
-                const namespace = routedTool.serverName ?? routedTool.sessionId;
+                const routedTool = tool as typeof tool & { sessionId?: string; serverId?: string; serverName?: string };
+                const namespace = routedTool.serverId ?? routedTool.sessionId;
                 const toolKey = isMetaTool(tool.name)
                     ? tool.name
-                    : this.getRouterToolKey(tool.name, routedTool.sessionId, routedTool.serverName);
+                    : this.getRouterToolKey(tool.name, routedTool.sessionId, routedTool.serverId);
 
                 return [
                     toolKey,
@@ -172,8 +172,8 @@ export class AIAdapter {
         );
     }
 
-    private getRouterToolKey(toolName: string, sessionId?: string, serverName?: string): string {
-        const namespace = sessionId ?? serverName ?? 'mcp';
+    private getRouterToolKey(toolName: string, sessionId?: string, serverId?: string): string {
+        const namespace = sessionId ?? serverId ?? 'mcp';
         const normalized = namespace
             .toLowerCase()
             .replace(/[^a-z0-9]+/g, '_')

package/src/adapters/langchain-adapter.ts

@@ -144,14 +144,14 @@ export class LangChainAdapter {
         const filteredTools = await router.getFilteredTools();
 
         return filteredTools.map((tool) => {
-            const routedTool = tool as typeof tool & { sessionId?: string; serverName?: string };
-            const namespace = routedTool.serverName ?? routedTool.sessionId;
+            const routedTool = tool as typeof tool & { sessionId?: string; serverId?: string; serverName?: string };
+            const namespace = routedTool.serverId ?? routedTool.sessionId;
             const schema = this.jsonSchemaToZod(tool.inputSchema);
 
             return new this.DynamicStructuredTool!({
                 name: isMetaTool(tool.name)
                     ? tool.name
-                    : this.getRouterToolKey(tool.name, routedTool.sessionId, routedTool.serverName),
+                    : this.getRouterToolKey(tool.name, routedTool.sessionId, routedTool.serverId),
                 description: tool.description || `Tool ${tool.name}`,
                 schema: schema,
                 func: async (args: any) => {
@@ -183,8 +183,8 @@ export class LangChainAdapter {
         });
     }
 
-    private getRouterToolKey(toolName: string, sessionId?: string, serverName?: string): string {
-        const namespace = sessionId ?? serverName ?? 'mcp';
+    private getRouterToolKey(toolName: string, sessionId?: string, serverId?: string): string {
+        const namespace = sessionId ?? serverId ?? 'mcp';
         const normalized = namespace
             .toLowerCase()
             .replace(/[^a-z0-9]+/g, '_')

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

@@ -118,6 +118,17 @@ export interface McpClient {
    */
   disconnect: (sessionId: string) => Promise<void>;
 
+  /**
+   * Reconnect to an MCP server (disconnects existing session first)
+   */
+  reconnect: (params: {
+    serverId: string;
+    serverName: string;
+    serverUrl: string;
+    callbackUrl: string;
+    transportType?: 'sse' | 'streamable_http';
+  }) => Promise<string>;
+
   /**
    * Get connection by session ID
    */
@@ -290,17 +301,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 +365,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: [],
               },
@@ -466,6 +510,41 @@ export function useMcp(options: UseMcpOptions): McpClient {
     []
   );
 
+  /**
+   * Reconnect to an MCP server (tears down existing session, then connects fresh)
+   */
+  const reconnect = useCallback(
+    async (params: {
+      serverId: string;
+      serverName: string;
+      serverUrl: string;
+      callbackUrl: string;
+      transportType?: 'sse' | 'streamable_http';
+    }): Promise<string> => {
+      if (!clientRef.current) {
+        throw new Error('SSE client not initialized');
+      }
+
+      // Find and disconnect existing session for the same server
+      const existing = connections.find(
+        (c: McpConnection) => c.serverId === params.serverId || c.serverUrl === params.serverUrl
+      );
+      if (existing) {
+        await clientRef.current.disconnectFromServer(existing.sessionId);
+        if (isMountedRef.current) {
+          setConnections((prev: McpConnection[]) =>
+            prev.filter((c: McpConnection) => c.sessionId !== existing.sessionId)
+          );
+        }
+      }
+
+      // Connect fresh
+      const result = await clientRef.current.connectToServer(params);
+      return result.sessionId;
+    },
+    [connections]
+  );
+
   /**
    * Disconnect from an MCP server
    */
@@ -635,6 +714,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
       status,
       isInitializing,
       connect,
+      reconnect,
       disconnect,
       getConnection,
       getConnectionByServerId,
@@ -658,6 +738,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
       status,
       isInitializing,
       connect,
+      reconnect,
       disconnect,
       getConnection,
       getConnectionByServerId,