Merge branch 'main' into client_notif_support

Author: kylestratis

.github/workflows/shared.yml

@@ -35,7 +35,7 @@ jobs:
     continue-on-error: true
     strategy:
       matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
+        python-version: ["3.10", "3.11", "3.12", "3.13", "3.14"]
         dep-resolution:
           - name: lowest-direct
             install-flags: "--upgrade --resolution lowest-direct"

CONTRIBUTING.md

@@ -2,6 +2,43 @@
 
 Thank you for your interest in contributing to the MCP Python SDK! This document provides guidelines and instructions for contributing.
 
+## Before You Start
+
+We welcome contributions! These guidelines exist to save everyone time, yours included. Following them means your work is more likely to be accepted.
+
+**All pull requests require a corresponding issue.** Unless your change is trivial (typo, docs tweak, broken link), create an issue first. Every merged feature becomes ongoing maintenance, so we need to agree something is worth doing before reviewing code. PRs without a linked issue will be closed.
+
+Having an issue doesn't guarantee acceptance. Wait for maintainer feedback or a `ready for work` label before starting. PRs for issues without buy-in may also be closed.
+
+Use issues to validate your idea before investing time in code. PRs are for execution, not exploration.
+
+### The SDK is Opinionated
+
+Not every contribution will be accepted, even with a working implementation. We prioritize maintainability and consistency over adding capabilities. This is at maintainers' discretion.
+
+### What Needs Discussion
+
+These always require an issue first:
+
+- New public APIs or decorators
+- Architectural changes or refactoring
+- Changes that touch multiple modules
+- Features that might require spec changes (these need a [SEP](https://github.com/modelcontextprotocol/modelcontextprotocol) first)
+
+Bug fixes for clear, reproducible issues are welcome—but still create an issue to track the fix.
+
+### Finding Issues to Work On
+
+| Label | For | Description |
+|-------|-----|-------------|
+| [`good first issue`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22good+first+issue%22) | Newcomers | Can tackle without deep codebase knowledge |
+| [`help wanted`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) | Experienced contributors | Maintainers probably won't get to this |
+| [`ready for work`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22ready+for+work%22) | Maintainers | Triaged and ready for a maintainer to pick up |
+
+Issues labeled `needs confirmation` or `needs maintainer action` are **not** ready for work—wait for maintainer input first.
+
+Before starting, comment on the issue so we can assign it to you. This prevents duplicate effort.
+
 ## Development Setup
 
 1. Make sure you have Python 3.10+ installed
@@ -76,13 +113,29 @@ pre-commit run --all-files
 - Add type hints to all functions
 - Include docstrings for public APIs
 
-## Pull Request Process
+## Pull Requests
+
+By the time you open a PR, the "what" and "why" should already be settled in an issue. This keeps reviews focused on implementation.
+
+### Scope
+
+Small PRs get reviewed fast. Large PRs sit in the queue.
+
+A few dozen lines can be reviewed in minutes. Hundreds of lines across many files takes real effort and things slip through. If your change is big, break it into smaller PRs or get alignment from a maintainer first.
+
+### What Gets Rejected
+
+- **No prior discussion**: Features or significant changes without an approved issue
+- **Scope creep**: Changes that go beyond what was discussed
+- **Misalignment**: Even well-implemented features may be rejected if they don't fit the SDK's direction
+- **Overengineering**: Unnecessary complexity for simple problems
+
+### Checklist
 
 1. Update documentation as needed
 2. Add tests for new functionality
 3. Ensure CI passes
-4. Maintainers will review your code
-5. Address review feedback
+4. Address review feedback
 
 ## Code of Conduct
 

examples/clients/conformance-auth-client/mcp_conformance_auth_client/__init__.py

@@ -29,7 +29,8 @@
 import logging
 import os
 import sys
-from urllib.parse import ParseResult, parse_qs, urlparse
+from typing import Any, cast
+from urllib.parse import parse_qs, urlparse
 
 import httpx
 from mcp import ClientSession
@@ -39,12 +40,12 @@
     PrivateKeyJWTOAuthProvider,
     SignedJWTParameters,
 )
-from mcp.client.streamable_http import streamablehttp_client
+from mcp.client.streamable_http import streamable_http_client
 from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata, OAuthToken
 from pydantic import AnyUrl
 
 
-def get_conformance_context() -> dict:
+def get_conformance_context() -> dict[str, Any]:
     """Load conformance test context from MCP_CONFORMANCE_CONTEXT environment variable."""
     context_json = os.environ.get("MCP_CONFORMANCE_CONTEXT")
     if not context_json:
@@ -116,9 +117,9 @@ async def handle_redirect(self, authorization_url: str) -> None:
 
             # Check for redirect response
             if response.status_code in (301, 302, 303, 307, 308):
-                location = response.headers.get("location")
+                location = cast(str, response.headers.get("location"))
                 if location:
-                    redirect_url: ParseResult = urlparse(location)
+                    redirect_url = urlparse(location)
                     query_params: dict[str, list[str]] = parse_qs(redirect_url.query)
 
                     if "code" in query_params:
@@ -259,12 +260,8 @@ async def run_client_credentials_basic_client(server_url: str) -> None:
 async def _run_session(server_url: str, oauth_auth: OAuthClientProvider) -> None:
     """Common session logic for all OAuth flows."""
     # Connect using streamable HTTP transport with OAuth
-    async with streamablehttp_client(
-        url=server_url,
-        auth=oauth_auth,
-        timeout=30.0,
-        sse_read_timeout=60.0,
-    ) as (read_stream, write_stream, _):
+    client = httpx.AsyncClient(auth=oauth_auth, timeout=30.0)
+    async with streamable_http_client(url=server_url, http_client=client) as (read_stream, write_stream, _):
         async with ClientSession(read_stream, write_stream) as session:
             # Initialize the session
             await session.initialize()

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

@@ -12,63 +12,87 @@ A demonstration of how to use the MCP Python SDK with OAuth authentication over
 
 ```bash
 cd examples/clients/simple-auth-client
-uv sync --reinstall 
+uv sync --reinstall
 ```
 
 ## Usage
 
 ### 1. Start an MCP server with OAuth support
 
+The simple-auth server example provides three server configurations. See [examples/servers/simple-auth/README.md](../../servers/simple-auth/README.md) for full details.
+
+#### Option A: New Architecture (Recommended)
+
+Separate Authorization Server and Resource Server:
+
+```bash
+# Terminal 1: Start Authorization Server on port 9000
+cd examples/servers/simple-auth
+uv run mcp-simple-auth-as --port=9000
+
+# Terminal 2: Start Resource Server on port 8001
+cd examples/servers/simple-auth
+uv run mcp-simple-auth-rs --port=8001 --auth-server=http://localhost:9000 --transport=streamable-http
+```
+
+#### Option B: Legacy Server (Backwards Compatibility)
+
 ```bash
-# Example with mcp-simple-auth
-cd path/to/mcp-simple-auth
-uv run mcp-simple-auth --transport streamable-http --port 3001
+# Single server that acts as both AS and RS (port 8000)
+cd examples/servers/simple-auth
+uv run mcp-simple-auth-legacy --port=8000 --transport=streamable-http
 ```
 
 ### 2. Run the client
 
 ```bash
-uv run mcp-simple-auth-client
+# Connect to Resource Server (new architecture, default port 8001)
+MCP_SERVER_PORT=8001 uv run mcp-simple-auth-client
 
-# Or with custom server URL
-MCP_SERVER_PORT=3001 uv run mcp-simple-auth-client
+# Connect to Legacy Server (port 8000)
+uv run mcp-simple-auth-client
 
 # Use SSE transport
-MCP_TRANSPORT_TYPE=sse uv run mcp-simple-auth-client
+MCP_SERVER_PORT=8001 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  
+- `call <tool_name> [args]` - Call a tool with optional JSON arguments
 - `quit` - Exit
 
 ## Example
 
 ```markdown
-🔐 Simple MCP Auth Client
-Connecting to: http://localhost:3001
+🚀 Simple MCP Auth Client
+Connecting to: http://localhost:8001/mcp
+Transport type: streamable-http
 
-Please visit the following URL to authorize the application:
-http://localhost:3001/authorize?response_type=code&client_id=...
+🔗 Attempting to connect to http://localhost:8001/mcp...
+📡 Opening StreamableHTTP transport connection with auth...
+Opening browser for authorization: http://localhost:9000/authorize?...
 
-✅ Connected to MCP server at http://localhost:3001
+✅ Connected to MCP server at http://localhost:8001/mcp
 
 mcp> list
 📋 Available tools:
-1. echo - Echo back the input text
+1. get_time
+   Description: Get the current server time.
 
-mcp> call echo {"text": "Hello, world!"}
-🔧 Tool 'echo' result:
-Hello, world!
+mcp> call get_time
+🔧 Tool 'get_time' result:
+{"current_time": "2024-01-15T10:30:00", "timezone": "UTC", ...}
 
 mcp> quit
-👋 Goodbye!
 ```
 
 ## Configuration
 
-- `MCP_SERVER_PORT` - Server URL (default: 8000)
-- `MCP_TRANSPORT_TYPE` - Transport type: `streamable-http` (default) or `sse`
+| Environment Variable | Description | Default |
+|---------------------|-------------|---------|
+| `MCP_SERVER_PORT` | Port number of the MCP server | `8000` |
+| `MCP_TRANSPORT_TYPE` | Transport type: `streamable-http` or `sse` | `streamable-http` |
+| `MCP_CLIENT_METADATA_URL` | Optional URL for client metadata (CIMD) | None |

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

@@ -6,21 +6,26 @@
 
 """
 
+from __future__ import annotations as _annotations
+
 import asyncio
 import os
+import socketserver
 import threading
 import time
 import webbrowser
 from http.server import BaseHTTPRequestHandler, HTTPServer
-from typing import Any
+from typing import Any, Callable
 from urllib.parse import parse_qs, urlparse
 
 import httpx
+from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
 from mcp.client.auth import OAuthClientProvider, TokenStorage
 from mcp.client.session import ClientSession
 from mcp.client.sse import sse_client
 from mcp.client.streamable_http import streamable_http_client
 from mcp.shared.auth import OAuthClientInformationFull, OAuthClientMetadata, OAuthToken
+from mcp.shared.message import SessionMessage
 
 
 class InMemoryTokenStorage(TokenStorage):
@@ -46,7 +51,13 @@ async def set_client_info(self, client_info: OAuthClientInformationFull) -> None
 class CallbackHandler(BaseHTTPRequestHandler):
     """Simple HTTP handler to capture OAuth callback."""
 
-    def __init__(self, request, client_address, server, callback_data):
+    def __init__(
+        self,
+        request: Any,
+        client_address: tuple[str, int],
+        server: socketserver.BaseServer,
+        callback_data: dict[str, Any],
+    ):
         """Initialize with callback data storage."""
         self.callback_data = callback_data
         super().__init__(request, client_address, server)
@@ -91,15 +102,14 @@ def do_GET(self):
             self.send_response(404)
             self.end_headers()
 
-    def log_message(self, format, *args):
+    def log_message(self, format: str, *args: Any):
         """Suppress default logging."""
-        pass
 
 
 class CallbackServer:
     """Simple server to handle OAuth callbacks."""
 
-    def __init__(self, port=3000):
+    def __init__(self, port: int = 3000):
         self.port = port
         self.server = None
         self.thread = None
@@ -110,7 +120,12 @@ def _create_handler_with_data(self):
         callback_data = self.callback_data
 
         class DataCallbackHandler(CallbackHandler):
-            def __init__(self, request, client_address, server):
+            def __init__(
+                self,
+                request: BaseHTTPRequestHandler,
+                client_address: tuple[str, int],
+                server: socketserver.BaseServer,
+            ):
                 super().__init__(request, client_address, server, callback_data)
 
         return DataCallbackHandler
@@ -131,7 +146,7 @@ def stop(self):
         if self.thread:
             self.thread.join(timeout=1)
 
-    def wait_for_callback(self, timeout=300):
+    def wait_for_callback(self, timeout: int = 300):
         """Wait for OAuth callback with timeout."""
         start_time = time.time()
         while time.time() - start_time < timeout:
@@ -225,7 +240,12 @@ async def _default_redirect_handler(authorization_url: str) -> None:
 
             traceback.print_exc()
 
-    async def _run_session(self, read_stream, write_stream, get_session_id):
+    async def _run_session(
+        self,
+        read_stream: MemoryObjectReceiveStream[SessionMessage | Exception],
+        write_stream: MemoryObjectSendStream[SessionMessage],
+        get_session_id: Callable[[], str | None] | None = None,
+    ):
         """Run the MCP session with the given streams."""
         print("🤝 Initializing MCP session...")
         async with ClientSession(read_stream, write_stream) as session:
@@ -314,7 +334,7 @@ async def interactive_loop(self):
                         continue
 
                     # Parse arguments (simple JSON-like format)
-                    arguments = {}
+                    arguments: dict[str, Any] = {}
                     if len(parts) > 2:
                         import json