Shift listener implementation out of the SDK

localden · localden · commit cbb504feda2f · 2025-06-02T18:28:50.000-07:00
diff --git a/samples/ProtectedMCPClient/Program.cs b/samples/ProtectedMCPClient/Program.cs
@@ -1,5 +1,10 @@
 using ModelContextProtocol.Authentication;
 using ModelContextProtocol.Client;
+using System;
+using System.Diagnostics;
+using System.Net;
+using System.Text;
+using System.Web;
 
 namespace ProtectedMCPClient;
 
@@ -18,18 +23,19 @@ static async Task Main(string[] args)
             PooledConnectionLifetime = TimeSpan.FromMinutes(2),
             PooledConnectionIdleTimeout = TimeSpan.FromMinutes(1)
         };
-        
+
         var httpClient = new HttpClient(sharedHandler);
-        
-        // Create the token provider with our custom HttpClient, 
-        // letting the AuthorizationHelpers be created automatically
+        // Create the token provider with our custom HttpClient and authorization URL handler
         var tokenProvider = new GenericOAuthProvider(
             new Uri(serverUrl),
             httpClient,
             null, // AuthorizationHelpers will be created automatically
             clientId: "6ad97b5f-7a7b-413f-8603-7a3517d4adb8",
+            clientSecret: "", // No secret needed for this client
             redirectUri: new Uri("http://localhost:1179/callback"),
-            scopes: ["api://167b4284-3f92-4436-92ed-38b38f83ae08/weather.read"]
+            scopes: ["api://167b4284-3f92-4436-92ed-38b38f83ae08/weather.read"],
+            logger: null,
+            authorizationUrlHandler: HandleAuthorizationUrlAsync
         );
 
         Console.WriteLine();
@@ -48,7 +54,7 @@ static async Task Main(string[] args)
                 transportOptions,
                 tokenProvider
             );
-            
+
             var client = await McpClientFactory.CreateAsync(transport);
 
             var tools = await client.ListToolsAsync();
@@ -82,12 +88,96 @@ static async Task Main(string[] args)
                 Console.WriteLine($"Inner error: {ex.InnerException.Message}");
             }
 
-            #if DEBUG
+#if DEBUG
             Console.WriteLine($"Stack trace: {ex.StackTrace}");
-            #endif
+#endif
         }
-
         Console.WriteLine("Press any key to exit...");
         Console.ReadKey();
     }
+
+    /// <summary>
+    /// Handles the OAuth authorization URL by starting a local HTTP server and opening a browser.
+    /// This implementation demonstrates how SDK consumers can provide their own authorization flow.
+    /// </summary>
+    /// <param name="authorizationUrl">The authorization URL to open in the browser.</param>
+    /// <param name="redirectUri">The redirect URI where the authorization code will be sent.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>The authorization code extracted from the callback, or null if the operation failed.</returns>    
+    private static async Task<string?> HandleAuthorizationUrlAsync(Uri authorizationUrl, Uri redirectUri, CancellationToken cancellationToken)
+    {
+        Console.WriteLine("Starting OAuth authorization flow...");
+        Console.WriteLine($"Opening browser to: {authorizationUrl}");
+
+        var listenerPrefix = redirectUri.GetLeftPart(UriPartial.Authority);
+        if (!listenerPrefix.EndsWith("/")) listenerPrefix += "/";
+
+        using var listener = new HttpListener();
+        listener.Prefixes.Add(listenerPrefix);
+
+        try
+        {
+            listener.Start();
+            Console.WriteLine($"Listening for OAuth callback on: {listenerPrefix}");
+
+            OpenBrowser(authorizationUrl);
+
+            var context = await listener.GetContextAsync();
+            var query = HttpUtility.ParseQueryString(context.Request.Url?.Query ?? string.Empty);
+            var code = query["code"];
+            var error = query["error"];
+
+            string responseHtml = "<html><body><h1>Authentication complete</h1><p>You can close this window now.</p></body></html>";
+            byte[] buffer = Encoding.UTF8.GetBytes(responseHtml);
+            context.Response.ContentLength64 = buffer.Length;
+            context.Response.ContentType = "text/html";
+            context.Response.OutputStream.Write(buffer, 0, buffer.Length);
+            context.Response.Close();
+
+            if (!string.IsNullOrEmpty(error))
+            {
+                Console.WriteLine($"Auth error: {error}");
+                return null;
+            }
+
+            if (string.IsNullOrEmpty(code))
+            {
+                Console.WriteLine("No authorization code received");
+                return null;
+            }
+
+            Console.WriteLine("Authorization code received successfully.");
+            return code;
+        }
+        catch (Exception ex)
+        {
+            Console.WriteLine($"Error getting auth code: {ex.Message}");
+            return null;
+        }
+        finally
+        {
+            if (listener.IsListening) listener.Stop();
+        }
+    }
+
+    /// <summary>
+    /// Opens the specified URL in the default browser.
+    /// </summary>
+    /// <param name="url">The URL to open.</param>
+    private static void OpenBrowser(Uri url)
+    {
+        try
+        {
+            var psi = new ProcessStartInfo
+            {
+                FileName = url.ToString(),
+                UseShellExecute = true
+            };
+            Process.Start(psi);
+        }
+        catch (Exception ex)
+        {
+            Console.WriteLine($"Error opening browser. {ex.Message}");
+        }
+    }
 }
