modelcontextprotocol/quickstart-resources
Watch
1
0
Fork
You've already forked quickstart-resources
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

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

Browse source 
* 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>
This commit is contained in:
Ola Hungerford 2026-08-09 05:46:03 -07:00 • committed by GitHub
commit 8e373f0f2e
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 1307 additions and 863 deletions
Download patch file Download diff file Expand all files Collapse all files

125
weather-server-python/weather.py
View file

@ -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():