@mcp-ts/sdk 1.6.2 → 2.0.0

package/dist/{tool-router-Dh2804tM.d.ts → tool-router-Ddtybmr0.d.ts}

@@ -1,57 +1,5 @@
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import { u as ToolClientProvider, T as ToolClient } from './types-rIuN1CQi.js';
-
-/**
- * SchemaCompressor — Utilities for reducing tool schema token overhead.
- *
- * Provides compact representations of tools (name + description only,
- * no inputSchema) and token savings estimation.
- *
- * @packageDocumentation
- */
-
-/**
- * A minimal tool representation containing only what an LLM needs to
- * *decide whether* to use a tool.  The full `inputSchema` is deferred.
- */
-interface CompactTool {
-    name: string;
-    description?: string;
-    /**
-     * Human-readable hint about the expected parameters.
-     * e.g. "(location: string, unit?: 'celsius' | 'fahrenheit')"
-     */
-    parameterHint?: string;
-}
-interface CompressionStats {
-    /** Estimated tokens for the *full* tool list. */
-    fullTokens: number;
-    /** Estimated tokens for the *compact* tool list. */
-    compactTokens: number;
-    /** Absolute token savings. */
-    savedTokens: number;
-    /** Percentage savings as a human-readable string, e.g. "82.3%". */
-    savingsPercent: string;
-}
-declare class SchemaCompressor {
-    /**
-     * Convert a full MCP Tool definition to a compact summary.
-     *
-     * The compact form omits `inputSchema` entirely and optionally generates
-     * a short `parameterHint` from the schema's top-level properties.
-     */
-    static toCompact(tool: Tool): CompactTool;
-    /**
-     * Convert an array of tools to compact form, optionally limiting the count.
-     */
-    static compactAll(tools: Tool[], options?: {
-        maxTools?: number;
-    }): CompactTool[];
-    /**
-     * Estimate token savings from using compact vs full tool schemas.
-     */
-    static estimateSavings(tools: Tool[]): CompressionStats;
-}
+import { u as ToolClientProvider, T as ToolClient } from './types-BCAG20P6.js';
 
 /**
  * ToolIndex — Lightweight in-memory search index for MCP tool discovery.
@@ -77,8 +25,6 @@ interface ToolSummary {
     serverId: string;
     /** Session the tool belongs to */
     sessionId: string;
