@mcp-ts/sdk 1.0.0

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

@@ -0,0 +1,210 @@
+
+import type { Redis } from 'ioredis';
+import { customAlphabet } from 'nanoid';
+import { StorageBackend, SessionData, SetClientOptions } from './types';
+import { SESSION_TTL_SECONDS } from '../../shared/constants.js';
+
+/** first char: letters only (required by OpenAI) */
+const firstChar = customAlphabet(
+    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz',
+    1
+);
+
+/** remaining chars: alphanumeric */
+const rest = customAlphabet(
+    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789',
+    11
+);
+
+/**
+ * Redis implementation of StorageBackend
+ */
+export class RedisStorageBackend implements StorageBackend {
+    private readonly DEFAULT_TTL = SESSION_TTL_SECONDS;
+    private readonly KEY_PREFIX = 'mcp:session:';
+
+    constructor(private redis: Redis) { }
+
+    /**
+     * Generates Redis key for a specific session
+     * @private
+     */
+    private getSessionKey(identity: string, sessionId: string): string {
+        return `${this.KEY_PREFIX}${identity}:${sessionId}`;
+    }
+
+    /**
+     * Generates Redis key for tracking all sessions for an identity
+     * @private
+     */
+    private getIdentityKey(identity: string): string {
+        return `mcp:identity:${identity}:sessions`;
+    }
+
+    generateSessionId(): string {
+        return firstChar() + rest();
+    }
+
+    async createSession(session: SessionData, ttl?: number): Promise<void> {
+        const { sessionId, identity } = session;
+        if (!sessionId || !identity) throw new Error('identity and sessionId required');
+
+        const sessionKey = this.getSessionKey(identity, sessionId);
+        const identityKey = this.getIdentityKey(identity);
+        const effectiveTtl = ttl ?? this.DEFAULT_TTL;
+
+        /** ioredis syntax: set(key, val, 'EX', ttl, 'NX') */
+        const result = await this.redis.set(
+            sessionKey,
+            JSON.stringify(session),
+            'EX',
+            effectiveTtl,
+            'NX'
+        );
+
+        if (result !== 'OK') {
+            throw new Error(`Session ${sessionId} already exists`);
+        }
+
+        await this.redis.sadd(identityKey, sessionId);
+    }
+    async updateSession(identity: string, sessionId: string, data: Partial<SessionData>, ttl?: number): Promise<void> {
+        const sessionKey = this.getSessionKey(identity, sessionId);
+        const effectiveTtl = ttl ?? this.DEFAULT_TTL;
+
+        /** Lua script for atomic parsing, merging, and saving */
+        const script = `
+            local currentStr = redis.call("GET", KEYS[1])
+            if not currentStr then
+                return 0
+            end
+
+            local current = cjson.decode(currentStr)
+            local updates = cjson.decode(ARGV[1])
+
+            for k,v in pairs(updates) do
+                current[k] = v
+            end
+
+            redis.call("SET", KEYS[1], cjson.encode(current), "EX", ARGV[2])
+            return 1
+        `;
+
+        const result = await this.redis.eval(
+            script,
+            1,
+            sessionKey,
+            JSON.stringify(data),
+            effectiveTtl
+        );
+
+        if (result === 0) {
+            throw new Error(`Session ${sessionId} not found for identity ${identity}`);
+        }
+    }
+
+    async getSession(identity: string, sessionId: string): Promise<SessionData | null> {
+        try {
+            const sessionKey = this.getSessionKey(identity, sessionId);
+            const sessionDataStr = await this.redis.get(sessionKey);
+
+            if (!sessionDataStr) {
+                return null;
+            }
+
+            const sessionData: SessionData = JSON.parse(sessionDataStr);
+            return sessionData;
+        } catch (error) {
+            console.error('[RedisStorage] Failed to get session:', error);
+            return null;
+        }
+    }
+
+    async getIdentityMcpSessions(identity: string): Promise<string[]> {
+        const identityKey = this.getIdentityKey(identity);
+        try {
+            return await this.redis.smembers(identityKey);
+        } catch (error) {
+            console.error(`[RedisStorage] Failed to get sessions for ${identity}:`, error);
+            return [];
+        }
+    }
+
+    async getIdentitySessionsData(identity: string): Promise<SessionData[]> {
+        try {
+            const sessionIds = await this.redis.smembers(this.getIdentityKey(identity));
+            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;
+                })
+            );
+
+            return results.filter((session): session is SessionData => session !== null);
+        } catch (error) {
+            console.error(`[RedisStorage] Failed to get session data for ${identity}:`, error);
+            return [];
+        }
+    }
+
+    async removeSession(identity: string, sessionId: string): Promise<void> {
+        try {
+            const sessionKey = this.getSessionKey(identity, sessionId);
+            const identityKey = this.getIdentityKey(identity);
+
+            await this.redis.srem(identityKey, sessionId);
+            await this.redis.del(sessionKey);
+        } catch (error) {
+            console.error('[RedisStorage] Failed to remove session:', error);
+        }
+    }
+
+    async getAllSessionIds(): Promise<string[]> {
+        try {
+            const pattern = `${this.KEY_PREFIX}*`;
+            const keys = await this.redis.keys(pattern);
+            return keys.map((key) => key.replace(this.KEY_PREFIX, ''));
+        } catch (error) {
+            console.error('[RedisStorage] Failed to get all sessions:', error);
+            return [];
+        }
+    }
+
+    async clearAll(): Promise<void> {
+        try {
+            const pattern = `${this.KEY_PREFIX}*`;
+            const keys = await this.redis.keys(pattern);
+            if (keys.length > 0) {
+                await this.redis.del(...keys);
+            }
+        } catch (error) {
+            console.error('[RedisStorage] Failed to clear sessions:', error);
+        }
+    }
+
+    async cleanupExpiredSessions(): Promise<void> {
+        try {
+            const pattern = `${this.KEY_PREFIX}*`;
+            const keys = await this.redis.keys(pattern);
+
+            for (const key of keys) {
+                const ttl = await this.redis.ttl(key);
+                if (ttl <= 0) {
+                    await this.redis.del(key);
+                }
+            }
+        } catch (error) {
+            console.error('[RedisStorage] Failed to cleanup expired sessions:', error);
+        }
+    }
+
+    async disconnect(): Promise<void> {
+        try {
+            await this.redis.quit();
+        } catch (error) {
+            console.error('[RedisStorage] Failed to disconnect:', error);
+        }
+    }
+}

