@mcp-use/client 2.0.0-beta.8 → 2.0.0

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.7";
+var VERSION = "2.0.0";
 function getPackageVersion() {
   return VERSION;
 }
@@ -148,16 +148,13 @@ var MCPAgentExecutionEvent = class extends BaseTelemetryEvent {
     return {
       // Core execution info
       execution_method: this.data.executionMethod,
-      query: this.data.query,
       query_length: this.data.query.length,
       success: this.data.success,
       // Agent configuration
       model_provider: this.data.modelProvider,
       model_name: this.data.modelName,
       server_count: this.data.serverCount,
-      server_identifiers: this.data.serverIdentifiers,
       total_tools_available: this.data.totalToolsAvailable,
-      tools_available_names: this.data.toolsAvailableNames,
       max_steps_configured: this.data.maxStepsConfigured,
       memory_enabled: this.data.memoryEnabled,
       use_server_manager: this.data.useServerManager,
@@ -168,8 +165,6 @@ var MCPAgentExecutionEvent = class extends BaseTelemetryEvent {
       // Execution results (always include, even if null)
       steps_taken: this.data.stepsTaken ?? null,
       tools_used_count: this.data.toolsUsedCount ?? null,
-      tools_used_names: this.data.toolsUsedNames ?? null,
-      response: this.data.response ?? null,
       response_length: this.data.response ? this.data.response.length : null,
       execution_time_ms: this.data.executionTimeMs ?? null,
       error_type: this.data.errorType ?? null,
@@ -265,21 +260,72 @@ async function telFetch(url, init) {
 }
 var POSTHOG_HOST = "https://eu.i.posthog.com";
 var POSTHOG_API_KEY = "phc_lyTtbYwvkdSbrcMQNPiKiiRWrrM1seyKIMjycSvItEI";
-function capturePostHog(params) {
-  const host = params.host ?? POSTHOG_HOST;
-  const apiKey = params.apiKey ?? POSTHOG_API_KEY;
-  return telFetch(`${host}/i/v0/e/`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    keepalive: true,
-    body: JSON.stringify({
+var CONTENT_PROPERTY = /(^|_)(arguments?|args|body|command|headers?|location|message|query|response|secret|subject|token|uri|url|user_agent)(_|$)/i;
+var IDENTIFYING_PROPERTY = /(^|_)(server_identifiers?|server_names?|servers|tool_names?|tools_(available|used)_names)(_|$)/i;
+var AGGREGATE_PROPERTY = /(_count|_length|_duration(?:_ms)?|_time_ms|(^|_)num_[a-z0-9_]+)$/i;
+function normalizePropertyKey(key) {
+  return key.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[^a-z0-9_$]+/gi, "_").toLowerCase();
+}
+function sanitizeValue(value, seen) {
+  if (Array.isArray(value)) {
+    if (seen.has(value)) {
+      throw new TypeError("Cyclic telemetry properties are not supported");
+    }
+    seen.add(value);
+    const sanitized = value.map((item) => sanitizeValue(item, seen));
+    seen.delete(value);
+    return sanitized;
+  }
+  if (value !== null && typeof value === "object" && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)) {
+    if (seen.has(value)) {
+      throw new TypeError("Cyclic telemetry properties are not supported");
+    }
+    seen.add(value);
+    const sanitized = sanitizeProperties(
+      value,
+      seen
+    );
+    seen.delete(value);
+    return sanitized;
+  }
+  return value;
+}
+function sanitizeProperties(properties, seen = /* @__PURE__ */ new WeakSet()) {
+  const sanitized = {};
+  for (const [key, value] of Object.entries(properties)) {
+    const normalizedKey = normalizePropertyKey(key);
+    if (AGGREGATE_PROPERTY.test(normalizedKey)) {
+      if (value === null || typeof value === "number") {
+        sanitized[key] = value;
+      }
+      continue;
+    }
+    if (IDENTIFYING_PROPERTY.test(normalizedKey) || CONTENT_PROPERTY.test(normalizedKey)) {
+      continue;
+    }
+    sanitized[key] = sanitizeValue(value, seen);
+  }
+  return sanitized;
+}
+async function capturePostHog(params) {
+  try {
+    const host = params.host ?? POSTHOG_HOST;
+    const apiKey = params.apiKey ?? POSTHOG_API_KEY;
+    const body = JSON.stringify({
       api_key: apiKey,
       event: params.event,
       distinct_id: params.distinctId,
-      properties: params.properties,
+      properties: sanitizeProperties(params.properties),
       timestamp: (/* @__PURE__ */ new Date()).toISOString()
-    })
-  });
+    });
+    await telFetch(`${host}/i/v0/e/`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      keepalive: true,
+      body
+    });
+  } catch {
+  }
 }
 
 // src/telemetry/telemetry.ts
