Merge branch 'main' into ylassoued/feat-request

Author: ylassoued

.gitignore

@@ -166,4 +166,5 @@ cython_debug/
 
 # vscode
 .vscode/
+.windsurfrules
 **/CLAUDE.local.md

CLAUDE.md

@@ -19,7 +19,7 @@ This document contains critical information about working with this codebase. Fo
    - Line length: 88 chars maximum
 
 3. Testing Requirements
-   - Framework: `uv run pytest`
+   - Framework: `uv run --frozen pytest`
    - Async testing: use anyio, not asyncio
    - Coverage: test edge cases and errors
    - New features require tests
@@ -54,9 +54,9 @@ This document contains critical information about working with this codebase. Fo
 ## Code Formatting
 
 1. Ruff
-   - Format: `uv run ruff format .`
-   - Check: `uv run ruff check .`
-   - Fix: `uv run ruff check . --fix`
+   - Format: `uv run --frozen ruff format .`
+   - Check: `uv run --frozen ruff check .`
+   - Fix: `uv run --frozen ruff check . --fix`
    - Critical issues:
      - Line length (88 chars)
      - Import sorting (I001)
@@ -67,7 +67,7 @@ This document contains critical information about working with this codebase. Fo
      - Imports: split into multiple lines
 
 2. Type Checking
-   - Tool: `uv run pyright`
+   - Tool: `uv run --frozen pyright`
    - Requirements:
      - Explicit None checks for Optional
      - Type narrowing for strings
@@ -104,6 +104,10 @@ This document contains critical information about working with this codebase. Fo
      - Add None checks
      - Narrow string types
      - Match existing patterns
+   - Pytest:
+     - If the tests aren't finding the anyio pytest mark, try adding PYTEST_DISABLE_PLUGIN_AUTOLOAD=""
+       to the start of the pytest run command eg:
+       `PYTEST_DISABLE_PLUGIN_AUTOLOAD="" uv run --frozen pytest`
 
 3. Best Practices
    - Check git status before commits

README.md

@@ -66,7 +66,7 @@ The Model Context Protocol allows applications to provide context for LLMs in a
 
 - Build MCP clients that can connect to any MCP server
 - Create MCP servers that expose resources, prompts and tools
-- Use standard transports like stdio and SSE
+- Use standard transports like stdio, SSE, and Streamable HTTP
 - Handle all MCP protocol messages and lifecycle events
 
 ## Installation
@@ -309,6 +309,33 @@ async def long_task(files: list[str], ctx: Context) -> str:
     return "Processing complete"
 ```
 
+### Authentication
+
+Authentication can be used by servers that want to expose tools accessing protected resources.
+
+`mcp.server.auth` implements an OAuth 2.0 server interface, which servers can use by
+providing an implementation of the `OAuthServerProvider` protocol.
+
+```
+mcp = FastMCP("My App",
+        auth_provider=MyOAuthServerProvider(),
+        auth=AuthSettings(
+            issuer_url="https://myapp.com",
+            revocation_options=RevocationOptions(
+                enabled=True,
+            ),
+            client_registration_options=ClientRegistrationOptions(
+                enabled=True,
+                valid_scopes=["myscope", "myotherscope"],
+                default_scopes=["myscope"],
+            ),
+            required_scopes=["myscope"],
+        ),
+)
+```
+
+See [OAuthServerProvider](src/mcp/server/auth/provider.py) for more details.
+
 ## Running Your Server
 
 ### Development Mode
@@ -360,8 +387,81 @@ python server.py
 mcp run server.py
 ```
 
+### Streamable HTTP Transport
+
+> **Note**: Streamable HTTP transport is superseding SSE transport for production deployments.
+
+```python
+from mcp.server.fastmcp import FastMCP
+
+# Stateful server (maintains session state)
+mcp = FastMCP("StatefulServer")
+
+# Stateless server (no session persistence)
+mcp = FastMCP("StatelessServer", stateless_http=True)
+
+# Run server with streamable_http transport
+mcp.run(transport="streamable-http")
+```
+
+You can mount multiple FastMCP servers in a FastAPI application:
+
+```python
+# echo.py
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP(name="EchoServer", stateless_http=True)
+
+
+@mcp.tool(description="A simple echo tool")
+def echo(message: str) -> str:
+    return f"Echo: {message}"
+```
+
+```python
+# math.py
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP(name="MathServer", stateless_http=True)
+
+
+@mcp.tool(description="A simple add tool")
+def add_two(n: int) -> str:
+    return n + 2
+```
+
+```python
+# main.py
+from fastapi import FastAPI
+from mcp.echo import echo
+from mcp.math import math
+
+
+app = FastAPI()
+
+# Use the session manager's lifespan
+app = FastAPI(lifespan=lambda app: echo.mcp.session_manager.run())
+app.mount("/echo", echo.mcp.streamable_http_app())
+app.mount("/math", math.mcp.streamable_http_app())
+```
+
+For low level server with Streamable HTTP implementations, see:
+- Stateful server: [`examples/servers/simple-streamablehttp/`](examples/servers/simple-streamablehttp/)
+- Stateless server: [`examples/servers/simple-streamablehttp-stateless/`](examples/servers/simple-streamablehttp-stateless/)
+
+
+
+The streamable HTTP transport supports:
+- Stateful and stateless operation modes
+- Resumability with event stores
+- JSON or SSE response formats  
+- Better scalability for multi-node deployments
+
+
 ### Mounting to an Existing ASGI Server
 
+> **Note**: SSE transport is being superseded by [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http).
+
 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
