@mcp-ts/sdk 2.5.1 → 2.5.2

package/dist/{tool-router-CUSSk6lT.d.ts → tool-router-C-Mw1_BQ.d.ts}

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

package/dist/{tool-router-C9ECn3FX.d.mts → tool-router-CsKVXbQB.d.mts}

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

package/dist/{types-CbFbPkfQ.d.mts → types-6SmXege4.d.mts}

@@ -57,6 +57,7 @@ type McpConnectionEvent = {
     serverId: string;
     toolCount: number;
     tools: any[];
+    allTools?: any[];
     timestamp: number;
 } | {
     type: 'auth_required';

package/dist/{types-CbFbPkfQ.d.ts → types-6SmXege4.d.ts}

@@ -57,6 +57,7 @@ type McpConnectionEvent = {
     serverId: string;
     toolCount: number;
     tools: any[];
+    allTools?: any[];
     timestamp: number;
 } | {
     type: 'auth_required';

package/package.json

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

package/src/client/react/use-mcp.ts

@@ -371,7 +371,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
           }
 
           return prev.map((c: McpConnection) =>
-            c.sessionId === event.sessionId ? { ...c, tools: event.tools, state: 'READY', updatedAt: new Date() } : c
+            c.sessionId === event.sessionId ? { ...c, tools: event.tools, allTools: (event as any).allTools, state: 'READY', updatedAt: new Date() } : c
           );
         }
 

package/src/client/vue/use-mcp.ts

