docs: correctness and coverage pass for the 2026-07-28 revision#2389
Conversation
|
![github-advanced-security[bot]](https://avatars.githubusercontent.com/in/57789?s=60&v=4){kind=small}
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
felixweinberger
force-pushed
the
fweinberger/docs-beta-pass
branch
from
88fb5f2 to
6663eda
Compare
@modelcontextprotocol/client
@modelcontextprotocol/codemod
@modelcontextprotocol/core
@modelcontextprotocol/server
@modelcontextprotocol/server-legacy
@modelcontextprotocol/express
@modelcontextprotocol/fastify
@modelcontextprotocol/hono
@modelcontextprotocol/node
commit: |
Verify the guides against the current public surface and fill coverage gaps: - Era-scope the push-style API docs: ctx.mcpReq.elicitInput/requestSampling and server.server.listRoots() throw on 2026-07-28-era connections; point each section at the in-band input_required replacement. Scope the 'bidirectional' framing and deprecation windows to 2025-era connections. - New coverage: serving over HTTP with createMcpHandler/toNodeHandler, serveStdio options, subscription streams (client.listen, honoredFilter, closed reasons, watch loop) and server change notifications (handler.notify, era semantics), response caching (client cache options + server cacheHints), the native input_required/MRTR story incl. the requestState codec and manual multi-round-trip handling, OAuth resource-server setup, RFC 8707 resource indicators, issuer metadata validation, SdkHttpError and the ClientHttp* codes, listMaxPages, per-request logLevel on 2026-07-28. - Quickstarts: rewrite the client tutorial tool loop to handle multiple tool_use blocks per response (single user turn carrying all tool_results, is_error propagation, loop until no tool calls remain); add isError to the weather server's failure returns; drop unneeded 'as const' casts, dead bin entries, and the chmod build step; rename the example packages to @mcp-examples/* and add READMEs noting the manifests are monorepo-internal. - Fix stale paths/links (authExtensions.ts, vitest.setup.js, hostHeaderValidation.ts), index the migration guides from documents.md, note @modelcontextprotocol/server-legacy/sse in the FAQ, and add the registry pins row to behavior-surface-pins.md. All code fences are synced from typechecked example sources (pnpm sync:snippets clean; examples typecheck + lint pass; typedoc clean).
Documents that handlers returning input_required stay write-once on 2025-era connections, where the SDK's default-on legacy shim fulfils the embedded requests by issuing real elicitation/sampling/roots requests over the session, and links the shim section of the 2026-07-28 support guide for the configuration knobs and limits. Merge together with (or after) the legacy-shim change itself: the described behavior and the linked support-guide section land with it. Without that change, an input_required return on a 2025-era connection fails the request.
felixweinberger
force-pushed
the
fweinberger/docs-beta-pass
branch
from
6663eda to
7cd032c
Compare
There was a problem hiding this comment.
Thanks for addressing the earlier feedback — the scratch/ working files are gone and the resource-template completion note now sits at the end of the Completions section. I didn't find any new issues on this revision, but given the volume of behavioral claims this docs pass makes about the 2026-07-28 surface (defaults, error codes, era-gating semantics), it's worth a maintainer's read before merge.
Extended reasoning...
Overview
This PR is a docs-and-examples-only pass: it rewrites large portions of docs/server.md and docs/client.md to cover the 2026-07-28 revision (input_required / requestState, subscription streams, response caching, cache hints, per-request log level, OAuth resource-server setup, createMcpHandler/serveStdio serving entries), reworks both quickstarts (serveStdio factory pattern, fixed multi-tool-use Anthropic loop), adds 16 type-checked snippet regions in examples/guides/.examples.ts, renames the two quickstart example packages to the @mcp-examples/ scope, and fixes stale paths in the FAQ and behavior-surface-pins docs. No SDK source code is touched.
Prior feedback
Both issues from my earlier review rounds are addressed in the current revision: the accidentally committed scratch/ directory (17 triage/working files) is no longer tracked on the branch, and the resource-template completions sentence has been moved to the end of the Completions section where the 'instead' has its antecedent.
Security risks
None direct — no runtime code changes. The main risk surface is documentation that teaches insecure patterns; the new auth and requestState sections actually do the opposite (HMAC codec guidance, attacker-controlled-input warnings, cachePartition isolation note, sensitive-data elicitation caveats). Spot-checks of behavioral claims (e.g. listMaxPages default 64) match the source, and every new code sample is synced from type-checked example files covered by CI typecheck/lint and pnpm sync:snippets --check.
Level of scrutiny
This is not a simple/mechanical change: it makes a large number of specific prose claims about SDK defaults, error codes, and era-gating behavior that type-checking cannot validate, and it changes what the quickstarts teach newcomers (serveStdio factory, isError on failures, the corrected tool-use loop). Per the repo's own review conventions (verify every claim against the SDK surface), a maintainer familiar with the 2026-07-28 implementation should give the prose a pass; I'm not in a position to certify all of it without much deeper verification, so I'm deferring rather than approving.
Other factors
The bug-hunting pass on this revision found no issues, the changeset-ignore update for the @mcp-examples/* rename is consistent with the existing wildcard entry, and the example package renames are private/ignored so nothing publishes. The only outstanding automated finding is the CodeQL rate-limiting note on the auth example snippet, which is expected for illustrative example code.
2 participants
Verifies every claim in
docs/(server and client guides, both quickstarts, FAQ) against the SDK surface on main and fills the coverage gaps for the 2026-07-28 revision. Every code sample in the guides is now synced from a type-checked source.Motivation and Context
The guides predate the 2026-07-28 implementation landing on main, and the costliest errors were silent ones: docs teaching APIs that now throw.
ctx.mcpReq.requestSampling(),ctx.mcpReq.elicitInput(), andserver.server.listRoots()as fully functional with no era caveat. On a connection pinned to 2026-07-28 (serveStdio/createMcpHandler) all three throwSdkError(MethodNotSupportedByProtocolVersion)before anything reaches the wire; the "MCP is bidirectional" framing had the same problem.inputRequired(...)) had no guide coverage at all: noinputRequiredbuilder, noacceptedContent, norequestState, no client-side auto-fulfilment or manual mode.tool_useblock: it re-sent the full assistant content per tool call and issued the follow-up request withouttools, so multi-tool turns produced malformed conversations and dead-end follow-ups.createMcpHandlerwas used in examples but never introduced, and HTTP had no 2026-07-28 serving section (stdio did).Highlights:
createMcpHandler+toNodeHandler),input_required/ multi-round trips (includingrequestStateintegrity guidance and a worked example), change notifications in both eras (handler.notify, the event bus, capability gating), cache hints (SEP-2549), and an OAuth resource-server setup (requireBearerAuth, metadata router,WWW-Authenticatechallenge);serveStdiooptions; stale source links fixed.cacheMode,responseCacheStore,cachePartition,defaultCacheTtlMs), subscription streams (listen(),honoredFilter, close reasons, a watch loop) with era notes onsubscribeResource()andlistChanged,input_requiredauto-fulfilment defaults plus the manual mode, the per-request log level on 2026-07-28 (LOG_LEVEL_META_KEY) versussetLoggingLevel(), RFC 8707 resource indicators and issuer validation (RFC 9207 / RFC 8414 §3.3),SdkHttpErrorand theClientHttp*codes,listMaxPages, and version-negotiation details (supportedProtocolVersions,connect({ prior })semantics).serveStdiofrom acreateServer()factory (the current serving entry; it owns the transport and serves current hosts and the 2026-07-28 revision from the same factory) instead of hand-wiring aStdioServerTransport; the client tool loop rewritten to the Messages API shape (one assistant turn, one user turn carrying everytool_result,is_errorpropagated, loop until no tool calls remain); weather-server failure returns setisError: true; dropped the unneededas constcasts, deadbinentries, and thechmodbuild step; both example packages renamed to the@mcp-examples/*scope used by every other example (changeset ignore list updated); READMEs note the manifests are monorepo-internal.//#regionblocks inexamples/guides/*.examples.ts, so every new code sample is type-checked and kept in sync bypnpm sync:snippets(two previously inline fences converted along the way).authExtensions.ts,vitest.setup.js,hostHeaderValidation.ts), the@modelcontextprotocol/server-legacy/sseescape hatch noted, a missing row added to the behavior-surface-pins inventory.How Has This Been Tested?
Docs and examples only.
pnpm sync:snippets --check, the examplestypecheckandlint, andpnpm docs:check(typedoc, warnings as errors) all pass; relative links and anchors were checked. Every behavioral claim was verified against the SDK source on current main before being written, and the quickstart apps type-check against the workspace packages.Breaking Changes
None. The two example packages are private and on the changeset ignore list, so the
@mcp-examples/*rename publishes nothing.Types of changes
Checklist
Additional context
#2381 merged while this was in flight, so alongside the native 2026-07-28
input_requireddocumentation this also adds the one-paragraph note that on 2025-era connections the default-on legacy shim fulfilsinput_requiredreturns over the session, linking the shim section of the support guide for its options. The docs index still omits the migration guides on purpose: now that they declarechildren:, adding them todocuments.mdpulls them into the typedoc document tree and turns on anchor validation whose heading slugs differ from GitHub's for inline-code headings (typedoc drops the code spans), which fails the build for GitHub-correct links — including two of the existing migration-internal ones. Reconciling the two sluggers belongs to the docs-site work.