@mcp-ts/sdk 1.3.5 → 1.3.6

package/package.json

@@ -1,13 +1,16 @@
 {
   "name": "@mcp-ts/sdk",
-  "version": "1.3.5",
+  "version": "1.3.6",
   "publishConfig": {
     "access": "public"
   },
-  "description": "A Lightweight MCP (Model Context Protocol) client library for JavaScript applications, supporting multiple storage backends (Memory, File, Redis) and real-time SSE support.",
+  "description": "A Lightweight MCP (Model Context Protocol) client library for JavaScript applications, supporting multiple storage backends (Memory, File, Redis, Supabase) and real-time SSE support.",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "mcp-ts": "./dist/bin/mcp-ts.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -68,7 +71,9 @@
   "files": [
     "dist",
     "src",
-    "README.md"
+    "supabase",
+    "README.md",
+    "LICENSE"
   ],
   "scripts": {
     "build": "tsup",
@@ -78,7 +83,10 @@
     "prepublishOnly": "npm run clean && npm run build",
     "test": "npx playwright test",
     "test:ui": "npx playwright test --ui",
-    "test:debug": "npx playwright test --debug"
+    "test:debug": "npx playwright test --debug",
+    "supabase:push": "supabase db push",
+    "supabase:reset": "supabase db reset",
+    "supabase:status": "supabase status"
   },
   "keywords": [
     "mcp",
@@ -111,7 +119,8 @@
     "ioredis": "^5.0.0",
     "react": ">=18.0.0",
     "rxjs": ">=7.0.0",
-    "zod": "^3.23.0"
+    "zod": "^3.23.0",
+    "@supabase/supabase-js": "^2.0.0"
   },
   "peerDependenciesMeta": {
     "react": {
@@ -137,6 +146,9 @@
     },
     "better-sqlite3": {
       "optional": true
+    },
+    "@supabase/supabase-js": {
+      "optional": true
     }
   },
   "dependencies": {
@@ -164,7 +176,8 @@
     "tsup": "^8.5.1",
     "typescript": "^5.9.3",
     "vue": "^3.5.27",
-    "zod": "^3.24.1"
+    "zod": "^3.24.1",
+    "@supabase/supabase-js": "^2.48.0"
   },
   "engines": {
     "node": ">=18.0.0"

package/src/bin/mcp-ts.ts

@@ -0,0 +1,102 @@
+#!/usr/bin/env node
+import * as fs from 'fs';
+import * as path from 'path';
+
+/**
+ * MCP-TS CLI Utility
+ * 
+ * Provides helper commands for users of the @mcp-ts/sdk library.
+ */
+async function run() {
+    const args = process.argv.slice(2);
+    const command = args[0];
+
+    if (command === 'supabase-init') {
+        await initSupabase();
+    } else {
+        showHelp();
+    }
+}
+
+function showHelp() {
+    console.log(`
+🚀 MCP-TS CLI Utility
+Usage: npx mcp-ts <command>
+
+Commands:
+  supabase-init    Initialize Supabase migrations in your project
+    `);
+}
+
+async function initSupabase() {
+    console.log('🚀 Initializing Supabase storage for MCP-TS...');
+
+    // When running from dist/bin/mcp-ts.js (compiled), __dirname is dist/bin.
+    // 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');
+    
+    if (!fs.existsSync(sourceDir)) {
+        console.error(`❌ Error: Could not find migration files in package at: ${sourceDir}`);
+        console.log('Please ensure you are running this from a project where @mcp-ts/sdk is installed.');
+        process.exit(1);
+    }
+
+    const targetDir = path.join(process.cwd(), 'supabase', 'migrations');
+
+    try {
+        if (!fs.existsSync(targetDir)) {
+            fs.mkdirSync(targetDir, { recursive: true });
+            console.log(`📁 Created directory: ${targetDir}`);
+        }
+
+        const files = fs.readdirSync(sourceDir);
+        let copiedCount = 0;
+
+        for (const file of files) {
+            if (file.endsWith('.sql')) {
+                const srcPath = path.join(sourceDir, file);
+                const destPath = path.join(targetDir, file);
+                
+                if (fs.existsSync(destPath)) {
+                    console.log(`⏭️  Skipping existing migration: ${file}`);
+                    continue;
+                }
+
+                fs.copyFileSync(srcPath, destPath);
+                console.log(`✅ Copied: ${file}`);
+                copiedCount++;
+            }
+        }
+
+        if (copiedCount > 0) {
+            console.log('\n✨ Database migrations successfully initialized!');
+            console.log('\nNext steps:');
+            console.log('1. Link your Supabase project:');
+            console.log('   npx supabase link --project-ref <your-project-id>');
+            console.log('\n2. Push the migrations to your remote database:');
+            console.log('   npx supabase db push');
+            console.log('\n3. Add your Supabase credentials to .env:');
+            console.log('   SUPABASE_URL=https://<your-project-id>.supabase.co');
+            console.log('   SUPABASE_SERVICE_ROLE_KEY=<your-service-role-key>');
+            console.log('\n⚠️  Important: Use the service_role key (not the anon key) for server-side storage.');
+            console.log('   The service_role key bypasses RLS policies and is required for mcp-ts to work correctly.');
+            console.log('   Find it in: Supabase Dashboard -> Project Settings -> API -> service_role');
+        } else if (files.length > 0) {
+            console.log('\n👍 All migration files are already present in your project.');
+            console.log('   Ensure SUPABASE_SERVICE_ROLE_KEY (not SUPABASE_ANON_KEY) is set in your .env');
+        } else {
+            console.log('⚠️  No migration files found to copy.');
+        }
+
+    } catch (error: any) {
+        console.error(`❌ Error initializing Supabase: ${error.message}`);
+        process.exit(1);
+    }
+}
+
+run().catch(err => {
+    console.error(err);
+    process.exit(1);
+});

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

@@ -5,10 +5,10 @@
  * - POST + JSON accepts direct RPC result response
  */
 
-import { SSEConnectionManager, type ClientMetadata } from './sse-handler.js';
-import type { McpConnectionEvent, McpObservabilityEvent } from '../../shared/events.js';
-import { isConnectionEvent, isRpcResponseEvent } from '../../shared/event-routing.js';
-import type { McpRpcResponse } from '../../shared/types.js';
+import { SSEConnectionManager, type ClientMetadata } from './sse-handler.js';
+import type { McpConnectionEvent, McpObservabilityEvent } from '../../shared/events.js';
+import { isConnectionEvent, isRpcResponseEvent } from '../../shared/event-routing.js';
+import type { McpRpcResponse } from '../../shared/types.js';
 
 export interface NextMcpHandlerOptions {
   /**
@@ -139,14 +139,14 @@ export function createNextMcpHandler(options: NextMcpHandlerOptions = {}) {
 
       const manager = new SSEConnectionManager(
         toManagerOptions(identity, resolvedClientMetadata),
-        (event: McpConnectionEvent | McpObservabilityEvent | McpRpcResponse) => {
-          if (isRpcResponseEvent(event)) {
-            sendSSE('rpc-response', event);
-          } else if (isConnectionEvent(event)) {
-            sendSSE('connection', event);
-          } else {
-            sendSSE('observability', event);
-          }
+        (event: McpConnectionEvent | McpObservabilityEvent | McpRpcResponse) => {
+          if (isRpcResponseEvent(event)) {
+            sendSSE('rpc-response', event);
+          } else if (isConnectionEvent(event)) {
+            sendSSE('connection', event);
+          } else {
+            sendSSE('observability', event);
+          }
         }
       );
 

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

@@ -13,8 +13,8 @@
  */
 
 import type { McpConnectionEvent, McpObservabilityEvent } from '../../shared/events.js';
-import type {
-  McpRpcRequest,
+import type {
+  McpRpcRequest,
   McpRpcResponse,
   ConnectParams,
   DisconnectParams,
@@ -32,12 +32,12 @@ import type {
   ListPromptsResult,
   ListResourcesResult,
   CallToolResult,
-} from '../../shared/types.js';
-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';
+} from '../../shared/types.js';
+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';
 
 // ============================================
 // Types & Interfaces
@@ -81,7 +81,7 @@ const DEFAULT_HEARTBEAT_INTERVAL = 30000;
  * Manages a single SSE connection and handles MCP operations.
  * Each instance corresponds to one connected browser client.
  */
-export class SSEConnectionManager {
+export class SSEConnectionManager {
   private readonly identity: string;
   private readonly clients = new Map<string, MCPClient>();
   private heartbeatTimer?: NodeJS.Timeout;
@@ -236,7 +236,7 @@ export class SSEConnectionManager {
   /**
    * Connect to an MCP server
    */
-  private async connect(params: ConnectParams): Promise<ConnectResult> {
+  private async connect(params: ConnectParams): Promise<ConnectResult> {
     const { serverName, serverUrl, callbackUrl, transportType } = params;
 
     // Normalize serverId to max 12 chars to keep tool names under 64 chars (DeepSeek/OpenAI limits)
@@ -267,21 +267,21 @@ export class SSEConnectionManager {
     // Generate session ID
     const sessionId = await storage.generateSessionId();
 
-    try {
+    try {
       // Get resolved client metadata
       const clientMetadata = await this.getResolvedClientMetadata();
 
       // Create MCP client
-      const client = new MCPClient({
-        identity: this.identity,
-        sessionId,
-        serverId,
-        serverName,
-        serverUrl,
-        callbackUrl,
-        transportType,
-        ...clientMetadata, // Spread client metadata (clientName, clientUri, logoUri, policyUri)
-      });
+      const client = new MCPClient({
+        identity: this.identity,
+        sessionId,
+        serverId,
+        serverName,
+        serverUrl,
+        callbackUrl,
+        transportType,
+        ...clientMetadata, // Spread client metadata (clientName, clientUri, logoUri, policyUri)
+      });
 
       // Note: Session will be created by MCPClient after successful connection
       // This ensures sessions only exist for successful or OAuth-pending connections
@@ -308,19 +308,19 @@ export class SSEConnectionManager {
         sessionId,
         success: true,
       };
-    } catch (error) {
-      if (error instanceof UnauthorizedError) {
-        // OAuth-required is a pending-auth state, not a failed connection.
-        this.clients.delete(sessionId);
-        return {
-          sessionId,
-          success: true,
-        };
-      }
-
-      this.emitConnectionEvent({
-        type: 'error',
-        sessionId,
+    } catch (error) {
+      if (error instanceof UnauthorizedError) {
+        // OAuth-required is a pending-auth state, not a failed connection.
+        this.clients.delete(sessionId);
+        return {
+          sessionId,
+          success: true,
+        };
+      }
+
+      this.emitConnectionEvent({
+        type: 'error',
+        sessionId,
         serverId,
         error: error instanceof Error ? error.message : 'Connection failed',
         errorType: 'connection',
@@ -466,18 +466,18 @@ export class SSEConnectionManager {
   /**
    * Complete OAuth authorization flow
    */
-  private async finishAuth(params: FinishAuthParams): Promise<FinishAuthResult> {
-    const { sessionId, code } = params;
-
-    const session = await storage.getSession(this.identity, sessionId);
-    if (!session) {
-      throw new Error('Session not found');
-    }
-
-    try {
-      const client = new MCPClient({
-        identity: this.identity,
-        sessionId,
+  private async finishAuth(params: FinishAuthParams): Promise<FinishAuthResult> {
+    const { sessionId, code } = params;
+
+    const session = await storage.getSession(this.identity, sessionId);
+    if (!session) {
+      throw new Error('Session not found');
+    }
+
+    try {
+      const client = new MCPClient({
+        identity: this.identity,
+        sessionId,
       });
 
       client.onConnectionEvent((event) => this.emitConnectionEvent(event));
@@ -573,8 +573,8 @@ export class SSEConnectionManager {
  * Create an SSE endpoint handler compatible with Node.js HTTP frameworks.
  * Handles both SSE streaming (GET) and RPC requests (POST).
  */
-export function createSSEHandler(options: SSEHandlerOptions) {
-  return async (req: { method?: string; on: Function }, res: { writeHead: Function; write: Function }) => {
+export function createSSEHandler(options: SSEHandlerOptions) {
+  return async (req: { method?: string; on: Function }, res: { writeHead: Function; write: Function }) => {
     // Set SSE headers
     res.writeHead(200, {
       'Content-Type': 'text/event-stream',
@@ -586,15 +586,15 @@ export function createSSEHandler(options: SSEHandlerOptions) {
     // Send initial connection acknowledgment
     writeSSEEvent(res, 'connected', { timestamp: Date.now() });
 
-    // Create connection manager with event routing
-    const manager = new SSEConnectionManager(options, (event) => {
-      if (isRpcResponseEvent(event)) {
-        writeSSEEvent(res, 'rpc-response', event);
-      } else if (isConnectionEvent(event)) {
-        writeSSEEvent(res, 'connection', event);
-      } else {
-        writeSSEEvent(res, 'observability', event);
-      }
+    // Create connection manager with event routing
+    const manager = new SSEConnectionManager(options, (event) => {
+      if (isRpcResponseEvent(event)) {
+        writeSSEEvent(res, 'rpc-response', event);
+      } else if (isConnectionEvent(event)) {
+        writeSSEEvent(res, 'connection', event);
+      } else {
+        writeSSEEvent(res, 'observability', event);
+      }
     });
 
     // Cleanup on client disconnect
@@ -625,7 +625,7 @@ export function createSSEHandler(options: SSEHandlerOptions) {
 /**
  * Write an SSE event to the response stream
  */
-function writeSSEEvent(res: { write: Function }, event: string, data: unknown): void {
-  res.write(`event: ${event}\n`);
-  res.write(`data: ${JSON.stringify(data)}\n\n`);
-}
+function writeSSEEvent(res: { write: Function }, event: string, data: unknown): void {
+  res.write(`event: ${event}\n`);
+  res.write(`data: ${JSON.stringify(data)}\n\n`);
+}

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

@@ -65,6 +65,7 @@ export class FileStorageBackend implements StorageBackend {
         }
 
         this.initialized = true;
+        console.log(`[mcp-ts][Storage] File: ✓ storage directory at ${path.dirname(this.filePath)} verified.`);
     }
 
     private async ensureInitialized() {

package/src/server/storage/index.ts

@@ -2,12 +2,17 @@
 import { RedisStorageBackend } from './redis-backend';
 import { MemoryStorageBackend } from './memory-backend';
 import { FileStorageBackend } from './file-backend';
-import { SqliteStorage } from './sqlite-backend';
-import type { StorageBackend } from './types';
+import { SqliteStorage } from './sqlite-backend.js';
+import { SupabaseStorageBackend } from './supabase-backend.js';
+import type { StorageBackend } from './types.js';
 
 // Re-export types
-export * from './types';
-export { RedisStorageBackend, MemoryStorageBackend, FileStorageBackend, SqliteStorage };
+export * from './types.js';
+export { RedisStorageBackend, MemoryStorageBackend, FileStorageBackend, SqliteStorage, SupabaseStorageBackend };
+
+export function createSupabaseStorageBackend(client: any): SupabaseStorageBackend {
+    return new SupabaseStorageBackend(client);
+}
 
 let storageInstance: StorageBackend | null = null;
 let storagePromise: Promise<StorageBackend> | null = null;
@@ -30,33 +35,53 @@ async function createStorage(): Promise<StorageBackend> {
         try {
             const { getRedis } = await import('./redis.js');
             const redis = await getRedis();
-            console.log('[Storage] Using Redis storage (Explicit)');
-            return new RedisStorageBackend(redis);
+            console.log('[mcp-ts][Storage] Explicit selection: "redis"');
+            return await initializeStorage(new RedisStorageBackend(redis));
         } catch (error: any) {
-            console.error('[Storage] Failed to initialize Redis:', error.message);
-            console.log('[Storage] Falling back to In-Memory storage');
-            return new MemoryStorageBackend();
+            console.error('[mcp-ts][Storage] Failed to initialize Redis:', error.message);
+            console.log('[mcp-ts][Storage] Falling back to In-Memory storage');
+            return await initializeStorage(new MemoryStorageBackend());
         }
     }
 
     if (type === 'file') {
         const filePath = process.env.MCP_TS_STORAGE_FILE;
-        if (!filePath) {
-            console.warn('[Storage] MCP_TS_STORAGE_TYPE is "file" but MCP_TS_STORAGE_FILE is missing');
-        }
-        console.log(`[Storage] Using File storage (${filePath}) (Explicit)`);
+        console.log(`[mcp-ts][Storage] Explicit selection: "file" (${filePath || 'default'})`);
         return await initializeStorage(new FileStorageBackend({ path: filePath }));
     }
 
     if (type === 'sqlite') {
         const dbPath = process.env.MCP_TS_STORAGE_SQLITE_PATH;
-        console.log(`[Storage] Using SQLite storage (${dbPath || 'default'}) (Explicit)`);
+        console.log(`[mcp-ts][Storage] Explicit selection: "sqlite" (${dbPath || 'default'})`);
         return await initializeStorage(new SqliteStorage({ path: dbPath }));
     }
 
+    if (type === 'supabase') {
+        const url = process.env.SUPABASE_URL;
+        const key = process.env.SUPABASE_SERVICE_ROLE_KEY || process.env.SUPABASE_ANON_KEY;
+        
+        if (!url || !key) {
+            console.warn('[mcp-ts][Storage] Explicit selection "supabase" requires SUPABASE_URL and SUPABASE_SERVICE_ROLE_KEY.');
+        } else {
+            if (!process.env.SUPABASE_SERVICE_ROLE_KEY) {
+                console.warn('[mcp-ts][Storage] ⚠️  Warning: Using "SUPABASE_ANON_KEY" for server-side storage. You may encounter RLS policy violations. "SUPABASE_SERVICE_ROLE_KEY" is recommended.');
+            }
+            try {
+                const { createClient } = await import('@supabase/supabase-js');
+                const client = createClient(url, key);
+                console.log('[mcp-ts][Storage] Explicit selection: "supabase"');
+                return await initializeStorage(new SupabaseStorageBackend(client as any));
+            } catch (error: any) {
+                console.error('[mcp-ts][Storage] Failed to initialize Supabase:', error.message);
+                console.log('[mcp-ts][Storage] Falling back to In-Memory storage');
+                return await initializeStorage(new MemoryStorageBackend());
+            }
+        }
+    }
+
     if (type === 'memory') {
-        console.log('[Storage] Using In-Memory storage (Explicit)');
-        return new MemoryStorageBackend();
+        console.log('[mcp-ts][Storage] Explicit selection: "memory"');
+        return await initializeStorage(new MemoryStorageBackend());
     }
 
     // Automatic inference (Fallback)
@@ -64,27 +89,44 @@ async function createStorage(): Promise<StorageBackend> {
         try {
             const { getRedis } = await import('./redis.js');
             const redis = await getRedis();
-            console.log('[Storage] Auto-detected REDIS_URL. Using Redis storage.');
-            return new RedisStorageBackend(redis);
+            console.log('[mcp-ts][Storage] Auto-detection: "redis" (via REDIS_URL)');
+            return await initializeStorage(new RedisStorageBackend(redis));
         } catch (error: any) {
-            console.error('[Storage] Redis auto-detection failed:', error.message);
-            console.log('[Storage] Falling back to In-Memory storage');
-            return new MemoryStorageBackend();
+            console.error('[mcp-ts][Storage] Redis auto-detection failed:', error.message);
+            console.log('[mcp-ts][Storage] Falling back to next available backend');
         }
     }
 
     if (process.env.MCP_TS_STORAGE_FILE) {
-        console.log(`[Storage] Auto-detected MCP_TS_STORAGE_FILE. Using File storage (${process.env.MCP_TS_STORAGE_FILE}).`);
+        console.log(`[mcp-ts][Storage] Auto-detection: "file" (${process.env.MCP_TS_STORAGE_FILE})`);
         return await initializeStorage(new FileStorageBackend({ path: process.env.MCP_TS_STORAGE_FILE }));
     }
 
     if (process.env.MCP_TS_STORAGE_SQLITE_PATH) {
-        console.log(`[Storage] Auto-detected MCP_TS_STORAGE_SQLITE_PATH. Using SQLite storage (${process.env.MCP_TS_STORAGE_SQLITE_PATH}).`);
+        console.log(`[mcp-ts][Storage] Auto-detection: "sqlite" (${process.env.MCP_TS_STORAGE_SQLITE_PATH})`);
         return await initializeStorage(new SqliteStorage({ path: process.env.MCP_TS_STORAGE_SQLITE_PATH }));
     }
 
-    console.log('[Storage] No storage configured. Using In-Memory storage (Default).');
-    return new MemoryStorageBackend();
+    if (process.env.SUPABASE_URL && (process.env.SUPABASE_SERVICE_ROLE_KEY || process.env.SUPABASE_ANON_KEY)) {
+        try {
+            const { createClient } = await import('@supabase/supabase-js');
+            const url = process.env.SUPABASE_URL;
+            const key = process.env.SUPABASE_SERVICE_ROLE_KEY || process.env.SUPABASE_ANON_KEY!;
+            
+            if (!process.env.SUPABASE_SERVICE_ROLE_KEY) {
+                console.warn('[mcp-ts][Storage] ⚠️ Warning: Using "SUPABASE_ANON_KEY" for server-side storage. You may encounter RLS policy violations. "SUPABASE_SERVICE_ROLE_KEY" is recommended.');
+            }
+
+            const client = createClient(url, key);
+            console.log('[mcp-ts][Storage] Auto-detection: "supabase" (via SUPABASE_URL)');
+            return await initializeStorage(new SupabaseStorageBackend(client as any));
+        } catch (error: any) {
+            console.error('[mcp-ts][Storage] Supabase auto-detection failed:', error.message);
+        }
+    }
+
+    console.log('[mcp-ts][Storage] Defaulting to: "memory"');
+    return await initializeStorage(new MemoryStorageBackend());
 }
 
 async function getStorage(): Promise<StorageBackend> {

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

@@ -27,6 +27,10 @@ export class MemoryStorageBackend implements StorageBackend {
 
     constructor() { }
 
+    async init(): Promise<void> {
+        console.log('[mcp-ts][Storage] Memory: ✓ internal memory store active.');
+    }
+
     private getSessionKey(identity: string, sessionId: string): string {
         return `${identity}:${sessionId}`;
     }

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

@@ -26,6 +26,15 @@ export class RedisStorageBackend implements StorageBackend {
     private readonly IDENTITY_KEY_SUFFIX = ':sessions';
 
     constructor(private redis: Redis) { }
+    
+    async init(): Promise<void> {
+        try {
+            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}`);
+        }
+    }
 
     /**
      * Generates Redis key for a specific session

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

@@ -44,6 +44,7 @@ export class SqliteStorage implements StorageBackend {
             `);
 
             this.initialized = true;
+            console.log(`[mcp-ts][Storage] SQLite: ✓ database at ${this.dbPath} verified.`);
         } catch (error: any) {
             if (error.code === 'MODULE_NOT_FOUND' || error.message?.includes('better-sqlite3')) {
                 throw new Error(