feat: add root OAuth discovery fallback with RFC compliance

Implements root OAuth discovery fallback when path-aware discovery fails,
restoring compatibility behavior from original code. Adds comprehensive
RFC documentation for OAuth 2.0 Authorization Server Metadata (RFC 8414)
and OpenID Connect Discovery 1.0 path handling rules.

Discovery sequence for issuer with path components:
1. OAuth with path insertion (RFC 8414 Section 3.1)
2. OIDC with path insertion (RFC 8414 Section 5 compatibility)
3. OIDC with path appending (OIDC Discovery 1.0 Section 4.1)
4. OAuth root fallback for compatibility

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <[email protected]>

Author: pcarleton

src/client/auth.test.ts

@@ -774,6 +774,52 @@ describe("OAuth Authorization", () => {
       expect(calls.length).toBe(2);
     });
 
+    it("should fall back to root OAuth discovery when path-aware discovery fails", async () => {
+      // First call (OAuth with path) returns 404
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+      });
+
+      // Second call (OIDC with path insertion) returns 404
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+      });
+
+      // Third call (OIDC with path appending) returns 404
+      mockFetch.mockResolvedValueOnce({
+        ok: false,
+        status: 404,
+      });
+
+      // Fourth call should be OAuth root fallback
+      mockFetch.mockResolvedValueOnce({
+        ok: true,
+        status: 200,
+        json: async () => validOAuthMetadata,
+      });
+
+      const metadata = await discoverAuthorizationServerMetadata(
+        "https://mcp.example.com",
+        "https://auth.example.com/tenant1"
+      );
+
+      expect(metadata).toEqual(validOAuthMetadata);
+      const calls = mockFetch.mock.calls;
+      expect(calls.length).toBe(4);
+      
+      // Should try OAuth with path first
+      expect(calls[0][0].toString()).toBe("https://auth.example.com/.well-known/oauth-authorization-server/tenant1");
+      
+      // Should try OIDC discoveries next
+      expect(calls[1][0].toString()).toBe("https://auth.example.com/.well-known/openid-configuration/tenant1");
+      expect(calls[2][0].toString()).toBe("https://auth.example.com/tenant1/.well-known/openid-configuration");
+      
+      // Should finally fall back to OAuth root discovery  
+      expect(calls[3][0].toString()).toBe("https://auth.example.com/.well-known/oauth-authorization-server");
+    });
+
     it("handles authorization server URL with path in OAuth discovery", async () => {
       mockFetch.mockResolvedValueOnce({
         ok: true,

src/client/auth.ts

@@ -698,6 +698,9 @@ export async function discoverAuthorizationServerMetadata(
     });
   }
 
+  const url = typeof authorizationServerUrl === 'string' ? new URL(authorizationServerUrl) : authorizationServerUrl;
+  const hasPath = url.pathname !== '/';
+
   const oauthMetadata = await retrieveOAuthMetadataFromAuthorizationServer(authorizationServerUrl, {
     fetchFn,
     protocolVersion,
@@ -707,10 +710,26 @@ export async function discoverAuthorizationServerMetadata(
     return oauthMetadata;
   }
 
-  return retrieveOpenIdProviderMetadataFromAuthorizationServer(authorizationServerUrl, {
+  const oidcMetadata = await retrieveOpenIdProviderMetadataFromAuthorizationServer(authorizationServerUrl, {
     fetchFn,
     protocolVersion,
   });
+
+  if (oidcMetadata) {
+    return oidcMetadata;
+  }
+
+  // If both path-aware discoveries failed and the issuer has a path component,
+  // try OAuth discovery at the root as a final fallback for compatibility
+  if (hasPath) {
+    const rootUrl = new URL(url.origin);
+    return retrieveOAuthMetadataFromAuthorizationServer(rootUrl, {
+      fetchFn,
+      protocolVersion,
+    });
+  }
+
+  return undefined;
 }
 
 /**
@@ -756,8 +775,12 @@ async function retrieveOAuthMetadataFromMcpServer(
 
 /**
  * Retrieves RFC 8414 OAuth 2.0 Authorization Server Metadata from the authorization server.
+ * 
+ * Per RFC 8414 Section 3.1, when the issuer identifier contains path components,
+ * the well-known URI is constructed by inserting "/.well-known/oauth-authorization-server"
+ * before the path component.
  *
- * @param authorizationServerUrl - The authorization server URL
+ * @param authorizationServerUrl - The authorization server URL (issuer identifier)
  * @param options - Configuration options
  * @param options.fetchFn - Optional fetch function for making HTTP requests, defaults to global fetch
  * @param options.protocolVersion - MCP protocol version to use (required)
@@ -774,7 +797,6 @@ async function retrieveOAuthMetadataFromAuthorizationServer(
   }
 ): Promise<OAuthMetadata | undefined> {
   const url = typeof authorizationServerUrl === 'string' ? new URL(authorizationServerUrl) : authorizationServerUrl;
-
   const hasPath = url.pathname !== '/';
 
   const metadataEndpoint = new URL(
@@ -801,8 +823,13 @@ async function retrieveOAuthMetadataFromAuthorizationServer(
 
 /**
  * Retrieves OpenID Connect Discovery 1.0 metadata from the authorization server.
+ * 
+ * Per RFC 8414 Section 5 compatibility notes and OpenID Connect Discovery 1.0 Section 4.1,
+ * when the issuer identifier contains path components, discovery endpoints are tried in order:
+ * 1. RFC 8414 style: Insert /.well-known/openid-configuration before the path
+ * 2. OIDC Discovery 1.0 style: Append /.well-known/openid-configuration after the path
  *
- * @param authorizationServerUrl - The authorization server URL
+ * @param authorizationServerUrl - The authorization server URL (issuer identifier)
  * @param options - Configuration options
  * @param options.fetchFn - Optional fetch function for making HTTP requests, defaults to global fetch
  * @param options.protocolVersion - MCP protocol version to use (required)