Merge branch 'modelcontextprotocol:main' into configure-input-size

Author: pantanurag555

.github/workflows/publish-docs-manually.yml

@@ -30,4 +30,4 @@ jobs:
             mkdocs-material-
 
       - run: uv sync --frozen --group docs
-      - run: uv run --no-sync mkdocs gh-deploy --force
+      - run: uv run --frozen --no-sync mkdocs gh-deploy --force

.github/workflows/publish-pypi.yml

@@ -22,7 +22,7 @@ jobs:
         run: uv python install 3.12
 
       - name: Build
-        run: uv build
+        run: uv build --frozen
 
       - name: Upload artifacts
         uses: actions/upload-artifact@v4
@@ -79,4 +79,4 @@ jobs:
             mkdocs-material-
 
       - run: uv sync --frozen --group docs
-      - run: uv run --no-sync mkdocs gh-deploy --force
+      - run: uv run --frozen --no-sync mkdocs gh-deploy --force

.github/workflows/shared.yml

@@ -44,5 +44,5 @@ jobs:
         run: uv sync --frozen --all-extras --python ${{ matrix.python-version }}
 
       - name: Run pytest
-        run: uv run --no-sync pytest
+        run: uv run --frozen --no-sync pytest
     continue-on-error: true

README.md

@@ -829,6 +829,67 @@ if __name__ == "__main__":
 
 Caution: The `mcp run` and `mcp dev` tool doesn't support low-level server.
 
+#### Structured Output Support
+
+The low-level server supports structured output for tools, allowing you to return both human-readable content and machine-readable structured data. Tools can define an `outputSchema` to validate their structured output:
+
+```python
+from types import Any
+
+import mcp.types as types
+from mcp.server.lowlevel import Server
+
+server = Server("example-server")
+
+
+@server.list_tools()
+async def list_tools() -> list[types.Tool]:
+    return [
+        types.Tool(
+            name="calculate",
+            description="Perform mathematical calculations",
+            inputSchema={
+                "type": "object",
+                "properties": {
+                    "expression": {"type": "string", "description": "Math expression"}
+                },
+                "required": ["expression"],
+            },
+            outputSchema={
+                "type": "object",
+                "properties": {
+                    "result": {"type": "number"},
+                    "expression": {"type": "string"},
+                },
+                "required": ["result", "expression"],
+            },
+        )
+    ]
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict[str, Any]) -> dict[str, Any]:
+    if name == "calculate":
+        expression = arguments["expression"]
+        try:
+            result = eval(expression)  # Use a safe math parser
+            structured = {"result": result, "expression": expression}
+
+            # low-level server will validate structured output against the tool's
+            # output schema, and automatically serialize it into a TextContent block
+            # for backwards compatibility with pre-2025-06-18 clients.
+            return structured
+        except Exception as e:
+            raise ValueError(f"Calculation error: {str(e)}")
+```
+
+Tools can return data in three 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
+
+When an `outputSchema` is defined, the server automatically validates the structured output against the schema. This ensures type safety and helps catch errors early.
+
 ### 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/servers/structured_output_lowlevel.py

@@ -0,0 +1,98 @@
+#!/usr/bin/env python3
+"""
+Example low-level MCP server demonstrating structured output support.
+
+This example shows how to use the low-level server API to return
+structured data from tools, with automatic validation against output
+schemas.
+"""
+
+import asyncio
+from datetime import datetime
+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
+
+# Create low-level server instance
+server = Server("structured-output-lowlevel-example")
+
+
+@server.list_tools()
+async def list_tools() -> list[types.Tool]:
+    """List available tools with their schemas."""
+    return [
+        types.Tool(
+            name="get_weather",
+            description="Get weather information (simulated)",
+            inputSchema={
+                "type": "object",
+                "properties": {"city": {"type": "string", "description": "City name"}},
+                "required": ["city"],
+            },
+            outputSchema={
+                "type": "object",
+                "properties": {
+                    "temperature": {"type": "number"},
+                    "conditions": {"type": "string"},
+                    "humidity": {"type": "integer", "minimum": 0, "maximum": 100},
+                    "wind_speed": {"type": "number"},
+                    "timestamp": {"type": "string", "format": "date-time"},
+                },
+                "required": ["temperature", "conditions", "humidity", "wind_speed", "timestamp"],
+            },
+        ),
+    ]
+
+
+@server.call_tool()
+async def call_tool(name: str, arguments: dict[str, Any]) -> Any:
+    """
+    Handle tool call with structured output.
+    """
+
+    if name == "get_weather":
+        # city = arguments["city"]  # Would be used with real weather API
+
+        # Simulate weather data (in production, call a real weather API)
+        import random
+
+        weather_conditions = ["sunny", "cloudy", "rainy", "partly cloudy", "foggy"]
+
+        weather_data = {
+            "temperature": round(random.uniform(0, 35), 1),
+            "conditions": random.choice(weather_conditions),
+            "humidity": random.randint(30, 90),
+            "wind_speed": round(random.uniform(0, 30), 1),
+            "timestamp": datetime.now().isoformat(),
+        }
+
+        # Return structured data only
+        # The low-level server will serialize this to JSON content automatically
+        return weather_data
+
+    else:
+        raise ValueError(f"Unknown tool: {name}")
+
+
+async def run():
+    """Run the low-level server using stdio transport."""
+    async with mcp.server.stdio.stdio_server() as (read_stream, write_stream):
+        await server.run(
+            read_stream,
+            write_stream,
+            InitializationOptions(
+                server_name="structured-output-lowlevel-example",
+                server_version="0.1.0",
+                capabilities=server.get_capabilities(
+                    notification_options=NotificationOptions(),
+                    experimental_capabilities={},
+                ),
+            ),
+        )
+
+
+if __name__ == "__main__":
+    asyncio.run(run())