package/src/server/storage/redis.ts

@@ -0,0 +1,160 @@
+/**
+ * Redis connection management with dependency injection support
+ * Allows configuration and testing without environment variables
+ */
+import type { Redis } from 'ioredis';
+
+export interface RedisConfig {
+    /**
+     * Redis connection URL (defaults to REDIS_URL env var)
+     */
+    url?: string;
+
+    /**
+     * Enable lazy connection (default: true)
+     */
+    lazyConnect?: boolean;
+
+    /**
+     * Maximum retries per request (default: 1)
+     */
+    maxRetriesPerRequest?: number;
+
+    /**
+     * Enable verbose logging (default: false)
+     */
+    verbose?: boolean;
+    /**
+     * @internal For testing only - bypass ioredis import
+     */
+    RedisConstructor?: any;
+}
+
+declare global {
+    // eslint-disable-next-line no-var
+    var __redis: Redis | undefined;
+    var __redisConfig: RedisConfig | undefined;
+}
+
+let redisInstance: Redis | null = null;
+
+/**
+ * Initialize Redis with custom configuration
+ * Call this before any Redis operations if you need custom config
+ * @param config - Redis configuration options
+ */
+export async function initRedis(config: RedisConfig): Promise<Redis> {
+    if (redisInstance) {
+        // Already initialized, return existing instance
+        return redisInstance;
+    }
+
+    const url = config.url ?? process.env.REDIS_URL;
+
+    if (!url) {
+        throw new Error(
+            'Redis URL is required. Set REDIS_URL environment variable or pass url in config.'
+        );
+    }
+
+    let Redis: typeof import('ioredis').Redis;
+    if (config.RedisConstructor) {
+        Redis = config.RedisConstructor;
+    } else {
+        try {
+            const ioredis = await import('ioredis');
+            Redis = ioredis.Redis;
+        } catch (error) {
+            throw new Error(
+                'ioredis is not installed. Install it with:\n' +
+                '  npm install ioredis\n\n' +
+                'Or use a different storage backend:\n' +
+                '  MCP_TS_STORAGE_TYPE=memory  (for development)\n' +
+                '  MCP_TS_STORAGE_TYPE=file    (for local persistence)'
+            );
+        }
+    }
+
+    redisInstance = new Redis(url, {
+        lazyConnect: config.lazyConnect ?? true,
+        maxRetriesPerRequest: config.maxRetriesPerRequest ?? 1,
+    });
+
+    if (config.verbose !== false) {
+        redisInstance.on('ready', () => {
+            console.log('✅ Redis connected');
+        });
+
+        redisInstance.on('error', (err) => {
+            console.error('❌ Redis error:', err.message);
+        });
+
+        redisInstance.on('reconnecting', () => {
+            console.log('🔄 Redis reconnecting...');
+        });
+    }
+
+    // Store globally for hot reloading scenarios
+    global.__redis = redisInstance;
+    global.__redisConfig = config;
+
+    return redisInstance;
+}
+
+/**
+ * Get the Redis instance
+ * Automatically initializes with default config if not already initialized
+ */
+export async function getRedis(): Promise<Redis> {
+    if (redisInstance) {
+        return redisInstance;
+    }
+
+    // Check for existing global instance (hot reload scenario)
+    if (global.__redis) {
+        redisInstance = global.__redis;
+        return redisInstance;
+    }
+
+    // Initialize with default config
+    return await initRedis({});
+}
+
+/**
+ * Set a custom Redis instance (useful for testing with mocks)
+ * @param instance - Redis instance or mock
+ */
+export function setRedisInstance(instance: Redis): void {
+    redisInstance = instance;
+    global.__redis = instance;
+}
+
+/**
+ * Close Redis connection and clear instance
+ */
+export async function closeRedis(): Promise<void> {
+    if (redisInstance) {
+        await redisInstance.quit();
+        redisInstance = null;
+        global.__redis = undefined;
+    }
+}
+
+/**
+ * Default Redis export for backward compatibility
+ * Will auto-initialize on first access
+ * Note: This is a lazy proxy that initializes Redis on first method call
+ */
+export const redis = new Proxy({} as Redis, {
+    get(_target, prop) {
+        // Return a function that handles async initialization
+        return async (...args: any[]) => {
+            const instance = await getRedis();
+            const value = (instance as any)[prop];
+            if (typeof value === 'function') {
+                return value.apply(instance, args);
+            }
+            return value;
+        };
+    },
+});