diff --git a/src/ModelContextProtocol.Core/Authentication/GenericOAuthProvider.cs b/src/ModelContextProtocol.Core/Authentication/GenericOAuthProvider.cs
@@ -8,6 +8,32 @@
 
 namespace ModelContextProtocol.Authentication;
 
+/// <summary>
+/// Represents a method that handles the OAuth authorization URL and returns the authorization code.
+/// </summary>
+/// <param name="authorizationUrl">The authorization URL that the user needs to visit.</param>
+/// <param name="redirectUri">The redirect URI where the authorization code will be sent.</param>
+/// <param name="cancellationToken">The cancellation token.</param>
+/// <returns>A task that represents the asynchronous operation. The task result contains the authorization code if successful, or null if the operation failed or was cancelled.</returns>
+/// <remarks>
+/// <para>
+/// This delegate provides SDK consumers with full control over how the OAuth authorization flow is handled.
+/// Implementers can choose to:
+/// </para>
+/// <list type="bullet">
+/// <item><description>Start a local HTTP server and open a browser (default behavior)</description></item>
+/// <item><description>Display the authorization URL to the user for manual handling</description></item>
+/// <item><description>Integrate with a custom UI or authentication flow</description></item>
+/// <item><description>Use a different redirect mechanism altogether</description></item>
+/// </list>
+/// <para>
+/// The implementation should handle user interaction to visit the authorization URL and extract
+/// the authorization code from the callback. The authorization code is typically provided as
+/// a query parameter in the redirect URI callback.
+/// </para>
+/// </remarks>
+public delegate Task<string?> AuthorizationUrlHandler(Uri authorizationUrl, Uri redirectUri, CancellationToken cancellationToken);
+
 /// <summary>
 /// A generic implementation of an OAuth authorization provider for MCP. This does not do any advanced token
 /// protection or caching - it acquires a token and server metadata and holds it in memory. 
@@ -27,15 +53,14 @@ public class GenericOAuthProvider : IMcpCredentialProvider
     private readonly HttpClient _httpClient;    private readonly AuthorizationHelpers _authorizationHelpers;
     private readonly ILogger _logger;
     private readonly Func<IReadOnlyList<Uri>, Uri?> _authServerSelector;
+    private readonly AuthorizationUrlHandler _authorizationUrlHandler;
     
     // Lazy-initialized shared HttpClient for when no client is provided
     private static readonly Lazy<HttpClient> _defaultHttpClient = new(() => new HttpClient());
 
     private static readonly JsonSerializerOptions _jsonOptions = new() { PropertyNameCaseInsensitive = true };
     private TokenContainer? _token;
