tests and readme

Author: ihrpr

README.md

@@ -801,7 +801,7 @@ async def main():
 The SDK supports OAuth 2.0 client authentication for secure access to MCP servers that require authentication:
 
 ```python
-from mcp.client.auth import OAuthClientProvider, UnauthorizedError
+from mcp.client.auth import UnauthorizedError
 from mcp.client.oauth_providers import InMemoryOAuthProvider
 from mcp.client.streamable_http import streamablehttp_client
 from mcp.shared.auth import OAuthClientMetadata
@@ -817,6 +817,7 @@ oauth_provider = InMemoryOAuthProvider(
     ),
 )
 
+
 async def main():
     # Connect with OAuth authentication
     async with streamablehttp_client(
@@ -834,6 +835,7 @@ async def main():
                 # Handle authorization required
                 print("Authorization required. Check your browser.")
 
+
 # Handle OAuth callback after user authorization
 async def handle_callback(authorization_code: str):
     from mcp.client.streamable_http import StreamableHTTPTransport
@@ -856,14 +858,17 @@ You can implement custom OAuth storage by creating your own provider:
 ```python
 from mcp.client.oauth_providers import InMemoryOAuthProvider
 
+
 class DatabaseOAuthProvider(InMemoryOAuthProvider):
     async def save_tokens(self, tokens):
         # Save to database
-        await db.save_tokens(self.client_id, tokens)
+        # await db.save_tokens(self.client_id, tokens)
+        pass
 
     async def tokens(self):
         # Load from database
-        return await db.load_tokens(self.client_id)
+        # return await db.load_tokens(self.client_id)
+        return None
 
     # Implement other methods as needed...
 ```

examples/clients/simple-auth-client/README.md

@@ -1,125 +1,70 @@
 # Simple Auth Client Example
 
-This example demonstrates how to use the MCP Python SDK to create a client that connects to an MCP server using OAuth authentication over streamable HTTP transport.
+A demonstration of how to use the MCP Python SDK with OAuth authentication over streamable HTTP transport.
 
 ## Features
 
 - OAuth 2.0 authentication with PKCE
 - Streamable HTTP transport  
 - Interactive command-line interface
-- Tool listing and execution
-
-## Prerequisites
-
-1. Python 3.9 or higher
-2. An MCP server that supports OAuth authentication (like `mcp-simple-auth`)
-3. uv for dependency management
 
 ## Installation
 
 ```bash
 cd examples/clients/simple-auth-client
-uv install
+uv sync --reinstall 
 ```
 
 ## Usage
 
-### 1. Start the Auth Server
-
-First, start the MCP auth server in another terminal:
+### 1. Start an MCP server with OAuth support
 
 ```bash
+# Example with mcp-simple-auth
 cd path/to/mcp-simple-auth
 uv run mcp-simple-auth --transport streamable-http --port 3001
 ```
 
-### 2. Run the Client
+### 2. Run the client
 
 ```bash
-# Run the client
 uv run mcp-simple-auth-client
 
 # Or with custom server URL
 MCP_SERVER_URL=http://localhost:3001 uv run mcp-simple-auth-client
 ```
 
-### 3. Authentication Flow
-
-1. The client will attempt to connect to the server
-2. If authentication is required, the client will open your default browser 
-3. Complete the OAuth flow in the browser
-4. Return to the client - it should now be connected
-
-### 4. Interactive Commands
+### 3. Complete OAuth flow
 
-Once connected, you can use these commands:
+The client will open your browser for authentication. After completing OAuth, you can use commands:
 
-- `list` - List available tools from the server
-- `call <tool_name> [args]` - Call a tool with optional JSON arguments
-- `quit` - Exit the client
+- `list` - List available tools
+- `call <tool_name> [args]` - Call a tool with optional JSON arguments  
+- `quit` - Exit
 
-### Example Session
+## Example
 
 ```
-=� Simple MCP Auth Client
+🔐 Simple MCP Auth Client
 Connecting to: http://localhost:3001
 
 Please visit the following URL to authorize the application:
 http://localhost:3001/authorize?response_type=code&client_id=...
 
- Connected to MCP server at http://localhost:3001
-Session ID: abc123
-
-<� Interactive MCP Client
-Commands:
-  list - List available tools
-  call <tool_name> [args] - Call a tool
-  quit - Exit the client
+✅ Connected to MCP server at http://localhost:3001
 
 mcp> list
-
-=� Available tools:
-1. echo
-   Description: Echo back the input text
+📋 Available tools:
+1. echo - Echo back the input text
 
 mcp> call echo {"text": "Hello, world!"}
-
-=' Tool 'echo' result:
+🔧 Tool 'echo' result:
 Hello, world!
 
 mcp> quit
