@mcp-ts/sdk 1.6.2 → 2.0.0

package/src/server/storage/neon-backend.ts

@@ -0,0 +1,281 @@
+import type { SessionStore, Session } from './types.js';
+import { SESSION_TTL_SECONDS } from '../../shared/constants.js';
+import { generateSessionId } from '../../shared/utils.js';
+import { encryptObject, decryptObject } from './crypto.js';
+
+export interface NeonStorageOptions {
+    schema?: string;
+    table?: string;
+}
+
+type NeonSql = {
+    query(queryWithPlaceholders: string, params?: unknown[]): Promise<any[]>;
+};
+
+type NeonSessionRow = {
+    session_id: string;
+    server_id?: string | null;
+    server_name?: string | null;
+    server_url: string;
+    transport_type: 'sse' | 'streamable-http';
+    callback_url: string;
+    created_at: string | Date;
+    user_id: string;
+    headers?: unknown;
+    active?: boolean | null;
+    client_information?: unknown;
+    tokens?: unknown;
+    code_verifier?: string | null;
+    client_id?: string | null;
+};
+
+export class NeonStorageBackend implements SessionStore {
+    private readonly DEFAULT_TTL = SESSION_TTL_SECONDS;
+    private readonly tableName: string;
+
+    constructor(
+        private readonly sql: NeonSql,
+        options: NeonStorageOptions = {}
+    ) {
+        const schema = options.schema || 'public';
+        const table = options.table || 'mcp_sessions';
+        this.tableName = `${this.quoteIdentifier(schema)}.${this.quoteIdentifier(table)}`;
+    }
+
+    async init(): Promise<void> {
+        const [{ exists } = { exists: null }] = await this.sql.query(
+            'SELECT to_regclass($1) AS exists',
+            [this.tableName.replace(/"/g, '')]
+        ) as Array<{ exists: string | null }>;
+
+        if (!exists) {
+            throw new Error(
+                '[NeonStorage] Table "mcp_sessions" not found in your database. ' +
+                'Please create it using the Neon storage guide in docs/storage-backends/neon.md.'
+            );
+        }
+
+        console.log('[mcp-ts][Storage] Neon: "mcp_sessions" table verified.');
+    }
+
+    generateSessionId(): string {
+        return generateSessionId();
+    }
+
+    private quoteIdentifier(identifier: string): string {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(identifier)) {
+            throw new Error(`Invalid Neon storage identifier: ${identifier}`);
+        }
+        return `"${identifier}"`;
+    }
+
+    private mapRowToSessionData(row: NeonSessionRow): Session {
+        return {
+            sessionId: row.session_id,
+            serverId: row.server_id ?? undefined,
+            serverName: row.server_name ?? undefined,
+            serverUrl: row.server_url,
+            transportType: row.transport_type,
+            callbackUrl: row.callback_url,
+            createdAt: new Date(row.created_at).getTime(),
+            userId: row.user_id,
+            headers: decryptObject(row.headers),
+            active: row.active ?? false,
+            clientInformation: row.client_information as Session['clientInformation'],
+            tokens: decryptObject(row.tokens),
+            codeVerifier: row.code_verifier ?? undefined,
+            clientId: row.client_id ?? undefined,
+        };
+    }
+
+    async create(session: Session, ttl?: number): Promise<void> {
+        const { sessionId, userId } = session;
+        if (!sessionId || !userId) throw new Error('userId and sessionId required');
+
+        const effectiveTtl = ttl ?? this.DEFAULT_TTL;
+        const expiresAt = new Date(Date.now() + effectiveTtl * 1000).toISOString();
+
+        try {
+            await this.sql.query(
+                `INSERT INTO ${this.tableName} (
+                    session_id,
+                    user_id,
+                    server_id,
+                    server_name,
+                    server_url,
+                    transport_type,
+                    callback_url,
+                    created_at,
+                    headers,
+                    active,
+                    client_information,
+                    tokens,
+                    code_verifier,
+                    client_id,
+                    expires_at
+                ) VALUES (
+                    $1, $2, $3, $4, $5, $6, $7, $8,
+                    $9, $10, $11, $12, $13, $14, $15
+                )`,
+                [
+                    sessionId,
+                    userId,
+                    session.serverId,
+                    session.serverName,
+                    session.serverUrl,
+                    session.transportType,
+                    session.callbackUrl,
+                    new Date(session.createdAt || Date.now()).toISOString(),
+                    encryptObject(session.headers),
+                    session.active ?? false,
+                    session.clientInformation,
+                    encryptObject(session.tokens),
+                    session.codeVerifier,
+                    session.clientId,
+                    expiresAt,
+                ]
+            );
+        } catch (error: any) {
+            if (error.code === '23505') {
+                throw new Error(`Session ${sessionId} already exists`);
+            }
+            throw new Error(`Failed to create session in Neon: ${error.message}`);
+        }
+    }
+
+    async update(userId: string, sessionId: string, data: Partial<Session>, ttl?: number): Promise<void> {
+        const currentSession = await this.get(userId, sessionId);
+        if (!currentSession) {
+            throw new Error(`Session ${sessionId} not found for userId ${userId}`);
+        }
+
+        const updatedSession = { ...currentSession, ...data };
+        const effectiveTtl = ttl ?? this.DEFAULT_TTL;
+        const expiresAt = new Date(Date.now() + effectiveTtl * 1000).toISOString();
+
+        const updatedRows = await this.sql.query(
+            `UPDATE ${this.tableName}
+             SET
+                server_id = $1,
+                server_name = $2,
+                server_url = $3,
+                transport_type = $4,
+                callback_url = $5,
+                active = $6,
+                headers = $7,
+                client_information = $8,
+                tokens = $9,
+                code_verifier = $10,
+                client_id = $11,
+                expires_at = $12,
+                updated_at = now()
+             WHERE user_id = $13 AND session_id = $14
+             RETURNING id`,
+            [
+                updatedSession.serverId,
+                updatedSession.serverName,
+                updatedSession.serverUrl,
+                updatedSession.transportType,
+                updatedSession.callbackUrl,
+                updatedSession.active ?? false,
+                encryptObject(updatedSession.headers),
+                updatedSession.clientInformation,
+                encryptObject(updatedSession.tokens),
+                updatedSession.codeVerifier,
+                updatedSession.clientId,
+                expiresAt,
+                userId,
+                sessionId,
+            ]
+        ) as Array<{ id: string }>;
+
+        if (updatedRows.length === 0) {
+            throw new Error(`Session ${sessionId} not found for userId ${userId}`);
+        }
+    }
+
+    async get(userId: string, sessionId: string): Promise<Session | null> {
+        try {
+            const rows = await this.sql.query(
+                `SELECT * FROM ${this.tableName} WHERE user_id = $1 AND session_id = $2`,
+                [userId, sessionId]
+            ) as NeonSessionRow[];
+            return rows[0] ? this.mapRowToSessionData(rows[0]) : null;
+        } catch (error) {
+            console.error('[NeonStorage] Failed to get session:', error);
+            return null;
+        }
+    }
+
+    async list(userId: string): Promise<Session[]> {
+        try {
+            const rows = await this.sql.query(
+                `SELECT * FROM ${this.tableName} WHERE user_id = $1`,
+                [userId]
+            ) as NeonSessionRow[];
+            return rows.map((row) => this.mapRowToSessionData(row));
+        } catch (error) {
+            console.error(`[NeonStorage] Failed to get session data for ${userId}:`, error);
+            return [];
+        }
+    }
+
+    async delete(userId: string, sessionId: string): Promise<void> {
+        try {
+            await this.sql.query(
+                `DELETE FROM ${this.tableName} WHERE user_id = $1 AND session_id = $2`,
+                [userId, sessionId]
+            );
+        } catch (error) {
+            console.error('[NeonStorage] Failed to remove session:', error);
+        }
+    }
+
+    async listIds(userId: string): Promise<string[]> {
+        try {
+            const rows = await this.sql.query(
+                `SELECT session_id FROM ${this.tableName} WHERE user_id = $1`,
+                [userId]
+            ) as Array<{ session_id: string }>;
+            return rows.map((row) => row.session_id);
+        } catch (error) {
+            console.error(`[NeonStorage] Failed to get sessions for ${userId}:`, error);
+            return [];
+        }
+    }
+
+    async listAllIds(): Promise<string[]> {
+        try {
+            const rows = await this.sql.query(
+                `SELECT session_id FROM ${this.tableName}`
+            ) as Array<{ session_id: string }>;
+            return rows.map((row) => row.session_id);
+        } catch (error) {
+            console.error('[NeonStorage] Failed to get all sessions:', error);
+            return [];
+        }
+    }
+
+    async clearAll(): Promise<void> {
+        try {
+            await this.sql.query(`DELETE FROM ${this.tableName}`);
+        } catch (error) {
+            console.error('[NeonStorage] Failed to clear sessions:', error);
+        }
+    }
+
+    async cleanupExpired(): Promise<void> {
+        try {
+            await this.sql.query(
+                `DELETE FROM ${this.tableName} WHERE expires_at < $1`,
+                [new Date().toISOString()]
+            );
+        } catch (error) {
+            console.error('[NeonStorage] Failed to cleanup expired sessions:', error);
+        }
+    }
+
+    async disconnect(): Promise<void> {
+        // Neon HTTP queries do not hold a persistent connection.
+    }
+}

package/src/server/storage/redis-backend.ts

@@ -1,16 +1,16 @@
 import type { Redis } from 'ioredis';
-import { StorageBackend, SessionData } from './types.js';
+import type { SessionStore, Session } from './types.js';
 import { SESSION_TTL_SECONDS } from '../../shared/constants.js';
 import { generateSessionId } from '../../shared/utils.js';
 
 /**
- * Redis implementation of StorageBackend
+ * Redis implementation of SessionStore
  */
-export class RedisStorageBackend implements StorageBackend {
+export class RedisStorageBackend implements SessionStore {
     private readonly DEFAULT_TTL = SESSION_TTL_SECONDS;
     private readonly KEY_PREFIX = 'mcp:session:';
-    private readonly IDENTITY_KEY_PREFIX = 'mcp:identity:';
-    private readonly IDENTITY_KEY_SUFFIX = ':sessions';
+    private readonly USER_ID_KEY_PREFIX = 'mcp:userId:';
+    private readonly USER_ID_KEY_SUFFIX = ':sessions';
 
     constructor(private redis: Redis) { }
     
@@ -19,7 +19,7 @@ export class RedisStorageBackend implements StorageBackend {
             await this.redis.ping();
             console.log('[mcp-ts][Storage] Redis: ✓ Connected to server.');
         } catch (error: any) {
-            throw new Error(`[RedisStorage] Failed to connect to Redis: ${error.message}`);
+            throw new Error(`[RedisStorageBackend] Failed to connect to Redis: ${error.message}`);
         }
     }
 
@@ -27,22 +27,22 @@ export class RedisStorageBackend implements StorageBackend {
      * Generates Redis key for a specific session
      * @private
      */
-    private getSessionKey(identity: string, sessionId: string): string {
-        return `${this.KEY_PREFIX}${identity}:${sessionId}`;
+    private getSessionKey(userId: string, sessionId: string): string {
+        return `${this.KEY_PREFIX}${userId}:${sessionId}`;
     }
 
     /**
-     * Generates Redis key for tracking all sessions for an identity
+     * Generates Redis key for tracking all sessions for a user
      * @private
      */
-    private getIdentityKey(identity: string): string {
-        return `${this.IDENTITY_KEY_PREFIX}${identity}${this.IDENTITY_KEY_SUFFIX}`;
+    private getUserIdKey(userId: string): string {
+        return `${this.USER_ID_KEY_PREFIX}${userId}${this.USER_ID_KEY_SUFFIX}`;
     }
 
-    private parseIdentityFromKey(identityKey: string): string {
-        return identityKey.slice(
-            this.IDENTITY_KEY_PREFIX.length,
-            identityKey.length - this.IDENTITY_KEY_SUFFIX.length
+    private parseUserIdFromKey(userIdKey: string): string {
+        return userIdKey.slice(
+            this.USER_ID_KEY_PREFIX.length,
+            userIdKey.length - this.USER_ID_KEY_SUFFIX.length
         );
     }
 
@@ -67,7 +67,7 @@ export class RedisStorageBackend implements StorageBackend {
                 }
             } while (cursor !== '0');
         } catch (error) {
-            console.warn('[RedisStorage] SCAN failed, falling back to KEYS:', error);
+            console.warn('[RedisStorageBackend] SCAN failed, falling back to KEYS:', error);
             return await this.redis.keys(pattern);
         }
 
@@ -78,12 +78,12 @@ export class RedisStorageBackend implements StorageBackend {
         return generateSessionId();
     }
 
-    async createSession(session: SessionData, ttl?: number): Promise<void> {
-        const { sessionId, identity } = session;
-        if (!sessionId || !identity) throw new Error('identity and sessionId required');
+    async create(session: Session, ttl?: number): Promise<void> {
+        const { sessionId, userId } = session;
+        if (!sessionId || !userId) throw new Error('userId and sessionId required');
 
-        const sessionKey = this.getSessionKey(identity, sessionId);
-        const identityKey = this.getIdentityKey(identity);
+        const sessionKey = this.getSessionKey(userId, sessionId);
+        const userIdKey = this.getUserIdKey(userId);
         const effectiveTtl = ttl ?? this.DEFAULT_TTL;
 
         /** ioredis syntax: set(key, val, 'EX', ttl, 'NX') */
@@ -99,10 +99,10 @@ export class RedisStorageBackend implements StorageBackend {
             throw new Error(`Session ${sessionId} already exists`);
         }
 
-        await this.redis.sadd(identityKey, sessionId);
+        await this.redis.sadd(userIdKey, sessionId);
     }
-    async updateSession(identity: string, sessionId: string, data: Partial<SessionData>, ttl?: number): Promise<void> {
-        const sessionKey = this.getSessionKey(identity, sessionId);
+    async update(userId: string, sessionId: string, data: Partial<Session>, ttl?: number): Promise<void> {
+        const sessionKey = this.getSessionKey(userId, sessionId);
         const effectiveTtl = ttl ?? this.DEFAULT_TTL;
 
         /** Lua script for atomic parsing, merging, and saving */
@@ -132,70 +132,70 @@ export class RedisStorageBackend implements StorageBackend {
         );
 
         if (result === 0) {
-            throw new Error(`Session ${sessionId} not found for identity ${identity}`);
+            throw new Error(`Session ${sessionId} not found for userId ${userId}`);
         }
     }
 
-    async getSession(identity: string, sessionId: string): Promise<SessionData | null> {
+    async get(userId: string, sessionId: string): Promise<Session | null> {
         try {
-            const sessionKey = this.getSessionKey(identity, sessionId);
+            const sessionKey = this.getSessionKey(userId, sessionId);
             const sessionDataStr = await this.redis.get(sessionKey);
 
             if (!sessionDataStr) {
                 return null;
             }
 
-            const sessionData: SessionData = JSON.parse(sessionDataStr);
-            return sessionData;
+            const Session: Session = JSON.parse(sessionDataStr);
+            return Session;
         } catch (error) {
-            console.error('[RedisStorage] Failed to get session:', error);
+            console.error('[RedisStorageBackend] Failed to get session:', error);
             return null;
         }
     }
 
-    async getIdentityMcpSessions(identity: string): Promise<string[]> {
-        const sessions = await this.getIdentitySessionsData(identity);
+    async listIds(userId: string): Promise<string[]> {
+        const sessions = await this.list(userId);
         return sessions.map((session) => session.sessionId);
     }
 
-    async getIdentitySessionsData(identity: string): Promise<SessionData[]> {
+    async list(userId: string): Promise<Session[]> {
         try {
-            const identityKey = this.getIdentityKey(identity);
-            const sessionIds = await this.redis.smembers(identityKey);
+            const userIdKey = this.getUserIdKey(userId);
+            const sessionIds = await this.redis.smembers(userIdKey);
             if (sessionIds.length === 0) return [];
 
             const results = await Promise.all(
                 sessionIds.map(async (sessionId) => {
-                    const data = await this.redis.get(this.getSessionKey(identity, sessionId));
-                    return data ? (JSON.parse(data) as SessionData) : null;
+                    const data = await this.redis.get(this.getSessionKey(userId, sessionId));
+                    return data ? (JSON.parse(data) as Session) : null;
                 })
             );
 
             const staleSessionIds = sessionIds.filter((_, index) => results[index] === null);
             if (staleSessionIds.length > 0) {
-                await this.redis.srem(identityKey, ...staleSessionIds);
+                await this.redis.srem(userIdKey, ...staleSessionIds);
             }
 
-            return results.filter((session): session is SessionData => session !== null);
+            return results.filter((session): session is Session => session !== null);
         } catch (error) {
-            console.error(`[RedisStorage] Failed to get session data for ${identity}:`, error);
+            console.error(`[RedisStorageBackend] Failed to get session data for ${userId}:`, error);
             return [];
         }
     }
 
-    async removeSession(identity: string, sessionId: string): Promise<void> {
+    async delete(userId: string, sessionId: string): Promise<void> {
         try {
-            const sessionKey = this.getSessionKey(identity, sessionId);
-            const identityKey = this.getIdentityKey(identity);
+            const sessionKey = this.getSessionKey(userId, sessionId);
+            const userIdKey = this.getUserIdKey(userId);
 
-            await this.redis.srem(identityKey, sessionId);
+            await this.redis.srem(userIdKey, sessionId);
             await this.redis.del(sessionKey);
         } catch (error) {
-            console.error('[RedisStorage] Failed to remove session:', error);
+            console.error('[RedisStorageBackend] Failed to remove session:', error);
         }
     }
 
-    async getAllSessionIds(): Promise<string[]> {
+    async listAllIds(): Promise<string[]> {
         try {
             const keys = await this.scanKeys(`${this.KEY_PREFIX}*`);
             const sessions = await Promise.all(
@@ -206,9 +206,9 @@ export class RedisStorageBackend implements StorageBackend {
                     }
 
                     try {
-                        return (JSON.parse(data) as SessionData).sessionId;
+                        return (JSON.parse(data) as Session).sessionId;
                     } catch (error) {
-                        console.error('[RedisStorage] Failed to parse session while listing all session IDs:', error);
+                        console.error('[RedisStorageBackend] Failed to parse session while listing all session IDs:', error);
                         return null;
                     }
                 })
@@ -216,7 +216,7 @@ export class RedisStorageBackend implements StorageBackend {
 
             return sessions.filter((sessionId): sessionId is string => sessionId !== null);
         } catch (error) {
-            console.error('[RedisStorage] Failed to get all sessions:', error);
+            console.error('[RedisStorageBackend] Failed to get all sessions:', error);
             return [];
         }
     }
@@ -224,45 +224,45 @@ export class RedisStorageBackend implements StorageBackend {
     async clearAll(): Promise<void> {
         try {
             const keys = await this.scanKeys(`${this.KEY_PREFIX}*`);
-            const identityKeys = await this.scanKeys(`${this.IDENTITY_KEY_PREFIX}*${this.IDENTITY_KEY_SUFFIX}`);
-            const allKeys = [...keys, ...identityKeys];
+            const userIdKeys = await this.scanKeys(`${this.USER_ID_KEY_PREFIX}*${this.USER_ID_KEY_SUFFIX}`);
+            const allKeys = [...keys, ...userIdKeys];
             if (allKeys.length > 0) {
                 await this.redis.del(...allKeys);
             }
         } catch (error) {
-            console.error('[RedisStorage] Failed to clear sessions:', error);
+            console.error('[RedisStorageBackend] Failed to clear sessions:', error);
         }
     }
 
-    async cleanupExpiredSessions(): Promise<void> {
+    async cleanupExpired(): Promise<void> {
         try {
-            const identityKeys = await this.scanKeys(`${this.IDENTITY_KEY_PREFIX}*${this.IDENTITY_KEY_SUFFIX}`);
+            const userIdKeys = await this.scanKeys(`${this.USER_ID_KEY_PREFIX}*${this.USER_ID_KEY_SUFFIX}`);
 
-            for (const identityKey of identityKeys) {
-                const identity = this.parseIdentityFromKey(identityKey);
-                const sessionIds = await this.redis.smembers(identityKey);
+            for (const userIdKey of userIdKeys) {
+                const userId = this.parseUserIdFromKey(userIdKey);
+                const sessionIds = await this.redis.smembers(userIdKey);
 
                 if (sessionIds.length === 0) {
-                    await this.redis.del(identityKey);
+                    await this.redis.del(userIdKey);
                     continue;
                 }
 
                 const existenceChecks = await Promise.all(
-                    sessionIds.map((sessionId) => this.redis.exists(this.getSessionKey(identity, sessionId)))
+                    sessionIds.map((sessionId) => this.redis.exists(this.getSessionKey(userId, sessionId)))
                 );
 
                 const staleSessionIds = sessionIds.filter((_, index) => existenceChecks[index] === 0);
                 if (staleSessionIds.length > 0) {
-                    await this.redis.srem(identityKey, ...staleSessionIds);
+                    await this.redis.srem(userIdKey, ...staleSessionIds);
                 }
 
-                const remainingCount = await this.redis.scard(identityKey);
+                const remainingCount = await this.redis.scard(userIdKey);
                 if (remainingCount === 0) {
-                    await this.redis.del(identityKey);
+                    await this.redis.del(userIdKey);
                 }
             }
         } catch (error) {
-            console.error('[RedisStorage] Failed to cleanup expired sessions:', error);
+            console.error('[RedisStorageBackend] Failed to cleanup expired sessions:', error);
         }
     }
 
@@ -270,7 +270,7 @@ export class RedisStorageBackend implements StorageBackend {
         try {
             await this.redis.quit();
         } catch (error) {
-            console.error('[RedisStorage] Failed to disconnect:', error);
+            console.error('[RedisStorageBackend] Failed to disconnect:', error);
         }
     }
 }