Implement OAuth with URL elicitation and lazy authentication

Complete implementation of OAuth 2.1 authentication with MCP URL elicitation support:

**Core Features:**
- OAuth Manager with URL elicitation integration
- Lazy authentication (OAuth triggered on first tool call)
- Automatic flow selection (PKCE for native, device for Docker)
- Callback server cleanup after OAuth completion
- PKCE → Device flow fallback on failures

**URL Elicitation Integration:**
- PKCE flow: Browser auto-open with URL elicitation fallback
- Device flow: Always uses URL elicitation (no stderr)
- Returns mcp.URLElicitationRequiredError for client UI integration
- Background polling for token completion
- Automatic retry after authentication completes

**Architecture:**
- internal/oauth/manager.go: OAuth state management with elicitation
- Authentication middleware in server.go triggers OAuth on tool calls
- Dynamic scope computation based on enabled tools
- Zero-config ready (server starts without token)

**Flow Selection:**
- Docker without port → Device flow (automatic)
- Native binary → PKCE flow (browser opens)
- Docker with --oauth-callback-port → PKCE flow
- PKCE failure → Device flow fallback

**Security:**
- PKCE S256 for code exchange
- Device flow OAuth 2.0 standard
- State parameter prevents CSRF
- ReadHeaderTimeout prevents Slowloris
- Callback server closes after completion (frees port)
- Tokens never persisted

All tests pass ✓
Linting passes ✓
Builds successfully ✓

Co-authored-by: SamMorrowDrums <[email protected]>

Author: Copilot

cmd/github-mcp-server/main.go

@@ -35,41 +35,37 @@ var (
 		Use:   "stdio",
 		Short: "Start stdio server",
 		Long:  `Start a server that communicates via standard input/output streams using JSON-RPC messages.`,
-		RunE: func(cmd *cobra.Command, _ []string) error {
+		RunE: func(_ *cobra.Command, _ []string) error {
 			token := viper.GetString("personal_access_token")
+			var oauthMgr *oauth.Manager
 
-			// If no token provided, attempt OAuth if configured
+			// If no token provided, setup OAuth manager if configured
 			if token == "" {
 				oauthClientID := viper.GetString("oauth_client_id")
 				if oauthClientID != "" {
-					// Perform interactive OAuth flow with the command's context
+					// Create OAuth manager for lazy authentication
 					oauthCfg := oauth.GetGitHubOAuthConfig(
 						oauthClientID,
 						viper.GetString("oauth_client_secret"),
 						getOAuthScopes(),
-						viper.GetString("host"), // Pass the gh-host configuration
+						viper.GetString("host"),
 						viper.GetInt("oauth_callback_port"),
 					)
-
-					result, err := oauth.StartOAuthFlow(cmd.Context(), oauthCfg)
-					if err != nil {
-						// OAuth flow failed - warn but allow server to start
-						// This enables future zero-configuration fallback patterns
-						fmt.Fprintf(os.Stderr, "Warning: OAuth flow failed: %v\n", err)
-						fmt.Fprintf(os.Stderr, "Starting server without authentication - tools will fail until authenticated\n")
-					} else {
-						token = result.AccessToken
-					}
+					oauthMgr = oauth.NewManager(oauthCfg)
+					fmt.Fprintf(os.Stderr, "OAuth configured - will prompt for authentication when needed\n")
 				} else {
-					// No token and no OAuth configured - warn but allow server to start
-					// This enables future zero-configuration use with baked-in fallback app
 					fmt.Fprintf(os.Stderr, "Warning: No authentication configured\n")
-					fmt.Fprintf(os.Stderr, "  - Set GITHUB_PERSONAL_ACCESS_TOKEN environment variable, or\n")
-					fmt.Fprintf(os.Stderr, "  - Configure OAuth with --oauth-client-id (or GITHUB_OAUTH_CLIENT_ID)\n")
-					fmt.Fprintf(os.Stderr, "Starting server without authentication - tools will fail until authenticated\n")
+					fmt.Fprintf(os.Stderr, "  - Set GITHUB_PERSONAL_ACCESS_TOKEN, or\n")
+					fmt.Fprintf(os.Stderr, "  - Configure OAuth with --oauth-client-id\n")
+					fmt.Fprintf(os.Stderr, "Tools will prompt for authentication when called\n")
 				}
 			}
 
+			// Extract token from OAuth manager if available
+			if oauthMgr != nil && token == "" {
+				token = oauthMgr.GetAccessToken()
+			}
+
 			// If you're wondering why we're not using viper.GetStringSlice("toolsets"),
 			// it's because viper doesn't handle comma-separated values correctly for env
 			// vars when using GetStringSlice.
@@ -106,6 +102,7 @@ var (
 				Version:              version,
 				Host:                 viper.GetString("host"),
 				Token:                token,
+				OAuthManager:         oauthMgr,
 				EnabledToolsets:      enabledToolsets,
 				EnabledTools:         enabledTools,
 				EnabledFeatures:      enabledFeatures,

internal/ghmcp/server.go

@@ -302,6 +302,14 @@ type StdioServerConfig struct {
 	// GitHub Token to authenticate with the GitHub API
 	Token string
 
+	// OAuthManager handles OAuth authentication with lazy loading
+	// When set, tools will trigger OAuth flow when authentication is needed
+	OAuthManager interface {
+		HasToken() bool
+		GetAccessToken() string
+		RequestAuthentication(context.Context) error
+	}
+
 	// EnabledToolsets is a list of toolsets to enable
 	// See: https://github.com/github/github-mcp-server?tab=readme-ov-file#tool-configuration
 	EnabledToolsets []string
@@ -405,6 +413,11 @@ func RunStdioServer(cfg StdioServerConfig) error {
 		return fmt.Errorf("failed to create MCP server: %w", err)
 	}
 
+	// Add OAuth authentication middleware if OAuth manager is configured
+	if cfg.OAuthManager != nil {
+		ghServer.AddReceivingMiddleware(createOAuthMiddleware(cfg.OAuthManager, logger))
+	}
+
 	if cfg.ExportTranslations {
 		// Once server is initialized, all translations are loaded
 		dumpTranslations()
@@ -699,3 +712,35 @@ func fetchTokenScopesForHost(ctx context.Context, token, host string) ([]string,
 
 	return fetcher.FetchTokenScopes(ctx, token)
 }
+
+// createOAuthMiddleware creates middleware that triggers OAuth authentication when needed
+func createOAuthMiddleware(oauthMgr interface {
+	HasToken() bool
+	GetAccessToken() string
+	RequestAuthentication(context.Context) error
+}, logger *slog.Logger) func(mcp.MethodHandler) mcp.MethodHandler {
+	return func(next mcp.MethodHandler) mcp.MethodHandler {
+		return func(ctx context.Context, method string, req mcp.Request) (mcp.Result, error) {
+			// Only check authentication for tool calls
+			if method != "tools/call" {
+				return next(ctx, method, req)
+			}
+
+			// Check if we have a token
+			if !oauthMgr.HasToken() {
+				logger.Info("no authentication token available, triggering OAuth flow")
+				// Trigger OAuth authentication
+				// This will return an MCP URL elicitation error that the client will handle
+				if err := oauthMgr.RequestAuthentication(ctx); err != nil {
+					// Return the error (which should be a URL elicitation error)
+					return nil, err
+				}
+				// If we get here without error, OAuth completed immediately
+				// Fall through to execute the tool with the new token
+			}
+
+			// Execute the tool with authentication
+			return next(ctx, method, req)
+		}
+	}
+}