Merge branch 'modelcontextprotocol:main' into main

Author: DebajitKumarPhukan

README.md

@@ -57,6 +57,7 @@
   - [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)
@@ -1737,6 +1738,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):

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

@@ -0,0 +1,33 @@
+"""
+FastMCP Echo Server that sends log messages and progress updates to the client
+"""
+
+import asyncio
+
+from mcp.server.fastmcp import Context, FastMCP
+
+# Create server
+mcp = FastMCP("Echo Server with logging and progress updates")
+
+
+@mcp.tool()
+async def echo(text: str, ctx: Context) -> str:
+    """Echo the input text sending log messages and progress updates during processing."""
+    await ctx.report_progress(progress=0, total=100)
+    await ctx.info("Starting to process echo for input: " + text)
+
+    await asyncio.sleep(2)
+
+    await ctx.info("Halfway through processing echo for input: " + text)
+    await ctx.report_progress(progress=50, total=100)
+
+    await asyncio.sleep(2)
+
+    await ctx.info("Finished processing echo for input: " + text)
+    await ctx.report_progress(progress=100, total=100)
+
+    # Progress notifications are process asynchronously by the client.
+    # A small delay here helps ensure the last notification is processed by the client.
+    await asyncio.sleep(0.1)
+
+    return text

examples/servers/simple-auth/README.md

@@ -43,7 +43,7 @@ uv run mcp-simple-auth-rs --port=8001 --auth-server=http://localhost:9000  --tra
 ```bash
 cd examples/clients/simple-auth-client
 # Start client with streamable HTTP
-MCP_SERVER_PORT=8001 MCP_TRANSPORT_TYPE=streamable_http uv run mcp-simple-auth-client
+MCP_SERVER_PORT=8001 MCP_TRANSPORT_TYPE=streamable-http uv run mcp-simple-auth-client
 ```
 
 ## How It Works
@@ -101,7 +101,7 @@ uv run mcp-simple-auth-legacy --port=8002
 ```bash
 # Test with client (will automatically fall back to legacy discovery)
 cd examples/clients/simple-auth-client
-MCP_SERVER_PORT=8002 MCP_TRANSPORT_TYPE=streamable_http uv run mcp-simple-auth-client
+MCP_SERVER_PORT=8002 MCP_TRANSPORT_TYPE=streamable-http uv run mcp-simple-auth-client
 ```
 
 The client will:

examples/servers/simple-pagination/README.md

@@ -0,0 +1,77 @@
+# MCP Simple Pagination
+
+A simple MCP server demonstrating pagination for tools, resources, and prompts using cursor-based pagination.
+
+## Usage
+
+Start the server using either stdio (default) or SSE transport:
+
+```bash
+# Using stdio transport (default)
+uv run mcp-simple-pagination
+
+# Using SSE transport on custom port
+uv run mcp-simple-pagination --transport sse --port 8000
+```
+
+The server exposes:
+
+- 25 tools (paginated, 5 per page)
+- 30 resources (paginated, 10 per page)
+- 20 prompts (paginated, 7 per page)
+
+Each paginated list returns a `nextCursor` when more pages are available. Use this cursor in subsequent requests to retrieve the next page.
+
+## Example
+
+Using the MCP client, you can retrieve paginated items like this using the STDIO transport:
+
+```python
+import asyncio
+from mcp.client.session import ClientSession
+from mcp.client.stdio import StdioServerParameters, stdio_client
+
+
+async def main():
+    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()
+
+            # Get first page of tools
+            tools_page1 = await session.list_tools()
+            print(f"First page: {len(tools_page1.tools)} tools")
+            print(f"Next cursor: {tools_page1.nextCursor}")
+
+            # Get second page using cursor
+            if tools_page1.nextCursor:
+                tools_page2 = await session.list_tools(cursor=tools_page1.nextCursor)
+                print(f"Second page: {len(tools_page2.tools)} tools")
+
+            # Similarly for resources
+            resources_page1 = await session.list_resources()
+            print(f"First page: {len(resources_page1.resources)} resources")
+
+            # And for prompts
+            prompts_page1 = await session.list_prompts()
+            print(f"First page: {len(prompts_page1.prompts)} prompts")
+
+
+asyncio.run(main())
+```
+
+## Pagination Details
+
+The server uses simple numeric indices as cursors for demonstration purposes. In production scenarios, you might use:
+
+- Database offsets or row IDs
+- Timestamps for time-based pagination
+- Opaque tokens encoding pagination state
+
+The pagination implementation demonstrates:
+
+- Handling `None` cursor for the first page
+- Returning `nextCursor` when more data exists
+- Gracefully handling invalid cursors
+- Different page sizes for different resource types

examples/servers/simple-pagination/mcp_simple_pagination/__init__.py

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