refactor(examples): per-story directory layout, self-verifying CI harness, and the start-here / capstone story set

[felixweinberger]

Restructures examples/ from two flat src/ directories into one self-verifying client/server pair per feature, each its own workspace package, and adds a CI job that builds the workspace and runs every pair end to end over every transport and protocol era it supports.

Motivation and Context

Examples were typechecked and built but never executed in CI, so silent drift was possible. Every story now ships a server.ts (what you would deploy) and a client.ts (what a host would write — connects with the public client API, asserts results, exits non-zero on any mismatch). The client is the e2e test; the harness is pure orchestration. Each story is a standalone @mcp-examples/<story> package, so a user can cd examples/tools && pnpm install && pnpm run server and it works.

How Has This Been Tested?

scripts/run-examples.ts runs 21 stories across 46 transport×era legs, all passing locally. The full workspace gate suite (typecheck / lint / docs:check / unit / e2e / integration / conformance) is green. sync:snippets --check passes with the new guide snippet paths.

Breaking Changes

None to published packages. The private @modelcontextprotocol/examples-server / -client packages collapse into per-story @mcp-examples/* packages and a shared @mcp-examples/shared; documentation links to example files are updated. One stale changeset that referenced the removed package is dropped.

Types of changes

• 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)
• Documentation update

Checklist

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

Additional context

Layout: examples/<story>/{server.ts, client.ts, README.md, package.json}. The dual-transport / dual-era scaffold (connectFromArgs, runServerFromArgs) lives in @mcp-examples/shared; the harness reads each package's "example": { transports?, era?, excluded? } field for pins. By default each story runs four legs: stdio×modern, stdio×legacy, http×modern, http×legacy.

New stories: tools / prompts / resources (the "start here" primitives), streaming (progress / logging / cancellation), stickynotes (the capstone — tools, resources, list_changed and elicitation in one stateful server), caching (server-side cacheHints stamping), legacy-routing (isLegacyRequest in front of a strict modern entry), subscriptions (the subscriptions/listen API end to end), and oauth-client-credentials (machine-to-machine grant — demo authorization server + a createMcpHandler resource server behind requireBearerAuth; no browser).

Stories that stay single-transport or single-era (each README.md says why): bearer-auth, hono, json-response, legacy-routing, stateless-legacy are HTTP-only by nature; mrtr and subscriptions are modern-era-only (the methods don't exist on the 2025 protocol); elicitation-form and sampling are stdio-only legacy (push-style server→client requests need a long-lived bidirectional connection — the modern equivalent is the mrtr story).

Excluded (documented in each package): examples/oauth/ (browser authorization-code flow), sse-polling, standalone-get.

[changeset-bot]

⚠️ No Changeset found

Latest commit: 9ab402d

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[pkg-pr-new]

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/client@2325

@modelcontextprotocol/codemod

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/codemod@2325

@modelcontextprotocol/server

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/server@2325

@modelcontextprotocol/server-legacy

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/server-legacy@2325

@modelcontextprotocol/express

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/express@2325

@modelcontextprotocol/fastify

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/fastify@2325

@modelcontextprotocol/hono

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/hono@2325

@modelcontextprotocol/node

npm i https://pkg.pr.new/modelcontextprotocol/typescript-sdk/@modelcontextprotocol/node@2325

commit: 9ab402d

[claude]

🔴 On the 2026-07-28 (inputRequired) path, plan_trip and link_account never terminate when the user declines or cancels: a non-accept response just re-issues the identical inputRequired round, so an auto-fulfilling client re-prompts until the round limit errors out — whereas the 2025-era branches of the same tools return a terminal "trip " / "link " result after one decline. register_user in this same file shows the correct pattern (presence-check inputResponses before re-issuing, terminal result on non-accept); mirroring it in both tools fixes the asymmetry.

Extended reasoning...

What the bug is. Two of the three tools in this canonical elicitation example handle a non-accept answer asymmetrically between protocol eras on the 2026-07-28 (inputRequired) path. link_account's modern branch checks only auth?.action !== 'accept' and re-issues the same inputRequired.elicitUrl round when the user declines or cancels. plan_trip's modern branch derives all of its state from acceptedContent(...), which (per packages/core/src/shared/inputRequired.ts:144-155) returns undefined whenever candidate.action !== 'accept' — so a declined dest or dates response is indistinguishable from "never asked" and the handler asks the same question again.

The code path that triggers it. A 2026-07-28 client calls plan_trip (or link_account); the tool returns inputRequired; the client's auto-fulfilment driver (packages/core/src/shared/inputRequiredDriver.ts) dispatches the embedded elicitation/create to the user, who clicks Decline or Cancel; the driver retries the call with inputResponses['dest'] = { action: 'decline' } (or ['auth']); the handler sees acceptedContent(...) === undefined / action !== 'accept' and returns the same inputRequired round again. The driver loops up to inputRequired.maxRounds (default 10) and then throws SdkErrorCode.InputRequiredRoundsExceeded — so the user is re-prompted repeatedly and the call ends in an error, instead of completing gracefully with a "declined" result.

Why this is an oversight, not a design choice. The 2025-era branches of the same two tools terminate after one decline (return { content: [{ type: 'text', text: \trip ${step1.action}` }] } / \link ${result.action}`), and register_user in this same file gets the modern path right: it first presence-checks ctx.mcpReq.inputResponses?.['form'] (so "asked but declined" is distinguishable from "not asked yet") and returns a terminal `registration ${response.action}` for non-accept. The README's framing — "the protocol carries it differently but the user experience is the same" — is violated only for these two tools.

Why CI doesn't catch it. examples/elicitation/client.ts only exercises the decline path for register_user (formAction = 'decline'); the elicitation handler always answers accept for plan_trip's and link_account's requests, so every harness leg stays green.

Step-by-step proof (plan_trip, modern leg).

1. Client calls plan_trip with no inputResponses → destination is undefined → handler returns inputRequired({ inputRequests: { dest: ... } }).
2. The auto-fulfilment driver shows the destination form; the user clicks Decline → driver retries with inputResponses = { dest: { action: 'decline' } }.
3. acceptedContent(inputResponses, 'dest') returns undefined (action is not 'accept'), requestState is unset → destination is still undefined → the handler returns the identical inputRequired round from step 1.
4. Steps 2–3 repeat until round 10, when the driver throws InputRequiredRoundsExceeded and callTool rejects — versus the 2025 leg of the same tool, which would have returned trip decline after step 2. link_account follows the same loop via its auth?.action !== 'accept' check.

Impact. This is the documented reference implementation of the multi-round-trip elicitation pattern (linked from docs/server.md and examples/README.md), so the buggy "re-ask on decline" shape will be copy-pasted into real servers, where a user clicking Decline/Cancel gets an endless re-prompt (auto-fulfilling host) or a confusing rounds-exceeded error (manual host).

How to fix. Mirror register_user's presence check in both tools: for link_account, if inputResponses['auth'] exists and action !== 'accept', return `link ${action}` instead of re-issuing; for plan_trip, read inputResponses['dest'] / ['dates'] directly and return `trip ${action}` on a present non-accept response before falling through to the re-issue branches.