fix: preserve canonical URL format in OAuth resource parameter per MCP auth spec

[xiaoyijun]

Fix OAuth resource parameter URL handling to preserve canonical URL format and prevent automatic trailing slash addition, and also ensuring compliance with MCP auth specification requirements.

Motivation and Context

When using the MCP Client SDK, I discovered that resource indicators from MCP server backend's resource metadata were automatically getting trailing slashes appended, causing authentication server validation failures when checking the resource indicator.

This issue occurred because the previous implementation used URL.href which automatically normalizes URLs by:

1. Adding trailing slashes to domain-only URLs (e.g., https://example.com becomes https://example.com/)
2. Converting schemes and host components to lowercase (e.g., HTTPS://EXAMPLE.COM becomes https://example.com/)

Both behaviors violate the MCP auth specification requirements. According to the MCP auth specification:

While both https://mcp.example.com/ (with trailing slash) and https://mcp.example.com (without trailing slash) are technically valid absolute URIs according to RFC 3986, implementations SHOULD consistently use the form without the trailing slash for better interoperability unless the trailing slash is semantically significant for the specific resource.
While the canonical form uses lowercase scheme and host components, implementations SHOULD accept uppercase scheme and host components for robustness and interoperability.

How Has This Been Tested?

• ✅ Unit tests: Added comprehensive test coverage for resourceUrlFromServerUrl function including:

  • URL format preservation (with/without trailing slashes)
  • Fragment removal with various URL structures
  • Case preservation for uppercase schemes and host components
  • Edge cases (empty fragments, IPv6 addresses, complex URLs)
  • Comparison tests demonstrating differences from URL.href behavior

• ✅ OAuth flow integration tests: Added test suite "resource URL handling (trailing slash preservation)" in src/client/auth.test.ts:

  • preserves server URLs without trailing slash in resource parameter - verifies authorization flow
  • preserves server URLs with trailing slash in resource parameter - verifies authorization flow
  • handles token exchange with preserved resource URL format - verifies token exchange flow

• ✅ Existing tests: All 667 existing tests pass, ensuring no regressions in:

  • OAuth authorization flows
  • Client transport functionality (SSE and StreamableHTTP)
  • Auth utilities and helper functions

• ✅ Build verification: TypeScript compilation and ESLint checks pass

Breaking Changes

Minor breaking change: The exported function signatures in the auth module have changed from accepting URL objects to string parameters to ensure MCP spec compliance:

• validateResourceURL?(serverUrl: string, resource?: string) (was URL objects)
• selectResourceURL(serverUrl: string, ...) (was URL object)
• resourceUrlFromServerUrl(url: string) (was URL object)

Impact: Most users are unlikely to be affected as these functions are primarily used internally by the SDK. The change was necessary because the previous implementation with URL objects automatically normalized URLs in ways that violated the MCP auth specification requirements.

Migration: If you were directly using these functions, update calls to pass string URLs instead of URL objects. Use .href property if converting from URL objects.

Types of changes

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)
• Documentation update

Checklist

• I have read the MCP Documentation
• My code follows the repository's style guidelines
• New and existing tests pass locally
• I have added appropriate error handling
• I have added or updated documentation as needed

[xiaoyijun]

It's strange, the CI failed. All tests passed in my local machine.