Fix CodeRabbit review comments for Keycloak OAuth provider

Address 11 actionable code review comments from CodeRabbitAI:

- Fix FileTokenStorage import and add CLEAR_TOKEN_CACHE feature flag in client example
- Remove manual scope splitting in server.py, delegate to KeycloakProviderSettings parser
- Merge client-requested scopes with required scopes in registration endpoint
- Always append missing required scopes to authorization requests
- Fix test mocking to only patch provider's httpx imports, not globally
- Move asyncio import to module scope in integration tests
- Fix markdown linting issues (convert bold to headings, remove trailing space)
- Fix troubleshooting paths in keycloak/README.md
- Pin dependency versions in requirements.txt for reproducibility

These changes ensure proper scope handling that preserves client intent while
enforcing server requirements, improve test isolation, and enhance code quality.

Author: stephaneberle9

examples/auth/keycloak_auth/README.md

@@ -17,13 +17,13 @@ Review the realm configuration file: [`keycloak/realm-fastmcp.json`](keycloak/re
 
 Choose one of the following options:
 
-**Option A: Local Keycloak Instance (Recommended for Testing)**
+#### Option A: Local Keycloak Instance (Recommended for Testing)
 
 See [keycloak/README.md](keycloak/README.md) for details.
 
-**Note:** The realm will be automatically imported on startup. 
+**Note:** The realm will be automatically imported on startup.
 
-**Option B: Existing Keycloak Instance**
+#### Option B: Existing Keycloak Instance
 
 Manually import the realm:
 - Log in to your Keycloak Admin Console

examples/auth/keycloak_auth/client.py

@@ -9,17 +9,22 @@
 import asyncio
 
 from fastmcp import Client
+from fastmcp.client.auth.oauth import FileTokenStorage
 
 SERVER_URL = "http://localhost:8000/mcp"
 
+# Set to True to clear any previously stored tokens.
+# This is useful if you have just restarted Keycloak and end up seeing
+# Keycloak showing this error: "We are sorry... Client not found."
+# instead of the login screen
+CLEAR_TOKEN_CACHE = False
+
 
 async def main():
-    # Uncomment the following lines to clear any previously stored tokens.
-    # This is useful if you have just restarted Keycloak and end up seeing
-    # Keycloak showing this error: "We are sorry... Client not found."
-    # instead of the login screen
-    # storage = FileTokenStorage("http://localhost:8000/mcp/")
-    # storage.clear()
+    if CLEAR_TOKEN_CACHE:
+        storage = FileTokenStorage(f"{SERVER_URL.rstrip('/')}/")
+        storage.clear()
+        print("🧹 Cleared cached OAuth tokens.")
 
     try:
         async with Client(SERVER_URL, auth="oauth") as client:

examples/auth/keycloak_auth/keycloak/README.md

@@ -105,8 +105,8 @@ docker-compose logs -f keycloak
 2. **Realm not found**
    - Verify realm import: Check admin console at [http://localhost:8080/admin](http://localhost:8080/admin)
    - Check realm file exists:
-     - Linux/macOS: `ls keycloak/realm-fastmcp.json`
-     - Windows: `dir keycloak\realm-fastmcp.json`
+     - Linux/macOS: `ls realm-fastmcp.json`
+     - Windows: `dir realm-fastmcp.json`
 
 3. **Client registration failed**
    - Verify the request comes from a trusted host

examples/auth/keycloak_auth/requirements.txt

@@ -1,2 +1,2 @@
-fastmcp
-python-dotenv
+fastmcp>=0.1.0
+python-dotenv>=1.0.0

examples/auth/keycloak_auth/server.py

@@ -24,16 +24,18 @@
 
 load_dotenv(".env", override=True)
 
+realm_url = os.getenv(
+    "FASTMCP_SERVER_AUTH_KEYCLOAK_REALM_URL", "http://localhost:8080/realms/fastmcp"
+)
+base_url = os.getenv("FASTMCP_SERVER_AUTH_KEYCLOAK_BASE_URL", "http://localhost:8000")
+required_scopes = os.getenv(
+    "FASTMCP_SERVER_AUTH_KEYCLOAK_REQUIRED_SCOPES", "openid,profile"
+)
+
 auth = KeycloakAuthProvider(
-    realm_url=os.getenv(
-        "FASTMCP_SERVER_AUTH_KEYCLOAK_REALM_URL", "http://localhost:8080/realms/fastmcp"
-    ),
-    base_url=os.getenv(
-        "FASTMCP_SERVER_AUTH_KEYCLOAK_BASE_URL", "http://localhost:8000"
-    ),
-    required_scopes=os.getenv(
-        "FASTMCP_SERVER_AUTH_KEYCLOAK_REQUIRED_SCOPES", "openid,profile"
-    ).split(","),
+    realm_url=realm_url,
+    base_url=base_url,
+    required_scopes=required_scopes,
 )
 
 mcp = FastMCP("Keycloak OAuth Example Server", auth=auth)

src/fastmcp/server/auth/providers/keycloak.py

@@ -262,12 +262,16 @@ async def register_client_proxy(request):
 
                 # Add the server's required scopes to the client registration data
                 if self.token_verifier.required_scopes:
+                    scopes = parse_scopes(registration_data.get("scope")) or []
+                    merged_scopes = scopes + [
+                        scope
+                        for scope in self.token_verifier.required_scopes
+                        if scope not in scopes
+                    ]
                     logger.info(
-                        f"Adding server-configured required scopes to client registration data: {self.token_verifier.required_scopes}"
-                    )
-                    registration_data["scope"] = " ".join(
-                        self.token_verifier.required_scopes
+                        f"Merging server-configured required scopes with client-requested scopes: {merged_scopes}"
                     )
+                    registration_data["scope"] = " ".join(merged_scopes)
                     # Update the body with modified client registration data
                     body = json.dumps(registration_data).encode("utf-8")
 
@@ -355,13 +359,20 @@ async def authorize_proxy(request):
 
                 # Add server-configured required scopes to the authorization request
                 query_params = dict(request.query_params)
-                if "scope" not in query_params and self.token_verifier.required_scopes:
-                    logger.info(
-                        f"Adding server-configured required scopes to authorization request: {self.token_verifier.required_scopes}"
-                    )
-                    query_params["scope"] = " ".join(
-                        self.token_verifier.required_scopes
-                    )
+                if self.token_verifier.required_scopes:
+                    existing_scopes = parse_scopes(query_params.get("scope")) or []
+                    missing_scopes = [
+                        scope
+                        for scope in self.token_verifier.required_scopes
+                        if scope not in existing_scopes
+                    ]
+                    if missing_scopes:
+                        logger.info(
+                            f"Adding server-configured required scopes to authorization request: {missing_scopes}"
+                        )
+                        query_params["scope"] = " ".join(
+                            existing_scopes + missing_scopes
+                        )
 
                 # Build authorization request URL for redirecting to Keycloak and including the (potentially modified) query string
                 authorization_url = str(self.oidc_config.authorization_endpoint)

tests/integration_tests/auth/test_keycloak_provider_integration.py

@@ -1,5 +1,6 @@
 """Integration tests for Keycloak OAuth provider."""
 
+import asyncio
 import os
 from unittest.mock import AsyncMock, Mock, patch
 from urllib.parse import parse_qs, urlparse
@@ -95,7 +96,9 @@ async def test_end_to_end_client_registration_flow(self, mock_keycloak_server):
             mcp_http_app = mcp.http_app()
 
             # Mock the actual HTTP client post method
-            with patch("httpx.AsyncClient.post") as mock_post:
+            with patch(
+                "fastmcp.server.auth.providers.keycloak.httpx.AsyncClient.post"
+            ) as mock_post:
                 # Mock Keycloak's response to client registration
                 mock_keycloak_response = Mock()
                 mock_keycloak_response.status_code = 201
@@ -288,7 +291,9 @@ async def test_concurrent_client_registrations(self):
             mcp_http_app = mcp.http_app()
 
             # Mock concurrent Keycloak responses
-            with patch("httpx.AsyncClient") as mock_client_class:
+            with patch(
+                "fastmcp.server.auth.providers.keycloak.httpx.AsyncClient"
+            ) as mock_client_class:
                 mock_client = AsyncMock()
                 mock_client_class.return_value.__aenter__.return_value = mock_client
 
@@ -318,8 +323,6 @@ async def test_concurrent_client_registrations(self):
                     transport=httpx.ASGITransport(app=mcp_http_app),
                     base_url=TEST_BASE_URL,
                 ) as client:
-                    import asyncio
-
                     registration_data = [
                         {
                             "redirect_uris": [f"http://localhost:800{i}/callback"],