-    private AuthorizationServerMetadata? _authServerMetadata;
-
-    /// <summary>
+    private AuthorizationServerMetadata? _authServerMetadata;    /// <summary>
     /// Initializes a new instance of the <see cref="GenericOAuthProvider"/> class.
     /// </summary>
     /// <param name="serverUrl">The MCP server URL.</param>
@@ -54,7 +79,34 @@ public GenericOAuthProvider(
         string clientSecret = "",
         Uri? redirectUri = null,
         IEnumerable<string>? scopes = null,
-        ILogger<GenericOAuthProvider>? logger = null)        : this(serverUrl, httpClient, authorizationHelpers, clientId, clientSecret, redirectUri, scopes, logger, null)
+        ILogger<GenericOAuthProvider>? logger = null)
+        : this(serverUrl, httpClient, authorizationHelpers, clientId, clientSecret, redirectUri, scopes, logger, null, null)
+    {
+    }   
+    
+    /// <summary>
+    /// Initializes a new instance of the <see cref="GenericOAuthProvider"/> class with a custom authorization URL handler.
+    /// </summary>
+    /// <param name="serverUrl">The MCP server URL.</param>
+    /// <param name="httpClient">The HTTP client to use for OAuth requests. If null, a default HttpClient will be used.</param>
+    /// <param name="authorizationHelpers">The authorization helpers.</param>
+    /// <param name="clientId">OAuth client ID.</param>
+    /// <param name="clientSecret">OAuth client secret.</param>
+    /// <param name="redirectUri">OAuth redirect URI.</param>
+    /// <param name="scopes">OAuth scopes.</param>
+    /// <param name="logger">The logger instance. If null, a NullLogger will be used.</param>
+    /// <param name="authorizationUrlHandler">Custom handler for processing the OAuth authorization URL. If null, uses the default HTTP listener approach.</param>
+    public GenericOAuthProvider(
+        Uri serverUrl,
+        HttpClient? httpClient,
+        AuthorizationHelpers? authorizationHelpers,
+        string clientId,
+        string clientSecret,
+        Uri? redirectUri,
+        IEnumerable<string>? scopes,
+        ILogger<GenericOAuthProvider>? logger,
+        AuthorizationUrlHandler? authorizationUrlHandler)
+        : this(serverUrl, httpClient, authorizationHelpers, clientId, clientSecret, redirectUri, scopes, logger, null, authorizationUrlHandler)
     {
     }    /// <summary>
     /// Initializes a new instance of the <see cref="GenericOAuthProvider"/> class with explicit authorization server selection.