package/src/server/storage/types.ts

@@ -0,0 +1,109 @@
+
+import type { MCPClient } from '../mcp/oauth-client.js';
+import type {
+    OAuthTokens,
+    OAuthClientInformationMixed,
+} from '@modelcontextprotocol/sdk/shared/auth.js';
+
+export interface SessionData {
+    sessionId: string;
+    serverId?: string; // Database server ID for mapping
+    serverName?: string;
+    serverUrl: string;
+    transportType: 'sse' | 'streamable_http';
+    callbackUrl: string;
+    createdAt: number;
+    identity?: string;
+    headers?: Record<string, string>;
+    // OAuth data (consolidated)
+    clientInformation?: OAuthClientInformationMixed;
+    tokens?: OAuthTokens;
+    codeVerifier?: string;
+    clientId?: string;
+}
+
+export interface SetClientOptions {
+    sessionId: string;
+    serverId?: string; // Database server ID
+    serverName?: string; // Human-readable server name
+    client?: MCPClient;
+    serverUrl?: string;
+    callbackUrl?: string;
+    transportType?: 'sse' | 'streamable_http';
+    identity?: string;
+    headers?: Record<string, string>;
+}
+
+/**
+ * Interface for MCP Session Storage Backends
+ */
+export interface StorageBackend {
+    /**
+     * Optional initialization (e.g., database connection)
+     */
+    init?(): Promise<void>;
+
+    /**
+     * Generates a unique session ID
+     */
+    generateSessionId(): string;
+
+    /**
+     * Stores or updates a session
+     */
+    /**
+     * Creates a new session. Throws if session already exists.
+     * @param session - Session data to create
+     * @param ttl - Optional TTL in seconds (defaults to backend's default)
+     */
+    createSession(session: SessionData, ttl?: number): Promise<void>;
+
+    /**
+     * Updates an existing session with partial data. Throws if session does not exist.
+     * @param identity - User identity
+     * @param sessionId - Session identifier
+     * @param data - Partial session data to update
+     * @param ttl - Optional TTL in seconds (defaults to backend's default)
+     */
+    updateSession(identity: string, sessionId: string, data: Partial<SessionData>, ttl?: number): Promise<void>;
+
+    /**
+     * Retrieves a session
+     */
+    getSession(identity: string, sessionId: string): Promise<SessionData | null>;
+
+    /**
+     * Gets full session data for all of an identity's sessions
+     */
+    getIdentitySessionsData(identity: string): Promise<SessionData[]>;
+
+    /**
+     * Removes a session
+     */
+    removeSession(identity: string, sessionId: string): Promise<void>;
+
+    /**
+     * Gets all sessions IDs of an identity
+     */
+    getIdentityMcpSessions(identity: string): Promise<string[]>;
+
+    /**
+     * Gets all session IDs across all users (Admin)
+     */
+    getAllSessionIds(): Promise<string[]>;
+
+    /**
+     * Clears all sessions (Admin)
+     */
+    clearAll(): Promise<void>;
+
+    /**
+     * Clean up expired sessions
+     */
+    cleanupExpiredSessions(): Promise<void>;
+
+    /**
+     * Disconnect from storage backend
+     */
+    disconnect(): Promise<void>;
+}