-=K Goodbye!
+👋 Goodbye!
 ```
 
 ## Configuration
 
-You can customize the client behavior with environment variables:
-
 - `MCP_SERVER_URL` - Server URL (default: http://localhost:3001)
-- `AUTH_CODE` - Authorization code for completing OAuth flow
-
-## Implementation Details
-
-This example shows how to:
-
-1. **Create an OAuth provider** - Implement the `OAuthClientProvider` protocol
-2. **Use streamable HTTP transport** - Connect using the `streamablehttp_client` context manager  
-3. **Handle authentication** - Manage OAuth flow including browser redirect
-4. **Interactive tool usage** - List and call tools from the command line
-
-The key components are:
-
-- `SimpleOAuthProvider` - Minimal OAuth provider implementation
-- `SimpleAuthClient` - Main client class that handles connection and tool operations
-- Interactive loop for user commands
-
-## Error Handling
-
-The client handles common error scenarios:
-
-- Server connection failures
-- Authentication errors  
-- Invalid tool calls
-- Network timeouts
-
-All errors are displayed with helpful messages to guide debugging.

examples/clients/simple-auth-client/mcp_simple_auth_client/__init__.py

@@ -1 +1 @@
-"""Simple OAuth client for MCP simple-auth server."""
+"""Simple OAuth client for MCP simple-auth server."""

examples/clients/simple-auth-client/mcp_simple_auth_client/main.py

@@ -135,7 +135,7 @@ class SimpleAuthClient:
     def __init__(self, server_url: str):
         self.server_url = server_url
         # Extract base URL for auth server (remove /mcp endpoint for auth endpoints)
-        # Use default redirect URI - this is where the auth server will redirect the user
+        # Use default redirect URI - this is where the auth server will redirect
         # The user will need to copy the authorization code from this callback URL
         self.session: ClientSession | None = None
 

src/mcp/client/auth.py

@@ -268,7 +268,8 @@ async def _validate_token_scopes(self, token_response: OAuthToken) -> None:
         set of scopes than requested, but must not grant additional scopes.
         """
         if not token_response.scope:
-            # If no scope is returned, validation passes (server didn't grant anything extra)
+            # If no scope is returned, validation passes
+            # (server didn't grant anything extra)
             return
 
         # Get the originally requested scopes
@@ -306,7 +307,8 @@ async def _validate_token_scopes(self, token_response: OAuthToken) -> None:
             # If no scopes were originally requested (fell back to server defaults),
             # accept whatever the server returned
             logger.debug(
-                f"No specific scopes were requested, accepting server-granted scopes: {returned_scopes}"
+                f"No specific scopes were requested, accepting server-granted "
+                f"scopes: {returned_scopes}"
             )
 
     async def initialize(self) -> None:
@@ -372,7 +374,7 @@ async def _perform_oauth_flow(self) -> None:
         auth_params = {
             "response_type": "code",
             "client_id": client_info.client_id,
-            "redirect_uri": self.client_metadata.redirect_uris[0],
+            "redirect_uri": str(self.client_metadata.redirect_uris[0]),
             "state": secrets.token_urlsafe(32),
             "code_challenge": self._code_challenge,
             "code_challenge_method": "S256",
@@ -396,9 +398,15 @@ async def _perform_oauth_flow(self) -> None:
 
         auth_code, returned_state = await self.callback_handler()
 
-        # Validate state parameter
-        if returned_state != auth_params["state"]:
-            raise Exception("State parameter mismatch")
+        # Validate state parameter using constant-time comparison
+        # to prevent timing attacks
+        if returned_state is None:
+            raise Exception("State parameter mismatch - possible CSRF attack")
+        # Type cast to ensure both args are str for compare_digest
+        expected_state = str(auth_params["state"])
+        actual_state = str(returned_state)
+        if not secrets.compare_digest(actual_state, expected_state):
+            raise Exception("State parameter mismatch - possible CSRF attack")
 
         if not auth_code:
             raise Exception("No authorization code received")
@@ -438,9 +446,20 @@ async def _exchange_code_for_token(
             )
 
             if response.status_code != 200:
-                raise Exception(
-                    f"Token exchange failed: {response.status_code} {response.text}"
-                )
+                # Try to parse OAuth error response, otherwise use basic error
+                try:
+                    error_data = response.json()
+                    error_msg = error_data.get(
+                        "error_description", error_data.get("error", "Unknown error")
+                    )
+                    raise Exception(
+                        f"Token exchange failed: {error_msg} "
+                        f"(HTTP {response.status_code})"
+                    )
+                except Exception:
+                    raise Exception(
+                        f"Token exchange failed: {response.status_code} {response.text}"
+                    )
 
             # Parse and store tokens
             token_response = OAuthToken.model_validate(response.json())
@@ -499,7 +518,8 @@ async def _refresh_access_token(self) -> bool:
                 # Parse and store new tokens
                 token_response = OAuthToken.model_validate(response.json())
 
-                # Validate returned scopes against requested scopes (OAuth 2.1 Section 3.3)
+                # Validate returned scopes against requested scopes
+                # (OAuth 2.1 Section 3.3)
                 await self._validate_token_scopes(token_response)
 
                 # Calculate expiry time if available