@mcp-use/client 2.0.0-beta.16 → 2.0.0-beta.18

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 /**
- * @mcp-use/client — MCP client for connecting to Model Context Protocol servers.
+ * `@mcp-use/client` — MCP client for connecting to Model Context Protocol servers.
  *
  * Connectors, protocol-neutral MCP connections, project configuration, OAuth,
  * and code-mode helpers. The SDK negotiates legacy sessionful and modern

package/dist/index.js

@@ -209,6 +209,11 @@ var init_base = __esm({
       notificationHandlers = [];
       rootsCache = [];
       activeProgressHandlers = /* @__PURE__ */ new Set();
+      /**
+       * Creates a connector with shared SDK and callback options.
+       *
+       * @param opts - Connector initialization options.
+       */
       constructor(opts = {}) {
         this.opts = opts;
         if (opts.roots) {
@@ -391,7 +396,9 @@ var init_base = __esm({
         }
       }
       /**
-       * Get the current roots.
+       * Returns the roots currently advertised to the server.
+       *
+       * @returns A copy of the configured roots.
        */
       getRoots() {
         return [...this.rootsCache];
@@ -460,7 +467,11 @@ var init_base = __esm({
           "setupElicitationHandler: Elicitation handler registered successfully"
         );
       }
-      /** Disconnect and release resources. */
+      /**
+       * Disconnects the SDK client and releases transport resources.
+       *
+       * @returns A promise that resolves after cleanup completes.
+       */
       async disconnect() {
         if (!this.connected) {
           logger.debug("Not connected to MCP implementation");
@@ -471,7 +482,7 @@ var init_base = __esm({
         this.connected = false;
         logger.debug("Disconnected from MCP implementation");
       }
-      /** Check if the client is connected */
+      /** Whether an SDK client currently exists for this connector. */
       get isClientConnected() {
         return this.client != null;
       }
@@ -481,6 +492,10 @@ var init_base = __esm({
        * In the SDK, `Client.connect(transport)` automatically performs the
        * protocol‑level `initialize` handshake, so we only need to cache the list of
        * tools and expose some server info.
+       *
+       * @param defaultRequestOptions - Options used while fetching the initial tool list.
+       * @returns The capabilities advertised by the server.
+       * @throws When {@link BaseConnector.connect} has not completed.
        */
       async initialize(defaultRequestOptions = this.opts.defaultRequestOptions ?? {}) {
         if (!this.client) {
@@ -518,18 +533,22 @@ var init_base = __esm({
         logger.debug("Server info:", serverInfo);
         return capabilities;
       }
-      /** Lazily expose the cached tools list. */
+      /**
+       * Returns the tool list cached during initialization.
+       *
+       * @throws When {@link BaseConnector.initialize} has not completed.
+       */
       get tools() {
         if (!this.toolsCache) {
           throw new Error("MCP client is not initialized; call initialize() first");
         }
         return this.toolsCache;
       }
-      /** Expose cached server capabilities. */
+      /** Capabilities cached during initialization, or an empty object. */
       get serverCapabilities() {
         return this.capabilitiesCache || {};
       }
-      /** Expose cached server info. */
+      /** Server identity cached during initialization, or `null`. */
       get serverInfo() {
         return this.serverInfoCache;
       }
@@ -550,7 +569,15 @@ var init_base = __esm({
       get negotiatedProtocolVersion() {
         return this.client?.getNegotiatedProtocolVersion?.();
       }
-      /** Call a tool on the server. */
+      /**
+       * Calls a tool on the connected server.
+       *
+       * @param name - Tool name.
+       * @param args - Tool arguments.
+       * @param options - Per-request timeout, cancellation, and progress options.
+       * @returns The tool result returned by the server.
+       * @throws When the connector is not connected or the tool call fails.
+       */
       async callTool(name, args, options) {
         if (!this.client) {
           throw new Error("MCP client is not connected");
@@ -675,7 +702,13 @@ var init_base = __esm({
         );
         return result;
       }
-      /** Read a resource by URI. */
+      /**
+       * Reads a resource by URI.
+       *
+       * @param uri - Resource URI to read.
+       * @param options - Per-request options.
+       * @returns The resource contents returned by the server.
+       */
       async readResource(uri, options) {
         if (!this.client) {
           throw new Error("MCP client is not connected");
@@ -710,6 +743,11 @@ var init_base = __esm({
         logger.debug(`Unsubscribing from resource: ${uri}`);
         return await this.client.unsubscribeResource({ uri }, options);
       }
+      /**
+       * Lists prompts exposed by the server.
+       *
+       * @returns The prompt list, or an empty list when prompts are unsupported.
+       */
       async listPrompts() {
         if (!this.client) {
           throw new Error("MCP client is not connected");
@@ -730,6 +768,13 @@ var init_base = __esm({
           throw err;
         }
       }
+      /**
+       * Gets a prompt with the supplied arguments.
+       *
+       * @param name - Prompt name.
+       * @param args - Prompt arguments.
+       * @returns The rendered prompt returned by the server.
+       */
       async getPrompt(name, args) {
         if (!this.client) {
           throw new Error("MCP client is not connected");
@@ -737,7 +782,14 @@ var init_base = __esm({
         logger.debug(`Getting prompt ${name}`);
         return await this.client.getPrompt({ name, arguments: args });
       }
-      /** Send a raw request through the client. */
+      /**
+       * Sends a raw, potentially non-standard request through the SDK client.
+       *
+       * @param method - JSON-RPC method name.
+       * @param params - Request parameters. Defaults to an empty object.
+       * @param options - Per-request options.
+       * @returns The unvalidated result returned by the server.
+       */
       async request(method, params = null, options) {
         if (!this.client) {
           throw new Error("MCP client is not connected");
@@ -959,6 +1011,11 @@ var init_stdio = __esm({
       errlog;
       clientInfo;
       protocolNegotiation;
+      /**
+       * Creates a stdio connector.
+       *
+       * @param options - Process launch, client identity, and shared connector options.
+       */
       constructor({
         command = "npx",
         args = [],
@@ -978,7 +1035,11 @@ var init_stdio = __esm({
         this.cwd = rest.cwd;
         this.protocolNegotiation = rest.protocolNegotiation ?? "legacy";
       }
-      /** Establish connection to the MCP implementation. */
+      /**
+       * Starts the child process and establishes an MCP connection.
+       *
+       * @returns A promise that resolves after protocol negotiation completes.
+       */
       async connect() {
         if (this.connected) {
           logger.debug("Already connected to MCP implementation");
@@ -1074,6 +1135,11 @@ var init_stdio = __esm({
           throw err;
         }
       }
+      /**
+       * Returns fields identifying the launched command and arguments.
+       *
+       * @returns Stdio connector identity metadata.
+       */
       get publicIdentifier() {
         return {
           type: "stdio",
@@ -1085,6 +1151,12 @@ var init_stdio = __esm({
       serverParams;
       errlog;
       _transport = null;
+      /**
+       * Creates a connection manager for a local server process.
+       *
+       * @param serverParams - Process parameters passed to the SDK transport.
+       * @param errlog - Destination for the child process's standard error stream.
+       */
       constructor(serverParams, errlog = process2.stderr) {
         super();
         this.serverParams = serverParams;
@@ -1134,7 +1206,7 @@ init_connector_telemetry();
 init_logging();
 
 // src/utils/version.ts
-var VERSION = "2.0.0-beta.16";
+var VERSION = "2.0.0-beta.18";
 function getPackageVersion() {
   return VERSION;
 }
@@ -2335,8 +2407,16 @@ var DEFAULT_PORT = 33418;
 var PORT_RANGE = 10;
 var DEFAULT_AUTH_TIMEOUT_MS2 = 5 * 6e4;
 var OAuthFlowError = class extends Error {
+  /** OAuth or local-flow error code. */
   code;
+  /** Optional human-readable error description. */
   description;
+  /**
+   * Creates an OAuth flow error.
+   *
+   * @param code - OAuth or local-flow error code.
+   * @param description - Optional human-readable description.
+   */
   constructor(code, description) {
     super(description ? `${code}: ${description}` : code);
     this.code = code;
@@ -2386,13 +2466,17 @@ h1{font-size:20px;margin:0 0 12px;color:#b00020}p{line-height:1.5}code{backgroun
 <p><code>${escapeHtml(err)}</code>${desc ? `: ${escapeHtml(desc)}` : ""}</p>
 <p>You can close this tab and return to your terminal.</p></body></html>`;
 var NodeOAuthClientProvider = class _NodeOAuthClientProvider {
+  /** Protected MCP server URL associated with this provider. */
   serverUrl;
+  /** Reserved localhost callback port. */
   port;
   session;
   kv;
   authTimeoutMs;
   openBrowserOverride;
   server = null;
+  /** Provider authorization URL, exposed only through the local redirect route. */
+  authorizationUrl = null;
   /** Currently in-flight deferred — used to prevent overlapping flows. */
   pending = null;
   /** Latest deferred (settled or in-flight) for the loopback response. */
@@ -2406,6 +2490,13 @@ var NodeOAuthClientProvider = class _NodeOAuthClientProvider {
     this.authTimeoutMs = options.authTimeoutMs ?? DEFAULT_AUTH_TIMEOUT_MS2;
     this.openBrowserOverride = options.openBrowser;
   }
+  /**
+   * Creates a Node OAuth provider and reserves a localhost callback port.
+   *
+   * @param serverUrl - Protected MCP server URL.
+   * @param options - OAuth metadata, storage, loopback, and browser options.
+   * @returns A provider ready to participate in the SDK OAuth flow.
+   */
   static async create(serverUrl, options = {}) {
     const serverUrlHash = OAuthSessionStore.hashString(serverUrl);
     const kv = options.kvStore ?? new FileKVStore(serverUrlHash, options.baseDir);
@@ -2438,48 +2529,100 @@ var NodeOAuthClientProvider = class _NodeOAuthClientProvider {
     return new _NodeOAuthClientProvider(serverUrl, port, session, kv, options);
   }
   // --- Identity passthroughs (parallel to BrowserOAuthClientProvider) ---
+  /** Prefix used for persisted OAuth session keys. */
   get storageKeyPrefix() {
     return this.session.storageKeyPrefix;
   }
+  /** Stable hash of the protected server URL used to namespace storage. */
   get serverUrlHash() {
     return this.session.serverUrlHash;
   }
   // --- SDK Interface (delegated to OAuthSessionStore) ---
+  /** Loopback redirect URL registered for this provider. */
   get redirectUrl() {
     return this.session.redirectUrl;
   }
+  /** OAuth client metadata presented during registration. */
   get clientMetadata() {
     return this.session.clientMetadata;
   }
+  /** OAuth Client ID Metadata Document URL, when configured. */
   get clientMetadataUrl() {
     return this.session.clientMetadataUrl;
   }
+  /**
+   * Loads saved OAuth tokens.
+   *
+   * @param ctx - Optional client registration context.
+   * @returns Saved tokens, or `undefined` when none exist.
+   */
   tokens(ctx) {
     return this.session.tokens(ctx);
   }
+  /**
+   * Persists OAuth tokens.
+   *
+   * @param tokens - Tokens to save.
+   * @param ctx - Optional client registration context.
+   */
   saveTokens(tokens, ctx) {
     return this.session.saveTokens(tokens, ctx);
   }
+  /**
+   * Loads saved OAuth client registration information.
+   *
+   * @param ctx - Optional registration context.
+   * @returns Saved registration information, or `undefined`.
+   */
   clientInformation(ctx) {
     return this.session.clientInformation(ctx);
   }
+  /**
+   * Persists OAuth client registration information.
+   *
+   * @param info - Client information to save.
+   * @param ctx - Optional registration context.
+   */
   saveClientInformation(info, ctx) {
     return this.session.saveClientInformation(info, ctx);
   }
+  /**
+   * Loads the saved PKCE code verifier.
+   *
+   * @returns The saved verifier.
+   */
   codeVerifier() {
     return this.session.codeVerifier();
   }
+  /**
+   * Persists a PKCE code verifier.
+   *
+   * @param codeVerifier - Verifier to save.
+   */
   saveCodeVerifier(codeVerifier) {
     return this.session.saveCodeVerifier(codeVerifier);
   }
+  /**
+   * Invalidates selected persisted OAuth credentials.
+   *
+   * @param scope - Credential group to remove.
+   */
   invalidateCredentials(scope) {
     return this.session.invalidateCredentials(scope);
   }
-  /** Persist OAuth discovery state (SEP-2352). Delegated to the session store. */
+  /**
+   * Persists OAuth discovery state.
+   *
+   * @param state - Discovery state to save.
+   */
   saveDiscoveryState(state) {
     return this.session.saveDiscoveryState(state);
   }
-  /** Return previously saved OAuth discovery state, or `undefined`. */
+  /**
+   * Returns previously saved OAuth discovery state.
+   *
+   * @returns Saved discovery state, or `undefined`.
+   */
   discoveryState() {
     return this.session.discoveryState();
   }
@@ -2487,6 +2630,10 @@ var NodeOAuthClientProvider = class _NodeOAuthClientProvider {
    * Bind the loopback server, set up the pending-code deferred, and ask the
    * platform to open the user's browser. Does NOT await the code; the
    * orchestrator awaits via `getAuthorizationCode()`.
+   *
+   * @param authorizationUrl - Authorization URL generated by the SDK.
+   * @returns A promise that resolves once the loopback listener is ready and
+   * the browser-open attempt completes.
    */
   async redirectToAuthorization(authorizationUrl) {
     if (this.pending) {
@@ -2498,6 +2645,7 @@ var NodeOAuthClientProvider = class _NodeOAuthClientProvider {
       authorizationUrl,
       { flowType: "redirect" }
     );
+    this.authorizationUrl = sanitizedUrl;
     await this.startLoopback();
     this.pending = createDeferred();
     this.lastFlow = this.pending;
@@ -2512,8 +2660,9 @@ var NodeOAuthClientProvider = class _NodeOAuthClientProvider {
       );
     }, this.authTimeoutMs);
     const opener = this.openBrowserOverride ?? defaultOpener;
+    const launcherUrl = `http://127.0.0.1:${this.port}/authorize`;
     try {
-      await opener(sanitizedUrl);
+      await opener(launcherUrl);
     } catch (err) {
       console.error(
         `[mcp-use] Could not open browser automatically: ${err instanceof Error ? err.message : String(err)}`
@@ -2528,6 +2677,8 @@ var NodeOAuthClientProvider = class _NodeOAuthClientProvider {
    * Must be called after `redirectToAuthorization()`. Returns the same
    * promise whether the callback has fired or not — callers may subscribe
    * before or after.
+   *
+   * @returns The authorization code received by the loopback callback.
    */
   getAuthorizationCode() {
     return this.getAuthorizationResponse().then((response) => response.code);
@@ -2535,6 +2686,9 @@ var NodeOAuthClientProvider = class _NodeOAuthClientProvider {
   /**
    * Resolves with the authorization code and RFC 9207 issuer captured by the
    * loopback callback.
+   *
+   * @returns The loopback authorization response.
+   * @throws When called before {@link NodeOAuthClientProvider.redirectToAuthorization}.
    */
   getAuthorizationResponse() {
     if (!this.lastFlow) {
@@ -2548,6 +2702,9 @@ var NodeOAuthClientProvider = class _NodeOAuthClientProvider {
   }
   /**
    * Cancel an in-progress flow (timeout, SIGINT, etc.) and close the loopback.
+   *
+   * Pending calls to {@link NodeOAuthClientProvider.getAuthorizationResponse}
+   * reject with an {@link OAuthFlowError} whose code is `"cancelled"`.
    */
   dispose() {
     if (this.pending) {
@@ -2556,7 +2713,7 @@ var NodeOAuthClientProvider = class _NodeOAuthClientProvider {
       this.stopLoopback();
     }
   }
-  /** Best-effort port for tests / status output. */
+  /** Local callback port, useful for status output and tests. */
   get callbackPort() {
     return this.port;
   }
@@ -2594,6 +2751,7 @@ var NodeOAuthClientProvider = class _NodeOAuthClientProvider {
       this.server.close();
       this.server = null;
     }
+    this.authorizationUrl = null;
   }
   resolvePending(response) {
     const p = this.pending;
@@ -2609,6 +2767,19 @@ var NodeOAuthClientProvider = class _NodeOAuthClientProvider {
   }
   handleCallback(rawUrl, res) {
     const url = new URL(rawUrl, `http://127.0.0.1:${this.port}`);
+    if (url.pathname === "/authorize") {
+      if (this.authorizationUrl === null || this.pending === null) {
+        res.statusCode = 410;
+        res.end("Authorization flow is not active");
+        return;
+      }
+      res.statusCode = 302;
+      res.setHeader("location", this.authorizationUrl);
+      res.setHeader("cache-control", "no-store");
+      res.setHeader("referrer-policy", "no-referrer");
+      res.end();
+      return;
+    }
     if (url.pathname !== "/callback") {
       res.statusCode = 404;
       res.end("Not Found");
@@ -2716,6 +2887,12 @@ var HttpConnector = class extends BaseConnector {
   reconnectionOptions;
   transportType = null;
   streamableTransport = null;
+  /**
+   * Creates an HTTP connector.
+   *
+   * @param baseUrl - MCP endpoint URL.
+   * @param opts - Authentication, transport, SDK, and reconnection options.
+   */
   constructor(baseUrl, opts = {}) {
     super(opts);
     const originalUrl = baseUrl.replace(/\/$/, "");
@@ -2833,7 +3010,12 @@ var HttpConnector = class extends BaseConnector {
     }
     return { fallbackReason, is401Error, httpStatusCode };
   }
-  /** Establish connection to the MCP implementation via streamable HTTP. */
+  /**
+   * Establishes a streamable HTTP connection to the MCP server.
+   *
+   * @returns A promise that resolves after protocol negotiation completes.
+   * @throws An error with `code: 401` when authentication is required.
+   */
   async connect() {
     if (this.connected) {
       logger.debug("Already connected to MCP implementation");
@@ -3061,6 +3243,11 @@ var HttpConnector = class extends BaseConnector {
       throw err;
     }
   }
+  /**
+   * Returns fields that identify the endpoint and negotiated transport.
+   *
+   * @returns HTTP connector identity metadata.
+   */
   get publicIdentifier() {
     return {
       type: "http",
@@ -3069,7 +3256,11 @@ var HttpConnector = class extends BaseConnector {
       protocolEra: this.protocolEra ?? "unknown"
     };
   }
-  /** Get the active transport type (`streamable-http` once connected). */
+  /**
+   * Returns the active transport type.
+   *
+   * @returns `"streamable-http"` after connection, otherwise `null`.
+   */
   getTransportType() {
     return this.transportType;
   }
@@ -3444,7 +3635,7 @@ var MCPConnection = class {
   /**
    * Normalized server metadata for this ready connection.
    *
-   * @throws {Error} When called before protocol negotiation completes.
+   * @throws When called before protocol negotiation completes.
    */
   get info() {
     const protocolEra = this.protocolEra;
@@ -3656,12 +3847,10 @@ function isOAuthClientProvider(provider) {
 var BaseMCPClient = class {
   /**
    * Internal configuration object containing MCP server definitions.
-   * @protected
    */
   config = {};
   /**
    * Map of server names to their active sessions.
-   * @protected
    */
   sessions = {};
   /**
@@ -3705,7 +3894,7 @@ var BaseMCPClient = class {
    *
    * @param _cfg - Configuration dictionary
    * @returns Client instance
-   * @throws {Error} If called on the base class instead of a concrete implementation
+   * @throws If called on the base class instead of a concrete implementation
    *
    * @example
    * ```typescript
@@ -3847,7 +4036,7 @@ var BaseMCPClient = class {
    * @param serverName - The name of the server as defined in the client configuration
    * @param autoInitialize - Whether to automatically initialize the session (default: true)
    * @returns A promise that resolves to the created MCPSession instance
-   * @throws {Error} If the server is not found in the configuration
+   * @throws If the server is not found in the configuration
    *
    * @example
    * ```typescript
@@ -4017,7 +4206,7 @@ var BaseMCPClient = class {
    *
    * @param serverName - Name of the server
    * @returns The session instance
-   * @throws {Error} If the session is not found
+   * @throws If the session is not found
    *
    * @example
    * ```typescript
@@ -4401,20 +4590,24 @@ global.search_tools = async (query, detailLevel = 'full') => {
     for (const [serverName, serverTools] of Object.entries(tools)) {
       if (!serverTools || serverTools.length === 0) continue;
       const safeServerName = serverName.replace(/[^a-zA-Z0-9_]/g, "_");
+      const escapedServerName = JSON.stringify(serverName);
+      const escapedSafeServerName = JSON.stringify(safeServerName);
       shim += `
-global['${serverName}'] = {`;
+global[${escapedServerName}] = {`;
       for (const tool of serverTools) {
+        const escapedToolName = JSON.stringify(tool.name);
         shim += `
-    '${tool.name}': async (args) => await global.__callMcpTool('${serverName}', '${tool.name}', args),`;
+    [${escapedToolName}]: async (args) => await global.__callMcpTool(${escapedServerName}, ${escapedToolName}, args),`;
       }
       shim += `
 };
-
+`;
+      if (safeServerName !== serverName) {
+        shim += `
 // Also expose as safe name if different
-if ('${safeServerName}' !== '${serverName}') {
-    global['${safeServerName}'] = global['${serverName}'];
-}
+global[${escapedSafeServerName}] = global[${escapedServerName}];
 `;
+      }
     }
     return shim;
   }
@@ -5108,9 +5301,7 @@ var MCPClient = class _MCPClient extends BaseMCPClient {
    * @param config - Configuration object or path to JSON config file. If omitted,
    *                 starts with empty configuration
    * @param options - Optional client behavior configuration
-   * @param options.codeMode - Enable code execution mode (boolean or advanced config)
-   * @param options.onSampling - Callback for handling sampling requests from servers
-   * @param options.onElicitation - Callback for handling elicitation requests
+   * Options can enable code mode or provide sampling and elicitation callbacks.
    *
    * @example
    * ```typescript
@@ -5211,7 +5402,7 @@ var MCPClient = class _MCPClient extends BaseMCPClient {
    * });
    * ```
    *
-   * @see {@link constructor} for direct instantiation
+   * @see {@link MCPClient} for direct instantiation
    * @see {@link fromConfigFile} for loading from file
    */
   static fromDict(cfg, options) {
@@ -5226,7 +5417,7 @@ var MCPClient = class _MCPClient extends BaseMCPClient {
    * @param path - Path to the JSON configuration file
    * @param options - Optional client behavior configuration
    * @returns New MCPClient instance
-   * @throws {Error} If the file cannot be read or parsed
+   * @throws If the file cannot be read or parsed
    *
    * @example
    * ```typescript
@@ -5242,7 +5433,7 @@ var MCPClient = class _MCPClient extends BaseMCPClient {
    * });
    * ```
    *
-   * @see {@link constructor} for direct instantiation
+   * @see {@link MCPClient} for direct instantiation
    * @see {@link fromDict} for inline configuration
    */
   static fromConfigFile(path2, options) {
@@ -5389,7 +5580,7 @@ var MCPClient = class _MCPClient extends BaseMCPClient {
    * @param code - JavaScript/TypeScript code to execute
    * @param timeout - Optional execution timeout in milliseconds
    * @returns Execution result with output, errors, and return value
-   * @throws {Error} If code mode is not enabled
+   * @throws If code mode is not enabled
    *
    * @example
    * ```typescript
@@ -5435,7 +5626,7 @@ var MCPClient = class _MCPClient extends BaseMCPClient {
    * @param query - Optional search query to filter tools (defaults to empty string for all tools)
    * @param detailLevel - Level of detail to return: "names", "descriptions", or "full"
    * @returns Tool search results with matching tools
-   * @throws {Error} If code mode is not enabled
+   * @throws If code mode is not enabled
    *
    * @example
    * ```typescript