Skip to content

Update examples for the 2026-07-28 era - #537

Merged
koic merged 1 commit into
modelcontextprotocol:mainfrom
koic:update_examples_for_2026_07_28
Aug 29, 2026
Merged

Update examples for the 2026-07-28 era#537
koic merged 1 commit into
modelcontextprotocol:mainfrom
koic:update_examples_for_2026_07_28

Conversation

@koic

@koic koic commented Aug 28, 2026

Copy link
Copy Markdown
Member

Motivation and Context

The runnable examples drifted from the SDK they ship with:

  • POST requests whose Accept header does not cover both application/json and text/event-stream are answered 406, so the cURL walkthroughs no longer worked as printed.
  • MCP::Client#connect now defaults to mode: :auto, which adopts the sessionless modern lifecycle (2026-07-28) against a dual-era server; the Streamable HTTP client example requires a session and broke against its own server.
  • POST responses on an established session arrive as an SSE stream, which the hand-rolled HTTP client did not parse.
  • notification_tool claimed to send SSE notifications but only returned a Tool::Response.
  • http_client.rb read a resource URI the server never registered and skipped notifications/initialized.

Handshake examples now offer the latest handshake protocol version (2025-11-25) instead of 2024-11-05, the Streamable HTTP client pins mode: :legacy for its session-based demo, notification_tool reports real notifications/progress events requested through _meta.progressToken, and the interactive client streams those events from the POST response so they are visible on screen.

The modern lifecycle itself had no runnable example, so a new server and client pair (modern_http_server.rb, modern_http_client.rb) shows the sessionless flow end to end: server/discover capability discovery, the per-request _meta envelope with the Mcp-Method and Mcp-Name headers (stamped by the SDK client automatically), resultType stamping, SEP-2549 cache hints, a SEP-2322 multi round-trip deploy tool resumed automatically by the client's elicitation handler, and the removal of legacy-only methods such as ping. The same server keeps serving the legacy initialize flow, routed per request by the MCP-Protocol-Version header. examples/README.md documents the pair and adds a cURL walkthrough covering the modern headers, the envelope, and the multi round-trip exchange.

How Has This Been Tested?

  • ruby examples/stdio_client.rb against stdio_server.rb
  • ruby examples/http_client.rb against http_server.rb
  • ruby examples/streamable_http_client.rb against streamable_http_server.rb, including the progress stream
  • ruby examples/modern_http_client.rb against modern_http_server.rb (discover, modern adoption, cache hints, resultType, the multi round-trip resume, ping rejection)
  • The cURL walkthroughs in the banners and examples/README.md, including the requestState echo and a legacy initialize against the modern example server

Breaking Changes

None.

Types of changes

  • Bug fix (non-breaking change which fixes an issue)
  • 新建 feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to change)
  • Documentation update

Checklist

  • I have read the MCP Documentation
  • My code follows the repository's style guidelines
  • 新建 and existing tests pass locally
  • I have added appropriate error handling
  • I have added or updated documentation as needed

## Motivation and Context

The runnable examples drifted from the SDK they ship with:

- POST requests whose `Accept` header does not cover both `application/json` and `text/event-stream` are answered 406,
  so the cURL walkthroughs  no longer worked as printed.
- `MCP::Client#connect` now defaults to `mode: :auto`, which adopts the sessionless modern lifecycle (2026-07-28)
  against a dual-era server; the Streamable HTTP client example requires a session and broke against its own server.
- POST responses on an established session arrive as an SSE stream, which the hand-rolled HTTP client did not parse.
- `notification_tool` claimed to send SSE notifications but only returned a `Tool::Response`.
- `http_client.rb` read a resource URI the server never registered and skipped `notifications/initialized`.

Handshake examples now offer the latest handshake protocol version (`2025-11-25`) instead of `2024-11-05`,
the Streamable HTTP client pins `mode: :legacy` for its session-based demo, `notification_tool` reports
real `notifications/progress` events requested through `_meta.progressToken`, and the interactive client streams
those events from the POST response so they are visible on screen.

The modern lifecycle itself had no runnable example, so a new server and client pair (`modern_http_server.rb`,
`modern_http_client.rb`) shows the sessionless flow end to end: `server/discover` capability discovery,
the per-request `_meta` envelope with the `Mcp-Method` and `Mcp-Name` headers (stamped by the SDK client automatically),
`resultType` stamping, SEP-2549 cache hints, a SEP-2322 multi round-trip `deploy` tool resumed automatically by
the client's elicitation handler, and the removal of legacy-only methods such as `ping`. The same server keeps serving
the legacy `initialize` flow, routed per request by the `MCP-Protocol-Version` header. `examples/README.md` documents
the pair and adds a cURL walkthrough covering the modern headers, the envelope, and the multi round-trip exchange.

## How Has This Been Tested?

- `ruby examples/stdio_client.rb` against `stdio_server.rb`
- `ruby examples/http_client.rb` against `http_server.rb`
- `ruby examples/streamable_http_client.rb` against `streamable_http_server.rb`, including the progress stream
- `ruby examples/modern_http_client.rb` against `modern_http_server.rb` (discover, modern adoption, cache hints,
  `resultType`, the multi round-trip resume, `ping` rejection)
- The cURL walkthroughs in the banners and `examples/README.md`, including the `requestState` echo and a legacy `initialize`
  against the modern example server

## Breaking Changes

None.
@koic
koic merged commit 11f9aac into modelcontextprotocol:main Aug 29, 2026
11 checks passed
@koic
koic deleted the update_examples_for_2026_07_28 branch August 29, 2026 09:55
注册 for free to join this conversation on GitHub. Already have an account? 登录 to comment

标签

None yet

项目

None yet

Development

Successfully merging this pull request may close these issues.

2 participants