docs: comprehensive GA pass — stable-release wording, released-spec links, install tags - #2566
Conversation
|
| Name | Type |
|---|---|
| @modelcontextprotocol/client | Patch |
| @modelcontextprotocol/codemod | Patch |
| @modelcontextprotocol/core-internal | Patch |
| @modelcontextprotocol/core | Patch |
| @modelcontextprotocol/express | Patch |
| @modelcontextprotocol/fastify | Patch |
| @modelcontextprotocol/hono | Patch |
| @modelcontextprotocol/node | Patch |
| @modelcontextprotocol/server-legacy | Patch |
| @modelcontextprotocol/server | Patch |
| @modelcontextprotocol/examples | Patch |
| @mcp-examples/bearer-auth-web | Patch |
| @mcp-examples/bearer-auth | Patch |
| @mcp-examples/caching | Patch |
| @mcp-examples/cli-client | Patch |
| @mcp-examples/client-quickstart | Patch |
| @mcp-examples/custom-methods | Patch |
| @mcp-examples/custom-version | Patch |
| @mcp-examples/dual-era | Patch |
| @mcp-examples/elicitation | Patch |
| @mcp-examples/extension-capabilities | Patch |
| @mcp-examples/gateway | Patch |
| @mcp-examples/hono | Patch |
| @mcp-examples/json-response | Patch |
| @mcp-examples/legacy-routing | Patch |
| @mcp-examples/mrtr | Patch |
| @mcp-examples/oauth-client-credentials | Patch |
| @mcp-examples/oauth | Patch |
| @mcp-examples/parallel-calls | Patch |
| @mcp-examples/prompts | Patch |
| @mcp-examples/repl | Patch |
| @mcp-examples/resources | Patch |
| @mcp-examples/sampling | Patch |
| @mcp-examples/schema-validators | Patch |
| @mcp-examples/scoped-tools | Patch |
| @mcp-examples/server-quickstart | Patch |
| @mcp-examples/shared | Patch |
| @mcp-examples/sse-polling | Patch |
| @mcp-examples/standalone-get | Patch |
| @mcp-examples/stateless-legacy | Patch |
| @mcp-examples/stickynotes | Patch |
| @mcp-examples/streaming | Patch |
| @mcp-examples/subscriptions | Patch |
| @mcp-examples/todos-server | Patch |
| @mcp-examples/tools | Patch |
| @modelcontextprotocol/test-conformance | Patch |
| @modelcontextprotocol/test-e2e | Patch |
| @modelcontextprotocol/test-helpers | Patch |
| @modelcontextprotocol/test-integration | Patch |
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
@modelcontextprotocol/client
@modelcontextprotocol/codemod
@modelcontextprotocol/core
@modelcontextprotocol/server
@modelcontextprotocol/server-legacy
@modelcontextprotocol/express
@modelcontextprotocol/fastify
@modelcontextprotocol/hono
@modelcontextprotocol/node
commit: |
…inks at the released revision
felixweinberger
changed the title
![claude[bot]](https://avatars.githubusercontent.com/in/1236702?s=60&v=4){kind=small}
There was a problem hiding this comment.
LGTM — docs/comment-only GA sweep; the two inline comments are one-line nit fixes (Fastify missing from one prose list, the v1 site banner's "v2 beta" wording) worth folding in before merge. The beta-WARNING banners in the package READMEs flagged in the previous review round are now reworded to stable-release wording in this diff, so the npm-tarball concern is resolved.
Extended reasoning...
Overview
Docs-only GA sweep across 20 files: install commands drop the @beta tag, beta banners are rewritten to stable-release wording (root README, package READMEs, docs landing page, site banner component, llms.txt header, CONTRIBUTING, issue template), draft-spec links move to the released /specification/2026-07-28/ revision (including the 16 JSDoc links in packages/core/src/schemas.ts and two moved ext-auth links), and the Fastify adapter is added to the package lists it was missing from. The four .ts files touched contain only JSDoc/comment string edits — I verified there is no runtime behavior change anywhere in the diff.
Security risks
None. No executable code changes; the modified TypeScript files change only documentation strings inside comments. The ext-auth spec links were verified to point at the stable/ path that replaced draft/.
Level of scrutiny
Moderate despite being docs-only, because the package READMEs are baked into the immutable 2.0.0 npm tarballs — an error here is effectively permanent in the GA artifacts. That was the substance of the previous review round's blocking comment (beta [!WARNING] banners contradicting the @latest install commands), and the current diff resolves it: both READMEs now open with stable-release wording. I re-verified the sweep's completeness: no @beta remains in any markdown surface, and the only surviving specification/draft references are internal test metadata (test/e2e/requirements.ts) and a config.mts comment describing the render-time link rewrite — neither is a published surface, matching the PR's stated deferral of the schema-artifact flip.
Other factors
The two confirmed findings are genuine but trivial nits (a one-word prose omission in the root README, and the v1 docs-site banner in docs/v1/.vitepress/theme/Banner.vue still saying "v2 beta documentation" — that shell builds from main per scripts/build-docs-site.sh, so it is in scope but continuously rebuildable, not baked into an immutable artifact). Neither blocks merge. The changeset-bot note about no changeset is expected for a docs-only PR. The whether-to-declare-GA decision itself is a maintainer product call the PR author owns, not a code-correctness question.
There was a problem hiding this comment.
LGTM — docs-only GA sweep; all prior review feedback (tarball README beta banners, root-README Fastify prose, v1-site banner) is addressed at 5986f9d, and the one remaining inline comment is a one-line nit in docs/clients/middleware.md that can land here or as a follow-up.
Extended reasoning...
Overview
This PR is a documentation-only GA pass across 21 files: install-tag flips (@beta → bare/@latest), beta-banner rewrites (package READMEs, root README, both VitePress site banners, llms.txt header, CONTRIBUTING, issue template), and draft-spec links repointed at the released /specification/2026-07-28/ revision. The only two source files touched — packages/core/src/schemas.ts and packages/server/src/server/server.ts — change JSDoc comments exclusively (verified against the diff); no runtime behavior, exports, or types change anywhere.
Security risks
None. No auth, crypto, transport, or handler logic is touched. The two .ts files change only comment text and JSDoc @see links (including two ext-auth links that moved from draft/ to stable/).
Level of scrutiny
Moderate despite being docs-only, because the package READMEs are baked into the immutable 2.0.0 npm tarballs. The earlier blocking concern — the surviving 'This is a beta release' WARNING in packages/client/README.md and packages/server/README.md — was fixed by the author (both now read 'v2 is the stable release line'), and a repo-wide grep confirms no published surface retains beta framing (remaining hits are historical CHANGELOG/changeset entries the PR deliberately keeps, and core-internal internals covered by the PR's explicitly deferred spec.types.2026-07-28.ts regeneration). The 'stable release line' claim itself is a release-timing decision already made in #2565 (prerelease mode exited); this PR just aligns prose with it.
Other factors
Both earlier nits (root-README 'for example Express, Hono…' enumeration and the v1-site Banner.vue) were fixed in head commit 5986f9d. This run's remaining finding is a genuine but minor completeness nit — docs/clients/middleware.md:29 enumerates the framework-adapter packages without @modelcontextprotocol/fastify — in a continuously rebuilt docs-site page outside the diff, so it does not create any irreversible artifact and is safe to fix in a follow-up. The spec links target a revision that publishes tomorrow (2026-07-28), a coordination window the PR description acknowledges. No changeset is needed for a docs-only change.
| ### Optional middleware packages | ||
|
|
||
| The SDK also publishes optional “middleware” packages that help you **wire MCP into a specific runtime or web framework** (for example Express, Hono, or Node.js `http`). | ||
| The SDK also publishes optional “middleware” packages that help you **wire MCP into a specific runtime or web framework** (for example Express, Fastify, Hono, or Node.js `http`). |
There was a problem hiding this comment.
🟡 One framework-adapter enumeration survives the Fastify sweep: the :::info Not the framework middleware packages callout in docs/clients/middleware.md (line 29) still lists only @modelcontextprotocol/express, @modelcontextprotocol/hono, and @modelcontextprotocol/node, and its see-also links cover only Express and Hono. Add @modelcontextprotocol/fastify to the list (and optionally Fastify to the see-also links) — the callout exists precisely to enumerate which packages carry the word "middleware", so the omission makes it factually incomplete. (Anchored here on the in-diff middleware prose; the edit target is docs/clients/middleware.md, which is not in the diff.)
Extended reasoning...
The issue. This PR's staleness sweep adds the Fastify adapter to "every package list" (the PR description's own words), and the head commit 5986f9d ("catch the v1-site banner and one more middleware mention") fixed the previously flagged README.md instance. One enumeration of the framework-adapter packages still survives without Fastify: docs/clients/middleware.md line 29, the :::info Not the framework middleware packages callout on the published v2 docs site:
The
@modelcontextprotocol/express,@modelcontextprotocol/hono, and@modelcontextprotocol/nodepackages also carry the word "middleware" — those are server-side framework adapters for mounting a handler. See Express and Hono.
Why the list is meant to be exhaustive. Unlike the "for example Express, Fastify, Hono…" prose fixed elsewhere in this PR, this callout is not illustrative: its entire purpose is to disambiguate which packages carry the word "middleware" from the client request middleware this page documents. @modelcontextprotocol/fastify (under packages/middleware/fastify) is one of them, and a docs/serving/fastify.md page exists for the see-also link. An enumeration whose job is completeness is wrong when incomplete.
Step-by-step proof.
- This PR merges; the v2 docs site rebuilds from
main. - A reader lands on the Client middleware page and reads the callout to learn which SDK packages are framework adapters.
- The callout names three adapters; the reader concludes there is no Fastify adapter — while
docs/serving/fastify.md,packages/middleware/README.md, the root README, andpackages/server/README.md(all updated by this very PR) say there is.
Why nothing else catches it. The callout is plain prose — no lint, snippet-sync, or test validates docs enumerations. Repo-wide grep confirms this is the only remaining framework-adapter enumeration missing Fastify after 5986f9d (docs/get-started/packages.md, docs/migration/upgrade-to-v2.md, docs/serving/http.md, docs/index.md, both READMEs, and packages/middleware/README.md all include it).
Relation to earlier review comments. This is not a duplicate of the earlier README.md:101 inline comment — that site was already fixed by head commit 5986f9d. This is a different file the same sweep missed; fixing README.md does not fix this line. It matches REVIEW.md's Completeness recurring catch: "when a PR replaces a pattern, grep for surviving instances of the old form."
Fix. In docs/clients/middleware.md line 29, change the enumeration to "The @modelcontextprotocol/express, @modelcontextprotocol/fastify, @modelcontextprotocol/hono, and @modelcontextprotocol/node packages…" and optionally extend the see-also to "See Express, Fastify and Hono."
Severity. Nit: this is docs-site prose, rebuilt continuously from main, so a one-line follow-up commit corrects it with no irreversible artifact (unlike the npm-tarball READMEs). Nothing breaks if it merges as-is — it just leaves the GA sweep slightly short of its own stated scope.
…ion note The GA docs pass (modelcontextprotocol#2566) added fastify to the package listings in README.md, packages/middleware/README.md and packages/server/README.md, but the client-middleware page still names only express, hono and node when disambiguating client middleware from the framework adapters. Add fastify to that list and link the existing serving/fastify.md page. Closes modelcontextprotocol#2112.
1 participant
Comprehensive sweep flipping all documentation surfaces to the stable release ahead of 2.0.0, so nothing published claims v2 is prerelease or points at the draft spec:
@betatags removed everywhere (barenpm install;npx codemod@latestkeeps the tag as a cache-buster)./specification/2026-07-28/…): three guide pages, the migration guides (including deleting a note that instructed tooling to track the draft schema directory), and the 16 spec links in the publishedcoreschemas module that render on IDE hover. Two links to ext-auth documents that moved fromdraft/tostable/were dead and are fixed.Historical alpha/beta references in the migration guides ("if you were on a v2 alpha…") are deliberately kept — that is what a migration guide is for.
One deferred item:
spec.types.2026-07-28.tsregeneration onto the versioned upstream schema directory can only run once the spec repository publishesschema/2026-07-28/; the fetch script already anticipates the flip.