-    /** Estimated token cost of the full inputSchema */
-    estimatedTokens: number;
 }
 /** Server-level summary derived from indexed tools. */
 interface ToolServerSummary {
@@ -163,8 +109,6 @@ declare class ToolIndex {
     private docLengths;
     /** BM25: average document length across the entire index. */
     private avgDocLength;
-    /** Cached total estimated token cost across all indexed tools. */
-    private totalTokenCost;
     private options;
     constructor(options?: ToolIndexOptions);
     /**
@@ -203,17 +147,11 @@ declare class ToolIndex {
     }): ToolListResult;
     /** Number of indexed tools (including duplicates). */
     get size(): number;
-    /** Total estimated token cost of all indexed tool schemas. */
-    getTotalTokenCost(): number;
-    /**
-     * Estimate token count of a tool's full schema (name + description + inputSchema).
-     *
-     * Uses character-class weighted counting calibrated against cl100k_base.
-     * Accuracy is typically within ±10% for JSON Schema payloads.
-     */
-    static estimateTokens(tool: Tool): number;
     /** Build a single searchable string from tool metadata. */
     private buildSearchableText;
+    /** Recursively collect JSON Schema argument names and descriptions. */
+    private collectSchemaSearchText;
+    private pushStringValue;
     private getDocumentKey;
     private matchesServer;
     /** Simple whitespace + camelCase + snake_case tokenizer. */
@@ -222,6 +160,72 @@ declare class ToolIndex {
     private cosineSimilarity;
 }
 
+/**
+ * SchemaCompressor — Utilities for compact tool representations.
+ *
+ * Provides compact representations of tools (name + description only,
+ * no inputSchema).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * A minimal tool representation containing only what an LLM needs to
+ * *decide whether* to use a tool.  The full `inputSchema` is deferred.
+ */
+interface CompactTool {
+    name: string;
+    description?: string;
+    /**
+     * Human-readable hint about the expected parameters.
+     * e.g. "(location: string, unit?: 'celsius' | 'fahrenheit')"
+     */
+    parameterHint?: string;
+}
+declare class SchemaCompressor {
+    /**
+     * Convert a full MCP Tool definition to a compact summary.
+     *
+     * The compact form omits `inputSchema` entirely and optionally generates
+     * a short `parameterHint` from the schema's top-level properties.
+     */
+    static toCompact(tool: Tool): CompactTool;
+    /**
+     * Convert an array of tools to compact form, optionally limiting the count.
+     */
+    static compactAll(tools: Tool[], options?: {
+        maxTools?: number;
+    }): CompactTool[];
+}
+
+/**
+ * ToolRouter — Middleware layer for intelligent MCP tool selection.
+ *
+ * Sits between your AI framework adapter and MultiSessionClient to reduce
+ * context window usage. Supports three strategies:
+ *
+ *  • `all`    — Pass through every tool (backward-compatible default)
+ *  • `search` — Expose only meta-tools; LLM discovers tools on-demand
+ *  • `groups` — Expose tools from active groups only
+ *
+ * Inspired by Anthropic's `defer_loading` + `tool_search_tool` pattern.
+ *
+ * @example
+ * ```ts
+ * import { ToolRouter } from '@mcp-ts/sdk/shared';
+ * import { AIAdapter } from '@mcp-ts/sdk/adapters/ai';
+ *
+ * const router = new ToolRouter(multiSessionClient, {
+ *   strategy: 'search',
+ *   maxTools: 5,
+ * });
+ *
+ * const tools = await AIAdapter.getTools(multiSessionClient, { toolRouter: router });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
 type ToolRouterStrategy = 'all' | 'search' | 'groups';
 interface ToolRouterOptions {
     /**
@@ -340,12 +344,6 @@ declare class ToolRouter {
     setActiveGroups(groups: string[]): void;
     /** Get the names of currently active groups. */
     getActiveGroups(): string[];
-    /** Total token cost of all tools if loaded without filtering. */
-    getTotalTokenCost(): number;
-    /** Estimate token cost of the currently filtered tool set. */
-    getFilteredTokenCost(): Promise<number>;
-    /** Get compression stats showing savings from current strategy. */
-    getCompressionStats(): CompressionStats;
     /** Number of total indexed tools. */
     get totalToolCount(): number;
     /** Change strategy at runtime. */
@@ -374,4 +372,4 @@ declare class ToolRouter {
     private getMetaToolDefinitions;
 }
 
-export { type CompactTool as C, type EmbedFn as E, type IndexedTool as I, SchemaCompressor as S, type ToolGroupInfo as T, type CompressionStats as a, ToolIndex as b, type ToolIndexOptions as c, type ToolListResult as d, ToolRouter as e, type ToolRouterClientInput as f, type ToolRouterOptions as g, type ToolRouterStrategy as h, type ToolSearchOptions as i, type ToolServerSummary as j, type ToolSummary as k };
+export { type CompactTool as C, type EmbedFn as E, type IndexedTool as I, SchemaCompressor as S, type ToolGroupInfo as T, ToolIndex as a, type ToolIndexOptions as b, type ToolListResult as c, ToolRouter as d, type ToolRouterClientInput as e, type ToolRouterOptions as f, type ToolRouterStrategy as g, type ToolSearchOptions as h, type ToolServerSummary as i, type ToolSummary as j };

package/dist/{tool-router-BVaV1udm.d.mts → tool-router-Dnd6IOKC.d.mts}

@@ -1,57 +1,5 @@
 import { Tool } from '@modelcontextprotocol/sdk/types.js';
-import { u as ToolClientProvider, T as ToolClient } from './types-rIuN1CQi.mjs';
-
-/**
- * SchemaCompressor — Utilities for reducing tool schema token overhead.
- *
- * Provides compact representations of tools (name + description only,
- * no inputSchema) and token savings estimation.
- *
- * @packageDocumentation
- */
-
-/**
- * A minimal tool representation containing only what an LLM needs to
- * *decide whether* to use a tool.  The full `inputSchema` is deferred.
- */
-interface CompactTool {
-    name: string;
-    description?: string;
-    /**
-     * Human-readable hint about the expected parameters.
-     * e.g. "(location: string, unit?: 'celsius' | 'fahrenheit')"
-     */
-    parameterHint?: string;
-}
-interface CompressionStats {
-    /** Estimated tokens for the *full* tool list. */
-    fullTokens: number;
-    /** Estimated tokens for the *compact* tool list. */
-    compactTokens: number;
-    /** Absolute token savings. */
-    savedTokens: number;
-    /** Percentage savings as a human-readable string, e.g. "82.3%". */
-    savingsPercent: string;
-}
-declare class SchemaCompressor {
-    /**
-     * Convert a full MCP Tool definition to a compact summary.
-     *
-     * The compact form omits `inputSchema` entirely and optionally generates
-     * a short `parameterHint` from the schema's top-level properties.
-     */
-    static toCompact(tool: Tool): CompactTool;
-    /**
-     * Convert an array of tools to compact form, optionally limiting the count.
-     */
-    static compactAll(tools: Tool[], options?: {
-        maxTools?: number;
-    }): CompactTool[];
-    /**
-     * Estimate token savings from using compact vs full tool schemas.
-     */
-    static estimateSavings(tools: Tool[]): CompressionStats;
-}
+import { u as ToolClientProvider, T as ToolClient } from './types-BCAG20P6.mjs';
 
 /**
  * ToolIndex — Lightweight in-memory search index for MCP tool discovery.
@@ -77,8 +25,6 @@ interface ToolSummary {
     serverId: string;
     /** Session the tool belongs to */
     sessionId: string;
-    /** Estimated token cost of the full inputSchema */
-    estimatedTokens: number;
 }
 /** Server-level summary derived from indexed tools. */
 interface ToolServerSummary {
@@ -163,8 +109,6 @@ declare class ToolIndex {
     private docLengths;
     /** BM25: average document length across the entire index. */
     private avgDocLength;
-    /** Cached total estimated token cost across all indexed tools. */
-    private totalTokenCost;
     private options;
     constructor(options?: ToolIndexOptions);
     /**
@@ -203,17 +147,11 @@ declare class ToolIndex {
     }): ToolListResult;
     /** Number of indexed tools (including duplicates). */
     get size(): number;
-    /** Total estimated token cost of all indexed tool schemas. */
-    getTotalTokenCost(): number;
-    /**
-     * Estimate token count of a tool's full schema (name + description + inputSchema).
-     *
-     * Uses character-class weighted counting calibrated against cl100k_base.
-     * Accuracy is typically within ±10% for JSON Schema payloads.
-     */
-    static estimateTokens(tool: Tool): number;
     /** Build a single searchable string from tool metadata. */
     private buildSearchableText;
+    /** Recursively collect JSON Schema argument names and descriptions. */
+    private collectSchemaSearchText;
+    private pushStringValue;
     private getDocumentKey;
     private matchesServer;
     /** Simple whitespace + camelCase + snake_case tokenizer. */
@@ -222,6 +160,72 @@ declare class ToolIndex {
     private cosineSimilarity;
 }
 
+/**
+ * SchemaCompressor — Utilities for compact tool representations.
+ *
+ * Provides compact representations of tools (name + description only,
+ * no inputSchema).
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * A minimal tool representation containing only what an LLM needs to
+ * *decide whether* to use a tool.  The full `inputSchema` is deferred.
+ */
+interface CompactTool {
+    name: string;
+    description?: string;
+    /**
+     * Human-readable hint about the expected parameters.
+     * e.g. "(location: string, unit?: 'celsius' | 'fahrenheit')"
+     */
+    parameterHint?: string;
+}
+declare class SchemaCompressor {
+    /**
+     * Convert a full MCP Tool definition to a compact summary.
+     *
+     * The compact form omits `inputSchema` entirely and optionally generates
+     * a short `parameterHint` from the schema's top-level properties.
+     */
+    static toCompact(tool: Tool): CompactTool;
+    /**
+     * Convert an array of tools to compact form, optionally limiting the count.
+     */
+    static compactAll(tools: Tool[], options?: {
+        maxTools?: number;
+    }): CompactTool[];
+}
+
+/**
+ * ToolRouter — Middleware layer for intelligent MCP tool selection.
+ *
+ * Sits between your AI framework adapter and MultiSessionClient to reduce
+ * context window usage. Supports three strategies:
+ *
+ *  • `all`    — Pass through every tool (backward-compatible default)
+ *  • `search` — Expose only meta-tools; LLM discovers tools on-demand
+ *  • `groups` — Expose tools from active groups only
+ *
+ * Inspired by Anthropic's `defer_loading` + `tool_search_tool` pattern.
+ *
+ * @example
+ * ```ts
+ * import { ToolRouter } from '@mcp-ts/sdk/shared';
+ * import { AIAdapter } from '@mcp-ts/sdk/adapters/ai';
+ *
+ * const router = new ToolRouter(multiSessionClient, {
+ *   strategy: 'search',
+ *   maxTools: 5,
+ * });
+ *
+ * const tools = await AIAdapter.getTools(multiSessionClient, { toolRouter: router });
+ * ```
+ *
+ * @packageDocumentation
+ */
+
 type ToolRouterStrategy = 'all' | 'search' | 'groups';
 interface ToolRouterOptions {
     /**
@@ -340,12 +344,6 @@ declare class ToolRouter {
     setActiveGroups(groups: string[]): void;
     /** Get the names of currently active groups. */
     getActiveGroups(): string[];
-    /** Total token cost of all tools if loaded without filtering. */
-    getTotalTokenCost(): number;
-    /** Estimate token cost of the currently filtered tool set. */
-    getFilteredTokenCost(): Promise<number>;
-    /** Get compression stats showing savings from current strategy. */
-    getCompressionStats(): CompressionStats;
     /** Number of total indexed tools. */
     get totalToolCount(): number;
     /** Change strategy at runtime. */
@@ -374,4 +372,4 @@ declare class ToolRouter {
     private getMetaToolDefinitions;
 }
 
-export { type CompactTool as C, type EmbedFn as E, type IndexedTool as I, SchemaCompressor as S, type ToolGroupInfo as T, type CompressionStats as a, ToolIndex as b, type ToolIndexOptions as c, type ToolListResult as d, ToolRouter as e, type ToolRouterClientInput as f, type ToolRouterOptions as g, type ToolRouterStrategy as h, type ToolSearchOptions as i, type ToolServerSummary as j, type ToolSummary as k };
+export { type CompactTool as C, type EmbedFn as E, type IndexedTool as I, SchemaCompressor as S, type ToolGroupInfo as T, ToolIndex as a, type ToolIndexOptions as b, type ToolListResult as c, ToolRouter as d, type ToolRouterClientInput as e, type ToolRouterOptions as f, type ToolRouterStrategy as g, type ToolSearchOptions as h, type ToolServerSummary as i, type ToolSummary as j };

package/dist/{types-rIuN1CQi.d.mts → types-BCAG20P6.d.mts}

@@ -81,8 +81,8 @@ type ToolInfo = {
     description?: string;
     inputSchema?: unknown;
 };
-type TransportType = 'sse' | 'streamable_http';
-type McpRpcMethod = 'connect' | 'disconnect' | 'listTools' | 'callTool' | 'getSessions' | 'restoreSession' | 'finishAuth' | 'listPrompts' | 'getPrompt' | 'listResources' | 'readResource';
+type TransportType = 'sse' | 'streamable-http';
+type McpRpcMethod = 'connect' | 'disconnect' | 'listTools' | 'callTool' | 'listSessions' | 'getSession' | 'finishAuth' | 'listPrompts' | 'getPrompt' | 'listResources' | 'readResource';
 interface McpRpcRequest {
     id: string;
     method: McpRpcMethod;
@@ -152,7 +152,7 @@ interface ConnectResult {
 interface DisconnectResult {
     success: boolean;
 }
-interface RestoreSessionResult {
+interface GetSessionResult {
     success: boolean;
     toolCount: number;
 }
@@ -183,4 +183,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 ListResourcesResult as l, type ListToolsResponse as m, type ListToolsRpcResult as n, type McpRpcParams as o, type McpRpcRequest as p, type McpRpcResponse as q, type RestoreSessionResult 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 { 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 };

package/dist/{types-rIuN1CQi.d.ts → types-BCAG20P6.d.ts}

@@ -81,8 +81,8 @@ type ToolInfo = {
     description?: string;
     inputSchema?: unknown;
 };
-type TransportType = 'sse' | 'streamable_http';
-type McpRpcMethod = 'connect' | 'disconnect' | 'listTools' | 'callTool' | 'getSessions' | 'restoreSession' | 'finishAuth' | 'listPrompts' | 'getPrompt' | 'listResources' | 'readResource';
+type TransportType = 'sse' | 'streamable-http';
+type McpRpcMethod = 'connect' | 'disconnect' | 'listTools' | 'callTool' | 'listSessions' | 'getSession' | 'finishAuth' | 'listPrompts' | 'getPrompt' | 'listResources' | 'readResource';
 interface McpRpcRequest {
     id: string;
     method: McpRpcMethod;
@@ -152,7 +152,7 @@ interface ConnectResult {
 interface DisconnectResult {
     success: boolean;
 }
-interface RestoreSessionResult {
+interface GetSessionResult {
     success: boolean;
     toolCount: number;
 }
@@ -183,4 +183,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 ListResourcesResult as l, type ListToolsResponse as m, type ListToolsRpcResult as n, type McpRpcParams as o, type McpRpcRequest as p, type McpRpcResponse as q, type RestoreSessionResult 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 { 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 };

package/dist/{utils-0qmYrqoa.d.mts → utils-DELRKQPU.d.mts}

@@ -75,7 +75,7 @@ declare class ToolExecutionError extends McpError {
  */
 declare const RpcErrorCodes: {
     readonly EXECUTION_ERROR: "EXECUTION_ERROR";
-    readonly MISSING_IDENTITY: "MISSING_IDENTITY";
+    readonly MISSING_USER_ID: "MISSING_USER_ID";
     readonly UNAUTHORIZED: "UNAUTHORIZED";
     readonly NO_CONNECTION: "NO_CONNECTION";
     readonly UNKNOWN_METHOD: "UNKNOWN_METHOD";

package/dist/{utils-0qmYrqoa.d.ts → utils-DELRKQPU.d.ts}

@@ -75,7 +75,7 @@ declare class ToolExecutionError extends McpError {
  */
 declare const RpcErrorCodes: {
     readonly EXECUTION_ERROR: "EXECUTION_ERROR";
-    readonly MISSING_IDENTITY: "MISSING_IDENTITY";
+    readonly MISSING_USER_ID: "MISSING_USER_ID";
     readonly UNAUTHORIZED: "UNAUTHORIZED";
     readonly NO_CONNECTION: "NO_CONNECTION";
     readonly UNKNOWN_METHOD: "UNKNOWN_METHOD";

package/migrations/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/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/{supabase/migrations → migrations/supabase}/20260330195700_install_mcp_sessions.sql

@@ -2,7 +2,7 @@
 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 Next.js user's ID or identity
+    user_id TEXT NOT NULL, -- Will store the application user's ID
     server_id TEXT,
     server_name TEXT,
     server_url TEXT NOT NULL,
@@ -12,7 +12,6 @@ CREATE TABLE IF NOT EXISTS public.mcp_sessions (
     updated_at TIMESTAMPTZ NOT NULL DEFAULT now(),
     expires_at TIMESTAMPTZ NOT NULL,
     active BOOLEAN DEFAULT false,
-    identity TEXT NOT NULL,
     headers JSONB,
     client_information JSONB,
     tokens JSONB,
@@ -20,8 +19,7 @@ CREATE TABLE IF NOT EXISTS public.mcp_sessions (
     client_id TEXT
 );
 
--- Add an index on identity and user_id for faster lookups
-CREATE INDEX IF NOT EXISTS idx_mcp_sessions_identity ON public.mcp_sessions(identity);
+-- 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);
@@ -50,7 +48,7 @@ ON public.mcp_sessions
 FOR SELECT
 TO authenticated
 USING (
-    auth.uid()::text = user_id OR auth.uid()::text = identity
+    auth.uid()::text = user_id
 );
 
 -- Policy 2: Users can insert their own sessions
@@ -59,7 +57,7 @@ ON public.mcp_sessions
 FOR INSERT
 TO authenticated
 WITH CHECK (
-    auth.uid()::text = user_id OR auth.uid()::text = identity
+    auth.uid()::text = user_id
 );
 
 -- Policy 3: Users can update their own sessions
@@ -68,10 +66,10 @@ ON public.mcp_sessions
 FOR UPDATE
 TO authenticated
 USING (
-    auth.uid()::text = user_id OR auth.uid()::text = identity
+    auth.uid()::text = user_id
 )
 WITH CHECK (
-    auth.uid()::text = user_id OR auth.uid()::text = identity
+    auth.uid()::text = user_id
 );
 
 -- Policy 4: Users can delete their own sessions
@@ -80,5 +78,5 @@ ON public.mcp_sessions
 FOR DELETE
 TO authenticated
 USING (
-    auth.uid()::text = user_id OR auth.uid()::text = identity
+    auth.uid()::text = user_id
 );