pyproject.toml

@@ -31,6 +31,7 @@ dependencies = [
     "sse-starlette>=1.6.1",
     "pydantic-settings>=2.5.2",
     "uvicorn>=0.23.1; sys_platform != 'emscripten'",
+    "jsonschema==4.20.0",
 ]
 
 [project.optional-dependencies]

src/mcp/client/auth.py

@@ -95,6 +95,7 @@ class OAuthContext:
     protected_resource_metadata: ProtectedResourceMetadata | None = None
     oauth_metadata: OAuthMetadata | None = None
     auth_server_url: str | None = None
+    protocol_version: str | None = None
 
     # Client registration
     client_info: OAuthClientInformationFull | None = None
@@ -154,6 +155,25 @@ def get_resource_url(self) -> str:
 
         return resource
 
+    def should_include_resource_param(self, protocol_version: str | None = None) -> bool:
+        """Determine if the resource parameter should be included in OAuth requests.
+
+        Returns True if:
+        - Protected resource metadata is available, OR
+        - MCP-Protocol-Version header is 2025-06-18 or later
+        """
+        # If we have protected resource metadata, include the resource param
+        if self.protected_resource_metadata is not None:
+            return True
+
+        # If no protocol version provided, don't include resource param
+        if not protocol_version:
+            return False
+
+        # Check if protocol version is 2025-06-18 or later
+        # Version format is YYYY-MM-DD, so string comparison works
+        return protocol_version >= "2025-06-18"
+
 
 class OAuthClientProvider(httpx.Auth):
     """
@@ -320,9 +340,12 @@ async def _perform_authorization(self) -> tuple[str, str]:
             "state": state,
             "code_challenge": pkce_params.code_challenge,
             "code_challenge_method": "S256",
-            "resource": self.context.get_resource_url(),  # RFC 8707
         }
 
+        # Only include resource param if conditions are met
+        if self.context.should_include_resource_param(self.context.protocol_version):
+            auth_params["resource"] = self.context.get_resource_url()  # RFC 8707
+
         if self.context.client_metadata.scope:
             auth_params["scope"] = self.context.client_metadata.scope
 
@@ -358,9 +381,12 @@ async def _exchange_token(self, auth_code: str, code_verifier: str) -> httpx.Req
             "redirect_uri": str(self.context.client_metadata.redirect_uris[0]),
             "client_id": self.context.client_info.client_id,
             "code_verifier": code_verifier,
-            "resource": self.context.get_resource_url(),  # RFC 8707
         }
 
+        # Only include resource param if conditions are met
+        if self.context.should_include_resource_param(self.context.protocol_version):
+            token_data["resource"] = self.context.get_resource_url()  # RFC 8707
+
         if self.context.client_info.client_secret:
             token_data["client_secret"] = self.context.client_info.client_secret
 
@@ -409,9 +435,12 @@ async def _refresh_token(self) -> httpx.Request:
             "grant_type": "refresh_token",
             "refresh_token": self.context.current_tokens.refresh_token,
             "client_id": self.context.client_info.client_id,
-            "resource": self.context.get_resource_url(),  # RFC 8707
         }
 
+        # Only include resource param if conditions are met
+        if self.context.should_include_resource_param(self.context.protocol_version):
+            refresh_data["resource"] = self.context.get_resource_url()  # RFC 8707
+
         if self.context.client_info.client_secret:
             refresh_data["client_secret"] = self.context.client_info.client_secret
 
@@ -457,6 +486,9 @@ async def async_auth_flow(self, request: httpx.Request) -> AsyncGenerator[httpx.
             if not self._initialized:
                 await self._initialize()
 
+            # Capture protocol version from request headers
+            self.context.protocol_version = request.headers.get(MCP_PROTOCOL_VERSION)
+
             # Perform OAuth flow if not authenticated
             if not self.context.is_token_valid():
                 try: