Merge pull request #8 from pvliesdonk/copilot/add-authentication-feature

pvliesdonk · web-flow · commit 7c5a330d2908 · 2025-11-01T09:05:33.000+01:00
Add configurable authentication and transport modes to FastMCP server
diff --git a/README.md b/README.md
@@ -79,20 +79,121 @@ Configuration is managed through environment variables with the `MCP_` prefix:
 | `MCP_DOCKER_HOST` | (auto-detect) | Docker daemon host URL |
 | `MCP_LOG_LEVEL` | `INFO` | Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL) |
 | `MCP_LOG_FORMAT` | `json` | Log format (json or text) |
-| `MCP_HOST` | `0.0.0.0` | Server host to bind to |
-| `MCP_PORT` | `8000` | Server port to bind to |
+| `MCP_HOST` | `0.0.0.0` | Server host to bind to (for HTTP-based transports) |
+| `MCP_PORT` | `8000` | Server port to bind to (for HTTP-based transports) |
 | `MCP_DEFAULT_IMAGE_ALIAS` | `python:3.11-slim` | Default image for warm container pool |
 | `MCP_WARM_POOL_ENABLED` | `true` | Enable warm container pool for fast attach |
 | `MCP_WARM_HEALTH_CHECK_INTERVAL` | `60` | Interval in seconds for warm container health checks |
 
+### Transport Configuration
+
+MCP DevBench supports multiple transport modes:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MCP_TRANSPORT_MODE` | `streamable-http` | Transport protocol: `stdio`, `sse`, or `streamable-http` |
+| `MCP_PATH` | `/mcp` | Path for HTTP-based transports (sse or streamable-http) |
+
+**Transport Modes:**
+- `stdio`: Standard input/output for local desktop clients (Claude Desktop, Cursor, etc.)
+- `sse`: Server-Sent Events (legacy HTTP transport, use streamable-http instead)
+- `streamable-http`: Recommended HTTP transport with full bidirectional streaming support
+
+### Authentication Configuration
+
+MCP DevBench supports multiple authentication modes for securing your server:
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `MCP_AUTH_MODE` | `none` | Authentication mode: `none`, `bearer`, `oauth`, or `oidc` |
+| `MCP_BEARER_TOKEN` | (none) | Bearer token for `bearer` authentication mode |
+| `MCP_OAUTH_CLIENT_ID` | (none) | OAuth/OIDC client ID |
+| `MCP_OAUTH_CLIENT_SECRET` | (none) | OAuth/OIDC client secret |
+| `MCP_OAUTH_CONFIG_URL` | (none) | OIDC provider configuration URL (e.g., `https://auth.example.com/.well-known/openid-configuration`) |
+| `MCP_OAUTH_BASE_URL` | (none) | Base URL of this server for OAuth callbacks |
+| `MCP_OAUTH_REDIRECT_PATH` | `/auth/callback` | OAuth callback redirect path |
+| `MCP_OAUTH_AUDIENCE` | (none) | OAuth audience parameter (required by some providers like Auth0) |
+| `MCP_OAUTH_REQUIRED_SCOPES` | (empty) | Comma-separated list of required OAuth scopes |
+
+**Authentication Modes:**
+
+1. **none** (default): No authentication required
+   ```bash
+   MCP_AUTH_MODE=none
+   ```
+
+2. **bearer**: Simple bearer token authentication for API keys and service accounts
+   ```bash
+   MCP_AUTH_MODE=bearer
+   MCP_BEARER_TOKEN=your-secret-token-here
+   ```
+
+3. **oidc**: OpenID Connect authentication with automatic provider discovery
+   ```bash
+   MCP_AUTH_MODE=oidc
+   MCP_OAUTH_CLIENT_ID=your-client-id
+   MCP_OAUTH_CLIENT_SECRET=your-client-secret
+   MCP_OAUTH_CONFIG_URL=https://your-provider.com/.well-known/openid-configuration
+   MCP_OAUTH_BASE_URL=https://your-server.com
+   MCP_OAUTH_REDIRECT_PATH=/auth/callback
+   # Optional:
+   MCP_OAUTH_AUDIENCE=https://api.your-server.com
+   MCP_OAUTH_REQUIRED_SCOPES=read,write,admin
+   ```
+
+4. **oauth**: Not directly supported - use `oidc` mode instead for OAuth providers with OIDC discovery support
+
+**OIDC Provider Examples:**
+
+- **Auth0**: Use `https://YOUR_DOMAIN.auth0.com/.well-known/openid-configuration`
+- **Google**: Use `https://accounts.google.com/.well-known/openid-configuration`
+- **Azure AD**: Use `https://login.microsoftonline.com/YOUR_TENANT_ID/v2.0/.well-known/openid-configuration`
+- **Keycloak**: Use `https://YOUR_KEYCLOAK_DOMAIN/realms/YOUR_REALM/.well-known/openid-configuration`
+
 ### Example .env file