@@ -589,6 +635,186 @@ setConnectorTelemetryTracker(
   (data) => Telemetry.getInstance().trackConnectorInit(data).catch(() => void 0)
 );
 
+// src/auth/storage.ts
+var AUTH_CRYPTO_DATABASE = "mcp-use-oauth-crypto";
+var AUTH_CRYPTO_STORE = "keys";
+var AUTH_CRYPTO_KEY = "aes-gcm-v1";
+var textEncoder = new TextEncoder();
+var textDecoder = new TextDecoder();
+var LocalStorageKVStore = class {
+  fallback = /* @__PURE__ */ new Map();
+  keyPromise;
+  durable = true;
+  async get(key) {
+    if (!this.durable) return this.fallback.get(key) ?? null;
+    let stored;
+    try {
+      stored = localStorage.getItem(key);
+    } catch {
+      this.durable = false;
+      return this.fallback.get(key) ?? null;
+    }
+    if (stored === null) return null;
+    const envelope = parseEncryptedEnvelope(stored);
+    if (!envelope) {
+      await this.set(key, stored);
+      return stored;
+    }
+    try {
+      const cryptoKey = await this.getCryptoKey();
+      const plaintext = await globalThis.crypto.subtle.decrypt(
+        {
+          name: "AES-GCM",
+          iv: decodeBase64(envelope.iv),
+          additionalData: textEncoder.encode(key)
+        },
+        cryptoKey,
+        decodeBase64(envelope.ciphertext)
+      );
+      return textDecoder.decode(plaintext);
+    } catch {
+      await this.remove(key);
+      return null;
+    }
+  }
+  async set(key, value) {
+    if (!this.durable) {
+      this.fallback.set(key, value);
+      return;
+    }
+    try {
+      const cryptoKey = await this.getCryptoKey();
+      const iv = globalThis.crypto.getRandomValues(new Uint8Array(12));
+      const ciphertext = await globalThis.crypto.subtle.encrypt(
+        {
+          name: "AES-GCM",
+          iv,
+          additionalData: textEncoder.encode(key)
+        },
+        cryptoKey,
+        textEncoder.encode(value)
+      );
+      const envelope = {
+        v: 1,
+        alg: "A256GCM",
+        iv: encodeBase64(iv),
+        ciphertext: encodeBase64(new Uint8Array(ciphertext))
+      };
+      localStorage.setItem(key, JSON.stringify(envelope));
+      this.fallback.delete(key);
+    } catch {
+      this.durable = false;
+      try {
+        localStorage.removeItem(key);
+      } catch {
+      }
+      this.fallback.set(key, value);
+    }
+  }
+  remove(key) {
+    this.fallback.delete(key);
+    try {
+      localStorage.removeItem(key);
+    } catch {
+      this.durable = false;
+    }
+  }
+  keys() {
+    const out = new Set(this.fallback.keys());
+    if (this.durable) {
+      try {
+        for (let i = 0; i < localStorage.length; i++) {
+          const key = localStorage.key(i);
+          if (key) out.add(key);
+        }
+      } catch {
+        this.durable = false;
+      }
+    }
+    return [...out];
+  }
+  getCryptoKey() {
+    this.keyPromise ??= getOrCreateCryptoKey();
+    return this.keyPromise;
+  }
+};
+function parseEncryptedEnvelope(value) {
+  try {
+    const parsed = JSON.parse(value);
+    if (!parsed || typeof parsed !== "object" || !("v" in parsed) || parsed.v !== 1 || !("alg" in parsed) || parsed.alg !== "A256GCM" || !("iv" in parsed) || typeof parsed.iv !== "string" || !("ciphertext" in parsed) || typeof parsed.ciphertext !== "string") {
+      return void 0;
+    }
+    return parsed;
+  } catch {
+    return void 0;
+  }
+}
+async function getOrCreateCryptoKey() {
+  if (!globalThis.crypto?.subtle || typeof indexedDB === "undefined") {
+    throw new Error("Durable browser cryptography is unavailable");
+  }
+  const candidate = await globalThis.crypto.subtle.generateKey(
+    { name: "AES-GCM", length: 256 },
+    false,
+    ["encrypt", "decrypt"]
+  );
+  const database = await openCryptoDatabase();
+  try {
+    return await new Promise((resolve, reject) => {
+      const transaction = database.transaction(AUTH_CRYPTO_STORE, "readwrite");
+      const store = transaction.objectStore(AUTH_CRYPTO_STORE);
+      const request = store.get(AUTH_CRYPTO_KEY);
+      let selected;
+      request.onsuccess = () => {
+        selected = request.result;
+        if (!selected) {
+          selected = candidate;
+          store.put(candidate, AUTH_CRYPTO_KEY);
+        }
+      };
+      request.onerror = () => reject(request.error);
+      transaction.oncomplete = () => {
+        if (selected) resolve(selected);
+        else reject(new Error("OAuth encryption key was not initialized"));
+      };
+      transaction.onerror = () => reject(transaction.error);
+      transaction.onabort = () => reject(transaction.error);
+    });
+  } finally {
+    database.close();
+  }
+}
+function openCryptoDatabase() {
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.open(AUTH_CRYPTO_DATABASE, 1);
+    request.onupgradeneeded = () => {
+      const database = request.result;
+      if (!database.objectStoreNames.contains(AUTH_CRYPTO_STORE)) {
+        database.createObjectStore(AUTH_CRYPTO_STORE);
+      }
+    };
+    request.onsuccess = () => resolve(request.result);
+    request.onerror = () => reject(request.error);
+    request.onblocked = () => reject(new Error("OAuth encryption database is blocked"));
+  });
+}
+function encodeBase64(bytes) {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary);
+}
+function decodeBase64(value) {
+  const binary = atob(value);
+  const bytes = new Uint8Array(binary.length);
+  for (let index = 0; index < binary.length; index++) {
+    bytes[index] = binary.charCodeAt(index);
+  }
+  return bytes;
+}
+
+// src/auth/session-store.ts
+import { validateClientMetadataUrl } from "@modelcontextprotocol/client";
+
 // src/auth/url.ts
 function sanitizeUrl(raw) {
   const abort = () => {
@@ -613,29 +839,7 @@ function sanitizeParam([k, v]) {
   return `${encodeURIComponent(k)}${v.length > 0 ? `=${encodeURIComponent(v)}` : ""}`;
 }
 
-// src/auth/storage.ts
-var LocalStorageKVStore = class {
-  get(key) {
-    return localStorage.getItem(key);
-  }
-  set(key, value) {
-    localStorage.setItem(key, value);
-  }
-  remove(key) {
-    localStorage.removeItem(key);
-  }
-  keys() {
-    const out = [];
-    for (let i = 0; i < localStorage.length; i++) {
-      const k = localStorage.key(i);
-      if (k) out.push(k);
-    }
-    return out;
-  }
-};
-
 // src/auth/session-store.ts
-import { validateClientMetadataUrl } from "@modelcontextprotocol/client";
 var OAuthSessionStore = class _OAuthSessionStore {
   serverUrl;
   storageKeyPrefix;
@@ -741,29 +945,39 @@ var OAuthSessionStore = class _OAuthSessionStore {
     if (ctx) await this.store.set(this.credentialKey("tokens"), serialized);
     await this.store.remove(this.getKey("code_verifier"));
     await this.store.remove(this.getKey("last_auth_url"));
+    await this.store.remove(this.getKey("last_auth_callback_url"));
   }
   async clientInformation(ctx) {
+    if (!this.allowClientSecret) {
+      const registeredRedirectUri = await this.store.get(
+        this.getKey("client_info_redirect_uri")
+      );
+      if (registeredRedirectUri !== this.redirectUrl) {
+        await this.invalidateCredentials("registration");
+        console.info(
+          `[${this.storageKeyPrefix}] Re-registering browser OAuth client after its Inspector callback changed or could not be verified.`
+        );
+        return void 0;
+      }
+    }
     const stored = await this.readCredential("client_info", ctx);
     if (!stored) return void 0;
     const { key, value: clientInfo } = stored;
     try {
       if (!this.allowClientSecret && clientInfo.client_secret) {
-        await this.store.remove(key);
-        if (ctx) await this.store.remove(this.credentialKey("client_info"));
+        await this.invalidateCredentials("registration");
         console.warn(
-          `[${this.storageKeyPrefix}] Removed OAuth client information containing a browser client_secret.`
+          `[${this.storageKeyPrefix}] Recovered stale browser OAuth credentials containing a client_secret.`
         );
         return void 0;
       }
       const storedRedirectUris = Array.isArray(clientInfo.redirect_uris) ? clientInfo.redirect_uris : [];
-      const hasMatchingRedirect = storedRedirectUris.length === 0 || storedRedirectUris.includes(this.redirectUrl);
+      const hasMatchingRedirect = storedRedirectUris.length === 0 && this.allowClientSecret || storedRedirectUris.includes(this.redirectUrl);
       if (!hasMatchingRedirect) {
         console.info(
-          `[${this.storageKeyPrefix}] Invalidating cached OAuth client info due to redirect URI mismatch.`
+          `[${this.storageKeyPrefix}] Recovering cached OAuth credentials after a redirect URI change.`
         );
-        await this.store.remove(key);
-        await this.store.remove(this.credentialKey("tokens", ctx));
-        await this.store.remove(this.getKey("last_auth_url"));
+        await this.invalidateCredentials("registration");
         return void 0;
       }
       return clientInfo;
@@ -781,11 +995,20 @@ var OAuthSessionStore = class _OAuthSessionStore {
         "Browser OAuth clients must be public clients; client_secret persistence is not allowed."
       );
     }
-    const serialized = JSON.stringify(clientInformation);
+    const persistedClientInformation = !this.allowClientSecret && (!("redirect_uris" in clientInformation) || !Array.isArray(
+      clientInformation.redirect_uris
+    ) || clientInformation.redirect_uris.length === 0) ? { ...clientInformation, redirect_uris: [this.redirectUrl] } : clientInformation;
+    const serialized = JSON.stringify(persistedClientInformation);
     await this.store.set(this.credentialKey("client_info", ctx), serialized);
     if (ctx) {
       await this.store.set(this.credentialKey("client_info"), serialized);
     }
+    if (!this.allowClientSecret) {
+      await this.store.set(
+        this.getKey("client_info_redirect_uri"),
+        this.redirectUrl
+      );
+    }
   }
   async saveCodeVerifier(codeVerifier) {
     await this.store.set(this.getKey("code_verifier"), codeVerifier);
@@ -810,11 +1033,22 @@ var OAuthSessionStore = class _OAuthSessionStore {
       }
     };
     switch (scope) {
+      case "registration":
+        await removeCredentialKeys("tokens");
+        await removeCredentialKeys("client_info");
+        await this.store.remove(this.getKey("code_verifier"));
+        await this.store.remove(this.getKey("last_auth_url"));
+        await this.store.remove(this.getKey("last_auth_callback_url"));
+        await this.store.remove(this.getKey("client_info_redirect_uri"));
+        await this.store.remove(this.getKey("token_endpoint"));
+        break;
       case "all":
         await removeCredentialKeys("tokens");
         await removeCredentialKeys("client_info");
         await this.store.remove(this.getKey("code_verifier"));
         await this.store.remove(this.getKey("last_auth_url"));
+        await this.store.remove(this.getKey("last_auth_callback_url"));
+        await this.store.remove(this.getKey("client_info_redirect_uri"));
         await this.store.remove(this.getKey("discovery_state"));
         await this.store.remove(this.getKey("token_endpoint"));
         break;
@@ -864,7 +1098,7 @@ var OAuthSessionStore = class _OAuthSessionStore {
    */
   async storeAuthorizationState(authorizationUrl, opts = {}) {
     const state = globalThis.crypto.randomUUID();
-    const stateKey = `${this.storageKeyPrefix}:state_${state}`;
+    const stateKey = `${this.storageKeyPrefix}_${this.serverUrlHash}_state_${state}`;
     const stateData = {
       serverUrlHash: this.serverUrlHash,
       expiry: Date.now() + 1e3 * 60 * 10,
@@ -884,6 +1118,10 @@ var OAuthSessionStore = class _OAuthSessionStore {
     authorizationUrl.searchParams.set("state", state);
     const sanitizedAuthUrl = sanitizeUrl(authorizationUrl.toString());
     await this.store.set(stateKey, JSON.stringify(stateData));
+    await this.store.set(
+      this.getKey("last_auth_callback_url"),
+      this.redirectUrl
+    );
     await this.store.set(this.getKey("last_auth_url"), sanitizedAuthUrl);
     return sanitizedAuthUrl;
   }
@@ -913,16 +1151,30 @@ async function serializeBody(body) {
   if (body instanceof Blob) return await body.text();
   return body;
 }
+function trimTrailingSlashes(value) {
+  let end = value.length;
+  while (end > 0 && value.charCodeAt(end - 1) === 47) {
+    end--;
+  }
+  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;
   connectionUrl;
   proxyOAuthRequests;
+  lastAttemptedAuthUrl = null;
+  authorizationPending = false;
+  /** Callback invoked immediately before an authorization popup opens. */
   onPopupWindow;
   constructor(serverUrl, options = {}) {
     if (options.staticClientInfo?.client_secret) {
@@ -931,10 +1183,11 @@ var BrowserOAuthClientProvider = class {
       );
     }
     this.serverUrl = serverUrl;
+    this.storage = new LocalStorageKVStore();
     this.session = new OAuthSessionStore(
       serverUrl,
       { ...options, allowClientSecret: false },
-      new LocalStorageKVStore()
+      this.storage
     );
     this.preventAutoAuth = options.preventAutoAuth;
     this.useRedirectFlow = options.useRedirectFlow;
@@ -945,33 +1198,54 @@ 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;
+  }
   /**
    * Re-anchor an SDK-derived OAuth discovery URL from the MCP connection
    * (proxy) origin onto the actual MCP server.
@@ -999,8 +1273,8 @@ var BrowserOAuthClientProvider = class {
       const [doc, ...suffixParts] = rest.split("/");
       if (!doc) return url;
       const suffix = suffixParts.length ? `/${suffixParts.join("/")}` : "";
-      const connectionPath = connection.pathname.replace(/\/+$/, "");
-      const targetPath = target.pathname.replace(/\/+$/, "");
+      const connectionPath = trimTrailingSlashes(connection.pathname);
+      const targetPath = trimTrailingSlashes(target.pathname);
       const newSuffix = suffix && suffix === connectionPath ? targetPath : suffix;
       return `${target.origin}/.well-known/${doc}${newSuffix}${requested.search}`;
     } catch {
@@ -1019,20 +1293,19 @@ var BrowserOAuthClientProvider = class {
    * therefore never alters fetch behavior for other servers, other
    * connections, or the rest of the page.
    *
-   * When this provider is not configured to proxy OAuth requests (no
-   * `oauthProxyUrl`, or `proxyOAuthRequests` disabled), the provided
-   * `baseFetch` is returned as-is (or `undefined` when none is given, letting
-   * the SDK fall back to its default `fetch`).
+   * OAuth metadata is always fetched with `cache: "no-store"`, including in
+   * direct mode. Authorization servers commonly vary CORS headers by Origin;
+   * bypassing the browser HTTP cache prevents a revalidated response cached
+   * for another localhost origin from poisoning discovery. When OAuth proxying
+   * is disabled or no `oauthProxyUrl` is configured, all requests still go
+   * directly to their original URLs.
    *
    * @param baseFetch - The fetch used for non-OAuth requests and for the
    *   underlying proxy calls. Defaults to the global `fetch`.
    */
   getProxyFetch(baseFetch) {
-    if (!this.proxyOAuthRequests || !this.oauthProxyUrl) {
-      return baseFetch;
-    }
     const base = baseFetch ?? globalThis.fetch.bind(globalThis);
-    const oauthProxyUrl = this.oauthProxyUrl;
+    const oauthProxyUrl = this.proxyOAuthRequests && this.oauthProxyUrl ? this.oauthProxyUrl : void 0;
     const discoveredEndpoints = /* @__PURE__ */ new Set();
     let restoredDiscovery = false;
     return async (input, init) => {
@@ -1045,6 +1318,12 @@ var BrowserOAuthClientProvider = class {
         return await base(input, init);
       }
       const isMetadata = pathname.includes("/.well-known/");
+      if (!oauthProxyUrl) {
+        return await base(
+          isMetadata ? url : input,
+          isMetadata ? { ...init, cache: "no-store" } : init
+        );
+      }
       if (!restoredDiscovery) {
         restoredDiscovery = true;
         const metadata = (await this.discoveryState())?.authorizationServerMetadata;
@@ -1079,7 +1358,8 @@ var BrowserOAuthClientProvider = class {
       if (isMetadata) {
         const response2 = await base(proxyEndpoint, {
           ...init,
-          method: "GET"
+          method: "GET",
+          cache: "no-store"
         });
         try {
           const metadata = await response2.clone().json();
@@ -1097,23 +1377,40 @@ var BrowserOAuthClientProvider = class {
         }
         return response2;
       }
-      const body = init?.body ? await serializeBody(init.body) : void 0;
+      const inputRequest = input instanceof Request ? input : void 0;
+      const method = init?.method ?? inputRequest?.method ?? "POST";
+      const requestHeaders = init?.headers ?? inputRequest?.headers;
+      let body;
+      if (init?.body !== void 0 && init.body !== null) {
+        body = await serializeBody(init.body);
+      } else if (inputRequest?.body && method !== "GET" && method !== "HEAD") {
+        body = await inputRequest.clone().text();
+      }
       const response = await base(proxyEndpoint, {
         method: "POST",
         headers: { "Content-Type": "application/json" },
         body: JSON.stringify({
           serverUrl: this.serverUrl,
           url,
-          method: init?.method || "POST",
-          headers: init?.headers ? Object.fromEntries(new Headers(init.headers)) : {},
+          method,
+          headers: requestHeaders ? Object.fromEntries(new Headers(requestHeaders)) : {},
           body
         })
       });
       const data = await response.json();
+      if (!response.ok || typeof data.status !== "number") {
+        return new Response(JSON.stringify(data), {
+          status: response.status,
+          statusText: response.statusText,
+          headers: response.headers
+        });
+      }
       return new Response(JSON.stringify(data.body), {
         status: data.status,
-        statusText: data.statusText,
-        headers: new Headers(data.headers)
+        statusText: typeof data.statusText === "string" ? data.statusText : void 0,
+        headers: new Headers(
+          data.headers && typeof data.headers === "object" ? data.headers : void 0
+        )
       });
     };
   }
@@ -1128,15 +1425,41 @@ var BrowserOAuthClientProvider = class {
     return this.session.tokens(ctx);
   }
   saveTokens(tokens, ctx) {
+    this.lastAttemptedAuthUrl = null;
+    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;
-    return this.session.saveClientInformation(clientInformation, ctx);
+    const { client_secret: discardedClientSecret, ...publicClientInformation } = clientInformation;
+    if (discardedClientSecret) {
+      console.info(
+        `[${this.storageKeyPrefix}] Discarded client_secret returned for a public browser OAuth client.`
+      );
+    }
+    return this.session.saveClientInformation(
+      publicClientInformation,
+      ctx
+    );
   }
   codeVerifier() {
     return this.session.codeVerifier();
@@ -1185,20 +1508,26 @@ var BrowserOAuthClientProvider = class {
    * use `redirectToAuthorization` for that.
    */
   async prepareAuthorizationUrl(authorizationUrl) {
-    return this.session.storeAuthorizationState(authorizationUrl, {
-      extraProviderOptions: {
-        oauthProxyUrl: this.oauthProxyUrl,
-        ...this.clientMetadataUrl ? { clientMetadataUrl: this.clientMetadataUrl } : {},
-        ...this.staticClientInfo ? { staticClientInfo: this.staticClientInfo } : {},
-        ...this.scope ? { scope: this.scope } : {}
-      },
-      flowType: this.useRedirectFlow ? "redirect" : "popup",
-      returnUrl: typeof window !== "undefined" ? window.location.href : void 0
-    });
+    const prepared = await this.session.storeAuthorizationState(
+      authorizationUrl,
+      {
+        extraProviderOptions: {
+          oauthProxyUrl: this.oauthProxyUrl,
+          ...this.clientMetadataUrl ? { clientMetadataUrl: this.clientMetadataUrl } : {},
+          ...this.staticClientInfo ? { staticClientInfo: this.staticClientInfo } : {},
+          ...this.scope ? { scope: this.scope } : {}
+        },
+        flowType: this.useRedirectFlow ? "redirect" : "popup",
+        returnUrl: typeof window !== "undefined" ? window.location.href : void 0
+      }
+    );
+    this.lastAttemptedAuthUrl = prepared;
+    this.authorizationPending = true;
+    return prepared;
   }
   /**
    * 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);
@@ -1246,40 +1575,27 @@ var BrowserOAuthClientProvider = class {
    * Retrieves the last URL passed to `redirectToAuthorization`. Useful for manual fallback.
    */
   getLastAttemptedAuthUrl() {
-    const storedUrl = localStorage.getItem(this.getKey("last_auth_url"));
-    if (!storedUrl) return null;
-    return sanitizeUrl(storedUrl);
+    return this.lastAttemptedAuthUrl;
   }
+  /**
+   * Removes OAuth state stored for this server.
+   *
+   * @returns The number of storage entries removed.
+   */
   clearStorage() {
+    this.lastAttemptedAuthUrl = null;
+    this.authorizationPending = false;
     const prefixPattern = `${this.storageKeyPrefix}_${this.serverUrlHash}_`;
-    const statePattern = `${this.storageKeyPrefix}:state_`;
     const keysToRemove = [];
     let count = 0;
-    for (let i = 0; i < localStorage.length; i++) {
-      const key = localStorage.key(i);
-      if (!key) continue;
+    for (const key of this.storage.keys()) {
       if (key.startsWith(prefixPattern)) {
         keysToRemove.push(key);
-      } else if (key.startsWith(statePattern)) {
-        try {
-          const item = localStorage.getItem(key);
-          if (item) {
-            const state = JSON.parse(item);
-            if (state.serverUrlHash === this.serverUrlHash) {
-              keysToRemove.push(key);
-            }
-          }
-        } catch (e) {
-          console.warn(
-            `[${this.storageKeyPrefix}] Error parsing state key ${key} during clearStorage:`,
-            e
-          );
-        }
       }
     }
     const uniqueKeysToRemove = [...new Set(keysToRemove)];
     uniqueKeysToRemove.forEach((key) => {
-      localStorage.removeItem(key);
+      this.storage.remove(key);
       count++;
     });
     return count;
@@ -1487,20 +1803,14 @@ function renderResult(title, message, error, returnUrl) {
   }
   document.body.appendChild(container);
 }
-function findStoredState(state) {
-  const defaultKey = `mcp:auth:state_${state}`;
-  let key = localStorage.getItem(defaultKey) ? defaultKey : null;
-  if (!key) {
-    const suffix = `:state_${state}`;
-    for (let index = 0; index < localStorage.length; index++) {
-      const candidate = localStorage.key(index);
-      if (candidate?.endsWith(suffix)) {
-        key = candidate;
-        break;
-      }
-    }
-  }
-  const serialized = key ? localStorage.getItem(key) : null;
+async function findStoredState(state) {
+  const store = new LocalStorageKVStore();
+  const legacySuffix = `:state_${state}`;
+  const scopedSuffix = `_state_${state}`;
+  const key = (await store.keys()).find(
+    (candidate) => candidate.endsWith(legacySuffix) || candidate.endsWith(scopedSuffix)
+  );
+  const serialized = key ? await store.get(key) : null;
   if (!key || !serialized) {
     throw new Error(`Invalid or expired OAuth state "${state}".`);
   }
@@ -1508,10 +1818,10 @@ function findStoredState(state) {
   try {
     value = JSON.parse(serialized);
   } catch {
-    localStorage.removeItem(key);
+    await store.remove(key);
     throw new Error("Failed to parse stored OAuth state.");
   }
-  return { key, value };
+  return { key, value, store };
 }
 function redirectWithError(returnUrl, message) {
   const url = new URL(returnUrl);
@@ -1570,17 +1880,19 @@ async function completeAuthorization() {
   const callbackParams = new URLSearchParams(window.location.search);
   const state = callbackParams.get("state");
   let stateKey = null;
+  let stateStore = null;
   let storedState = null;
   let provider = null;
   try {
     if (!state) {
       throw new Error("OAuth callback is missing the state parameter.");
     }
-    const stored = findStoredState(state);
+    const stored = await findStoredState(state);
     stateKey = stored.key;
+    stateStore = stored.store;
     storedState = stored.value;
     if (!storedState.expiry || storedState.expiry < Date.now()) {
-      localStorage.removeItem(stateKey);
+      await stateStore.remove(stateKey);
       throw new Error(
         "OAuth state has expired. Please start authentication again."
       );
@@ -1595,7 +1907,7 @@ async function completeAuthorization() {
       fetch: provider.getProxyFetch()
     });
     await transport.finishAuth(callbackParams);
-    localStorage.removeItem(stateKey);
+    await stateStore.remove(stateKey);
     signalResult(true, void 0, storedState, {
       state,
       serverUrlHash: storedState.serverUrlHash
@@ -1603,8 +1915,12 @@ async function completeAuthorization() {
   } catch (error) {
     const message = error instanceof Error ? error.message : String(error);
     console.error("[mcp-callback] OAuth callback failed:", error);
-    if (stateKey) localStorage.removeItem(stateKey);
-    if (provider) localStorage.removeItem(provider.getKey("last_auth_url"));
+    if (stateKey && stateStore) await stateStore.remove(stateKey);
+    if (provider) {
+      await (stateStore ?? new LocalStorageKVStore()).remove(
+        provider.getKey("last_auth_url")
+      );
+    }
     signalResult(false, message, storedState, {
       state,
       serverUrlHash: storedState?.serverUrlHash
@@ -1646,11 +1962,12 @@ async function completeOAuthFlow(provider, serverUrl, options = {}) {
       throw new Error(`Unexpected OAuth auth() result: ${result}`);
     }
   }
-  if (typeof flowProvider.getAuthorizationCode === "function") {
-    const code = await flowProvider.getAuthorizationCode();
+  if (typeof flowProvider.getAuthorizationResponse === "function" || typeof flowProvider.getAuthorizationCode === "function") {
+    const response = typeof flowProvider.getAuthorizationResponse === "function" ? await flowProvider.getAuthorizationResponse() : { code: await flowProvider.getAuthorizationCode() };
     await auth(provider, {
       serverUrl,
-      authorizationCode: code,
+      authorizationCode: response.code,
+      ...response.iss !== void 0 ? { iss: response.iss } : {},
       fetchFn
     });
     return;
@@ -1664,6 +1981,8 @@ async function waitForBrowserAuthComplete(provider, timeoutMs) {
     );
   }
   if (provider.useRedirectFlow) {
+    await new Promise(() => {
+    });
     return;
   }
   const tokensKey = provider.getKey?.("tokens");
@@ -1680,25 +1999,29 @@ async function waitForBrowserAuthComplete(provider, timeoutMs) {
     } catch {
     }
   }
-  const result = await runAuthPopup({
-    popup: null,
-    state,
-    tokensKey,
-    timeoutMs
-  });
-  switch (result.kind) {
-    case "success":
-      return;
-    case "cancelled":
-      throw new Error("OAuth authentication was cancelled.");
-    case "timeout":
-      throw new Error(
-        `OAuth callback not received within ${timeoutMs}ms. Ensure /oauth/callback calls onMcpAuthorization().`
-      );
-    case "error":
-      throw new Error(result.error);
-    default:
-      throw new Error("Unexpected OAuth popup result");
+  try {
+    const result = await runAuthPopup({
+      popup: null,
+      state,
+      tokensKey,
+      timeoutMs
+    });
+    switch (result.kind) {
+      case "success":
+        return;
+      case "cancelled":
+        throw new Error("OAuth authentication was cancelled.");
+      case "timeout":
+        throw new Error(
+          `OAuth callback not received within ${timeoutMs}ms. Ensure /oauth/callback calls onMcpAuthorization().`
+        );
+      case "error":
+        throw new Error(result.error);
+      default:
+        throw new Error("Unexpected OAuth popup result");
+    }
+  } finally {
+    provider.markFlowComplete?.();
   }
 }
 
@@ -1769,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) {
@@ -1951,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];
@@ -2020,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");
@@ -2031,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;
   }
@@ -2041,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) {
@@ -2078,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;
   }
@@ -2110,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");
@@ -2235,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");
@@ -2270,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");
@@ -2290,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");
@@ -2297,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");
@@ -2396,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(/\/$/, "");
@@ -2513,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");
@@ -2741,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",
@@ -2749,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;
   }
@@ -3117,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;
@@ -3329,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 = {};
   /**
@@ -3378,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
@@ -3520,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
@@ -3690,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
@@ -3859,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);
   }