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

[olaservo]

Draft until the 2026-07-28 revision and SDK is released

Brings the Python examples onto MCP SDK 2.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",  ... }
]

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.

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.

Matched to modelcontextprotocol/modelcontextprotocol#3124 so the tutorials and this code agree: the short from mcp.server import MCPServer spelling; httpx2 instead of httpx, with httpx dropped from the dependencies because httpx2>=2.5.0 is a hard dependency of mcp and listing it installed a second HTTP stack; result.content narrowed to TextContent before being forwarded 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 (10953 bytes)
  content: 1 block(s)
    [0] type=text bytes=11278 serialized-JSON=true

structuredContent is a JSON array at the top level, not an object wrapping one, and the tool's 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, the model calls the tool and answers from the structured result:

Connected over protocol 2026-07-28 with tools: ['get_alerts', 'get_forecast']
[Calling tool get_alerts with args {'state': 'TX'}]
Here are the active weather alerts in Texas: ...

Draft status

Two separate gates:

1. #163 has to merge first. The smoke test on main uses an MCP SDK v1 helper, which negotiates 2025-11-25.

2. The revision has to ship. 2026-07-28 support is only in the mcp 2.0 prereleases, so this pins mcp[cli]>=2.0.0b2 and sets [tool.uv] prerelease = "allow" in pyproject.toml so plain uv run and uv sync work without extra flags. Ideally this PR waits for mcp 2.0 stable and the pin is the only line that changes.

I will rebase and mark ready once both are cleared.

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. The Ruby examples are deliberately not in the set: the mcp gem caps at protocol 2025-11-25.

---

🤖 Generated with Claude Code

[olaservo]

Will remove this before un-drafting.

[olaservo]

Will remove this before un-drafting.

[olaservo]

Will remove this before un-drafting.