Add OAuth 2.1 authentication flow for MCP server

.dev.vars.example

@@ -0,0 +1,84 @@
+# Gravatar MCP Server - Development Secrets and Overrides
+# 
+# Copy this file to `.dev.vars` and fill in your actual values.
+# This file contains ONLY secrets and development-specific overrides.
+# All other configuration is defined in wrangler.jsonc for clarity.
+
+# =============================================================================
+# SECRETS (Not stored in wrangler.jsonc for security)
+# =============================================================================
+
+# Gravatar API Configuration (Optional)
+# Get your API key from: https://gravatar.com/developers/
+GRAVATAR_API_KEY="your-gravatar-api-key-here"
+
+# OAuth Client Secrets
+# Get your app secrets from: https://developer.wordpress.com/apps/
+OAUTH_CLIENT_ID=your-wordpress-app-client-id
+OAUTH_CLIENT_SECRET=your-wordpress-app-client-secret
+
+# OAuth Server Configuration Secrets
+# Generate random 32+ character strings for these:
+# You can use: openssl rand -hex 32
+OAUTH_SIGNING_SECRET=generate-a-random-32-plus-character-string-for-jwt-signing
+OAUTH_COOKIE_SECRET=generate-a-random-32-plus-character-string-for-cookie-encryption
+
+# =============================================================================
+# DEVELOPMENT-ONLY OVERRIDES (Optional)
+# =============================================================================
+
+# Debug Configuration
+# Set to 'true' to enable detailed MCP transport logging
+DEBUG=true
+
+# OAuth 2.1 Authentication Configuration
+# Set to 'true' to enable OAuth authentication for MCP endpoints
+OAUTH_ENABLED=true
+
+# OAuth Server Configuration (Development URLs)
+# These should match your local development setup
+OAUTH_ISSUER_URL=http://localhost:8787/mcp
+OAUTH_BASE_URL=http://localhost:8787/mcp
+
+# =============================================================================
+# OPTIONAL DEVELOPMENT OVERRIDES
+# Uncomment to override wrangler.jsonc defaults for local testing
+# =============================================================================
+
+# DNS Rebinding Protection Configuration
+# ENABLE_DNS_REBINDING_PROTECTION=true
+# ALLOWED_HOSTS=localhost:8787,127.0.0.1:8787
+# ALLOWED_ORIGINS=http://localhost:8787,http://127.0.0.1:8787,http://localhost:6274
+
+# OAuth Service Documentation
+# OAUTH_SERVICE_DOCS_URL=https://docs.yourapp.com/oauth
+
+# =============================================================================
+# SETUP INSTRUCTIONS
+# =============================================================================
+#
+# 1. Copy this file to `.dev.vars`:
+#    cp .dev.vars.example .dev.vars
+#
+# 2. Get a Gravatar API key (optional):
+#    - Visit https://gravatar.com/developers/
+#    - Create an application and copy the API key
+#    - Replace "your-gravatar-api-key-here" above
+#
+# 3. Create a WordPress.com OAuth app:
+#    - Visit https://developer.wordpress.com/apps/
+#    - Create a new application
+#    - Set redirect URI to: http://localhost:8787/callback
+#    - Copy the Client ID and Client Secret
+#    - Replace the OAUTH_CLIENT_ID and OAUTH_CLIENT_SECRET above
+#
+# 4. Generate random secrets:
+#    - Run: openssl rand -hex 32
+#    - Use the output for OAUTH_SIGNING_SECRET and OAUTH_COOKIE_SECRET
+#    - Make sure each secret is unique
+#
+# 5. Test your setup:
+#    - Run: npm run dev
+#    - Visit: http://localhost:8787
+#    - Try the OAuth authentication flow
+#

.gitignore

@@ -179,3 +179,6 @@ dist
 # Client
 .clinerules/
 memory-bank/
+
+# MCP
+.mcp.json

CLAUDE.md

