feat: implement OAuth device flow authentication

cmd/github-mcp-server/main.go

@@ -1,7 +1,6 @@
 package main
 
 import (
-	"errors"
 	"fmt"
 	"os"
 	"strings"
@@ -32,10 +31,8 @@ var (
 		Short: "Start stdio server",
 		Long:  `Start a server that communicates via standard input/output streams using JSON-RPC messages.`,
 		RunE: func(_ *cobra.Command, _ []string) error {
+			// Token is optional - if not provided, server starts in auth mode
 			token := viper.GetString("personal_access_token")
-			if token == "" {
-				return errors.New("GITHUB_PERSONAL_ACCESS_TOKEN not set")
-			}
 
 			// 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
@@ -84,6 +81,8 @@ var (
 				ContentWindowSize:    viper.GetInt("content-window-size"),
 				LockdownMode:         viper.GetBool("lockdown-mode"),
 				RepoAccessCacheTTL:   &ttl,
+				OAuthClientID:        viper.GetString("oauth-client-id"),
+				OAuthClientSecret:    viper.GetString("oauth-client-secret"),
 			}
 			return ghmcp.RunStdioServer(stdioServerConfig)
 		},
@@ -109,6 +108,8 @@ func init() {
 	rootCmd.PersistentFlags().Int("content-window-size", 5000, "Specify the content window size")
 	rootCmd.PersistentFlags().Bool("lockdown-mode", false, "Enable lockdown mode")
 	rootCmd.PersistentFlags().Duration("repo-access-cache-ttl", 5*time.Minute, "Override the repo access cache TTL (e.g. 1m, 0s to disable)")
+	rootCmd.PersistentFlags().String("oauth-client-id", "", "OAuth App client ID for device flow authentication (optional, uses default if not provided)")
+	rootCmd.PersistentFlags().String("oauth-client-secret", "", "OAuth App client secret for device flow authentication (optional, for confidential clients)")
 
 	// Bind flag to viper
 	_ = viper.BindPFlag("toolsets", rootCmd.PersistentFlags().Lookup("toolsets"))
@@ -123,6 +124,8 @@ func init() {
 	_ = viper.BindPFlag("content-window-size", rootCmd.PersistentFlags().Lookup("content-window-size"))
 	_ = viper.BindPFlag("lockdown-mode", rootCmd.PersistentFlags().Lookup("lockdown-mode"))
 	_ = viper.BindPFlag("repo-access-cache-ttl", rootCmd.PersistentFlags().Lookup("repo-access-cache-ttl"))
+	_ = viper.BindPFlag("oauth-client-id", rootCmd.PersistentFlags().Lookup("oauth-client-id"))
+	_ = viper.BindPFlag("oauth-client-secret", rootCmd.PersistentFlags().Lookup("oauth-client-secret"))
 
 	// Add subcommands
 	rootCmd.AddCommand(stdioCmd)

docs/auth-design.md

@@ -0,0 +1,321 @@
+# OAuth Device Flow Authentication Design
+
+## Overview
+
+This document describes the implementation of OAuth Device Flow authentication for the GitHub MCP Server's stdio transport. The design enables users to authenticate without pre-configuring tokens, making setup significantly simpler.
+
+## Problem Statement
+
+Currently, users must:
+1. Generate a Personal Access Token (PAT) manually on GitHub
+2. Configure the token in their MCP host's configuration (often in plain text)
+3. Manage token rotation manually
+
+This creates friction for new users and security concerns around token storage.
+
+## Proposed Solution
+
+When the server starts without a `GITHUB_PERSONAL_ACCESS_TOKEN`, instead of failing, it starts in "unauthenticated mode" with only authentication tools available. Users authenticate through MCP tool calls:
+
+1. **`auth_login`** - Initiates device flow, returns verification URL and user code
+2. **`auth_verify`** - Completes the flow after user authorizes in browser
+
+Once authenticated, the token is held in memory for the session and all regular tools become available.
+
+## User Experience
+
+### Before (Current)
+```jsonc
+{
+  "githubz": {
+    "command": "docker",
+    "args": ["run", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "ghcr.io/github/github-mcp-server"],
+    "env": {
+      "GITHUB_PERSONAL_ACCESS_TOKEN": "${input:github_token}"  // User must create PAT first
+    }
+  }
+}
+```
+
+### After (New)
+```jsonc
+{
+  "github": {
+    "command": "docker", 
+    "args": ["run", "--rm", "-i", "ghcr.io/github/github-mcp-server", "stdio", "--toolsets=all"]
+    // No token needed! User authenticates via tool call
+  }
+}
+```
+
+### Authentication Flow (User Perspective)
+
+1. User asks agent: "Create an issue on my repo"
+2. Agent calls `auth_login` tool
+3. Tool returns:
+   ```
+   To authenticate, visit: https://github.com/login/device
+   Enter code: ABCD-1234
+   
+   After authorizing, use the auth_verify tool to complete login.
+   ```
+4. User opens browser, enters code, clicks "Authorize"
+5. Agent calls `auth_verify` tool
+6. Tool returns: "Successfully authenticated as @username"
+7. Agent proceeds with original request using now-available tools
+
+## Technical Design
+
+### Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                        MCP Server                                │
+├─────────────────────────────────────────────────────────────────┤
+│                                                                  │
+│  ┌──────────────┐    ┌──────────────┐    ┌──────────────────┐  │
+│  │ Auth State   │───▶│ Tool Filter  │───▶│ GitHub Clients   │  │
+│  │ Manager      │    │              │    │ (lazy init)      │  │
+│  └──────────────┘    └──────────────┘    └──────────────────┘  │
+│         │                                         │              │
+│         │ token                                   │              │
+│         ▼                                         ▼              │
+│  ┌──────────────┐                        ┌──────────────────┐  │
+│  │ Device Flow  │                        │ REST/GraphQL     │  │
+│  │ Handler      │                        │ Clients          │  │
+│  └──────────────┘                        └──────────────────┘  │
+│                                                                  │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+### State Machine
+
+```
+┌─────────────────┐
+│ UNAUTHENTICATED │ ◀──────────────────────────────┐
+│                 │                                 │
+│ Tools: auth_*   │                                 │
+└────────┬────────┘                                 │
+         │ auth_login()                             │
+         ▼                                          │
+┌─────────────────┐                                 │
+│ PENDING_AUTH    │                                 │
+│                 │──── timeout/error ─────────────▶│
+│ Tools: auth_*   │                                 │
+└────────┬────────┘                                 │
+         │ auth_verify() success                    │
+         ▼                                          │
+┌─────────────────┐                                 │
+│ AUTHENTICATED   │                                 │
+│                 │──── token invalid ─────────────▶│
+│ Tools: all      │                                 │
+└─────────────────┘
+```
+
+### Host URL Derivation
+
+For different GitHub products, device flow endpoints are derived from the configured host:
+
+| Product | Host Config | Device Code Endpoint |
+|---------|-------------|---------------------|
+| github.com | (default) | `https://github.com/login/device/code` |
+| GHEC | `https://tenant.ghe.com` | `https://tenant.ghe.com/login/device/code` |
+| GHES | `https://github.example.com` | `https://github.example.com/login/device/code` |
+
+### OAuth App Requirements
+
+The device flow requires an OAuth App. Options:
+1. **GitHub-provided OAuth App** (recommended) - We register a public OAuth App for this purpose
+2. **User-provided OAuth App** - Via `--oauth-client-id` flag for enterprise scenarios
+
+Default OAuth App scopes (matching `gh` CLI minimal scopes):
+- `repo` - Full control of private repositories
+- `read:org` - Read org membership
+- `gist` - Create gists
+
+### Key Components
+
+#### 1. Auth State Manager (`pkg/github/auth_state.go`)
+
+```go
+type AuthState struct {
+    mu           sync.RWMutex
+    token        string
+    deviceCode   *DeviceCodeResponse
+    pollInterval time.Duration
+    expiresAt    time.Time
+}
+
+func (a *AuthState) IsAuthenticated() bool
+func (a *AuthState) GetToken() string
+func (a *AuthState) StartDeviceFlow(ctx context.Context, host apiHost, clientID string) (*DeviceCodeResponse, error)
+func (a *AuthState) CompleteDeviceFlow(ctx context.Context) (string, error)
+```
+
+#### 2. Auth Tools (`pkg/github/auth_tools.go`)
+
+```go
+// auth_login tool - initiates device flow
+func AuthLogin(ctx context.Context) (*AuthLoginResult, error)
+
+// auth_verify tool - completes device flow  
+func AuthVerify(ctx context.Context) (*AuthVerifyResult, error)
+```
+
+#### 3. Dynamic Tool Registration
+
+When unauthenticated, only auth tools are registered. After successful auth:
+1. Initialize GitHub clients with new token
+2. Register all configured toolsets
+3. Send `tools/list_changed` notification to client
+
+### Docker Considerations
+
+With `--rm` containers:
+- Token lives only in memory for the session duration
+- User re-authenticates each time container starts
+- This is acceptable UX since device flow is quick (~30 seconds)
+
+For persistent auth (optional future enhancement):
+- Mount a config volume: `-v ~/.config/github-mcp-server:/config`
+- Server stores encrypted token in volume
+- Requires user opt-in for security
+
+### Security Considerations
+
+1. **Token never in config** - Token obtained at runtime, never written to disk (in --rm mode)
+2. **Short-lived session** - Token only valid for container lifetime
+3. **Principle of least privilege** - Request minimal scopes
+4. **PKCE** - Use PKCE extension for additional security (if supported)
+5. **User verification** - User explicitly authorizes in browser with full visibility
+
+### Error Handling
+
+| Scenario | Behavior |
+|----------|----------|
+| Device flow timeout | Return error, user can retry `auth_login` |
+| User denies authorization | Return error explaining denial |
+| Network issues during poll | Retry with backoff, eventually timeout |
+| Invalid client ID | Clear error message with setup instructions |
+| Token expires mid-session | Return 401-like error, prompt re-auth via tools |
+
+## Implementation Plan
+
+### Phase 1: Core Auth Flow
+1. Add `pkg/github/auth_state.go` - Auth state management
+2. Add `pkg/github/auth_tools.go` - Auth tool implementations
+3. Modify `internal/ghmcp/server.go` - Support unauthenticated startup
+4. Add device flow endpoint derivation for all host types
+
+### Phase 2: Dynamic Tool Registration
+1. Implement `tools/list_changed` notification after auth
+2. Add tool filtering based on auth state
+3. Update inventory to support dynamic registration
+
+### Phase 3: Polish & Documentation
+1. Add comprehensive error messages
+2. Update README with new usage
+3. Add integration tests
+4. Document OAuth App setup for enterprises
+
+## Usage Documentation
+
+### Quick Start (New Users)
+
+```jsonc
+// VS Code settings.json or mcp.json
+{
+  "servers": {
+    "github": {
+      "command": "docker",
+      "args": ["run", "--rm", "-i", "ghcr.io/github/github-mcp-server", "stdio"],
+      "type": "stdio"
+    }
+  }
+}
+```
+
+Then just ask your AI assistant to do something with GitHub - it will guide you through authentication!
+
+### Native Installation
+
+```bash
+# Install
+go install github.com/github/github-mcp-server/cmd/github-mcp-server@latest
+
+# Run (will prompt for auth on first GitHub operation)
+github-mcp-server stdio
+```
+
+### Enterprise (GHES/GHEC)
+
+```jsonc
+{
+  "servers": {
+    "github": {
+      "command": "github-mcp-server",
+      "args": ["stdio", "--gh-host", "https://github.mycompany.com"],
+      "type": "stdio"
+    }
+  }
+}
+```
+
+### With Pre-configured Token (Legacy/CI)
+
+```jsonc
+{
+  "servers": {
+    "github": {
+      "command": "github-mcp-server",
+      "args": ["stdio"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "ghp_xxxx"
+      },
+      "type": "stdio"
+    }
+  }
+}
+```
+
+## Open Questions
+
+1. **OAuth App ownership** - Should GitHub provide a first-party OAuth App, or require users to create their own?
+2. **Token refresh** - Should we support refresh tokens for longer sessions, or is re-auth acceptable?
+3. **Scope customization** - Should users be able to request additional scopes via tool parameters?
+4. **Persistent storage** - Should we support optional persistent token storage for non-Docker installs?
+
+## Appendix: Device Flow Sequence
+
+```mermaid
+sequenceDiagram
+    participant User
+    participant Agent as AI Agent
+    participant MCP as MCP Server
+    participant GH as GitHub
+
+    User->>Agent: "Create issue on my repo"
+    Agent->>MCP: tools/list
+    MCP-->>Agent: [auth_login, auth_verify]
+    
+    Agent->>MCP: tools/call auth_login
+    MCP->>GH: POST /login/device/code
+    GH-->>MCP: device_code, user_code, verification_uri
+    MCP-->>Agent: "Visit github.com/login/device, enter ABCD-1234"
+    
+    Agent->>User: "Please visit github.com/login/device and enter code ABCD-1234"
+    User->>GH: Opens browser, enters code, authorizes
+    
+    Agent->>MCP: tools/call auth_verify
+    MCP->>GH: POST /login/oauth/access_token (polling)
+    GH-->>MCP: access_token
+    MCP->>MCP: Initialize GitHub clients
+    MCP-->>Agent: notifications/tools/list_changed
+    MCP-->>Agent: "Authenticated as @username"
+    
+    Agent->>MCP: tools/list
+    MCP-->>Agent: [all tools now available]
+    Agent->>MCP: tools/call create_issue
+    MCP-->>Agent: Issue created!
+    Agent->>User: "Done! Created issue #123"
+```