package/src/shared/constants.ts

@@ -0,0 +1,29 @@
+/**
+ * Centralized constants for MCP Redis library
+ * Eliminates magic numbers and enables consistent configuration
+ */
+
+// Redis TTL and Session Management
+export const SESSION_TTL_SECONDS = 43200; // 12 hours
+export const STATE_EXPIRATION_MS = 10 * 60 * 1000; // 10 minutes for OAuth state
+
+// Heartbeat and Connection
+export const DEFAULT_HEARTBEAT_INTERVAL_MS = 30000; // 30 seconds
+
+// Redis Key Prefixes
+export const REDIS_KEY_PREFIX = 'mcp:session:';
+
+// Token Management
+export const TOKEN_EXPIRY_BUFFER_MS = 5 * 60 * 1000; // 5 minute buffer before expiry
+
+// Client Information
+export const DEFAULT_CLIENT_NAME = 'MCP Assistant';
+export const DEFAULT_CLIENT_URI = 'https://mcp-assistant.in';
+export const DEFAULT_LOGO_URI = 'https://mcp-assistant.in/logo.png';
+export const DEFAULT_POLICY_URI = 'https://mcp-assistant.in/privacy';
+export const SOFTWARE_ID = '@mcp-ts';
+export const SOFTWARE_VERSION = '1.0.0-beta.5';
+
+// MCP Client Configuration
+export const MCP_CLIENT_NAME = 'mcp-ts-oauth-client';
+export const MCP_CLIENT_VERSION = '2.0';

package/src/shared/errors.ts

