@mcp-ts/sdk 2.4.4 → 2.5.0

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

@@ -4,6 +4,7 @@ import { DORMANT_SESSION_EXPIRATION_MS } from '../../shared/constants.js';
 import { generateSessionId } from '../../shared/utils.js';
 import { encryptObject, decryptObject } from './crypto.js';
 import { resolveSessionExpiresAt } from './session-lifecycle.js';
+import { normalizeToolPolicy } from './tool-policy.js';
 
 export interface NeonStorageOptions {
     schema?: string;
@@ -30,6 +31,7 @@ type NeonSessionRow = {
     headers?: unknown;
     auth_url?: string | null;
     status?: SessionStatus | null;
+    tool_policy?: unknown;
 };
 
 type NeonCredentialsRow = {
@@ -103,6 +105,7 @@ export class NeonStorageBackend implements SessionStore {
             headers: decryptObject(row.headers),
             authUrl: row.auth_url ?? undefined,
             status: row.status ?? 'pending',
+            toolPolicy: normalizeToolPolicy(row.tool_policy as Parameters<typeof normalizeToolPolicy>[0]),
         };
     }
 
@@ -135,43 +138,35 @@ export class NeonStorageBackend implements SessionStore {
         const status = session.status ?? 'pending';
         const createdAt = new Date(session.createdAt || Date.now()).toISOString();
         const updatedAt = new Date(session.updatedAt ?? session.createdAt ?? Date.now()).toISOString();
-        const expiresAt = resolveSessionExpiresAt(status, new Date(createdAt).getTime());
+        const createdAtMs = new Date(createdAt).getTime();
+        const expiresAt = resolveSessionExpiresAt(status, createdAtMs);
+        const toolPolicy = normalizeToolPolicy(session.toolPolicy, createdAtMs);
+
+        const columns: string[] = [
+            'session_id', 'user_id', 'server_id', 'server_name',
+            'server_url', 'transport_type', 'callback_url',
+            'created_at', 'updated_at', 'headers', 'auth_url',
+            'status', 'expires_at',
+        ];
+        const values: unknown[] = [
+            sessionId, userId, session.serverId, session.serverName,
+            session.serverUrl, session.transportType, session.callbackUrl,
+            createdAt, updatedAt, encryptObject(session.headers),
+            session.authUrl ?? null, status,
+            expiresAt === null ? null : new Date(expiresAt).toISOString(),
+        ];
+
+        if (toolPolicy) {
+            columns.push('tool_policy');
+            values.push(toolPolicy);
+        }
+
+        const placeholders = values.map((_, i) => `$${i + 1}`);
 
         try {
             await this.sql.query(
-                `INSERT INTO ${this.tableName} (
-                    session_id,
-                    user_id,
-                    server_id,
-                    server_name,
-                    server_url,
-                    transport_type,
-                    callback_url,
-                    created_at,
-                    updated_at,
-                    headers,
-                    auth_url,
-                    status,
-                    expires_at
-                ) VALUES (
-                    $1, $2, $3, $4, $5, $6, $7, $8,
-                    $9, $10, $11, $12, $13
-                )`,
-                [
-                    sessionId,
-                    userId,
-                    session.serverId,
-                    session.serverName,
-                    session.serverUrl,
-                    session.transportType,
-                    session.callbackUrl,
-                    createdAt,
-                    updatedAt,
-                    encryptObject(session.headers),
-                    session.authUrl ?? null,
-                    status,
-                    expiresAt === null ? null : new Date(expiresAt).toISOString(),
-                ]
+                `INSERT INTO ${this.tableName} (${columns.join(', ')}) VALUES (${placeholders.join(', ')})`,
+                values
             );
         } catch (error: any) {
             if (error.code === '23505') {
@@ -200,38 +195,44 @@ export class NeonStorageBackend implements SessionStore {
             'callbackUrl' in data ||
             'status' in data ||
             'headers' in data ||
-            'authUrl' in data
+            'authUrl' in data ||
+            'toolPolicy' in data
         );
 
         if (shouldUpdateSession) {
+            const setClauses: string[] = [];
+            const values: unknown[] = [];
+            let paramIndex = 1;
+
+            const addSet = (column: string, value: unknown) => {
+                setClauses.push(`${column} = $${paramIndex++}`);
+                values.push(value);
+            };
+
+            addSet('server_id', updatedSession.serverId);
+            addSet('server_name', updatedSession.serverName);
+            addSet('server_url', updatedSession.serverUrl);
+            addSet('transport_type', updatedSession.transportType);
+            addSet('callback_url', updatedSession.callbackUrl);
+            addSet('status', status);
+            addSet('headers', encryptObject(updatedSession.headers));
+            addSet('auth_url', updatedSession.authUrl ?? null);
+            addSet('expires_at', expiresAt === null ? null : new Date(expiresAt).toISOString());
+
+            if ('toolPolicy' in data) {
+                const policyUpdatedAt = updatedSession.updatedAt ?? Date.now();
+                const toolPolicy = normalizeToolPolicy(updatedSession.toolPolicy, policyUpdatedAt) ?? { mode: 'all' as const, toolIds: [], updatedAt: policyUpdatedAt };
+                addSet('tool_policy', toolPolicy);
+            }
+
+            setClauses.push('updated_at = now()');
+
             const updatedRows = await this.sql.query(
                 `UPDATE ${this.tableName}
-                 SET
-                    server_id = $1,
-                    server_name = $2,
-                    server_url = $3,
-                    transport_type = $4,
-                    callback_url = $5,
-                    status = $6,
-                    headers = $7,
-                    auth_url = $8,
-                    expires_at = $9,
-                    updated_at = now()
-                 WHERE user_id = $10 AND session_id = $11
+                 SET ${setClauses.join(', ')}
+                 WHERE user_id = $${paramIndex++} AND session_id = $${paramIndex++}
                  RETURNING id`,
-                [
-                    updatedSession.serverId,
-                    updatedSession.serverName,
-                    updatedSession.serverUrl,
-                    updatedSession.transportType,
-                    updatedSession.callbackUrl,
-                    status,
-                    encryptObject(updatedSession.headers),
-                    updatedSession.authUrl ?? null,
-                    expiresAt === null ? null : new Date(expiresAt).toISOString(),
-                    userId,
-                    sessionId,
-                ]
+                [...values, userId, sessionId]
             ) as Array<{ id: string }>;
 
             if (updatedRows.length === 0) {
@@ -412,3 +413,7 @@ export class NeonStorageBackend implements SessionStore {
         // Neon HTTP queries do not hold a persistent connection.
     }
 }
+
+
+
+

package/src/server/storage/session-lifecycle.ts

@@ -4,6 +4,7 @@ import {
     STATE_EXPIRATION_MS,
 } from '../../shared/constants.js';
 import type { Session, SessionStatus } from './types.js';
+import { normalizeToolPolicy } from './tool-policy.js';
 
 export function resolveSessionExpiresAt(status: SessionStatus = 'pending', referenceTime = Date.now()): number | null {
     return status === 'active' ? null : referenceTime + STATE_EXPIRATION_MS;
@@ -26,6 +27,7 @@ export function normalizeNewSession(session: Session, now = Date.now()): Session
         createdAt,
         updatedAt,
         expiresAt: resolveSessionExpiresAt(status, status === 'active' ? updatedAt : createdAt),
+        toolPolicy: normalizeToolPolicy(session.toolPolicy, updatedAt),
     };
 }
 
@@ -46,6 +48,7 @@ export function mergeSessionUpdate(
         ...updated,
         status,
         expiresAt: resolveSessionExpiresAt(status, updatedAt),
+        toolPolicy: normalizeToolPolicy(updated.toolPolicy, updatedAt),
     };
 }
 
@@ -63,6 +66,7 @@ export function normalizeStoredSession(session: Session): Session {
         createdAt,
         updatedAt,
         expiresAt,
+        toolPolicy: normalizeToolPolicy(session.toolPolicy, updatedAt),
     };
 }
 
@@ -76,3 +80,4 @@ export function isSessionExpired(session: Session, now = Date.now()): boolean {
 
     return typeof hydrated.expiresAt === 'number' && hydrated.expiresAt < now;
 }
+

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

@@ -3,6 +3,7 @@ import type { SessionStore, Session, SessionCredentials } from './types.js';
 import { generateSessionId } from '../../shared/utils.js';
 import { encryptObject, decryptObject } from './crypto.js';
 import { resolveSessionExpiresAt } from './session-lifecycle.js';
+import { normalizeToolPolicy } from './tool-policy.js';
 import { DORMANT_SESSION_EXPIRATION_MS } from '../../shared/constants.js';
 
 export class SupabaseStorageBackend implements SessionStore {
@@ -51,6 +52,7 @@ export class SupabaseStorageBackend implements SessionStore {
             headers: decryptObject(row.headers),
             authUrl: row.auth_url,
             status: row.status ?? 'pending',
+            toolPolicy: normalizeToolPolicy(row.tool_policy),
         };
     }
 
@@ -85,23 +87,30 @@ export class SupabaseStorageBackend implements SessionStore {
         const updatedAt = new Date(session.updatedAt ?? session.createdAt ?? Date.now()).toISOString();
         const expiresAt = resolveSessionExpiresAt(status, new Date(createdAt).getTime());
 
+        const insertData: Record<string, unknown> = {
+            session_id: sessionId,
+            user_id: userId,
+            server_id: session.serverId,
+            server_name: session.serverName,
+            server_url: session.serverUrl,
+            transport_type: session.transportType,
+            callback_url: session.callbackUrl,
+            created_at: createdAt,
+            updated_at: updatedAt,
+            headers: encryptObject(session.headers),
+            auth_url: session.authUrl ?? null,
+            status,
+            expires_at: expiresAt === null ? null : new Date(expiresAt).toISOString(),
+        };
+
+        const toolPolicy = normalizeToolPolicy(session.toolPolicy);
+        if (toolPolicy) {
+            insertData.tool_policy = toolPolicy;
+        }
+
         const { error } = await this.supabase
             .from('mcp_sessions')
-            .insert({
-                session_id: sessionId,
-                user_id: userId,
-                server_id: session.serverId,
-                server_name: session.serverName,
-                server_url: session.serverUrl,
-                transport_type: session.transportType,
-                callback_url: session.callbackUrl,
-                created_at: createdAt,
-                updated_at: updatedAt,
-                headers: encryptObject(session.headers),
-                auth_url: session.authUrl ?? null,
-                status,
-                expires_at: expiresAt === null ? null : new Date(expiresAt).toISOString(),
-            });
+            .insert(insertData);
 
         if (error) {
             if (error.code === '23505') {
@@ -130,6 +139,7 @@ export class SupabaseStorageBackend implements SessionStore {
         }
         if ('headers' in data) updateData.headers = encryptObject(data.headers);
         if ('authUrl' in data) updateData.auth_url = data.authUrl ?? null;
+        if ('toolPolicy' in data) updateData.tool_policy = normalizeToolPolicy(data.toolPolicy);
 
         const shouldUpdateSession = Object.keys(updateData).some((key) => key !== 'updated_at');
 
@@ -351,3 +361,5 @@ export class SupabaseStorageBackend implements SessionStore {
         // Supabase client handles its own connection pooling over HTTP.
     }
 }
+
+

package/src/server/storage/tool-policy.ts

@@ -0,0 +1,89 @@
+import type { Tool } from '@modelcontextprotocol/sdk/types.js';
+import type { ToolPolicy } from './types.js';
+
+export type ToolPolicyInput = {
+    mode?: unknown;
+    toolIds?: unknown;
+    updatedAt?: unknown;
+} | null | undefined;
+
+export function createToolId(serverId: string, toolName: string): string {
+    return `${serverId}::${toolName}`;
+}
+
+function normalizeToolIds(input?: unknown): string[] {
+    if (!Array.isArray(input)) return [];
+
+    return Array.from(new Set(
+        input
+            .filter((id): id is string => typeof id === 'string')
+            .map((id) => id.trim())
+            .filter(Boolean)
+    ));
+}
+
+export function normalizeToolPolicy(input?: ToolPolicyInput, now = Date.now()): ToolPolicy | undefined {
+    if (!input || typeof input !== 'object') {
+        return undefined;
+    }
+
+    const mode = input.mode === 'allowlist' || input.mode === 'denylist'
+        ? input.mode
+        : 'all';
+    const updatedAt = typeof input.updatedAt === 'number' && Number.isFinite(input.updatedAt)
+        ? input.updatedAt
+        : now;
+
+    if (mode === 'all') {
+        return { mode: 'all', toolIds: [], updatedAt };
+    }
+
+    return { mode, toolIds: normalizeToolIds(input.toolIds), updatedAt };
+}
+
+export function normalizeToolPolicyForUpdate(input: ToolPolicyInput, now = Date.now()): ToolPolicy {
+    return normalizeToolPolicy(input, now) ?? { mode: 'all', toolIds: [], updatedAt: now };
+}
+
+export function isToolAllowed(policy: ToolPolicy | undefined, toolName: string, serverId?: string): boolean {
+    if (!policy || policy.mode === 'all') return true;
+    if (!serverId) return false;
+
+    const toolId = createToolId(serverId, toolName);
+    if (policy.mode === 'allowlist') {
+        return policy.toolIds.includes(toolId);
+    }
+
+    return !policy.toolIds.includes(toolId);
+}
+
+export function assertToolAllowed(policy: ToolPolicy | undefined, toolName: string, serverId?: string): void {
+    if (isToolAllowed(policy, toolName, serverId)) return;
+    throw new Error(`Tool "${toolName}" is not allowed for this MCP session`);
+}
+
+export function filterToolsByPolicy<T extends Pick<Tool, 'name'>>(
+    tools: T[],
+    policy: ToolPolicy | undefined,
+    serverId?: string
+): T[] {
+    if (!policy || policy.mode === 'all') return tools;
+    return tools.filter((tool) => isToolAllowed(policy, tool.name, serverId));
+}
+
+export function validateToolPolicyAgainstTools(
+    policy: ToolPolicy,
+    tools: Array<Pick<Tool, 'name'>>,
+    serverId?: string
+): void {
+    if (policy.mode === 'all') return;
+    if (!serverId) {
+        throw new Error('Cannot validate MCP tool policy without a serverId');
+    }
+
+    const availableIds = new Set(tools.map((tool) => createToolId(serverId, tool.name)));
+    const unknownIds = policy.toolIds.filter((id) => !availableIds.has(id));
+    if (unknownIds.length > 0) {
+        throw new Error(`Unknown tool id(s) for this MCP session: ${unknownIds.join(', ')}`);
+    }
+}

package/src/server/storage/types.ts

@@ -14,6 +14,14 @@ export interface OAuthState {
 
 export type SessionStatus = 'pending' | 'active';
 
+export type ToolPolicyMode = 'all' | 'allowlist' | 'denylist';
+
+export interface ToolPolicy {
+    mode: ToolPolicyMode;
+    toolIds: string[];
+    updatedAt: number;
+}
+
 export interface Session {
     sessionId: string;
     serverId?: string; // Database server ID for mapping
@@ -37,6 +45,7 @@ export interface Session {
      * - active: restorable session after successful connection/auth completion
      */
     status?: SessionStatus;
+    toolPolicy?: ToolPolicy;
 }
 
 export interface SessionCredentials {
@@ -158,3 +167,5 @@ export interface SessionStore {
      */
     disconnect(): Promise<void>;
 }
+
+

package/src/shared/types.ts

@@ -21,6 +21,7 @@ export interface ToolClient {
   callTool(name: string, args: Record<string, unknown>): Promise<any>;
   getServerId?(): string | undefined;
   getServerName?(): string | undefined;
+  getServerUrl?(): string | undefined;
   getSessionId?(): string;
 }
 
@@ -169,6 +170,13 @@ export type ToolInfo = {
 // Transport type
 export type TransportType = 'sse' | 'streamable-http';
 export type SessionStatus = 'pending' | 'active';
+export type ToolPolicyMode = 'all' | 'allowlist' | 'denylist';
+
+export interface ToolPolicy {
+  mode: ToolPolicyMode;
+  toolIds: string[];
+  updatedAt: number;
+}
 
 // SSE/RPC types
 export type McpRpcMethod =
@@ -182,7 +190,9 @@ export type McpRpcMethod =
   | 'listPrompts'
   | 'getPrompt'
   | 'listResources'
-  | 'readResource';
+  | 'readResource'
+  | 'setToolPolicy'
+  | 'getToolPolicy';
 
 export interface McpRpcRequest {
   id: string;
@@ -239,6 +249,18 @@ export interface FinishAuthParams {
   code: string;
 }
 
+export interface SetToolPolicyParams {
+  sessionId: string;
+  toolPolicy: {
+    mode: ToolPolicyMode;
+    toolIds?: string[];
+  };
+}
+
+export interface GetToolPolicyParams {
+  sessionId: string;
+}
+
 export type McpRpcParams =
   | ConnectParams
   | DisconnectParams
@@ -247,6 +269,8 @@ export type McpRpcParams =
   | GetPromptParams
   | ReadResourceParams
   | FinishAuthParams
+  | SetToolPolicyParams
+  | GetToolPolicyParams
   | undefined;
 
 // RPC Result Types
@@ -263,6 +287,7 @@ export interface SessionInfo {
    * `pending` means auth is in progress and should be resumed explicitly by user action.
    */
   status: SessionStatus;
+  toolPolicy?: ToolPolicy;
 }
 
 export interface SessionListResult {
@@ -292,6 +317,25 @@ export interface ListToolsRpcResult {
   tools: Tool[];
 }
 
+export interface SetToolPolicyResult {
+  success: boolean;
+  toolPolicy: ToolPolicy;
+  tools: Tool[];
+  toolCount: number;
+}
+
+export type ToolAccessInfo = Tool & {
+  toolId: string;
+  allowed: boolean;
+};
+
+export interface GetToolPolicyResult {
+  toolPolicy: ToolPolicy;
+  tools: ToolAccessInfo[];
+  toolCount: number;
+  allowedToolCount: number;
+}
+
 export interface ListPromptsResult {
   prompts: Array<{
     name: string;
@@ -314,3 +358,6 @@ export interface ListResourcesResult {
 }
 
 export type { CallToolResult };
+
+
+

package/src/shared/utils.ts

@@ -1,17 +1,10 @@
-import { customAlphabet } from 'nanoid';
+import { customAlphabet, nanoid } from 'nanoid';
 
 const OAUTH_STATE_SEPARATOR = '.';
 
-/** first char: letters only (required by OpenAI) */
-const firstChar = customAlphabet(
-    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz',
-    1
-);
-
-/** remaining chars: alphanumeric */
-const rest = customAlphabet(
-    'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789',
-    11
+const serverIdAlphabet = customAlphabet(
+    'abcdefghijklmnopqrstuvwxyz0123456789',
+    12
 );
 
 /**
@@ -32,11 +25,20 @@ export function sanitizeServerLabel(name: string): string {
 }
 
 /**
- * Generates a standard 12-character session ID compliant with external tool restrictions.
- * First character is always a letter.
+ * Generates a session ID with a human-readable prefix for easy identification.
+ * Format: sess_<21-char nanoid> (26 chars total).
+ * Not used in tool names, so length is not constrained.
  */
 export function generateSessionId(): string {
-    return firstChar() + rest();
+    return 'sess_' + nanoid(21);
+}
+
+/**
+ * Generates a short server ID suitable for use in tool names.
+ * 12-char alphanumeric string that keeps tool_<serverId>_<toolName> under 64 chars.
+ */
+export function generateServerId(): string {
+    return serverIdAlphabet();
 }
 
 export interface ParsedOAuthState {