+
+**Basic configuration (no auth, HTTP transport):**
 ```bash
 MCP_ALLOWED_REGISTRIES=docker.io,ghcr.io,registry.example.com
 MCP_STATE_DB=/data/state.db
 MCP_LOG_LEVEL=DEBUG
 MCP_LOG_FORMAT=json
 MCP_DEFAULT_IMAGE_ALIAS=python:3.11-slim
 MCP_WARM_POOL_ENABLED=true
+MCP_TRANSPORT_MODE=streamable-http
+MCP_HOST=0.0.0.0
+MCP_PORT=8000
+MCP_PATH=/mcp
+```
+
+**With bearer token authentication:**
+```bash
+MCP_TRANSPORT_MODE=streamable-http
+MCP_HOST=0.0.0.0
+MCP_PORT=8000
+MCP_AUTH_MODE=bearer
+MCP_BEARER_TOKEN=my-secret-api-key-12345
+```
+
+**With OIDC authentication (Auth0 example):**
+```bash
+MCP_TRANSPORT_MODE=streamable-http
+MCP_HOST=0.0.0.0
+MCP_PORT=8000
+MCP_AUTH_MODE=oidc
+MCP_OAUTH_CLIENT_ID=your-auth0-client-id
+MCP_OAUTH_CLIENT_SECRET=your-auth0-client-secret
+MCP_OAUTH_CONFIG_URL=https://your-tenant.auth0.com/.well-known/openid-configuration
+MCP_OAUTH_BASE_URL=https://your-mcp-server.com
+MCP_OAUTH_AUDIENCE=https://your-mcp-server.com/api
+MCP_OAUTH_REQUIRED_SCOPES=openid,profile,email
+```
+
+**STDIO transport for local use (e.g., Claude Desktop):**
+```bash
+MCP_TRANSPORT_MODE=stdio
+MCP_AUTH_MODE=none
+# Host and port are not used for stdio transport
 ```
 
 ## Development
