@mcp-ts/sdk 2.4.0 → 2.4.2

package/dist/{tool-router-CuApsDiV.d.mts → tool-router-CbG4Tum6.d.mts}

@@ -1,5 +1,5 @@
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import { u as ToolClientProvider, T as ToolClient } from './types-DCk_IF4L.mjs';
+import { A as ToolClientProvider, T as ToolClient } from './types-CjczQwNX.mjs';
 
 /**
  * ToolIndex — Lightweight in-memory search index for MCP tool discovery.

package/dist/{tool-router-CZMrOG8J.d.ts → tool-router-ChIhPwgP.d.ts}

@@ -1,5 +1,5 @@
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import { u as ToolClientProvider, T as ToolClient } from './types-DCk_IF4L.js';
+import { A as ToolClientProvider, T as ToolClient } from './types-CjczQwNX.js';
 
 /**
  * ToolIndex — Lightweight in-memory search index for MCP tool discovery.

package/dist/{types-DCk_IF4L.d.ts → types-CjczQwNX.d.mts}

@@ -1,5 +1,126 @@
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 
+/**
+ * Simple event emitter pattern for MCP connection events
+ * Inspired by Cloudflare's agents pattern but adapted for serverless
+ */
+type Disposable = {
+    dispose(): void;
+};
+type Event<T> = (listener: (event: T) => void) => Disposable;
+/**
+ * Event emitter class for type-safe event handling
+ * Similar to Cloudflare's Emitter but simplified for our use case
+ */
+declare class Emitter<T> {
+    private listeners;
+    /**
+     * Subscribe to events
+     * @param listener - Callback function to handle events
+     * @returns Disposable to unsubscribe
+     */
+    get event(): Event<T>;
+    /**
+     * Fire an event to all listeners
+     * @param event - Event data to emit
+     */
+    fire(event: T): void;
+    /**
+     * Clear all listeners
+     */
+    dispose(): void;
+    /**
+     * Get number of active listeners
+     */
+    get listenerCount(): number;
+}
+/**
+ * Connection state types matching your existing ConnectionStatus
+ * Extended with more granular states for better observability
+ */
+type McpConnectionState = 'DISCONNECTED' | 'CONNECTING' | 'AUTHENTICATING' | 'AUTHENTICATED' | 'DISCOVERING' | 'CONNECTED' | 'READY' | 'VALIDATING' | 'RECONNECTING' | 'INITIALIZING' | 'FAILED';
+/**
+ * MCP Connection Event Types
+ * Discriminated union for type-safe event handling
+ */
+type McpConnectionEvent = {
+    type: 'state_changed';
+    sessionId: string;
+    serverId: string;
+    serverName: string;
+    serverUrl: string;
+    createdAt?: number;
+    state: McpConnectionState;
+    previousState: McpConnectionState;
+    timestamp: number;
+} | {
+    type: 'tools_discovered';
+    sessionId: string;
+    serverId: string;
+    toolCount: number;
+    tools: any[];
+    timestamp: number;
+} | {
+    type: 'auth_required';
+    sessionId: string;
+    serverId: string;
+    authUrl: string;
+    timestamp: number;
+} | {
+    type: 'error';
+    sessionId: string;
+    serverId: string;
+    error: string;
+    errorType: 'connection' | 'auth' | 'validation' | 'unknown';
+    timestamp: number;
+} | {
+    type: 'disconnected';
+    sessionId: string;
+    serverId: string;
+    timestamp: number;
+} | {
+    type: 'progress';
+    sessionId: string;
+    serverId: string;
+    message: string;
+    timestamp: number;
+};
+/**
+ * Event fired when a tool execution returns a UI resource URI
+ */
+interface McpAppsUIEvent {
+    type: 'mcp-apps-ui';
+    sessionId: string;
+    resourceUri: string;
+    toolName: string;
+    result: unknown;
+    timestamp: number;
+}
+/**
+ * Observability event for debugging and monitoring
+ */
+interface McpObservabilityEvent {
+    type?: string;
+    level?: 'debug' | 'info' | 'warn' | 'error';
+    message?: string;
+    displayMessage?: string;
+    sessionId?: string;
+    serverId?: string;
+    payload?: Record<string, any>;
+    metadata?: Record<string, any>;
+    timestamp: number;
+    id?: string;
+}
+/**
+ * DisposableStore for managing multiple disposables
+ * Useful for cleanup in React hooks
+ */
+declare class DisposableStore {
+    private disposables;
+    add(disposable: Disposable): void;
+    dispose(): void;
+}
+
 /**
  * Type definitions for MCP operations
  */
