Merge branch 'main' of https://github.com/modelcontextprotocol/python-sdk into feat/rfc7523

Author: LucaButBoring

.gitattribute

@@ -0,0 +1,2 @@
+# Generated
+uv.lock  linguist-generated=true

.gitignore

@@ -52,6 +52,7 @@ coverage.xml
 *.py,cover
 .hypothesis/
 .pytest_cache/
+.ruff_cache/
 cover/
 
 # Translations
@@ -168,3 +169,6 @@ cython_debug/
 .vscode/
 .windsurfrules
 **/CLAUDE.local.md
+
+# claude code
+.claude/

.pre-commit-config.yaml

@@ -25,22 +25,22 @@ repos:
     hooks:
       - id: ruff-format
         name: Ruff Format
-        entry: uv run ruff
+        entry: uv run --frozen ruff
         args: [format]
         language: system
         types: [python]
         pass_filenames: false
       - id: ruff
         name: Ruff
-        entry: uv run ruff
+        entry: uv run --frozen ruff
         args: ["check", "--fix", "--exit-non-zero-on-fix"]
         types: [python]
         language: system
         pass_filenames: false
         exclude: ^README\.md$
       - id: pyright
         name: pyright
-        entry: uv run pyright
+        entry: uv run --frozen pyright
         language: system
         types: [python]
         pass_filenames: false
@@ -52,7 +52,7 @@ repos:
         pass_filenames: false
       - id: readme-snippets
         name: Check README snippets are up to date
-        entry: uv run scripts/update_readme_snippets.py --check
+        entry: uv run --frozen python scripts/update_readme_snippets.py --check
         language: system
         files: ^(README\.md|examples/.*\.py|scripts/update_readme_snippets\.py)$
         pass_filenames: false

README.md

