@mcp-ts/sdk 1.6.1 → 2.0.0

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@mcp-ts/sdk",
-  "version": "1.6.1",
+  "version": "2.0.0",
   "publishConfig": {
     "access": "public"
   },
-  "description": "A lightweight MCP (Model Context Protocol) client library for JavaScript and cross-runtime environments, supporting MCP Apps in host applications and multiple storage backends (Memory, File, Redis, Supabase).",
+  "description": "A lightweight MCP (Model Context Protocol) client library for JavaScript and cross-runtime environments, supporting MCP Apps in host applications and multiple storage backends (Memory, File, Redis, Supabase, Neon).",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
@@ -71,7 +71,7 @@
   "files": [
     "dist",
     "src",
-    "supabase",
+    "migrations",
     "README.md",
     "LICENSE"
   ],
@@ -117,13 +117,15 @@
   "peerDependencies": {
     "@ag-ui/client": ">=0.0.40",
     "@langchain/core": "^1.1.39",
+    "@neondatabase/serverless": "^1.1.0",
     "@supabase/supabase-js": "^2.0.0",
     "ai": "^6.0.0",
     "better-sqlite3": "^12.0.0",
     "ioredis": "^5.0.0",
     "react": ">=18.0.0",
     "rxjs": ">=7.0.0",
-    "zod": "^3.23.0"
+    "zod": "^3.23.0",
+    "json-schema-to-zod": "^2.7.0"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -135,6 +137,9 @@
     "@langchain/core": {
       "optional": true
     },
+    "@neondatabase/serverless": {
+      "optional": true
+    },
     "zod": {
       "optional": true
     },
@@ -152,18 +157,21 @@
     },
     "@supabase/supabase-js": {
       "optional": true
+    },
+    "json-schema-to-zod": {
+      "optional": true
     }
   },
   "dependencies": {
     "@modelcontextprotocol/ext-apps": "^1.5.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "json-schema": "^0.4.0",
-    "json-schema-to-zod": "^2.7.0",
     "nanoid": "^5.1.6"
   },
   "devDependencies": {
     "@ag-ui/client": "^0.0.52",
     "@langchain/core": "^1.1.39",
+    "@neondatabase/serverless": "^1.1.0",
     "@playwright/test": "^1.58.0",
     "@supabase/supabase-js": "^2.48.0",
     "@types/better-sqlite3": "^7.6.13",
@@ -175,6 +183,7 @@
     "better-sqlite3": "^12.6.2",
     "ioredis": "^5.9.2",
     "ioredis-mock": "^8.13.1",
+    "json-schema-to-zod": "^2.7.0",
     "playwright": "^1.58.0",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",

package/src/adapters/ai-adapter.ts

@@ -22,6 +22,13 @@ export interface AIAdapterOptions {
      * When not provided, all tools are returned as before (backward-compatible).
      */
     toolRouter?: ToolRouter;
+
+    /**
+     * Optional custom callback to determine if a tool requires user approval.
+     * Can return a boolean or a Promise<boolean>.
+     * If not provided, defaults to checking the tool's `destructiveHint` annotation.
+     */
+    needsApproval?: (tool: any, args: any) => boolean | Promise<boolean>;
 }
 
 /**
@@ -80,7 +87,12 @@ export class AIAdapter {
                                 const errorMessage = error instanceof Error ? error.message : String(error);
                                 throw new Error(`Tool execution failed: ${errorMessage}`);
                             }
-                        }
+                        },
+                        needsApproval: this.options.needsApproval
+                            ? (args: any) => this.options.needsApproval!(tool, args)
+                            : (tool.annotations as any)?.destructiveHint === true
+                                ? () => true
+                                : undefined
                     }
                 ];
             })
@@ -166,6 +178,23 @@ export class AIAdapter {
                             // route directly to the correct MCP client
                             return await router.callTool(tool.name, args, namespace);
                         },
+                        needsApproval: this.options.needsApproval
+                            ? (args: any) => this.options.needsApproval!(tool, args)
+                            : (args: any) => {
+                                // Default HITL logic using annotations
+                                if (tool.name === 'mcp_execute_tool') {
+                                    const targetToolName = String(args?.toolName ?? "");
+                                    const targetNamespace = String(args?.serverId ?? "") || undefined;
+                                    if (!targetToolName) return false;
+                                    try {
+                                        const targetTool = router.getToolSchema(targetToolName, targetNamespace);
+                                        return (targetTool as any)?.annotations?.destructiveHint === true;
+                                    } catch {
+                                        return false;
+                                    }
+                                }
+                                return (tool.annotations as any)?.destructiveHint === true;
+                            }
                     },
                 ];
             })

package/src/adapters/langchain-adapter.ts

@@ -96,9 +96,13 @@ export class LangChainAdapter {
             const zodSchemaString = parseSchema(schema);
             // eslint-disable-next-line
             return new Function('z', 'return ' + zodSchemaString)(this.z);
-        } catch (error) {
+        } catch (error: any) {
             // Fallback: Accept any object if conversion fails
-            console.warn('[LangChainAdapter] Failed to convert JSON Schema to Zod, using fallback:', error);
+            if (error.code === 'MODULE_NOT_FOUND') {
+                console.warn('[LangChainAdapter] json-schema-to-zod is not installed. To improve type checking, install it with: npm install json-schema-to-zod');
+            } else {
+                console.warn('[LangChainAdapter] Failed to convert JSON Schema to Zod, using fallback:', error);
+            }
             return this.z!.record(this.z!.any()).optional().describe("Dynamic Input");
         }
     }

package/src/adapters/mastra-adapter.ts

@@ -87,9 +87,13 @@ export class MastraAdapter {
             const zodSchemaString = parseSchema(schema);
             // eslint-disable-next-line
             return new Function('z', 'return ' + zodSchemaString)(this.z);
-        } catch (error) {
+        } catch (error: any) {
             // Fallback: Accept any object if conversion fails
-            console.warn('[MastraAdapter] Failed to convert JSON Schema to Zod, using fallback:', error);
+            if (error.code === 'MODULE_NOT_FOUND') {
+                console.warn('[MastraAdapter] json-schema-to-zod is not installed. To improve type checking, install it with: npm install json-schema-to-zod');
+            } else {
+                console.warn('[MastraAdapter] Failed to convert JSON Schema to Zod, using fallback:', error);
+            }
             return this.z!.record(this.z!.any()).optional().describe("Dynamic Input");
         }
     }

package/src/bin/mcp-ts.ts

@@ -35,7 +35,10 @@ async function initSupabase() {
     // The supabase/ migrations are at the root of the package.
     // We need to look up two levels to find 'supabase' folder in the package.
     const pkgRoot = path.resolve(__dirname, '../..');
-    const sourceDir = path.join(pkgRoot, 'supabase', 'migrations');
+    const sourceDir = resolveFirstExistingPath([
+        path.join(pkgRoot, 'migrations', 'supabase'),
+        path.join(pkgRoot, 'supabase', 'migrations'),
+    ]);
     
     if (!fs.existsSync(sourceDir)) {
         console.error(`❌ Error: Could not find migration files in package at: ${sourceDir}`);
@@ -96,6 +99,10 @@ async function initSupabase() {
     }
 }
 
+function resolveFirstExistingPath(paths: string[]): string {
+    return paths.find(candidate => fs.existsSync(candidate)) || paths[0];
+}
+
 run().catch(err => {
     console.error(err);
     process.exit(1);

package/src/client/core/app-host.ts

@@ -559,7 +559,7 @@ export class AppHost {
   private async getSessionId(): Promise<string | undefined> {
     if (this.sessionId) return this.sessionId;
     if (!this.client) return undefined;
-    const result = await this.client.getSessions();
+    const result = await this.client.listSessions();
     return result.sessions?.[0]?.sessionId;
   }
 

package/src/client/core/sse-client.ts

@@ -20,7 +20,7 @@ import type {
   SessionListResult,
   ConnectResult,
   DisconnectResult,
-  RestoreSessionResult,
+  GetSessionResult,
   FinishAuthResult,
   ListToolsRpcResult,
   ListPromptsResult,
@@ -32,7 +32,7 @@ export interface SSEClientOptions {
   url: string;
 
   /** User/Client identifier */
-  identity: string;
+  userId: string;
 
   /** Optional auth token for authenticated requests */
   authToken?: string;
@@ -87,8 +87,8 @@ export class SSEClient {
     return this.connected;
   }
 
-  async getSessions(): Promise<SessionListResult> {
-    return this.sendRequest<SessionListResult>('getSessions');
+  async listSessions(): Promise<SessionListResult> {
+    return this.sendRequest<SessionListResult>('listSessions');
   }
 
   async connectToServer(params: ConnectParams): Promise<ConnectResult> {
@@ -113,8 +113,8 @@ export class SSEClient {
     return result;
   }
 
-  async restoreSession(sessionId: string): Promise<RestoreSessionResult> {
-    return this.sendRequest<RestoreSessionResult>('restoreSession', { sessionId });
+  async getSession(sessionId: string): Promise<GetSessionResult> {
+    return this.sendRequest<GetSessionResult>('getSession', { sessionId });
   }
 
   async finishAuth(sessionId: string, code: string): Promise<FinishAuthResult> {
@@ -198,7 +198,7 @@ export class SSEClient {
     const data = await this.readRpcResponseFromStream(response, {
       delayConnectionEvents:
         method === 'connect' ||
-        method === 'restoreSession' ||
+        method === 'getSession' ||
         method === 'finishAuth',
     });
     return this.parseRpcResponse<T>(data);
@@ -311,22 +311,20 @@ export class SSEClient {
   }
 
   private buildUrl(): string {
-    const url = new URL(this.options.url, globalThis.location?.origin);
-    url.searchParams.set('identity', this.options.identity);
-    if (this.options.authToken) {
-      url.searchParams.set('token', this.options.authToken);
-    }
-    return url.toString();
+    return new URL(this.options.url, globalThis.location?.origin).toString();
   }
 
   private buildHeaders(): HeadersInit {
-    const headers: HeadersInit = {
+    const headers: Record<string, string> = {
       'Content-Type': 'application/json',
       'Accept': 'text/event-stream',
+      'x-mcp-user-id': this.options.userId,
     };
+
     if (this.options.authToken) {
       headers['Authorization'] = `Bearer ${this.options.authToken}`;
     }
+    
     return headers;
   }
 

package/src/client/core/types.ts

@@ -17,7 +17,7 @@ export interface AppHostClient {
     /**
      * Get list of active sessions
      */
-    getSessions(): Promise<SessionListResult>;
+    listSessions(): Promise<SessionListResult>;
 
     /**
      * Call a tool on a specific session

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

@@ -42,6 +42,19 @@ export interface McpOAuthCallbackContentProps {
 
 const AUTH_CODE_MESSAGE = 'MCP_AUTH_CODE';
 const AUTH_RESULT_MESSAGE = 'MCP_AUTH_RESULT';
+const AUTH_CHANNEL_NAME = 'mcp-auth-channel';
+
+function createAuthBroadcastChannel(): BroadcastChannel | null {
+  if (typeof BroadcastChannel === 'undefined') {
+    return null;
+  }
+
+  try {
+    return new BroadcastChannel(AUTH_CHANNEL_NAME);
+  } catch {
+    return null;
+  }
+}
 
 function postPopupResult(
   popupWindow: WindowProxy | null,
@@ -51,13 +64,23 @@ function postPopupResult(
     error?: string;
   }
 ): void {
-  popupWindow?.postMessage(
-    {
-      type: AUTH_RESULT_MESSAGE,
-      ...result,
-    },
-    window.location.origin
-  );
+  const payload = {
+    type: AUTH_RESULT_MESSAGE,
+    ...result,
+  };
+
+  try {
+    popupWindow?.postMessage(payload, window.location.origin);
+  } catch {
+    // COOP can leave a WindowProxy reference that is no longer usable.
+    // The BroadcastChannel path below is the reliable fallback.
+  }
+
+  const channel = createAuthBroadcastChannel();
+  if (channel) {
+    channel.postMessage(payload);
+    channel.close();
+  }
 }
 
 /**
@@ -130,14 +153,16 @@ export function useMcpOAuthPopup<TConnection extends OAuthPopupConnectionLike>(
   finishAuth: (sessionId: string, code: string) => Promise<unknown>
 ): void {
   const pendingPopupsRef = useRef<Map<string, WindowProxy>>(new Map());
+  const processingCodesRef = useRef<Set<string>>(new Set());
 
   useEffect(() => {
     const handleMessage = async (event: MessageEvent) => {
-      if (event.origin !== window.location.origin) {
+      if (event.origin && event.origin !== window.location.origin) {
         return;
       }
 
-      if (event.data?.type !== AUTH_CODE_MESSAGE || !event.data.code) {
+      const code = typeof event.data?.code === 'string' ? event.data.code : '';
+      if (event.data?.type !== AUTH_CODE_MESSAGE || !code) {
         return;
       }
 
@@ -146,56 +171,84 @@ export function useMcpOAuthPopup<TConnection extends OAuthPopupConnectionLike>(
         : null;
       const targetSessionId = typeof event.data.sessionId === 'string' ? event.data.sessionId : '';
 
+      if (popupWindow && targetSessionId) {
+        pendingPopupsRef.current.set(targetSessionId, popupWindow);
+      }
+
       if (!targetSessionId) {
-        postPopupResult(popupWindow, {
-          success: false,
-          error: 'Missing OAuth session identifier',
-        });
+        if (popupWindow) {
+          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',
-        });
+        if (popupWindow) {
+          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);
+      const codeKey = `${targetSession.sessionId}:${code}`;
+      if (processingCodesRef.current.has(codeKey)) {
+        return;
       }
+      processingCodesRef.current.add(codeKey);
 
       try {
-        await finishAuth(targetSession.sessionId, event.data.code);
+        await finishAuth(targetSession.sessionId, code);
       } catch (error) {
+        processingCodesRef.current.delete(codeKey);
         pendingPopupsRef.current.delete(targetSession.sessionId);
-        postPopupResult(popupWindow, {
-          sessionId: targetSession.sessionId,
-          success: false,
-          error: error instanceof Error ? error.message : 'Failed to finish auth',
-        });
+        if (popupWindow) {
+          postPopupResult(popupWindow, {
+            sessionId: targetSession.sessionId,
+            success: false,
+            error: error instanceof Error ? error.message : 'Failed to finish auth',
+          });
+        }
+      }
+    };
+
+    const channel = createAuthBroadcastChannel();
+    const handleChannelMessage = (event: MessageEvent) => {
+      if (event.data?.type === AUTH_CODE_MESSAGE) {
+        void handleMessage(event);
       }
     };
 
     window.addEventListener('message', handleMessage);
-    return () => window.removeEventListener('message', handleMessage);
+    channel?.addEventListener('message', handleChannelMessage);
+    
+    return () => {
+      window.removeEventListener('message', handleMessage);
+      channel?.removeEventListener('message', handleChannelMessage);
+      channel?.close();
+    };
   }, [connections, finishAuth]);
 
   useEffect(() => {
     for (const connection of connections) {
-      const popupWindow = pendingPopupsRef.current.get(connection.sessionId);
-      if (!popupWindow) {
-        continue;
-      }
+      const popupWindow = pendingPopupsRef.current.get(connection.sessionId) || null;
 
-      if (connection.state === 'AUTHENTICATED') {
+      if (connection.state === 'AUTHENTICATED' || connection.state === 'READY' || connection.state === 'CONNECTED') {
         postPopupResult(popupWindow, {
           sessionId: connection.sessionId,
           success: true,
         });
+        for (const codeKey of processingCodesRef.current) {
+          if (codeKey.startsWith(`${connection.sessionId}:`)) {
+            processingCodesRef.current.delete(codeKey);
+          }
+        }
         pendingPopupsRef.current.delete(connection.sessionId);
         continue;
       }
@@ -206,6 +259,11 @@ export function useMcpOAuthPopup<TConnection extends OAuthPopupConnectionLike>(
           success: false,
           error: connection.error || 'Failed to complete authorization',
         });
+        for (const codeKey of processingCodesRef.current) {
+          if (codeKey.startsWith(`${connection.sessionId}:`)) {
+            processingCodesRef.current.delete(codeKey);
+          }
+        }
         pendingPopupsRef.current.delete(connection.sessionId);
       }
     }
@@ -238,16 +296,13 @@ export function McpOAuthCallbackContent({
   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;
+  const blockingError = missingCode
+    ? 'Error: No authorization code received.'
+    : missingSessionId
+      ? 'Error: No OAuth state received.'
+      : null;
 
   useEffect(() => {
     if (debugPhase) {
@@ -263,9 +318,9 @@ export function McpOAuthCallbackContent({
     }
 
     let closed = false;
-
+    const channel = createAuthBroadcastChannel();
     const handleResult = (event: MessageEvent) => {
-      if (event.origin !== window.location.origin) {
+      if (event.origin && event.origin !== window.location.origin) {
         return;
       }
 
@@ -280,6 +335,7 @@ export function McpOAuthCallbackContent({
       if (event.data.success) {
         setPhase('success');
         window.removeEventListener('message', handleResult);
+        channel?.close();
         closed = true;
         window.setTimeout(() => window.close(), 1200);
         return;
@@ -294,23 +350,27 @@ export function McpOAuthCallbackContent({
     };
 
     window.addEventListener('message', handleResult);
+    channel?.addEventListener('message', handleResult);
+
+    const payload = { type: AUTH_CODE_MESSAGE, code, sessionId };
 
-    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(() => {
+    if (window.opener) {
+      try {
+        window.opener.postMessage(payload, window.location.origin);
+      } catch {
         setPhase('error');
         setErrorMessage('Error: Could not communicate with main window.');
-      }, 0);
+      }
+    }
+
+    if (channel) {
+      channel.postMessage(payload);
     }
 
     return () => {
       if (!closed) {
         window.removeEventListener('message', handleResult);
+        channel?.close();
       }
     };
   }, [blockingError, code, sessionId, debugPhase]);

package/src/client/react/use-mcp-apps.tsx

@@ -72,7 +72,7 @@ export interface McpAppRendererProps extends Pick<UseAppHostOptions, 'sandbox' |
 
 type McpAppViewProps = McpAppRendererProps & {
   /**
-   * Ref avoids tying `McpAppRenderer` identity to `mcpClient`: when `connections` updates, `useMcp()` still
+   * Ref avoids tying `McpAppRenderer` userId to `mcpClient`: when `connections` updates, `useMcp()` still
    * returns a new object (correct for `useEffect` deps), but the iframe must not remount.
    */
   clientRef: MutableRefObject<McpClient | null>;

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

@@ -25,7 +25,7 @@ export interface UseMcpOptions {
   /**
    * User/Client identifier
    */
-  identity: string;
+  userId: string;
 
   /**
    * Optional auth token
@@ -110,7 +110,7 @@ export interface McpClient {
     serverName: string;
     serverUrl: string;
     callbackUrl: string;
-    transportType?: 'sse' | 'streamable_http';
+    transportType?: 'sse' | 'streamable-http';
   }) => Promise<string>;
 
   /**
@@ -126,7 +126,7 @@ export interface McpClient {
     serverName: string;
     serverUrl: string;
     callbackUrl: string;
-    transportType?: 'sse' | 'streamable_http';
+    transportType?: 'sse' | 'streamable-http';
   }) => Promise<string>;
 
   /**
@@ -220,7 +220,7 @@ export interface McpClient {
 export function useMcp(options: UseMcpOptions): McpClient {
   const {
     url,
-    identity,
+    userId,
     authToken,
     autoConnect = true,
     autoInitialize = true,
@@ -249,7 +249,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
 
     const clientOptions: SSEClientOptions = {
       url,
-      identity,
+      userId,
       authToken,
       onConnectionEvent: (event) => {
         // Update local state based on event
@@ -285,7 +285,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
       isMountedRef.current = false;
       client.disconnect();
     };
-  }, [url, identity, authToken, autoConnect, autoInitialize]);
+  }, [url, userId, authToken, autoConnect, autoInitialize]);
 
   /**
    * Update connections based on event
@@ -441,7 +441,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
     try {
       setIsInitializing(true);
 
-      const result = await clientRef.current.getSessions();
+      const result = await clientRef.current.listSessions();
       const sessions = result.sessions || [];
 
       // Initialize connections
@@ -470,7 +470,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
                 return;
               }
               suppressAuthRedirectSessionsRef.current.add(session.sessionId);
-              await clientRef.current.restoreSession(session.sessionId);
+              await clientRef.current.getSession(session.sessionId);
             } catch (error) {
               console.error(`[useMcp] Failed to validate session ${session.sessionId}:`, error);
             } finally {
@@ -498,7 +498,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
       serverName: string;
       serverUrl: string;
       callbackUrl: string;
-      transportType?: 'sse' | 'streamable_http';
+      transportType?: 'sse' | 'streamable-http';
     }): Promise<string> => {
       if (!clientRef.current) {
         throw new Error('SSE client not initialized');
@@ -519,7 +519,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
       serverName: string;
       serverUrl: string;
       callbackUrl: string;
-      transportType?: 'sse' | 'streamable_http';
+      transportType?: 'sse' | 'streamable-http';
     }): Promise<string> => {
       if (!clientRef.current) {
         throw new Error('SSE client not initialized');
@@ -602,7 +602,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
     }
     // Ensure this attempt is not suppressed as background restore.
     suppressAuthRedirectSessionsRef.current.delete(sessionId);
-    await clientRef.current.restoreSession(sessionId);
+    await clientRef.current.getSession(sessionId);
   }, []);
 
   /**