Uh oh!
There was an error while loading. Please reload this page.
docs: correctness and coverage pass for the 2026-07-28 revision - #2389
Conversation
|
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
88fb5f2 to
6663edaCompare@modelcontextprotocol/client@modelcontextprotocol/codemod@modelcontextprotocol/core@modelcontextprotocol/server@modelcontextprotocol/server-legacy@modelcontextprotocol/express@modelcontextprotocol/fastify@modelcontextprotocol/hono@modelcontextprotocol/nodecommit: |
Uh oh!
There was an error while loading. Please reload this page.
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.
6663eda to
7cd032cCompareThere 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.
Uh oh!
There was an error while loading. Please reload this page.
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.