@mcp-ts/sdk 2.5.1 → 2.5.2

package/dist/index.js

@@ -2320,6 +2320,15 @@ var MCPClient = class {
     __publicField(this, "_onObservabilityEvent", new Emitter());
     __publicField(this, "onObservabilityEvent", this._onObservabilityEvent.event);
     __publicField(this, "currentState", "DISCONNECTED");
+    /**
+     * 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.
+     */
+    __publicField(this, "cachedTools", null);
     this.serverUrl = options.serverUrl;
     this.serverName = options.serverName;
     this.callbackUrl = options.callbackUrl;
@@ -2640,13 +2649,20 @@ var MCPClient = class {
     throw lastError || new Error("No transports available");
   }
   /**
-   * 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() {
+    this.cachedTools = null;
     if (this.client.transport) {
       this.transport = null;
       try {
@@ -2829,17 +2845,30 @@ var MCPClient = class {
     }
   }
   /**
-   * 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.
+   * 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() {
+    if (this.cachedTools) {
+      return this.cachedTools;
+    }
     const request = {
       method: "tools/list",
       params: {}
     };
-    return await this.withRetry(
+    const result = await this.withRetry(
       () => this.client.request(request, types_js.ListToolsResultSchema)
     );
+    this.cachedTools = result;
+    return result;
   }
   /**
    * Lists all available tools from the connected MCP server
@@ -3125,10 +3154,14 @@ var MCPClient = class {
     this.emitStateChange("DISCONNECTED");
   }
   /**
-   * 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() {
+    this.cachedTools = null;
     this._onConnectionEvent.dispose();
     this._onObservabilityEvent.dispose();
   }
@@ -3187,21 +3220,47 @@ var ToolPolicyGateway = class {
     this.sessionId = sessionId;
     this.client = client;
   }
+  /**
+   * Returns whether the underlying MCP client transport is currently connected.
+   */
   isConnected() {
     return this.client.isConnected();
   }
+  /**
+   * Returns the server ID from the underlying client, if available.
+   */
   getServerId() {
     return this.client.getServerId?.();
   }
+  /**
+   * Returns the human-readable server name from the underlying client, if available.
+   */
   getServerName() {
     return this.client.getServerName?.();
   }
+  /**
+   * Returns the server URL from the underlying client, if available.
+   */
   getServerUrl() {
     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() {
     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() {
     const session = await this.getSession();
     const result = await this.client.fetchTools();
@@ -3211,20 +3270,61 @@ var ToolPolicyGateway = class {
       tools
     };
   }
+  /**
+   * 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() {
     return await this.client.fetchTools();
   }
+  /**
+   * 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, args) {
     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, tools) {
     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, toolName) {
     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.
+   */
   async getSession() {
     const session = await sessions.get(this.userId, this.sessionId);
     if (!session) {
@@ -3232,6 +3332,11 @@ var ToolPolicyGateway = class {
     }
     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.
+   */
   getPolicyServerId(session) {
     return this.client.getServerId?.() ?? session.serverId;
   }
@@ -3791,12 +3896,29 @@ var SSEConnectionManager = class {
     this.clients.set(sessionId, client);
     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.
+   */
   async listPolicyFilteredTools(sessionId) {
     const session = await sessions.get(this.userId, sessionId);
     if (!session) {
       throw new Error("Session not found");
     }
     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();
     this.emitConnectionEvent({
@@ -3805,12 +3927,15 @@ var SSEConnectionManager = class {
       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.
    */
   async listTools(params) {
     const { sessionId } = params;
@@ -3847,7 +3972,15 @@ var SSEConnectionManager = class {
     };
   }
   /**
-   * 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.
    */
   async setToolPolicy(params) {
     const { sessionId } = params;
@@ -3867,6 +4000,7 @@ var SSEConnectionManager = class {
       serverId: session.serverId ?? "unknown",
       toolCount: filteredTools.length,
       tools: filteredTools,
+      allTools: allTools.tools,
       timestamp: Date.now()
     });
     return {
@@ -3877,7 +4011,8 @@ var SSEConnectionManager = class {
     };
   }
   /**
-   * 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.
    */
   async callTool(params) {
     const { sessionId, toolName, toolArgs } = params;