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

package/dist/index-browser.js

@@ -128,7 +128,7 @@ var Logger = class {
 var logger = Logger.get();
 
 // src/utils/version.ts
-var VERSION = "2.0.0-beta.16";
+var VERSION = "2.0.0-beta.17";
 function getPackageVersion() {
   return VERSION;
 }
@@ -1159,11 +1159,14 @@ function trimTrailingSlashes(value) {
   return value.slice(0, end);
 }
 var BrowserOAuthClientProvider = class {
+  /** Protected MCP server URL associated with this provider. */
   serverUrl;
+  /** Pre-registered public client information, when configured. */
   staticClientInfo;
   session;
   storage;
   // Browser-only state
+  /** Whether initial connection waits for explicit authentication. */
   preventAutoAuth;
   useRedirectFlow;
   oauthProxyUrl;
@@ -1171,6 +1174,7 @@ var BrowserOAuthClientProvider = class {
   proxyOAuthRequests;
   lastAttemptedAuthUrl = null;
   authorizationPending = false;
+  /** Callback invoked immediately before an authorization popup opens. */
   onPopupWindow;
   constructor(serverUrl, options = {}) {
     if (options.staticClientInfo?.client_secret) {
@@ -1194,36 +1198,51 @@ var BrowserOAuthClientProvider = class {
     this.onPopupWindow = options.onPopupWindow;
   }
   // --- Identity / key fields exposed for callback handling ---
+  /** Prefix used for persisted OAuth keys. */
   get storageKeyPrefix() {
     return this.session.storageKeyPrefix;
   }
+  /** Stable hash used to namespace storage for this server. */
   get serverUrlHash() {
     return this.session.serverUrlHash;
   }
+  /** Human-readable OAuth client name. */
   get clientName() {
     return this.session.clientName;
   }
+  /** Public website describing the OAuth client. */
   get clientUri() {
     return this.session.clientUri;
   }
+  /** Public OAuth client logo URL. */
   get logoUri() {
     return this.session.logoUri;
   }
+  /** OAuth redirect URI. */
   get callbackUrl() {
     return this.session.callbackUrl;
   }
+  /** Space-delimited OAuth scopes requested by the client. */
   get scope() {
     return this.session.scope;
   }
   get clientMetadataUrl() {
     return this.session.clientMetadataUrl;
   }
+  /**
+   * Returns a provider-scoped storage key.
+   *
+   * @param keySuffix - Suffix identifying the stored value.
+   * @returns Namespaced storage key.
+   */
   getKey(keySuffix) {
     return this.session.getKey(keySuffix);
   }
+  /** Whether an authorization flow is awaiting completion. */
   get hasPendingFlow() {
     return this.authorizationPending;
   }
+  /** Marks the current authorization flow as complete. */
   markFlowComplete() {
     this.authorizationPending = false;
   }
@@ -1410,10 +1429,25 @@ var BrowserOAuthClientProvider = class {
     this.authorizationPending = false;
     return this.session.saveTokens(tokens, ctx);
   }
+  /**
+   * Returns the configured or dynamically registered OAuth client information.
+   *
+   * @param ctx - Optional registration context.
+   * @returns OAuth client information, or `undefined` when not registered.
+   */
   async clientInformation(ctx) {
     if (this.staticClientInfo) return this.staticClientInfo;
     return this.session.clientInformation(ctx);
   }
+  /**
+   * Persists public OAuth client registration information.
+   *
+   * Static client configuration takes precedence, and browser providers discard
+   * any client secret returned for a public client.
+   *
+   * @param clientInformation - Registration information to save.
+   * @param ctx - Optional registration context.
+   */
   async saveClientInformation(clientInformation, ctx) {
     if (this.staticClientInfo) return;
     const { client_secret: discardedClientSecret, ...publicClientInformation } = clientInformation;
@@ -1493,7 +1527,7 @@ var BrowserOAuthClientProvider = class {
   }
   /**
    * Redirects the user agent to the authorization URL, storing necessary state.
-   * @param authorizationUrl The fully constructed authorization URL from the SDK.
+   * @param authorizationUrl - The fully constructed authorization URL from the SDK.
    */
   async redirectToAuthorization(authorizationUrl) {
     const sanitizedAuthUrl = await this.prepareAuthorizationUrl(authorizationUrl);
@@ -1543,6 +1577,11 @@ var BrowserOAuthClientProvider = class {
   getLastAttemptedAuthUrl() {
     return this.lastAttemptedAuthUrl;
   }
+  /**
+   * Removes OAuth state stored for this server.
+   *
+   * @returns The number of storage entries removed.
+   */
   clearStorage() {
     this.lastAttemptedAuthUrl = null;
     this.authorizationPending = false;
@@ -2053,6 +2092,11 @@ var BaseConnector = class {
   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) {
@@ -2235,7 +2279,9 @@ var BaseConnector = class {
     }
   }
   /**
-   * Get the current roots.
+   * Returns the roots currently advertised to the server.
+   *
+   * @returns A copy of the configured roots.
    */
   getRoots() {
     return [...this.rootsCache];
@@ -2304,7 +2350,11 @@ var BaseConnector = class {
       "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");
@@ -2315,7 +2365,7 @@ var BaseConnector = class {
     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;
   }
@@ -2325,6 +2375,10 @@ var BaseConnector = class {
    * 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) {
@@ -2362,18 +2416,22 @@ var BaseConnector = class {
     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;
   }
@@ -2394,7 +2452,15 @@ var BaseConnector = class {
   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");
@@ -2519,7 +2585,13 @@ var BaseConnector = class {
     );
     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");
@@ -2554,6 +2626,11 @@ var BaseConnector = class {
     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");
@@ -2574,6 +2651,13 @@ var BaseConnector = class {
       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");
@@ -2581,7 +2665,14 @@ var BaseConnector = class {
     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");
@@ -2680,6 +2771,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(/\/$/, "");
@@ -2797,7 +2894,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");
@@ -3025,6 +3127,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",
@@ -3033,7 +3140,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;
   }
@@ -3401,7 +3512,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;
@@ -3613,12 +3724,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 = {};
   /**
@@ -3662,7 +3771,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
@@ -3804,7 +3913,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
@@ -3974,7 +4083,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
@@ -4143,16 +4252,28 @@ function trackBrowserClientInit(config) {
 }
 var BrowserMCPClient = class _BrowserMCPClient extends BaseMCPClient {
   /**
-   * Get the mcp-use package version.
-   * Works in all environments (Node.js, browser, Cloudflare Workers, Deno, etc.)
+   * Returns the installed `@mcp-use/client` package version.
+   *
+   * @returns The package version string.
    */
   static getPackageVersion() {
     return getPackageVersion();
   }
+  /**
+   * Creates a browser MCP client.
+   *
+   * @param config - Client configuration containing an optional `mcpServers` map.
+   */
   constructor(config) {
     super(config);
     trackBrowserClientInit(this.config);
   }
+  /**
+   * Creates a browser client from an inline configuration object.
+   *
+   * @param cfg - Client configuration containing an optional `mcpServers` map.
+   * @returns A browser client initialized with `cfg`.
+   */
   static fromDict(cfg) {
     return new _BrowserMCPClient(cfg);
   }