@@ -367,19 +367,47 @@ export default {
 };
 ```
 
-## API Key Configuration
+## Development Setup
 
-The server supports optional Gravatar API key configuration:
+### Environment Configuration
 
-### Production
-```bash
-npx wrangler secret put GRAVATAR_API_KEY
-```
+The server requires environment variables for secrets and configuration:
 
-### Development
-Create `.dev.vars`:
+1. **Copy the example file:**
+   ```bash
+   cp .dev.vars.example .dev.vars
+   ```
+
+2. **Fill in your values:**
+   - Get a Gravatar API key from https://gravatar.com/developers/
+   - Create a WordPress.com OAuth app at https://developer.wordpress.com/apps/
+   - Generate random secrets for JWT signing and cookie encryption
+   - See `.dev.vars.example` for detailed setup instructions
+
+### Configuration Architecture
+
+- **`wrangler.jsonc`** - Contains all explicit configuration for each environment
+- **`.dev.vars`** - Contains only secrets and development-specific overrides
+- **`.dev.vars.example`** - Template file with setup instructions
+
+### Production Deployment
+
+Set secrets for each environment using Wrangler:
+
+**For staging:**
 ```bash
-GRAVATAR_API_KEY=your-api-key-here
+npx wrangler secret put GRAVATAR_API_KEY --env staging
+npx wrangler secret put OAUTH_CLIENT_ID --env staging
+npx wrangler secret put OAUTH_CLIENT_SECRET --env staging
+npx wrangler secret put OAUTH_SIGNING_SECRET --env staging
+npx wrangler secret put OAUTH_COOKIE_SECRET --env staging
 ```
 
-The API key enables access to additional profile fields and authenticated endpoints.
+**For production:**
+```bash
+npx wrangler secret put GRAVATAR_API_KEY --env production
+npx wrangler secret put OAUTH_CLIENT_ID --env production
+npx wrangler secret put OAUTH_CLIENT_SECRET --env production
+npx wrangler secret put OAUTH_SIGNING_SECRET --env production
+npx wrangler secret put OAUTH_COOKIE_SECRET --env production
+```

README.md

@@ -222,30 +222,52 @@ When using email-based tools, you can provide any valid email format. The system
 2. Generate the appropriate hash for API requests
 3. Process the email securely without storing it
 
-## API Key Configuration (Optional)
+## Configuration
 
-The server works without authentication, but you can optionally configure a Gravatar API key to access additional profile fields.
+### Development Setup
 
-### For Production Deployment
+The server requires environment variables for secrets and OAuth configuration:
 
-Set the API key as a Cloudflare Workers secret:
+1. **Copy the example file:**
+   ```bash
+   cp .dev.vars.example .dev.vars
+   ```
 
-```bash
-npx wrangler secret put GRAVATAR_API_KEY
-```
+2. **Fill in your values:**
+   - Get a Gravatar API key from https://gravatar.com/developers/ (optional)
+   - Create a WordPress.com OAuth app at https://developer.wordpress.com/apps/
+   - Generate random secrets for JWT signing and cookie encryption
+   - See `.dev.vars.example` for detailed setup instructions
+
+### Configuration Architecture
 
-When prompted, enter your Gravatar API key. The key will be securely stored and automatically used by the deployed server.
+- **`wrangler.jsonc`** - Contains all explicit configuration for each environment
+- **`.dev.vars`** - Contains only secrets and development-specific overrides  
+- **`.dev.vars.example`** - Template file with setup instructions (safe to commit)
 
-### For Local Development
+### Production Deployment
 
-Create a `.dev.vars` file in the project root:
+Set secrets for each environment using Wrangler:
+
+**For staging:**
+```bash
+npx wrangler secret put GRAVATAR_API_KEY --env staging
+npx wrangler secret put OAUTH_CLIENT_ID --env staging
+npx wrangler secret put OAUTH_CLIENT_SECRET --env staging
+npx wrangler secret put OAUTH_SIGNING_SECRET --env staging
+npx wrangler secret put OAUTH_COOKIE_SECRET --env staging
+```
 
+**For production:**
 ```bash
-# .dev.vars
-GRAVATAR_API_KEY=your-api-key-here
+npx wrangler secret put GRAVATAR_API_KEY --env production
+npx wrangler secret put OAUTH_CLIENT_ID --env production
+npx wrangler secret put OAUTH_CLIENT_SECRET --env production
+npx wrangler secret put OAUTH_SIGNING_SECRET --env production
+npx wrangler secret put OAUTH_COOKIE_SECRET --env production
 ```
 
-This file is automatically loaded during local development and should not be committed to version control (it's already in `.gitignore`).
+The server works without the Gravatar API key, but configuring it enables access to additional profile fields.
 
 ## Development