@mcp-use/client 0.0.0-bootstrap.0 → 2.0.0-beta.1

package/dist/index-browser.js

@@ -0,0 +1,4150 @@
+// src/telemetry/client-telemetry.ts
+var tracker;
+function setClientTelemetryTracker(nextTracker) {
+  tracker = nextTracker;
+}
+function trackClientAddServer(name, config) {
+  void tracker?.addServer(name, config);
+}
+function trackClientRemoveServer(name) {
+  void tracker?.removeServer(name);
+}
+
+// src/telemetry/connector-telemetry.ts
+var tracker2;
+function setConnectorTelemetryTracker(nextTracker) {
+  tracker2 = nextTracker;
+}
+function trackConnectorTelemetry(data) {
+  void tracker2?.(data);
+}
+
+// src/utils/logging.ts
+var LEVELS = [
+  "silent",
+  "error",
+  "warn",
+  "info",
+  "http",
+  "verbose",
+  "debug",
+  "silly"
+];
+var EMOJI = {
+  silent: "",
+  error: "\u274C",
+  warn: "\u26A0\uFE0F",
+  info: "\u2139\uFE0F",
+  http: "\u{1F310}",
+  verbose: "\u{1F4DD}",
+  debug: "\u{1F50D}",
+  silly: "\u{1F92A}"
+};
+function envLevel() {
+  let raw;
+  try {
+    raw = typeof process !== "undefined" ? process.env?.MCP_USE_LOG_LEVEL ?? process.env?.DEBUG : void 0;
+  } catch {
+  }
+  const v = raw?.trim().toLowerCase();
+  if (v === "2") return "debug";
+  if (v && LEVELS.includes(v)) return v;
+  return "info";
+}
+var SimpleConsoleLogger = class {
+  constructor(name = "mcp-use", level = "info", format = "minimal") {
+    this.name = name;
+    this.level = level;
+    this.format = format;
+  }
+  write(level, message, args) {
+    if (this.level === "silent" || LEVELS.indexOf(level) > LEVELS.indexOf(this.level)) {
+      return;
+    }
+    const extra = args.map((a) => {
+      if (typeof a === "string") return a;
+      try {
+        return JSON.stringify(a);
+      } catch {
+        return String(a);
+      }
+    }).join(" ");
+    const full = extra ? `${message} ${extra}` : message;
+    const ts = (/* @__PURE__ */ new Date()).toLocaleTimeString("en-US", { hour12: false });
+    const label = this.format === "minimal" ? level : level.toUpperCase();
+    const emoji = this.format === "emoji" ? ` ${EMOJI[level]}` : "";
+    const line = `${ts} [${this.name}]${emoji} ${label}: ${full}`;
+    const fn = level === "error" ? console.error : level === "warn" ? console.warn : level === "info" ? console.info : level === "debug" ? console.debug : console.log;
+    fn(line);
+  }
+  error = (m, ...a) => this.write("error", m, a);
+  warn = (m, ...a) => this.write("warn", m, a);
+  info = (m, ...a) => this.write("info", m, a);
+  debug = (m, ...a) => this.write("debug", m, a);
+  http = (m, ...a) => this.write("http", m, a);
+  verbose = (m, ...a) => this.write("verbose", m, a);
+  silly = (m, ...a) => this.write("silly", m, a);
+  setFormat(format) {
+    this.format = format;
+  }
+};
+var Logger = class {
+  static instances = {};
+  static currentFormat = "minimal";
+  static currentLevel;
+  static get(name = "mcp-use") {
+    return this.instances[name] ??= new SimpleConsoleLogger(
+      name,
+      this.currentLevel ?? envLevel(),
+      this.currentFormat
+    );
+  }
+  static configure({
+    level = envLevel(),
+    format = "minimal"
+  } = {}) {
+    this.currentLevel = level;
+    this.currentFormat = format;
+    for (const log of Object.values(this.instances)) {
+      log.level = level;
+      log.format = format;
+    }
+  }
+  static setDebug(enabled) {
+    const level = enabled === 2 || enabled === true ? "debug" : "info";
+    this.currentLevel = level;
+    for (const log of Object.values(this.instances)) log.level = level;
+    try {
+      if (typeof process !== "undefined" && process.env) {
+        process.env.MCP_USE_LOG_LEVEL = level;
+      }
+    } catch {
+    }
+  }
+  static setFormat(format) {
+    this.configure({ format });
+  }
+};
+var logger = Logger.get();
+
+// src/utils/version.ts
+var VERSION = "2.0.0-beta.0";
+function getPackageVersion() {
+  return VERSION;
+}
+
+// src/telemetry/events.ts
+var BaseTelemetryEvent = class {
+};
+var MCPAgentExecutionEvent = class extends BaseTelemetryEvent {
+  constructor(data) {
+    super();
+    this.data = data;
+  }
+  get name() {
+    return "mcp_agent_execution";
+  }
+  get properties() {
+    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,
+      // Execution parameters (always include, even if null)
+      max_steps_used: this.data.maxStepsUsed,
+      manage_connector: this.data.manageConnector,
+      external_history_used: this.data.externalHistoryUsed,
+      // 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,
+      conversation_history_length: this.data.conversationHistoryLength ?? null
+    };
+  }
+};
+var MCPClientInitEvent = class extends BaseTelemetryEvent {
+  constructor(data) {
+    super();
+    this.data = data;
+  }
+  get name() {
+    return "mcpclient_init";
+  }
+  get properties() {
+    return {
+      code_mode: this.data.codeMode,
+      sandbox: this.data.sandbox,
+      all_callbacks: this.data.allCallbacks,
+      verify: this.data.verify,
+      servers: this.data.servers,
+      num_servers: this.data.numServers,
+      is_browser: this.data.isBrowser
+    };
+  }
+};
+var ConnectorInitEvent = class extends BaseTelemetryEvent {
+  constructor(data) {
+    super();
+    this.data = data;
+  }
+  get name() {
+    return "connector_init";
+  }
+  get properties() {
+    return {
+      connector_type: this.data.connectorType,
+      server_command: this.data.serverCommand ?? null,
+      server_args: this.data.serverArgs ?? null,
+      server_url: this.data.serverUrl ?? null,
+      public_identifier: this.data.publicIdentifier ?? null
+    };
+  }
+};
+var ClientAddServerEvent = class extends BaseTelemetryEvent {
+  constructor(data) {
+    super();
+    this.data = data;
+  }
+  get name() {
+    return "client_add_server";
+  }
+  get properties() {
+    const { serverName, serverConfig } = this.data;
+    const url = serverConfig.url;
+    return {
+      server_name: serverName,
+      server_url_domain: url ? this._extractHostname(url) : null,
+      transport: serverConfig.transport ?? null,
+      has_auth: !!(serverConfig.authToken || serverConfig.authProvider)
+    };
+  }
+  _extractHostname(url) {
+    try {
+      return new URL(url).hostname;
+    } catch {
+      return null;
+    }
+  }
+};
+var ClientRemoveServerEvent = class extends BaseTelemetryEvent {
+  constructor(data) {
+    super();
+    this.data = data;
+  }
+  get name() {
+    return "client_remove_server";
+  }
+  get properties() {
+    return {
+      server_name: this.data.serverName
+    };
+  }
+};
+
+// src/telemetry/tel-fetch.ts
+async function telFetch(url, init) {
+  try {
+    await fetch(url, init);
+  } catch {
+  }
+}
+var POSTHOG_HOST = "https://eu.i.posthog.com";
+var POSTHOG_API_KEY = "phc_lyTtbYwvkdSbrcMQNPiKiiRWrrM1seyKIMjycSvItEI";
+var SCARF_GATEWAY_URL = "https://mcpuse.gateway.scarf.sh/events-ts";
+var SCARF_GATEWAY_BEACON_URL = "https://mcpuse.gateway.scarf.sh/simple/";
+var SCARF_BEACON_MAX_URL = 1800;
+var SCARF_BEACON_TRUNCATED_KEYS = /* @__PURE__ */ new Set(["query", "response", "messages"]);
+function stringifyScarfValue(value) {
+  if (value === null || value === void 0) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "boolean") {
+    return String(value);
+  }
+  try {
+    return JSON.stringify(value);
+  } catch {
+    return String(value);
+  }
+}
+function buildScarfBeaconUrl(properties, baseUrl = SCARF_GATEWAY_BEACON_URL) {
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(properties)) {
+    let serialized = stringifyScarfValue(value);
+    if (SCARF_BEACON_TRUNCATED_KEYS.has(key) && serialized.length > 120) {
+      serialized = `${serialized.slice(0, 117)}...`;
+    }
+    if (serialized !== "") params.set(key, serialized);
+  }
+  let url = `${baseUrl}${baseUrl.includes("?") ? "&" : "?"}${params.toString()}`;
+  if (url.length <= SCARF_BEACON_MAX_URL) return url;
+  const keys = [...params.keys()].sort(
+    (a, b) => (params.get(b)?.length ?? 0) - (params.get(a)?.length ?? 0)
+  );
+  for (const key of keys) {
+    if (url.length <= SCARF_BEACON_MAX_URL) break;
+    if (key === "event" || key === "user_id") continue;
+    params.delete(key);
+    url = `${baseUrl}${baseUrl.includes("?") ? "&" : "?"}${params.toString()}`;
+  }
+  return url.slice(0, SCARF_BEACON_MAX_URL);
+}
+function captureScarfPost(properties, endpoint) {
+  return telFetch(endpoint, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    keepalive: true,
+    body: JSON.stringify(properties)
+  });
+}
+function captureScarfBeacon(properties, endpoint) {
+  try {
+    const url = buildScarfBeaconUrl(properties, endpoint);
+    const img = new Image();
+    img.referrerPolicy = "no-referrer-when-downgrade";
+    img.src = url;
+  } catch {
+  }
+  return Promise.resolve();
+}
+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({
+      api_key: apiKey,
+      event: params.event,
+      distinct_id: params.distinctId,
+      properties: params.properties,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    })
+  });
+}
+function captureScarf(properties, endpoint = SCARF_GATEWAY_URL) {
+  if (typeof window !== "undefined") {
+    const beaconEndpoint = endpoint === SCARF_GATEWAY_URL ? SCARF_GATEWAY_BEACON_URL : endpoint;
+    return captureScarfBeacon(properties, beaconEndpoint);
+  }
+  return captureScarfPost(properties, endpoint);
+}
+
+// src/telemetry/telemetry.ts
+function generateUUID() {
+  return globalThis.crypto.randomUUID();
+}
+function secureRandomString() {
+  const array = new Uint8Array(8);
+  globalThis.crypto.getRandomValues(array);
+  return Array.from(array, (v) => v.toString(16).padStart(2, "0")).join("");
+}
+function isVersionGreater(a, b) {
+  const parse = (v) => v.split("-")[0].split(".").map((n) => parseInt(n, 10) || 0);
+  const pa = parse(a);
+  const pb = parse(b);
+  const len = Math.max(pa.length, pb.length);
+  for (let i = 0; i < len; i++) {
+    const da = pa[i] ?? 0;
+    const db = pb[i] ?? 0;
+    if (da !== db) return da > db;
+  }
+  return false;
+}
+var USER_ID_STORAGE_KEY = "mcp_use_user_id";
+var PROJECT_API_KEY = "phc_lyTtbYwvkdSbrcMQNPiKiiRWrrM1seyKIMjycSvItEI";
+var HOST = "https://eu.i.posthog.com";
+var configuredStorage = null;
+function isLocalStorageFunctional() {
+  return typeof localStorage !== "undefined" && typeof localStorage.getItem === "function" && typeof localStorage.setItem === "function" && typeof localStorage.removeItem === "function";
+}
+function createLocalStorageBackend() {
+  if (!isLocalStorageFunctional()) return null;
+  try {
+    localStorage.setItem("__mcp_use_test__", "1");
+    localStorage.removeItem("__mcp_use_test__");
+  } catch {
+    return null;
+  }
+  return {
+    getUserId() {
+      try {
+        return localStorage.getItem(USER_ID_STORAGE_KEY);
+      } catch {
+        return null;
+      }
+    },
+    setUserId(id) {
+      try {
+        localStorage.setItem(USER_ID_STORAGE_KEY, id);
+      } catch {
+      }
+    },
+    // Package-download dedup is node/Scarf-oriented; localStorage unused.
+    getDownloadedVersion: () => null,
+    setDownloadedVersion: () => void 0
+  };
+}
+function detectRuntimeEnvironment() {
+  try {
+    if (typeof globalThis.Bun !== "undefined") {
+      return "bun";
+    }
+    if (typeof globalThis.Deno !== "undefined") {
+      return "deno";
+    }
+    if (typeof navigator !== "undefined" && navigator.userAgent?.includes("Cloudflare-Workers")) {
+      return "cloudflare-workers";
+    }
+    if (typeof globalThis.EdgeRuntime !== "undefined") {
+      return "edge";
+    }
+    if (typeof window !== "undefined" && typeof document !== "undefined") {
+      return "browser";
+    }
+    if (typeof process !== "undefined" && typeof process.versions?.node !== "undefined") {
+      return "node";
+    }
+    return "unknown";
+  } catch {
+    return "unknown";
+  }
+}
+function readSourceHint() {
+  if (typeof process !== "undefined" && process.env?.MCP_USE_TELEMETRY_SOURCE) {
+    return process.env.MCP_USE_TELEMETRY_SOURCE;
+  }
+  try {
+    if (isLocalStorageFunctional()) {
+      return localStorage.getItem("MCP_USE_TELEMETRY_SOURCE") ?? void 0;
+    }
+  } catch {
+  }
+  return void 0;
+}
+function isTelemetryDisabled() {
+  if (typeof window !== "undefined" && window.__MCP_USE_ANONYMIZED_TELEMETRY__ === false) {
+    return true;
+  }
+  if (typeof process !== "undefined" && process.env?.MCP_USE_ANONYMIZED_TELEMETRY?.toLowerCase() === "false") {
+    return true;
+  }
+  try {
+    if (isLocalStorageFunctional() && localStorage.getItem("MCP_USE_ANONYMIZED_TELEMETRY") === "false") {
+      return true;
+    }
+  } catch {
+  }
+  return false;
+}
+function sessionId() {
+  try {
+    return `session-${generateUUID()}`;
+  } catch {
+    return `session-${Date.now()}-${secureRandomString()}`;
+  }
+}
+var Telemetry = class _Telemetry {
+  static instance = null;
+  UNKNOWN_USER_ID = "UNKNOWN_USER_ID";
+  _currUserId = null;
+  _telemetryEnabled = false;
+  _pending = /* @__PURE__ */ new Set();
+  _scarfEnabled = false;
+  _runtimeEnvironment;
+  _storageCapability;
+  _storage;
+  /** True when node entry installed fs storage (package-download dedup). */
+  _fsBacked;
+  _source;
+  _productVersion;
+  constructor() {
+    this._runtimeEnvironment = detectRuntimeEnvironment();
+    this._fsBacked = configuredStorage !== null;
+    this._storage = configuredStorage ?? createLocalStorageBackend() ?? null;
+    this._storageCapability = this._storage ? "persistent" : "session-only";
+    this._source = readSourceHint() || this._runtimeEnvironment;
+    const disabled = isTelemetryDisabled();
+    const canSupport = this._runtimeEnvironment !== "unknown";
+    if (disabled) {
+      this._telemetryEnabled = false;
+      logger.debug("Telemetry disabled via opt-out");
+    } else if (!canSupport) {
+      this._telemetryEnabled = false;
+      logger.debug(
+        `Telemetry disabled - unknown environment: ${this._runtimeEnvironment}`
+      );
+    } else {
+      logger.debug(
+        "Anonymized telemetry enabled. Set MCP_USE_ANONYMIZED_TELEMETRY=false to disable."
+      );
+      this._telemetryEnabled = true;
+      this._scarfEnabled = true;
+      if (this._fsBacked) {
+        setTimeout(() => {
+          this.trackPackageDownload({ triggered_by: "initialization" }).catch(
+            (e) => logger.debug(`Failed to track package download: ${e}`)
+          );
+        }, 0);
+      }
+    }
+  }
+  get runtimeEnvironment() {
+    return this._runtimeEnvironment;
+  }
+  get storageCapability() {
+    return this._storageCapability;
+  }
+  static getInstance() {
+    if (!_Telemetry.instance) {
+      _Telemetry.instance = new _Telemetry();
+    }
+    return _Telemetry.instance;
+  }
+  setSource(source) {
+    this._source = source;
+    try {
+      if (isLocalStorageFunctional()) {
+        localStorage.setItem("MCP_USE_TELEMETRY_SOURCE", source);
+      }
+    } catch {
+    }
+    logger.debug(`Telemetry source set to: ${source}`);
+  }
+  getSource() {
+    return this._source;
+  }
+  setProductVersion(version) {
+    this._productVersion = version;
+  }
+  get isEnabled() {
+    return this._telemetryEnabled || this._scarfEnabled;
+  }
+  get userId() {
+    if (this._currUserId) return this._currUserId;
+    try {
+      if (this._storage) {
+        const existing = this._storage.getUserId();
+        if (existing) {
+          this._currUserId = existing;
+          return existing;
+        }
+        const id = generateUUID();
+        this._storage.setUserId(id);
+        this._currUserId = id;
+        return id;
+      }
+      this._currUserId = sessionId();
+    } catch {
+      this._currUserId = this.UNKNOWN_USER_ID;
+    }
+    return this._currUserId;
+  }
+  async capture(event) {
+    if (!this._telemetryEnabled && !this._scarfEnabled) return;
+    const currentUserId = this.userId;
+    const properties = {
+      ...event.properties,
+      mcp_use_version: this._productVersion ?? getPackageVersion(),
+      language: "typescript",
+      source: this._source,
+      runtime: this._runtimeEnvironment
+    };
+    if (this._telemetryEnabled) {
+      const p = capturePostHog({
+        host: HOST,
+        apiKey: PROJECT_API_KEY,
+        event: event.name,
+        distinctId: currentUserId,
+        properties
+      });
+      this._pending.add(p);
+      void p.finally(() => this._pending.delete(p));
+    }
+    if (this._scarfEnabled) {
+      const p = captureScarf({
+        ...properties,
+        user_id: currentUserId,
+        event: event.name
+      });
+      this._pending.add(p);
+      void p.finally(() => this._pending.delete(p));
+    }
+  }
+  async trackPackageDownload(properties) {
+    if (!this._scarfEnabled || !this._fsBacked || !this._storage) return;
+    const currentVersion = getPackageVersion();
+    const saved = this._storage.getDownloadedVersion();
+    let firstDownload = false;
+    let shouldTrack = false;
+    if (!saved) {
+      shouldTrack = true;
+      firstDownload = true;
+      this._storage.setDownloadedVersion(currentVersion);
+    } else if (isVersionGreater(currentVersion, saved)) {
+      shouldTrack = true;
+      this._storage.setDownloadedVersion(currentVersion);
+    }
+    if (!shouldTrack) return;
+    await captureScarf({
+      ...properties || {},
+      mcp_use_version: currentVersion,
+      user_id: this.userId,
+      event: "package_download",
+      first_download: firstDownload,
+      language: "typescript",
+      source: this._source,
+      runtime: this._runtimeEnvironment
+    });
+  }
+  async trackAgentExecution(data) {
+    if (!this.isEnabled) return;
+    await this.capture(new MCPAgentExecutionEvent(data));
+  }
+  async trackMCPClientInit(data) {
+    if (!this.isEnabled) return;
+    await this.capture(new MCPClientInitEvent(data));
+  }
+  async trackConnectorInit(data) {
+    if (!this.isEnabled) return;
+    await this.capture(new ConnectorInitEvent(data));
+  }
+  async trackClientAddServer(serverName, serverConfig) {
+    if (!this.isEnabled) return;
+    await this.capture(new ClientAddServerEvent({ serverName, serverConfig }));
+  }
+  async trackClientRemoveServer(serverName) {
+    if (!this.isEnabled) return;
+    await this.capture(new ClientRemoveServerEvent({ serverName }));
+  }
+  async trackUseMcpConnection(data) {
+    if (!this.isEnabled) return;
+    await this.capture({
+      name: "usemcp_connection",
+      properties: {
+        url_domain: new URL(data.url).hostname,
+        transport_type: data.transportType,
+        success: data.success,
+        error_type: data.errorType ?? null,
+        connection_time_ms: data.connectionTimeMs ?? null,
+        has_oauth: data.hasOAuth,
+        has_sampling: data.hasSampling,
+        has_elicitation: data.hasElicitation
+      }
+    });
+  }
+  async trackUseMcpToolCall(data) {
+    if (!this.isEnabled) return;
+    await this.capture({
+      name: "usemcp_tool_call",
+      properties: {
+        tool_name: data.toolName,
+        success: data.success,
+        error_type: data.errorType ?? null,
+        execution_time_ms: data.executionTimeMs ?? null
+      }
+    });
+  }
+  async trackUseMcpResourceRead(data) {
+    if (!this.isEnabled) return;
+    await this.capture({
+      name: "usemcp_resource_read",
+      properties: {
+        resource_uri_scheme: data.resourceUri.split(":")[0],
+        success: data.success,
+        error_type: data.errorType ?? null
+      }
+    });
+  }
+  identify(userId, properties) {
+    this._currUserId = userId;
+    this._storage?.setUserId(userId);
+    if (this._telemetryEnabled) {
+      void capturePostHog({
+        host: HOST,
+        apiKey: PROJECT_API_KEY,
+        event: "$identify",
+        distinctId: userId,
+        properties: { $set: properties ?? {} }
+      });
+    }
+  }
+  reset() {
+    this._currUserId = null;
+  }
+  flush() {
+    void Promise.allSettled([...this._pending]);
+  }
+  async shutdown() {
+    try {
+      await Promise.allSettled([...this._pending]);
+      logger.debug("Telemetry fetch captures flushed");
+    } catch (e) {
+      logger.debug(`Error flushing telemetry captures: ${e}`);
+    }
+  }
+};
+var Tel = Telemetry;
+function setTelemetrySource(source) {
+  Tel.getInstance().setSource(source);
+}
+function setProductVersion(version) {
+  Tel.getInstance().setProductVersion(version);
+}
+
+// src/telemetry/configure-browser.ts
+setClientTelemetryTracker({
+  addServer: (name, config) => Telemetry.getInstance().trackClientAddServer(name, config).catch(() => void 0),
+  removeServer: (name) => Telemetry.getInstance().trackClientRemoveServer(name).catch(() => void 0)
+});
+setConnectorTelemetryTracker(
+  (data) => Telemetry.getInstance().trackConnectorInit(data).catch(() => void 0)
+);
+
+// src/auth/url.ts
+function sanitizeUrl(raw) {
+  const abort = () => {
+    throw new Error(`Invalid url to pass to open(): ${raw}`);
+  };
+  let url;
+  try {
+    url = new URL(raw);
+  } catch (_) {
+    abort();
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") abort();
+  if (url.hostname !== encodeURIComponent(url.hostname)) abort();
+  if (url.username) url.username = encodeURIComponent(url.username);
+  if (url.password) url.password = encodeURIComponent(url.password);
+  url.pathname = url.pathname.slice(0, 1) + encodeURIComponent(url.pathname.slice(1)).replace(/%2f/gi, "/");
+  url.search = url.search.slice(0, 1) + Array.from(url.searchParams.entries()).map(sanitizeParam).join("&");
+  url.hash = url.hash.slice(0, 1) + encodeURIComponent(url.hash.slice(1));
+  return url.href;
+}
+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;
+  serverUrlHash;
+  clientName;
+  clientUri;
+  logoUri;
+  callbackUrl;
+  clientMetadataUrl;
+  scope;
+  store;
+  allowClientSecret;
+  constructor(serverUrl, options, store) {
+    validateClientMetadataUrl(options.clientMetadataUrl);
+    this.serverUrl = serverUrl;
+    this.storageKeyPrefix = options.storageKeyPrefix || "mcp:auth";
+    this.serverUrlHash = _OAuthSessionStore.hashString(serverUrl);
+    this.clientName = options.clientName || "mcp-use";
+    this.clientUri = options.clientUri || (typeof window !== "undefined" ? window.location.origin : "https://mcp-use.com");
+    this.logoUri = options.logoUri || "https://mcp-use.com/logo.png";
+    this.callbackUrl = sanitizeUrl(
+      options.callbackUrl || (typeof window !== "undefined" ? new URL("/oauth/callback", window.location.origin).toString() : "/oauth/callback")
+    );
+    this.clientMetadataUrl = options.clientMetadataUrl;
+    this.scope = options.scope;
+    this.store = store;
+    this.allowClientSecret = options.allowClientSecret ?? true;
+  }
+  getKey(keySuffix) {
+    return `${this.storageKeyPrefix}_${this.serverUrlHash}_${keySuffix}`;
+  }
+  static hashString(str) {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+      const char = str.charCodeAt(i);
+      hash = (hash << 5) - hash + char;
+      hash = hash & hash;
+    }
+    return Math.abs(hash).toString(16);
+  }
+  // --- SDK Interface Methods (delegated) ---
+  get redirectUrl() {
+    return this.callbackUrl;
+  }
+  get clientMetadata() {
+    return {
+      redirect_uris: [this.redirectUrl],
+      token_endpoint_auth_method: "none",
+      grant_types: ["authorization_code", "refresh_token"],
+      response_types: ["code"],
+      client_name: this.clientName,
+      client_uri: this.clientUri,
+      logo_uri: this.logoUri,
+      ...this.scope ? { scope: this.scope } : {}
+    };
+  }
+  credentialKey(kind, ctx) {
+    return ctx ? this.getKey(`${kind}_${encodeURIComponent(ctx.issuer)}`) : this.getKey(kind);
+  }
+  async readCredential(kind, ctx) {
+    const key = this.credentialKey(kind, ctx);
+    const data = await this.store.get(key);
+    if (!data && ctx) {
+      const legacyKey = this.credentialKey(kind);
+      const legacyData = await this.store.get(legacyKey);
+      if (legacyData) {
+        try {
+          const legacyValue = JSON.parse(legacyData);
+          if (!legacyValue.issuer || legacyValue.issuer === ctx.issuer) {
+            const migratedValue = {
+              ...legacyValue,
+              issuer: ctx.issuer
+            };
+            const migratedData = JSON.stringify(migratedValue);
+            await this.store.set(key, migratedData);
+            await this.store.set(legacyKey, migratedData);
+            return { key, value: migratedValue };
+          }
+        } catch {
+          await this.store.remove(legacyKey);
+        }
+      }
+      return void 0;
+    }
+    if (!data) return void 0;
+    try {
+      return { key, value: JSON.parse(data) };
+    } catch (e) {
+      console.warn(
+        `[${this.storageKeyPrefix}] Failed to parse ${kind.replace("_", " ")}:`,
+        e
+      );
+      await this.store.remove(key);
+      return void 0;
+    }
+  }
+  async tokens(ctx) {
+    return (await this.readCredential("tokens", ctx))?.value;
+  }
+  async saveTokens(tokens, ctx) {
+    const serialized = JSON.stringify(tokens);
+    await this.store.set(this.credentialKey("tokens", ctx), serialized);
+    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"));
+  }
+  async clientInformation(ctx) {
+    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"));
+        console.warn(
+          `[${this.storageKeyPrefix}] Removed OAuth client information containing a browser client_secret.`
+        );
+        return void 0;
+      }
+      const storedRedirectUris = Array.isArray(clientInfo.redirect_uris) ? clientInfo.redirect_uris : [];
+      const hasMatchingRedirect = storedRedirectUris.length === 0 || storedRedirectUris.includes(this.redirectUrl);
+      if (!hasMatchingRedirect) {
+        console.info(
+          `[${this.storageKeyPrefix}] Invalidating cached OAuth client info due to redirect URI mismatch.`
+        );
+        await this.store.remove(key);
+        await this.store.remove(this.credentialKey("tokens", ctx));
+        await this.store.remove(this.getKey("last_auth_url"));
+        return void 0;
+      }
+      return clientInfo;
+    } catch {
+      await this.store.remove(key);
+      return void 0;
+    }
+  }
+  async saveClientInformation(clientInformation, ctx) {
+    const info = clientInformation;
+    if (!this.allowClientSecret && info.client_secret) {
+      await this.store.remove(this.credentialKey("client_info", ctx));
+      if (ctx) await this.store.remove(this.credentialKey("client_info"));
+      throw new Error(
+        "Browser OAuth clients must be public clients; client_secret persistence is not allowed."
+      );
+    }
+    const serialized = JSON.stringify(clientInformation);
+    await this.store.set(this.credentialKey("client_info", ctx), serialized);
+    if (ctx) {
+      await this.store.set(this.credentialKey("client_info"), serialized);
+    }
+  }
+  async saveCodeVerifier(codeVerifier) {
+    await this.store.set(this.getKey("code_verifier"), codeVerifier);
+  }
+  async codeVerifier() {
+    const key = this.getKey("code_verifier");
+    const verifier = await this.store.get(key);
+    if (!verifier) {
+      throw new Error(
+        `[${this.storageKeyPrefix}] Code verifier not found in storage for key ${key}. Auth flow likely corrupted or timed out.`
+      );
+    }
+    return verifier;
+  }
+  async invalidateCredentials(scope) {
+    const removeCredentialKeys = async (kind) => {
+      const prefix = `${this.getKey(kind)}_`;
+      for (const key of await this.store.keys()) {
+        if (key === this.getKey(kind) || key.startsWith(prefix)) {
+          await this.store.remove(key);
+        }
+      }
+    };
+    switch (scope) {
+      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("discovery_state"));
+        await this.store.remove(this.getKey("token_endpoint"));
+        break;
+      case "client":
+        await removeCredentialKeys("client_info");
+        break;
+      case "tokens":
+        await removeCredentialKeys("tokens");
+        break;
+      case "verifier":
+        await this.store.remove(this.getKey("code_verifier"));
+        break;
+      case "discovery":
+        await this.store.remove(this.getKey("discovery_state"));
+        break;
+      default:
+        break;
+    }
+  }
+  /**
+   * Persist the OAuth discovery state (authorization-server metadata resolved
+   * during the auth flow). Stored with the same durability as the code
+   * verifier so the callback leg can verify it is exchanging the code at the
+   * same authorization server the redirect targeted (SEP-2352 mix-up defense).
+   */
+  async saveDiscoveryState(state) {
+    await this.store.set(this.getKey("discovery_state"), JSON.stringify(state));
+  }
+  /** Return the previously saved discovery state, or `undefined`. */
+  async discoveryState() {
+    const data = await this.store.get(this.getKey("discovery_state"));
+    if (!data) return void 0;
+    try {
+      return JSON.parse(data);
+    } catch {
+      await this.store.remove(this.getKey("discovery_state"));
+      return void 0;
+    }
+  }
+  // --- Helper / non-SDK methods ---
+  /**
+   * Generates and persists `StoredState` for an authorization request,
+   * appends the `state` query param to the URL, and persists the sanitized
+   * URL to `last_auth_url` so it can be replayed on popup-blocker fallback.
+   *
+   * @returns The sanitized authorization URL string with the `state` param appended.
+   */
+  async storeAuthorizationState(authorizationUrl, opts = {}) {
+    const state = globalThis.crypto.randomUUID();
+    const stateKey = `${this.storageKeyPrefix}:state_${state}`;
+    const stateData = {
+      serverUrlHash: this.serverUrlHash,
+      expiry: Date.now() + 1e3 * 60 * 10,
+      // State expires in 10 minutes
+      providerOptions: {
+        serverUrl: this.serverUrl,
+        storageKeyPrefix: this.storageKeyPrefix,
+        clientName: this.clientName,
+        clientUri: this.clientUri,
+        callbackUrl: this.callbackUrl,
+        ...this.clientMetadataUrl ? { clientMetadataUrl: this.clientMetadataUrl } : {},
+        ...opts.extraProviderOptions ?? {}
+      },
+      flowType: opts.flowType,
+      returnUrl: opts.returnUrl
+    };
+    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_url"), sanitizedAuthUrl);
+    return sanitizedAuthUrl;
+  }
+  /**
+   * Return the token endpoint from SDK-managed discovery state. The SDK
+   * persists this state during `auth()`, avoiding a second discovery flow.
+   */
+  async getTokenEndpoint() {
+    return (await this.discoveryState())?.authorizationServerMetadata?.token_endpoint ?? null;
+  }
+};
+
+// src/auth/browser.ts
+async function serializeBody(body) {
+  if (typeof body === "string") return body;
+  if (body instanceof URLSearchParams || body instanceof FormData) {
+    return Object.fromEntries(body.entries());
+  }
+  if (body instanceof Blob) return await body.text();
+  return body;
+}
+var BrowserOAuthClientProvider = class {
+  serverUrl;
+  staticClientInfo;
+  session;
+  // Browser-only state
+  preventAutoAuth;
+  useRedirectFlow;
+  oauthProxyUrl;
+  connectionUrl;
+  proxyOAuthRequests;
+  onPopupWindow;
+  constructor(serverUrl, options = {}) {
+    if (options.staticClientInfo?.client_secret) {
+      throw new Error(
+        "Browser OAuth clients must be public clients; staticClientInfo.client_secret is not allowed."
+      );
+    }
+    this.serverUrl = serverUrl;
+    this.session = new OAuthSessionStore(
+      serverUrl,
+      { ...options, allowClientSecret: false },
+      new LocalStorageKVStore()
+    );
+    this.preventAutoAuth = options.preventAutoAuth;
+    this.useRedirectFlow = options.useRedirectFlow;
+    this.oauthProxyUrl = options.oauthProxyUrl;
+    this.connectionUrl = options.connectionUrl;
+    this.proxyOAuthRequests = options.proxyOAuthRequests ?? true;
+    this.staticClientInfo = options.staticClientInfo;
+    this.onPopupWindow = options.onPopupWindow;
+  }
+  // --- Identity / key fields exposed for callback handling ---
+  get storageKeyPrefix() {
+    return this.session.storageKeyPrefix;
+  }
+  get serverUrlHash() {
+    return this.session.serverUrlHash;
+  }
+  get clientName() {
+    return this.session.clientName;
+  }
+  get clientUri() {
+    return this.session.clientUri;
+  }
+  get logoUri() {
+    return this.session.logoUri;
+  }
+  get callbackUrl() {
+    return this.session.callbackUrl;
+  }
+  get scope() {
+    return this.session.scope;
+  }
+  get clientMetadataUrl() {
+    return this.session.clientMetadataUrl;
+  }
+  getKey(keySuffix) {
+    return this.session.getKey(keySuffix);
+  }
+  /**
+   * Re-anchor an SDK-derived OAuth discovery URL from the MCP connection
+   * (proxy) origin onto the actual MCP server.
+   *
+   * When MCP traffic is tunneled through a gateway/inspector proxy, the SDK
+   * transport derives `/.well-known/*` URLs from the URL it connected to (the
+   * proxy) whenever no `resource_metadata` hint is available — the SSE
+   * transport's EventSource cannot read `WWW-Authenticate`, and token refresh
+   * runs without a 401 response at hand. The proxy origin serves no OAuth
+   * metadata, so discovery would fail and the server would be misclassified
+   * as "does not support OAuth". Rewriting reproduces what a direct
+   * connection would have requested: the same well-known document, anchored
+   * on the server origin, with the RFC 8414 §3.1 / RFC 9728 §3.1 path
+   * insertion using the server's path instead of the proxy's.
+   */
+  reanchorWellKnownUrl(url) {
+    if (!this.connectionUrl) return url;
+    try {
+      const requested = new URL(url);
+      const connection = new URL(this.connectionUrl);
+      if (requested.origin !== connection.origin) return url;
+      if (!requested.pathname.startsWith("/.well-known/")) return url;
+      const target = new URL(this.serverUrl);
+      const rest = requested.pathname.slice("/.well-known/".length);
+      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 newSuffix = suffix && suffix === connectionPath ? targetPath : suffix;
+      return `${target.origin}/.well-known/${doc}${newSuffix}${requested.search}`;
+    } catch {
+      return url;
+    }
+  }
+  /**
+   * Returns a `fetch` function, scoped to this provider, that routes OAuth
+   * metadata and non-browser OAuth endpoint requests through the configured
+   * `oauthProxyUrl` to bypass CORS. Authorization endpoints are navigated by
+   * the browser and all unrelated requests pass through unchanged.
+   *
+   * Unlike patching the global `fetch`, the returned function only affects the
+   * transport/auth calls it is explicitly handed to (via the SDK transport's
+   * `fetch` option or `auth({ fetchFn })`). Connecting one server "Via Proxy"
+   * 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`).
+   *
+   * @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 discoveredEndpoints = /* @__PURE__ */ new Set();
+    let restoredDiscovery = false;
+    return async (input, init) => {
+      const requestedUrl = typeof input === "string" ? input : input instanceof URL ? input.toString() : input.url;
+      const url = this.reanchorWellKnownUrl(requestedUrl);
+      let pathname;
+      try {
+        pathname = new URL(url).pathname;
+      } catch {
+        return await base(input, init);
+      }
+      const isMetadata = pathname.includes("/.well-known/");
+      if (!restoredDiscovery) {
+        restoredDiscovery = true;
+        const metadata = (await this.discoveryState())?.authorizationServerMetadata;
+        for (const key of [
+          "registration_endpoint",
+          "token_endpoint",
+          "revocation_endpoint",
+          "introspection_endpoint"
+        ]) {
+          if (typeof metadata?.[key] === "string") {
+            discoveredEndpoints.add(metadata[key]);
+          }
+        }
+      }
+      const isProxiedEndpoint = discoveredEndpoints.has(url) || /\/(?:register|registration|token|revoke|revocation|introspect|introspection)\/?$/.test(
+        pathname
+      );
+      if (!isMetadata && !isProxiedEndpoint) {
+        return await base(input, init);
+      }
+      try {
+        const urlObj = new URL(url);
+        const proxyUrlObj = new URL(oauthProxyUrl);
+        if (urlObj.origin === proxyUrlObj.origin && (urlObj.pathname.startsWith(proxyUrlObj.pathname) || url.includes("/inspector/api/oauth"))) {
+          return await base(input, init);
+        }
+      } catch {
+      }
+      const proxyEndpoint = isMetadata ? `${oauthProxyUrl}/metadata?serverUrl=${encodeURIComponent(
+        this.serverUrl
+      )}&url=${encodeURIComponent(url)}` : `${oauthProxyUrl}/proxy`;
+      if (isMetadata) {
+        const response2 = await base(proxyEndpoint, {
+          ...init,
+          method: "GET"
+        });
+        try {
+          const metadata = await response2.clone().json();
+          for (const key of [
+            "registration_endpoint",
+            "token_endpoint",
+            "revocation_endpoint",
+            "introspection_endpoint"
+          ]) {
+            if (typeof metadata[key] === "string") {
+              discoveredEndpoints.add(metadata[key]);
+            }
+          }
+        } catch {
+        }
+        return response2;
+      }
+      const body = init?.body ? await serializeBody(init.body) : void 0;
+      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)) : {},
+          body
+        })
+      });
+      const data = await response.json();
+      return new Response(JSON.stringify(data.body), {
+        status: data.status,
+        statusText: data.statusText,
+        headers: new Headers(data.headers)
+      });
+    };
+  }
+  // --- SDK Interface Methods (delegated) ---
+  get redirectUrl() {
+    return this.session.redirectUrl;
+  }
+  get clientMetadata() {
+    return this.session.clientMetadata;
+  }
+  tokens(ctx) {
+    return this.session.tokens(ctx);
+  }
+  saveTokens(tokens, ctx) {
+    return this.session.saveTokens(tokens, ctx);
+  }
+  async clientInformation(ctx) {
+    if (this.staticClientInfo) return this.staticClientInfo;
+    return this.session.clientInformation(ctx);
+  }
+  async saveClientInformation(clientInformation, ctx) {
+    if (this.staticClientInfo) return;
+    return this.session.saveClientInformation(clientInformation, ctx);
+  }
+  codeVerifier() {
+    return this.session.codeVerifier();
+  }
+  saveCodeVerifier(codeVerifier) {
+    return this.session.saveCodeVerifier(codeVerifier);
+  }
+  invalidateCredentials(scope) {
+    return this.session.invalidateCredentials(scope);
+  }
+  /**
+   * Persist OAuth discovery state (SEP-2352). Delegated to the session store;
+   * implementing this silences the SDK's per-callback warning and enables the
+   * authorization-server mix-up defense on the callback leg.
+   */
+  saveDiscoveryState(state) {
+    return this.session.saveDiscoveryState(state);
+  }
+  /** Return previously saved OAuth discovery state, or `undefined`. */
+  discoveryState() {
+    return this.session.discoveryState();
+  }
+  /**
+   * Return the token endpoint from the SDK's persisted discovery state.
+   * Returns `null` before a successful authorization discovery.
+   */
+  getTokenEndpoint() {
+    return this.session.getTokenEndpoint();
+  }
+  /**
+   * Return the stored public OAuth client ID. Browser providers do not retain
+   * client secrets.
+   */
+  async getClientCredentials() {
+    const info = await this.clientInformation();
+    return info?.client_id ? { client_id: info.client_id } : null;
+  }
+  /**
+   * Generates and persists `StoredState` for an authorization request,
+   * and returns the sanitized URL with the `state` param appended. Does NOT
+   * open a popup or redirect —
+   * 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
+    });
+  }
+  /**
+   * Redirects the user agent to the authorization URL, storing necessary state.
+   * @param authorizationUrl The fully constructed authorization URL from the SDK.
+   */
+  async redirectToAuthorization(authorizationUrl) {
+    const sanitizedAuthUrl = await this.prepareAuthorizationUrl(authorizationUrl);
+    if (this.preventAutoAuth) {
+      console.info(
+        `[${this.storageKeyPrefix}] Auto-auth prevented. Authorization URL stored for manual trigger.`
+      );
+      return;
+    }
+    if (this.useRedirectFlow) {
+      console.info(
+        `[${this.storageKeyPrefix}] Redirecting to authorization URL (full-page redirect).`
+      );
+      window.location.href = sanitizedAuthUrl;
+      return;
+    }
+    const popupFeatures = "width=600,height=700,resizable=yes,scrollbars=yes,status=yes";
+    try {
+      const popup = window.open(
+        sanitizedAuthUrl,
+        `mcp_auth_${this.serverUrlHash}`,
+        popupFeatures
+      );
+      if (this.onPopupWindow) {
+        this.onPopupWindow(sanitizedAuthUrl, popupFeatures, popup);
+      }
+      if (!popup || popup.closed || typeof popup.closed === "undefined") {
+        console.warn(
+          `[${this.storageKeyPrefix}] Popup likely blocked by browser. Manual navigation might be required using the stored URL.`
+        );
+      } else {
+        popup.focus();
+        console.info(
+          `[${this.storageKeyPrefix}] Redirecting to authorization URL in popup.`
+        );
+      }
+    } catch (e) {
+      console.error(
+        `[${this.storageKeyPrefix}] Error opening popup window:`,
+        e
+      );
+    }
+  }
+  /**
+   * 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);
+  }
+  clearStorage() {
+    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;
+      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);
+      count++;
+    });
+    return count;
+  }
+};
+async function createOAuthProvider(serverUrl, options = {}) {
+  return new BrowserOAuthClientProvider(serverUrl, options);
+}
+
+// src/auth/callback.ts
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+
+// src/auth/popup.ts
+var MCP_AUTH_BROADCAST_CHANNEL = "mcp_auth_callback";
+var MCP_AUTH_CALLBACK_MESSAGE_TYPE = "mcp_auth_callback";
+function hasStoredTokens(tokensKey) {
+  try {
+    return typeof localStorage !== "undefined" && !!localStorage.getItem(tokensKey);
+  } catch {
+    return false;
+  }
+}
+function runAuthPopup({
+  popup,
+  state,
+  tokensKey,
+  timeoutMs = 5 * 6e4,
+  closePollMs = 1e3,
+  closeGraceMs = 2e4,
+  expectedOrigin = typeof window !== "undefined" ? window.location.origin : ""
+}) {
+  return new Promise((resolve) => {
+    let settled = false;
+    let closeTimer = null;
+    let timeoutTimer = null;
+    let graceTimer = null;
+    let broadcastChannel = null;
+    const cleanup = () => {
+      if (closeTimer) {
+        clearInterval(closeTimer);
+        closeTimer = null;
+      }
+      if (timeoutTimer) {
+        clearTimeout(timeoutTimer);
+        timeoutTimer = null;
+      }
+      if (graceTimer) {
+        clearTimeout(graceTimer);
+        graceTimer = null;
+      }
+      if (typeof window !== "undefined") {
+        window.removeEventListener("message", messageHandler);
+        window.removeEventListener("storage", storageHandler);
+      }
+      if (broadcastChannel) {
+        try {
+          broadcastChannel.removeEventListener("message", broadcastHandler);
+          broadcastChannel.close();
+        } catch {
+        }
+        broadcastChannel = null;
+      }
+    };
+    const settle = (result) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(result);
+    };
+    const handlePayload = (payload) => {
+      if (!payload || payload.type !== MCP_AUTH_CALLBACK_MESSAGE_TYPE) return;
+      if (payload.state && state && payload.state !== state) return;
+      if (payload.success) {
+        settle({ kind: "success" });
+      } else {
+        settle({
+          kind: "error",
+          error: payload.error ?? "Authentication failed in callback."
+        });
+      }
+    };
+    const messageHandler = (event) => {
+      if (expectedOrigin && event.origin !== expectedOrigin) return;
+      handlePayload(event.data);
+    };
+    const broadcastHandler = (event) => {
+      handlePayload(event.data);
+    };
+    const storageHandler = (event) => {
+      if (event.key !== tokensKey) return;
+      if (event.newValue) settle({ kind: "success" });
+    };
+    if (typeof window !== "undefined") {
+      window.addEventListener("message", messageHandler);
+      window.addEventListener("storage", storageHandler);
+    }
+    if (typeof BroadcastChannel !== "undefined") {
+      try {
+        broadcastChannel = new BroadcastChannel(MCP_AUTH_BROADCAST_CHANNEL);
+        broadcastChannel.addEventListener("message", broadcastHandler);
+      } catch {
+        broadcastChannel = null;
+      }
+    }
+    if (popup) {
+      closeTimer = setInterval(() => {
+        if (settled) return;
+        let closed = false;
+        try {
+          closed = popup.closed;
+        } catch {
+          closed = false;
+        }
+        if (!closed) return;
+        if (closeTimer) {
+          clearInterval(closeTimer);
+          closeTimer = null;
+        }
+        if (hasStoredTokens(tokensKey)) {
+          settle({ kind: "success" });
+          return;
+        }
+        graceTimer = setTimeout(() => {
+          settle(
+            hasStoredTokens(tokensKey) ? { kind: "success" } : { kind: "cancelled" }
+          );
+        }, closeGraceMs);
+      }, closePollMs);
+    }
+    timeoutTimer = setTimeout(() => {
+      settle(
+        hasStoredTokens(tokensKey) ? { kind: "success" } : { kind: "timeout" }
+      );
+    }, timeoutMs);
+  });
+}
+
+// src/auth/callback.ts
+var inFlightCallback = null;
+function isMcpAuthPopupWindow() {
+  return typeof window !== "undefined" && window.name.startsWith("mcp_auth_");
+}
+function buildCallbackPayload(success, error, meta) {
+  return {
+    type: MCP_AUTH_CALLBACK_MESSAGE_TYPE,
+    success,
+    ...success ? {} : { error: error ?? "Unknown error" },
+    ...meta.state ? { state: meta.state } : {},
+    ...meta.serverUrlHash ? { serverUrlHash: meta.serverUrlHash } : {}
+  };
+}
+function broadcastCallback(payload) {
+  if (typeof BroadcastChannel === "undefined") return;
+  let channel;
+  try {
+    channel = new BroadcastChannel(MCP_AUTH_BROADCAST_CHANNEL);
+    channel.postMessage(payload);
+  } catch (error) {
+    console.warn("[mcp-callback] Failed to broadcast callback result:", error);
+  } finally {
+    if (channel) {
+      setTimeout(() => {
+        try {
+          channel?.close();
+        } catch {
+        }
+      }, 0);
+    }
+  }
+}
+function renderResult(title, message, error, returnUrl) {
+  if (typeof document === "undefined") return;
+  document.body.innerHTML = "";
+  const container = document.createElement("div");
+  container.style.fontFamily = "sans-serif";
+  container.style.padding = "20px";
+  const heading = document.createElement("h1");
+  heading.textContent = title;
+  container.appendChild(heading);
+  const text = document.createElement("p");
+  text.textContent = message;
+  if (error) {
+    text.style.color = "red";
+    text.style.backgroundColor = "#ffebeb";
+    text.style.border = "1px solid red";
+    text.style.padding = "10px";
+    text.style.borderRadius = "4px";
+  }
+  container.appendChild(text);
+  const close = document.createElement("a");
+  close.href = "#";
+  close.textContent = "Close this window";
+  close.onclick = (event) => {
+    event.preventDefault();
+    window.close();
+    return false;
+  };
+  container.appendChild(close);
+  if (returnUrl) {
+    const separator = document.createTextNode(" or ");
+    const back = document.createElement("a");
+    back.href = returnUrl;
+    back.textContent = "return to the app";
+    container.append(separator, back);
+  }
+  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;
+  if (!key || !serialized) {
+    throw new Error(`Invalid or expired OAuth state "${state}".`);
+  }
+  let value;
+  try {
+    value = JSON.parse(serialized);
+  } catch {
+    localStorage.removeItem(key);
+    throw new Error("Failed to parse stored OAuth state.");
+  }
+  return { key, value };
+}
+function redirectWithError(returnUrl, message) {
+  const url = new URL(returnUrl);
+  url.searchParams.set("auth_error", "oauth_callback_failed");
+  url.searchParams.set("auth_error_description", message);
+  window.location.href = url.toString();
+}
+function signalResult(success, error, storedState, meta) {
+  const payload = buildCallbackPayload(success, error, meta);
+  const returnUrl = storedState?.returnUrl;
+  const popup = storedState?.flowType === "popup" || isMcpAuthPopupWindow();
+  if (storedState?.flowType === "redirect" && returnUrl) {
+    if (success) window.location.href = returnUrl;
+    else redirectWithError(returnUrl, error ?? "Authentication failed.");
+    return;
+  }
+  if (window.opener && !window.opener.closed) {
+    window.opener.postMessage(payload, window.location.origin);
+    window.close();
+    return;
+  }
+  if (popup) {
+    broadcastCallback(payload);
+    renderResult(
+      success ? "Authentication Successful!" : "Authentication Error",
+      success ? "You're authenticated. You can close this window and return to the app." : error ?? "Authentication failed.",
+      !success,
+      returnUrl
+    );
+    try {
+      window.close();
+    } catch {
+    }
+    return;
+  }
+  if (returnUrl) {
+    if (success) window.location.href = returnUrl;
+    else redirectWithError(returnUrl, error ?? "Authentication failed.");
+    return;
+  }
+  if (!success) {
+    renderResult(
+      "Authentication Error",
+      error ?? "Authentication failed.",
+      true
+    );
+    return;
+  }
+  window.location.href = "/";
+}
+function onMcpAuthorization() {
+  if (!inFlightCallback) inFlightCallback = completeAuthorization();
+  return inFlightCallback;
+}
+async function completeAuthorization() {
+  const callbackParams = new URLSearchParams(window.location.search);
+  const state = callbackParams.get("state");
+  let stateKey = null;
+  let storedState = null;
+  let provider = null;
+  try {
+    if (!state) {
+      throw new Error("OAuth callback is missing the state parameter.");
+    }
+    const stored = findStoredState(state);
+    stateKey = stored.key;
+    storedState = stored.value;
+    if (!storedState.expiry || storedState.expiry < Date.now()) {
+      localStorage.removeItem(stateKey);
+      throw new Error(
+        "OAuth state has expired. Please start authentication again."
+      );
+    }
+    if (!storedState.providerOptions) {
+      throw new Error("Stored OAuth state is missing provider options.");
+    }
+    const { serverUrl, ...providerOptions } = storedState.providerOptions;
+    provider = new BrowserOAuthClientProvider(serverUrl, providerOptions);
+    const transport = new StreamableHTTPClientTransport(new URL(serverUrl), {
+      authProvider: provider,
+      fetch: provider.getProxyFetch()
+    });
+    await transport.finishAuth(callbackParams);
+    localStorage.removeItem(stateKey);
+    signalResult(true, void 0, storedState, {
+      state,
+      serverUrlHash: storedState.serverUrlHash
+    });
+  } 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"));
+    signalResult(false, message, storedState, {
+      state,
+      serverUrlHash: storedState?.serverUrlHash
+    });
+  }
+}
+
+// src/auth/flow.ts
+import {
+  auth,
+  UnauthorizedError
+} from "@modelcontextprotocol/client";
+var DEFAULT_AUTH_TIMEOUT_MS = 5 * 6e4;
+function isUnauthorized(err, depth = 0) {
+  if (!err || depth > 5) return false;
+  if (err instanceof UnauthorizedError) return true;
+  if (err instanceof Error) {
+    const code = err.code;
+    if (code === 401) return true;
+    if (err.name === "UnauthorizedError") return true;
+    const message = err.message ?? "";
+    if (message.includes("401") || message.includes("Unauthorized")) {
+      return true;
+    }
+    if (err.cause && isUnauthorized(err.cause, depth + 1)) return true;
+    const data = err.data;
+    if (data?.cause && isUnauthorized(data.cause, depth + 1)) return true;
+  }
+  return false;
+}
+async function completeOAuthFlow(provider, serverUrl, options = {}) {
+  const flowProvider = provider;
+  const timeoutMs = options.timeoutMs ?? DEFAULT_AUTH_TIMEOUT_MS;
+  const fetchFn = options.fetchFn ?? flowProvider.getProxyFetch?.() ?? void 0;
+  if (!flowProvider.hasPendingFlow) {
+    const result = await auth(provider, { serverUrl, fetchFn });
+    if (result === "AUTHORIZED") return;
+    if (result !== "REDIRECT") {
+      throw new Error(`Unexpected OAuth auth() result: ${result}`);
+    }
+  }
+  if (typeof flowProvider.getAuthorizationCode === "function") {
+    const code = await flowProvider.getAuthorizationCode();
+    await auth(provider, {
+      serverUrl,
+      authorizationCode: code,
+      fetchFn
+    });
+    return;
+  }
+  await waitForBrowserAuthComplete(flowProvider, timeoutMs);
+}
+async function waitForBrowserAuthComplete(provider, timeoutMs) {
+  if (typeof window === "undefined") {
+    throw new Error(
+      "OAuth redirect requires a browser environment or a provider with getAuthorizationCode()"
+    );
+  }
+  if (provider.useRedirectFlow) {
+    return;
+  }
+  const tokensKey = provider.getKey?.("tokens");
+  if (!tokensKey) {
+    throw new Error(
+      "Browser OAuth provider must expose getKey() for token storage"
+    );
+  }
+  let state = null;
+  const authUrl = provider.getLastAttemptedAuthUrl?.();
+  if (authUrl) {
+    try {
+      state = new URL(authUrl).searchParams.get("state");
+    } 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");
+  }
+}
+
+// src/index-browser.ts
+import { auth as auth2, UnauthorizedError as UnauthorizedError3 } from "@modelcontextprotocol/client";
+
+// src/transport/http.ts
+import {
+  Client,
+  SdkError,
+  SdkHttpError,
+  StreamableHTTPClientTransport as StreamableHTTPClientTransport2,
+  UnauthorizedError as UnauthorizedError2
+} from "@modelcontextprotocol/client";
+
+// src/utils/json-schema-validator.ts
+import {
+  CfWorkerJsonSchemaValidator
+} from "@modelcontextprotocol/client/validators/cf-worker";
+var DRAFT_04_URI = "http://json-schema.org/draft-04/schema";
+var DRAFT_07_URIS = /* @__PURE__ */ new Set([
+  "http://json-schema.org/draft-07/schema",
+  "https://json-schema.org/draft-07/schema"
+]);
+var DRAFT_2019_09_URIS = /* @__PURE__ */ new Set([
+  "https://json-schema.org/draft/2019-09/schema",
+  "http://json-schema.org/draft/2019-09/schema"
+]);
+var DRAFT_2020_12_URIS = /* @__PURE__ */ new Set([
+  "https://json-schema.org/draft/2020-12/schema",
+  "http://json-schema.org/draft/2020-12/schema"
+]);
+function resolveDraft(schema) {
+  if (!("$schema" in schema) || typeof schema.$schema !== "string") {
+    return "2020-12";
+  }
+  const normalized = schema.$schema.replace(/#$/, "");
+  if (normalized === DRAFT_04_URI) return "4";
+  if (DRAFT_07_URIS.has(normalized)) return "7";
+  if (DRAFT_2019_09_URIS.has(normalized)) return "2019-09";
+  if (DRAFT_2020_12_URIS.has(normalized)) return "2020-12";
+  return void 0;
+}
+var DialectJsonSchemaValidator = class {
+  getValidator(schema) {
+    const draft = resolveDraft(schema);
+    const delegate = draft !== void 0 ? new CfWorkerJsonSchemaValidator({ draft }) : new CfWorkerJsonSchemaValidator();
+    return delegate.getValidator(schema);
+  }
+};
+
+// src/transport/base.ts
+var passthroughResultSchema = {
+  "~standard": {
+    version: 1,
+    vendor: "mcp-use",
+    validate: (value) => ({ value })
+  }
+};
+var BaseConnector = class {
+  client = null;
+  connectionManager = null;
+  toolsCache = null;
+  capabilitiesCache = null;
+  serverInfoCache = null;
+  connected = false;
+  opts;
+  notificationHandlers = [];
+  rootsCache = [];
+  activeProgressHandlers = /* @__PURE__ */ new Set();
+  constructor(opts = {}) {
+    this.opts = opts;
+    if (opts.roots) {
+      this.rootsCache = [...opts.roots];
+    }
+    if (opts.onNotification) {
+      this.notificationHandlers.push(opts.onNotification);
+    }
+  }
+  /**
+   * Track connector initialization event
+   * Should be called by subclasses after successful connection
+   */
+  trackConnectorInit(data) {
+    const connectorType = this.constructor.name;
+    trackConnectorTelemetry({ connectorType, ...data });
+  }
+  /**
+   * Register a handler for server notifications
+   *
+   * @param handler - Function to call when a notification is received
+   *
+   * @example
+   * ```typescript
+   * connector.onNotification((notification) => {
+   *   console.log(`Received: ${notification.method}`, notification.params);
+   * });
+   * ```
+   */
+  onNotification(handler) {
+    this.notificationHandlers.push(handler);
+    if (this.client) {
+      this.setupNotificationHandler();
+    }
+  }
+  /** Forward a normalized notification to every registered consumer. */
+  async forwardNotification(notification) {
+    for (const handler of this.notificationHandlers) {
+      try {
+        await handler(notification);
+      } catch (err) {
+        logger.error("Error in notification handler:", err);
+      }
+    }
+  }
+  /** Handle SDK list-change callbacks identically on v1 and v2 connections. */
+  async handleListChanged(method, error, tools) {
+    if (error) {
+      logger.warn(`[Auto] ${method} refresh failed:`, error);
+      return;
+    }
+    if (method === "notifications/tools/list_changed" && tools) {
+      this.toolsCache = [...tools];
+    }
+    await this.forwardNotification({ method });
+  }
+  /**
+   * Internal: wire notification handlers to the SDK client
+   * Includes automatic handling for list_changed notifications per MCP spec
+   */
+  setupNotificationHandler() {
+    if (!this.client) return;
+    this.client.fallbackNotificationHandler = async (notification) => {
+      switch (notification.method) {
+        case "notifications/tools/list_changed":
+          await this.refreshToolsCache();
+          break;
+        case "notifications/resources/list_changed":
+          await this.onResourcesListChanged();
+          break;
+        case "notifications/prompts/list_changed":
+          await this.onPromptsListChanged();
+          break;
+        default:
+          break;
+      }
+      await this.forwardNotification(notification);
+    };
+    const client = this.client;
+    const handlersMap = client._notificationHandlers;
+    for (const method of [
+      "notifications/progress",
+      "notifications/cancelled"
+    ]) {
+      const originalHandler = handlersMap.get(method);
+      if (originalHandler) {
+        handlersMap.set(method, async (notification) => {
+          await originalHandler(notification);
+          await this.forwardNotification(notification);
+        });
+      }
+    }
+  }
+  /**
+   * Forward v2 MRTR progress whose retry request IDs are not associated with
+   * the original call callback by the current SDK beta.
+   *
+   * ponytail: fallback is enabled only when exactly one progress-aware call is
+   * active; remove it when the upstream SDK propagates handlers to MRTR rounds.
+   */
+  setupRoundProgressForwarding() {
+    if (!this.client) return;
+    const sdkClient = this.client;
+    const original = sdkClient._onnotification.bind(this.client);
+    sdkClient._onnotification = async (message) => {
+      if (message && typeof message === "object" && message.method === "notifications/progress") {
+        this.forwardRoundProgress(message.params);
+      }
+      await original?.(message);
+    };
+  }
+  /** Forward progress parsed from a transport stream to the active call. */
+  forwardRoundProgress(params) {
+    if (this.activeProgressHandlers.size === 1) {
+      const [handler] = this.activeProgressHandlers;
+      handler?.(
+        params
+      );
+    }
+  }
+  /**
+   * Auto-refresh tools cache when server sends tools/list_changed notification
+   */
+  async refreshToolsCache() {
+    if (!this.client) return;
+    try {
+      logger.debug(
+        "[Auto] Refreshing tools cache due to list_changed notification"
+      );
+      const result = await this.client.listTools();
+      this.toolsCache = result.tools ?? [];
+      logger.debug(
+        `[Auto] Refreshed tools cache: ${this.toolsCache.length} tools`
+      );
+    } catch (err) {
+      logger.warn("[Auto] Failed to refresh tools cache:", err);
+    }
+  }
+  /**
+   * Called when server sends resources/list_changed notification
+   * Resources aren't cached by default, but we log for user awareness
+   */
+  async onResourcesListChanged() {
+    logger.debug(
+      "[Auto] Resources list changed - clients should re-fetch if needed"
+    );
+  }
+  /**
+   * Called when server sends prompts/list_changed notification
+   * Prompts aren't cached by default, but we log for user awareness
+   */
+  async onPromptsListChanged() {
+    logger.debug(
+      "[Auto] Prompts list changed - clients should re-fetch if needed"
+    );
+  }
+  /**
+   * Set roots and notify the server.
+   * Roots represent directories or files that the client has access to.
+   *
+   * @param roots - Array of Root objects with `uri` (must start with "file://") and optional `name`
+   *
+   * @deprecated Roots are retained only for v1 compatibility.
+   *
+   * @example
+   * ```typescript
+   * await connector.setRoots([
+   *   { uri: "file:///home/user/project", name: "My Project" },
+   *   { uri: "file:///home/user/data" }
+   * ]);
+   * ```
+   */
+  async setRoots(roots) {
+    this.rootsCache = [...roots];
+    if (this.client) {
+      logger.debug(
+        `Sending roots/list_changed notification with ${roots.length} root(s)`
+      );
+      await this.client.sendRootsListChanged();
+    }
+  }
+  /**
+   * Get the current roots.
+   */
+  getRoots() {
+    return [...this.rootsCache];
+  }
+  /**
+   * Internal: set up roots/list request handler.
+   * Must be registered after Client construction and before connect() so the
+   * handler is available during initialize / reverse RPC for the full session.
+   */
+  setupRootsHandler() {
+    if (!this.client) return;
+    this.client.setRequestHandler("roots/list", async () => {
+      logger.debug(
+        `Server requested roots list, returning ${this.rootsCache.length} root(s)`
+      );
+      return { roots: this.rootsCache };
+    });
+  }
+  /**
+   * Internal: set up sampling/createMessage request handler.
+   * Must be registered after Client construction and before connect().
+   */
+  setupSamplingHandler() {
+    if (!this.client) {
+      logger.debug("setupSamplingHandler: No client available");
+      return;
+    }
+    const samplingCallback = this.opts.onSampling;
+    if (!samplingCallback) {
+      logger.debug("setupSamplingHandler: No sampling callback provided");
+      return;
+    }
+    logger.debug("setupSamplingHandler: Setting up sampling request handler");
+    this.client.setRequestHandler("sampling/createMessage", async (request) => {
+      logger.debug("Server requested sampling, forwarding to callback");
+      return await samplingCallback(request.params);
+    });
+    logger.debug(
+      "setupSamplingHandler: Sampling handler registered successfully"
+    );
+  }
+  /**
+   * Internal: set up elicitation/create request handler.
+   * Must be registered after Client construction and before connect().
+   */
+  setupElicitationHandler() {
+    if (!this.client) {
+      logger.debug("setupElicitationHandler: No client available");
+      return;
+    }
+    const elicitationCallback = this.opts.onElicitation;
+    if (!elicitationCallback) {
+      logger.debug("setupElicitationHandler: No elicitation callback provided");
+      return;
+    }
+    logger.debug(
+      "setupElicitationHandler: Setting up elicitation request handler"
+    );
+    this.client.setRequestHandler("elicitation/create", async (request) => {
+      logger.debug("Server requested elicitation, forwarding to callback");
+      return await elicitationCallback(
+        request.params
+      );
+    });
+    logger.debug(
+      "setupElicitationHandler: Elicitation handler registered successfully"
+    );
+  }
+  /** Disconnect and release resources. */
+  async disconnect() {
+    if (!this.connected) {
+      logger.debug("Not connected to MCP implementation");
+      return;
+    }
+    logger.debug("Disconnecting from MCP implementation");
+    await this.cleanupResources();
+    this.connected = false;
+    logger.debug("Disconnected from MCP implementation");
+  }
+  /** Check if the client is connected */
+  get isClientConnected() {
+    return this.client != null;
+  }
+  /**
+   * Initialise the MCP session **after** `connect()` has succeeded.
+   *
+   * 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.
+   */
+  async initialize(defaultRequestOptions = this.opts.defaultRequestOptions ?? {}) {
+    if (!this.client) {
+      throw new Error("MCP client is not connected");
+    }
+    logger.debug("Caching server capabilities & tools");
+    const capabilities = this.client.getServerCapabilities();
+    this.capabilitiesCache = capabilities || null;
+    const serverInfo = this.client.getServerVersion();
+    this.serverInfoCache = serverInfo ? {
+      name: serverInfo.name,
+      version: serverInfo.version,
+      title: serverInfo.title,
+      description: serverInfo.description,
+      websiteUrl: serverInfo.websiteUrl,
+      icons: serverInfo.icons
+    } : null;
+    try {
+      const listToolsRes = await this.client.listTools(
+        void 0,
+        defaultRequestOptions
+      );
+      this.toolsCache = listToolsRes.tools ?? [];
+      logger.debug(`Fetched ${this.toolsCache.length} tools from server`);
+    } catch (err) {
+      const error = err;
+      if (error.code === -32601) {
+        logger.debug("Server does not implement tools/list, assuming no tools");
+      } else {
+        logger.debug("Failed to list tools, assuming empty:", error.message);
+      }
+      this.toolsCache = [];
+    }
+    logger.debug("Server capabilities:", capabilities);
+    logger.debug("Server info:", serverInfo);
+    return capabilities;
+  }
+  /** Lazily expose the cached tools list. */
+  get tools() {
+    if (!this.toolsCache) {
+      throw new Error("MCP client is not initialized; call initialize() first");
+    }
+    return this.toolsCache;
+  }
+  /** Expose cached server capabilities. */
+  get serverCapabilities() {
+    return this.capabilitiesCache || {};
+  }
+  /** Expose cached server info. */
+  get serverInfo() {
+    return this.serverInfoCache;
+  }
+  /** Instructions supplied by the connected server, if any. */
+  get instructions() {
+    return this.client?.getInstructions?.();
+  }
+  /**
+   * The negotiated protocol era for the active connection.
+   * - `"legacy"` — 2025-era server, sessionful `initialize` handshake.
+   * - `"modern"` — 2026-era server, stateless per-request.
+   * `undefined` before the connection has negotiated.
+   */
+  get protocolEra() {
+    return this.client?.getProtocolEra?.();
+  }
+  /** The protocol version string negotiated for the active connection. */
+  get negotiatedProtocolVersion() {
+    return this.client?.getNegotiatedProtocolVersion?.();
+  }
+  /** Call a tool on the server. */
+  async callTool(name, args, options) {
+    if (!this.client) {
+      throw new Error("MCP client is not connected");
+    }
+    const enhancedOptions = options ? { ...options } : void 0;
+    if (enhancedOptions?.resetTimeoutOnProgress && !enhancedOptions.onprogress) {
+      enhancedOptions.onprogress = () => {
+      };
+      logger.debug(
+        `[BaseConnector] Added onprogress callback for tool '${name}' to enable progressToken`
+      );
+    }
+    logger.debug(`Calling tool '${name}' with args`, args);
+    const progressHandler = enhancedOptions?.onprogress;
+    if (progressHandler) this.activeProgressHandlers.add(progressHandler);
+    try {
+      const res = await this.client.callTool(
+        { name, arguments: args },
+        enhancedOptions
+      );
+      logger.debug(`Tool '${name}' returned`, res);
+      return res;
+    } finally {
+      if (progressHandler) this.activeProgressHandlers.delete(progressHandler);
+    }
+  }
+  /**
+   * List all available tools from the MCP server.
+   * This method fetches fresh tools from the server, unlike the `tools` getter which returns cached tools.
+   *
+   * @param options - Optional request options
+   * @returns Array of available tools
+   */
+  async listTools(options) {
+    if (!this.client) {
+      throw new Error("MCP client is not connected");
+    }
+    logger.debug("[listTools] Fetching fresh tools from server...");
+    const result = await this.client.listTools(void 0, options);
+    const tools = result.tools ? [...result.tools] : [];
+    logger.debug(
+      `[listTools] Returned ${tools.length} tools:`,
+      tools.map((t) => t.name)
+    );
+    return tools;
+  }
+  /**
+   * List resources from the server with optional pagination
+   *
+   * @param cursor - Optional cursor for pagination
+   * @param options - Request options
+   * @returns Resource list with optional nextCursor for pagination
+   */
+  async listResources(cursor, options) {
+    if (!this.client) {
+      throw new Error("MCP client is not connected");
+    }
+    logger.debug("Listing resources", cursor ? `with cursor: ${cursor}` : "");
+    return await this.client.listResources({ cursor }, options);
+  }
+  /**
+   * List all resources from the server, automatically handling pagination
+   *
+   * @param options - Request options
+   * @returns Complete list of all resources
+   */
+  async listAllResources(options) {
+    if (!this.client) {
+      throw new Error("MCP client is not connected");
+    }
+    if (!this.capabilitiesCache?.resources) {
+      logger.debug("Server does not advertise resources capability, skipping");
+      return { resources: [] };
+    }
+    try {
+      logger.debug("Listing all resources (with auto-pagination)");
+      const allResources = [];
+      let cursor = void 0;
+      do {
+        const result = await this.client.listResources({ cursor }, options);
+        allResources.push(...result.resources || []);
+        cursor = result.nextCursor;
+      } while (cursor);
+      return { resources: allResources };
+    } catch (err) {
+      const error = err;
+      if (error.code === -32601) {
+        logger.debug("Server advertised resources but method not found");
+        return { resources: [] };
+      }
+      throw err;
+    }
+  }
+  /**
+   * List resource templates from the server
+   *
+   * @param options - Request options
+   * @returns List of available resource templates
+   */
+  async listResourceTemplates(options) {
+    if (!this.client) {
+      throw new Error("MCP client is not connected");
+    }
+    logger.debug("Listing resource templates");
+    return await this.client.listResourceTemplates(void 0, options);
+  }
+  /**
+   * Request completion suggestions for a prompt or resource template argument
+   *
+   * @param params - Completion request parameters
+   * @param options - Request options
+   * @returns Completion suggestions from the server
+   */
+  async complete(params, options) {
+    if (!this.client) {
+      throw new Error("MCP client is not connected");
+    }
+    logger.debug("[complete] Requesting completions for:", params.ref);
+    const result = await this.client.complete(params, options);
+    logger.debug(
+      `[complete] Received ${result.completion.values.length} suggestions`
+    );
+    return result;
+  }
+  /** Read a resource by URI. */
+  async readResource(uri, options) {
+    if (!this.client) {
+      throw new Error("MCP client is not connected");
+    }
+    logger.debug(`Reading resource ${uri}`);
+    const res = await this.client.readResource({ uri }, options);
+    return res;
+  }
+  /**
+   * Subscribe to resource updates
+   *
+   * @param uri - URI of the resource to subscribe to
+   * @param options - Request options
+   */
+  async subscribeToResource(uri, options) {
+    if (!this.client) {
+      throw new Error("MCP client is not connected");
+    }
+    logger.debug(`Subscribing to resource: ${uri}`);
+    return await this.client.subscribeResource({ uri }, options);
+  }
+  /**
+   * Unsubscribe from resource updates
+   *
+   * @param uri - URI of the resource to unsubscribe from
+   * @param options - Request options
+   */
+  async unsubscribeFromResource(uri, options) {
+    if (!this.client) {
+      throw new Error("MCP client is not connected");
+    }
+    logger.debug(`Unsubscribing from resource: ${uri}`);
+    return await this.client.unsubscribeResource({ uri }, options);
+  }
+  async listPrompts() {
+    if (!this.client) {
+      throw new Error("MCP client is not connected");
+    }
+    if (!this.capabilitiesCache?.prompts) {
+      logger.debug("Server does not advertise prompts capability, skipping");
+      return { prompts: [] };
+    }
+    try {
+      logger.debug("Listing prompts");
+      return await this.client.listPrompts();
+    } catch (err) {
+      const error = err;
+      if (error.code === -32601) {
+        logger.debug("Server advertised prompts but method not found");
+        return { prompts: [] };
+      }
+      throw err;
+    }
+  }
+  async getPrompt(name, args) {
+    if (!this.client) {
+      throw new Error("MCP client is not connected");
+    }
+    logger.debug(`Getting prompt ${name}`);
+    return await this.client.getPrompt({ name, arguments: args });
+  }
+  /** Send a raw request through the client. */
+  async request(method, params = null, options) {
+    if (!this.client) {
+      throw new Error("MCP client is not connected");
+    }
+    logger.debug(`Sending raw request '${method}' with params`, params);
+    return await this.client.request(
+      { method, params: params ?? {} },
+      passthroughResultSchema,
+      options
+    );
+  }
+  /**
+   * Helper to tear down the client & connection manager safely.
+   */
+  async cleanupResources() {
+    const issues = [];
+    if (this.client) {
+      try {
+        if (typeof this.client.close === "function") {
+          await this.client.close();
+        }
+      } catch (e) {
+        const msg = `Error closing client: ${e}`;
+        logger.warn(msg);
+        issues.push(msg);
+      } finally {
+        this.client = null;
+      }
+    }
+    if (this.connectionManager) {
+      try {
+        await this.connectionManager.stop();
+      } catch (e) {
+        const msg = `Error stopping connection manager: ${e}`;
+        logger.warn(msg);
+        issues.push(msg);
+      } finally {
+        this.connectionManager = null;
+      }
+    }
+    this.toolsCache = null;
+    if (issues.length) {
+      logger.warn(`Resource cleanup finished with ${issues.length} issue(s)`);
+    }
+  }
+};
+
+// src/transport/http.ts
+function detectUnauthorized(err, depth = 0) {
+  if (!err || depth > 5) return false;
+  if (err instanceof UnauthorizedError2) return true;
+  if (err instanceof SdkHttpError && err.status === 401) return true;
+  if (err instanceof Error) {
+    if (err.cause) {
+      if (detectUnauthorized(err.cause, depth + 1)) return true;
+    }
+    const data = err instanceof SdkError ? err.data : void 0;
+    if (data?.cause && detectUnauthorized(data.cause, depth + 1)) return true;
+  }
+  return false;
+}
+function createMcpProxyFetch(logicalServerUrl, proxyUrl, baseFetch, serverId) {
+  const logical = new URL(logicalServerUrl);
+  const proxy = proxyUrl.replace(/\/$/, "");
+  return async (input, init) => {
+    const request = new Request(input, init);
+    const requestUrl = new URL(request.url);
+    const isMcpTransportRequest = requestUrl.origin === logical.origin && requestUrl.pathname === logical.pathname;
+    if (!isMcpTransportRequest) {
+      return baseFetch(request);
+    }
+    const headers = new Headers(request.headers);
+    headers.set("X-Target-URL", request.url);
+    if (serverId) headers.set("X-Server-Id", serverId);
+    const body = request.method === "GET" || request.method === "HEAD" ? void 0 : await request.clone().arrayBuffer();
+    return baseFetch(
+      new Request(proxy, {
+        method: request.method,
+        headers,
+        body,
+        signal: request.signal,
+        redirect: "manual"
+      })
+    );
+  };
+}
+var HttpConnector = class extends BaseConnector {
+  baseUrl;
+  headers;
+  timeout;
+  customFetch;
+  clientInfo;
+  protocolNegotiation;
+  gatewayUrl;
+  serverId;
+  reconnectionOptions;
+  transportType = null;
+  streamableTransport = null;
+  constructor(baseUrl, opts = {}) {
+    super(opts);
+    const originalUrl = baseUrl.replace(/\/$/, "");
+    this.baseUrl = originalUrl;
+    this.headers = { ...opts.headers ?? {} };
+    this.gatewayUrl = opts.gatewayUrl;
+    this.serverId = opts.serverId;
+    if (opts.authToken) {
+      this.headers.Authorization = `Bearer ${opts.authToken}`;
+    }
+    this.timeout = opts.timeout ?? 1e4;
+    const baseFetch = opts.fetch ?? globalThis.fetch.bind(globalThis);
+    this.customFetch = this.gatewayUrl ? createMcpProxyFetch(
+      originalUrl,
+      this.gatewayUrl,
+      baseFetch,
+      this.serverId
+    ) : opts.fetch;
+    this.clientInfo = opts.clientInfo ?? {
+      name: "http-connector",
+      version: "1.0.0"
+    };
+    this.protocolNegotiation = opts.protocolNegotiation ?? "auto";
+    this.reconnectionOptions = opts.reconnectionOptions;
+  }
+  buildClientOptions() {
+    return {
+      ...this.opts.clientOptions || {},
+      jsonSchemaValidator: this.opts.clientOptions?.jsonSchemaValidator ?? new DialectJsonSchemaValidator(),
+      versionNegotiation: {
+        // Allow a caller-supplied versionNegotiation in clientOptions to win.
+        mode: this.protocolNegotiation,
+        ...this.opts.clientOptions?.versionNegotiation ?? {}
+      },
+      listChanged: {
+        tools: {
+          autoRefresh: true,
+          onChanged: (error, tools) => void this.handleListChanged(
+            "notifications/tools/list_changed",
+            error,
+            tools
+          )
+        },
+        resources: {
+          autoRefresh: false,
+          onChanged: (error) => void this.handleListChanged(
+            "notifications/resources/list_changed",
+            error
+          )
+        },
+        prompts: {
+          autoRefresh: false,
+          onChanged: (error) => void this.handleListChanged(
+            "notifications/prompts/list_changed",
+            error
+          )
+        },
+        ...this.opts.clientOptions?.listChanged ?? {}
+      },
+      capabilities: {
+        ...this.opts.clientOptions?.capabilities || {},
+        roots: { listChanged: true },
+        ...this.opts.onSampling ? { sampling: {} } : {},
+        ...this.opts.onElicitation ? { elicitation: { form: {}, url: {} } } : {}
+      }
+    };
+  }
+  // In v2 HTTP transport errors are thrown as SdkHttpError (subclass of
+  // SdkError) with a numeric `.status` accessor, replacing v1's
+  // StreamableHTTPError (which carried the status on `.code`).
+  unwrapStreamableError(err) {
+    if (err instanceof SdkHttpError) {
+      return err;
+    }
+    if (err instanceof Error && err.cause instanceof SdkHttpError) {
+      return err.cause;
+    }
+    return null;
+  }
+  classifyStreamableHttpFailure(err) {
+    let fallbackReason = "Unknown error";
+    let is401Error = false;
+    let httpStatusCode;
+    const streamableErr = this.unwrapStreamableError(err);
+    if (streamableErr) {
+      const status = streamableErr.status;
+      is401Error = status === 401;
+      httpStatusCode = status;
+      if (status === 400 && streamableErr.message.includes("Missing session ID")) {
+        fallbackReason = "Server requires session ID (FastMCP compatibility)";
+        logger.warn(`\u26A0\uFE0F  ${fallbackReason}`);
+      } else if (status === 404 || status === 405) {
+        fallbackReason = `Server returned ${status} - server likely doesn't support streamable HTTP`;
+        logger.debug(fallbackReason);
+      } else {
+        fallbackReason = `Server returned ${status}: ${streamableErr.message}`;
+        logger.debug(fallbackReason);
+      }
+      return { fallbackReason, is401Error, httpStatusCode };
+    }
+    if (err instanceof Error) {
+      const errorStr = err.toString();
+      const errorMsg = err.message || "";
+      is401Error = detectUnauthorized(err) || errorStr.includes("401") || errorMsg.includes("Unauthorized");
+      if (errorStr.includes("Missing session ID") || errorStr.includes("Bad Request: Missing session ID") || errorMsg.includes("FastMCP session ID error")) {
+        fallbackReason = "Server requires session ID (FastMCP compatibility)";
+        logger.warn(`\u26A0\uFE0F  ${fallbackReason}`);
+      } else if (errorStr.includes("405 Method Not Allowed") || errorStr.includes("404 Not Found")) {
+        fallbackReason = "Server doesn't support streamable HTTP (405/404)";
+        logger.debug(fallbackReason);
+      } else {
+        fallbackReason = `Streamable HTTP failed: ${err.message}`;
+        logger.debug(fallbackReason);
+      }
+    }
+    return { fallbackReason, is401Error, httpStatusCode };
+  }
+  /** Establish connection to the MCP implementation via streamable HTTP. */
+  async connect() {
+    if (this.connected) {
+      logger.debug("Already connected to MCP implementation");
+      return;
+    }
+    const baseUrl = this.baseUrl;
+    logger.debug(`Connecting to MCP implementation via HTTP: ${baseUrl}`);
+    try {
+      await this.connectWithStreamableHttp(baseUrl);
+      logger.debug("\u2705 Successfully connected via streamable HTTP");
+    } catch (err) {
+      logger.debug("Streamable HTTP connect failed", err);
+      const { fallbackReason, is401Error, httpStatusCode } = this.classifyStreamableHttpFailure(err);
+      await this.cleanupResources();
+      if (is401Error) {
+        logger.info("Authentication required");
+        const authError = new Error("Authentication required");
+        authError.code = 401;
+        throw authError;
+      }
+      const finalError = new Error(
+        `Could not connect via streamable HTTP: ${fallbackReason}`
+      );
+      if (httpStatusCode !== void 0) {
+        Object.defineProperty(finalError, "code", {
+          value: httpStatusCode,
+          writable: false,
+          enumerable: true,
+          configurable: true
+        });
+      }
+      throw finalError;
+    }
+  }
+  /**
+   * Tee an SSE response so v2 MRTR progress can be correlated even when the
+   * upstream SDK does not carry the original callback to retry request IDs.
+   */
+  observeSseProgress(response) {
+    if (!response.body || !response.headers.get("content-type")?.includes("text/event-stream")) {
+      return response;
+    }
+    const [body, observed] = response.body.tee();
+    void (async () => {
+      const reader = observed.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+      try {
+        while (true) {
+          const { done, value } = await reader.read();
+          if (done) break;
+          buffer += decoder.decode(value, { stream: true });
+          const events = buffer.split(/\r?\n\r?\n/);
+          buffer = events.pop() ?? "";
+          for (const event of events) {
+            for (const line of event.split(/\r?\n/)) {
+              if (!line.startsWith("data:")) continue;
+              try {
+                const message = JSON.parse(line.slice(5).trim());
+                if (message.method === "notifications/progress") {
+                  this.forwardRoundProgress(message.params);
+                }
+              } catch {
+              }
+            }
+          }
+        }
+      } catch (error) {
+        if (!(error instanceof DOMException && error.name === "AbortError")) {
+          logger.debug("Progress observer stream ended:", error);
+        }
+      } finally {
+        reader.releaseLock();
+      }
+    })();
+    return new Response(body, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers
+    });
+  }
+  async connectWithStreamableHttp(baseUrl) {
+    try {
+      logger.debug("[HttpConnector] Connecting with Streamable HTTP", {
+        baseUrl,
+        originalUrl: this.baseUrl,
+        gatewayUrl: this.gatewayUrl || "none",
+        authProviderUrl: this.opts.authProvider && "serverUrl" in this.opts.authProvider && typeof this.opts.authProvider.serverUrl === "string" ? this.opts.authProvider.serverUrl : "none",
+        headers: this.headers
+      });
+      let markPushStreamReady;
+      const pushStreamReady = new Promise((resolve) => {
+        markPushStreamReady = resolve;
+      });
+      const baseFetch = this.customFetch ?? globalThis.fetch.bind(globalThis);
+      const observedFetch = async (input, init) => {
+        const response = await baseFetch(input, init);
+        const method = init?.method ?? (input instanceof Request ? input.method : "GET");
+        const requestHeaders = new Headers(
+          input instanceof Request ? input.headers : void 0
+        );
+        new Headers(init?.headers).forEach((value, key) => {
+          requestHeaders.set(key, value);
+        });
+        if (method.toUpperCase() === "GET" && response.ok && response.headers.get("content-type")?.includes("text/event-stream")) {
+          markPushStreamReady?.();
+        }
+        return requestHeaders.get("mcp-method") === "subscriptions/listen" ? response : this.observeSseProgress(response);
+      };
+      const streamableTransport = new StreamableHTTPClientTransport2(
+        new URL(baseUrl),
+        {
+          authProvider: this.opts.authProvider,
+          // ← Pass OAuth provider to SDK
+          fetch: observedFetch,
+          requestInit: {
+            headers: this.headers
+          },
+          reconnectionOptions: {
+            maxReconnectionDelay: 3e4,
+            initialReconnectionDelay: 1e3,
+            reconnectionDelayGrowFactor: 1.5,
+            maxRetries: 2,
+            ...this.reconnectionOptions
+          }
+          // Don't pass sessionId - let the SDK generate it automatically during connect()
+        }
+      );
+      let transport = streamableTransport;
+      if (this.opts.wrapTransport) {
+        const serverId = this.baseUrl;
+        transport = this.opts.wrapTransport(
+          transport,
+          serverId
+        );
+      }
+      const clientOptions = this.buildClientOptions();
+      logger.debug(
+        `Creating Client with capabilities:`,
+        JSON.stringify(clientOptions.capabilities, null, 2)
+      );
+      this.client = new Client(this.clientInfo, clientOptions);
+      this.setupRootsHandler();
+      this.setupSamplingHandler();
+      this.setupElicitationHandler();
+      logger.debug(
+        "Roots/sampling/elicitation handlers registered before connect"
+      );
+      try {
+        let connectTimeout;
+        await Promise.race([
+          this.client.connect(transport),
+          new Promise((_, reject) => {
+            connectTimeout = setTimeout(
+              () => reject(
+                new Error(`MCP connection timed out after ${this.timeout}ms`)
+              ),
+              this.timeout
+            );
+          })
+        ]).finally(() => {
+          if (connectTimeout !== void 0) clearTimeout(connectTimeout);
+        });
+        if ((this.client.getProtocolEra?.() ?? "legacy") === "legacy" && streamableTransport.sessionId) {
+          let readinessTimeout;
+          const attached = await Promise.race([
+            pushStreamReady.then(() => true),
+            new Promise(
+              (resolve) => readinessTimeout = setTimeout(
+                () => resolve(false),
+                Math.min(this.timeout, 5e3)
+              )
+            )
+          ]);
+          if (readinessTimeout) clearTimeout(readinessTimeout);
+          if (!attached) {
+            logger.warn(
+              "Legacy server push stream did not attach before connect completed"
+            );
+          }
+        }
+        const sessionId2 = streamableTransport.sessionId;
+        if (sessionId2) {
+          logger.debug(`Session ID obtained: ${sessionId2}`);
+        }
+      } catch (connectErr) {
+        if (connectErr instanceof Error) {
+          const errMsg = connectErr.message || connectErr.toString();
+          if (errMsg.includes("Missing session ID") || errMsg.includes("Bad Request: Missing session ID") || errMsg.includes("Mcp-Session-Id header is required")) {
+            const wrappedError = new Error(
+              `Session ID error: ${errMsg}. The SDK should automatically extract session ID from initialize response.`
+            );
+            wrappedError.cause = connectErr;
+            throw wrappedError;
+          }
+        }
+        throw connectErr;
+      }
+      this.streamableTransport = streamableTransport;
+      this.connectionManager = {
+        stop: async () => {
+          if (this.streamableTransport) {
+            try {
+              await this.streamableTransport.close();
+            } catch (e) {
+              logger.warn(`Error closing Streamable HTTP transport: ${e}`);
+            } finally {
+              this.streamableTransport = null;
+            }
+          }
+        }
+      };
+      this.connected = true;
+      this.transportType = "streamable-http";
+      this.setupNotificationHandler();
+      logger.debug(
+        `Successfully connected to MCP implementation via streamable HTTP: ${baseUrl}`
+      );
+      this.trackConnectorInit({
+        serverUrl: this.baseUrl,
+        publicIdentifier: `${this.baseUrl} (streamable-http)`
+      });
+    } catch (err) {
+      await this.cleanupResources();
+      throw err;
+    }
+  }
+  get publicIdentifier() {
+    return {
+      type: "http",
+      url: this.baseUrl,
+      transport: this.transportType || "unknown",
+      protocolEra: this.protocolEra ?? "unknown"
+    };
+  }
+  /** Get the active transport type (`streamable-http` once connected). */
+  getTransportType() {
+    return this.transportType;
+  }
+  // Send the streamable-HTTP DELETE *before* super.cleanupResources() invokes
+  // client.close(). The SDK's transport.close() aborts the shared abort
+  // controller, and terminateSession()'s DELETE fetch reuses that signal —
+  // running it after close() rejects immediately with AbortError.
+  async cleanupResources() {
+    if (this.streamableTransport && this.protocolEra !== "modern") {
+      let terminationTimeout;
+      try {
+        const terminated = await Promise.race([
+          this.streamableTransport.terminateSession().then(() => true),
+          new Promise(
+            (resolve) => terminationTimeout = setTimeout(
+              () => resolve(false),
+              Math.min(this.timeout, 5e3)
+            )
+          )
+        ]);
+        if (!terminated) {
+          logger.debug(
+            "Timed out terminating legacy HTTP session; closing transport"
+          );
+        }
+      } catch (e) {
+        logger.debug(`Error terminating Streamable HTTP session: ${e}`);
+      } finally {
+        if (terminationTimeout) clearTimeout(terminationTimeout);
+      }
+    }
+    await super.cleanupResources();
+  }
+};
+
+// src/core/config.ts
+function resolveCallbacks(perServer, globalDefaults) {
+  const pickSampling = perServer?.onSampling ?? globalDefaults?.onSampling;
+  const pickElicitation = perServer?.onElicitation ?? globalDefaults?.onElicitation;
+  const pickNotification = perServer?.onNotification ?? globalDefaults?.onNotification;
+  return {
+    onSampling: pickSampling,
+    onElicitation: pickElicitation,
+    onNotification: pickNotification
+  };
+}
+function shouldAutoProvisionOAuth(serverConfig) {
+  if (!("url" in serverConfig) || typeof serverConfig.url !== "string") {
+    return false;
+  }
+  if (serverConfig.authProvider) return false;
+  if (serverConfig.authToken) return false;
+  if (serverConfig.oauth === false) return false;
+  const headers = serverConfig.headers;
+  if (headers) {
+    for (const key of Object.keys(headers)) {
+      if (key.toLowerCase() === "authorization") return false;
+    }
+  }
+  return true;
+}
+function getDefaultClientInfo() {
+  return {
+    name: "mcp-use",
+    title: "mcp-use",
+    version: getPackageVersion(),
+    description: "mcp-use is a complete TypeScript framework for building and using MCP",
+    icons: [
+      {
+        src: "https://mcp-use.com/logo.png"
+      }
+    ],
+    websiteUrl: "https://mcp-use.com"
+  };
+}
+function normalizeClientInfo(input) {
+  const fallback = getDefaultClientInfo();
+  if (!input || typeof input !== "object") return fallback;
+  const ci = input;
+  if (!ci.name || !ci.version) return fallback;
+  return { ...fallback, ...ci };
+}
+function resolveClientOptions(clientOptions) {
+  const capabilities = clientOptions?.capabilities;
+  if (!capabilities || capabilities.views !== true) return clientOptions;
+  const { views: _views, ...capsWithoutViews } = capabilities;
+  const extensions = capsWithoutViews.extensions && typeof capsWithoutViews.extensions === "object" && !Array.isArray(capsWithoutViews.extensions) ? { ...capsWithoutViews.extensions } : {};
+  return {
+    ...clientOptions,
+    capabilities: {
+      ...capsWithoutViews,
+      extensions: {
+        ...extensions,
+        "io.modelcontextprotocol/ui": {
+          mimeTypes: ["text/html;profile=mcp-app"]
+        }
+      }
+    }
+  };
+}
+function createConnectorFromConfig(serverConfig, connectorOptions) {
+  const clientInfo = normalizeClientInfo(serverConfig.clientInfo);
+  if ("command" in serverConfig && "args" in serverConfig) {
+    throw new Error(
+      "Stdio connector is not supported in this environment. Stdio connections require Node.js and are only available in the Node.js MCPClient."
+    );
+  }
+  if ("url" in serverConfig) {
+    return new HttpConnector(serverConfig.url, {
+      headers: serverConfig.headers,
+      fetch: serverConfig.fetch,
+      authToken: serverConfig.authToken,
+      authProvider: serverConfig.authProvider,
+      protocolNegotiation: serverConfig.protocolNegotiation,
+      timeout: serverConfig.timeout,
+      roots: serverConfig.roots,
+      clientOptions: resolveClientOptions(serverConfig.clientOptions),
+      defaultRequestOptions: serverConfig.defaultRequestOptions,
+      clientInfo,
+      ...connectorOptions
+    });
+  }
+  throw new Error("Cannot determine connector type from config");
+}
+
+// src/core/session.ts
+var MCPConnection = class {
+  /**
+   * The underlying connector managing the transport layer.
+   * This is the Stdio, HTTP, or WebSocket connector handling actual communication.
+   */
+  connector;
+  /**
+   * Whether to automatically connect when initializing.
+   * @internal
+   */
+  autoConnect;
+  /**
+   * Creates a new MCP session.
+   *
+   * @param connector - The connector to use for communication (Stdio, HTTP, WebSocket)
+   * @param autoConnect - Whether to automatically connect during initialization (default: true)
+   *
+   * @example
+   * ```typescript
+   * const connector = new HttpConnector({ url: 'http://localhost:3000/mcp' });
+   * const session = new MCPSession(connector);
+   * await session.initialize(); // Auto-connects and initializes
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Manual connection control
+   * const session = new MCPSession(connector, false);
+   * await session.connect();
+   * await session.initialize();
+   * ```
+   */
+  constructor(connector, autoConnect = true) {
+    this.connector = connector;
+    this.autoConnect = autoConnect;
+  }
+  /**
+   * Establishes the connection to the MCP server.
+   *
+   * This method starts the underlying transport (spawns process for Stdio,
+   * opens WebSocket, etc.) but does not perform the MCP initialization
+   * handshake. Call {@link initialize} after connecting.
+   *
+   * @returns Promise that resolves when connected
+   *
+   * @example
+   * ```typescript
+   * await session.connect();
+   * await session.initialize();
+   * ```
+   *
+   * @see {@link initialize} for performing the MCP handshake
+   * @see {@link disconnect} for closing the connection
+   */
+  async connect() {
+    await this.connector.connect();
+  }
+  /**
+   * Closes the connection to the MCP server.
+   *
+   * This method gracefully shuts down the transport and cleans up resources.
+   * After disconnecting, the session cannot be used until reconnected.
+   *
+   * @returns Promise that resolves when disconnected
+   *
+   * @example
+   * ```typescript
+   * await session.disconnect();
+   * console.log('Session closed');
+   * ```
+   *
+   * @see {@link connect} for establishing connections
+   */
+  async disconnect() {
+    await this.connector.disconnect();
+  }
+  /**
+   * Initializes the MCP session with the server.
+   *
+   * This method performs the MCP initialization handshake, exchanging
+   * capabilities and metadata with the server. If `autoConnect` is true
+   * and the session is not yet connected, it will connect first.
+   *
+   * After initialization, you can list and call tools, read resources, etc.
+   *
+   * @returns Promise that resolves when initialized
+   *
+   * @example
+   * ```typescript
+   * const session = await client.createSession('my-server', false);
+   * await session.connect();
+   * await session.initialize();
+   * // Now ready to use
+   * const tools = await session.listTools();
+   * ```
+   *
+   * @see {@link connect} for establishing the connection first
+   */
+  async initialize() {
+    if (!this.isConnected && this.autoConnect) {
+      await this.connect();
+    }
+    await this.connector.initialize();
+  }
+  /**
+   * Checks if the session is currently connected to the server.
+   *
+   * @returns True if connected, false otherwise
+   *
+   * @example
+   * ```typescript
+   * if (session.isConnected) {
+   *   const tools = await session.listTools();
+   * }
+   * ```
+   */
+  get isConnected() {
+    return this.connector && this.connector.isClientConnected;
+  }
+  /**
+   * Register an event handler for session events
+   *
+   * @param event - The event type to listen for
+   * @param handler - The handler function to call when the event occurs
+   *
+   * @example
+   * ```typescript
+   * session.on("notification", async (notification) => {
+   *   console.log(`Received: ${notification.method}`, notification.params);
+   *
+   *   if (notification.method === "notifications/tools/list_changed") {
+   *     // Refresh tools list
+   *   }
+   * });
+   * ```
+   */
+  on(event, handler) {
+    if (event === "notification") {
+      this.connector.onNotification(handler);
+    }
+  }
+  /**
+   * Set roots and notify the server.
+   * Roots represent directories or files that the client has access to.
+   *
+   * @param roots - Array of Root objects with `uri` (must start with "file://") and optional `name`
+   *
+   * @deprecated Roots are a v1 compatibility feature and are not part of the
+   * sessionless v2 protocol.
+   *
+   * @example
+   * ```typescript
+   * await session.setRoots([
+   *   { uri: "file:///home/user/project", name: "My Project" },
+   *   { uri: "file:///home/user/data" }
+   * ]);
+   * ```
+   */
+  async setRoots(roots) {
+    return this.connector.setRoots(roots);
+  }
+  /**
+   * Gets the current roots advertised to the server.
+   *
+   * Roots represent directories or files that the client has provided access to.
+   * The server may use this information to scope its operations.
+   *
+   * @returns Array of Root objects
+   *
+   * @example
+   * ```typescript
+   * const roots = session.getRoots();
+   * console.log(`Current roots: ${roots.map(r => r.uri).join(', ')}`);
+   * ```
+   *
+   * @see {@link setRoots} for updating roots
+   */
+  getRoots() {
+    return this.connector.getRoots();
+  }
+  /**
+   * Get the cached list of tools from the server.
+   *
+   * @returns Array of available tools
+   *
+   * @example
+   * ```typescript
+   * const tools = session.tools;
+   * console.log(`Available tools: ${tools.map(t => t.name).join(", ")}`);
+   * ```
+   */
+  get tools() {
+    return this.connector.tools;
+  }
+  /**
+   * List all available tools from the MCP server.
+   * This method fetches fresh tools from the server, unlike the `tools` getter which returns cached tools.
+   *
+   * @param options - Optional request options
+   * @returns Array of available tools
+   *
+   * @example
+   * ```typescript
+   * const tools = await session.listTools();
+   * console.log(`Available tools: ${tools.map(t => t.name).join(", ")}`);
+   * ```
+   */
+  async listTools(options) {
+    return this.connector.listTools(options);
+  }
+  /**
+   * Get the server capabilities advertised during initialization.
+   *
+   * @returns Server capabilities object
+   */
+  get serverCapabilities() {
+    return this.connector.serverCapabilities;
+  }
+  /**
+   * Get the server information (name and version).
+   *
+   * @returns Server info object or null if not available
+   */
+  get serverInfo() {
+    return this.connector.serverInfo;
+  }
+  /**
+   * The negotiated protocol era for this session's connection:
+   * `"legacy"` (2025-era) or `"modern"` (2026-07-28-era).
+   * `undefined` before the connection has negotiated.
+   */
+  get protocolEra() {
+    return this.connector.protocolEra;
+  }
+  /** The negotiated protocol version string for this session's connection. */
+  get negotiatedProtocolVersion() {
+    return this.connector.negotiatedProtocolVersion;
+  }
+  /**
+   * Normalized server metadata for this ready connection.
+   *
+   * @throws {Error} When called before protocol negotiation completes.
+   */
+  get info() {
+    const protocolEra = this.protocolEra;
+    const protocolVersion = this.negotiatedProtocolVersion;
+    const server = this.serverInfo;
+    if (!protocolEra || !protocolVersion || !server) {
+      throw new Error("MCP connection is not initialized");
+    }
+    const capabilities = this.serverCapabilities;
+    const extensions = capabilities.extensions && typeof capabilities.extensions === "object" && !Array.isArray(capabilities.extensions) ? capabilities.extensions : {};
+    return {
+      protocolEra,
+      protocolVersion,
+      server,
+      capabilities,
+      instructions: this.connector.instructions,
+      extensions
+    };
+  }
+  /**
+   * Whether the server advertised a named MCP capability.
+   *
+   * @param capability - A top-level capability name such as `"tools"` or
+   * `"resources"`.
+   */
+  supports(capability) {
+    return capability in this.serverCapabilities;
+  }
+  /**
+   * Call a tool on the server.
+   *
+   * @param name - Name of the tool to call
+   * @param args - Arguments to pass to the tool (defaults to empty object)
+   * @param options - Optional request options (timeout, progress handlers, etc.)
+   * @returns Result from the tool execution
+   *
+   * @example
+   * ```typescript
+   * const result = await session.callTool("add", { a: 5, b: 3 });
+   * console.log(`Result: ${result.content[0].text}`);
+   * ```
+   */
+  async callTool(name, args = {}, options) {
+    return this.connector.callTool(name, args, options);
+  }
+  /**
+   * List resources from the server with optional pagination.
+   *
+   * @param cursor - Optional cursor for pagination
+   * @param options - Request options
+   * @returns Resource list with optional nextCursor for pagination
+   *
+   * @example
+   * ```typescript
+   * const result = await session.listResources();
+   * console.log(`Found ${result.resources.length} resources`);
+   * ```
+   */
+  async listResources(cursor, options) {
+    return this.connector.listResources(cursor, options);
+  }
+  /**
+   * List all resources from the server, automatically handling pagination.
+   *
+   * @param options - Request options
+   * @returns Complete list of all resources
+   *
+   * @example
+   * ```typescript
+   * const result = await session.listAllResources();
+   * console.log(`Total resources: ${result.resources.length}`);
+   * ```
+   */
+  async listAllResources(options) {
+    return this.connector.listAllResources(options);
+  }
+  /**
+   * List resource templates from the server.
+   *
+   * @param options - Request options
+   * @returns List of available resource templates
+   *
+   * @example
+   * ```typescript
+   * const result = await session.listResourceTemplates();
+   * console.log(`Available templates: ${result.resourceTemplates.length}`);
+   * ```
+   */
+  async listResourceTemplates(options) {
+    return this.connector.listResourceTemplates(options);
+  }
+  /**
+   * Request completion suggestions for a prompt or resource template argument.
+   *
+   * @param params - Completion request parameters
+   * @param options - Request options
+   * @returns Completion suggestions from the server
+   *
+   * @example
+   * ```typescript
+   * // Complete a prompt argument
+   * const result = await session.complete({
+   *   ref: { type: "ref/prompt", name: "my-prompt" },
+   *   argument: { name: "language", value: "py" }
+   * });
+   * console.log(result.completion.values); // ["python"]
+   * ```
+   */
+  async complete(params, options) {
+    return this.connector.complete(params, options);
+  }
+  /**
+   * Read a resource by URI.
+   *
+   * @param uri - URI of the resource to read
+   * @param options - Request options
+   * @returns Resource content
+   *
+   * @example
+   * ```typescript
+   * const resource = await session.readResource("file:///path/to/file.txt");
+   * console.log(resource.contents);
+   * ```
+   */
+  async readResource(uri, options) {
+    return this.connector.readResource(uri, options);
+  }
+  /**
+   * Subscribe to resource updates.
+   *
+   * @param uri - URI of the resource to subscribe to
+   * @param options - Request options
+   *
+   * @example
+   * ```typescript
+   * await session.subscribeToResource("file:///path/to/file.txt");
+   * // Now you'll receive notifications when this resource changes
+   * ```
+   */
+  async subscribeToResource(uri, options) {
+    return this.connector.subscribeToResource(uri, options);
+  }
+  /**
+   * Unsubscribe from resource updates.
+   *
+   * @param uri - URI of the resource to unsubscribe from
+   * @param options - Request options
+   *
+   * @example
+   * ```typescript
+   * await session.unsubscribeFromResource("file:///path/to/file.txt");
+   * ```
+   */
+  async unsubscribeFromResource(uri, options) {
+    return this.connector.unsubscribeFromResource(uri, options);
+  }
+  /**
+   * List available prompts from the server.
+   *
+   * @returns List of available prompts
+   *
+   * @example
+   * ```typescript
+   * const result = await session.listPrompts();
+   * console.log(`Available prompts: ${result.prompts.length}`);
+   * ```
+   */
+  async listPrompts() {
+    return this.connector.listPrompts();
+  }
+  /**
+   * Get a specific prompt with arguments.
+   *
+   * @param name - Name of the prompt to get
+   * @param args - Arguments for the prompt
+   * @returns Prompt result
+   *
+   * @example
+   * ```typescript
+   * const prompt = await session.getPrompt("greeting", { name: "Alice" });
+   * console.log(prompt.messages);
+   * ```
+   */
+  async getPrompt(name, args) {
+    return this.connector.getPrompt(name, args);
+  }
+  /**
+   * Send a raw request through the client.
+   *
+   * @param method - MCP method name
+   * @param params - Request parameters
+   * @param options - Request options
+   * @returns Response from the server
+   *
+   * @example
+   * ```typescript
+   * const result = await session.request("custom/method", { key: "value" });
+   * ```
+   */
+  async request(method, params = null, options) {
+    return this.connector.request(method, params, options);
+  }
+};
+
+// src/core/base.ts
+function isOAuthClientProvider(provider) {
+  return !!provider && typeof provider === "object" && "redirectUrl" in provider && "clientMetadata" in provider;
+}
+var BaseMCPClient = class {
+  /**
+   * Internal configuration object containing MCP server definitions.
+   * @protected
+   */
+  config = {};
+  /**
+   * Map of server names to their active sessions.
+   * @protected
+   */
+  sessions = {};
+  /**
+   * List of server names that have active sessions.
+   * This array is kept in sync with the sessions map and can be used
+   * to iterate over active connections.
+   *
+   * @example
+   * ```typescript
+   * console.log(`Active servers: ${client.activeSessions.join(', ')}`);
+   * ```
+   */
+  activeSessions = [];
+  /**
+   * Creates a new BaseMCPClient instance.
+   *
+   * @param config - Optional configuration object with MCP server definitions
+   *
+   * @example
+   * ```typescript
+   * const client = new MCPClient({
+   *   mcpServers: {
+   *     'example': {
+   *       command: 'node',
+   *       args: ['server.js']
+   *     }
+   *   }
+   * });
+   * ```
+   */
+  constructor(config) {
+    if (config) {
+      this.config = config;
+    }
+  }
+  /**
+   * Creates a client instance from a configuration dictionary.
+   *
+   * This static factory method must be implemented by concrete subclasses
+   * to provide proper type information and platform-specific initialization.
+   *
+   * @param _cfg - Configuration dictionary
+   * @returns Client instance
+   * @throws {Error} If called on the base class instead of a concrete implementation
+   *
+   * @example
+   * ```typescript
+   * const client = MCPClient.fromDict({
+   *   mcpServers: {
+   *     'my-server': { command: 'node', args: ['server.js'] }
+   *   }
+   * });
+   * ```
+   */
+  static fromDict(_cfg) {
+    throw new Error("fromDict must be implemented by concrete class");
+  }
+  /**
+   * Adds a new MCP server configuration to the client.
+   *
+   * This method adds or updates a server configuration dynamically without
+   * needing to restart the client. The server can then be used to create
+   * new sessions.
+   *
+   * @param name - Unique name for the server
+   * @param serverConfig - Server configuration object (connector type, command, args, etc.)
+   *
+   * @example
+   * ```typescript
+   * client.addServer('new-server', {
+   *   command: 'python',
+   *   args: ['server.py']
+   * });
+   *
+   * // Now you can create a session
+   * const session = await client.createSession('new-server');
+   * ```
+   *
+   * @see {@link removeServer} for removing servers
+   * @see {@link getServerConfig} for retrieving configurations
+   */
+  addServer(name, serverConfig) {
+    this.config.mcpServers = this.config.mcpServers || {};
+    this.config.mcpServers[name] = serverConfig;
+    trackClientAddServer(name, serverConfig);
+  }
+  /**
+   * Removes an MCP server configuration from the client.
+   *
+   * This method removes a server configuration and cleans up any active
+   * sessions associated with that server. If there's an active session,
+   * it will be removed from the active sessions list.
+   *
+   * @param name - Name of the server to remove
+   *
+   * @example
+   * ```typescript
+   * // Remove a server configuration
+   * await client.removeServer('old-server');
+   *
+   * // The server name will no longer appear in getServerNames()
+   * console.log(client.getServerNames()); // 'old-server' is gone
+   * ```
+   *
+   * @see {@link addServer} for adding servers
+   * @see {@link closeSession} for properly closing sessions before removal
+   */
+  async removeServer(name) {
+    if (!this.config.mcpServers?.[name]) return;
+    await this.closeSession(name);
+    delete this.config.mcpServers[name];
+    trackClientRemoveServer(name);
+  }
+  /**
+   * Gets the names of all configured MCP servers.
+   *
+   * @returns Array of server names defined in the configuration
+   *
+   * @example
+   * ```typescript
+   * const serverNames = client.getServerNames();
+   * console.log(`Configured servers: ${serverNames.join(', ')}`);
+   *
+   * // Create sessions for all servers
+   * for (const name of serverNames) {
+   *   await client.createSession(name);
+   * }
+   * ```
+   *
+   * @see {@link activeSessions} for servers with active sessions
+   */
+  getServerNames() {
+    return Object.keys(this.config.mcpServers ?? {});
+  }
+  /**
+   * Gets the configuration for a specific MCP server.
+   *
+   * @param name - Name of the server
+   * @returns Server configuration object, or undefined if not found
+   *
+   * @example
+   * ```typescript
+   * const config = client.getServerConfig('my-server');
+   * if (config) {
+   *   console.log(`Command: ${config.command}`);
+   *   console.log(`Args: ${config.args.join(' ')}`);
+   * }
+   * ```
+   *
+   * @see {@link getConfig} for retrieving the entire configuration
+   */
+  getServerConfig(name) {
+    return this.config.mcpServers?.[name];
+  }
+  /**
+   * Gets the complete client configuration.
+   *
+   * @returns Complete configuration object including all server definitions
+   *
+   * @example
+   * ```typescript
+   * const config = client.getConfig();
+   * console.log(`Total servers: ${Object.keys(config.mcpServers).length}`);
+   * ```
+   *
+   * @see {@link getServerConfig} for retrieving individual server configurations
+   */
+  getConfig() {
+    return this.config ?? {};
+  }
+  /**
+   * Creates a new session for connecting to an MCP server.
+   *
+   * @deprecated Use {@link connect}; modern MCP servers are sessionless.
+   *
+   * This method initializes a connection to the specified server using the
+   * configuration provided during client construction. Sessions manage the
+   * lifecycle of connections and provide methods for calling tools, listing
+   * resources, and more.
+   *
+   * If a session already exists for the server, it will be replaced with a new one.
+   *
+   * @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
+   *
+   * @example
+   * ```typescript
+   * // Create and initialize a session
+   * const session = await client.createSession('my-server');
+   * const tools = await session.listTools();
+   *
+   * // Create without auto-initialization
+   * const session = await client.createSession('my-server', false);
+   * await session.connect();
+   * await session.initialize();
+   * ```
+   *
+   * @see {@link MCPSession} for session management methods
+   * @see {@link closeSession} for closing sessions
+   * @see {@link getSession} for retrieving existing sessions
+   */
+  async createSession(serverName, autoInitialize = true) {
+    const servers = this.config.mcpServers ?? {};
+    if (Object.keys(servers).length === 0) {
+      logger.warn("No MCP servers defined in config");
+    }
+    if (!servers[serverName]) {
+      throw new Error(`Server '${serverName}' not found in config`);
+    }
+    let serverConfig = { ...servers[serverName] };
+    let oauthProvider;
+    if (shouldAutoProvisionOAuth(serverConfig)) {
+      const oauthOptions = serverConfig.oauth === false ? void 0 : serverConfig.oauth ?? {};
+      oauthProvider = await this.createDefaultOAuthProvider(
+        serverConfig.url,
+        oauthOptions
+      );
+      serverConfig = {
+        ...serverConfig,
+        authProvider: oauthProvider
+      };
+    } else if ("authProvider" in serverConfig && serverConfig.authProvider && isOAuthClientProvider(serverConfig.authProvider)) {
+      oauthProvider = serverConfig.authProvider;
+    }
+    const openSession = async () => {
+      const connector = await Promise.resolve(
+        this.createConnectorFromConfig(serverConfig)
+      );
+      const session2 = new MCPConnection(connector);
+      if (autoInitialize) {
+        await session2.initialize();
+      }
+      return session2;
+    };
+    let session;
+    try {
+      session = await openSession();
+    } catch (err) {
+      const httpConfig = serverConfig;
+      if (!autoInitialize || !oauthProvider || !("url" in httpConfig) || !isUnauthorized(err)) {
+        throw err;
+      }
+      if (oauthProvider.preventAutoAuth) {
+        throw err;
+      }
+      logger.info(
+        `[MCPClient] Unauthorized connecting to '${serverName}'; completing OAuth\u2026`
+      );
+      await completeOAuthFlow(oauthProvider, httpConfig.url);
+      session = await openSession();
+    }
+    this.sessions[serverName] = session;
+    if (!this.activeSessions.includes(serverName)) {
+      this.activeSessions.push(serverName);
+    }
+    return session;
+  }
+  /**
+   * Connect to a configured MCP server and return a ready, protocol-neutral
+   * connection.
+   *
+   * The returned connection represents either a legacy sessionful server or a
+   * modern sessionless server uniformly. Inspect {@link MCPConnection.info} for
+   * the negotiated protocol version and normalized server metadata.
+   *
+   * @param serverName - The configured server name.
+   */
+  async connect(serverName) {
+    return this.createSession(serverName);
+  }
+  /**
+   * Creates sessions for all configured MCP servers.
+   *
+   * This is a convenience method that iterates through all servers in the
+   * configuration and creates a session for each one. Sessions are created
+   * sequentially to avoid overwhelming the system.
+   *
+   * @param autoInitialize - Whether to automatically initialize each session (default: true)
+   * @returns A promise that resolves to a map of server names to sessions
+   *
+   * @example
+   * ```typescript
+   * // Create sessions for all configured servers
+   * const sessions = await client.createAllSessions();
+   * console.log(`Created ${Object.keys(sessions).length} sessions`);
+   *
+   * // List tools from all servers
+   * for (const [name, session] of Object.entries(sessions)) {
+   *   const tools = await session.listTools();
+   *   console.log(`${name}: ${tools.length} tools`);
+   * }
+   * ```
+   *
+   * @see {@link createSession} for creating individual sessions
+   * @see {@link closeAllSessions} for closing all sessions
+   */
+  async createAllSessions(autoInitialize = true) {
+    const servers = this.config.mcpServers ?? {};
+    if (Object.keys(servers).length === 0) {
+      logger.warn("No MCP servers defined in config");
+    }
+    for (const name of Object.keys(servers)) {
+      await this.createSession(name, autoInitialize);
+    }
+    return this.sessions;
+  }
+  /**
+   * Connect to every configured server sequentially.
+   *
+   * Each result uses the same {@link MCPConnection} API regardless of whether
+   * the negotiated protocol is legacy/sessionful or modern/sessionless.
+   */
+  async connectAll() {
+    return this.createAllSessions();
+  }
+  /**
+   * Retrieves an existing session by server name.
+   *
+   * This method returns null if no session exists, making it safe for
+   * checking session existence without throwing errors.
+   *
+   * @param serverName - Name of the server
+   * @returns The session instance or null if not found
+   *
+   * @example
+   * ```typescript
+   * const session = client.getSession('my-server');
+   * if (session) {
+   *   const tools = await session.listTools();
+   * } else {
+   *   console.log('Session not found, creating...');
+   *   await client.createSession('my-server');
+   * }
+   * ```
+   *
+   * @see {@link requireSession} for getting a session that throws if not found
+   * @see {@link createSession} for creating sessions
+   */
+  getSession(serverName) {
+    const session = this.sessions[serverName];
+    if (!session) {
+      return null;
+    }
+    return session;
+  }
+  /**
+   * Retrieves an existing session by server name, throwing if not found.
+   *
+   * This method is useful when you need to ensure a session exists before
+   * proceeding. It throws a descriptive error if the session is not found.
+   *
+   * @param serverName - Name of the server
+   * @returns The session instance
+   * @throws {Error} If the session is not found
+   *
+   * @example
+   * ```typescript
+   * try {
+   *   const session = client.requireSession('my-server');
+   *   const tools = await session.listTools();
+   * } catch (error) {
+   *   console.error('Session not found:', error.message);
+   * }
+   * ```
+   *
+   * @see {@link getSession} for a null-returning alternative
+   * @see {@link createSession} for creating sessions
+   */
+  requireSession(serverName) {
+    const session = this.sessions[serverName];
+    if (!session) {
+      throw new Error(
+        `Session '${serverName}' not found. Available sessions: ${this.activeSessions.join(", ") || "none"}`
+      );
+    }
+    return session;
+  }
+  /**
+   * Gets all active sessions as a map of server names to sessions.
+   *
+   * @returns Map of server names to their active sessions
+   *
+   * @example
+   * ```typescript
+   * const sessions = client.getAllActiveSessions();
+   *
+   * // Iterate over all active sessions
+   * for (const [name, session] of Object.entries(sessions)) {
+   *   console.log(`Server: ${name}`);
+   *   const tools = await session.listTools();
+   *   console.log(`  Tools: ${tools.length}`);
+   * }
+   * ```
+   *
+   * @see {@link activeSessions} for just the list of server names
+   * @see {@link getSession} for retrieving individual sessions
+   */
+  getAllActiveSessions() {
+    return Object.fromEntries(
+      this.activeSessions.map((n) => [n, this.sessions[n]])
+    );
+  }
+  /**
+   * Closes a session and cleans up its resources.
+   *
+   * This method gracefully disconnects from the server and removes the
+   * session from the active sessions list. It's safe to call even if
+   * the session doesn't exist.
+   *
+   * @param serverName - Name of the server whose session should be closed
+   *
+   * @example
+   * ```typescript
+   * // Close a specific session
+   * await client.closeSession('my-server');
+   *
+   * // Verify it's closed
+   * console.log(client.activeSessions.includes('my-server')); // false
+   * ```
+   *
+   * @see {@link closeAllSessions} for closing all sessions at once
+   * @see {@link createSession} for creating new sessions
+   */
+  async closeSession(serverName) {
+    const session = this.sessions[serverName];
+    if (!session) {
+      logger.warn(
+        `No session exists for server ${serverName}, nothing to close`
+      );
+      return;
+    }
+    try {
+      logger.debug(`Closing session for server ${serverName}`);
+      await session.disconnect();
+    } catch (e) {
+      logger.error(`Error closing session for server '${serverName}': ${e}`);
+    } finally {
+      if (this.sessions[serverName] === session) {
+        delete this.sessions[serverName];
+        this.activeSessions = this.activeSessions.filter(
+          (n) => n !== serverName
+        );
+      }
+    }
+  }
+  /**
+   * Closes all active sessions and cleans up their resources.
+   *
+   * This method iterates through all sessions and attempts to close each one
+   * gracefully. If any session fails to close, the error is logged but the
+   * method continues to close remaining sessions.
+   *
+   * This is particularly useful for cleanup on application shutdown.
+   *
+   * @example
+   * ```typescript
+   * // Clean shutdown
+   * try {
+   *   await client.closeAllSessions();
+   *   console.log('All sessions closed successfully');
+   * } catch (error) {
+   *   console.error('Error during cleanup:', error);
+   * }
+   * ```
+   *
+   * @example
+   * ```typescript
+   * // Use in application shutdown handler
+   * process.on('SIGINT', async () => {
+   *   console.log('Shutting down...');
+   *   await client.closeAllSessions();
+   *   process.exit(0);
+   * });
+   * ```
+   *
+   * @see {@link closeSession} for closing individual sessions
+   * @see {@link createAllSessions} for creating sessions
+   */
+  async closeAllSessions() {
+    const serverNames = Object.keys(this.sessions);
+    const errors = [];
+    for (const serverName of serverNames) {
+      try {
+        logger.debug(`Closing session for server ${serverName}`);
+        await this.closeSession(serverName);
+      } catch (e) {
+        const errorMsg = `Failed to close session for server '${serverName}': ${e}`;
+        logger.error(errorMsg);
+        errors.push(errorMsg);
+      }
+    }
+    if (errors.length) {
+      logger.error(
+        `Encountered ${errors.length} errors while closing sessions`
+      );
+    } else {
+      logger.debug("All sessions closed successfully");
+    }
+  }
+  /** Close every active MCP connection. */
+  async close() {
+    await this.closeAllSessions();
+  }
+};
+
+// src/core/browser.ts
+function trackBrowserClientInit(config) {
+  const servers = Object.keys(config.mcpServers ?? {});
+  Tel.getInstance().trackMCPClientInit({
+    codeMode: false,
+    sandbox: false,
+    allCallbacks: false,
+    verify: false,
+    servers,
+    numServers: servers.length,
+    isBrowser: true
+  }).catch(
+    (e) => logger.debug(`Failed to track BrowserMCPClient init: ${e}`)
+  );
+}
+var BrowserMCPClient = class _BrowserMCPClient extends BaseMCPClient {
+  /**
+   * Get the mcp-use package version.
+   * Works in all environments (Node.js, browser, Cloudflare Workers, Deno, etc.)
+   */
+  static getPackageVersion() {
+    return getPackageVersion();
+  }
+  constructor(config) {
+    super(config);
+    trackBrowserClientInit(this.config);
+  }
+  static fromDict(cfg) {
+    return new _BrowserMCPClient(cfg);
+  }
+  async createDefaultOAuthProvider(serverUrl, options = {}) {
+    return createOAuthProvider(serverUrl, options);
+  }
+  /**
+   * Create a connector from server configuration (Browser version)
+   * Supports HTTP connector only
+   */
+  createConnectorFromConfig(serverConfig) {
+    const {
+      url,
+      headers,
+      fetch: configuredFetch,
+      authToken,
+      authProvider,
+      wrapTransport,
+      clientOptions,
+      protocolNegotiation,
+      timeout,
+      gatewayUrl,
+      serverId,
+      reconnectionOptions
+    } = serverConfig;
+    if (!url) {
+      throw new Error("Server URL is required");
+    }
+    const globalDefaults = this.config;
+    const resolved = resolveCallbacks(
+      serverConfig,
+      globalDefaults
+    );
+    const clientInfo = normalizeClientInfo(
+      serverConfig.clientInfo ?? this.config.clientInfo
+    );
+    const connectorOptions = {
+      headers,
+      fetch: configuredFetch ?? globalThis.fetch.bind(globalThis),
+      authToken,
+      authProvider,
+      wrapTransport,
+      clientOptions,
+      onSampling: resolved.onSampling,
+      onElicitation: resolved.onElicitation,
+      onNotification: resolved.onNotification,
+      protocolNegotiation,
+      timeout,
+      clientInfo,
+      gatewayUrl,
+      serverId,
+      reconnectionOptions
+    };
+    logger.debug(
+      `[BrowserMCPClient] Connector options prepared (clientOptions: ${clientOptions ? "provided" : "none"})`
+    );
+    return new HttpConnector(url, connectorOptions);
+  }
+};
+
+// src/utils/favicon.ts
+var FAVICON_API = "https://favicon.tools.mcp-use.com";
+var IPV4_RE = /^\d{1,3}(\.\d{1,3}){3}$/;
+function parseHostname(serverUrl) {
+  try {
+    const raw = serverUrl.includes("://") ? serverUrl : `https://${serverUrl}`;
+    return new URL(raw).hostname;
+  } catch {
+    return null;
+  }
+}
+function isLocalHost(hostname) {
+  const h = hostname.toLowerCase();
+  if (h === "localhost" || h.endsWith(".localhost")) return true;
+  if (h === "host.docker.internal" || h === "0.0.0.0") return true;
+  if (!IPV4_RE.test(h)) return false;
+  if (h === "127.0.0.1" || h.startsWith("127.")) return true;
+  if (h.startsWith("10.")) return true;
+  if (h.startsWith("192.168.")) return true;
+  const m = /^172\.(\d+)\./.exec(h);
+  if (m) {
+    const second = Number.parseInt(m[1], 10);
+    if (second >= 16 && second <= 31) return true;
+  }
+  return false;
+}
+function subdomainLevels(hostname) {
+  const parts = hostname.split(".");
+  return Array.from(
+    { length: parts.length - 1 },
+    (_, i) => parts.slice(i).join(".")
+  );
+}
+function blobToDataUrl(blob) {
+  return new Promise((resolve, reject) => {
+    const reader = new FileReader();
+    reader.onloadend = () => resolve(reader.result);
+    reader.onerror = reject;
+    reader.readAsDataURL(blob);
+  });
+}
+async function detectFavicon(serverUrl) {
+  try {
+    const hostname = parseHostname(serverUrl);
+    if (!hostname || isLocalHost(hostname)) return null;
+    for (const domain of subdomainLevels(hostname)) {
+      try {
+        const res = await fetch(`${FAVICON_API}/${domain}?response=json`, {
+          signal: AbortSignal.timeout(2e3)
+        });
+        if (!res.ok) continue;
+        const data = await res.json();
+        if (data.source === "default") continue;
+        const imageUrl = data.url.replace(/^http:\/\//, "https://");
+        const img = await fetch(imageUrl, {
+          signal: AbortSignal.timeout(2e3)
+        });
+        if (!img.ok) continue;
+        return await blobToDataUrl(await img.blob());
+      } catch {
+        continue;
+      }
+    }
+    return null;
+  } catch (error) {
+    console.warn("[favicon] Error detecting favicon:", error);
+    return null;
+  }
+}
+export {
+  BaseConnector,
+  BrowserOAuthClientProvider,
+  DialectJsonSchemaValidator,
+  HttpConnector,
+  BrowserMCPClient as MCPClient,
+  MCPConnection,
+  MCPConnection as MCPSession,
+  POSTHOG_API_KEY,
+  POSTHOG_HOST,
+  SCARF_GATEWAY_URL,
+  Tel,
+  Telemetry,
+  UnauthorizedError3 as UnauthorizedError,
+  VERSION,
+  auth2 as auth,
+  capturePostHog,
+  captureScarf,
+  completeOAuthFlow,
+  createConnectorFromConfig,
+  createOAuthProvider,
+  detectFavicon,
+  getPackageVersion,
+  isUnauthorized,
+  logger,
+  normalizeClientInfo,
+  onMcpAuthorization,
+  resolveCallbacks,
+  resolveClientOptions,
+  setProductVersion,
+  setTelemetrySource,
+  shouldAutoProvisionOAuth,
+  telFetch
+};
+//# sourceMappingURL=index-browser.js.map