Merge branch 'main' into ylassoued/feat-request

Author: ylassoued

.github/workflows/shared.yml

@@ -37,10 +37,11 @@ jobs:
         run: uv run --no-sync pyright
 
   test:
-    runs-on: ubuntu-latest
+    runs-on: ${{ matrix.os }}
     strategy:
       matrix:
         python-version: ["3.10", "3.11", "3.12", "3.13"]
+        os: [ubuntu-latest, windows-latest]
 
     steps:
       - uses: actions/checkout@v4
@@ -55,3 +56,4 @@ jobs:
 
       - name: Run pytest
         run: uv run --no-sync pytest
+    continue-on-error: true

README.md

@@ -318,7 +318,7 @@ providing an implementation of the `OAuthServerProvider` protocol.
 
 ```
 mcp = FastMCP("My App",
-        auth_provider=MyOAuthServerProvider(),
+        auth_server_provider=MyOAuthServerProvider(),
         auth=AuthSettings(
             issuer_url="https://myapp.com",
             revocation_options=RevocationOptions(
@@ -387,6 +387,8 @@ python server.py
 mcp run server.py
 ```
 
+Note that `mcp run` or `mcp dev` only supports server using FastMCP and not the low-level server variant.
+
 ### Streamable HTTP Transport
 
 > **Note**: Streamable HTTP transport is superseding SSE transport for production deployments.
@@ -400,6 +402,9 @@ mcp = FastMCP("StatefulServer")
 # Stateless server (no session persistence)
 mcp = FastMCP("StatelessServer", stateless_http=True)
 
+# Stateless server (no session persistence, no sse stream with supported client)
+mcp = FastMCP("StatelessServer", stateless_http=True, json_response=True)
+
 # Run server with streamable_http transport
 mcp.run(transport="streamable-http")
 ```
@@ -426,21 +431,28 @@ mcp = FastMCP(name="MathServer", stateless_http=True)
 
 
 @mcp.tool(description="A simple add tool")
-def add_two(n: int) -> str:
+def add_two(n: int) -> int:
     return n + 2
 ```
 
 ```python
 # main.py
+import contextlib
 from fastapi import FastAPI
 from mcp.echo import echo
 from mcp.math import math
 
 
-app = FastAPI()
+# Create a combined lifespan to manage both session managers
+@contextlib.asynccontextmanager
+async def lifespan(app: FastAPI):
+    async with contextlib.AsyncExitStack() as stack:
+        await stack.enter_async_context(echo.mcp.session_manager.run())
+        await stack.enter_async_context(math.mcp.session_manager.run())
+        yield
 
-# Use the session manager's lifespan
-app = FastAPI(lifespan=lambda app: echo.mcp.session_manager.run())
+
+app = FastAPI(lifespan=lifespan)
 app.mount("/echo", echo.mcp.streamable_http_app())
 app.mount("/math", math.mcp.streamable_http_app())
 ```
@@ -462,6 +474,8 @@ The streamable HTTP transport supports:
 
 > **Note**: SSE transport is being superseded by [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http).
 
+By default, SSE servers are mounted at `/sse` and Streamable HTTP servers are mounted at `/mcp`. You can customize these paths using the methods described below.
+
 You can mount the SSE server to an existing ASGI server using the `sse_app` method. This allows you to integrate the SSE server with other ASGI applications.
 
 ```python
@@ -617,7 +631,7 @@ server = Server("example-server", lifespan=server_lifespan)
 # Access lifespan context in handlers
 @server.call_tool()
 async def query_db(name: str, arguments: dict) -> list:
-    ctx = server.request_context
+    ctx = server.get_context()
     db = ctx.lifespan_context["db"]
     return await db.query(arguments["query"])
 ```
@@ -692,6 +706,8 @@ if __name__ == "__main__":
     asyncio.run(run())
 ```
 
+Caution: The `mcp run` and `mcp dev` tool doesn't support low-level server.
+
 ### Writing MCP Clients
 
 The SDK provides a high-level client interface for connecting to MCP servers using various [transports](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports):
@@ -780,6 +796,60 @@ async def main():
             tool_result = await session.call_tool("echo", {"message": "hello"})
 ```
 
+### OAuth Authentication for Clients
+
+The SDK includes [authorization support](https://modelcontextprotocol.io/specification/2025-03-26/basic/authorization) for connecting to protected MCP servers:
+
+```python
+from mcp.client.auth import OAuthClientProvider, TokenStorage
+from mcp.client.session import ClientSession
+from mcp.client.streamable_http import streamablehttp_client
+from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata, OAuthToken
+
+
+class CustomTokenStorage(TokenStorage):
+    """Simple in-memory token storage implementation."""
+
+    async def get_tokens(self) -> OAuthToken | None:
+        pass
+
+    async def set_tokens(self, tokens: OAuthToken) -> None:
+        pass
+
+    async def get_client_info(self) -> OAuthClientInformationFull | None:
+        pass
+
+    async def set_client_info(self, client_info: OAuthClientInformationFull) -> None:
+        pass
+
+
+async def main():
+    # Set up OAuth authentication
+    oauth_auth = OAuthClientProvider(
+        server_url="https://api.example.com",
+        client_metadata=OAuthClientMetadata(
+            client_name="My Client",
+            redirect_uris=["http://localhost:3000/callback"],
+            grant_types=["authorization_code", "refresh_token"],
+            response_types=["code"],
+        ),
+        storage=CustomTokenStorage(),
+        redirect_handler=lambda url: print(f"Visit: {url}"),
+        callback_handler=lambda: ("auth_code", None),
+    )
+
+    # Use with streamable HTTP client
+    async with streamablehttp_client(
+        "https://api.example.com/mcp", auth=oauth_auth
+    ) as (read, write, _):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+            # Authenticated session ready
+```
+
+For a complete working example, see [`examples/clients/simple-auth-client/`](examples/clients/simple-auth-client/).
+
+
 ### MCP Primitives
 
 The MCP protocol defines three core primitives that servers can implement:

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

@@ -0,0 +1,74 @@
+# Simple Auth Client Example
+
+A demonstration of how to use the MCP Python SDK with OAuth authentication over streamable HTTP or SSE transport.
+
+## Features
+
+- OAuth 2.0 authentication with PKCE
+- Support for both StreamableHTTP and SSE transports
+- Interactive command-line interface
+
+## Installation
+
+```bash
+cd examples/clients/simple-auth-client
+uv sync --reinstall 
+```
+
+## Usage
+
+### 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
+
+```bash
+uv run mcp-simple-auth-client
+
+# Or with custom server URL
+MCP_SERVER_PORT=3001 uv run mcp-simple-auth-client
+
+# Use SSE transport
+MCP_TRANSPORT_TYPE=sse uv run mcp-simple-auth-client
+```
+
+### 3. Complete OAuth flow
+
+The client will open your browser for authentication. After completing OAuth, you can use commands:
+
+- `list` - List available tools
+- `call <tool_name> [args]` - Call a tool with optional JSON arguments  
+- `quit` - Exit
+
+## Example
+
+```
+🔐 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
+
+mcp> list
+📋 Available tools:
+1. echo - Echo back the input text
+
+mcp> call echo {"text": "Hello, world!"}
+🔧 Tool 'echo' result:
+Hello, world!
+
+mcp> quit
+👋 Goodbye!
+```
+
+## Configuration
+
+- `MCP_SERVER_PORT` - Server URL (default: 8000)
+- `MCP_TRANSPORT_TYPE` - Transport type: `streamable_http` (default) or `sse`

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

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