@@ -383,6 +483,43 @@ app = Starlette(
 app.router.routes.append(Host('mcp.acme.corp', app=mcp.sse_app()))
 ```
 
+When mounting multiple MCP servers under different paths, you can configure the mount path in several ways:
+
+```python
+from starlette.applications import Starlette
+from starlette.routing import Mount
+from mcp.server.fastmcp import FastMCP
+
+# Create multiple MCP servers
+github_mcp = FastMCP("GitHub API")
+browser_mcp = FastMCP("Browser")
+curl_mcp = FastMCP("Curl")
+search_mcp = FastMCP("Search")
+
+# Method 1: Configure mount paths via settings (recommended for persistent configuration)
+github_mcp.settings.mount_path = "/github"
+browser_mcp.settings.mount_path = "/browser"
+
+# Method 2: Pass mount path directly to sse_app (preferred for ad-hoc mounting)
+# This approach doesn't modify the server's settings permanently
+
+# Create Starlette app with multiple mounted servers
+app = Starlette(
+    routes=[
+        # Using settings-based configuration
+        Mount("/github", app=github_mcp.sse_app()),
+        Mount("/browser", app=browser_mcp.sse_app()),
+        # Using direct mount path parameter
+        Mount("/curl", app=curl_mcp.sse_app("/curl")),
+        Mount("/search", app=search_mcp.sse_app("/search")),
+    ]
+)
+
+# Method 3: For direct execution, you can also pass the mount path to run()
+if __name__ == "__main__":
+    search_mcp.run(transport="sse", mount_path="/search")
+```
+
 For more information on mounting applications in Starlette, see the [Starlette documentation](https://www.starlette.io/routing/#submounting-routes).
 
 ## Examples
@@ -557,7 +694,7 @@ if __name__ == "__main__":
 
 ### Writing MCP Clients
 
-The SDK provides a high-level client interface for connecting to MCP servers:
+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):
 
 ```python
 from mcp import ClientSession, StdioServerParameters, types
@@ -621,6 +758,28 @@ if __name__ == "__main__":
     asyncio.run(run())
 ```
 
+Clients can also connect using [Streamable HTTP transport](https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#streamable-http):
+
+```python
+from mcp.client.streamable_http import streamablehttp_client
+from mcp import ClientSession
+
+
+async def main():
+    # Connect to a streamable HTTP server
+    async with streamablehttp_client("example/mcp") as (
+        read_stream,
+        write_stream,
+        _,
+    ):
+        # Create a session using the client streams
+        async with ClientSession(read_stream, write_stream) as session:
+            # Initialize the connection
+            await session.initialize()
+            # Call a tool
+            tool_result = await session.call_tool("echo", {"message": "hello"})
+```
+
 ### MCP Primitives
 
 The MCP protocol defines three core primitives that servers can implement:

examples/clients/simple-chatbot/mcp_simple_chatbot/main.py

@@ -323,8 +323,7 @@ async def process_llm_response(self, llm_response: str) -> str:
                                 total = result["total"]
                                 percentage = (progress / total) * 100
                                 logging.info(
-                                    f"Progress: {progress}/{total} "
-                                    f"({percentage:.1f}%)"
+                                    f"Progress: {progress}/{total} ({percentage:.1f}%)"
                                 )
 
                             return f"Tool execution result: {result}"

examples/servers/simple-auth/README.md

@@ -0,0 +1,65 @@
+# Simple MCP Server with GitHub OAuth Authentication
+
+This is a simple example of an MCP server with GitHub OAuth authentication. It demonstrates the essential components needed for OAuth integration with just a single tool.
+
+This is just an example of a server that uses auth, an official GitHub mcp server is [here](https://github.com/github/github-mcp-server)
+
+## Overview
+
+This simple demo to show to set up a server with:
+- GitHub OAuth2 authorization flow
+- Single tool: `get_user_profile` to retrieve GitHub user information
+
+
+## Prerequisites
+
+1. Create a GitHub OAuth App:
+   - Go to GitHub Settings > Developer settings > OAuth Apps > New OAuth App
+   - Application name: Any name (e.g., "Simple MCP Auth Demo")
+   - Homepage URL: `http://localhost:8000`
+   - Authorization callback URL: `http://localhost:8000/github/callback`
+   - Click "Register application"
+   - Note down your Client ID and Client Secret
+
+## Required Environment Variables
+
+You MUST set these environment variables before running the server:
+
+```bash
+export MCP_GITHUB_GITHUB_CLIENT_ID="your_client_id_here"
+export MCP_GITHUB_GITHUB_CLIENT_SECRET="your_client_secret_here"
+```
+
+The server will not start without these environment variables properly set.
+
+
+## Running the Server
+
+```bash
+# Set environment variables first (see above)
+
+# Run the server
+uv run mcp-simple-auth
+```
+
+The server will start on `http://localhost:8000`.
+
+## Available Tool
+
+### get_user_profile
+
+The only tool in this simple example. Returns the authenticated user's GitHub profile information.
+
+**Required scope**: `user`
+
+**Returns**: GitHub user profile data including username, email, bio, etc.
+
+
+## Troubleshooting
+
+If the server fails to start, check:
+1. Environment variables `MCP_GITHUB_GITHUB_CLIENT_ID` and `MCP_GITHUB_GITHUB_CLIENT_SECRET` are set
+2. The GitHub OAuth app callback URL matches `http://localhost:8000/github/callback`
+3. No other service is using port 8000
+
+You can use [Inspector](https://github.com/modelcontextprotocol/inspector) to test Auth

examples/servers/simple-auth/mcp_simple_auth/__init__.py

@@ -0,0 +1 @@
+"""Simple MCP server with GitHub OAuth authentication."""

examples/servers/simple-auth/mcp_simple_auth/__main__.py

@@ -0,0 +1,7 @@
+"""Main entry point for simple MCP server with GitHub OAuth authentication."""
+
+import sys
+
+from mcp_simple_auth.server import main
+
+sys.exit(main())