feat: implement optional OAuth 2.1 authentication with modular middleware and configuration

Author: nickytonline

.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 authentication (default: false)
+- `OAUTH_CLIENT_ID` - OAuth client ID (required if auth enabled)
+- `OAUTH_CLIENT_SECRET` - OAuth client secret (required if auth enabled)
+- `OAUTH_AUTH_ENDPOINT` - OAuth authorization endpoint (required if auth enabled)
+- `OAUTH_TOKEN_ENDPOINT` - OAuth token endpoint (required if auth enabled)
+- `OAUTH_SCOPE` - OAuth scope (default: "read")
+- `OAUTH_REDIRECT_URI` - OAuth redirect URI (required if auth enabled)
+
 ## Coding Guidelines
 
 - Follow existing patterns in the codebase
@@ -119,4 +131,30 @@ 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
+
+### Modular Authentication
+
+The template includes optional OAuth 2.1 authentication that can be easily enabled or completely removed:
+
+- **Modular Design**: All OAuth code is in `src/auth/` directory
+- **Conditional Loading**: OAuth middleware only applies when `ENABLE_AUTH=true`
+- **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`
+
+### Authentication Patterns
+
+1. **External OAuth (Recommended)**: Use Pomerium or similar OAuth proxy
+2. **Built-in OAuth Server**: Use the provided OAuth implementation in `src/auth/`
+
+### 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,18 @@
+# Server Configuration
+PORT=3000
+NODE_ENV=development
+SERVER_NAME=mcp-typescript-template
+SERVER_VERSION=1.0.0
+LOG_LEVEL=info
+
+# OAuth Configuration (Optional)
+# Set ENABLE_AUTH=true to enable OAuth authentication
+ENABLE_AUTH=false
+
+# Required if ENABLE_AUTH=true
+OAUTH_CLIENT_ID=your-client-id
+OAUTH_CLIENT_SECRET=your-client-secret
+OAUTH_AUTH_ENDPOINT=https://auth.example.com/oauth/authorize
+OAUTH_TOKEN_ENDPOINT=https://auth.example.com/oauth/token
+OAUTH_SCOPE=read
+OAUTH_REDIRECT_URI=http://localhost:3000/oauth/callback

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 authentication (default: false)
+- `OAUTH_CLIENT_ID` - OAuth client ID (required if auth enabled)
+- `OAUTH_CLIENT_SECRET` - OAuth client secret (required if auth enabled)
+- `OAUTH_AUTH_ENDPOINT` - OAuth authorization endpoint (required if auth enabled)
+- `OAUTH_TOKEN_ENDPOINT` - OAuth token endpoint (required if auth enabled)
+- `OAUTH_SCOPE` - OAuth scope (default: "read")
+- `OAUTH_REDIRECT_URI` - OAuth redirect URI (required if auth enabled)
+
 ## Logging Best Practices
 
 - Use appropriate log levels: `error`, `warn`, `info`, `debug`
@@ -108,4 +120,30 @@ 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
+
+### Modular Authentication
+
+The template includes optional OAuth 2.1 authentication that can be easily enabled or completely removed:
+
+- **Modular Design**: All OAuth code is in `src/auth/` directory
+- **Conditional Loading**: OAuth middleware only applies when `ENABLE_AUTH=true`
+- **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`
+
+### Authentication Patterns
+
+1. **External OAuth (Recommended)**: Use Pomerium or similar OAuth proxy
+2. **Built-in OAuth Server**: Use the provided OAuth implementation in `src/auth/`
+
+### 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.

README.md

@@ -12,6 +12,7 @@ This template provides:
 - **ESLint + Prettier** - Code quality and formatting
 - **Docker** - Containerization support
 - **Example Tool** - Simple echo tool to demonstrate MCP tool implementation
+- **OAuth 2.1 Compatible** - Optional OAuth implementation (can use Pomerium for external auth or built-in server implementation)
 
 ## Getting Started
 
