* Add structured output to the TypeScript weather server and client
Both tools declare an outputSchema and return structuredContent alongside the
text.
get-alerts declares z.array(...), so it 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.
This costs older clients nothing. The server declares the array schema once
and never branches on protocol version: serveStdio serves both eras from one
factory, and the SDK projects the schema down to
{"type":"object","properties":{"result":...}} for a 2025-11-25 client, wrapping
the structured content to match. Verified against both eras.
Error paths throw: a tool declaring an outputSchema MUST return conforming
structured content, so a path with no data has to fail.
The client passes versionNegotiation {mode:"auto"}; the SDK default is
"legacy". The SDK validates every 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, structuredContent is used as data,
reporting how many items came back.
Moves to the 2.0 beta packages, where the 2026-07-28 support lives:
@modelcontextprotocol/sdk is replaced by @modelcontextprotocol/server and
@modelcontextprotocol/client. Model identifier moves to claude-sonnet-5.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* Update to @modelcontextprotocol/{server,client} 2.0.0
The 2.0 packages left beta on 2026-07-27, so the dependency ranges move off
2.0.0-beta.5.
Also from review: engines.node goes to 20, which is what the 2.0 packages
require, and 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>
* Query the active-alerts endpoint in the TypeScript server
get-alerts asked for /alerts?area=XX, which returns every alert NWS has on
file for the state including expired ones. The Python, Go and Rust servers
all ask for /alerts/active/area/XX.
Measured against the live API for TX: 372 alerts before, 8 after, and the
tools/call response drops from roughly 270KB to 5KB. The other four servers
return the same 8.
Pre-existing on main rather than introduced by the structured-output work,
but it is the one thing that stopped the examples being comparable.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* Match the shared alert and forecast shapes in the TypeScript server
get-alerts published status and headline where Python, Go, Rust and Ruby all
publish description and instructions, and get-forecast periods used the NWS
camelCase spelling with shortForecast instead of detailed_forecast. The
divergence predates this round, but declaring an outputSchema turns it from a
difference in prose formatting into a difference in the published contract,
which defeats the point of a five-language example.
All five now advertise:
get_alerts -> [{event, area, severity, description, instructions}]
get_forecast -> {latitude, longitude, periods[{name, temperature,
temperature_unit, wind_speed, wind_direction,
detailed_forecast}]}
Also limits the forecast to the next 5 periods, which the other four already
did, and uses `??` on the alert fields because NWS sends explicit nulls
rather than omitting them.
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>
* Address review feedback on the TypeScript weather server
- Point the structured-content link at the dated 2026-07-28 spec rather
than /draft, since the surrounding text names that revision.
- Model a missing temperature as null instead of 0. `ForecastPeriod.temperature`
is optional upstream, so the old `?? 0` published an incorrect but
valid-looking 0degF rather than admitting the gap. The output schema now
declares `z.number().nullable()`, and formatPeriod renders "Temperature:
Unknown" for the null case instead of "null degF".
- Fall back to "Unknown" for a missing wind direction, matching the
neighbouring fields.
- Report out-of-band errors via serveStdio's onerror callback.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* Require Node 24 in the TypeScript examples
The client declared `>=20.0.0` and the server declared no floor at all,
while its lockfile root still recorded `>=16.0.0`. Node 20 reached end of
life on 2026-04-30, so it should not be what the examples ask people to
install.
Both packages now require `>=24.0.0`, the Active LTS, matching the Node 24
that ci.yml already provisions and the reasoning its comment already gives.
The SDK's own floor is `>=20`, but that is the oldest runtime the library
tolerates, not what an example should recommend. Lockfile roots regenerated;
no dependency versions move.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
The surrounding sentence names 2026-07-28 as the revision that first allows
an array-rooted schema, but the link pointed at /draft, which moves on to
the next revision and stops matching the claim.
Came in with #164. The same fix is on the open Go, Rust, and Ruby branches.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The surrounding sentence names 2026-07-28 as the revision that first allows
an array-rooted schema, but the link pointed at /draft, which moves on to
the next revision and stops matching the claim.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The surrounding sentence names 2026-07-28 as the revision that first allows
an array-rooted schema, but the link pointed at /draft, which moves on to
the next revision and stops matching the claim.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
`#[tool_handler]` generated `ttl_ms: None, cache_scope: None`, but both are
required on a paginated result at 2026-07-28, so a strict client rejected
tools/list before it could reach a tool call. The server worked around that by
hand-writing list_tools purely to set the two fields.
rust-sdk#1120 fixed the macro, released in rmcp 3.1.1: it now emits the fields
when the negotiated revision expects them and omits them otherwise. Both
lockfiles move to 3.1.2 and the override goes away, so the server is back to the
plain `#[tool_handler]` path the SDK documents.
Verified on the raw wire: after a 2026-07-28 handshake, tools/list carries
`ttlMs: 0` and `cacheScope: "public"` with no code setting them, and the smoke
test's strict client still validates both tools' structured content.
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>
rmcp left beta on 2026-07-28 and reached 3.1.0 on 2026-07-31, so the pin
moves off 3.0.0-beta.2.
get_info now sets server_info. ServerInfo::default() reports rmcp own crate
name and version, so the server was identifying itself as rmcp 3.1.0
rather than weather 1.0.0 as the other three quickstarts do.
The hand-written list_tools stays: rmcp-macros 3.1.0 still generates
ttl_ms: None, cache_scope: None, which a strict client rejects.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Both tools declare an output_schema and return structured_content alongside
the text.
get_alerts declares Vec<Alert>, so it 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.
Error paths return a tool-level error: a tool declaring an output_schema MUST
return conforming structured content, so a path with no data has to fail.
The client compiles every declared outputSchema at connect time and validates
results against it. rmcp does not do this; its docs point at the jsonschema
crate, which is the one new dependency here. 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. A missing .env is no longer fatal, and the
API key is checked after connecting rather than before.
This supersedes #143, which bumped rmcp 0.3 -> 1.4 and failed CI because the
0.3 #[tool] macro API does not survive the jump. The rewrite was required
either way, so the bump is folded in and taken to 3.0.0-beta.2, the first
version with the 2026-07-28 model.
list_tools is hand-written. #[tool_handler] generates one hardcoding
ttl_ms: None, cache_scope: None, but both are required on a paginated result
at 2026-07-28 (SEP-2549) and a strict client rejects the response outright.
get_info does not pin ProtocolVersion::V_2026_07_28 either: rmcp's server
never implements server/discover, so pinning would overstate support.
Model identifier moves to claude-sonnet-5, replacing claude-sonnet-4-20250514,
which is past end of life.
Note that rmcp sends an array-rooted schema as written on every connection
rather than projecting it down, so an older client rejects the tool list.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
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>
go-sdk defaults ServerCapabilities to {"logging":{}} when ServerOptions is
nil — "for historical reasons", as its own doc comment puts it. This server
does no logging, and logging is deprecated as of 2026-07-28 (SEP-2577), so an
example for that revision should not be advertising it.
Passing an empty Capabilities suppresses the default. The tools capability is
still inferred from the registered tools, so server/discover now reports
{"tools":{"listChanged":true}} rather than logging alongside it.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Forecast.Periods reused ForecastPeriod, the struct that decodes the NWS
response, so its camelCase json tags leaked into the declared outputSchema:
temperatureUnit and detailedForecast where the other four quickstarts publish
temperature_unit and detailed_forecast.
Splits out a Period output type, for the same reason Alert is already
separate from AlertProperties: the shape NWS sends and the shape the tool
publishes are different contracts and should not be one struct.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
v1.7.0 shipped on 2026-07-27, so the pin moves off v1.7.0-pre.3.
Removes mcp-client-go.exe and weather-server-go/weather.exe, which were
committed by accident in the previous commit — 14MB of build output that
should never have been in the tree. The tests branch adds the ignore rules
that keep them out.
Also from review: the server README claimed both tools set an OutputSchema.
Only get_alerts does; get_forecast relies on inference from the handler
return type, which is the idiomatic spelling and worth saying so.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Both tools declare an OutputSchema and return StructuredContent alongside the
text.
get_alerts returns []Alert, so it 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 declared schema narrows the inferred ["null","array"] root to
"array": jsonschema-go infers the nullable form because a nil slice is valid
Go, but the handler always builds a slice.
Error paths return an error: a tool declaring an OutputSchema MUST return
conforming structured content, so a path with no data has to fail.
The client compiles every declared OutputSchema at connect time and validates
results against it, using jsonschema-go - already an SDK dependency, so no new
one. Each channel goes to its stated reader: Content is forwarded to the
model, StructuredContent is used as data, reporting how many items came back.
The client no longer treats a missing .env as fatal and checks for
ANTHROPIC_API_KEY after connecting rather than before, matching the Python and
TypeScript clients, so the connection can be exercised without credentials.
Requires go-sdk v1.7.0-pre.3: non-object output schema support (SEP-2106)
landed after v1.6.1 and is in no stable release. Model identifier moves to
claude-sonnet-5; the second call in the tool loop used a hardcoded
ModelClaude3_7SonnetLatest while the first used the package variable, so both
now use the same one.
Note that the SDK sends an array-rooted schema as written on every connection
rather than projecting it down, so an older client rejects the tool list.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* 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>
* Assert on structured output in the smoke tests
The smoke tests connected to each server, listed its tools and stopped there,
so they could not catch a broken structured result.
mcp-test-client now calls every tool that declares an outputSchema and checks
the answer against it: the result must carry structuredContent, and a tool
with an array-rooted schema must return a top-level JSON array rather than an
object wrapping one. Tools with no output schema are left alone, so this is
not a new requirement on any example. The client negotiates with mode "auto",
so it exercises servers of either protocol era. Tool calls reach the live NWS
API; an error result is reported as a skip rather than a failure.
mock-mcp-server moves to the low-level Server and advertises one array-rooted
and one object-rooted tool, with the schemas written out literally. A client
that compiles every declared outputSchema at connect time fails against the
array-rooted one if it assumes output schemas are always objects.
utils.sh no longer swallows build output. A failed build left no binary behind
and the test reported a downstream spawn ENOENT instead of the compiler error,
which is what makes a broken build hard to diagnose from CI logs; #143 is the
current example. check_dependency returns instead of exiting, so a missing
toolchain fails its own test and the suite still prints its summary. Binaries
resolve through a helper that accounts for the .exe suffix.
The test helpers move to the 2.0 MCP SDK packages, where the 2026-07-28
support lives; the examples themselves are untouched. Those require Node 20 or
newer, so CI moves off Node 18 to Node 24, the Active LTS - Node 20 reached
end of life in April 2026.
The Go examples and the Rust client stay uncovered here. Both clients abort
when no .env file is present, so that coverage lands with those examples.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
* Update to the stable 2.0 SDK packages and address review feedback
@modelcontextprotocol/{client,server} 2.0.0 shipped on 2026-07-27, so the
helpers move off 2.0.0-beta.5.
Review fixes:
- strip the UTF-8 BOM that preceded smoke-test.sh's shebang
- ensure_built and ensure_helpers_built return rather than exit, so one
project failing to build no longer aborts the suite before the summary
- engines.node and the documented Node requirement go to 20, matching what
the 2.0 SDK packages actually require
- close the client on the failure path, so a failing test cannot leave the
spawned server running
- the README claimed Go and Rust client coverage that did not exist
Adds the Go weather server to the smoke test, with the Go toolchain CI was
missing. The Go and Rust clients stay uncovered: on main both abort without
a .env, so credential-free startup has to land in their own directories.
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 5 <noreply@anthropic.com>
Apply the same Messages API tool-use fixes that #141 made to the Python
client (mcp-client-python/client.py) to mcp-client-typescript/index.ts:
- Reply to each tool_use with a proper tool_result block carrying
tool_use_id, and append the assistant's full content (preserving the
tool_use block) instead of sending the result as a plain user string.
- Restructure processQuery into a turn-level loop so parallel tool calls
in one response and chained tool calls across turns both work; pass
tools on every follow-up request.
- Add MAX_TOOL_TURNS = 10 cap with a "[Stopped after N tool-use turns]"
notice to prevent unbounded tool-use loops.
- Fix chatLoop to exit cleanly on EOF (Ctrl-D) and SIGINT (Ctrl-C) via
an AbortController wired to readline close, instead of hanging or
throwing on stdin EOF.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
