feat: Add OAuth

.cursorrules

@@ -36,9 +36,11 @@ This is a TypeScript template for building Model Context Protocol (MCP) servers.
   - Defines all available MCP tools with their JSON schemas
   - Routes tool calls to registered tool handlers
   - Handles error responses in MCP format
+  - Conditionally applies OAuth middleware based on configuration
 - **`src/config.ts`** - Environment configuration with validation using Zod
 - **`src/logger.ts`** - Structured logging with Pino (OpenTelemetry compatible)
 - **`src/lib/utils.ts`** - Utility functions for MCP response formatting
+- **`src/auth/`** - Optional OAuth 2.1 authentication module (can be completely removed)
 
 ### Template MCP Tools Available
 
@@ -101,6 +103,16 @@ The following environment variables are supported (see `src/config.ts`):
 - `SERVER_VERSION` - Server version (default: 1.0.0)
 - `LOG_LEVEL` - Logging level (error/warn/info/debug, default: info)
 
+### OAuth Configuration (Optional)
+
+- `ENABLE_AUTH` - Enable OAuth 2.1 authentication (default: false)
+- `OAUTH_ISSUER` - OAuth issuer URL (required if auth enabled)
+- `OAUTH_CLIENT_ID` - OAuth client ID (required if auth enabled)
+- `OAUTH_CLIENT_SECRET` - OAuth client secret (required if auth enabled)
+- `OAUTH_AUDIENCE` - Expected audience in JWT tokens (optional but recommended)
+- `OAUTH_SCOPE` - OAuth scope (default: "openid profile email")
+- `OAUTH_REDIRECT_URI` - OAuth redirect URI (optional, defaults to BASE_URL/callback)
+
 ## Coding Guidelines
 
 - Follow existing patterns in the codebase
@@ -119,4 +131,49 @@ The following environment variables are supported (see `src/config.ts`):
 - Include relevant context in log messages (user IDs, session IDs, etc.)
 - Log structured data as the second parameter: `logger.info("message", { key: value })`
 - Error logs should include error details: `logger.error("Error message", { error: error.message })`
-- The logger automatically includes trace correlation when OpenTelemetry is configured
+- The logger automatically includes trace correlation when OpenTelemetry is configured
+
+## OAuth Implementation
+
+### Simple Binary Configuration
+
+The template includes optional OAuth 2.1 authentication with a simple on/off approach:
+
+- **Default**: No authentication required - server runs immediately with `ENABLE_AUTH=false`
+- **Enable When Needed**: Set `ENABLE_AUTH=true` and provide OAuth configuration
+- **Modular Design**: All OAuth code is in `src/auth/` directory
+- **Zero Impact When Disabled**: No performance overhead when authentication is disabled
+- **Easy Removal**: Delete `src/auth/` directory and remove auth import from `src/index.ts`
+
+### Use Cases
+
+**Authentication Disabled** (`ENABLE_AUTH=false` or omitted):
+- Public MCP servers
+- Gateway-protected deployments (Pomerium, nginx with auth, etc.)
+- Development and testing
+- Internal corporate networks with perimeter security
+
+**Authentication Enabled** (`ENABLE_AUTH=true`):
+- Direct OAuth 2.1 with token validation
+- Self-contained secure deployment
+- Production servers without gateway infrastructure
+
+### Quick Setup
+
+To enable authentication, add to your `.env`:
+```bash
+ENABLE_AUTH=true
+OAUTH_ISSUER=https://your-provider.com
+OAUTH_CLIENT_ID=your-client-id
+OAUTH_CLIENT_SECRET=your-client-secret
+```
+
+### Removing OAuth
+
+To completely remove OAuth support:
+
+1. Delete the `src/auth/` directory
+2. Remove the auth import and middleware lines from `src/index.ts`  
+3. Remove OAuth environment variables from `src/config.ts`
+
+The core MCP server functionality is completely independent of the authentication layer.

.env.example

