@mcp-ts/sdk 1.6.2 → 2.0.0

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@mcp-ts/sdk",
-  "version": "1.6.2",
+  "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/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);
   }, []);
 
   /**

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

@@ -25,7 +25,7 @@ export interface UseMcpOptions {
     /**
      * User/Client identifier
      */
-    identity: string;
+    userId: string;
 
     /**
      * Optional auth token
@@ -109,7 +109,7 @@ export interface McpClient {
         serverName: string;
         serverUrl: string;
         callbackUrl: string;
-        transportType?: 'sse' | 'streamable_http';
+        transportType?: 'sse' | 'streamable-http';
     }) => Promise<string>;
 
     /**
@@ -125,7 +125,7 @@ export interface McpClient {
         serverName: string;
         serverUrl: string;
         callbackUrl: string;
-        transportType?: 'sse' | 'streamable_http';
+        transportType?: 'sse' | 'streamable-http';
     }) => Promise<string>;
 
     /**
@@ -219,7 +219,7 @@ export interface McpClient {
 export function useMcp(options: UseMcpOptions): McpClient {
     const {
         url,
-        identity,
+        userId,
         authToken,
         autoConnect = true,
         autoInitialize = true,
@@ -386,7 +386,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
         try {
             isInitializing.value = true;
 
-            const result = await clientRef.value.getSessions();
+            const result = await clientRef.value.listSessions();
             const sessions = result.sessions || [];
 
             // Initialize connections
@@ -413,7 +413,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
                                 return;
                             }
                             suppressAuthRedirectSessions.value.add(session.sessionId);
-                            await clientRef.value.restoreSession(session.sessionId);
+                            await clientRef.value.getSession(session.sessionId);
                         } catch (error) {
                             console.error(`[useMcp] Failed to validate session ${session.sessionId}:`, error);
                         } finally {
@@ -443,7 +443,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
 
         const clientOptions: SSEClientOptions = {
             url,
-            identity,
+            userId,
             authToken,
             onConnectionEvent: (event) => {
                 // Update local state based on event
@@ -493,7 +493,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.value) {
             throw new Error('SSE client not initialized');
@@ -511,7 +511,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.value) {
             throw new Error('SSE client not initialized');
@@ -589,7 +589,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
             throw new Error('SSE client not initialized');
         }
         suppressAuthRedirectSessions.value.delete(sessionId);
-        await clientRef.value.restoreSession(sessionId);
+        await clientRef.value.getSession(sessionId);
     };
 
     /**

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

@@ -12,9 +12,9 @@ import type { McpRpcResponse } from '../../shared/types.js';
 
 export interface NextMcpHandlerOptions {
   /**
-   * Extract identity from request (default: from 'identity' query param)
+   * Extract userId from request (default: from 'userId' query param)
    */
-  getIdentity?: (request: Request) => string | null;
+  getUserId?: (request: Request) => string | null;
 
   /**
    * Extract auth token from request (default: from 'token' query param or Authorization header)
@@ -25,7 +25,7 @@ export interface NextMcpHandlerOptions {
    * Authenticate user and verify access (optional)
    * Return true if user is authenticated, false otherwise
    */
-  authenticate?: (identity: string, token: string | null) => Promise<boolean> | boolean;
+  authenticate?: (userId: string, token: string | null) => Promise<boolean> | boolean;
 
   /**
    * Heartbeat interval in milliseconds (default: 30000)
@@ -45,10 +45,13 @@ export interface NextMcpHandlerOptions {
 
 export function createNextMcpHandler(options: NextMcpHandlerOptions = {}) {
   const {
-    getIdentity = (request: Request) => new URL(request.url).searchParams.get('identity'),
+    getUserId = (request: Request) => request.headers.get('x-mcp-user-id'),
     getAuthToken = (request: Request) => {
-      const url = new URL(request.url);
-      return url.searchParams.get('token') || request.headers.get('authorization');
+      const authHeader = request.headers.get('authorization');
+      if (authHeader?.toLowerCase().startsWith('bearer ')) {
+        return authHeader.slice(7);
+      }
+      return authHeader;
     },
     authenticate = () => true,
     heartbeatInterval = 30000,
@@ -56,8 +59,8 @@ export function createNextMcpHandler(options: NextMcpHandlerOptions = {}) {
     getClientMetadata,
   } = options;
 
-  const toManagerOptions = (identity: string, resolvedClientMetadata?: ClientMetadata) => ({
-    identity,
+  const toManagerOptions = (userId: string, resolvedClientMetadata?: ClientMetadata) => ({
+    userId,
     heartbeatInterval,
     clientDefaults: resolvedClientMetadata,
   });
@@ -79,15 +82,15 @@ export function createNextMcpHandler(options: NextMcpHandlerOptions = {}) {
   }
 
   async function POST(request: Request): Promise<Response> {
-    const identity = getIdentity(request);
+    const userId = getUserId(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 });
+    if (!userId) {
+      return Response.json({ error: { code: 'MISSING_userId', message: 'Missing userId' } }, { status: 400 });
     }
 
-    const isAuthorized = await authenticate(identity, authToken);
+    const isAuthorized = await authenticate(userId, authToken);
     if (!isAuthorized) {
       return Response.json({ error: { code: 'UNAUTHORIZED', message: 'Unauthorized' } }, { status: 401 });
     }
@@ -113,7 +116,7 @@ export function createNextMcpHandler(options: NextMcpHandlerOptions = {}) {
 
       if (!acceptsEventStream) {
         const manager = new SSEConnectionManager(
-          toManagerOptions(identity, resolvedClientMetadata),
+          toManagerOptions(userId, resolvedClientMetadata),
           () => { }
         );
         try {
@@ -138,7 +141,7 @@ export function createNextMcpHandler(options: NextMcpHandlerOptions = {}) {
       };
 
       const manager = new SSEConnectionManager(
-        toManagerOptions(identity, resolvedClientMetadata),
+        toManagerOptions(userId, resolvedClientMetadata),
         (event: McpConnectionEvent | McpObservabilityEvent | McpRpcResponse) => {
           if (isRpcResponseEvent(event)) {
             sendSSE('rpc-response', event);
@@ -183,7 +186,7 @@ export function createNextMcpHandler(options: NextMcpHandlerOptions = {}) {
     } catch (error) {
       const err = error instanceof Error ? error : new Error('Unknown error');
       console.error('[MCP Next Handler] Failed to handle RPC', {
-        identity,
+        userId,
         message: err.message,
         stack: err.stack,
         rawBody: rawBody.slice(0, 500),