@@ -84,6 +84,7 @@ export interface McpConnection {
     transport?: string;
     state: McpConnectionState;
     tools: ToolInfo[];
+    allTools?: ToolInfo[];
     authUrl?: string;
     error?: string;
     createdAt?: Date;
@@ -294,7 +295,7 @@ export function useMcp(options: UseMcpOptions): McpClient {
             case 'tools_discovered': {
                 const index = connections.value.findIndex((c) => c.sessionId === event.sessionId);
                 if (index !== -1) {
-                    connections.value[index] = { ...connections.value[index], tools: event.tools, state: 'READY', updatedAt: new Date() };
+                    connections.value[index] = { ...connections.value[index], tools: event.tools, allTools: (event as any).allTools, state: 'READY', updatedAt: new Date() };
                 }
                 break;
             }

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

@@ -508,6 +508,22 @@ export class SSEConnectionManager {
     return client;
   }
 
+  /**
+   * Fetches all tools from the remote MCP server and emits a `tools_discovered` event.
+   *
+   * Two lists are always published together:
+   * - `tools`    — policy-filtered list that agents are allowed to call.
+   * - `allTools` — the complete, unfiltered list used by the management UI so
+   *                that blocked tools still appear as checkboxes in the dialog.
+   *
+   * `fetchTools()` is called first (populates the in-memory cache), then
+   * `gateway.listTools()` re-uses that cache internally — so only one remote
+   * network round-trip is made regardless of how many callers follow.
+   *
+   * @param sessionId - The session whose tools should be discovered.
+   * @returns The session record and the policy-filtered tool list.
+   * @throws {Error} When the session does not exist in the store.
+   */
   private async listPolicyFilteredTools(sessionId: string): Promise<{ session: Session; result: ListToolsRpcResult }> {
     const session = await sessions.get(this.userId, sessionId);
     if (!session) {
@@ -515,6 +531,7 @@ export class SSEConnectionManager {
     }
 
     const client = await this.getOrCreateClient(sessionId);
+    const allTools = await client.fetchTools().catch(() => ({ tools: [] }));
     const gateway = createToolPolicyGateway(this.userId, sessionId, client);
     const result = await gateway.listTools();
 
@@ -524,13 +541,17 @@ export class SSEConnectionManager {
       serverId: session.serverId ?? 'unknown',
       toolCount: result.tools.length,
       tools: result.tools,
+      allTools: allTools.tools,
       timestamp: Date.now(),
     });
 
     return { session, result };
   }
+
   /**
-   * List tools from a session
+   * Returns the policy-filtered tool list for a session (agent-facing).
+   * Internally re-uses `listPolicyFilteredTools` which also emits a
+   * `tools_discovered` SSE event to keep client state up to date.
    */
   private async listTools(params: SessionParams): Promise<ListToolsRpcResult> {
     const { sessionId } = params;
@@ -571,7 +592,15 @@ export class SSEConnectionManager {
   }
 
   /**
-   * Update per-session tool access policy.
+   * Persists a new tool access policy for a session and broadcasts the updated
+   * filtered tool list to all connected browser clients via a `tools_discovered` event.
+   *
+   * Both `tools` (policy-filtered) and `allTools` (complete list) are emitted
+   * so the management UI can immediately reflect the new checkbox states without
+   * an additional round-trip to the server.
+   *
+   * @param params - Session ID and the new `{ mode, toolIds }` policy to apply.
+   * @throws {Error} When the session does not exist or the policy references unknown tool IDs.
    */
   private async setToolPolicy(params: SetToolPolicyParams): Promise<SetToolPolicyResult> {
     const { sessionId } = params;
@@ -594,6 +623,7 @@ export class SSEConnectionManager {
       serverId: session.serverId ?? 'unknown',
       toolCount: filteredTools.length,
       tools: filteredTools,
+      allTools: allTools.tools,
       timestamp: Date.now(),
     });
 
@@ -604,8 +634,10 @@ export class SSEConnectionManager {
       toolCount: filteredTools.length,
     };
   }
+
   /**
-   * Call a tool on the MCP server
+   * Proxies a tool invocation to the remote MCP server.
+   * Resolves the client for the given session and delegates to the tool router.
    */
   private async callTool(params: CallToolParams): Promise<CallToolResult> {
     const { sessionId, toolName, toolArgs } = params;

package/src/server/mcp/oauth-client.ts

@@ -509,13 +509,20 @@ export class MCPClient {
   }
 
   /**
-   * Connects to the MCP server
-   * Automatically validates and refreshes OAuth tokens if needed
-   * Saves session to Redis on first successful connection
-   * @throws {UnauthorizedError} When OAuth authorization is required
-   * @throws {Error} When connection fails for other reasons
+   * Connects to the MCP server.
+   *
+   * Automatically validates and refreshes OAuth tokens if needed.
+   * Saves the session to Redis on first successful connection.
+   *
+   * The in-memory tools cache (`cachedTools`) is cleared at the start of every
+   * call so that a reconnection always fetches a fresh tool list from the remote
+   * server — even if the same `MCPClient` instance is reused.
+   *
+   * @throws {UnauthorizedError} When OAuth authorization is required.
+   * @throws {Error} When connection fails for other reasons.
    */
   async connect(): Promise<void> {
+    this.cachedTools = null;
     // Close any existing transport so we can negotiate a fresh session.
     // The SDK Client throws if asked to connect() while a transport is
     // already attached; close() detaches it cleanly so the same Client
@@ -782,18 +789,41 @@ export class MCPClient {
   }
 
   /**
-   * Lists all available tools from the connected MCP server without emitting discovery events.
-   * Gateways use this to apply policy before publishing tools to agents or UI state.
+   * In-memory cache for the remote server's full tools list.
+   *
+   * Populated on the first `fetchTools()` call and reused for the lifetime of
+   * the connection. Cleared to `null` at the start of `connect()` so that a
+   * reconnect always retrieves a fresh list, and also in `dispose()` to release
+   * the memory when the client is no longer needed.
+   */
+  private cachedTools: ListToolsResult | null = null;
+
+  /**
+   * Lists all available tools from the connected MCP server without emitting
+   * discovery events. The result is cached in memory for the lifetime of the
+   * connection — subsequent callers (e.g. `gateway.listTools()` running right
+   * after `fetchTools()`) pay zero extra network cost.
+   *
+   * Gateways use this to apply a tool-access policy before publishing the
+   * filtered list to agents or UI state.
+   *
+   * @returns The full `ListToolsResult` from the remote server.
+   * @throws {Error} When the client is not connected or the request times out.
    */
   async fetchTools(): Promise<ListToolsResult> {
+    if (this.cachedTools) {
+      return this.cachedTools;
+    }
     const request: ListToolsRequest = {
       method: 'tools/list',
       params: {},
     };
 
-    return await this.withRetry(() =>
+    const result = await this.withRetry(() =>
       this.client!.request(request, ListToolsResultSchema)
     );
+    this.cachedTools = result;
+    return result;
   }
 
   /**
@@ -1119,10 +1149,14 @@ export class MCPClient {
   }
 
   /**
-   * Dispose of all event emitters
-   * Call this when the client is no longer needed
+   * Disposes all event emitters and releases cached state.
+   *
+   * Clears `cachedTools` to free memory, and disposes the connection and
+   * observability event emitters so downstream listeners are unsubscribed.
+   * Call this when the client is permanently shut down (not just disconnected).
    */
   dispose(): void {
+    this.cachedTools = null;
     this._onConnectionEvent.dispose();
     this._onObservabilityEvent.dispose();
   }
@@ -1177,14 +1211,4 @@ export class MCPClient {
   getSessionId(): string {
     return this.sessionId;
   }
-
 }
-
-
-
-
-
-
-
-
-

package/src/server/mcp/tool-policy-gateway.ts

@@ -4,12 +4,27 @@ import { sessions } from '../storage/index.js';
 import type { Session } from '../storage/types.js';
 import { assertToolAllowed, filterToolsByPolicy } from '../storage/tool-policy.js';
 
+/**
+ * Internal shape expected from the underlying MCP client.
+ * Extends `ToolClient` with the raw `fetchTools` / `listTools` / `callTool`
+ * methods so the gateway can fetch unfiltered results and apply policy on top.
+ */
 type RawToolClient = ToolClient & {
     fetchTools(): Promise<{ tools: Tool[] }>;
     listTools(): Promise<{ tools: Tool[] }>;
     callTool(name: string, args: Record<string, unknown>): Promise<CallToolResult>;
 };
 
+/**
+ * A thin policy-enforcement layer that wraps a raw `MCPClient`.
+ *
+ * Every public method on this class loads the current session's `toolPolicy`
+ * from the session store and uses it to filter or guard tool access before
+ * delegating to the underlying client.
+ *
+ * This keeps security logic in one place and prevents agents from calling
+ * tools that a user has explicitly blocked via the management UI.
+ */
 export class ToolPolicyGateway implements ToolClient {
     constructor(
         private readonly userId: string,
@@ -17,26 +32,52 @@ export class ToolPolicyGateway implements ToolClient {
         private readonly client: RawToolClient
     ) {}
 
+    /**
+     * Returns whether the underlying MCP client transport is currently connected.
+     */
     isConnected(): boolean {
         return this.client.isConnected();
     }
 
+    /**
+     * Returns the server ID from the underlying client, if available.
+     */
     getServerId(): string | undefined {
         return this.client.getServerId?.();
     }
 
+    /**
+     * Returns the human-readable server name from the underlying client, if available.
+     */
     getServerName(): string | undefined {
         return this.client.getServerName?.();
     }
 
+    /**
+     * Returns the server URL from the underlying client, if available.
+     */
     getServerUrl(): string | undefined {
         return this.client.getServerUrl?.();
     }
 
+    /**
+     * Returns the session ID — prefers the value reported by the underlying
+     * client, falling back to the one injected at construction time.
+     */
     getSessionId(): string {
         return this.client.getSessionId?.() ?? this.sessionId;
     }
 
+    /**
+     * Returns the **policy-filtered** list of tools that the current session
+     * is allowed to call.
+     *
+     * Internally calls `client.fetchTools()` (which is cache-backed) so no
+     * extra network round-trip is incurred when called after `fetchTools()`.
+     *
+     * @returns A `ListToolsResult` containing only the permitted tools.
+     * @throws {Error} When the session does not exist in the store.
+     */
     async listTools(): Promise<ListToolsResult> {
         const session = await this.getSession();
         const result = await this.client.fetchTools();
@@ -48,24 +89,65 @@ export class ToolPolicyGateway implements ToolClient {
         } as ListToolsResult;
     }
 
+    /**
+     * Returns the **complete, unfiltered** list of tools from the remote server,
+     * bypassing any tool-access policy.
+     *
+     * Used by the management UI to show all available tools (including blocked
+     * ones) so users can toggle individual tool access in the dialog.
+     *
+     * @returns The raw `ListToolsResult` from the remote server.
+     */
     async listAllTools(): Promise<ListToolsResult> {
         return await this.client.fetchTools() as ListToolsResult;
     }
 
+    /**
+     * Executes a tool call on the remote server after verifying that the tool
+     * is permitted by the current session's policy.
+     *
+     * @param name - The exact tool name to invoke.
+     * @param args - Key/value arguments to pass to the tool.
+     * @returns The tool's `CallToolResult`.
+     * @throws {Error} When the tool is blocked by the session's policy.
+     * @throws {Error} When the session does not exist in the store.
+     */
     async callTool(name: string, args: Record<string, unknown>): Promise<CallToolResult> {
         const session = await this.getSession();
         this.assertAllowed(session, name);
         return await this.client.callTool(name, args);
     }
 
+    /**
+     * Filters a raw tools array down to only those permitted by the session's
+     * `toolPolicy`.
+     *
+     * @param session - The session whose policy should be applied.
+     * @param tools   - The unfiltered list of tools from the remote server.
+     * @returns A subset of `tools` that the policy allows.
+     */
     filterTools(session: Session, tools: Tool[]): Tool[] {
         return filterToolsByPolicy(tools, session.toolPolicy, this.getPolicyServerId(session));
     }
 
+    /**
+     * Throws if `toolName` is blocked by the session's policy.
+     * Call this before proxying a `callTool` request to the remote server.
+     *
+     * @param session  - The session whose policy should be enforced.
+     * @param toolName - The tool being invoked.
+     * @throws {Error} When the tool is not permitted.
+     */
     assertAllowed(session: Session, toolName: string): void {
         assertToolAllowed(session.toolPolicy, toolName, this.getPolicyServerId(session));
     }
 
+    /**
+     * Loads the session from the store and throws if it does not exist.
+     *
+     * @returns The fully-hydrated `Session` record.
+     * @throws {Error} When the session cannot be found.
+     */
     private async getSession(): Promise<Session> {
         const session = await sessions.get(this.userId, this.sessionId);
         if (!session) {
@@ -74,11 +156,27 @@ export class ToolPolicyGateway implements ToolClient {
         return session;
     }
 
+    /**
+     * Resolves the server ID to use when evaluating tool policy.
+     * Prefers the value from the live client (most accurate) and falls back
+     * to the server ID stored on the session record.
+     */
     private getPolicyServerId(session: Session): string | undefined {
         return this.client.getServerId?.() ?? session.serverId;
     }
 }
 
+/**
+ * Factory function that creates a `ToolPolicyGateway` for a specific session.
+ *
+ * Prefer this over constructing `ToolPolicyGateway` directly — it keeps call
+ * sites concise and makes it easier to swap the implementation in tests.
+ *
+ * @param userId    - The owner of the session (used for storage lookups).
+ * @param sessionId - The session to enforce policy for.
+ * @param client    - The raw MCP client that the gateway wraps.
+ * @returns A fully configured `ToolPolicyGateway` instance.
+ */
 export function createToolPolicyGateway(
     userId: string,
     sessionId: string,
@@ -86,5 +184,3 @@ export function createToolPolicyGateway(
 ): ToolPolicyGateway {
     return new ToolPolicyGateway(userId, sessionId, client);
 }
-
-

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

@@ -1,16 +1,42 @@
 import type { Tool } from '@modelcontextprotocol/sdk/types.js';
 import type { ToolPolicy } from './types.js';
 
+/**
+ * Raw, unvalidated shape of a tool policy as it may arrive from an external
+ * source (HTTP request body, database read, etc.). All fields are typed as
+ * `unknown` so callers are forced to pass through one of the `normalize*`
+ * helpers before using the value as a `ToolPolicy`.
+ */
 export type ToolPolicyInput = {
     mode?: unknown;
     toolIds?: unknown;
     updatedAt?: unknown;
 } | null | undefined;
 
+/**
+ * Constructs the canonical tool ID string used throughout the policy system.
+ *
+ * Tool IDs combine the server ID and the tool name with a `::` separator so
+ * they are globally unique across all connected MCP servers:
+ * ```
+ * "mn0v3pfwwbxv::delete_mcp_server"
+ * ```
+ *
+ * @param serverId  - The short server identifier (e.g. `"mn0v3pfwwbxv"`).
+ * @param toolName  - The exact tool name as reported by the remote server.
+ * @returns A namespaced tool ID string.
+ */
 export function createToolId(serverId: string, toolName: string): string {
     return `${serverId}::${toolName}`;
 }
 
+/**
+ * Coerces an arbitrary value into a deduplicated array of trimmed, non-empty
+ * strings. Returns an empty array for any non-array or invalid input.
+ *
+ * @param input - Raw value to normalise (typically from user input or a DB read).
+ * @returns A clean `string[]` with duplicates and blank entries removed.
+ */
 function normalizeToolIds(input?: unknown): string[] {
     if (!Array.isArray(input)) return [];
 
@@ -22,6 +48,18 @@ function normalizeToolIds(input?: unknown): string[] {
     ));
 }
 
+/**
+ * Converts a raw, potentially untrusted `ToolPolicyInput` into a validated
+ * `ToolPolicy` object, or `undefined` if the input is absent / malformed.
+ *
+ * - Invalid `mode` values fall back to `"all"` (no restrictions).
+ * - Invalid `updatedAt` values fall back to `now`.
+ * - `"all"` mode always produces an empty `toolIds` array regardless of input.
+ *
+ * @param input - Raw policy data to normalise (from request body, DB, etc.).
+ * @param now   - Unix timestamp used as the fallback for `updatedAt`. Defaults to `Date.now()`.
+ * @returns A well-formed `ToolPolicy`, or `undefined` if `input` is absent.
+ */
 export function normalizeToolPolicy(input?: ToolPolicyInput, now = Date.now()): ToolPolicy | undefined {
     if (!input || typeof input !== 'object') {
         return undefined;
@@ -41,10 +79,39 @@ export function normalizeToolPolicy(input?: ToolPolicyInput, now = Date.now()):
     return { mode, toolIds: normalizeToolIds(input.toolIds), updatedAt };
 }
 
+/**
+ * Same as `normalizeToolPolicy` but guaranteed to return a `ToolPolicy`.
+ * Falls back to an unrestricted `{ mode: "all" }` policy when the input is
+ * absent or invalid.
+ *
+ * Use this variant when a policy is required (e.g. when persisting an update)
+ * rather than when reading an optional policy from the session store.
+ *
+ * @param input - Raw policy data to normalise.
+ * @param now   - Unix timestamp used as the fallback for `updatedAt`. Defaults to `Date.now()`.
+ * @returns A well-formed `ToolPolicy`, never `undefined`.
+ */
 export function normalizeToolPolicyForUpdate(input: ToolPolicyInput, now = Date.now()): ToolPolicy {
     return normalizeToolPolicy(input, now) ?? { mode: 'all', toolIds: [], updatedAt: now };
 }
 
+/**
+ * Determines whether a specific tool is permitted under the given policy.
+ *
+ * | Policy mode  | Allowed when…                                    |
+ * |--------------|--------------------------------------------------|
+ * | `"all"`      | Always (no restrictions).                        |
+ * | `"allowlist"`| The tool's ID is present in `policy.toolIds`.    |
+ * | `"denylist"` | The tool's ID is **not** in `policy.toolIds`.    |
+ *
+ * Returns `false` when the policy requires a `serverId` for ID construction
+ * but none is provided (fail-safe / deny by default).
+ *
+ * @param policy   - The active tool policy, or `undefined` for unrestricted access.
+ * @param toolName - The tool name to check (as reported by the remote server).
+ * @param serverId - The server that owns the tool (required for `allowlist`/`denylist`).
+ * @returns `true` if the tool is allowed, `false` otherwise.
+ */
 export function isToolAllowed(policy: ToolPolicy | undefined, toolName: string, serverId?: string): boolean {
     if (!policy || policy.mode === 'all') return true;
     if (!serverId) return false;
@@ -57,11 +124,33 @@ export function isToolAllowed(policy: ToolPolicy | undefined, toolName: string,
     return !policy.toolIds.includes(toolId);
 }
 
+/**
+ * Asserts that a tool call is permitted under the current session policy.
+ * Throws a descriptive error if the tool is blocked — call this inside
+ * `ToolPolicyGateway.callTool` before proxying the request to the remote server.
+ *
+ * @param policy   - The active tool policy, or `undefined` for unrestricted access.
+ * @param toolName - The tool being invoked.
+ * @param serverId - The server that owns the tool.
+ * @throws {Error} When the tool is not permitted by the policy.
+ */
 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`);
 }
 
+/**
+ * Returns the subset of `tools` that are permitted under the given policy.
+ *
+ * When no policy is set (or mode is `"all"`), the original array is returned
+ * unchanged (no copy is made). Otherwise each tool is tested with
+ * `isToolAllowed` and only the passing tools are included.
+ *
+ * @param tools    - The full, unfiltered list of tools from the remote server.
+ * @param policy   - The active tool policy, or `undefined` for unrestricted access.
+ * @param serverId - The server that owns the tools (required for `allowlist`/`denylist`).
+ * @returns A filtered array containing only the permitted tools.
+ */
 export function filterToolsByPolicy<T extends Pick<Tool, 'name'>>(
     tools: T[],
     policy: ToolPolicy | undefined,
@@ -71,6 +160,19 @@ export function filterToolsByPolicy<T extends Pick<Tool, 'name'>>(
     return tools.filter((tool) => isToolAllowed(policy, tool.name, serverId));
 }
 
+/**
+ * Validates that every tool ID referenced in a policy actually exists on the
+ * connected MCP server. Throws if any ID is unknown.
+ *
+ * This prevents silent misconfigurations where a user accidentally saves a
+ * policy referencing a tool that no longer exists (e.g. after a server update).
+ *
+ * @param policy   - The policy to validate (skipped for `"all"` mode).
+ * @param tools    - The authoritative list of tools from the remote server.
+ * @param serverId - Required to construct tool IDs for comparison.
+ * @throws {Error} When `serverId` is missing and the policy is not `"all"`.
+ * @throws {Error} When the policy contains tool IDs not present in `tools`.
+ */
 export function validateToolPolicyAgainstTools(
     policy: ToolPolicy,
     tools: Array<Pick<Tool, 'name'>>,

package/src/shared/events.ts

@@ -98,6 +98,7 @@ export type McpConnectionEvent =
     serverId: string;
     toolCount: number;
     tools: any[];
+    allTools?: any[];
     timestamp: number;
   }
   | {