diff --git a/src/mcp_devbench/auth.py b/src/mcp_devbench/auth.py
@@ -0,0 +1,87 @@
+"""Authentication provider factory for MCP DevBench."""
+
+from typing import Any
+
+from mcp_devbench.config import get_settings
+from mcp_devbench.utils import get_logger
+
+logger = get_logger(__name__)
+
+
+def create_auth_provider() -> Any | None:
+    """
+    Create authentication provider based on configuration.
+
+    Returns:
+        Authentication provider instance or None for no authentication
+    """
+    settings = get_settings()
+
+    if settings.auth_mode == "none":
+        logger.info("No authentication configured")
+        return None
+
+    if settings.auth_mode == "bearer":
+        if not settings.bearer_token:
+            raise ValueError("Bearer token authentication requires MCP_BEARER_TOKEN to be set")
+
+        # Use StaticTokenVerifier for simple bearer token authentication
+        from fastmcp.server.auth import StaticTokenVerifier
+
+        logger.info("Configuring bearer token authentication with StaticTokenVerifier")
+
+        # StaticTokenVerifier expects a dict of token -> claims
+        # For simple bearer auth, we just validate the token exists
+        tokens = {settings.bearer_token: {"sub": "api-client", "scope": "api:full"}}
+        return StaticTokenVerifier(tokens=tokens)
+
+    if settings.auth_mode == "oauth":
+        # Note: OAuth proxy requires manual configuration of provider endpoints
+        # For full OAuth support, users should configure an OIDC provider instead
+        logger.warning(
+            "OAuth mode requires manual endpoint configuration. "
+            "Consider using 'oidc' mode for automatic provider discovery."
+        )
+        raise NotImplementedError(
+            "OAuth mode requires manual endpoint configuration. "
+            "Use 'oidc' mode for providers with OIDC discovery support, "
+            "or implement a custom OAuth provider."
+        )
+
+    if settings.auth_mode == "oidc":
+        # Validate required OIDC configuration
+        if not settings.oauth_client_id:
+            raise ValueError("OIDC authentication requires MCP_OAUTH_CLIENT_ID to be set")
+        if not settings.oauth_client_secret:
+            raise ValueError("OIDC authentication requires MCP_OAUTH_CLIENT_SECRET to be set")
+        if not settings.oauth_config_url:
+            raise ValueError("OIDC authentication requires MCP_OAUTH_CONFIG_URL to be set")
+        if not settings.oauth_base_url:
+            raise ValueError("OIDC authentication requires MCP_OAUTH_BASE_URL to be set")
+
+        from fastmcp.server.auth.oidc_proxy import OIDCProxy
+
+        logger.info(
+            "Configuring OIDC proxy authentication",
+            extra={"config_url": settings.oauth_config_url},
+        )
+
+        # Build OIDC proxy configuration
+        oidc_kwargs = {
+            "config_url": settings.oauth_config_url,
+            "client_id": settings.oauth_client_id,
+            "client_secret": settings.oauth_client_secret,
+            "base_url": settings.oauth_base_url,
+            "redirect_path": settings.oauth_redirect_path,
+        }
+
+        # Add optional parameters if configured
+        if settings.oauth_audience:
+            oidc_kwargs["audience"] = settings.oauth_audience
+
+        if settings.oauth_required_scopes_list:
+            oidc_kwargs["required_scopes"] = settings.oauth_required_scopes_list
+
+        return OIDCProxy(**oidc_kwargs)
+
+    raise ValueError(f"Invalid auth_mode: {settings.auth_mode}")
diff --git a/src/mcp_devbench/config/settings.py b/src/mcp_devbench/config/settings.py
@@ -1,7 +1,7 @@
 """Settings and configuration management for MCP DevBench."""
 
 from functools import lru_cache
-from typing import List
+from typing import List, Literal
 
 from pydantic import Field
 from pydantic_settings import BaseSettings, SettingsConfigDict
@@ -84,11 +84,79 @@ class Settings(BaseSettings):
         description="Interval in seconds for warm container health checks",
     )
 
+    # Transport configuration
+    transport_mode: Literal["stdio", "sse", "streamable-http"] = Field(
+        default="streamable-http",
+        description="Transport protocol for MCP server (stdio, sse, or streamable-http)",
+    )
+
+    path: str = Field(
+        default="/mcp",
+        description="Path for HTTP-based transports (sse or streamable-http)",
+    )
+
+    # Authentication configuration
+    auth_mode: Literal["none", "bearer", "oauth", "oidc"] = Field(
+        default="none",
+        description="Authentication mode (none, bearer, oauth, or oidc)",
+    )
+
+    # Bearer token authentication
+    bearer_token: str | None = Field(
+        default=None,
+        description="Bearer token for bearer authentication mode",
+        repr=False,
+    )
+
+    # OAuth/OIDC configuration
+    oauth_client_id: str | None = Field(
+        default=None,
+        description="OAuth/OIDC client ID",
+    )
+
+    oauth_client_secret: str | None = Field(
+        default=None,
+        description="OAuth/OIDC client secret",
+        repr=False,
+    )
+
+    oauth_config_url: str | None = Field(
+        default=None,
+        description="OAuth provider configuration URL (for OIDC, this is the .well-known URL)",
+    )
+
+    oauth_base_url: str | None = Field(
+        default=None,
+        description="Base URL of this server for OAuth callbacks",
+    )
+
+    oauth_redirect_path: str = Field(
+        default="/auth/callback",
+        description="OAuth callback redirect path",
+    )
+
+    oauth_audience: str | None = Field(
+        default=None,
+        description="OAuth audience parameter (required by some providers like Auth0)",
+    )
+
+    oauth_required_scopes: str = Field(
+        default="",
+        description="Comma-separated list of required OAuth scopes",
+    )
+
     @property
     def allowed_registries_list(self) -> List[str]:
         """Parse allowed registries into a list."""
         return [r.strip() for r in self.allowed_registries.split(",") if r.strip()]
 
