* Fix the tool-use loop in the Go, Rust, and Ruby clients and add a tool-loop smoke test
## Motivation and Context
Only the Python and TypeScript clients implemented a correct tool-use loop. The other three
had bugs that break ordinary multi-step requests:
- **Go, Rust, Ruby** did a single tool round and then called Claude once more *without*
`tools`, so any request that needs a second tool call stalled. Go silently dropped
`tool_use` blocks from that final response.
- **Ruby** called Claude once per `tool_use` block, each time with a single `tool_result`.
Parallel tool calls produced a malformed message sequence and an API 400.
- **max_tokens** was 1000 in TypeScript and Ruby, 1024 in Go, and unset in Rust. Sonnet 5
thinks adaptively, so 1000 tokens is regularly exhausted mid-thought. Python already used
10000 with a comment explaining why.
- **Ruby** never forwarded MCP `isError` as `is_error`, so the model could not tell a failed
tool call from a successful one. Rust cannot set the flag either (see below).
- **TypeScript** forwarded raw MCP content blocks to Anthropic. The two block shapes differ,
so a non-text result would have failed.
The existing smoke test never noticed because it only checks that each client calls
`tools/list`. None of these bugs was reachable without an API key.
### What changed
All five clients now run the same loop: call tools until Claude answers without one, send
every `tool_result` of a turn in one user message, pass `tools` on every call, and stop
after `MAX_TOOL_TURNS = 10`. `max_tokens` is 10000 everywhere, with the same comment.
Python and TypeScript also keep the last response's text when the turn cap is hit; it used
to be dropped.
Rust keeps the `genai` crate. Its tool-response type has no `is_error` field, so an error
result is marked with an `Error:` prefix in the text and the limitation is commented.
### New smoke test
`tests/helpers/tool-loop-test.ts` starts a fake Anthropic Messages API on a loopback port,
points a client at it through `ANTHROPIC_BASE_URL`, pipes in one query, and checks every
request the client sends. It scripts two parallel tool calls, then a call to a tool the mock
server lacks (an `isError` result), then a final answer, and asserts that tools are passed
each time, `max_tokens` is 10000, all `tool_result`s arrive in one message with matching
ids, and the error is forwarded. `smoke-test.sh` runs it for Python, TypeScript, Go, and
Ruby.
The Rust client is excluded for now: `genai` reads no endpoint variable, and the client
negotiates protocol `2025-11-25`, under which the mock's array-rooted tool is refused at call
time. Both will be addressed in a follow-up that brings all examples to current SDK versions.
## How Has This Been Tested?
- `./tests/smoke-test.sh` passes for every example.
- The new tool-loop test passes all 19 checks for Python, TypeScript, Go, and Ruby.
- The Rust client was driven through the same scripted conversation with a temporary
endpoint resolver (not committed) and passes.
- As a negative check, the Ruby client from `main` was run through the new test. It fails 10
of 19 checks, on exactly the bugs listed above.
- Go and Ruby were built and run in `golang:1.25` and `ruby:3.4` containers.
## Breaking Changes
None. The clients' command lines, output format, and no-key behavior are unchanged.
## Types of changes
- [x] Bug fix (non-breaking change which fixes an issue)
- [ ] New feature (non-breaking change which adds functionality)
- [ ] Breaking change (fix or feature that would cause existing functionality to change)
- [x] Documentation update
## Checklist
- [x] I have read the [MCP Documentation](https://modelcontextprotocol.io)
- [x] My code follows the repository's style guidelines
- [x] New and existing tests pass locally
- [x] I have added appropriate error handling
- [x] I have added or updated documentation as needed
## Additional context
Two pre-existing issues surfaced while testing and are left for a follow-up:
- The Rust client (rmcp 3.1.2) negotiates `2025-11-25`. The TypeScript mock server and the
Python weather server both reject its calls to array-rooted tools under that revision.
Even current rmcp defaults to `2025-11-25`, so the client must request `2026-07-28`
explicitly.
- The Go SDK's tool-result helper sends content as a list of text blocks rather than a
string. The API accepts both, so it is unchanged.
AI assistance: the analysis, code changes, test helper, and this description were prepared
partially manually, partially with Claude Code and reviewed by me.
* Improvements
* Address comments
* 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>
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>
This commit adds `tests/smoke-test.sh`, which performs a smoke test of
all clients and servers. The smoke test tests that the clients and
servers run and that list tools is called.
This commit also adds a GitHub Actions workflow to run the smoke test on
all pull requests and pushes to main.
For practicality, this commit modifies the TypeScript and Python clients
to lazily initialize the Anthropic client, thus allowing tests to skip
setting an API key. This change also provides a friendly error when
users forget to set an API key.
🤖 Generated with [Claude Code](https://claude.com/claude-code)
Co-authored-by: Claude <noreply@anthropic.com>
Co-authored-by: Alex Akimov <alexeyakimov@gmail.com>
