Add structured content to the Python weather server and client and update to v2 (#164)

* Add structured output to the Python weather server and client

Both tools declare an output schema - the return type annotation - and return
structured_content alongside the text.

get_alerts answers with a top-level JSON array rather than an array nested in
an object, which protocol revision 2026-07-28 is the first to allow. "No
alerts" is simply []. get_forecast returns an object, for contrast.

The detail worth reading the source for: Alerts is a RootModel[list[Alert]],
not a plain list[Alert]. A list is not a JSON object, so the SDK wraps it as
{"result": [...]} and advertises an object-rooted schema to match, with no
opt-out. A RootModel is a BaseModel, so it is taken as the schema exactly as
written, and a RootModel over a list serializes as the bare list.

Error paths raise: a tool declaring an output schema MUST return conforming
structured content, so a path with no data has to fail.

The client moves to the 2.0 Client API with mode="auto" and prints the
negotiated version on connect. call_tool already revalidates every non-error
result against the declared schema, so the client-side SHOULD needs no code.
Each channel goes to its stated reader: content is forwarded to the model,
structured_content is used as data, reporting how many items came back.

This clears the staleness modelcontextprotocol#3124 flags against this
repository - weather.py imported mcp.server.fastmcp, client.py held the
ClientSession version - and matches that PR's idioms: the short
"from mcp.server import MCPServer" spelling, httpx2 with httpx dropped from
the dependencies since httpx2>=2.5.0 is a hard dependency of mcp,
result.content narrowed to TextContent, and input() on a worker thread.

Requires mcp 2.0.0b2; pyproject.toml sets [tool.uv] prerelease = "allow" so
plain uv run and uv sync work without flags. Model identifier moves to
claude-sonnet-5.

Note that an array-rooted schema only works on a 2026-07-28 connection. This
SDK does not project it down for older clients; it raises server-side instead.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* Update to mcp 2.0.0

The SDK left beta on 2026-07-28, so the pins move off 2.0.0b2 and both
projects drop `[tool.uv] prerelease = allow` — plain `uv run` works now.

Also from review: declare the imports rather than lean on transitive
resolution. weather.py imports httpx2 and client.py imports mcp_types, so
both are listed explicitly. The client README no longer implies every
structured result is counted — only array-rooted ones are.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* Fix get_alerts failing when NWS sends a null field

`dict.get(key, default)` returns the default only when the key is absent. The
NWS API sends these fields as explicit nulls instead of omitting them, so
`props.get(instruction, ...)` passed None straight into a `str` field and
Pydantic rejected the whole result.

One alert in eight for TX is a Special Weather Statement with a null
instruction, which was enough to fail the entire call:

  Error executing tool get_alerts: 1 validation error for Alert
  instructions
    Input should be a valid string [type=string_type, input_value=None]

The smoke test missed it twice over: it calls get_alerts with CA, whose
alerts happen to have no nulls today, and it reports an isError result as a
skip rather than a failure.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

* Say "structured content", not "structured output"

The spec never uses the phrase "structured output". It defines two separate
things under Tool Result: "Structured Content" (the `structuredContent` field)
and "Output Schema" (the `outputSchema` field). Collapsing them into
"structured output" conflates the two.

It is also actively confusing here. In LLM tooling "structured output" means
constrained decoding — making the *model* emit conforming JSON. These clients
call a model API, so a reader could reasonably take the phrase to mean the
tool constrains the model's response, which is the opposite of what is going
on: the tool describes the shape of its own result.

Headings and prose now say "structured content". References to real
identifiers are left alone: the Python SDK's own docs page is called
Structured Output and lives at docs/servers/structured-output.md, and its
decorator parameter is `structured_output`.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 5 <noreply@anthropic.com>

mcp-client-python/README.md

@@ -1,3 +1,11 @@
 # An LLM-Powered Chatbot MCP Client written in Python
 
 See the [Build an MCP client](https://modelcontextprotocol.io/docs/develop/build-client) tutorial for more information.
+
+## Structured content
+
+`call_tool` validates every result against the tool's declared output schema, so the spec's client-side SHOULD needs no code here.
+
+The two channels go to different readers: `content` is forwarded to the model, while `structured_content` is used as data — when a tool returns an array, the client counts its items rather than re-reading the prose. See [Structured Content](https://modelcontextprotocol.io/specification/draft/server/tools#structured-content).
+
+`Client(transport, mode="auto")` probes `server/discover` and falls back to the `2025-11-25` handshake; `client.protocol_version` reports which era you got. See [Protocol versions](https://py.sdk.modelcontextprotocol.io/v2/protocol-versions/).

mcp-client-python/client.py

@@ -5,20 +5,24 @@ from pathlib import Path
 
 from anthropic import Anthropic
 from dotenv import load_dotenv
-from mcp import ClientSession, StdioServerParameters
+from mcp import Client, StdioServerParameters
 from mcp.client.stdio import stdio_client
+from mcp_types import TextContent
 
 load_dotenv()  # load environment variables from .env
 
 # Claude model constant
-ANTHROPIC_MODEL = "claude-sonnet-4-5"
+ANTHROPIC_MODEL = "claude-sonnet-5"
+# Sonnet 5 thinks adaptively unless told otherwise, and max_tokens caps thinking
+# plus the reply, so leave room for both.
+MAX_TOKENS = 10000
 MAX_TOOL_TURNS = 10
 
 
 class MCPClient:
     def __init__(self):
         # Initialize session and client objects
-        self.session: ClientSession | None = None
+        self.client: Client | None = None
         self.exit_stack = AsyncExitStack()
         self._anthropic: Anthropic | None = None
 
@@ -50,31 +54,30 @@ class MCPClient:
         else:
             server_params = StdioServerParameters(command="node", args=[server_script_path], env=None)
 
-        stdio_transport = await self.exit_stack.enter_async_context(stdio_client(server_params))
-        self.stdio, self.write = stdio_transport
-        self.session = await self.exit_stack.enter_async_context(ClientSession(self.stdio, self.write))
-
-        await self.session.initialize()
+        # "auto" probes server/discover, falling back to the 2025-11-25 handshake.
+        self.client = await self.exit_stack.enter_async_context(
+            Client(stdio_client(server_params), mode="auto")
+        )
 
         # List available tools
-        response = await self.session.list_tools()
+        response = await self.client.list_tools()
         tools = response.tools
-        print("\nConnected to server with tools:", [tool.name for tool in tools])
+        print(f"\nConnected over protocol {self.client.protocol_version} with tools:", [tool.name for tool in tools])
 
     async def process_query(self, query: str) -> str:
         """Process a query using Claude and available tools"""
         messages = [{"role": "user", "content": query}]
 
-        tools_response = await self.session.list_tools()
+        tools_response = await self.client.list_tools()
         available_tools = [
-            {"name": tool.name, "description": tool.description, "input_schema": tool.inputSchema}
+            {"name": tool.name, "description": tool.description, "input_schema": tool.input_schema}
             for tool in tools_response.tools
         ]
 
         final_text = []
 
         response = self.anthropic.messages.create(
-            model=ANTHROPIC_MODEL, max_tokens=1000, messages=messages, tools=available_tools
+            model=ANTHROPIC_MODEL, max_tokens=MAX_TOKENS, messages=messages, tools=available_tools
         )
 
         for _ in range(MAX_TOOL_TURNS):
@@ -90,13 +93,23 @@ class MCPClient:
 
             tool_results = []
             for tool_use in tool_uses:
-                result = await self.session.call_tool(tool_use.name, tool_use.input)
+                # call_tool validates the result against the declared schema.
+                result = await self.client.call_tool(tool_use.name, tool_use.input)
                 final_text.append(f"[Calling tool {tool_use.name} with args {tool_use.input}]")
+
+                # structured_content is data the application can use directly.
+                if isinstance(result.structured_content, list):
+                    final_text.append(f"[{tool_use.name} returned {len(result.structured_content)} items]")
+
+                # content is a list of block types; forward only the text ones.
                 tool_results.append(
                     {
                         "type": "tool_result",
                         "tool_use_id": tool_use.id,
-                        "content": result.content,
+                        "content": "\n".join(
+                            block.text for block in result.content if isinstance(block, TextContent)
+                        ),
+                        "is_error": bool(result.is_error),
                     }
                 )
 
@@ -105,7 +118,7 @@ class MCPClient:
 
             response = self.anthropic.messages.create(
                 model=ANTHROPIC_MODEL,
-                max_tokens=1000,
+                max_tokens=MAX_TOKENS,
                 messages=messages,
                 tools=available_tools,
             )
@@ -119,8 +132,9 @@ class MCPClient:
         print("Type your queries or 'quit' to exit.")
 
         while True:
+            # input() blocks, so keep it off the event loop.
             try:
-                query = input("\nQuery: ").strip()
+                query = (await asyncio.to_thread(input, "\nQuery: ")).strip()
             except (EOFError, KeyboardInterrupt):
                 break
 

mcp-client-python/pyproject.toml

@@ -6,7 +6,9 @@ readme = "README.md"
 requires-python = ">=3.10"
 dependencies = [
     "anthropic>=0.87.0",
-    "mcp>=1.28.1",
+    "mcp>=2.0.0",
+    # client.py imports TextContent from mcp_types, which `mcp` pins exactly.
+    "mcp-types>=2.0.0",
     "python-dotenv>=1.2.2",
 ]
 

weather-server-python/README.md

@@ -1,3 +1,11 @@
 # A Simple MCP Weather Server written in Python
 
 See the [Build an MCP server](https://modelcontextprotocol.io/docs/develop/build-server) tutorial for more information.
+
+## Structured content
+
+Both tools declare an output schema and return `structured_content`. `get_forecast` returns an object; `get_alerts` returns a top-level JSON array, which protocol revision `2026-07-28` is the first to allow — see [Structured Content](https://modelcontextprotocol.io/specification/draft/server/tools#structured-content) in the spec.
+
+`Alerts` is a `RootModel[list[Alert]]` rather than a plain `list[Alert]` because the SDK wraps non-object return types as `{"result": ...}`; a `RootModel` is taken as the schema exactly as written. See [Structured Output](https://py.sdk.modelcontextprotocol.io/v2/servers/structured-output/) in the SDK docs.
+
+Note that an array-rooted schema requires a `2026-07-28` client. This SDK does not project it down for older ones — it raises instead.

weather-server-python/pyproject.toml

@@ -4,9 +4,13 @@ version = "0.1.0"
 description = "A simple MCP weather server"
 readme = "README.md"
 requires-python = ">=3.10"
+# httpx2, not httpx: `mcp` already depends on httpx2, so adding httpx would
+# install a second HTTP stack alongside it.
 dependencies = [
-    "httpx>=0.28.1",
-    "mcp[cli]>=1.26.0",
+    "httpx2>=2.5.0",
+    "mcp[cli]>=2.0.0",
+    # weather.py imports BaseModel, Field, and RootModel directly. RootModel is v2-only.
+    "pydantic>=2.0.0",
 ]
 
 [build-system]

weather-server-python/weather.py

@@ -1,20 +1,60 @@
 from typing import Any
 
-import httpx
-from mcp.server.fastmcp import FastMCP
+import httpx2
+from mcp.server import MCPServer
+from pydantic import BaseModel, Field, RootModel
 
-# Initialize FastMCP server
-mcp = FastMCP("weather")
+# Initialize the MCP server
+mcp = MCPServer("weather")
 
 # Constants
 NWS_API_BASE = "https://api.weather.gov"
 USER_AGENT = "weather-app/1.0"
 
 
+class Alert(BaseModel):
+    """One active weather alert."""
+
+    event: str = Field(description="The kind of weather event")
+    area: str = Field(description="The area the alert covers")
+    severity: str = Field(description="How severe the event is")
+    description: str = Field(description="What is happening")
+    instructions: str = Field(description="What people in the area should do")
+
+
+class Alerts(RootModel[list[Alert]]):
+    """The output schema of get_alerts: a top-level array, not an object.
+
+    A plain `-> list[Alert]` annotation would be wrapped as `{"result": [...]}`.
+    A RootModel is a BaseModel, so it is taken as the schema as written, and a
+    RootModel over a list serializes as the bare list. Revision 2026-07-28 is
+    the first to allow a non-object root.
+    """
+
+
+class Period(BaseModel):
+    """One period of a forecast."""
+
+    name: str = Field(description="Label for the period, e.g. Tonight or Tuesday")
+    temperature: int = Field(description="Forecast temperature")
+    temperature_unit: str = Field(description="Unit of the temperature, F or C")
+    wind_speed: str = Field(description="Wind speed, e.g. 10 to 15 mph")
+    wind_direction: str = Field(description="Wind direction as a compass point")
+    detailed_forecast: str = Field(description="Prose description of the period")
+
+
+class Forecast(BaseModel):
+    """The output schema of get_forecast: the object case, for contrast."""
+
+    latitude: float = Field(description="Latitude the forecast is for")
+    longitude: float = Field(description="Longitude the forecast is for")
+    periods: list[Period] = Field(description="The forecast periods, soonest first")
+
+
 async def make_nws_request(url: str) -> dict[str, Any] | None:
     """Make a request to the NWS API with proper error handling."""
     headers = {"User-Agent": USER_AGENT, "Accept": "application/geo+json"}
-    async with httpx.AsyncClient() as client:
+    async with httpx2.AsyncClient() as client:
         try:
             response = await client.get(url, headers=headers, timeout=30.0)
             response.raise_for_status()
@@ -23,40 +63,39 @@ async def make_nws_request(url: str) -> dict[str, Any] | None:
             return None
 
 
-def format_alert(feature: dict) -> str:
-    """Format an alert feature into a readable string."""
-    props = feature["properties"]
-    return f"""
-Event: {props.get("event", "Unknown")}
-Area: {props.get("areaDesc", "Unknown")}
-Severity: {props.get("severity", "Unknown")}
-Description: {props.get("description", "No description available")}
-Instructions: {props.get("instruction", "No specific instructions provided")}
-"""
-
-
 @mcp.tool()
-async def get_alerts(state: str) -> str:
+async def get_alerts(state: str) -> Alerts:
     """Get weather alerts for a US state.
 
     Args:
         state: Two-letter US state code (e.g. CA, NY)
     """
-    url = f"{NWS_API_BASE}/alerts/active/area/{state}"
+    url = f"{NWS_API_BASE}/alerts/active/area/{state.upper()}"
     data = await make_nws_request(url)
 
     if not data or "features" not in data:
-        return "Unable to fetch alerts or no alerts found."
+        raise ValueError(f"Unable to fetch alerts for {state.upper()}.")
 
-    if not data["features"]:
-        return "No active alerts for this state."
-
-    alerts = [format_alert(feature) for feature in data["features"]]
-    return "\n---\n".join(alerts)
+    # An empty result is an empty array, not an error.
+    #
+    # `or` rather than a `get` default: NWS sends these fields as explicit
+    # nulls rather than omitting them, and a default only covers a missing key.
+    return Alerts(
+        [
+            Alert(
+                event=props.get("event") or "Unknown",
+                area=props.get("areaDesc") or "Unknown",
+                severity=props.get("severity") or "Unknown",
+                description=props.get("description") or "No description available",
+                instructions=props.get("instruction") or "No specific instructions provided",
+            )
+            for props in (feature["properties"] for feature in data["features"])
+        ]
+    )
 
 
 @mcp.tool()
-async def get_forecast(latitude: float, longitude: float) -> str:
+async def get_forecast(latitude: float, longitude: float) -> Forecast:
     """Get weather forecast for a location.
 
     Args:
@@ -68,28 +107,34 @@ async def get_forecast(latitude: float, longitude: float) -> str:
     points_data = await make_nws_request(points_url)
 
     if not points_data:
-        return "Unable to fetch forecast data for this location."
+        raise ValueError("Unable to fetch forecast data for this location.")
 
     # Get the forecast URL from the points response
     forecast_url = points_data["properties"]["forecast"]
     forecast_data = await make_nws_request(forecast_url)
 
     if not forecast_data:
-        return "Unable to fetch detailed forecast."
+        raise ValueError("Unable to fetch detailed forecast.")
 
-    # Format the periods into a readable forecast
-    periods = forecast_data["properties"]["periods"]
-    forecasts = []
-    for period in periods[:5]:  # Only show next 5 periods
-        forecast = f"""
-{period["name"]}:
-Temperature: {period["temperature"]}°{period["temperatureUnit"]}
-Wind: {period["windSpeed"]} {period["windDirection"]}
-Forecast: {period["detailedForecast"]}
-"""
-        forecasts.append(forecast)
+    periods = forecast_data["properties"]["periods"][:5]  # Only show next 5 periods
+    if not periods:
+        raise ValueError("No forecast periods available.")
 
-    return "\n---\n".join(forecasts)
+    return Forecast(
+        latitude=latitude,
+        longitude=longitude,
+        periods=[
+            Period(
+                name=period["name"],
+                temperature=period["temperature"],
+                temperature_unit=period["temperatureUnit"],
+                wind_speed=period["windSpeed"],
+                wind_direction=period["windDirection"],
+                detailed_forecast=period["detailedForecast"],
+            )
+            for period in periods
+        ],
+    )
 
 
 def main():