From d85bbc201ea7d72933445b1995ded812b46e23c4 Mon Sep 17 00:00:00 2001
From: shlee1223 <shlee1223@raoncorp.com>
Date: Thu, 29 Oct 2026 16:05:40 +0900
Subject: [PATCH] docs(client): reattach JSDoc to
 validateAuthorizationResponseIssuer and InsufficientScopeError

---
 .changeset/reattach-auth-jsdoc.md        |  5 +++
 packages/client/src/client/auth.ts       | 20 ++++++------
 packages/client/src/client/authErrors.ts | 40 ++++++++++++------------
 3 files changed, 35 insertions(+), 30 deletions(-)
 create mode 100644 .changeset/reattach-auth-jsdoc.md

diff --git a/.changeset/reattach-auth-jsdoc.md b/.changeset/reattach-auth-jsdoc.md
new file mode 100644
index 0000000000..1f3f69670e
--- /dev/null
+++ b/.changeset/reattach-auth-jsdoc.md
@@ -0,0 +1,5 @@
+---
+'@modelcontextprotocol/client': patch
+---
+
+Restore the documentation of `validateAuthorizationResponseIssuer()` and `InsufficientScopeError`, which was attached to the wrong declarations and missing from the published types.
diff --git a/packages/client/src/client/auth.ts b/packages/client/src/client/auth.ts
index 69366521da..1a44c43863 100644
--- a/packages/client/src/client/auth.ts
+++ b/packages/client/src/client/auth.ts
@@ -583,6 +583,16 @@ export class UnauthorizedError extends Error {
     }
 }
 
+/**
+ * Reads RFC 9207's `authorization_response_iss_parameter_supported` from
+ * authorization-server metadata. Only a literal `true` counts as advertised;
+ * absent, `false`, or a non-boolean wire value (coerced to `undefined` by the
+ * schema) means not advertised.
+ */
+function isIssParameterSupported(metadata: AuthorizationServerMetadata | undefined): boolean {
+    return metadata?.authorization_response_iss_parameter_supported === true;
+}
+
 /**
  * Validates the `iss` parameter from an authorization response against the
  * issuer recorded from the authorization server's validated metadata, per
@@ -604,16 +614,6 @@ export class UnauthorizedError extends Error {
  *
  * @throws {IssuerMismatchError} with `kind: 'authorization_response'`
  */
-/**
- * Reads RFC 9207's `authorization_response_iss_parameter_supported` from
- * authorization-server metadata. Only a literal `true` counts as advertised;
- * absent, `false`, or a non-boolean wire value (coerced to `undefined` by the
- * schema) means not advertised.
- */
-function isIssParameterSupported(metadata: AuthorizationServerMetadata | undefined): boolean {
-    return metadata?.authorization_response_iss_parameter_supported === true;
-}
-
 export function validateAuthorizationResponseIssuer({
     iss,
     expectedIssuer,
diff --git a/packages/client/src/client/authErrors.ts b/packages/client/src/client/authErrors.ts
index df61820c5f..1c402dcab7 100644
--- a/packages/client/src/client/authErrors.ts
+++ b/packages/client/src/client/authErrors.ts
@@ -156,26 +156,6 @@ export class InsecureTokenEndpointError extends OAuthClientFlowError {
     }
 }
 
-/**
- * Thrown by the HTTP client transport when the server responds with
- * `403 Forbidden` and `WWW-Authenticate: Bearer error="insufficient_scope"`,
- * and either (a) the transport's `onInsufficientScope` option is `'throw'`, or
- * (b) `onInsufficientScope` is the default `'reauthorize'` but the transport
- * has no {@linkcode index.OAuthClientProvider | OAuthClientProvider} to drive
- * step-up (e.g. a minimal `AuthProvider`, `requestInit`-only headers, or no
- * `authProvider`).
- *
- * Carries the challenge parameters so the host can decide whether to initiate
- * step-up authorization itself (e.g., behind a UX gate) or surface the error.
- *
- * Does **not** extend `OAuthError`: that class represents OAuth protocol errors
- * from the authorization server; this is a resource-server challenge surfaced
- * at the transport layer.
- *
- * All fields originate from the resource server's `WWW-Authenticate` header;
- * treat them as untrusted input when displaying or logging (this includes
- * `requiredScope`, which appears in the error message).
- */
 /**
  * Thrown by `auth()` and `fetchToken()` when the authorization server in use differs
  * from the one a credential is bound to and the flow cannot simply start over:
@@ -208,6 +188,26 @@ export class AuthorizationServerMismatchError extends OAuthClientFlowError {
     }
 }
 
+/**
+ * Thrown by the HTTP client transport when the server responds with
+ * `403 Forbidden` and `WWW-Authenticate: Bearer error="insufficient_scope"`,
+ * and either (a) the transport's `onInsufficientScope` option is `'throw'`, or
+ * (b) `onInsufficientScope` is the default `'reauthorize'` but the transport
+ * has no {@linkcode index.OAuthClientProvider | OAuthClientProvider} to drive
+ * step-up (e.g. a minimal `AuthProvider`, `requestInit`-only headers, or no
+ * `authProvider`).
+ *
+ * Carries the challenge parameters so the host can decide whether to initiate
+ * step-up authorization itself (e.g., behind a UX gate) or surface the error.
+ *
+ * Does **not** extend `OAuthError`: that class represents OAuth protocol errors
+ * from the authorization server; this is a resource-server challenge surfaced
+ * at the transport layer.
+ *
+ * All fields originate from the resource server's `WWW-Authenticate` header;
+ * treat them as untrusted input when displaying or logging (this includes
+ * `requiredScope`, which appears in the error message).
+ */
 export class InsufficientScopeError extends OAuthClientFlowError {
     static {
         Object.defineProperty(this, 'mcpBrand', { value: 'mcp.InsufficientScopeError' });