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
4 changed files with 1307 additions and 863 deletions
Download patch file Download diff file Expand all files Collapse all files

8
mcp-client-python/README.md
View file

@ -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/).

48
mcp-client-python/client.py
View file

@ -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

4
mcp-client-python/pyproject.toml
View file

@ -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",
]

1055
mcp-client-python/uv.lock generated
View file

File diff suppressed because it is too large Load diff