@@ -184,6 +185,21 @@ server.registerTool(
 );
 ```
 
+## Authentication & Authorization
+
+### OAuth 2.1 Support
+
+This template supports **optional** OAuth 2.1 authentication with two approaches:
+
+1. **External OAuth (Recommended)** - Use Pomerium or similar OAuth proxy to handle authentication externally
+2. **Built-in OAuth Server** - Implement OAuth directly in the MCP server using the provided modular implementation
+
+The OAuth implementation is designed to be easily added or removed without affecting core server functionality.
+
+### Enabling OAuth
+
+To enable OAuth authentication, see the `src/auth/` directory for a modular OAuth implementation that can be toggled via environment variables.
+
 ## Why Express?
 
 This template uses Express for the HTTP server, which provides:

src/auth/index.ts

@@ -0,0 +1,42 @@
+import { OAuthProvider, OAuthConfig } from "./oauth-provider.js";
+import { createOAuthMiddleware, createOptionalOAuthMiddleware } from "./middleware.js";
+import { getConfig } from "../config.js";
+
+export { OAuthProvider, type OAuthConfig, type AuthenticatedRequest } from "./oauth-provider.js";
+export { createOAuthMiddleware, createOptionalOAuthMiddleware } from "./middleware.js";
+
+/**
+ * Initialize OAuth provider if authentication is enabled
+ */
+export function initializeAuth() {
+  const config = getConfig();
+  
+  if (!config.ENABLE_AUTH) {
+    return null;
+  }
+
+  const oauthConfig: OAuthConfig = {
+    clientId: config.OAUTH_CLIENT_ID!,
+    clientSecret: config.OAUTH_CLIENT_SECRET!,
+    authorizationEndpoint: config.OAUTH_AUTH_ENDPOINT!,
+    tokenEndpoint: config.OAUTH_TOKEN_ENDPOINT!,
+    scope: config.OAUTH_SCOPE || "read",
+    redirectUri: config.OAUTH_REDIRECT_URI!,
+  };
+
+  return new OAuthProvider(oauthConfig);
+}
+
+/**
+ * Create authentication middleware based on configuration
+ */
+export function createAuthMiddleware() {
+  const oauthProvider = initializeAuth();
+  
+  if (!oauthProvider) {
+    // Return pass-through middleware when auth is disabled
+    return (_req: any, _res: any, next: any) => next();
+  }
+
+  return createOAuthMiddleware(oauthProvider);
+}

src/auth/middleware.ts

@@ -0,0 +1,81 @@
+import { Request, Response, NextFunction } from "express";
+import { OAuthProvider } from "./oauth-provider.js";
+import { logger } from "../logger.js";
+
+export interface AuthenticatedRequest extends Request {
+  userId?: string;
+  accessToken?: string;
+}
+
+/**
+ * Create OAuth middleware that can be easily added/removed
+ */
+export function createOAuthMiddleware(oauthProvider: OAuthProvider) {
+  return async (req: AuthenticatedRequest, res: Response, next: NextFunction) => {
+    const authHeader = req.headers.authorization;
+    
+    if (!authHeader || !authHeader.startsWith("Bearer ")) {
+      return res.status(401).json({
+        error: "unauthorized",
+        error_description: "Missing or invalid authorization header",
+      });
+    }
+
+    const token = authHeader.substring(7); // Remove "Bearer " prefix
+    
+    try {
+      const validation = await oauthProvider.validateToken(token);
+      
+      if (!validation.valid) {
+        return res.status(401).json({
+          error: "invalid_token",
+          error_description: "The access token is invalid or expired",
+        });
+      }
+
+      // Add user context to request
+      req.userId = validation.userId;
+      req.accessToken = token;
+      
+      logger.info("Request authenticated", { userId: validation.userId });
+      next();
+    } catch (error) {
+      logger.error("Authentication middleware error", { error: error.message });
+      return res.status(500).json({
+        error: "server_error",
+        error_description: "Internal server error during authentication",
+      });
+    }
+  };
+}
+
+/**
+ * Optional middleware that only authenticates if token is present
+ */
+export function createOptionalOAuthMiddleware(oauthProvider: OAuthProvider) {
+  return async (req: AuthenticatedRequest, res: Response, next: NextFunction) => {
+    const authHeader = req.headers.authorization;
+    
+    if (!authHeader || !authHeader.startsWith("Bearer ")) {
+      // No auth header, continue without authentication
+      return next();
+    }
+
+    const token = authHeader.substring(7);
+    
+    try {
+      const validation = await oauthProvider.validateToken(token);
+      
+      if (validation.valid) {
+        req.userId = validation.userId;
+        req.accessToken = token;
+        logger.info("Request authenticated", { userId: validation.userId });
+      }
+      
+      next();
+    } catch (error) {
+      logger.warn("Optional authentication failed", { error: error.message });
+      next(); // Continue without authentication
+    }
+  };
+}