feat(config): make OAuth callback port configurable (#39) (#48)

Port 8000 conflicts with common dev servers (Next.js, etc). Add a minimal
config.json with oauth_port setting, change the default to 8100, and
improve the port-conflict error message.

- Add Config struct, LoadConfig/WriteDefaultConfig to internal/config
- Extract resolveOAuthPort() with resolution order: env var → config.json → default
- Validate port range 1-65535 for both env var and config paths
- `gsuite-mcp init` now creates config.json with defaults
- `gsuite-mcp check` shows resolved OAuth port (with env override note)
- `gsuite-mcp help` shows config.json path and GSUITE_MCP_OAUTH_PORT env var
- Update README, INSTALLATION.md, and AGENTS.md documentation

Author: aliwatters

INSTALLATION.md

@@ -177,6 +177,7 @@ Claude should use gsuite-mcp to fetch your real data.
 | `403: SERVICE_DISABLED` | API not enabled in GCP project | Run `gsuite-mcp check` for enable links |
 | `invalid_grant` | Token expired or revoked | Run `gsuite-mcp auth` |
 | `401: invalid_client` | Wrong or corrupted client_secret.json | Re-download from GCP Console |
+| `port XXXX is in use` | OAuth callback port conflict | Set `oauth_port` in config.json or `GSUITE_MCP_OAUTH_PORT` env var |
 
 ### Token Expired or Invalid Credentials
 
@@ -254,12 +255,23 @@ All configuration lives in `~/.config/gsuite-mcp/`:
 
 ```
 ~/.config/gsuite-mcp/
-├── client_secret.json      # Your OAuth app credentials
+├── client_secret.json            # Your OAuth app credentials
+├── config.json                   # Settings (optional — created by `gsuite-mcp init`)
 └── credentials/
     ├── alice@gmail.com.json      # Token for alice@gmail.com
     └── bob@company.com.json      # Token for bob@company.com
 ```
 
+### config.json
+
+Optional configuration file created by `gsuite-mcp init`. Settings:
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `oauth_port` | `8100` | Port for the OAuth callback server during `gsuite-mcp auth` |
+
+Override `oauth_port` via the `GSUITE_MCP_OAUTH_PORT` environment variable.
+
 ## Next Steps
 
 - Read the [README](README.md) for the full tool reference

README.md

@@ -280,11 +280,21 @@ See [INSTALLATION.md](INSTALLATION.md) for full setup instructions.
 ```
 ~/.config/gsuite-mcp/
 ├── client_secret.json      # Your OAuth app credentials
-├── config.json             # Account configuration (optional)
+├── config.json             # Settings (optional — created by `gsuite-mcp init`)
 └── credentials/
-    └── {label}.json        # Per-account tokens
+    └── {email}.json        # Per-account tokens
 ```
 
+### OAuth Callback Port
+
+The default OAuth callback port is **8100**. Override it in `config.json`:
+
+```json
+{ "oauth_port": 9000 }
+```
+
+Or via environment variable: `GSUITE_MCP_OAUTH_PORT=9000`
+
 ## Development
 
 ```bash

cmd/gsuite-mcp/check.go

@@ -45,6 +45,16 @@ func runCheck() {
 		fmt.Printf("  ✓ OAuth client ID (project: %s)\n", projectNumber)
 	}
 
+	port, envOverride, err := auth.ResolveOAuthPort()
+	if err != nil {
+		fmt.Printf("  ✗ OAuth port: %v\n", err)
+		issues++
+	} else if envOverride {
+		fmt.Printf("  ✓ OAuth port: %d (env override)\n", port)
+	} else {
+		fmt.Printf("  ✓ OAuth port: %d\n", port)
+	}
+
 	// Stage 2: Accounts
 	fmt.Println("\nChecking accounts...")
 

cmd/gsuite-mcp/main.go

@@ -104,21 +104,38 @@ When tools request an account without credentials, auth flow is triggered automa
 
 Configuration:
   Config dir:     %s
+  Config file:    %s
   Credentials:    %s
   Client secret:  %s
 
+Environment variables:
+  GSUITE_MCP_OAUTH_PORT   Override OAuth callback port (default: %d)
+
 For more information, see README.md
 `, serverName, serverName, serverName, serverName, serverName, serverName,
-		config.DefaultConfigDir(), config.CredentialsDir(), config.ClientSecretPath())
+		config.DefaultConfigDir(), config.ConfigPath(), config.CredentialsDir(), config.ClientSecretPath(),
+		config.DefaultOAuthPort)
 }
 
-// runInit ensures config directory exists and shows setup instructions.
+// runInit ensures config directory exists, creates default config, and shows setup instructions.
 func runInit() {
 	if err := config.EnsureConfigDir(); err != nil {
 		fmt.Fprintf(os.Stderr, "Error creating config directory: %v\n", err)
 		os.Exit(1)
 	}
 	fmt.Printf("Config directory ready: %s\n", config.DefaultConfigDir())
+
+	created, err := config.WriteDefaultConfig()
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Error creating config.json: %v\n", err)
+		os.Exit(1)
+	}
+	if created {
+		fmt.Printf("Created config.json:    %s\n", config.ConfigPath())
+	} else {
+		fmt.Printf("Config.json exists:     %s\n", config.ConfigPath())
+	}
+
 	fmt.Printf("\nSetup steps:\n")
 	fmt.Printf("1. Create OAuth credentials in Google Cloud Console\n")
 	fmt.Printf("2. Download and save as: %s\n", config.ClientSecretPath())

docs/AGENTS.md

@@ -58,10 +58,10 @@ gsuite-mcp/
 ### Configuration Files
 ```
 ~/.config/gsuite-mcp/
-├── config.json             # Account configuration
 ├── client_secret.json      # Google OAuth app credentials
+├── config.json             # Settings: oauth_port (optional — created by init)
 └── credentials/
-    └── {label}.json        # Per-account OAuth tokens
+    └── {email}.json        # Per-account OAuth tokens
 ```
 
 ## Key Rules

internal/auth/auth.go

@@ -17,6 +17,7 @@ import (
 	"os"
 	"os/exec"
 	"runtime"
+	"strconv"
 	"sync"
 	"time"
 
@@ -46,9 +47,6 @@ const (
 	// oauthCallbackTimeout is the maximum time to wait for OAuth flow completion.
 	oauthCallbackTimeout = 5 * time.Minute
 
-	// defaultOAuthPort is the default port for OAuth callback.
-	defaultOAuthPort = 8000
-
 	// oauthResultTimeout is the maximum time to wait for the main loop to process the result.
 	oauthResultTimeout = 10 * time.Second
 
@@ -185,20 +183,52 @@ func loadOAuthConfig() (*oauth2.Config, error) {
 	return cfg, nil
 }
 
+// resolveOAuthPort determines the OAuth callback port.
+// Resolution order: GSUITE_MCP_OAUTH_PORT env var → config.json → default (8100).
+func resolveOAuthPort() (int, error) {
+	if portStr := os.Getenv("GSUITE_MCP_OAUTH_PORT"); portStr != "" {
+		port, err := strconv.Atoi(portStr)
+		if err != nil || port < 1 || port > 65535 {
+			return 0, fmt.Errorf("invalid GSUITE_MCP_OAUTH_PORT value %q: must be 1-65535", portStr)
+		}
+		return port, nil
+	}
+
+	cfg, err := config.LoadConfig()
+	if err != nil {
+		return 0, err
+	}
+
+	if cfg.OAuthPort < 1 || cfg.OAuthPort > 65535 {
+		return 0, fmt.Errorf("invalid oauth_port %d in %s: must be 1-65535", cfg.OAuthPort, config.ConfigPath())
+	}
+
+	return cfg.OAuthPort, nil
+}
+
+// ResolveOAuthPort returns the resolved OAuth callback port and whether it was overridden by env var.
+func ResolveOAuthPort() (port int, envOverride bool, err error) {
+	if os.Getenv("GSUITE_MCP_OAUTH_PORT") != "" {
+		p, err := resolveOAuthPort()
+		return p, true, err
+	}
+	p, err := resolveOAuthPort()
+	return p, false, err
+}
+
 // AuthenticateDynamic performs OAuth2 flow without requiring a pre-configured account.
 // It opens the browser, lets the user choose any Google account, and saves the credential
 // using the authenticated email as the identifier. Returns the authenticated email.
 func (m *Manager) AuthenticateDynamic(ctx context.Context) (string, error) {
-	oauthPort := defaultOAuthPort
-	if portStr := os.Getenv("GSUITE_MCP_OAUTH_PORT"); portStr != "" {
-		if p, err := fmt.Sscanf(portStr, "%d", &oauthPort); err != nil || p != 1 {
-			return "", fmt.Errorf("invalid GSUITE_MCP_OAUTH_PORT value: %s", portStr)
-		}
+	oauthPort, err := resolveOAuthPort()
+	if err != nil {
+		return "", err
 	}
 
 	listener, err := net.Listen("tcp", fmt.Sprintf("localhost:%d", oauthPort))
 	if err != nil {
-		return "", fmt.Errorf("failed to listen on port %d: %w", oauthPort, err)
+		return "", fmt.Errorf("port %d is in use — set a different port in %s (oauth_port) or via GSUITE_MCP_OAUTH_PORT env var: %w",
+			oauthPort, config.ConfigPath(), err)
 	}
 	defer listener.Close()
 

internal/config/config.go

@@ -3,11 +3,85 @@
 package config
 
 import (
+	"encoding/json"
+	"fmt"
 	"os"
 	"path/filepath"
 	"sort"
 )
 
+// DefaultOAuthPort is the default port used for the OAuth callback server.
+const DefaultOAuthPort = 8100
+
+// Config holds the application configuration loaded from config.json.
+type Config struct {
+	OAuthPort int `json:"oauth_port"`
+}
+
+// ConfigPath returns the path to config.json.
+func ConfigPath() string {
+	return filepath.Join(DefaultConfigDir(), "config.json")
+}
+
+// LoadConfig loads config from the default config.json path.
+func LoadConfig() (Config, error) {
+	return loadConfigFromPath(ConfigPath())
+}
+
+// loadConfigFromPath loads config from the given path.
+// Returns default Config if the file doesn't exist (config.json is optional).
+func loadConfigFromPath(path string) (Config, error) {
+	cfg := Config{OAuthPort: DefaultOAuthPort}
+
+	data, err := os.ReadFile(path)
+	if err != nil {
+		if os.IsNotExist(err) {
+			return cfg, nil
+		}
+		return cfg, fmt.Errorf("reading config: %w", err)
+	}
+
+	var fileCfg Config
+	if err := json.Unmarshal(data, &fileCfg); err != nil {
+		return cfg, fmt.Errorf("parsing config.json: %w", err)
+	}
+
+	if fileCfg.OAuthPort == 0 {
+		fileCfg.OAuthPort = DefaultOAuthPort
+	}
+
+	return fileCfg, nil
+}
+
+// WriteDefaultConfig creates config.json with defaults if it doesn't already exist.
+// Returns true if the file was created, false if it already existed.
+func WriteDefaultConfig() (bool, error) {
+	return writeDefaultConfigTo(ConfigPath())
+}
+
+// writeDefaultConfigTo creates config.json at the given path with defaults.
+// Returns true if the file was created, false if it already existed.
+func writeDefaultConfigTo(path string) (bool, error) {
+	if _, err := os.Stat(path); err == nil {
+		return false, nil
+	} else if !os.IsNotExist(err) {
+		return false, fmt.Errorf("checking config.json: %w", err)
+	}
+
+	cfg := Config{OAuthPort: DefaultOAuthPort}
+	data, err := json.MarshalIndent(cfg, "", "  ")
+	if err != nil {
+		return false, fmt.Errorf("marshaling default config: %w", err)
+	}
+	data = append(data, '\n')
+
+	if err := os.WriteFile(path, data, 0644); err != nil {
+		return false, fmt.Errorf("writing config.json: %w", err)
+	}
+
+	return true, nil
+}
+
 // DefaultConfigDir returns the default configuration directory.
 func DefaultConfigDir() string {
 	home, err := os.UserHomeDir()