chore: import upstream snapshot with attribution

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 Streamable HTTP transport:
+
+```bash
+# Using stdio transport (default)
+uv run mcp-simple-pagination
+
+# Using Streamable HTTP transport on custom port
+uv run mcp-simple-pagination --transport streamable-http --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/__main__.py

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

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

@@ -0,0 +1,176 @@
+"""Simple MCP server demonstrating pagination for tools, resources, and prompts.
+
+This example shows how to implement pagination with the low-level server API
+to handle large lists of items that need to be split across multiple pages.
+"""
+
+from typing import TypeVar
+
+import anyio
+import click
+import mcp_types as types
+from mcp.server import Server, ServerRequestContext
+
+T = TypeVar("T")
+
+# Sample data - in real scenarios, this might come from a database
+SAMPLE_TOOLS = [
+    types.Tool(
+        name=f"tool_{i}",
+        title=f"Tool {i}",
+        description=f"This is sample tool number {i}",
+        input_schema={"type": "object", "properties": {"input": {"type": "string"}}},
+    )
+    for i in range(1, 26)  # 25 tools total
+]
+
+SAMPLE_RESOURCES = [
+    types.Resource(
+        uri=f"file:///path/to/resource_{i}.txt",
+        name=f"resource_{i}",
+        description=f"This is sample resource number {i}",
+    )
+    for i in range(1, 31)  # 30 resources total
+]
+
+SAMPLE_PROMPTS = [
+    types.Prompt(
+        name=f"prompt_{i}",
+        description=f"This is sample prompt number {i}",
+        arguments=[
+            types.PromptArgument(name="arg1", description="First argument", required=True),
+        ],
+    )
+    for i in range(1, 21)  # 20 prompts total
+]
+
+
+def _paginate(cursor: str | None, items: list[T], page_size: int) -> tuple[list[T], str | None]:
+    """Helper to paginate a list of items given a cursor."""
+    if cursor is not None:
+        try:
+            start_idx = int(cursor)
+        except (ValueError, TypeError):
+            return [], None
+    else:
+        start_idx = 0
+
+    page = items[start_idx : start_idx + page_size]
+    next_cursor = str(start_idx + page_size) if start_idx + page_size < len(items) else None
+    return page, next_cursor
+
+
+# Paginated list_tools - returns 5 tools per page
+async def handle_list_tools(
+    ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
+) -> types.ListToolsResult:
+    cursor = params.cursor if params is not None else None
+    page, next_cursor = _paginate(cursor, SAMPLE_TOOLS, page_size=5)
+    return types.ListToolsResult(tools=page, next_cursor=next_cursor)
+
+
+# Paginated list_resources - returns 10 resources per page
+async def handle_list_resources(
+    ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
+) -> types.ListResourcesResult:
+    cursor = params.cursor if params is not None else None
+    page, next_cursor = _paginate(cursor, SAMPLE_RESOURCES, page_size=10)
+    return types.ListResourcesResult(resources=page, next_cursor=next_cursor)
+
+
+# Paginated list_prompts - returns 7 prompts per page
+async def handle_list_prompts(
+    ctx: ServerRequestContext, params: types.PaginatedRequestParams | None
+) -> types.ListPromptsResult:
+    cursor = params.cursor if params is not None else None
+    page, next_cursor = _paginate(cursor, SAMPLE_PROMPTS, page_size=7)
+    return types.ListPromptsResult(prompts=page, next_cursor=next_cursor)
+
+
+async def handle_call_tool(ctx: ServerRequestContext, params: types.CallToolRequestParams) -> types.CallToolResult:
+    # Find the tool in our sample data
+    tool = next((t for t in SAMPLE_TOOLS if t.name == params.name), None)
+    if not tool:
+        raise ValueError(f"Unknown tool: {params.name}")
+
+    return types.CallToolResult(
+        content=[
+            types.TextContent(
+                type="text",
+                text=f"Called tool '{params.name}' with arguments: {params.arguments}",
+            )
+        ]
+    )
+
+
+async def handle_read_resource(
+    ctx: ServerRequestContext, params: types.ReadResourceRequestParams
+) -> types.ReadResourceResult:
+    resource = next((r for r in SAMPLE_RESOURCES if r.uri == str(params.uri)), None)
+    if not resource:
+        raise ValueError(f"Unknown resource: {params.uri}")
+
+    return types.ReadResourceResult(
+        contents=[
+            types.TextResourceContents(
+                uri=str(params.uri),
+                text=f"Content of {resource.name}: This is sample content for the resource.",
+                mime_type="text/plain",
+            )
+        ]
+    )
+
+
+async def handle_get_prompt(ctx: ServerRequestContext, params: types.GetPromptRequestParams) -> types.GetPromptResult:
+    prompt = next((p for p in SAMPLE_PROMPTS if p.name == params.name), None)
+    if not prompt:
+        raise ValueError(f"Unknown prompt: {params.name}")
+
+    message_text = f"This is the prompt '{params.name}'"
+    if params.arguments:
+        message_text += f" with arguments: {params.arguments}"
+
+    return types.GetPromptResult(
+        description=prompt.description,
+        messages=[
+            types.PromptMessage(
+                role="user",
+                content=types.TextContent(type="text", text=message_text),
+            )
+        ],
+    )
+
+
+@click.command()
+@click.option("--port", default=8000, help="Port to listen on for HTTP")
+@click.option(
+    "--transport",
+    type=click.Choice(["stdio", "streamable-http"]),
+    default="stdio",
+    help="Transport type",
+)
+def main(port: int, transport: str) -> int:
+    app = Server(
+        "mcp-simple-pagination",
+        on_list_tools=handle_list_tools,
+        on_list_resources=handle_list_resources,
+        on_list_prompts=handle_list_prompts,
+        on_call_tool=handle_call_tool,
+        on_read_resource=handle_read_resource,
+        on_get_prompt=handle_get_prompt,
+    )
+
+    if transport == "streamable-http":
+        import uvicorn
+
+        uvicorn.run(app.streamable_http_app(), host="127.0.0.1", port=port)
+    else:
+        from mcp.server.stdio import stdio_server
+
+        async def arun():
+            async with stdio_server() as streams:
+                await app.run(streams[0], streams[1], app.create_initialization_options())
+
+        anyio.run(arun)
+
+    return 0

examples/servers/simple-pagination/pyproject.toml

@@ -0,0 +1,43 @@
+[project]
+name = "mcp-simple-pagination"
+version = "0.1.0"
+description = "A simple MCP server demonstrating pagination for tools, resources, and prompts"
+readme = "README.md"
+requires-python = ">=3.10"
+authors = [{ name = "Model Context Protocol a Series of LF Projects, LLC." }]
+keywords = ["mcp", "llm", "automation", "pagination", "cursor"]
+license = { text = "MIT" }
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+]
+dependencies = ["anyio>=4.5", "click>=8.2.0", "httpx>=0.27", "mcp"]
+
+[project.scripts]
+mcp-simple-pagination = "mcp_simple_pagination.server:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["mcp_simple_pagination"]
+
+[tool.pyright]
+include = ["mcp_simple_pagination"]
+venvPath = "."
+venv = ".venv"
+
+[tool.ruff.lint]
+select = ["E", "F", "I"]
+ignore = []
+
+[tool.ruff]
+line-length = 120
+target-version = "py310"
+
+[dependency-groups]
+dev = ["pyright>=1.1.378", "pytest>=8.3.3", "ruff>=0.6.9"]