+    @property
+    def oauth_required_scopes_list(self) -> List[str]:
+        """Parse OAuth required scopes into a list."""
+        if not self.oauth_required_scopes:
+            return []
+        return [s.strip() for s in self.oauth_required_scopes.split(",") if s.strip()]
+
 
 @lru_cache
 def get_settings() -> Settings:
diff --git a/src/mcp_devbench/server.py b/src/mcp_devbench/server.py
@@ -7,6 +7,7 @@
 from fastmcp import FastMCP
 from pydantic import BaseModel
 
+from mcp_devbench.auth import create_auth_provider
 from mcp_devbench.config import get_settings
 from mcp_devbench.managers.container_manager import ContainerManager
 from mcp_devbench.managers.exec_manager import ExecManager
@@ -71,7 +72,8 @@ class HealthCheckResponse(BaseModel):
     version: str = "0.1.0"
 
 
-# Initialize FastMCP server
+# Initialize FastMCP server without authentication initially
+# Auth provider will be set in main() after settings are loaded
 mcp = FastMCP("MCP DevBench")
 logger = get_logger(__name__)
 
@@ -988,18 +990,48 @@ def main() -> None:
     """Main entry point for the MCP DevBench server."""
     settings = get_settings()
 
+    # Setup logging first so auth initialization can be properly logged
+    setup_logging(log_level=settings.log_level, log_format=settings.log_format)
+
+    # Initialize authentication provider after settings and logging are configured
+    auth_provider = create_auth_provider()
+
+    # Set the auth provider on the FastMCP server
+    mcp.auth = auth_provider
+
     logger.info(
         "Starting server",
         extra={
-            "host": settings.host,
-            "port": settings.port,
+            "transport": settings.transport_mode,
+            "auth_mode": settings.auth_mode,
+            "host": settings.host if settings.transport_mode != "stdio" else "N/A",
+            "port": settings.port if settings.transport_mode != "stdio" else "N/A",
             "allowed_registries": settings.allowed_registries_list,
         },
     )
 
     try:
-        # Run the FastMCP server with streamable HTTP transport
-        mcp.run(transport="streamable", host=settings.host, port=settings.port)
+        # Map config transport mode to FastMCP transport parameter
+        # FastMCP expects "streamable" for streamable-http mode
+        transport_map = {
+            "stdio": "stdio",
+            "sse": "sse",
+            "streamable-http": "streamable",
+        }
+
+        transport = transport_map[settings.transport_mode]
+
+        # Prepare run kwargs based on transport mode
+        run_kwargs = {"transport": transport}
+
+        # Add HTTP-specific settings for HTTP-based transports
+        if settings.transport_mode in ("sse", "streamable-http"):
+            run_kwargs["host"] = settings.host
+            run_kwargs["port"] = settings.port
+            run_kwargs["path"] = settings.path
+
+        # Run the FastMCP server with configured transport
+        mcp.run(**run_kwargs)
     except KeyboardInterrupt:
         logger.info("Received keyboard interrupt, shutting down")
         sys.exit(0)
diff --git a/tests/unit/test_auth_config.py b/tests/unit/test_auth_config.py