@@ -186,4 +307,4 @@ interface ListResourcesResult {
     }>;
 }
 
-export { isConnectSuccess as A, isListToolsSuccess as B, type CallToolParams as C, type DisconnectParams as D, type FinishAuthParams as F, type GetPromptParams as G, type ListPromptsResult as L, type McpRpcMethod as M, type ReadResourceParams as R, type SessionInfo as S, type ToolClient as T, type CallToolRequest as a, type CallToolResponse as b, type ConnectAuthRequiredResponse as c, type ConnectErrorResponse as d, type ConnectParams as e, type ConnectRequest as f, type ConnectResponse as g, type ConnectResult as h, type ConnectSuccessResponse as i, type DisconnectResult as j, type FinishAuthResult as k, type GetSessionResult as l, type ListResourcesResult as m, type ListToolsResponse as n, type ListToolsRpcResult as o, type McpRpcParams as p, type McpRpcRequest as q, type McpRpcResponse as r, type SessionListResult as s, type SessionParams as t, type ToolClientProvider as u, type ToolInfo as v, type TransportType as w, isCallToolSuccess as x, isConnectAuthRequired as y, isConnectError as z };
+export { type ToolClientProvider as A, type ToolInfo as B, type CallToolParams as C, type DisconnectParams as D, Emitter as E, type FinishAuthParams as F, type GetPromptParams as G, type TransportType as H, isCallToolSuccess as I, isConnectAuthRequired as J, isConnectError as K, type ListPromptsResult as L, type McpConnectionEvent as M, isConnectSuccess as N, isListToolsSuccess as O, type McpAppsUIEvent as P, type ReadResourceParams as R, type SessionInfo as S, type ToolClient as T, type CallToolRequest as a, type CallToolResponse as b, type ConnectAuthRequiredResponse as c, type ConnectErrorResponse as d, type ConnectParams as e, type ConnectRequest as f, type ConnectResponse as g, type ConnectResult as h, type ConnectSuccessResponse as i, type DisconnectResult as j, type Disposable as k, DisposableStore as l, type Event as m, type FinishAuthResult as n, type GetSessionResult as o, type ListResourcesResult as p, type ListToolsResponse as q, type ListToolsRpcResult as r, type McpConnectionState as s, type McpObservabilityEvent as t, type McpRpcMethod as u, type McpRpcParams as v, type McpRpcRequest as w, type McpRpcResponse as x, type SessionListResult as y, type SessionParams as z };

package/dist/{types-DCk_IF4L.d.mts → types-CjczQwNX.d.ts}

@@ -1,5 +1,126 @@
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
 
+/**
+ * Simple event emitter pattern for MCP connection events
+ * Inspired by Cloudflare's agents pattern but adapted for serverless
+ */
+type Disposable = {
+    dispose(): void;
+};
+type Event<T> = (listener: (event: T) => void) => Disposable;
+/**
+ * Event emitter class for type-safe event handling
+ * Similar to Cloudflare's Emitter but simplified for our use case
+ */
+declare class Emitter<T> {
+    private listeners;
+    /**
+     * Subscribe to events
+     * @param listener - Callback function to handle events
+     * @returns Disposable to unsubscribe
+     */
+    get event(): Event<T>;
+    /**
+     * Fire an event to all listeners
+     * @param event - Event data to emit
+     */
+    fire(event: T): void;
+    /**
+     * Clear all listeners
+     */
+    dispose(): void;
+    /**
+     * Get number of active listeners
+     */
+    get listenerCount(): number;
+}
+/**
+ * Connection state types matching your existing ConnectionStatus
+ * Extended with more granular states for better observability
+ */
+type McpConnectionState = 'DISCONNECTED' | 'CONNECTING' | 'AUTHENTICATING' | 'AUTHENTICATED' | 'DISCOVERING' | 'CONNECTED' | 'READY' | 'VALIDATING' | 'RECONNECTING' | 'INITIALIZING' | 'FAILED';
+/**
+ * MCP Connection Event Types
+ * Discriminated union for type-safe event handling
+ */
+type McpConnectionEvent = {
+    type: 'state_changed';
+    sessionId: string;
+    serverId: string;
+    serverName: string;
+    serverUrl: string;
+    createdAt?: number;
+    state: McpConnectionState;
+    previousState: McpConnectionState;
+    timestamp: number;
+} | {
+    type: 'tools_discovered';
+    sessionId: string;
+    serverId: string;
+    toolCount: number;
+    tools: any[];
+    timestamp: number;
+} | {
+    type: 'auth_required';
+    sessionId: string;
+    serverId: string;
+    authUrl: string;
+    timestamp: number;
+} | {
+    type: 'error';
+    sessionId: string;
+    serverId: string;
+    error: string;
+    errorType: 'connection' | 'auth' | 'validation' | 'unknown';
+    timestamp: number;
+} | {
+    type: 'disconnected';
+    sessionId: string;
+    serverId: string;
+    timestamp: number;
+} | {
+    type: 'progress';
+    sessionId: string;
+    serverId: string;
+    message: string;
+    timestamp: number;
+};
+/**
+ * Event fired when a tool execution returns a UI resource URI
+ */
+interface McpAppsUIEvent {
+    type: 'mcp-apps-ui';
+    sessionId: string;
+    resourceUri: string;
+    toolName: string;
+    result: unknown;
+    timestamp: number;
+}
+/**
+ * Observability event for debugging and monitoring
+ */
+interface McpObservabilityEvent {
+    type?: string;
+    level?: 'debug' | 'info' | 'warn' | 'error';
+    message?: string;
+    displayMessage?: string;
+    sessionId?: string;
+    serverId?: string;
+    payload?: Record<string, any>;
+    metadata?: Record<string, any>;
+    timestamp: number;
+    id?: string;
+}
+/**
+ * DisposableStore for managing multiple disposables
+ * Useful for cleanup in React hooks
+ */
+declare class DisposableStore {
+    private disposables;
+    add(disposable: Disposable): void;
+    dispose(): void;
+}
+
 /**
  * Type definitions for MCP operations
  */
@@ -186,4 +307,4 @@ interface ListResourcesResult {
     }>;
 }
 
-export { isConnectSuccess as A, isListToolsSuccess as B, type CallToolParams as C, type DisconnectParams as D, type FinishAuthParams as F, type GetPromptParams as G, type ListPromptsResult as L, type McpRpcMethod as M, type ReadResourceParams as R, type SessionInfo as S, type ToolClient as T, type CallToolRequest as a, type CallToolResponse as b, type ConnectAuthRequiredResponse as c, type ConnectErrorResponse as d, type ConnectParams as e, type ConnectRequest as f, type ConnectResponse as g, type ConnectResult as h, type ConnectSuccessResponse as i, type DisconnectResult as j, type FinishAuthResult as k, type GetSessionResult as l, type ListResourcesResult as m, type ListToolsResponse as n, type ListToolsRpcResult as o, type McpRpcParams as p, type McpRpcRequest as q, type McpRpcResponse as r, type SessionListResult as s, type SessionParams as t, type ToolClientProvider as u, type ToolInfo as v, type TransportType as w, isCallToolSuccess as x, isConnectAuthRequired as y, isConnectError as z };
+export { type ToolClientProvider as A, type ToolInfo as B, type CallToolParams as C, type DisconnectParams as D, Emitter as E, type FinishAuthParams as F, type GetPromptParams as G, type TransportType as H, isCallToolSuccess as I, isConnectAuthRequired as J, isConnectError as K, type ListPromptsResult as L, type McpConnectionEvent as M, isConnectSuccess as N, isListToolsSuccess as O, type McpAppsUIEvent as P, type ReadResourceParams as R, type SessionInfo as S, type ToolClient as T, type CallToolRequest as a, type CallToolResponse as b, type ConnectAuthRequiredResponse as c, type ConnectErrorResponse as d, type ConnectParams as e, type ConnectRequest as f, type ConnectResponse as g, type ConnectResult as h, type ConnectSuccessResponse as i, type DisconnectResult as j, type Disposable as k, DisposableStore as l, type Event as m, type FinishAuthResult as n, type GetSessionResult as o, type ListResourcesResult as p, type ListToolsResponse as q, type ListToolsRpcResult as r, type McpConnectionState as s, type McpObservabilityEvent as t, type McpRpcMethod as u, type McpRpcParams as v, type McpRpcRequest as w, type McpRpcResponse as x, type SessionListResult as y, type SessionParams as z };

package/migrations/v2.3.4/neon/20260513010000_install_mcp_sessions.sql

@@ -0,0 +1,69 @@
+-- Create the mcp_sessions table for Neon Postgres.
+-- Run this with an owner/admin role, then grant app access with the least-privilege SQL below.
+
+CREATE TABLE IF NOT EXISTS public.mcp_sessions (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    session_id TEXT NOT NULL UNIQUE,
+    user_id TEXT NOT NULL,
+    server_id TEXT,
+    server_name TEXT,
+    server_url TEXT NOT NULL,
+    transport_type TEXT NOT NULL,
+    callback_url TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    expires_at TIMESTAMPTZ NOT NULL,
+    active BOOLEAN DEFAULT false,
+    headers JSONB,
+    client_information JSONB,
+    tokens JSONB,
+    code_verifier TEXT,
+    client_id TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_mcp_sessions_user_id ON public.mcp_sessions(user_id);
+CREATE INDEX IF NOT EXISTS idx_mcp_sessions_expires_at ON public.mcp_sessions(expires_at);
+
+CREATE OR REPLACE FUNCTION public.set_current_timestamp_updated_at()
+RETURNS TRIGGER AS $$
+BEGIN
+  NEW.updated_at = now();
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS trg_mcp_sessions_updated_at ON public.mcp_sessions;
+
+CREATE TRIGGER trg_mcp_sessions_updated_at
+BEFORE UPDATE ON public.mcp_sessions
+FOR EACH ROW
+EXECUTE FUNCTION public.set_current_timestamp_updated_at();
+
+-- Optional production configuration:
+-- Create a dedicated app role and use its credentials in NEON_DATABASE_URL.
+-- Replace neondb and the password before running.
+--
+-- CREATE ROLE mcp_service_role LOGIN PASSWORD 'replace-with-a-strong-password';
+-- GRANT CONNECT ON DATABASE neondb TO mcp_service_role;
+-- GRANT USAGE ON SCHEMA public TO mcp_service_role;
+-- GRANT SELECT, INSERT, UPDATE, DELETE ON public.mcp_sessions TO mcp_service_role;
+-- GRANT USAGE ON ALL SEQUENCES IN SCHEMA public TO mcp_service_role;
+
+-- Optional RLS configuration:
+-- Uncomment and run this block after creating mcp_service_role if you want
+-- to enforce access through Row Level Security for the dedicated app role.
+--
+-- REVOKE ALL ON public.mcp_sessions FROM PUBLIC;
+-- REVOKE ALL ON ALL SEQUENCES IN SCHEMA public FROM PUBLIC;
+--
+-- GRANT SELECT, INSERT, UPDATE, DELETE ON public.mcp_sessions TO mcp_service_role;
+-- GRANT USAGE ON ALL SEQUENCES IN SCHEMA public TO mcp_service_role;
+--
+-- ALTER TABLE public.mcp_sessions ENABLE ROW LEVEL SECURITY;
+--
+-- CREATE POLICY mcp_service_role_full_access
+-- ON public.mcp_sessions
+-- FOR ALL
+-- TO mcp_service_role
+-- USING (true)
+-- WITH CHECK (true);

package/migrations/v2.3.4/neon/20260513020000_add_session_cleanup_cron.sql

@@ -0,0 +1,35 @@
+-- Optional Neon pg_cron cleanup jobs.
+--
+-- Neon pg_cron requires endpoint-level setup before this migration can run:
+-- configure cron.database_name for your compute endpoint, restart the compute,
+-- then install/schedule jobs from the target database.
+--
+-- If pg_cron is not enabled for your Neon project, skip this migration and run
+-- storage.cleanupExpiredSessions() from your application scheduler instead.
+
+CREATE EXTENSION IF NOT EXISTS pg_cron;
+
+-- Keep reruns idempotent without NOTICE noise.
+SELECT cron.unschedule(jobname)
+FROM cron.job
+WHERE jobname IN (
+  'mcp-cleanup-transient-sessions',
+  'mcp-cleanup-dormant-sessions'
+);
+
+-- Stage 1: Short-term Transient Purge (every 5 minutes)
+-- Removes failed connections, abandoned OAuth flows, and other inactive
+-- sessions whose TTL has expired.
+SELECT cron.schedule(
+    'mcp-cleanup-transient-sessions',
+    '*/5 * * * *',
+    $$DELETE FROM public.mcp_sessions WHERE expires_at < now() AND active IS NOT TRUE;$$
+);
+
+-- Stage 2: Long-term Dormancy Eviction (daily at midnight UTC)
+-- Removes active sessions that have not been touched for 30+ days.
+SELECT cron.schedule(
+    'mcp-cleanup-dormant-sessions',
+    '0 0 * * *',
+    $$DELETE FROM public.mcp_sessions WHERE active = true AND updated_at < now() - interval '30 days';$$
+);

package/migrations/v2.3.4/supabase/20260330195700_install_mcp_sessions.sql

@@ -0,0 +1,82 @@
+-- Create the mcp_sessions table
+CREATE TABLE IF NOT EXISTS public.mcp_sessions (
+    id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
+    session_id TEXT NOT NULL UNIQUE,
+    user_id TEXT NOT NULL, -- Will store the application user's ID
+    server_id TEXT,
+    server_name TEXT,
+    server_url TEXT NOT NULL,
+    transport_type TEXT NOT NULL,
+    callback_url TEXT NOT NULL,
+    created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+    expires_at TIMESTAMPTZ NOT NULL,
+    active BOOLEAN DEFAULT false,
+    headers JSONB,
+    client_information JSONB,
+    tokens JSONB,
+    code_verifier TEXT,
+    client_id TEXT
+);
+
+-- Add an index on user_id for faster lookups
+CREATE INDEX IF NOT EXISTS idx_mcp_sessions_user_id ON public.mcp_sessions(user_id);
+-- Add an index on expires_at to speed up the cleanup job
+CREATE INDEX IF NOT EXISTS idx_mcp_sessions_expires_at ON public.mcp_sessions(expires_at);
+
+-- Trigger to automatically update the 'updated_at' column
+CREATE OR REPLACE FUNCTION public.set_current_timestamp_updated_at()
+RETURNS TRIGGER AS $$
+BEGIN
+  NEW.updated_at = now();
+  RETURN NEW;
+END;
+$$ LANGUAGE plpgsql;
+
+DROP TRIGGER IF EXISTS trg_mcp_sessions_updated_at ON public.mcp_sessions;
+CREATE TRIGGER trg_mcp_sessions_updated_at
+BEFORE UPDATE ON public.mcp_sessions
+FOR EACH ROW
+EXECUTE FUNCTION public.set_current_timestamp_updated_at();
+
+-- Enable Row Level Security (RLS)
+ALTER TABLE public.mcp_sessions ENABLE ROW LEVEL SECURITY;
+
+-- Policy 1: Users can read their own sessions
+CREATE POLICY "Users can view their own sessions"
+ON public.mcp_sessions
+FOR SELECT
+TO authenticated
+USING (
+    auth.uid()::text = user_id
+);
+
+-- Policy 2: Users can insert their own sessions
+CREATE POLICY "Users can insert their own sessions"
+ON public.mcp_sessions
+FOR INSERT
+TO authenticated
+WITH CHECK (
+    auth.uid()::text = user_id
+);
+
+-- Policy 3: Users can update their own sessions
+CREATE POLICY "Users can update their own sessions"
+ON public.mcp_sessions
+FOR UPDATE
+TO authenticated
+USING (
+    auth.uid()::text = user_id
+)
+WITH CHECK (
+    auth.uid()::text = user_id
+);
+
+-- Policy 4: Users can delete their own sessions
+CREATE POLICY "Users can delete their own sessions"
+ON public.mcp_sessions
+FOR DELETE
+TO authenticated
+USING (
+    auth.uid()::text = user_id
+);

package/migrations/v2.3.4/supabase/20260421010000_add_session_cleanup_cron.sql

@@ -0,0 +1,32 @@
+-- Enable the pg_cron extension (available on all Supabase plans).
+-- This is idempotent and safe to run multiple times.
+CREATE EXTENSION IF NOT EXISTS pg_cron;
+
+-- -----------------------------------------------------------------------------
+-- Stage 1: Short-term Transient Purge (every 5 minutes)
+-- -----------------------------------------------------------------------------
+-- Targets sessions that are NOT active (failed connections, abandoned OAuth
+-- flows, mid-flow errors) whose TTL has expired. Active sessions are explicitly
+-- excluded from this sweep to preserve automation credentials.
+--
+-- The idx_mcp_sessions_expires_at index ensures this is a fast indexed scan.
+SELECT cron.schedule(
+    'cleanup-transient-sessions',
+    '*/5 * * * *',
+    $$DELETE FROM public.mcp_sessions WHERE expires_at < now() AND active IS NOT TRUE;$$
+);
+
+-- -----------------------------------------------------------------------------
+-- Stage 2: Long-term Dormancy Eviction (daily at midnight UTC)
+-- -----------------------------------------------------------------------------
+-- Safety net for sessions that were successfully established (active = true)
+-- but have been completely untouched for 30+ days. This prevents "active"
+-- records from persisting indefinitely if they are genuinely abandoned.
+SELECT cron.schedule(
+    'cleanup-dormant-sessions',
+    '0 0 * * *',
+    $$DELETE FROM public.mcp_sessions WHERE active = true AND updated_at < now() - interval '30 days';$$
+);
+
+-- Add a comment on the extension for visibility in Supabase Dashboard
+COMMENT ON EXTENSION pg_cron IS 'Automated Session Lifecycle Management.';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mcp-ts/sdk",
-  "version": "2.4.0",
+  "version": "2.4.2",
   "publishConfig": {
     "access": "public"
   },

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

@@ -356,8 +356,8 @@ export class SSEConnectionManager {
     const client = this.clients.get(sessionId);
 
     if (client) {
+      // clearSession() handles DELETE + local cleanup internally.
       await client.clearSession();
-      client.disconnect();
       this.clients.delete(sessionId);
     } else {
       // Handle orphaned sessions (e.g., OAuth flow failed before client was stored)
@@ -606,16 +606,18 @@ export class SSEConnectionManager {
   /**
    * Cleanup and close all connections
    */
-  dispose(): void {
+  async dispose(): Promise<void> {
     this.isActive = false;
 
     if (this.heartbeatTimer) {
       clearInterval(this.heartbeatTimer);
     }
 
-    for (const client of this.clients.values()) {
-      client.disconnect();
-    }
+    // Send HTTP DELETE to each Streamable HTTP server before closing, per spec.
+    // Run in parallel so shutdown is not serialised across many sessions.
+    await Promise.all(
+      Array.from(this.clients.values()).map((client) => client.disconnect())
+    );
 
     this.clients.clear();
   }