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

package/dist/index.js

@@ -209,6 +209,11 @@ var init_base = __esm({
       notificationHandlers = [];
       rootsCache = [];
       activeProgressHandlers = /* @__PURE__ */ new Set();
+      /**
+       * Creates a connector with shared SDK and callback options.
+       *
+       * @param opts - Connector initialization options.
+       */
       constructor(opts = {}) {
         this.opts = opts;
         if (opts.roots) {
@@ -391,7 +396,9 @@ var init_base = __esm({
         }
       }
       /**
-       * Get the current roots.
+       * Returns the roots currently advertised to the server.
+       *
+       * @returns A copy of the configured roots.
        */
       getRoots() {
         return [...this.rootsCache];
@@ -460,7 +467,11 @@ var init_base = __esm({
           "setupElicitationHandler: Elicitation handler registered successfully"
         );
       }
-      /** Disconnect and release resources. */
+      /**
+       * Disconnects the SDK client and releases transport resources.
+       *
+       * @returns A promise that resolves after cleanup completes.
+       */
       async disconnect() {
         if (!this.connected) {
           logger.debug("Not connected to MCP implementation");
@@ -471,7 +482,7 @@ var init_base = __esm({
         this.connected = false;
         logger.debug("Disconnected from MCP implementation");
       }
-      /** Check if the client is connected */
+      /** Whether an SDK client currently exists for this connector. */
       get isClientConnected() {
         return this.client != null;
       }
@@ -481,6 +492,10 @@ var init_base = __esm({
        * In the SDK, `Client.connect(transport)` automatically performs the
        * protocol‑level `initialize` handshake, so we only need to cache the list of
        * tools and expose some server info.
+       *
+       * @param defaultRequestOptions - Options used while fetching the initial tool list.
+       * @returns The capabilities advertised by the server.
+       * @throws When {@link BaseConnector.connect} has not completed.
        */
       async initialize(defaultRequestOptions = this.opts.defaultRequestOptions ?? {}) {
         if (!this.client) {
@@ -518,18 +533,22 @@ var init_base = __esm({
         logger.debug("Server info:", serverInfo);
         return capabilities;
       }
-      /** Lazily expose the cached tools list. */
+      /**
+       * Returns the tool list cached during initialization.
+       *
+       * @throws When {@link BaseConnector.initialize} has not completed.
+       */
       get tools() {
         if (!this.toolsCache) {
           throw new Error("MCP client is not initialized; call initialize() first");
         }
         return this.toolsCache;
       }
-      /** Expose cached server capabilities. */
+      /** Capabilities cached during initialization, or an empty object. */
       get serverCapabilities() {
         return this.capabilitiesCache || {};
       }
-      /** Expose cached server info. */
+      /** Server identity cached during initialization, or `null`. */
       get serverInfo() {
         return this.serverInfoCache;
       }
@@ -550,7 +569,15 @@ var init_base = __esm({
       get negotiatedProtocolVersion() {
         return this.client?.getNegotiatedProtocolVersion?.();
       }
-      /** Call a tool on the server. */
+      /**
+       * Calls a tool on the connected server.
+       *
+       * @param name - Tool name.
+       * @param args - Tool arguments.
+       * @param options - Per-request timeout, cancellation, and progress options.
+       * @returns The tool result returned by the server.
+       * @throws When the connector is not connected or the tool call fails.
+       */
       async callTool(name, args, options) {
         if (!this.client) {
           throw new Error("MCP client is not connected");
@@ -675,7 +702,13 @@ var init_base = __esm({
         );
         return result;
       }
-      /** Read a resource by URI. */
+      /**
+       * Reads a resource by URI.
+       *
+       * @param uri - Resource URI to read.
+       * @param options - Per-request options.
+       * @returns The resource contents returned by the server.
+       */
       async readResource(uri, options) {
         if (!this.client) {
           throw new Error("MCP client is not connected");
@@ -710,6 +743,11 @@ var init_base = __esm({
         logger.debug(`Unsubscribing from resource: ${uri}`);
         return await this.client.unsubscribeResource({ uri }, options);
       }
+      /**
+       * Lists prompts exposed by the server.
+       *
+       * @returns The prompt list, or an empty list when prompts are unsupported.
+       */
       async listPrompts() {
         if (!this.client) {
           throw new Error("MCP client is not connected");
@@ -730,6 +768,13 @@ var init_base = __esm({
           throw err;
         }
       }
+      /**
+       * Gets a prompt with the supplied arguments.
+       *
+       * @param name - Prompt name.
+       * @param args - Prompt arguments.
+       * @returns The rendered prompt returned by the server.
+       */
       async getPrompt(name, args) {
         if (!this.client) {
           throw new Error("MCP client is not connected");
@@ -737,7 +782,14 @@ var init_base = __esm({
         logger.debug(`Getting prompt ${name}`);
         return await this.client.getPrompt({ name, arguments: args });
       }
-      /** Send a raw request through the client. */
+      /**
+       * Sends a raw, potentially non-standard request through the SDK client.
+       *
+       * @param method - JSON-RPC method name.
+       * @param params - Request parameters. Defaults to an empty object.
+       * @param options - Per-request options.
+       * @returns The unvalidated result returned by the server.
+       */
       async request(method, params = null, options) {
         if (!this.client) {
           throw new Error("MCP client is not connected");
@@ -802,6 +854,8 @@ var init_connection_manager = __esm({
       _connection = null;
       _task = null;
       _abortController = null;
+      _startPromise = null;
+      _stopPromise = null;
       constructor() {
         this.reset();
       }
@@ -811,10 +865,21 @@ var init_connection_manager = __esm({
        * @returns The established connection.
        * @throws If the connection cannot be established.
        */
-      async start() {
+      start() {
+        if (this._stopPromise) {
+          return this._stopPromise.then(() => this.start());
+        }
+        if (this._startPromise) return this._startPromise;
         this.reset();
         logger.debug(`Starting ${this.constructor.name}`);
         this._task = this.connectionTask();
+        this._startPromise = this.waitUntilReady().catch((error) => {
+          this._startPromise = null;
+          throw error;
+        });
+        return this._startPromise;
+      }
+      async waitUntilReady() {
         await this._readyPromise;
         if (this._exception) {
           throw this._exception;
@@ -827,7 +892,18 @@ var init_connection_manager = __esm({
       /**
        * Stop the connection manager and close the connection.
        */
-      async stop() {
+      stop() {
+        if (this._stopPromise) return this._stopPromise;
+        if (!this._task) return Promise.resolve();
+        const trackedStop = this.stopTask().finally(() => {
+          if (this._stopPromise === trackedStop) {
+            this._stopPromise = null;
+          }
+        });
+        this._stopPromise = trackedStop;
+        return trackedStop;
+      }
+      async stopTask() {
         if (this._task && this._abortController) {
           logger.debug(`Cancelling ${this.constructor.name} task`);
           this._abortController.abort();
@@ -842,6 +918,8 @@ var init_connection_manager = __esm({
           }
         }
         await this._donePromise;
+        this._task = null;
+        this._startPromise = null;
         logger.debug(`${this.constructor.name} task completed`);
       }
       /**
@@ -933,6 +1011,11 @@ var init_stdio = __esm({
       errlog;
       clientInfo;
       protocolNegotiation;
+      /**
+       * Creates a stdio connector.
+       *
+       * @param options - Process launch, client identity, and shared connector options.
+       */
       constructor({
         command = "npx",
         args = [],
@@ -952,7 +1035,11 @@ var init_stdio = __esm({
         this.cwd = rest.cwd;
         this.protocolNegotiation = rest.protocolNegotiation ?? "legacy";
       }
-      /** Establish connection to the MCP implementation. */
+      /**
+       * Starts the child process and establishes an MCP connection.
+       *
+       * @returns A promise that resolves after protocol negotiation completes.
+       */
       async connect() {
         if (this.connected) {
           logger.debug("Already connected to MCP implementation");
@@ -1048,6 +1135,11 @@ var init_stdio = __esm({
           throw err;
         }
       }
+      /**
+       * Returns fields identifying the launched command and arguments.
+       *
+       * @returns Stdio connector identity metadata.
+       */
       get publicIdentifier() {
         return {
           type: "stdio",
@@ -1059,6 +1151,12 @@ var init_stdio = __esm({
       serverParams;
       errlog;
       _transport = null;
+      /**
+       * Creates a connection manager for a local server process.
+       *
+       * @param serverParams - Process parameters passed to the SDK transport.
+       * @param errlog - Destination for the child process's standard error stream.
+       */
       constructor(serverParams, errlog = process2.stderr) {
         super();
         this.serverParams = serverParams;
@@ -1108,7 +1206,7 @@ init_connector_telemetry();
 init_logging();
 
 // src/utils/version.ts
-var VERSION = "2.0.0-beta.8";
+var VERSION = "2.0.0";
 function getPackageVersion() {
   return VERSION;
 }
@@ -1128,16 +1226,13 @@ var MCPAgentExecutionEvent = class extends BaseTelemetryEvent {
     return {
       // Core execution info
       execution_method: this.data.executionMethod,
-      query: this.data.query,
       query_length: this.data.query.length,
       success: this.data.success,
       // Agent configuration
       model_provider: this.data.modelProvider,
       model_name: this.data.modelName,
       server_count: this.data.serverCount,
-      server_identifiers: this.data.serverIdentifiers,
       total_tools_available: this.data.totalToolsAvailable,
-      tools_available_names: this.data.toolsAvailableNames,
       max_steps_configured: this.data.maxStepsConfigured,
       memory_enabled: this.data.memoryEnabled,
       use_server_manager: this.data.useServerManager,
@@ -1148,8 +1243,6 @@ var MCPAgentExecutionEvent = class extends BaseTelemetryEvent {
       // Execution results (always include, even if null)
       steps_taken: this.data.stepsTaken ?? null,
       tools_used_count: this.data.toolsUsedCount ?? null,
-      tools_used_names: this.data.toolsUsedNames ?? null,
-      response: this.data.response ?? null,
       response_length: this.data.response ? this.data.response.length : null,
       execution_time_ms: this.data.executionTimeMs ?? null,
       error_type: this.data.errorType ?? null,
@@ -1245,21 +1338,72 @@ async function telFetch(url, init) {
 }
 var POSTHOG_HOST = "https://eu.i.posthog.com";
 var POSTHOG_API_KEY = "phc_lyTtbYwvkdSbrcMQNPiKiiRWrrM1seyKIMjycSvItEI";
-function capturePostHog(params) {
-  const host = params.host ?? POSTHOG_HOST;
-  const apiKey = params.apiKey ?? POSTHOG_API_KEY;
-  return telFetch(`${host}/i/v0/e/`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    keepalive: true,
-    body: JSON.stringify({
+var CONTENT_PROPERTY = /(^|_)(arguments?|args|body|command|headers?|location|message|query|response|secret|subject|token|uri|url|user_agent)(_|$)/i;
+var IDENTIFYING_PROPERTY = /(^|_)(server_identifiers?|server_names?|servers|tool_names?|tools_(available|used)_names)(_|$)/i;
+var AGGREGATE_PROPERTY = /(_count|_length|_duration(?:_ms)?|_time_ms|(^|_)num_[a-z0-9_]+)$/i;
+function normalizePropertyKey(key) {
+  return key.replace(/([a-z0-9])([A-Z])/g, "$1_$2").replace(/[^a-z0-9_$]+/gi, "_").toLowerCase();
+}
+function sanitizeValue(value, seen) {
+  if (Array.isArray(value)) {
+    if (seen.has(value)) {
+      throw new TypeError("Cyclic telemetry properties are not supported");
+    }
+    seen.add(value);
+    const sanitized = value.map((item) => sanitizeValue(item, seen));
+    seen.delete(value);
+    return sanitized;
+  }
+  if (value !== null && typeof value === "object" && (Object.getPrototypeOf(value) === Object.prototype || Object.getPrototypeOf(value) === null)) {
+    if (seen.has(value)) {
+      throw new TypeError("Cyclic telemetry properties are not supported");
+    }
+    seen.add(value);
+    const sanitized = sanitizeProperties(
+      value,
+      seen
+    );
+    seen.delete(value);
+    return sanitized;
+  }
+  return value;
+}
+function sanitizeProperties(properties, seen = /* @__PURE__ */ new WeakSet()) {
+  const sanitized = {};
+  for (const [key, value] of Object.entries(properties)) {
+    const normalizedKey = normalizePropertyKey(key);
+    if (AGGREGATE_PROPERTY.test(normalizedKey)) {
+      if (value === null || typeof value === "number") {
+        sanitized[key] = value;
+      }
+      continue;
+    }
+    if (IDENTIFYING_PROPERTY.test(normalizedKey) || CONTENT_PROPERTY.test(normalizedKey)) {
+      continue;
+    }
+    sanitized[key] = sanitizeValue(value, seen);
+  }
+  return sanitized;
+}
+async function capturePostHog(params) {
+  try {
+    const host = params.host ?? POSTHOG_HOST;
+    const apiKey = params.apiKey ?? POSTHOG_API_KEY;
+    const body = JSON.stringify({
       api_key: apiKey,
       event: params.event,
       distinct_id: params.distinctId,
-      properties: params.properties,
+      properties: sanitizeProperties(params.properties),
       timestamp: (/* @__PURE__ */ new Date()).toISOString()
-    })
-  });
+    });
+    await telFetch(`${host}/i/v0/e/`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      keepalive: true,
+      body
+    });
+  } catch {
+  }
 }
 
 // src/telemetry/telemetry.ts
@@ -1789,11 +1933,12 @@ async function completeOAuthFlow(provider, serverUrl, options = {}) {
       throw new Error(`Unexpected OAuth auth() result: ${result}`);
     }
   }
-  if (typeof flowProvider.getAuthorizationCode === "function") {
-    const code = await flowProvider.getAuthorizationCode();
+  if (typeof flowProvider.getAuthorizationResponse === "function" || typeof flowProvider.getAuthorizationCode === "function") {
+    const response = typeof flowProvider.getAuthorizationResponse === "function" ? await flowProvider.getAuthorizationResponse() : { code: await flowProvider.getAuthorizationCode() };
     await auth(provider, {
       serverUrl,
-      authorizationCode: code,
+      authorizationCode: response.code,
+      ...response.iss !== void 0 ? { iss: response.iss } : {},
       fetchFn
     });
     return;
@@ -1807,6 +1952,8 @@ async function waitForBrowserAuthComplete(provider, timeoutMs) {
     );
   }
   if (provider.useRedirectFlow) {
+    await new Promise(() => {
+    });
     return;
   }
   const tokensKey = provider.getKey?.("tokens");
@@ -1823,25 +1970,29 @@ async function waitForBrowserAuthComplete(provider, timeoutMs) {
     } catch {
     }
   }
-  const result = await runAuthPopup({
-    popup: null,
-    state,
-    tokensKey,
-    timeoutMs
-  });
-  switch (result.kind) {
-    case "success":
-      return;
-    case "cancelled":
-      throw new Error("OAuth authentication was cancelled.");
-    case "timeout":
-      throw new Error(
-        `OAuth callback not received within ${timeoutMs}ms. Ensure /oauth/callback calls onMcpAuthorization().`
-      );
-    case "error":
-      throw new Error(result.error);
-    default:
-      throw new Error("Unexpected OAuth popup result");
+  try {
+    const result = await runAuthPopup({
+      popup: null,
+      state,
+      tokensKey,
+      timeoutMs
+    });
+    switch (result.kind) {
+      case "success":
+        return;
+      case "cancelled":
+        throw new Error("OAuth authentication was cancelled.");
+      case "timeout":
+        throw new Error(
+          `OAuth callback not received within ${timeoutMs}ms. Ensure /oauth/callback calls onMcpAuthorization().`
+        );
+      case "error":
+        throw new Error(result.error);
+      default:
+        throw new Error("Unexpected OAuth popup result");
+    }
+  } finally {
+    provider.markFlowComplete?.();
   }
 }
 
@@ -2054,29 +2205,39 @@ var OAuthSessionStore = class _OAuthSessionStore {
     if (ctx) await this.store.set(this.credentialKey("tokens"), serialized);
     await this.store.remove(this.getKey("code_verifier"));
     await this.store.remove(this.getKey("last_auth_url"));
+    await this.store.remove(this.getKey("last_auth_callback_url"));
   }
   async clientInformation(ctx) {
+    if (!this.allowClientSecret) {
+      const registeredRedirectUri = await this.store.get(
+        this.getKey("client_info_redirect_uri")
+      );
+      if (registeredRedirectUri !== this.redirectUrl) {
+        await this.invalidateCredentials("registration");
+        console.info(
+          `[${this.storageKeyPrefix}] Re-registering browser OAuth client after its Inspector callback changed or could not be verified.`
+        );
+        return void 0;
+      }
+    }
     const stored = await this.readCredential("client_info", ctx);
     if (!stored) return void 0;
     const { key, value: clientInfo } = stored;
     try {
       if (!this.allowClientSecret && clientInfo.client_secret) {
-        await this.store.remove(key);
-        if (ctx) await this.store.remove(this.credentialKey("client_info"));
+        await this.invalidateCredentials("registration");
         console.warn(
-          `[${this.storageKeyPrefix}] Removed OAuth client information containing a browser client_secret.`
+          `[${this.storageKeyPrefix}] Recovered stale browser OAuth credentials containing a client_secret.`
         );
         return void 0;
       }
       const storedRedirectUris = Array.isArray(clientInfo.redirect_uris) ? clientInfo.redirect_uris : [];
-      const hasMatchingRedirect = storedRedirectUris.length === 0 || storedRedirectUris.includes(this.redirectUrl);
+      const hasMatchingRedirect = storedRedirectUris.length === 0 && this.allowClientSecret || storedRedirectUris.includes(this.redirectUrl);
       if (!hasMatchingRedirect) {
         console.info(
-          `[${this.storageKeyPrefix}] Invalidating cached OAuth client info due to redirect URI mismatch.`
+          `[${this.storageKeyPrefix}] Recovering cached OAuth credentials after a redirect URI change.`
         );
-        await this.store.remove(key);
-        await this.store.remove(this.credentialKey("tokens", ctx));
-        await this.store.remove(this.getKey("last_auth_url"));
+        await this.invalidateCredentials("registration");
         return void 0;
       }
       return clientInfo;
@@ -2094,11 +2255,20 @@ var OAuthSessionStore = class _OAuthSessionStore {
         "Browser OAuth clients must be public clients; client_secret persistence is not allowed."
       );
     }
-    const serialized = JSON.stringify(clientInformation);
+    const persistedClientInformation = !this.allowClientSecret && (!("redirect_uris" in clientInformation) || !Array.isArray(
+      clientInformation.redirect_uris
+    ) || clientInformation.redirect_uris.length === 0) ? { ...clientInformation, redirect_uris: [this.redirectUrl] } : clientInformation;
+    const serialized = JSON.stringify(persistedClientInformation);
     await this.store.set(this.credentialKey("client_info", ctx), serialized);
     if (ctx) {
       await this.store.set(this.credentialKey("client_info"), serialized);
     }
+    if (!this.allowClientSecret) {
+      await this.store.set(
+        this.getKey("client_info_redirect_uri"),
+        this.redirectUrl
+      );
+    }
   }
   async saveCodeVerifier(codeVerifier) {
     await this.store.set(this.getKey("code_verifier"), codeVerifier);
@@ -2123,11 +2293,22 @@ var OAuthSessionStore = class _OAuthSessionStore {
       }
     };
     switch (scope) {
+      case "registration":
+        await removeCredentialKeys("tokens");
+        await removeCredentialKeys("client_info");
+        await this.store.remove(this.getKey("code_verifier"));
+        await this.store.remove(this.getKey("last_auth_url"));
+        await this.store.remove(this.getKey("last_auth_callback_url"));
+        await this.store.remove(this.getKey("client_info_redirect_uri"));
+        await this.store.remove(this.getKey("token_endpoint"));
+        break;
       case "all":
         await removeCredentialKeys("tokens");
         await removeCredentialKeys("client_info");
         await this.store.remove(this.getKey("code_verifier"));
         await this.store.remove(this.getKey("last_auth_url"));
+        await this.store.remove(this.getKey("last_auth_callback_url"));
+        await this.store.remove(this.getKey("client_info_redirect_uri"));
         await this.store.remove(this.getKey("discovery_state"));
         await this.store.remove(this.getKey("token_endpoint"));
         break;
@@ -2177,7 +2358,7 @@ var OAuthSessionStore = class _OAuthSessionStore {
    */
   async storeAuthorizationState(authorizationUrl, opts = {}) {
     const state = globalThis.crypto.randomUUID();
-    const stateKey = `${this.storageKeyPrefix}:state_${state}`;
+    const stateKey = `${this.storageKeyPrefix}_${this.serverUrlHash}_state_${state}`;
     const stateData = {
       serverUrlHash: this.serverUrlHash,
       expiry: Date.now() + 1e3 * 60 * 10,
@@ -2197,6 +2378,10 @@ var OAuthSessionStore = class _OAuthSessionStore {
     authorizationUrl.searchParams.set("state", state);
     const sanitizedAuthUrl = sanitizeUrl(authorizationUrl.toString());
     await this.store.set(stateKey, JSON.stringify(stateData));
+    await this.store.set(
+      this.getKey("last_auth_callback_url"),
+      this.redirectUrl
+    );
     await this.store.set(this.getKey("last_auth_url"), sanitizedAuthUrl);
     return sanitizedAuthUrl;
   }
@@ -2222,8 +2407,16 @@ var DEFAULT_PORT = 33418;
 var PORT_RANGE = 10;
 var DEFAULT_AUTH_TIMEOUT_MS2 = 5 * 6e4;
 var OAuthFlowError = class extends Error {
+  /** OAuth or local-flow error code. */
   code;
+  /** Optional human-readable error description. */
   description;
+  /**
+   * Creates an OAuth flow error.
+   *
+   * @param code - OAuth or local-flow error code.
+   * @param description - Optional human-readable description.
+   */
   constructor(code, description) {
     super(description ? `${code}: ${description}` : code);
     this.code = code;
@@ -2273,16 +2466,20 @@ h1{font-size:20px;margin:0 0 12px;color:#b00020}p{line-height:1.5}code{backgroun
 <p><code>${escapeHtml(err)}</code>${desc ? `: ${escapeHtml(desc)}` : ""}</p>
 <p>You can close this tab and return to your terminal.</p></body></html>`;
 var NodeOAuthClientProvider = class _NodeOAuthClientProvider {
+  /** Protected MCP server URL associated with this provider. */
   serverUrl;
+  /** Reserved localhost callback port. */
   port;
   session;
   kv;
   authTimeoutMs;
   openBrowserOverride;
   server = null;
+  /** Provider authorization URL, exposed only through the local redirect route. */
+  authorizationUrl = null;
   /** Currently in-flight deferred — used to prevent overlapping flows. */
   pending = null;
-  /** Latest deferred (settled or in-flight) — what `getAuthorizationCode()` returns. */
+  /** Latest deferred (settled or in-flight) for the loopback response. */
   lastFlow = null;
   pendingTimer = null;
   constructor(serverUrl, port, session, kv, options) {
@@ -2293,6 +2490,13 @@ var NodeOAuthClientProvider = class _NodeOAuthClientProvider {
     this.authTimeoutMs = options.authTimeoutMs ?? DEFAULT_AUTH_TIMEOUT_MS2;
     this.openBrowserOverride = options.openBrowser;
   }
+  /**
+   * Creates a Node OAuth provider and reserves a localhost callback port.
+   *
+   * @param serverUrl - Protected MCP server URL.
+   * @param options - OAuth metadata, storage, loopback, and browser options.
+   * @returns A provider ready to participate in the SDK OAuth flow.
+   */
   static async create(serverUrl, options = {}) {
     const serverUrlHash = OAuthSessionStore.hashString(serverUrl);
     const kv = options.kvStore ?? new FileKVStore(serverUrlHash, options.baseDir);
@@ -2325,48 +2529,100 @@ var NodeOAuthClientProvider = class _NodeOAuthClientProvider {
     return new _NodeOAuthClientProvider(serverUrl, port, session, kv, options);
   }
   // --- Identity passthroughs (parallel to BrowserOAuthClientProvider) ---
+  /** Prefix used for persisted OAuth session keys. */
   get storageKeyPrefix() {
     return this.session.storageKeyPrefix;
   }
+  /** Stable hash of the protected server URL used to namespace storage. */
   get serverUrlHash() {
     return this.session.serverUrlHash;
   }
   // --- SDK Interface (delegated to OAuthSessionStore) ---
+  /** Loopback redirect URL registered for this provider. */
   get redirectUrl() {
     return this.session.redirectUrl;
   }
+  /** OAuth client metadata presented during registration. */
   get clientMetadata() {
     return this.session.clientMetadata;
   }
+  /** OAuth Client ID Metadata Document URL, when configured. */
   get clientMetadataUrl() {
     return this.session.clientMetadataUrl;
   }
+  /**
+   * Loads saved OAuth tokens.
+   *
+   * @param ctx - Optional client registration context.
+   * @returns Saved tokens, or `undefined` when none exist.
+   */
   tokens(ctx) {
     return this.session.tokens(ctx);
   }
+  /**
+   * Persists OAuth tokens.
+   *
+   * @param tokens - Tokens to save.
+   * @param ctx - Optional client registration context.
+   */
   saveTokens(tokens, ctx) {
     return this.session.saveTokens(tokens, ctx);
   }
+  /**
+   * Loads saved OAuth client registration information.
+   *
+   * @param ctx - Optional registration context.
+   * @returns Saved registration information, or `undefined`.
+   */
   clientInformation(ctx) {
     return this.session.clientInformation(ctx);
   }
+  /**
+   * Persists OAuth client registration information.
+   *
+   * @param info - Client information to save.
+   * @param ctx - Optional registration context.
+   */
   saveClientInformation(info, ctx) {
     return this.session.saveClientInformation(info, ctx);
   }
+  /**
+   * Loads the saved PKCE code verifier.
+   *
+   * @returns The saved verifier.
+   */
   codeVerifier() {
     return this.session.codeVerifier();
   }
+  /**
+   * Persists a PKCE code verifier.
+   *
+   * @param codeVerifier - Verifier to save.
+   */
   saveCodeVerifier(codeVerifier) {
     return this.session.saveCodeVerifier(codeVerifier);
   }
+  /**
+   * Invalidates selected persisted OAuth credentials.
+   *
+   * @param scope - Credential group to remove.
+   */
   invalidateCredentials(scope) {
     return this.session.invalidateCredentials(scope);
   }
-  /** Persist OAuth discovery state (SEP-2352). Delegated to the session store. */
+  /**
+   * Persists OAuth discovery state.
+   *
+   * @param state - Discovery state to save.
+   */
   saveDiscoveryState(state) {
     return this.session.saveDiscoveryState(state);
   }
-  /** Return previously saved OAuth discovery state, or `undefined`. */
+  /**
+   * Returns previously saved OAuth discovery state.
+   *
+   * @returns Saved discovery state, or `undefined`.
+   */
   discoveryState() {
     return this.session.discoveryState();
   }
@@ -2374,6 +2630,10 @@ var NodeOAuthClientProvider = class _NodeOAuthClientProvider {
    * Bind the loopback server, set up the pending-code deferred, and ask the
    * platform to open the user's browser. Does NOT await the code; the
    * orchestrator awaits via `getAuthorizationCode()`.
+   *
+   * @param authorizationUrl - Authorization URL generated by the SDK.
+   * @returns A promise that resolves once the loopback listener is ready and
+   * the browser-open attempt completes.
    */
   async redirectToAuthorization(authorizationUrl) {
     if (this.pending) {
@@ -2385,6 +2645,7 @@ var NodeOAuthClientProvider = class _NodeOAuthClientProvider {
       authorizationUrl,
       { flowType: "redirect" }
     );
+    this.authorizationUrl = sanitizedUrl;
     await this.startLoopback();
     this.pending = createDeferred();
     this.lastFlow = this.pending;
@@ -2399,8 +2660,9 @@ var NodeOAuthClientProvider = class _NodeOAuthClientProvider {
       );
     }, this.authTimeoutMs);
     const opener = this.openBrowserOverride ?? defaultOpener;
+    const launcherUrl = `http://127.0.0.1:${this.port}/authorize`;
     try {
-      await opener(sanitizedUrl);
+      await opener(launcherUrl);
     } catch (err) {
       console.error(
         `[mcp-use] Could not open browser automatically: ${err instanceof Error ? err.message : String(err)}`
@@ -2409,15 +2671,30 @@ var NodeOAuthClientProvider = class _NodeOAuthClientProvider {
   }
   /**
    * Resolves with the authorization code captured by the loopback callback.
+   *
+   * @remarks This compatibility method omits the RFC 9207 issuer. OAuth flow
+   * orchestrators should use {@link getAuthorizationResponse} when available.
    * Must be called after `redirectToAuthorization()`. Returns the same
    * promise whether the callback has fired or not — callers may subscribe
    * before or after.
+   *
+   * @returns The authorization code received by the loopback callback.
    */
   getAuthorizationCode() {
+    return this.getAuthorizationResponse().then((response) => response.code);
+  }
+  /**
+   * Resolves with the authorization code and RFC 9207 issuer captured by the
+   * loopback callback.
+   *
+   * @returns The loopback authorization response.
+   * @throws When called before {@link NodeOAuthClientProvider.redirectToAuthorization}.
+   */
+  getAuthorizationResponse() {
     if (!this.lastFlow) {
       return Promise.reject(
         new Error(
-          "NodeOAuthClientProvider.getAuthorizationCode() called before redirectToAuthorization()"
+          "NodeOAuthClientProvider.getAuthorizationResponse() called before redirectToAuthorization()"
         )
       );
     }
@@ -2425,6 +2702,9 @@ var NodeOAuthClientProvider = class _NodeOAuthClientProvider {
   }
   /**
    * Cancel an in-progress flow (timeout, SIGINT, etc.) and close the loopback.
+   *
+   * Pending calls to {@link NodeOAuthClientProvider.getAuthorizationResponse}
+   * reject with an {@link OAuthFlowError} whose code is `"cancelled"`.
    */
   dispose() {
     if (this.pending) {
@@ -2433,7 +2713,7 @@ var NodeOAuthClientProvider = class _NodeOAuthClientProvider {
       this.stopLoopback();
     }
   }
-  /** Best-effort port for tests / status output. */
+  /** Local callback port, useful for status output and tests. */
   get callbackPort() {
     return this.port;
   }
@@ -2471,12 +2751,13 @@ var NodeOAuthClientProvider = class _NodeOAuthClientProvider {
       this.server.close();
       this.server = null;
     }
+    this.authorizationUrl = null;
   }
-  resolvePending(code) {
+  resolvePending(response) {
     const p = this.pending;
     this.pending = null;
     this.stopLoopback();
-    p?.resolve(code);
+    p?.resolve(response);
   }
   rejectPending(err) {
     const p = this.pending;
@@ -2486,6 +2767,19 @@ var NodeOAuthClientProvider = class _NodeOAuthClientProvider {
   }
   handleCallback(rawUrl, res) {
     const url = new URL(rawUrl, `http://127.0.0.1:${this.port}`);
+    if (url.pathname === "/authorize") {
+      if (this.authorizationUrl === null || this.pending === null) {
+        res.statusCode = 410;
+        res.end("Authorization flow is not active");
+        return;
+      }
+      res.statusCode = 302;
+      res.setHeader("location", this.authorizationUrl);
+      res.setHeader("cache-control", "no-store");
+      res.setHeader("referrer-policy", "no-referrer");
+      res.end();
+      return;
+    }
     if (url.pathname !== "/callback") {
       res.statusCode = 404;
       res.end("Not Found");
@@ -2493,6 +2787,7 @@ var NodeOAuthClientProvider = class _NodeOAuthClientProvider {
     }
     const code = url.searchParams.get("code");
     const state = url.searchParams.get("state");
+    const iss = url.searchParams.get("iss") ?? void 0;
     const err = url.searchParams.get("error");
     const errDesc = url.searchParams.get("error_description") ?? void 0;
     if (err) {
@@ -2510,7 +2805,7 @@ var NodeOAuthClientProvider = class _NodeOAuthClientProvider {
     res.statusCode = 200;
     res.setHeader("content-type", "text/html; charset=utf-8");
     res.end(SUCCESS_HTML);
-    this.resolvePending(code);
+    this.resolvePending({ code, ...iss !== void 0 ? { iss } : {} });
   }
 };
 async function defaultOpener(url) {
@@ -2592,6 +2887,12 @@ var HttpConnector = class extends BaseConnector {
   reconnectionOptions;
   transportType = null;
   streamableTransport = null;
+  /**
+   * Creates an HTTP connector.
+   *
+   * @param baseUrl - MCP endpoint URL.
+   * @param opts - Authentication, transport, SDK, and reconnection options.
+   */
   constructor(baseUrl, opts = {}) {
     super(opts);
     const originalUrl = baseUrl.replace(/\/$/, "");
@@ -2709,7 +3010,12 @@ var HttpConnector = class extends BaseConnector {
     }
     return { fallbackReason, is401Error, httpStatusCode };
   }
-  /** Establish connection to the MCP implementation via streamable HTTP. */
+  /**
+   * Establishes a streamable HTTP connection to the MCP server.
+   *
+   * @returns A promise that resolves after protocol negotiation completes.
+   * @throws An error with `code: 401` when authentication is required.
+   */
   async connect() {
     if (this.connected) {
       logger.debug("Already connected to MCP implementation");
@@ -2937,6 +3243,11 @@ var HttpConnector = class extends BaseConnector {
       throw err;
     }
   }
+  /**
+   * Returns fields that identify the endpoint and negotiated transport.
+   *
+   * @returns HTTP connector identity metadata.
+   */
   get publicIdentifier() {
     return {
       type: "http",
@@ -2945,7 +3256,11 @@ var HttpConnector = class extends BaseConnector {
       protocolEra: this.protocolEra ?? "unknown"
     };
   }
-  /** Get the active transport type (`streamable-http` once connected). */
+  /**
+   * Returns the active transport type.
+   *
+   * @returns `"streamable-http"` after connection, otherwise `null`.
+   */
   getTransportType() {
     return this.transportType;
   }
@@ -3320,7 +3635,7 @@ var MCPConnection = class {
   /**
    * Normalized server metadata for this ready connection.
    *
-   * @throws {Error} When called before protocol negotiation completes.
+   * @throws When called before protocol negotiation completes.
    */
   get info() {
     const protocolEra = this.protocolEra;
@@ -3532,12 +3847,10 @@ function isOAuthClientProvider(provider) {
 var BaseMCPClient = class {
   /**
    * Internal configuration object containing MCP server definitions.
-   * @protected
    */
   config = {};
   /**
    * Map of server names to their active sessions.
-   * @protected
    */
   sessions = {};
   /**
@@ -3581,7 +3894,7 @@ var BaseMCPClient = class {
    *
    * @param _cfg - Configuration dictionary
    * @returns Client instance
-   * @throws {Error} If called on the base class instead of a concrete implementation
+   * @throws If called on the base class instead of a concrete implementation
    *
    * @example
    * ```typescript
@@ -3723,7 +4036,7 @@ var BaseMCPClient = class {
    * @param serverName - The name of the server as defined in the client configuration
    * @param autoInitialize - Whether to automatically initialize the session (default: true)
    * @returns A promise that resolves to the created MCPSession instance
-   * @throws {Error} If the server is not found in the configuration
+   * @throws If the server is not found in the configuration
    *
    * @example
    * ```typescript
@@ -3893,7 +4206,7 @@ var BaseMCPClient = class {
    *
    * @param serverName - Name of the server
    * @returns The session instance
-   * @throws {Error} If the session is not found
+   * @throws If the session is not found
    *
    * @example
    * ```typescript
@@ -4277,20 +4590,24 @@ global.search_tools = async (query, detailLevel = 'full') => {
     for (const [serverName, serverTools] of Object.entries(tools)) {
       if (!serverTools || serverTools.length === 0) continue;
       const safeServerName = serverName.replace(/[^a-zA-Z0-9_]/g, "_");
+      const escapedServerName = JSON.stringify(serverName);
+      const escapedSafeServerName = JSON.stringify(safeServerName);
       shim += `
-global['${serverName}'] = {`;
+global[${escapedServerName}] = {`;
       for (const tool of serverTools) {
+        const escapedToolName = JSON.stringify(tool.name);
         shim += `
-    '${tool.name}': async (args) => await global.__callMcpTool('${serverName}', '${tool.name}', args),`;
+    [${escapedToolName}]: async (args) => await global.__callMcpTool(${escapedServerName}, ${escapedToolName}, args),`;
       }
       shim += `
 };
-
+`;
+      if (safeServerName !== serverName) {
+        shim += `
 // Also expose as safe name if different
-if ('${safeServerName}' !== '${serverName}') {
-    global['${safeServerName}'] = global['${serverName}'];
-}
+global[${escapedSafeServerName}] = global[${escapedServerName}];
 `;
+      }
     }
     return shim;
   }
@@ -4984,9 +5301,7 @@ var MCPClient = class _MCPClient extends BaseMCPClient {
    * @param config - Configuration object or path to JSON config file. If omitted,
    *                 starts with empty configuration
    * @param options - Optional client behavior configuration
-   * @param options.codeMode - Enable code execution mode (boolean or advanced config)
-   * @param options.onSampling - Callback for handling sampling requests from servers
-   * @param options.onElicitation - Callback for handling elicitation requests
+   * Options can enable code mode or provide sampling and elicitation callbacks.
    *
    * @example
    * ```typescript
@@ -5087,7 +5402,7 @@ var MCPClient = class _MCPClient extends BaseMCPClient {
    * });
    * ```
    *
-   * @see {@link constructor} for direct instantiation
+   * @see {@link MCPClient} for direct instantiation
    * @see {@link fromConfigFile} for loading from file
    */
   static fromDict(cfg, options) {
@@ -5102,7 +5417,7 @@ var MCPClient = class _MCPClient extends BaseMCPClient {
    * @param path - Path to the JSON configuration file
    * @param options - Optional client behavior configuration
    * @returns New MCPClient instance
-   * @throws {Error} If the file cannot be read or parsed
+   * @throws If the file cannot be read or parsed
    *
    * @example
    * ```typescript
@@ -5118,7 +5433,7 @@ var MCPClient = class _MCPClient extends BaseMCPClient {
    * });
    * ```
    *
-   * @see {@link constructor} for direct instantiation
+   * @see {@link MCPClient} for direct instantiation
    * @see {@link fromDict} for inline configuration
    */
   static fromConfigFile(path2, options) {
@@ -5265,7 +5580,7 @@ var MCPClient = class _MCPClient extends BaseMCPClient {
    * @param code - JavaScript/TypeScript code to execute
    * @param timeout - Optional execution timeout in milliseconds
    * @returns Execution result with output, errors, and return value
-   * @throws {Error} If code mode is not enabled
+   * @throws If code mode is not enabled
    *
    * @example
    * ```typescript
@@ -5311,7 +5626,7 @@ var MCPClient = class _MCPClient extends BaseMCPClient {
    * @param query - Optional search query to filter tools (defaults to empty string for all tools)
    * @param detailLevel - Level of detail to return: "names", "descriptions", or "full"
    * @returns Tool search results with matching tools
-   * @throws {Error} If code mode is not enabled
+   * @throws If code mode is not enabled
    *
    * @example
    * ```typescript