@@ -31,22 +31,33 @@
     - [Prompts](#prompts)
     - [Images](#images)
     - [Context](#context)
+      - [Getting Context in Functions](#getting-context-in-functions)
+      - [Context Properties and Methods](#context-properties-and-methods)
     - [Completions](#completions)
     - [Elicitation](#elicitation)
     - [Sampling](#sampling)
     - [Logging and Notifications](#logging-and-notifications)
     - [Authentication](#authentication)
     - [FastMCP Properties](#fastmcp-properties)
-    - [Session Properties](#session-properties-and-methods)
+    - [Session Properties and Methods](#session-properties-and-methods)
     - [Request Context Properties](#request-context-properties)
   - [Running Your Server](#running-your-server)
     - [Development Mode](#development-mode)
     - [Claude Desktop Integration](#claude-desktop-integration)
     - [Direct Execution](#direct-execution)
     - [Streamable HTTP Transport](#streamable-http-transport)
+      - [CORS Configuration for Browser-Based Clients](#cors-configuration-for-browser-based-clients)
     - [Mounting to an Existing ASGI Server](#mounting-to-an-existing-asgi-server)
+      - [StreamableHTTP servers](#streamablehttp-servers)
+        - [Basic mounting](#basic-mounting)
+        - [Host-based routing](#host-based-routing)
+        - [Multiple servers with path configuration](#multiple-servers-with-path-configuration)
+        - [Path configuration at initialization](#path-configuration-at-initialization)
+      - [SSE servers](#sse-servers)
   - [Advanced Usage](#advanced-usage)
     - [Low-Level Server](#low-level-server)
+      - [Structured Output Support](#structured-output-support)
+    - [Pagination (Advanced)](#pagination-advanced)
     - [Writing MCP Clients](#writing-mcp-clients)
     - [Client Display Utilities](#client-display-utilities)
     - [OAuth Authentication for Clients](#oauth-authentication-for-clients)
@@ -400,7 +411,7 @@ def get_weather(city: str) -> WeatherData:
     """Get weather for a city - returns structured data."""
     # Simulated weather data
     return WeatherData(
-        temperature=72.5,
+        temperature=22.5,
         humidity=45.0,
         condition="sunny",
         wind_speed=5.2,
@@ -505,6 +516,41 @@ def debug_error(error: str) -> list[base.Message]:
 _Full example: [examples/snippets/servers/basic_prompt.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/basic_prompt.py)_
 <!-- /snippet-source -->
 
+### Icons
+
+MCP servers can provide icons for UI display. Icons can be added to the server implementation, tools, resources, and prompts:
+
+```python
+from mcp.server.fastmcp import FastMCP, Icon
+
+# Create an icon from a file path or URL
+icon = Icon(
+    src="icon.png",
+    mimeType="image/png",
+    sizes="64x64"
+)
+
+# Add icons to server
+mcp = FastMCP(
+    "My Server",
+    website_url="https://example.com",
+    icons=[icon]
+)
+
+# Add icons to tools, resources, and prompts
+@mcp.tool(icons=[icon])
+def my_tool():
+    """Tool with an icon."""
+    return "result"
+
+@mcp.resource("demo://resource", icons=[icon])
+def my_resource():
+    """Resource with an icon."""
+    return "content"
+```
+
+_Full example: [examples/fastmcp/icons_demo.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/fastmcp/icons_demo.py)_
+
 ### Images
 
 FastMCP provides an `Image` class that automatically handles image data:
@@ -736,6 +782,8 @@ async def book_table(date: str, time: str, party_size: int, ctx: Context[ServerS
 _Full example: [examples/snippets/servers/elicitation.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/elicitation.py)_
 <!-- /snippet-source -->
 
+Elicitation schemas support default values for all field types. Default values are automatically included in the JSON schema sent to clients, allowing them to pre-populate forms.
+
 The `elicit()` method returns an `ElicitationResult` with:
 
 - `action`: "accept", "decline", or "cancel"
@@ -885,6 +933,8 @@ The FastMCP server instance accessible via `ctx.fastmcp` provides access to serv
 
 - `ctx.fastmcp.name` - The server's name as defined during initialization
 - `ctx.fastmcp.instructions` - Server instructions/description provided to clients
+- `ctx.fastmcp.website_url` - Optional website URL for the server
+- `ctx.fastmcp.icons` - Optional list of icons for UI display
 - `ctx.fastmcp.settings` - Complete server configuration object containing:
   - `debug` - Debug mode flag
   - `log_level` - Current logging level
@@ -1727,6 +1777,116 @@ Tools can return data in three ways:
 
 When an `outputSchema` is defined, the server automatically validates the structured output against the schema. This ensures type safety and helps catch errors early.
 
+### Pagination (Advanced)
+
+For servers that need to handle large datasets, the low-level server provides paginated versions of list operations. This is an optional optimization - most servers won't need pagination unless they're dealing with hundreds or thousands of items.
+
+#### Server-side Implementation
+
+<!-- snippet-source examples/snippets/servers/pagination_example.py -->
+```python
+"""
+Example of implementing pagination with MCP server decorators.
+"""
+
+from pydantic import AnyUrl
+
+import mcp.types as types
+from mcp.server.lowlevel import Server
+
+# Initialize the server
+server = Server("paginated-server")
+
+# Sample data to paginate
+ITEMS = [f"Item {i}" for i in range(1, 101)]  # 100 items
+
+
+@server.list_resources()
+async def list_resources_paginated(request: types.ListResourcesRequest) -> types.ListResourcesResult:
+    """List resources with pagination support."""
+    page_size = 10
+
+    # Extract cursor from request params
+    cursor = request.params.cursor if request.params is not None else None
+
+    # Parse cursor to get offset
+    start = 0 if cursor is None else int(cursor)
+    end = start + page_size
+
+    # Get page of resources
+    page_items = [
+        types.Resource(uri=AnyUrl(f"resource://items/{item}"), name=item, description=f"Description for {item}")
+        for item in ITEMS[start:end]
+    ]
+
+    # Determine next cursor
+    next_cursor = str(end) if end < len(ITEMS) else None
+
+    return types.ListResourcesResult(resources=page_items, nextCursor=next_cursor)
+```
+
+_Full example: [examples/snippets/servers/pagination_example.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/pagination_example.py)_
+<!-- /snippet-source -->
+
+#### Client-side Consumption
+
+<!-- snippet-source examples/snippets/clients/pagination_client.py -->
+```python
+"""
+Example of consuming paginated MCP endpoints from a client.
+"""
+
+import asyncio
+
+from mcp.client.session import ClientSession
+from mcp.client.stdio import StdioServerParameters, stdio_client
+from mcp.types import Resource
+
+
+async def list_all_resources() -> None:
+    """Fetch all resources using pagination."""
+    async with stdio_client(StdioServerParameters(command="uv", args=["run", "mcp-simple-pagination"])) as (
+        read,
+        write,
+    ):
+        async with ClientSession(read, write) as session:
+            await session.initialize()
+
+            all_resources: list[Resource] = []
+            cursor = None
+
+            while True:
+                # Fetch a page of resources
+                result = await session.list_resources(cursor=cursor)
+                all_resources.extend(result.resources)
+
+                print(f"Fetched {len(result.resources)} resources")
+
+                # Check if there are more pages
+                if result.nextCursor:
+                    cursor = result.nextCursor
+                else:
+                    break
+
+            print(f"Total resources: {len(all_resources)}")
+
+
+if __name__ == "__main__":
+    asyncio.run(list_all_resources())
+```
+
+_Full example: [examples/snippets/clients/pagination_client.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/clients/pagination_client.py)_
+<!-- /snippet-source -->
+
+#### Key Points
+
+- **Cursors are opaque strings** - the server defines the format (numeric offsets, timestamps, etc.)
+- **Return `nextCursor=None`** when there are no more pages
+- **Backward compatible** - clients that don't support pagination will still work (they'll just get the first page)
+- **Flexible page sizes** - Each endpoint can define its own page size based on data characteristics
+
+See the [simple-pagination example](examples/servers/simple-pagination) for a complete implementation.
+
 ### 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):
@@ -2137,6 +2297,7 @@ MCP servers declare capabilities during initialization:
 
 ## Documentation
 
+- [API Reference](https://modelcontextprotocol.github.io/python-sdk/api/)
 - [Model Context Protocol documentation](https://modelcontextprotocol.io)
 - [Model Context Protocol specification](https://spec.modelcontextprotocol.io)
 - [Officially supported servers](https://github.com/modelcontextprotocol/servers)

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

@@ -71,4 +71,4 @@ mcp> quit
 ## Configuration
 
 - `MCP_SERVER_PORT` - Server URL (default: 8000)
-- `MCP_TRANSPORT_TYPE` - Transport type: `streamable_http` (default) or `sse`
+- `MCP_TRANSPORT_TYPE` - Transport type: `streamable-http` (default) or `sse`

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

@@ -150,7 +150,7 @@ def get_state(self):
 class SimpleAuthClient:
     """Simple MCP client with auth support."""
 
-    def __init__(self, server_url: str, transport_type: str = "streamable_http"):
+    def __init__(self, server_url: str, transport_type: str = "streamable-http"):
         self.server_url = server_url
         self.transport_type = transport_type
         self.session: ClientSession | None = None
@@ -334,10 +334,10 @@ async def main():
     # Default server URL - can be overridden with environment variable
     # Most MCP streamable HTTP servers use /mcp as the endpoint
     server_url = os.getenv("MCP_SERVER_PORT", 8000)
-    transport_type = os.getenv("MCP_TRANSPORT_TYPE", "streamable_http")
+    transport_type = os.getenv("MCP_TRANSPORT_TYPE", "streamable-http")
     server_url = (
         f"http://localhost:{server_url}/mcp"
-        if transport_type == "streamable_http"
+        if transport_type == "streamable-http"
         else f"http://localhost:{server_url}/sse"
     )
 

examples/fastmcp/icons_demo.py

@@ -0,0 +1,55 @@
+"""
+FastMCP Icons Demo Server
+
+Demonstrates using icons with tools, resources, prompts, and implementation.
+"""
+
+import base64
+from pathlib import Path
+
+from mcp.server.fastmcp import FastMCP, Icon
+
+# Load the icon file and convert to data URI
+icon_path = Path(__file__).parent / "mcp.png"
+icon_data = base64.standard_b64encode(icon_path.read_bytes()).decode()
+icon_data_uri = f"data:image/png;base64,{icon_data}"
+
+icon_data = Icon(src=icon_data_uri, mimeType="image/png", sizes=["64x64"])
+
+# Create server with icons in implementation
+mcp = FastMCP("Icons Demo Server", website_url="https://github.com/modelcontextprotocol/python-sdk", icons=[icon_data])
+
+
+@mcp.tool(icons=[icon_data])
+def demo_tool(message: str) -> str:
+    """A demo tool with an icon."""
+    return message
+
+
+@mcp.resource("demo://readme", icons=[icon_data])
+def readme_resource() -> str:
+    """A demo resource with an icon"""
+    return "This resource has an icon"
+
+
+@mcp.prompt("prompt_with_icon", icons=[icon_data])
+def prompt_with_icon(text: str) -> str:
+    """A demo prompt with an icon"""
+    return text
+
+
+@mcp.tool(
+    icons=[
+        Icon(src=icon_data_uri, mimeType="image/png", sizes=["16x16"]),
+        Icon(src=icon_data_uri, mimeType="image/png", sizes=["32x32"]),
+        Icon(src=icon_data_uri, mimeType="image/png", sizes=["64x64"]),
+    ]
+)
+def multi_icon_tool(action: str) -> str:
+    """A tool demonstrating multiple icons."""
+    return "multi_icon_tool"
+
+
+if __name__ == "__main__":
+    # Run the server
+    mcp.run()