Merge branch 'outputSchema' of https://github.com/davemssavage/python-sdk into outputSchema

Author: davemssavage

.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):

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/__main__.py

@@ -4,4 +4,4 @@
 
 from mcp_simple_auth.server import main
 
-sys.exit(main())
+sys.exit(main())  # type: ignore[call-arg]

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

@@ -3,7 +3,7 @@
 import logging
 import secrets
 import time
-from typing import Any
+from typing import Any, Literal
 
 import click
 from pydantic import AnyHttpUrl
@@ -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-prompt/mcp_simple_prompt/__main__.py

@@ -2,4 +2,4 @@
 
 from .server import main
 
-sys.exit(main())
+sys.exit(main())  # type: ignore[call-arg]

examples/servers/simple-resource/mcp_simple_resource/__main__.py

@@ -2,4 +2,4 @@
 
 from .server import main
 
-sys.exit(main())
+sys.exit(main())  # type: ignore[call-arg]

examples/servers/simple-resource/mcp_simple_resource/server.py

@@ -2,7 +2,7 @@
 import click
 import mcp.types as types
 from mcp.server.lowlevel import Server
-from pydantic import FileUrl
+from pydantic import AnyUrl
 
 SAMPLE_RESOURCES = {
     "greeting": "Hello! This is a sample text resource.",
@@ -26,7 +26,7 @@ def main(port: int, transport: str) -> int:
     async def list_resources() -> list[types.Resource]:
         return [
             types.Resource(
-                uri=FileUrl(f"file:///{name}.txt"),
+                uri=AnyUrl(f"file:///{name}.txt"),
                 name=name,
                 description=f"A sample text resource named {name}",
                 mimeType="text/plain",
@@ -35,7 +35,9 @@ async def list_resources() -> list[types.Resource]:
         ]
 
     @app.read_resource()
-    async def read_resource(uri: FileUrl) -> str | bytes:
+    async def read_resource(uri: AnyUrl) -> str | bytes:
+        if uri.path is None:
+            raise ValueError(f"Invalid resource path: {uri}")
         name = uri.path.replace(".txt", "").lstrip("/")
 
         if name not in SAMPLE_RESOURCES:

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

@@ -1,4 +1,7 @@
 from .server import main
 
 if __name__ == "__main__":
-    main()
+    # Click will handle CLI arguments
+    import sys
+
+    sys.exit(main())  # type: ignore[call-arg]