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

Author: LucaButBoring

.gitignore

@@ -89,7 +89,7 @@ ipython_config.py
 # pyenv
 #   For a library or package, you might want to ignore these files since the code is
 #   intended to run in multiple environments; otherwise, check them in:
-# .python-version
+.python-version
 
 # pipenv
 #   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.

CLAUDE.md

@@ -48,8 +48,6 @@ This document contains critical information about working with this codebase. Fo
   the problem it tries to solve, and how it is solved. Don't go into the specifics of the
   code unless it adds clarity.
 
-- Always add `jerome3o-anthropic` and `jspahrsummers` as reviewer.
-
 - NEVER ever mention a `co-authored-by` or similar aspects. In particular, never
   mention the tool used to create the commit message or PR.
 

README.md

@@ -8,8 +8,8 @@
 [![MIT licensed][mit-badge]][mit-url]
 [![Python Version][python-badge]][python-url]
 [![Documentation][docs-badge]][docs-url]
+[![Protocol][protocol-badge]][protocol-url]
 [![Specification][spec-badge]][spec-url]
-[![GitHub Discussions][discussions-badge]][discussions-url]
 
 </div>
 
@@ -74,12 +74,12 @@
 [mit-url]: https://github.com/modelcontextprotocol/python-sdk/blob/main/LICENSE
 [python-badge]: https://img.shields.io/pypi/pyversions/mcp.svg
 [python-url]: https://www.python.org/downloads/
-[docs-badge]: https://img.shields.io/badge/docs-modelcontextprotocol.io-blue.svg
-[docs-url]: https://modelcontextprotocol.io
+[docs-badge]: https://img.shields.io/badge/docs-python--sdk-blue.svg
+[docs-url]: https://modelcontextprotocol.github.io/python-sdk/
+[protocol-badge]: https://img.shields.io/badge/protocol-modelcontextprotocol.io-blue.svg
+[protocol-url]: https://modelcontextprotocol.io
 [spec-badge]: https://img.shields.io/badge/spec-spec.modelcontextprotocol.io-blue.svg
 [spec-url]: https://spec.modelcontextprotocol.io
-[discussions-badge]: https://img.shields.io/github/discussions/modelcontextprotocol/python-sdk
-[discussions-url]: https://github.com/modelcontextprotocol/python-sdk/discussions
 
 ## Overview
 
@@ -383,6 +383,61 @@ causes the tool to be classified as structured _and this is undesirable_,
 the  classification can be suppressed by passing `structured_output=False`
 to the `@tool` decorator.
 
