@mcp-ts/sdk 2.5.0 → 2.5.2

package/dist/server/index.mjs

@@ -2174,6 +2174,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;
@@ -2494,13 +2503,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 {
@@ -2683,17 +2699,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, ListToolsResultSchema)
     );
+    this.cachedTools = result;
+    return result;
   }
   /**
    * Lists all available tools from the connected MCP server
@@ -2979,10 +3008,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();
   }
@@ -3037,21 +3070,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();
@@ -3061,20 +3120,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) {
@@ -3082,6 +3182,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;
   }
@@ -3386,6 +3491,9 @@ var SSEConnectionManager = class {
         case "connect":
           result = await this.connect(request.params);
           break;
+        case "reconnect":
+          result = await this.reconnect(request.params);
+          break;
         case "disconnect":
           result = await this.disconnect(request.params);
           break;
@@ -3528,6 +3636,66 @@ var SSEConnectionManager = class {
       throw error;
     }
   }
+  /**
+   * Reconnect to an MCP server — tears down the active client transport/connection
+   * and creates a fresh connection while reusing the existing session credentials in a single RPC call.
+   */
+  async reconnect(params) {
+    const { serverId: rawServerId, serverName, serverUrl, callbackUrl, transportType } = params;
+    const headers = normalizeHeaders(params.headers);
+    const serverId = rawServerId && rawServerId.length <= 12 ? rawServerId : generateServerId();
+    const existingSessions = await sessions.list(this.userId);
+    const duplicate = existingSessions.find(
+      (s) => s.serverId === serverId || s.serverUrl === serverUrl
+    );
+    const sessionId = duplicate ? duplicate.sessionId : await sessions.generateSessionId();
+    if (duplicate) {
+      const existingClient = this.clients.get(duplicate.sessionId);
+      if (existingClient) {
+        await existingClient.disconnect();
+        this.clients.delete(duplicate.sessionId);
+      }
+    }
+    try {
+      const clientMetadata = await this.getResolvedClientMetadata();
+      const client = new MCPClient({
+        userId: this.userId,
+        sessionId,
+        serverId,
+        serverName,
+        serverUrl,
+        callbackUrl,
+        transportType,
+        headers,
+        ...clientMetadata
+      });
+      this.clients.set(sessionId, client);
+      client.onConnectionEvent((event) => {
+        this.emitConnectionEvent(event);
+      });
+      client.onObservabilityEvent((event) => {
+        this.sendEvent(event);
+      });
+      await client.connect();
+      await this.listPolicyFilteredTools(sessionId);
+      return { sessionId, success: true };
+    } catch (error) {
+      if (error instanceof UnauthorizedError) {
+        this.clients.delete(sessionId);
+        return { sessionId, success: true };
+      }
+      this.emitConnectionEvent({
+        type: "error",
+        sessionId,
+        serverId,
+        error: error instanceof Error ? error.message : "Connection failed",
+        errorType: "connection",
+        timestamp: Date.now()
+      });
+      this.clients.delete(sessionId);
+      throw error;
+    }
+  }
   /**
    * Disconnect from an MCP server
    */
@@ -3574,12 +3742,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({
@@ -3588,12 +3773,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;
@@ -3630,7 +3818,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;
@@ -3650,6 +3846,7 @@ var SSEConnectionManager = class {
       serverId: session.serverId ?? "unknown",
       toolCount: filteredTools.length,
       tools: filteredTools,
+      allTools: allTools.tools,
       timestamp: Date.now()
     });
     return {
@@ -3660,7 +3857,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;