@@ -0,0 +1,66 @@
+# Server Configuration
+PORT=3000
+NODE_ENV=development
+SERVER_NAME=mcp-typescript-template
+SERVER_VERSION=1.0.0
+LOG_LEVEL=info
+
+# Base URL for the server (used for OAuth redirects and discovery endpoints)
+# Defaults to http://localhost:PORT if not set (where PORT is the configured port)
+# BASE_URL=http://localhost:3000
+
+# ============================================================================
+# Authentication Configuration (Optional)
+# ============================================================================
+# Default: No authentication required - server runs immediately
+# Enable when you need OAuth 2.1 authentication with token validation
+# ENABLE_AUTH=false
+
+# When ENABLE_AUTH=true, configure your OAuth provider:
+# ENABLE_AUTH=true
+# OAUTH_ISSUER=https://your-provider.com
+# OAUTH_CLIENT_ID=your-client-id
+# OAUTH_CLIENT_SECRET=your-client-secret
+
+# Additional OAuth settings (optional)
+# OAUTH_AUDIENCE=your-api-identifier  # For token audience validation
+# OAUTH_SCOPE=openid profile email    # Default scope
+# OAUTH_REDIRECT_URI=http://localhost:3000/callback  # Defaults to BASE_URL/callback
+
+# ============================================================================
+# Common OAuth Provider Examples
+# ============================================================================
+
+# Auth0 Example:
+# ENABLE_AUTH=true
+# OAUTH_ISSUER=https://your-domain.auth0.com
+# OAUTH_CLIENT_ID=your-auth0-client-id
+# OAUTH_CLIENT_SECRET=your-auth0-client-secret
+# OAUTH_AUDIENCE=your-api-identifier
+
+# Okta Example:
+# ENABLE_AUTH=true
+# OAUTH_ISSUER=https://your-domain.okta.com
+# OAUTH_CLIENT_ID=your-okta-client-id
+# OAUTH_CLIENT_SECRET=your-okta-client-secret
+
+# Google Example:
+# ENABLE_AUTH=true
+# OAUTH_ISSUER=https://accounts.google.com
+# OAUTH_CLIENT_ID=your-google-client-id.apps.googleusercontent.com
+# OAUTH_CLIENT_SECRET=your-google-client-secret
+
+# ============================================================================
+# Use Cases
+# ============================================================================
+# 
+# Auth Disabled (ENABLE_AUTH=false or omitted):
+# - Public MCP servers
+# - Gateway-protected deployments (Pomerium, nginx with auth, etc.)
+# - Development and testing
+# - Internal corporate networks with perimeter security
+#
+# Auth Enabled (ENABLE_AUTH=true):
+# - Direct OAuth 2.1 with token validation
+# - Self-contained secure deployment
+# - Production servers without gateway infrastructure

.github/copilot-instructions.md

@@ -74,6 +74,16 @@ See `src/config.ts` for all supported environment variables:
 - `SERVER_VERSION` - Server version
 - `LOG_LEVEL` - Logging level (error/warn/info/debug)
 
+### OAuth Configuration (Optional)
+
+- `ENABLE_AUTH` - Enable OAuth 2.1 authentication (default: false)
+- `OAUTH_ISSUER` - OAuth issuer URL (required if auth enabled)
+- `OAUTH_CLIENT_ID` - OAuth client ID (required if auth enabled)
+- `OAUTH_CLIENT_SECRET` - OAuth client secret (required if auth enabled)
+- `OAUTH_AUDIENCE` - Expected audience in JWT tokens (optional but recommended)
+- `OAUTH_SCOPE` - OAuth scope (default: "openid profile email")
+- `OAUTH_REDIRECT_URI` - OAuth redirect URI (optional, defaults to BASE_URL/callback)
+
 ## Common Patterns
 
 ### Adding a New MCP Tool
