docs: consolidate OAuth docs, trim README bloat

- Reduce README OAuth section from 145 to 22 lines
- Link to docs/oauth-authentication.md for full details
- Use concise table instead of verbose prose
- Net reduction: 125 lines from README

Author: SamMorrowDrums

README.md

@@ -188,149 +188,24 @@ To keep your GitHub PAT secure and reusable across different MCP hosts:
 
 ### OAuth Authentication (stdio mode)
 
-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.
+For stdio mode, you can use OAuth 2.1 instead of a Personal Access Token. The server automatically selects the appropriate 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`
+| Environment | Flow | Setup |
+|-------------|------|-------|
+| Native binary | PKCE (browser auto-opens) | Just set `GITHUB_OAUTH_CLIENT_ID` |
+| Docker | Device flow (enter code at github.com/login/device) | Just set `GITHUB_OAUTH_CLIENT_ID` |
+| Docker with port | PKCE (browser auto-opens) | Set `GITHUB_OAUTH_CALLBACK_PORT` and bind port |
 
-#### Quick Setup
-
-**Option 1: Device Flow (Easiest for Docker)**
-```bash
-# 1. Create GitHub OAuth App at https://github.com/settings/developers
-# 2. Run with Docker (device flow automatic)
-docker run -i --rm \
-  -e GITHUB_OAUTH_CLIENT_ID=your_client_id \
-  -e GITHUB_OAUTH_CLIENT_SECRET=your_client_secret \
-  ghcr.io/github/github-mcp-server
-# → Displays: Visit https://github.com/login/device and enter code: ABCD-1234
-```
-
-**Option 2: Interactive Flow (Best UX)**
+**Quick start:**
 ```bash
-# For native binary
 export GITHUB_OAUTH_CLIENT_ID=your_client_id
 export GITHUB_OAUTH_CLIENT_SECRET=your_client_secret
 ./github-mcp-server stdio
-# → Browser opens automatically
-
-# For Docker with port binding (requires setup in OAuth app callback)
-docker run -i --rm -p 8080:8080 \
-  -e GITHUB_OAUTH_CLIENT_ID=your_client_id \
-  -e GITHUB_OAUTH_CLIENT_SECRET=your_client_secret \
-  -e GITHUB_OAUTH_CALLBACK_PORT=8080 \
-  ghcr.io/github/github-mcp-server
-# → Browser opens automatically (callback works via bound port)
-```
-
-#### Prerequisites for OAuth
-
-1. Create a GitHub OAuth App at [https://github.com/settings/developers](https://github.com/settings/developers)
-   - 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
-
-2. Set your OAuth app credentials:
-   ```bash
-   export GITHUB_OAUTH_CLIENT_ID=your_client_id
-   export GITHUB_OAUTH_CLIENT_SECRET=your_client_secret
-   ```
-
-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 \
-     -e GITHUB_OAUTH_CLIENT_SECRET=your_client_secret \
-     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_CLIENT_SECRET=your_client_secret \
-     -e GITHUB_OAUTH_CALLBACK_PORT=8080 \
-     ghcr.io/github/github-mcp-server
-   ```
-
-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 GitHub OAuth app client secret (required)
-- `--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-client-secret YOUR_CLIENT_SECRET \
-  --oauth-scopes repo,user
 ```
 
-#### Pre-configured MCP Host Setup
-
-OAuth can be pre-configured for MCP hosts (similar to PAT distribution). For Docker with port binding:
-
-**Claude Desktop/Code:**
-```bash
-claude mcp add github \
-  -e GITHUB_OAUTH_CLIENT_ID=your_client_id \
-  -e GITHUB_OAUTH_CLIENT_SECRET=your_client_secret \
-  -e GITHUB_OAUTH_CALLBACK_PORT=8080 \
-  -- docker run -i --rm -p 8080:8080 \
-     -e GITHUB_OAUTH_CLIENT_ID \
-     -e GITHUB_OAUTH_CLIENT_SECRET \
-     -e GITHUB_OAUTH_CALLBACK_PORT \
-     ghcr.io/github/github-mcp-server
-```
-
-**VS Code (settings.json):**
-```json
-{
-  "mcp": {
-    "servers": {
-      "github": {
-        "command": "docker",
-        "args": ["run", "-i", "--rm", "-p", "8080:8080", 
-                 "-e", "GITHUB_OAUTH_CLIENT_ID", 
-                 "-e", "GITHUB_OAUTH_CLIENT_SECRET",
-                 "-e", "GITHUB_OAUTH_CALLBACK_PORT", 
-                 "ghcr.io/github/github-mcp-server"],
-        "env": {
-          "GITHUB_OAUTH_CLIENT_ID": "${input:github_oauth_client_id}",
-          "GITHUB_OAUTH_CLIENT_SECRET": "${input:github_oauth_client_secret}",
-          "GITHUB_OAUTH_CALLBACK_PORT": "8080"
-        }
-      }
-    }
-  }
-}
-```
-
-Port binding setup is straightforward and can be automated through installation instructions.
-
-#### 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)
+See [docs/oauth-authentication.md](docs/oauth-authentication.md) for full setup instructions, including how to create a GitHub OAuth App.
 
-> **Note**: OAuth authentication is only available in stdio mode. For remote server usage, use Personal Access Tokens as described above.
+> **Note**: OAuth is only available in stdio mode. For remote server usage, use Personal Access Tokens.
 
 ### GitHub Enterprise Server and Enterprise Cloud with data residency (ghe.com)