+##### Advanced: Direct CallToolResult
+
+For full control over tool responses including the `_meta` field (for passing data to client applications without exposing it to the model), you can return `CallToolResult` directly:
+
+<!-- snippet-source examples/snippets/servers/direct_call_tool_result.py -->
+```python
+"""Example showing direct CallToolResult return for advanced control."""
+
+from typing import Annotated
+
+from pydantic import BaseModel
+
+from mcp.server.fastmcp import FastMCP
+from mcp.types import CallToolResult, TextContent
+
+mcp = FastMCP("CallToolResult Example")
+
+
+class ValidationModel(BaseModel):
+    """Model for validating structured output."""
+
+    status: str
+    data: dict[str, int]
+
+
+@mcp.tool()
+def advanced_tool() -> CallToolResult:
+    """Return CallToolResult directly for full control including _meta field."""
+    return CallToolResult(
+        content=[TextContent(type="text", text="Response visible to the model")],
+        _meta={"hidden": "data for client applications only"},
+    )
+
+
+@mcp.tool()
+def validated_tool() -> Annotated[CallToolResult, ValidationModel]:
+    """Return CallToolResult with structured output validation."""
+    return CallToolResult(
+        content=[TextContent(type="text", text="Validated response")],
+        structuredContent={"status": "success", "data": {"result": 42}},
+        _meta={"internal": "metadata"},
+    )
+
+
+@mcp.tool()
+def empty_result_tool() -> CallToolResult:
+    """For empty results, return CallToolResult with empty content."""
+    return CallToolResult(content=[])
+```
+
+_Full example: [examples/snippets/servers/direct_call_tool_result.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/direct_call_tool_result.py)_
+<!-- /snippet-source -->
+
+**Important:** `CallToolResult` must always be returned (no `Optional` or `Union`). For empty results, use `CallToolResult(content=[])`. For optional simple types, use `str | None` without `CallToolResult`.
+
 <!-- snippet-source examples/snippets/servers/structured_output.py -->
 ```python
 """Example showing structured output with tools."""
@@ -1769,14 +1824,93 @@ if __name__ == "__main__":
 _Full example: [examples/snippets/servers/lowlevel/structured_output.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/lowlevel/structured_output.py)_
 <!-- /snippet-source -->
 
-Tools can return data in three ways:
+Tools can return data in four ways:
 
 1. **Content only**: Return a list of content blocks (default behavior before spec revision 2025-06-18)
 2. **Structured data only**: Return a dictionary that will be serialized to JSON (Introduced in spec revision 2025-06-18)
 3. **Both**: Return a tuple of (content, structured_data) preferred option to use for backwards compatibility
+4. **Direct CallToolResult**: Return `CallToolResult` directly for full control (including `_meta` field)
 
 When an `outputSchema` is defined, the server automatically validates the structured output against the schema. This ensures type safety and helps catch errors early.
 
+##### Returning CallToolResult Directly
+
+For full control over the response including the `_meta` field (for passing data to client applications without exposing it to the model), return `CallToolResult` directly:
+
+<!-- snippet-source examples/snippets/servers/lowlevel/direct_call_tool_result.py -->
+```python
+"""
+Run from the repository root:
+    uv run examples/snippets/servers/lowlevel/direct_call_tool_result.py
+"""
+
+import asyncio
+from typing import Any
+
+import mcp.server.stdio
+import mcp.types as types
+from mcp.server.lowlevel import NotificationOptions, Server
+from mcp.server.models import InitializationOptions
+
+server = Server("example-server")
+
+
+@server.list_tools()
+async def list_tools() -> list[types.Tool]:
+    """List available tools."""
+    return [
+        types.Tool(
+            name="advanced_tool",
+            description="Tool with full control including _meta field",
+            inputSchema={
+                "type": "object",
+                "properties": {"message": {"type": "string"}},
+                "required": ["message"],
+            },
+        )
+    ]
+
+
+@server.call_tool()
+async def handle_call_tool(name: str, arguments: dict[str, Any]) -> types.CallToolResult:
+    """Handle tool calls by returning CallToolResult directly."""
+    if name == "advanced_tool":
+        message = str(arguments.get("message", ""))
+        return types.CallToolResult(
+            content=[types.TextContent(type="text", text=f"Processed: {message}")],
+            structuredContent={"result": "success", "message": message},
+            _meta={"hidden": "data for client applications only"},
+        )
+
+    raise ValueError(f"Unknown tool: {name}")
+
+
+async def run():
+    """Run the server."""
+    async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            InitializationOptions(
+                server_name="example",
+                server_version="0.1.0",
+                capabilities=server.get_capabilities(
+                    notification_options=NotificationOptions(),
+                    experimental_capabilities={},
+                ),
+            ),
+        )
+
+
+if __name__ == "__main__":
+    asyncio.run(run())
+```
+
+_Full example: [examples/snippets/servers/lowlevel/direct_call_tool_result.py](https://github.com/modelcontextprotocol/python-sdk/blob/main/examples/snippets/servers/lowlevel/direct_call_tool_result.py)_
+<!-- /snippet-source -->
+
+**Note:** When returning `CallToolResult`, you bypass the automatic content/structured conversion. You must construct the complete response yourself.
+
 ### 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.
@@ -1840,7 +1974,7 @@ import asyncio
 
 from mcp.client.session import ClientSession
 from mcp.client.stdio import StdioServerParameters, stdio_client
-from mcp.types import Resource
+from mcp.types import PaginatedRequestParams, Resource
 
 
 async def list_all_resources() -> None:
@@ -1857,7 +1991,7 @@ async def list_all_resources() -> None:
 
             while True:
                 # Fetch a page of resources
-                result = await session.list_resources(cursor=cursor)
+                result = await session.list_resources(params=PaginatedRequestParams(cursor=cursor))
                 all_resources.extend(result.resources)
 
                 print(f"Fetched {len(result.resources)} resources")

docs/authorization.md

@@ -0,0 +1,5 @@
+# Authorization
+
+!!! warning "Under Construction"
+
+    This page is currently being written. Check back soon for complete documentation.

docs/concepts.md

@@ -0,0 +1,13 @@
+# Concepts
+
+!!! warning "Under Construction"
+
+    This page is currently being written. Check back soon for complete documentation.
+
+<!--
+  - Server vs Client
+  - Three primitives (tools, resources, prompts)
+  - Transports (stdio, SSE, streamable HTTP)
+  - Context and sessions
+  - Lifecycle and state
+ -->

docs/index.md

@@ -1,5 +1,57 @@
-# MCP Server
+# MCP Python SDK
 
-This is the MCP Server implementation in Python.
+The **Model Context Protocol (MCP)** allows applications to provide context for LLMs in a standardized way, separating the concerns of providing context from the actual LLM interaction.
 
-It only contains the [API Reference](api.md) for the time being.
+This Python SDK implements the full MCP specification, making it easy to:
+
+- **Build MCP servers** that expose resources, prompts, and tools
+- **Create MCP clients** that can connect to any MCP server
+- **Use standard transports** like stdio, SSE, and Streamable HTTP
+
+If you want to read more about the specification, please visit the [MCP documentation](https://modelcontextprotocol.io).
+
+## Quick Example
+
+Here's a simple MCP server that exposes a tool, resource, and prompt:
+
+```python title="server.py"
+from mcp.server.fastmcp import FastMCP
+
+mcp = FastMCP("Test Server")
+
+
+@mcp.tool()
+def add(a: int, b: int) -> int:
+    """Add two numbers"""
+    return a + b
+
+
+@mcp.resource("greeting://{name}")
+def get_greeting(name: str) -> str:
+    """Get a personalized greeting"""
+    return f"Hello, {name}!"
+
+
+@mcp.prompt()
+def greet_user(name: str, style: str = "friendly") -> str:
+    """Generate a greeting prompt"""
+    return f"Write a {style} greeting for someone named {name}."
+```
+
+Test it with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
+
+```bash
+uv run mcp dev server.py
+```
+
+## Getting Started
+
+<!-- TODO(Marcelo): automatically generate the follow references with a header on each of those files. -->
+1. **[Install](installation.md)** the MCP SDK
+2. **[Learn concepts](concepts.md)** - understand the three primitives and architecture
+3. **[Explore authorization](authorization.md)** - add security to your servers
+4. **[Use low-level APIs](low-level-server.md)** - for advanced customization
+
+## API Reference
+
+Full API documentation is available in the [API Reference](api.md).

docs/installation.md

@@ -0,0 +1,31 @@
+# Installation
+
+The Python SDK is available on PyPI as [`mcp`](https://pypi.org/project/mcp/) so installation is as simple as:
+
+=== "pip"
+
+    ```bash
+    pip install mcp
+    ```
+=== "uv"
+
+    ```bash
+    uv add mcp
+    ```
+
+The following dependencies are automatically installed:
+
+- [`httpx`](https://pypi.org/project/httpx/): HTTP client to handle HTTP Streamable and SSE transports.
+- [`httpx-sse`](https://pypi.org/project/httpx-sse/): HTTP client to handle SSE transport.
+- [`pydantic`](https://pypi.org/project/pydantic/): Types, JSON schema generation, data validation, and [more](https://docs.pydantic.dev/latest/).
+- [`starlette`](https://pypi.org/project/starlette/): Web framework used to build the HTTP transport endpoints.
+- [`python-multipart`](https://pypi.org/project/python-multipart/): Handle HTTP body parsing.
+- [`sse-starlette`](https://pypi.org/project/sse-starlette/): Server-Sent Events for Starlette, used to build the SSE transport endpoint.
+- [`pydantic-settings`](https://pypi.org/project/pydantic-settings/): Settings management used in FastMCP.
+- [`uvicorn`](https://pypi.org/project/uvicorn/): ASGI server used to run the HTTP transport endpoints.
+- [`jsonschema`](https://pypi.org/project/jsonschema/): JSON schema validation.
+- [`pywin32`](https://pypi.org/project/pywin32/): Windows specific dependencies for the CLI tools.
+
+This package has the following optional groups:
+
+- `cli`: Installs `typer` and `python-dotenv` for the MCP CLI tools.

docs/low-level-server.md

@@ -0,0 +1,5 @@
+# Low-Level Server
+
+!!! warning "Under Construction"
+
+    This page is currently being written. Check back soon for complete documentation.