Add device flow fallback for Docker environments

- Add StartDeviceFlow for environments without callback capabilities
- Add StartOAuthFlow that auto-selects between device and interactive flows
- Detect Docker environment and use device flow automatically
- Add --oauth-callback-port flag for advanced Docker users with port binding
- Support fixed ports in callback server for Docker -p usage
- Update all OAuth endpoints to include device auth URL
- Comprehensive tests for both flows and port configurations
- Update README with Docker-specific OAuth instructions

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

Author: Copilot

README.md

@@ -190,10 +190,17 @@ To keep your GitHub PAT secure and reusable across different MCP hosts:
 
 For stdio mode (local binary execution), you can use OAuth 2.1 with PKCE instead of a Personal Access Token. This provides an interactive browser-based login flow.
 
+**The OAuth flow automatically adapts to your environment:**
+- **Native binary**: Uses interactive PKCE flow (browser opens automatically)
+- **Docker container**: Uses device flow (displays code + URL, no callback needed)
+- **Docker with port binding**: Can use PKCE flow with `--oauth-callback-port`
+
 #### Prerequisites for OAuth
 
 1. Create a GitHub OAuth App at [https://github.com/settings/developers](https://github.com/settings/developers)
-   - Set the callback URL to `http://localhost` (the actual port will be dynamically assigned)
+   - For native binary: Set callback URL to `http://localhost` (port is dynamic)
+   - For Docker with port binding: Set callback URL to `http://localhost:PORT/callback` (your chosen port)
+   - For Docker with device flow: No callback URL needed
    - For public clients, you can use PKCE without a client secret
 
 2. Set your OAuth app credentials:
@@ -204,22 +211,47 @@ For stdio mode (local binary execution), you can use OAuth 2.1 with PKCE instead
 
 3. Run the server without a PAT:
    ```bash
+   # Native binary - interactive PKCE flow
    ./github-mcp-server stdio
+   
+   # Docker - device flow (automatic)
+   docker run -i --rm -e GITHUB_OAUTH_CLIENT_ID=your_client_id ghcr.io/github/github-mcp-server
+   
+   # Docker with port binding - interactive PKCE flow
+   docker run -i --rm -p 8080:8080 \
+     -e GITHUB_OAUTH_CLIENT_ID=your_client_id \
+     -e GITHUB_OAUTH_CALLBACK_PORT=8080 \
+     ghcr.io/github/github-mcp-server
    ```
 
-The server will automatically detect the OAuth configuration and launch your browser for authorization. After you approve, the server will receive the token and start normally.
+The server will automatically detect the environment and use the appropriate OAuth flow.
 
 #### OAuth Configuration Options
 
 - `--oauth-client-id` / `GITHUB_OAUTH_CLIENT_ID` - Your GitHub OAuth app client ID (required for OAuth flow)
 - `--oauth-client-secret` / `GITHUB_OAUTH_CLIENT_SECRET` - Your client secret (optional, PKCE is used)
 - `--oauth-scopes` / `GITHUB_OAUTH_SCOPES` - Comma-separated list of scopes (defaults: `repo,user,gist,notifications,read:org,project`)
+- `--oauth-callback-port` / `GITHUB_OAUTH_CALLBACK_PORT` - Fixed callback port for Docker (0 for random)
 
 Example with custom scopes:
 ```bash
 ./github-mcp-server stdio --oauth-client-id YOUR_CLIENT_ID --oauth-scopes repo,user
 ```
 
+#### Device Flow vs Interactive Flow
+
+**Device Flow** (automatic in Docker):
+- Displays a verification URL and code
+- User visits URL in browser and enters code
+- No callback server required
+- Works in any environment
+
+**Interactive PKCE Flow** (automatic for native binary):
+- Opens browser automatically
+- User approves scopes
+- Faster and more seamless
+- Requires callback server (localhost)
+
 > **Note**: OAuth authentication is only available in stdio mode. For remote server usage, use Personal Access Tokens as described above.
 
 ### GitHub Enterprise Server and Enterprise Cloud with data residency (ghe.com)

cmd/github-mcp-server/main.go

@@ -45,9 +45,10 @@ var (
 						viper.GetString("oauth_client_secret"),
 						getOAuthScopes(),
 						viper.GetString("host"), // Pass the gh-host configuration
+						viper.GetInt("oauth_callback_port"),
 					)
 
-					result, err := oauth.StartInteractiveFlow(cmd.Context(), oauthCfg)
+					result, err := oauth.StartOAuthFlow(cmd.Context(), oauthCfg)
 					if err != nil {
 						return fmt.Errorf("OAuth flow failed: %w", err)
 					}
@@ -137,6 +138,7 @@ func init() {
 	rootCmd.PersistentFlags().String("oauth-client-id", "", "GitHub OAuth app client ID (enables interactive OAuth flow if token not set)")
 	rootCmd.PersistentFlags().String("oauth-client-secret", "", "GitHub OAuth app client secret (optional for public clients with PKCE)")
 	rootCmd.PersistentFlags().StringSlice("oauth-scopes", nil, "OAuth scopes to request (comma-separated)")
+	rootCmd.PersistentFlags().Int("oauth-callback-port", 0, "Fixed port for OAuth callback (0 for random, required for Docker with -p flag)")
 
 	// Bind flag to viper
 	_ = viper.BindPFlag("toolsets", rootCmd.PersistentFlags().Lookup("toolsets"))
@@ -155,6 +157,7 @@ func init() {
 	_ = viper.BindPFlag("oauth_client_id", rootCmd.PersistentFlags().Lookup("oauth-client-id"))
 	_ = viper.BindPFlag("oauth_client_secret", rootCmd.PersistentFlags().Lookup("oauth-client-secret"))
 	_ = viper.BindPFlag("oauth_scopes", rootCmd.PersistentFlags().Lookup("oauth-scopes"))
+	_ = viper.BindPFlag("oauth_callback_port", rootCmd.PersistentFlags().Lookup("oauth-callback-port"))
 
 	// Add subcommands
 	rootCmd.AddCommand(stdioCmd)

internal/oauth/oauth.go

@@ -25,13 +25,15 @@ const (
 
 // Config holds the OAuth configuration
 type Config struct {
-	ClientID     string
-	ClientSecret string // Optional for public clients with PKCE
-	RedirectURL  string
-	Scopes       []string
-	AuthURL      string
-	TokenURL     string
-	Host         string // GitHub host (for constructing OAuth URLs)
+	ClientID      string
+	ClientSecret  string // Optional for public clients with PKCE
+	RedirectURL   string
+	Scopes        []string
+	AuthURL       string
+	TokenURL      string
+	Host          string // GitHub host (for constructing OAuth URLs)
+	DeviceAuthURL string // Device authorization URL (for device flow)
+	CallbackPort  int    // Fixed callback port (0 for random)
 }
 
 // Result contains the OAuth flow result
@@ -54,6 +56,81 @@ func generatePKCEVerifier() (string, error) {
 	return verifier, nil
 }
 
+// isRunningInDocker detects if the process is running inside a Docker container
+func isRunningInDocker() bool {
+	// Check for .dockerenv file (most common indicator)
+	if _, err := os.Stat("/.dockerenv"); err == nil {
+		return true
+	}
+
+	// Check cgroup for docker (fallback)
+	data, err := os.ReadFile("/proc/1/cgroup")
+	if err == nil && (strings.Contains(string(data), "docker") || strings.Contains(string(data), "containerd")) {
+		return true
+	}
+
+	return false
+}
+
+// StartDeviceFlow initiates an OAuth device authorization flow
+// This is suitable for environments without callback capabilities (like Docker containers)
+func StartDeviceFlow(ctx context.Context, cfg Config) (*Result, error) {
+	oauth2Cfg := &oauth2.Config{
+		ClientID:     cfg.ClientID,
+		ClientSecret: cfg.ClientSecret,
+		Scopes:       cfg.Scopes,
+		Endpoint: oauth2.Endpoint{
+			AuthURL:       cfg.AuthURL,
+			TokenURL:      cfg.TokenURL,
+			DeviceAuthURL: cfg.DeviceAuthURL,
+		},
+	}
+
+	// Request device authorization
+	deviceAuth, err := oauth2Cfg.DeviceAuth(ctx)
+	if err != nil {
+		return nil, fmt.Errorf("failed to get device authorization: %w", err)
+	}
+
+	// Display verification instructions to user
+	fmt.Fprint(os.Stderr, "\n"+strings.Repeat("=", 80)+"\n")
+	fmt.Fprint(os.Stderr, "GitHub OAuth Device Authorization\n")
+	fmt.Fprint(os.Stderr, strings.Repeat("=", 80)+"\n\n")
+	fmt.Fprintf(os.Stderr, "Please visit: %s\n\n", deviceAuth.VerificationURI)
+	fmt.Fprintf(os.Stderr, "And enter code: %s\n\n", deviceAuth.UserCode)
+	fmt.Fprint(os.Stderr, strings.Repeat("=", 80)+"\n\n")
+
+	// Poll for token
+	token, err := oauth2Cfg.DeviceAccessToken(ctx, deviceAuth)
+	if err != nil {
+		return nil, fmt.Errorf("failed to get device access token: %w", err)
+	}
+
+	fmt.Fprint(os.Stderr, "\n✓ Authorization successful!\n\n")
+
+	return &Result{
+		AccessToken:  token.AccessToken,
+		RefreshToken: token.RefreshToken,
+		TokenType:    token.TokenType,
+		Expiry:       token.Expiry,
+	}, nil
+}
+
+// StartOAuthFlow automatically selects the appropriate OAuth flow based on environment
+// - Device flow for Docker containers (no callback server possible)
+// - Interactive PKCE flow for native binaries (best UX with browser)
+func StartOAuthFlow(ctx context.Context, cfg Config) (*Result, error) {
+	// Check if we're in Docker
+	if isRunningInDocker() && cfg.CallbackPort == 0 {
+		// Docker without explicit callback port - use device flow
+		log.Printf("Detected Docker environment, using device flow")
+		return StartDeviceFlow(ctx, cfg)
+	}
+
+	// Use interactive PKCE flow (browser-based)
+	return StartInteractiveFlow(ctx, cfg)
+}
+
 // StartInteractiveFlow initiates an interactive OAuth flow with PKCE
 // This is intended for stdio mode only and opens a browser for user consent
 func StartInteractiveFlow(ctx context.Context, cfg Config) (*Result, error) {
@@ -83,7 +160,7 @@ func StartInteractiveFlow(ctx context.Context, cfg Config) (*Result, error) {
 	state := base64.RawURLEncoding.EncodeToString(stateBytes)
 
 	// Start local HTTP server for callback
-	listener, port, err := startLocalServer()
+	listener, port, err := startLocalServer(cfg.CallbackPort)
 	if err != nil {
 		return nil, fmt.Errorf("failed to start local server: %w", err)
 	}
@@ -167,15 +244,17 @@ func StartInteractiveFlow(ctx context.Context, cfg Config) (*Result, error) {
 	}, nil
 }
 
-// startLocalServer starts a local HTTP server on a random available port
-func startLocalServer() (net.Listener, int, error) {
-	listener, err := net.Listen("tcp", "localhost:0")
+// startLocalServer starts a local HTTP server on the specified port
+// If port is 0, uses a random available port
+func startLocalServer(port int) (net.Listener, int, error) {
+	addr := fmt.Sprintf("localhost:%d", port)
+	listener, err := net.Listen("tcp", addr)
 	if err != nil {
-		return nil, 0, fmt.Errorf("failed to start listener: %w", err)
+		return nil, 0, fmt.Errorf("failed to start listener on %s: %w", addr, err)
 	}
 
-	port := listener.Addr().(*net.TCPAddr).Port
-	return listener, port, nil
+	actualPort := listener.Addr().(*net.TCPAddr).Port
+	return listener, actualPort, nil
 }
 
 // createCallbackHandler creates an HTTP handler for the OAuth callback
@@ -263,25 +342,28 @@ func openBrowser(url string) error {
 
 // GetGitHubOAuthConfig returns the GitHub OAuth configuration for the specified host
 // host can be empty for github.com, or a full URL like "https://github.enterprise.com" for GHES
-func GetGitHubOAuthConfig(clientID, clientSecret string, scopes []string, host string) Config {
-	authURL, tokenURL := getOAuthEndpoints(host)
+func GetGitHubOAuthConfig(clientID, clientSecret string, scopes []string, host string, callbackPort int) Config {
+	authURL, tokenURL, deviceAuthURL := getOAuthEndpoints(host)
 
 	return Config{
-		ClientID:     clientID,
-		ClientSecret: clientSecret,
-		Scopes:       scopes,
-		AuthURL:      authURL,
-		TokenURL:     tokenURL,
-		Host:         host,
+		ClientID:      clientID,
+		ClientSecret:  clientSecret,
+		Scopes:        scopes,
+		AuthURL:       authURL,
+		TokenURL:      tokenURL,
+		DeviceAuthURL: deviceAuthURL,
+		Host:          host,
+		CallbackPort:  callbackPort,
 	}
 }
 
 // getOAuthEndpoints returns the appropriate OAuth endpoints based on the host
-func getOAuthEndpoints(host string) (authURL, tokenURL string) {
+func getOAuthEndpoints(host string) (authURL, tokenURL, deviceAuthURL string) {
 	// Default to github.com
 	if host == "" {
 		return "https://github.com/login/oauth/authorize",
-			"https://github.com/login/oauth/access_token"
+			"https://github.com/login/oauth/access_token",
+			"https://github.com/login/device/code"
 	}
 
 	// For GHES/GHEC, OAuth endpoints are at the main domain, not api subdomain
@@ -319,6 +401,7 @@ func getOAuthEndpoints(host string) (authURL, tokenURL string) {
 
 	authURL = fmt.Sprintf("%s://%s/login/oauth/authorize", scheme, hostname)
 	tokenURL = fmt.Sprintf("%s://%s/login/oauth/access_token", scheme, hostname)
+	deviceAuthURL = fmt.Sprintf("%s://%s/login/device/code", scheme, hostname)
 
-	return authURL, tokenURL
+	return authURL, tokenURL, deviceAuthURL
 }

internal/oauth/oauth_test.go

@@ -33,34 +33,51 @@ func TestGetGitHubOAuthConfig(t *testing.T) {
 	scopes := []string{"repo", "user"}
 
 	t.Run("default github.com", func(t *testing.T) {
-		cfg := GetGitHubOAuthConfig(clientID, clientSecret, scopes, "")
+		cfg := GetGitHubOAuthConfig(clientID, clientSecret, scopes, "", 0)
 
 		assert.Equal(t, clientID, cfg.ClientID)
 		assert.Equal(t, clientSecret, cfg.ClientSecret)
 		assert.Equal(t, scopes, cfg.Scopes)
 		assert.Equal(t, "https://github.com/login/oauth/authorize", cfg.AuthURL)
 		assert.Equal(t, "https://github.com/login/oauth/access_token", cfg.TokenURL)
+		assert.Equal(t, "https://github.com/login/device/code", cfg.DeviceAuthURL)
 		assert.Equal(t, "", cfg.Host)
+		assert.Equal(t, 0, cfg.CallbackPort)
 	})
 
 	t.Run("GHES host", func(t *testing.T) {
-		cfg := GetGitHubOAuthConfig(clientID, clientSecret, scopes, "https://github.enterprise.com")
+		cfg := GetGitHubOAuthConfig(clientID, clientSecret, scopes, "https://github.enterprise.com", 8080)
 
 		assert.Equal(t, clientID, cfg.ClientID)
 		assert.Equal(t, clientSecret, cfg.ClientSecret)
 		assert.Equal(t, scopes, cfg.Scopes)
 		assert.Equal(t, "https://github.enterprise.com/login/oauth/authorize", cfg.AuthURL)
 		assert.Equal(t, "https://github.enterprise.com/login/oauth/access_token", cfg.TokenURL)
+		assert.Equal(t, "https://github.enterprise.com/login/device/code", cfg.DeviceAuthURL)
 		assert.Equal(t, "https://github.enterprise.com", cfg.Host)
+		assert.Equal(t, 8080, cfg.CallbackPort)
 	})
 }
 
 func TestStartLocalServer(t *testing.T) {
-	listener, port, err := startLocalServer()
-	require.NoError(t, err)
-	require.NotNil(t, listener)
-	defer listener.Close()
+	t.Run("random port", func(t *testing.T) {
+		listener, port, err := startLocalServer(0)
+		require.NoError(t, err)
+		require.NotNil(t, listener)
+		defer listener.Close()
+
+		assert.Greater(t, port, 0)
+		assert.Less(t, port, 65536)
+	})
 
-	assert.Greater(t, port, 0)
-	assert.Less(t, port, 65536)
+	t.Run("fixed port", func(t *testing.T) {
+		// Use a high port to avoid conflicts
+		fixedPort := 54321
+		listener, port, err := startLocalServer(fixedPort)
+		require.NoError(t, err)
+		require.NotNil(t, listener)
+		defer listener.Close()
+
+		assert.Equal(t, fixedPort, port)
+	})
 }