Add structured content to the Python weather server and client and update to v2

[olaservo]

Brings the Python examples onto MCP SDK 2.0.0 and protocol revision 2026-07-28, and gives both tools a declared outputSchema with matching structuredContent.

This also clears the staleness that modelcontextprotocol/modelcontextprotocol#3124 flags against this repository. That PR modernises the Python in the tutorials and notes that the "complete code" they link to here had fallen behind: weather.py imported mcp.server.fastmcp, which does not exist in v2, and client.py still held the ClientSession version.

get_alerts answers with a top-level JSON array:

[
  { "event": "Flood Warning", "area": "La Salle County", ... },
  { "event": "Heat Advisory",  "area": "Wheeler County",  ... }
]

Through 2025-11-25 an outputSchema had to be object-rooted, so a tool returning a list had to invent a key to hang it off. get_forecast returns an object, for contrast.

The bare array without dropping to the low-level API

Alerts is a RootModel[list[Alert]] rather than a plain list[Alert]. A list[...] annotation is silently wrapped as {"result": ...}, but _try_create_model_and_schema takes any BaseModel subclass as the schema verbatim and RootModel is one — so the ordinary @mcp.tool() decorator yields an array-rooted schema and a bare array.

This is undocumented: docs/servers/structured-output.md still presents the wrapper as unavoidable for a list return. It is the difference between Python being able to demonstrate this spec feature idiomatically and not, and it is worth a docs PR upstream.

Other changes

Error paths raise. Once a tool declares an output schema it MUST return conforming structured content, so a path with no data to return has to fail rather than answer with a bare text result. "No alerts" is an empty array, not an error.

A null-field crash is fixed. props.get("instruction", "…") supplies its default only when the key is absent, and NWS sends these fields as explicit nulls. None reached a str field and Pydantic rejected the whole result, so get_alerts failed outright for any state with such an alert — one Texas alert in eight was enough. All five fields now use or.

The client negotiates. It moves to the 2.0 Client API and passes mode="auto" — one server/discover probe, falling back to the 2025-11-25 handshake — and prints the negotiated version on connect. call_tool revalidates non-error results against the declared schema, so the spec's client-side SHOULD needs no code here.

Dependencies are declared rather than inherited. weather.py imports httpx2 and client.py imports mcp_types, so both are listed explicitly instead of relying on mcp pulling them in. httpx stays out — mcp depends on httpx2, and listing httpx installs a second HTTP stack.

Matched to modelcontextprotocol/modelcontextprotocol#3124 so the tutorials and this code agree: the short from mcp.server import MCPServer spelling; TextContent narrowing before forwarding content to the model API; and input() moved onto a worker thread so it does not block the event loop.

Verification

Captured off the raw wire — a real get_alerts("TX") call against live NWS data, with no SDK on the client side, so this is literally what the server sends:

server/discover -> OK, versions=["2026-07-28"]
tools/list      -> get_alerts outputSchema.type = "array"

tools/call keys: ["content","isError","resultType","structuredContent"]
  resultType: "complete"
  structuredContent: ARRAY (8 items)
  content: 1 block(s), serialized JSON

structuredContent is a JSON array at the top level, not an object wrapping one. The single content block is the serialised JSON — the backwards-compatibility fallback the tools specification recommends for structured results.

Driven through the client with a real API key on mcp 2.0.0, the model calls the tool and answers from the structured result:

Connected over protocol 2026-07-28 with tools: ['get_alerts', 'get_forecast']
Query: What weather alerts are active in Texas right now?
[Calling tool get_alerts with args {'state': 'TX'}]
[get_alerts returned 8 items]
Here's a summary of active weather alerts in Texas right now: ...

The 8 items line comes from structured_content, not from re-reading the prose — the two channels going to their stated readers. That run also covers the null-field fix above: one of the eight is a Special Weather Statement with a null instruction, which is exactly the alert that failed before it.

Related

One of a set bringing the examples onto 2026-07-28, one PR per language so the four can be compared: #164 (Python), #165 (TypeScript), #166 (Go), #167 (Rust), with #163 as the shared prerequisite.

#163 has to merge first. The smoke test on main uses an MCP SDK v1 helper which negotiates 2025-11-25, and it rejects this server's array-rooted schema before reaching a tool call, so CI here stays red until that lands. The failure is Handler returned an invalid result from the Python server raising server-side; nothing in this diff causes it.

The Ruby examples are not in the set. The mcp gem 1.1.0 does now negotiate 2026-07-28, but its server never emits the resultType field that the revision makes mandatory, so a spec-strict client rejects every response including tools/list. That is an upstream fix, not something an example can work around.

---

🤖 Generated with Claude Code

[olaservo]

Will remove this before un-drafting.

[Copilot]

Pull request overview

Updates the Python weather MCP server and client to MCP SDK v2 (protocol revision 2026-07-28) and adds explicit structured output via declared outputSchema / structuredContent, including an array-rooted schema for get_alerts.

Changes:

• Migrates the Python weather server to MCPServer, switches HTTP stack usage to httpx2, and returns Pydantic-typed structured results (array root for alerts, object root for forecast).
• Migrates the Python client to the v2 Client API with mode="auto" version negotiation and uses structured_content as app data while forwarding only text blocks from content to the model.
• Updates Python project config/locks and docs to allow prereleases (uv prerelease mode) and document structured output behavior.

Reviewed changes

Copilot reviewed 6 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
weather-server-python/weather.py	Moves to MCP SDK v2 server API and returns structured Pydantic models (including array-root alerts).
weather-server-python/uv.lock	Updates locked deps for MCP 2.0 prerelease and enables prerelease mode.
weather-server-python/README.md	Documents structured output behavior and protocol requirements.
weather-server-python/pyproject.toml	Pins mcp[cli]>=2.0.0b2 and configures uv prerelease allowance.
mcp-client-python/client.py	Migrates to v2 Client with auto negotiation; forwards only text content and uses structured content as data.
mcp-client-python/uv.lock	Updates locked deps for MCP 2.0 prerelease and enables prerelease mode.
mcp-client-python/README.md	Documents structured output usage and version negotiation behavior.
mcp-client-python/pyproject.toml	Pins mcp>=2.0.0b2 and configures uv prerelease allowance.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.