@@ -134,9 +144,30 @@ const port = config.PORT;
 const serverName = config.SERVER_NAME;
 ```
 
+## Authentication
+
+### Simple Binary Configuration
+
+The template includes optional OAuth 2.1 authentication:
+
+- **Default**: No authentication required (`ENABLE_AUTH=false`)
+- **Enable when needed**: Set `ENABLE_AUTH=true` and provide OAuth config
+- **Use cases**: Public servers (auth disabled) or secure deployments (auth enabled)
+
+### Quick Setup
+
+To enable authentication, add to `.env`:
+```bash
+ENABLE_AUTH=true
+OAUTH_ISSUER=https://your-provider.com
+OAUTH_CLIENT_ID=your-client-id
+OAUTH_CLIENT_SECRET=your-client-secret
+```
+
 ## Important Notes
 
 - **File extensions**: Use `.js` in import statements (TypeScript compilation requirement)
 - **OpenTelemetry ready**: Logger automatically correlates with OTel traces when configured
 - **Production ready**: Includes graceful shutdown, error handling, and structured logging
-- **Template usage**: This is a template - customize for your specific MCP server needs
+- **Template usage**: This is a template - customize for your specific MCP server needs
+- **Authentication**: Server starts immediately with no auth setup required, add OAuth when needed

.gitignore

@@ -140,3 +140,6 @@ vite.config.ts.timestamp-*
 
 # Claude Code local settings
 .claude/
+
+# macOS metadata
+.DS_Store

CLAUDE.md

@@ -32,9 +32,11 @@ This is a TypeScript template for building Model Context Protocol (MCP) servers.
   - Defines all available MCP tools with their JSON schemas
   - Routes tool calls to registered tool handlers
   - Handles error responses in MCP format
+  - Conditionally applies OAuth middleware based on configuration
 - **`src/config.ts`** - Environment configuration with validation using Zod
 - **`src/logger.ts`** - Structured logging with Pino (OpenTelemetry compatible)
 - **`src/lib/utils.ts`** - Utility functions for MCP response formatting
+- **`src/auth/`** - Optional OAuth 2.1 authentication module (can be completely removed)
 
 ### Template MCP Tools Available
 
@@ -89,6 +91,16 @@ The following environment variables are supported (see `src/config.ts`):
 - `SERVER_VERSION` - Server version (default: 1.0.0)
 - `LOG_LEVEL` - Logging level (error/warn/info/debug, default: info)
 
+### OAuth Configuration (Optional)
+
+- `ENABLE_AUTH` - Enable OAuth 2.1 authentication (default: false)
+- `OAUTH_ISSUER` - OAuth issuer URL (required if auth enabled)
+- `OAUTH_CLIENT_ID` - OAuth client ID (required if auth enabled)
+- `OAUTH_CLIENT_SECRET` - OAuth client secret (required if auth enabled)
+- `OAUTH_AUDIENCE` - Expected audience in JWT tokens (optional but recommended)
+- `OAUTH_SCOPE` - OAuth scope (default: "openid profile email")
+- `OAUTH_REDIRECT_URI` - OAuth redirect URI (optional, defaults to BASE_URL/callback)
+
 ## Logging Best Practices
 
 - Use appropriate log levels: `error`, `warn`, `info`, `debug`
@@ -108,4 +120,39 @@ When adding new tools to the MCP server:
 4. Return responses in MCP content format with JSON stringified data
 5. Handle errors gracefully and return appropriate error messages
 6. Use structured logging to track tool usage: `logger.info("Tool executed", { toolName, args })`
-7. Log errors with context: `logger.error("Tool execution failed", { toolName, error: error.message })`
+7. Log errors with context: `logger.error("Tool execution failed", { toolName, error: error.message })`
+
+## OAuth Implementation
+
+### Simple Binary Configuration
+
+The template includes optional OAuth 2.1 authentication with a simple on/off approach:
+
+- **Default**: No authentication required - server runs immediately
+- **Enable When Needed**: Set `ENABLE_AUTH=true` and provide OAuth config
+- **Modular Design**: All OAuth code is in `src/auth/` directory
+- **Zero Impact When Disabled**: No performance overhead when authentication is disabled
+- **Easy Removal**: Delete `src/auth/` directory and remove auth import from `src/index.ts`
+
+### Use Cases
+
+**Authentication Disabled** (`ENABLE_AUTH=false` or omitted):
+- Public MCP servers
+- Gateway-protected deployments (Pomerium, nginx with auth, etc.)
+- Development and testing
+- Internal corporate networks with perimeter security
+
+**Authentication Enabled** (`ENABLE_AUTH=true`):
+- Direct OAuth 2.1 with token validation
+- Self-contained secure deployment
+- Production servers without gateway infrastructure
+
+### Removing OAuth
+
+To completely remove OAuth support:
+
+1. Delete the `src/auth/` directory
+2. Remove the auth import and middleware lines from `src/index.ts`  
+3. Remove OAuth environment variables from `src/config.ts`
+
+The core MCP server functionality is completely independent of the authentication layer.