Merge branch 'main' into ihrpr/inlcude-examples-in-pyright

Author: ihrpr

.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

@@ -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
@@ -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,8 +387,85 @@ 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.
+
+```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) -> int:
+    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).
+
+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
@@ -544,7 +621,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"])
 ```
@@ -619,9 +696,11 @@ 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:
+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
@@ -685,6 +764,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/README.MD

@@ -25,6 +25,7 @@ This example demonstrates how to integrate the Model Context Protocol (MCP) into
    ```plaintext
    LLM_API_KEY=your_api_key_here
    ```
+   **Note:** The current implementation is configured to use the Groq API endpoint (`https://api.groq.com/openai/v1/chat/completions`) with the `llama-3.2-90b-vision-preview` model. If you plan to use a different LLM provider, you'll need to modify the `LLMClient` class in `main.py` to use the appropriate endpoint URL and model parameters.
 
 3. **Configure servers:**
 

examples/servers/simple-auth/README.md

@@ -44,6 +44,31 @@ uv run mcp-simple-auth
 
 The server will start on `http://localhost:8000`.
 
+### Transport Options
+
+This server supports multiple transport protocols that can run on the same port:
+
+#### SSE (Server-Sent Events) - Default
+```bash
+uv run mcp-simple-auth
+# or explicitly:
+uv run mcp-simple-auth --transport sse
+```
+
+SSE transport provides endpoint:
+- `/sse`
+
+#### Streamable HTTP
+```bash
+uv run mcp-simple-auth --transport streamable-http
+```
+
+Streamable HTTP transport provides endpoint:
+- `/mcp`
+
+
+This ensures backward compatibility without needing multiple server instances. When using SSE transport (`--transport sse`), only the `/sse` endpoint is available.
+
 ## Available Tool
 
 ### get_user_profile
@@ -61,5 +86,6 @@ 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
+4. The transport specified is valid (`sse` or `streamable-http`)
 
 You can use [Inspector](https://github.com/modelcontextprotocol/inspector) to test Auth

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

@@ -3,10 +3,9 @@
 import logging
 import secrets
 import time
-from typing import Any
+from typing import Any, Literal
 
 import click
-import httpx
 from pydantic import AnyHttpUrl
 from pydantic_settings import BaseSettings, SettingsConfigDict
 from starlette.exceptions import HTTPException
@@ -24,6 +23,7 @@
 )
 from mcp.server.auth.settings import AuthSettings, ClientRegistrationOptions
 from mcp.server.fastmcp.server import FastMCP
+from mcp.shared._httpx_utils import create_mcp_http_client
 from mcp.shared.auth import OAuthClientInformationFull, OAuthToken
 
 logger = logging.getLogger(__name__)
@@ -123,7 +123,7 @@ async def handle_github_callback(self, code: str, state: str) -> str:
         client_id = state_data["client_id"]
 
         # Exchange code for token with GitHub
-        async with httpx.AsyncClient() as client:
+        async with create_mcp_http_client() as client:
             response = await client.post(
                 self.settings.github_token_url,
                 data={
@@ -325,7 +325,7 @@ async def get_user_profile() -> dict[str, Any]:
         """
         github_token = get_github_token()
 
-        async with httpx.AsyncClient() as client:
+        async with create_mcp_http_client() as client:
             response = await client.get(
                 "https://api.github.com/user",
                 headers={
@@ -347,7 +347,13 @@ async def get_user_profile() -> dict[str, Any]:
 @click.command()
 @click.option("--port", default=8000, help="Port to listen on")
 @click.option("--host", default="localhost", help="Host to bind to")
-def main(port: int, host: str) -> int:
+@click.option(
+    "--transport",
+    default="sse",
+    type=click.Choice(["sse", "streamable-http"]),
+    help="Transport protocol to use ('sse' or 'streamable-http')",
+)
+def main(port: int, host: str, transport: Literal["sse", "streamable-http"]) -> int:
     """Run the simple GitHub MCP server."""
     logging.basicConfig(level=logging.INFO)
 
@@ -364,5 +370,6 @@ def main(port: int, host: str) -> int:
         return 1
 
     mcp_server = create_simple_mcp_server(settings)
-    mcp_server.run(transport="sse")
+    logger.info(f"Starting server with {transport} transport")
+    mcp_server.run(transport=transport)
     return 0

examples/servers/simple-streamablehttp-stateless/mcp_simple_streamablehttp_stateless/server.py

@@ -1,37 +1,17 @@
 import contextlib
 import logging
+from collections.abc import AsyncIterator
 
 import anyio
 import click
 import mcp.types as types
 from mcp.server.lowlevel import Server
-from mcp.server.streamable_http import (
-    StreamableHTTPServerTransport,
-)
+from mcp.server.streamable_http_manager import StreamableHTTPSessionManager
 from starlette.applications import Starlette
 from starlette.routing import Mount
+from starlette.types import Receive, Scope, Send
 
 logger = logging.getLogger(__name__)
-# Global task group that will be initialized in the lifespan
-task_group = None
-
-
-@contextlib.asynccontextmanager
-async def lifespan(app):
-    """Application lifespan context manager for managing task group."""
-    global task_group
-
-    async with anyio.create_task_group() as tg:
-        task_group = tg
-        logger.info("Application started, task group initialized!")
-        try:
-            yield
-        finally:
-            logger.info("Application shutting down, cleaning up resources...")
-            if task_group:
-                tg.cancel_scope.cancel()
-                task_group = None
-            logger.info("Resources cleaned up successfully.")
 
 
 @click.command()
@@ -122,35 +102,28 @@ async def list_tools() -> list[types.Tool]:
             )
         ]
 
-    # ASGI handler for stateless HTTP connections
-    async def handle_streamable_http(scope, receive, send):
-        logger.debug("Creating new transport")
-        # Use lock to prevent race conditions when creating new sessions
-        http_transport = StreamableHTTPServerTransport(
-            mcp_session_id=None,
-            is_json_response_enabled=json_response,
-        )
-        async with http_transport.connect() as streams:
-            read_stream, write_stream = streams
-
-            if not task_group:
-                raise RuntimeError("Task group is not initialized")
-
-            async def run_server():
-                await app.run(
-                    read_stream,
-                    write_stream,
-                    app.create_initialization_options(),
-                    # Runs in standalone mode for stateless deployments
-                    # where clients perform initialization with any node
-                    stateless=True,
-                )
-
-            # Start server task
-            task_group.start_soon(run_server)
-
-            # Handle the HTTP request and return the response
-            await http_transport.handle_request(scope, receive, send)
+    # Create the session manager with true stateless mode
+    session_manager = StreamableHTTPSessionManager(
+        app=app,
+        event_store=None,
+        json_response=json_response,
+        stateless=True,
+    )
+
+    async def handle_streamable_http(
+        scope: Scope, receive: Receive, send: Send
+    ) -> None:
+        await session_manager.handle_request(scope, receive, send)
+
+    @contextlib.asynccontextmanager
+    async def lifespan(app: Starlette) -> AsyncIterator[None]:
+        """Context manager for session manager."""
+        async with session_manager.run():
+            logger.info("Application started with StreamableHTTP session manager!")
+            try:
+                yield
+            finally:
+                logger.info("Application shutting down...")
 
     # Create an ASGI application using the transport
     starlette_app = Starlette(