@@ -68,6 +120,7 @@ public GenericOAuthProvider(
     /// <param name="scopes">OAuth scopes.</param>
     /// <param name="logger">The logger instance. If null, a NullLogger will be used.</param>
     /// <param name="authServerSelector">Function to select which authorization server to use from available servers. If null, uses default selection strategy.</param>
+    /// <param name="authorizationUrlHandler">Custom handler for processing the OAuth authorization URL. If null, uses the default HTTP listener approach.</param>
     /// <exception cref="ArgumentNullException">Thrown when serverUrl is null.</exception>
     public GenericOAuthProvider(
         Uri serverUrl,
@@ -78,7 +131,8 @@ public GenericOAuthProvider(
         Uri? redirectUri,
         IEnumerable<string>? scopes,
         ILogger<GenericOAuthProvider>? logger,
-        Func<IReadOnlyList<Uri>, Uri?>? authServerSelector)
+        Func<IReadOnlyList<Uri>, Uri?>? authServerSelector,
+        AuthorizationUrlHandler? authorizationUrlHandler)
     {
         if (serverUrl == null) throw new ArgumentNullException(nameof(serverUrl));
         
@@ -94,17 +148,35 @@ public GenericOAuthProvider(
         
         // Set up authorization server selection strategy
         _authServerSelector = authServerSelector ?? DefaultAuthServerSelector;
-    }
-
-    /// <summary>
+        
+        // Set up authorization URL handler (use default if not provided)
+        _authorizationUrlHandler = authorizationUrlHandler ?? DefaultAuthorizationUrlHandler;
+    }    /// <summary>
     /// Default authorization server selection strategy that selects the first available server.
     /// </summary>
     /// <param name="availableServers">List of available authorization servers.</param>
-    /// <returns>The selected authorization server, or null if none are available.</returns>
+        /// <returns>The selected authorization server, or null if none are available.</returns>
     private static Uri? DefaultAuthServerSelector(IReadOnlyList<Uri> availableServers)
     {
         return availableServers.FirstOrDefault();
     }
+    
+    /// <summary>
+    /// Default authorization URL handler that displays the URL to the user for manual input.
+    /// </summary>
+    /// <param name="authorizationUrl">The authorization URL to handle.</param>
+    /// <param name="redirectUri">The redirect URI where the authorization code will be sent.</param>
+    /// <param name="cancellationToken">The cancellation token.</param>
+    /// <returns>The authorization code entered by the user, or null if none was provided.</returns>
+    private Task<string?> DefaultAuthorizationUrlHandler(Uri authorizationUrl, Uri redirectUri, CancellationToken cancellationToken)
+    {
+        Console.WriteLine($"Please open the following URL in your browser to authorize the application:");
+        Console.WriteLine($"{authorizationUrl}");
+        Console.WriteLine();
+        Console.Write("Enter the authorization code from the redirect URL: ");
+        var authorizationCode = Console.ReadLine();
+        return Task.FromResult<string?>(authorizationCode);
+    }
 
     /// <inheritdoc />
     public IEnumerable<string> SupportedSchemes => new[] { BearerScheme };
@@ -371,56 +443,9 @@ private Uri BuildAuthorizationUrl(AuthorizationServerMetadata authServerMetadata
         };
         return uriBuilder.Uri;
     }
-    
-    private async Task<string?> GetAuthorizationCodeAsync(Uri authorizationUrl, CancellationToken cancellationToken)
+      private async Task<string?> GetAuthorizationCodeAsync(Uri authorizationUrl, CancellationToken cancellationToken)
     {
-        var listenerPrefix = _redirectUri.GetLeftPart(UriPartial.Authority);
-        if (!listenerPrefix.EndsWith("/")) listenerPrefix += "/";
-        
-        using var listener = new System.Net.HttpListener();
-        listener.Prefixes.Add(listenerPrefix);
-        
-        try
-        {
-            listener.Start();
-            
-            OpenBrowser(authorizationUrl);
-            
-            var context = await listener.GetContextAsync();
-            var query = HttpUtility.ParseQueryString(context.Request.Url?.Query ?? string.Empty);
-            var code = query["code"];
-            var error = query["error"];
-            
-            string responseHtml = "<html><body><h1>Authentication complete</h1><p>You can close this window now.</p></body></html>";
-            byte[] buffer = Encoding.UTF8.GetBytes(responseHtml);
-            context.Response.ContentLength64 = buffer.Length;
-            context.Response.ContentType = "text/html";
-            context.Response.OutputStream.Write(buffer, 0, buffer.Length);
-            context.Response.Close();
-            
-            if (!string.IsNullOrEmpty(error))
-            {
-                _logger.LogError("Auth error: {Error}", error);
-                return null;
-            }
-            
-            if (string.IsNullOrEmpty(code))
-            {
-                _logger.LogError("No authorization code received");
-                return null;
-            }
-            
-            return code;
-        }
-        catch (Exception ex)
-        {
-            _logger.LogError(ex, "Error getting auth code");
-            return null;
-        }
-        finally
-        {
-            if (listener.IsListening) listener.Stop();
-        }
+        return await _authorizationUrlHandler(authorizationUrl, _redirectUri, cancellationToken);
     }
 
     private async Task<TokenContainer?> ExchangeCodeForTokenAsync(
