@mcp-ts/sdk 1.6.1 → 2.0.0

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),

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

@@ -26,7 +26,7 @@ import type {
   SessionListResult,
   ConnectResult,
   DisconnectResult,
-  RestoreSessionResult,
+  GetSessionResult,
   FinishAuthResult,
   ListToolsRpcResult,
   ListPromptsResult,
@@ -37,7 +37,7 @@ import { RpcErrorCodes } from '../../shared/errors.js';
 import { UnauthorizedError } from '../../shared/errors.js';
 import { isConnectionEvent, isRpcResponseEvent } from '../../shared/event-routing.js';
 import { MCPClient } from '../mcp/oauth-client.js';
-import { storage } from '../storage/index.js';
+import { sessions } from '../storage/index.js';
 
 // ============================================
 // Types & Interfaces
@@ -52,10 +52,10 @@ export interface ClientMetadata {
 
 export interface SSEHandlerOptions {
   /** User/Client identifier */
-  identity: string;
+  userId: string;
 
   /** Optional callback for authentication/authorization */
-  onAuth?: (identity: string) => Promise<boolean>;
+  onAuth?: (userId: string) => Promise<boolean>;
 
   /** Heartbeat interval in milliseconds @default 30000 */
   heartbeatInterval?: number;
@@ -92,7 +92,7 @@ function normalizeHeaders(headers?: Record<string, string>): Record<string, stri
  * Each instance corresponds to one connected browser client.
  */
 export class SSEConnectionManager {
-  private readonly identity: string;
+  private readonly userId: string;
   private readonly clients = new Map<string, MCPClient>();
   private heartbeatTimer?: NodeJS.Timeout;
   private isActive = true;
@@ -101,7 +101,7 @@ export class SSEConnectionManager {
     private readonly options: SSEHandlerOptions,
     private readonly sendEvent: (event: McpConnectionEvent | McpObservabilityEvent | McpRpcResponse) => void
   ) {
-    this.identity = options.identity;
+    this.userId = options.userId;
     this.startHeartbeat();
   }
 
@@ -148,11 +148,11 @@ export class SSEConnectionManager {
    */
   async handleRequest(request: McpRpcRequest): Promise<McpRpcResponse> {
     try {
-      let result: SessionListResult | ConnectResult | DisconnectResult | RestoreSessionResult | FinishAuthResult | ListToolsRpcResult | ListPromptsResult | ListResourcesResult | unknown;
+      let result: SessionListResult | ConnectResult | DisconnectResult | GetSessionResult | FinishAuthResult | ListToolsRpcResult | ListPromptsResult | ListResourcesResult | unknown;
 
       switch (request.method) {
-        case 'getSessions':
-          result = await this.getSessions();
+        case 'listSessions':
+          result = await this.listSessions();
           break;
 
         case 'connect':
@@ -171,8 +171,8 @@ export class SSEConnectionManager {
           result = await this.callTool(request.params as CallToolParams);
           break;
 
-        case 'restoreSession':
-          result = await this.restoreSession(request.params as SessionParams);
+        case 'getSession':
+          result = await this.getSession(request.params as SessionParams);
           break;
 
         case 'finishAuth':
@@ -225,13 +225,13 @@ export class SSEConnectionManager {
   }
 
   /**
-   * Get all sessions for the current identity
+   * Get all sessions for the current userId
    */
-  private async getSessions(): Promise<SessionListResult> {
-    const sessions = await storage.getIdentitySessionsData(this.identity);
+  private async listSessions(): Promise<SessionListResult> {
+    const sessionList = await sessions.list(this.userId);
 
     return {
-      sessions: sessions.map((s) => ({
+      sessions: sessionList.map((s) => ({
         sessionId: s.sessionId,
         serverId: s.serverId,
         serverName: s.serverName,
@@ -254,10 +254,10 @@ export class SSEConnectionManager {
     // Tool name format: tool_<serverId>_<toolName> - with 12 char serverId leaves 46 chars for tool name
     const serverId = params.serverId && params.serverId.length <= 12
       ? params.serverId
-      : await storage.generateSessionId();
+      : await sessions.generateSessionId();
 
     // Check for existing connections
-    const existingSessions = await storage.getIdentitySessionsData(this.identity);
+    const existingSessions = await sessions.list(this.userId);
     const duplicate = existingSessions.find(s =>
       s.serverId === serverId || s.serverUrl === serverUrl
     );
@@ -266,7 +266,7 @@ export class SSEConnectionManager {
       // If the existing session is still pending OAuth, treat connect as "resume auth"
       // instead of failing with duplicate connection error.
       if (duplicate.active === false) {
-        await this.restoreSession({ sessionId: duplicate.sessionId });
+        await this.getSession({ sessionId: duplicate.sessionId });
         return {
           sessionId: duplicate.sessionId,
           success: true,
@@ -276,7 +276,7 @@ export class SSEConnectionManager {
     }
 
     // Generate session ID
-    const sessionId = await storage.generateSessionId();
+    const sessionId = await sessions.generateSessionId();
 
     try {
       // Get resolved client metadata
@@ -284,7 +284,7 @@ export class SSEConnectionManager {
 
       // Create MCP client
       const client = new MCPClient({
-        identity: this.identity,
+        userId: this.userId,
         sessionId,
         serverId,
         serverName,
@@ -360,7 +360,7 @@ export class SSEConnectionManager {
     } else {
       // Handle orphaned sessions (e.g., OAuth flow failed before client was stored)
       // Directly remove from storage since there's no active client
-      await storage.removeSession(this.identity, sessionId);
+      await sessions.delete(this.userId, sessionId);
     }
 
     return { success: true };
@@ -375,13 +375,13 @@ export class SSEConnectionManager {
       return existing;
     }
 
-    const session = await storage.getSession(this.identity, sessionId);
+    const session = await sessions.get(this.userId, sessionId);
     if (!session) {
       throw new Error('Session not found');
     }
 
     const client = new MCPClient({
-      identity: this.identity,
+      userId: this.userId,
       sessionId,
       // These fields are optional in MCPClient, but when rehydrating a known
       // stored session on the server we pass them explicitly to preserve the
@@ -439,10 +439,10 @@ export class SSEConnectionManager {
   /**
    * Restore and validate an existing session
    */
-  private async restoreSession(params: SessionParams): Promise<RestoreSessionResult> {
+  private async getSession(params: SessionParams): Promise<GetSessionResult> {
     const { sessionId } = params;
 
-    const session = await storage.getSession(this.identity, sessionId);
+    const session = await sessions.get(this.userId, sessionId);
     if (!session) {
       throw new Error('Session not found');
     }
@@ -462,7 +462,7 @@ export class SSEConnectionManager {
       const clientMetadata = await this.getResolvedClientMetadata();
 
       const client = new MCPClient({
-        identity: this.identity,
+        userId: this.userId,
         sessionId,
         // These fields are optional in MCPClient, but when rehydrating a known
         // stored session on the server we pass them explicitly to preserve the
@@ -506,14 +506,14 @@ export class SSEConnectionManager {
   private async finishAuth(params: FinishAuthParams): Promise<FinishAuthResult> {
     const { sessionId, code } = params;
 
-    const session = await storage.getSession(this.identity, sessionId);
+    const session = await sessions.get(this.userId, sessionId);
     if (!session) {
       throw new Error('Session not found');
     }
 
     try {
       const client = new MCPClient({
-        identity: this.identity,
+        userId: this.userId,
         sessionId,
         // These fields are optional in MCPClient, but when rehydrating a known
         // stored session on the server we pass them explicitly to preserve the
@@ -524,7 +524,7 @@ export class SSEConnectionManager {
         serverUrl: session.serverUrl,
         callbackUrl: session.callbackUrl,
         // NOTE: transportType is intentionally omitted here.
-        // The session's stored transportType is a placeholder ('streamable_http')
+        // 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.

package/src/server/index.ts

@@ -6,7 +6,7 @@
 /** Core MCP client and session management */
 export { MCPClient } from './mcp/oauth-client.js';
 export { UnauthorizedError } from '../shared/errors.js';
-export { storage, type StorageBackend } from './storage/index.js';
+export { sessions, type SessionStore } from './storage/index.js';
 export { StorageOAuthClientProvider } from './mcp/storage-oauth-provider.js';
 export { MultiSessionClient } from './mcp/multi-session-client.js';
 

package/src/server/mcp/multi-session-client.ts

@@ -1,7 +1,7 @@
 
 
 import { MCPClient } from './oauth-client.js';
-import { storage, type SessionData } from '../storage/index.js';
+import { sessions, type Session } from '../storage/index.js';
 
 const DEFAULT_TIMEOUT_MS = 15000;
 const DEFAULT_MAX_RETRIES = 2;
@@ -9,7 +9,7 @@ const DEFAULT_RETRY_DELAY_MS = 1000;
 const CONNECTION_BATCH_SIZE = 5;
 
 /**
- * Manages multiple MCP connections for a single user identity.
+ * Manages multiple MCP connections for a single user.
  * Allows aggregating tools from all connected servers.
  */
 export interface MultiSessionOptions {
@@ -31,7 +31,7 @@ export interface MultiSessionOptions {
 }
 
 /**
- * Manages multiple MCP client connections for a single user identity.
+ * Manages multiple MCP client connections for a single user.
  *
  * On a traditional long-running server, you can cache this instance per user
  * so the connections stay alive between requests. On serverless, a new instance
@@ -40,18 +40,18 @@ export interface MultiSessionOptions {
  */
 export class MultiSessionClient {
     private clients: MCPClient[] = [];
-    private identity: string;
+    private userId: string;
     private options: MultiSessionOptions;
 
     /**
-     * Creates a new MultiSessionClient for the given user identity.
+     * Creates a new MultiSessionClient for the given user userId.
      *
-     * @param identity - A unique string identifying the user (e.g. user ID or email).
+     * @param userId - A unique string identifying the user (e.g. user ID or email).
      * @param options  - Optional tuning for connection timeout, retry count, and retry delay.
      *                   Falls back to sensible defaults if not provided.
      */
-    constructor(identity: string, options: MultiSessionOptions = {}) {
-        this.identity = identity;
+    constructor(userId: string, options: MultiSessionOptions = {}) {
+        this.userId = userId;
         this.options = {
             timeout: DEFAULT_TIMEOUT_MS,
             maxRetries: DEFAULT_MAX_RETRIES,
@@ -61,7 +61,7 @@ export class MultiSessionClient {
     }
 
     /**
-     * Fetches all sessions for this identity from storage and returns only the
+     * Fetches all sessions for this userId from storage and returns only the
      * ones that are ready to connect.
      *
      * A session is considered connectable when:
@@ -73,9 +73,9 @@ export class MultiSessionClient {
      * Note: Sessions where `active` is `undefined` (legacy records) are included
      * for backwards compatibility.
      */
-    private async getActiveSessions(): Promise<SessionData[]> {
-        const sessions = await storage.getIdentitySessionsData(this.identity);
-        const valid = sessions.filter(s =>
+    private async getActiveSessions(): Promise<Session[]> {
+        const sessionList = await sessions.list(this.userId);
+        const valid = sessionList.filter(s =>
             s.serverId &&
             s.serverUrl &&
             s.callbackUrl &&
@@ -91,7 +91,7 @@ export class MultiSessionClient {
      * has many active MCP sessions (e.g. 20+ servers). Within each batch, sessions
      * are connected concurrently using `Promise.all` for speed.
      */
-    private async connectInBatches(sessions: SessionData[]): Promise<void> {
+    private async connectInBatches(sessions: Session[]): Promise<void> {
         for (let i = 0; i < sessions.length; i += CONNECTION_BATCH_SIZE) {
             const batch = sessions.slice(i, i + CONNECTION_BATCH_SIZE);
             await Promise.all(batch.map(session => this.connectSession(session)));
@@ -110,7 +110,7 @@ export class MultiSessionClient {
      *   per-session mutex so we never spin up two physical connections for the same session.
      * - On completion (success or failure), the promise is cleaned up from the map.
      */
-    private async connectSession(session: SessionData): Promise<void> {
+    private async connectSession(session: Session): Promise<void> {
         const existingClient = this.clients.find(c => c.getSessionId() === session.sessionId);
         if (existingClient?.isConnected()) {
             return;
@@ -146,7 +146,7 @@ export class MultiSessionClient {
      * If all attempts are exhausted, logs an error and returns silently (does not throw),
      * so a single bad server doesn't block the rest of the batch from connecting.
      */
-    private async establishConnectionWithRetries(session: SessionData): Promise<void> {
+    private async establishConnectionWithRetries(session: Session): Promise<void> {
         const maxRetries = this.options.maxRetries ?? DEFAULT_MAX_RETRIES;
         const retryDelay = this.options.retryDelay ?? DEFAULT_RETRY_DELAY_MS;
         let lastError: unknown;
@@ -154,7 +154,7 @@ export class MultiSessionClient {
         for (let attempt = 0; attempt <= maxRetries; attempt++) {
             try {
                 const client = new MCPClient({
-                    identity: this.identity,
+                    userId: this.userId,
                     sessionId: session.sessionId,
                     serverId: session.serverId,
                     serverUrl: session.serverUrl,
@@ -192,7 +192,7 @@ export class MultiSessionClient {
     }
 
     /**
-     * The main entry point. Fetches all active sessions for this identity from
+     * The main entry point. Fetches all active sessions for this userId from
      * storage and establishes connections to all of them in batches.
      *
      * Call this once after creating the client. On traditional servers, you can