docs: add multi-provider OAuth support and flexible storage options

- Add support and documentation for multiple OAuth providers: GitHub, GitLab, and Gitea
- Introduce flexible storage options with both in-memory and Redis-backed persistence
- Update instructions and examples to use the new oauth-server and oauth-client structure
- Expand setup and usage sections with detailed steps for both development (memory store) and production (Redis store) environments
- Add command-line flag documentation for server configuration, including new provider and storage options
- Provide new curl examples for client registration and resource metadata endpoints
- Clarify and generalize references to OAuth tokens instead of GitHub-specific tokens
- Add links to additional documentation and relevant external resources

Signed-off-by: Bo-Yi Wu <appleboy.tw@gmail.com>

Author: appleboy

03-oauth-mcp/README.md

@@ -1,6 +1,8 @@
 # OAuth MCP Server
 
-This project demonstrates an OAuth 2.0 protected [Model Context Protocol (MCP)](https://github.com/mark3labs/mcp-go) server written in Go. It integrates with GitHub as the OAuth provider and showcases authenticated MCP tool execution with token context propagation.
+This project demonstrates an OAuth 2.0 protected [Model Context Protocol (MCP)](https://github.com/mark3labs/mcp-go) server written in Go. It supports multiple OAuth providers (GitHub, GitLab, Gitea) and showcases authenticated MCP tool execution with token context propagation.
+
+The implementation includes both an OAuth authorization server (`oauth-server/`) and an example OAuth client (`oauth-client/`), demonstrating the complete OAuth 2.0 flow with PKCE support and flexible storage options.
 
 ---
 
@@ -9,6 +11,7 @@ This project demonstrates an OAuth 2.0 protected [Model Context Protocol (MCP)](
 The server provides:
 
 - **Multi-Provider OAuth Integration**: Supports GitHub, GitLab, and Gitea as OAuth 2.0 providers for user authentication
+- **Flexible Storage Backends**: Choose between in-memory or Redis-backed storage for OAuth data persistence
 - **MCP Server with Authentication**: Requires valid OAuth tokens for all MCP endpoint access
 - **Context-based Token Propagation**: Injects and propagates authentication tokens through Go's `context.Context`
 - **Two Authenticated MCP Tools**:
@@ -169,64 +172,92 @@ flowchart TD
 1. Change to the server directory:
 
    ```bash
-   cd 03-oauth-mcp/server
+   cd 03-oauth-mcp/oauth-server
    ```
 
 2. Start the server with your OAuth credentials:
 
-   **GitHub (default):**
+   **GitHub (default with memory store):**
+
+   ```bash
+   go run . -client_id="your-github-client-id" -client_secret="your-github-client-secret"
+   ```
+
+   **GitHub with Redis store:**
 
    ```bash
-   go run server.go -client_id="your-github-client-id" -client_secret="your-github-client-secret"
+   # Start Redis first
+   docker run -d -p 6379:6379 redis:alpine
+
+   # Run server with Redis
+   go run . -client_id="your-id" -client_secret="your-secret" -store redis -redis-addr localhost:6379
    ```
 
    **GitLab.com:**
 
    ```bash
-   go run server.go -provider="gitlab" -client_id="your-gitlab-client-id" -client_secret="your-gitlab-client-secret"
+   go run . -provider="gitlab" -client_id="your-gitlab-client-id" -client_secret="your-gitlab-client-secret"
    ```
 
    **Self-hosted GitLab:**
 
    ```bash
-   go run server.go -provider="gitlab" -gitlab-host="https://gitlab.example.com" -client_id="your-client-id" -client_secret="your-client-secret"
+   go run . -provider="gitlab" -gitlab-host="https://gitlab.example.com" -client_id="your-client-id" -client_secret="your-client-secret"
    ```
 
    **Gitea:**
 
    ```bash
-   go run server.go -provider="gitea" -gitea-host="https://gitea.example.com" -client_id="your-client-id" -client_secret="your-client-secret"
+   go run . -provider="gitea" -gitea-host="https://gitea.example.com" -client_id="your-client-id" -client_secret="your-client-secret"
    ```
 
-3. Optional: Specify a different port:
+3. Optional flags:
 
    ```bash
-   go run server.go -provider="gitlab" -client_id="your-id" -client_secret="your-secret" -addr=":8095"
+   go run . -client_id="your-id" -client_secret="your-secret" \
+     -addr=":8095" \
+     -log-level="INFO" \
+     -store="redis" \
+     -redis-addr="localhost:6379" \
+     -redis-password="mypassword" \
+     -redis-db=1
    ```
 
 ### Server Endpoints
 
-| Endpoint | Method | Description | Auth Required |
-|----------|--------|-------------|---------------|
-| `/mcp` | POST/GET/DELETE | MCP protocol endpoint | ✅ Bearer token |
-| `/.well-known/oauth-protected-resource` | GET | Resource metadata | ❌ |
-| `/.well-known/oauth-authorization-server` | GET | OAuth server metadata | ❌ |
-| `/authorize` | GET | OAuth authorization (redirects to provider) | ❌ |
-| `/token` | POST | Token exchange with OAuth provider | ❌ |
-| `/register` | POST | Dynamic client registration | ❌ |
+| Endpoint                                  | Method          | Description                                 | Auth Required   |
+| ----------------------------------------- | --------------- | ------------------------------------------- | --------------- |
+| `/mcp`                                    | POST/GET/DELETE | MCP protocol endpoint                       | ✅ Bearer token |
+| `/.well-known/oauth-protected-resource`   | GET             | Resource metadata                           | ❌              |
+| `/.well-known/oauth-authorization-server` | GET             | OAuth server metadata                       | ❌              |
+| `/authorize`                              | GET             | OAuth authorization (redirects to provider) | ❌              |
+| `/token`                                  | POST            | Token exchange with OAuth provider          | ❌              |
+| `/register`                               | POST            | Dynamic client registration                 | ❌              |
 
 ### Testing with curl
 
 ```bash
 # Get OAuth metadata
 curl http://localhost:8095/.well-known/oauth-authorization-server
 
+# Get protected resource metadata
+curl http://localhost:8095/.well-known/oauth-protected-resource
+
+# Register a client
+curl -X POST http://localhost:8095/register \
+  -H "Content-Type: application/json" \
+  -d '{
+    "redirect_uris": ["http://localhost:8085/oauth/callback"],
+    "grant_types": ["authorization_code"],
+    "response_types": ["code"]
+  }'
+
 # Try MCP without token (should get 401)
 curl -X POST http://localhost:8095/mcp
 
 # Test with valid token (after OAuth flow)
 curl -X POST http://localhost:8095/mcp \
-  -H "Authorization: Bearer your-github-token" \
+  -H "Authorization: Bearer your-oauth-token" \
   -H "Content-Type: application/json"
 ```
 
@@ -237,19 +268,31 @@ curl -X POST http://localhost:8095/mcp \
 ### Key Components
 
 - **`MCPServer`**: Wraps the mark3labs/mcp-go server with OAuth authentication
-- **`GitHubProvider`**: Implements GitHub OAuth 2.0 integration with proper error handling
+- **OAuth Providers**:
+  - `GitHubProvider`: GitHub OAuth 2.0 integration
+  - `GitLabProvider`: GitLab OAuth 2.0 integration with self-hosted support
+  - `GiteaProvider`: Gitea OAuth 2.0 integration with self-hosted support
+- **Storage Layer**:
+  - `store.MemoryStore`: In-memory storage for development
+  - `store.RedisStore`: Redis-backed persistent storage for production
+  - Factory pattern for easy store creation
 - **`authMiddleware`**: Gin middleware that enforces Authorization header requirements
 - **Context Injection**: Uses `core.AuthFromRequest` to propagate tokens through request context
 
 ### File Structure
 
 ```txt
 03-oauth-mcp/
-├── server/
+├── oauth-server/
 │   ├── server.go              # Main server with MCP and OAuth endpoints
 │   ├── oauth_provider.go      # OAuth provider interface definition
-│   └── provider_github.go     # GitHub OAuth implementation
-├── client/
+│   ├── provider_github.go     # GitHub OAuth implementation
+│   ├── provider_gitlab.go     # GitLab OAuth implementation
+│   ├── provider_gitea.go      # Gitea OAuth implementation
+│   ├── middleware.go          # Authentication middleware
+│   ├── auth_meta.go           # Client registration metadata
+│   └── README.md              # Server documentation
+├── oauth-client/
 │   ├── client.go              # OAuth MCP client example
 │   └── README.md              # Client documentation
 └── README.md                  # This file
@@ -262,29 +305,115 @@ curl -X POST http://localhost:8095/mcp \
 - **Token Masking**: Sensitive tokens are masked in logs and responses
 - **CORS Configuration**: Proper CORS headers for cross-origin requests
 - **Request Timeouts**: 30-second timeouts on all external HTTP requests
+- **Client Secret Validation**: Validates client credentials before token exchange
+- **Redirect URI Validation**: Ensures redirect URIs match registered URIs
+
+### Storage Options
+
+#### Memory Store
+
+- **Pros**: No external dependencies, fast, simple setup
+- **Cons**: Data lost on restart, not suitable for production with multiple instances
+- **Use case**: Development and testing
+
+#### Redis Store
+
+- **Pros**: Persistent storage, production-ready, supports multiple server instances
+- **Cons**: Requires Redis server
+- **Use case**: Production deployments
+
+See [oauth-server/README.md](oauth-server/README.md) for detailed storage configuration.
 
 ---
 
 ## Testing the Complete Flow
 
-1. **Start the server** with your GitHub OAuth credentials
-2. **Run the client** - it will open your browser to GitHub
-3. **Authorize the application** in GitHub
+1. **Start the server** with your OAuth credentials:
+
+   ```bash
+   cd 03-oauth-mcp/oauth-server
+   go run . -client_id="your-id" -client_secret="your-secret"
+   ```
+
+2. **Run the client** in a separate terminal:
+
+   ```bash
+   cd 03-oauth-mcp/oauth-client
+   go run .
+   ```
+
+3. **Authorize the application** - the client will open your browser to the OAuth provider
 4. **Observe the logs** showing successful token exchange and user info fetch
-5. **See MCP tools execute** with the authenticated GitHub token
+5. **See MCP tools execute** with the authenticated token
+
+### Testing with Different Configurations
+
+**Development setup (memory store):**
+
+```bash
+# Terminal 1: Server
+cd 03-oauth-mcp/oauth-server
+go run . -client_id=<id> -client_secret=<secret>
+
+# Terminal 2: Client
+cd 03-oauth-mcp/oauth-client
+go run .
+```
+
+**Production setup (Redis store):**
+
+```bash
+# Terminal 1: Redis
+docker run -d -p 6379:6379 redis:alpine
+
+# Terminal 2: Server
+cd 03-oauth-mcp/oauth-server
+go run . -client_id=<id> -client_secret=<secret> -store redis -log-level INFO
+
+# Terminal 3: Client
+cd 03-oauth-mcp/oauth-client
+go run .
+```
 
 ---
 
 ## See Also
 
-For detailed OAuth MCP Client implementation, features, and usage examples, see [`client/README.md`](client/README.md).
+- [OAuth Server Documentation](oauth-server/README.md) - Detailed server configuration and storage options
+- [OAuth Client Documentation](oauth-client/README.md) - Complete client implementation guide
+- [Store Package](../pkg/store/README.md) - Storage layer implementation details
+
+---
+
+## Command-Line Flags
+
+### Required Flags
+
+- `-client_id`: OAuth 2.0 Client ID from your provider
+- `-client_secret`: OAuth 2.0 Client Secret from your provider
+
+### Optional Flags
+
+- `-addr`: Server address (default: `:8095`)
+- `-provider`: OAuth provider - `github`, `gitlab`, or `gitea` (default: `github`)
+- `-gitea-host`: Gitea host URL (default: `https://gitea.com`)
+- `-gitlab-host`: GitLab host URL (default: `https://gitlab.com`)
+- `-log-level`: Log level - `DEBUG`, `INFO`, `WARN`, `ERROR` (default: `DEBUG`)
+- `-store`: Storage type - `memory` or `redis` (default: `memory`)
+- `-redis-addr`: Redis address (default: `localhost:6379`)
+- `-redis-password`: Redis password (optional)
+- `-redis-db`: Redis database number (default: `0`)
 
 ---
 
 ## References
 
 - [MCP Documentation](https://mark3.ai/docs/mcp/)
 - [OAuth 2.0 RFC6749](https://datatracker.ietf.org/doc/html/rfc6749)
+- [PKCE RFC7636](https://datatracker.ietf.org/doc/html/rfc7636)
 - [GitHub OAuth Apps](https://docs.github.com/en/apps/oauth-apps)
+- [GitLab OAuth Documentation](https://docs.gitlab.com/ee/api/oauth2.html)
+- [Gitea OAuth Documentation](https://docs.gitea.io/en-us/oauth2-provider/)
 - [mark3labs/mcp-go](https://github.com/mark3labs/mcp-go)
 - [Gin Web Framework](https://gin-gonic.com/)
+- [Redis](https://redis.io/)