@@ -0,0 +1,133 @@
+/**
+ * Standardized error classes for MCP Redis library
+ * Provides consistent error handling across the codebase
+ */
+
+/**
+ * Base error class for all MCP-related errors
+ */
+export class McpError extends Error {
+    constructor(
+        public readonly code: string,
+        message: string,
+        public readonly cause?: Error
+    ) {
+        super(message);
+        this.name = 'McpError';
+        // Maintain proper prototype chain for instanceof checks
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+
+    toJSON() {
+        return {
+            name: this.name,
+            code: this.code,
+            message: this.message,
+            ...(this.cause ? { cause: this.cause.message } : {}),
+        };
+    }
+}
+
+/**
+ * Thrown when OAuth authorization is required
+ */
+export class UnauthorizedError extends McpError {
+    constructor(message: string = 'OAuth authorization required', cause?: Error) {
+        super('UNAUTHORIZED', message, cause);
+        this.name = 'UnauthorizedError';
+    }
+}
+
+/**
+ * Thrown when connection to MCP server fails
+ */
+export class ConnectionError extends McpError {
+    constructor(message: string, cause?: Error) {
+        super('CONNECTION_ERROR', message, cause);
+        this.name = 'ConnectionError';
+    }
+}
+
+/**
+ * Thrown when session is not found or expired
+ */
+export class SessionNotFoundError extends McpError {
+    constructor(sessionId: string, cause?: Error) {
+        super('SESSION_NOT_FOUND', `Session not found: ${sessionId}`, cause);
+        this.name = 'SessionNotFoundError';
+    }
+}
+
+/**
+ * Thrown when session validation fails
+ */
+export class SessionValidationError extends McpError {
+    constructor(message: string, cause?: Error) {
+        super('SESSION_VALIDATION_ERROR', message, cause);
+        this.name = 'SessionValidationError';
+    }
+}
+
+/**
+ * Thrown when authentication fails
+ */
+export class AuthenticationError extends McpError {
+    constructor(message: string, cause?: Error) {
+        super('AUTH_ERROR', message, cause);
+        this.name = 'AuthenticationError';
+    }
+}
+
+/**
+ * Thrown when OAuth state validation fails
+ */
+export class InvalidStateError extends McpError {
+    constructor(message: string = 'Invalid OAuth state', cause?: Error) {
+        super('INVALID_STATE', message, cause);
+        this.name = 'InvalidStateError';
+    }
+}
+
+/**
+ * Thrown when client is not connected
+ */
+export class NotConnectedError extends McpError {
+    constructor(message: string = 'Not connected to server', cause?: Error) {
+        super('NOT_CONNECTED', message, cause);
+        this.name = 'NotConnectedError';
+    }
+}
+
+/**
+ * Thrown when required configuration is missing
+ */
+export class ConfigurationError extends McpError {
+    constructor(message: string, cause?: Error) {
+        super('CONFIGURATION_ERROR', message, cause);
+        this.name = 'ConfigurationError';
+    }
+}
+
+/**
+ * Thrown when tool execution fails
+ */
+export class ToolExecutionError extends McpError {
+    constructor(toolName: string, message: string, cause?: Error) {
+        super('TOOL_EXECUTION_ERROR', `Tool '${toolName}' failed: ${message}`, cause);
+        this.name = 'ToolExecutionError';
+    }
+}
+
+/**
+ * RPC error codes for SSE communication
+ */
+export const RpcErrorCodes = {
+    EXECUTION_ERROR: 'EXECUTION_ERROR',
+    MISSING_IDENTITY: 'MISSING_IDENTITY',
+    UNAUTHORIZED: 'UNAUTHORIZED',
+    NO_CONNECTION: 'NO_CONNECTION',
+    UNKNOWN_METHOD: 'UNKNOWN_METHOD',
+    INVALID_PARAMS: 'INVALID_PARAMS',
+} as const;
+
+export type RpcErrorCode = typeof RpcErrorCodes[keyof typeof RpcErrorCodes];