docs: rebuild the v2 documentation around a task-based page tree (#2397)

Author: felixweinberger

.github/ISSUE_TEMPLATE/v2-feedback.yml

@@ -0,0 +1,53 @@
+name: v2 feedback
+description: Bugs, API friction, or docs gaps in v2 of the SDK
+title: '[v2] '
+labels: ['v2']
+body:
+    - type: markdown
+      attributes:
+          value: |
+              Thanks for trying v2. Anything that broke, surprised you, or slowed you down is useful — API feedback is explicitly welcome while v2 is in beta.
+
+              Docs: https://ts.sdk.modelcontextprotocol.io/v2/ · Migration from v1: https://ts.sdk.modelcontextprotocol.io/v2/migration/
+    - type: textarea
+      id: what
+      attributes:
+          label: What happened?
+          description: What did you do, and what went wrong (or felt wrong)? Paste error output verbatim if there is any.
+      validations:
+          required: true
+    - type: textarea
+      id: expected
+      attributes:
+          label: What did you expect?
+      validations:
+          required: false
+    - type: textarea
+      id: repro
+      attributes:
+          label: Code to reproduce
+          description: The smallest snippet or repository that shows it. For docs feedback, link the page instead.
+          render: TypeScript
+      validations:
+          required: false
+    - type: input
+      id: version
+      attributes:
+          label: SDK version
+          description: The published version (`npm ls @modelcontextprotocol/server @modelcontextprotocol/client`) or commit.
+      validations:
+          required: false
+    - type: dropdown
+      id: area
+      attributes:
+          label: Area
+          options:
+              - Server
+              - Client
+              - Transports
+              - Auth
+              - Documentation
+              - Migration / codemod
+              - Other
+      validations:
+          required: false

.github/workflows/examples.yml

@@ -45,3 +45,9 @@ jobs:
 
             - name: Run all example pairs (transport × era)
               run: pnpm tsx scripts/examples/run-examples.ts
+
+            # Every docs-page companion under examples/guides/ is a real program
+            # (the page's quoted output comes from it). Run each one; a file whose
+            # first line is "// docs: typecheck-only" is skipped.
+            - name: Run guide examples
+              run: pnpm docs:examples

.gitignore

@@ -51,7 +51,6 @@ dist/
 .worktrees/
 
 # Generated docs-site artifacts
-docs/index.md
 docs/api/
 docs/.vitepress/cache/
 docs/.vitepress/dist/

CLAUDE.md

@@ -131,7 +131,7 @@ basket. See `examples/README.md` for the full story matrix.
 
 - `examples/shared/` — `@mcp-examples/shared` package. Root export is args-only (`parseExampleArgs`, `check`, `siblingPath`); the demo OAuth provider and `InMemoryEventStore` live at the `@mcp-examples/shared/auth` subpath so non-auth stories don't eagerly evaluate better-auth/express/better-sqlite3. Stories import only this plumbing and inline the SDK transport setup themselves — see `examples/CONTRIBUTING.md`.
 - `scripts/examples/` — runner (`run-examples.ts`)
-- `examples/guides/` — typecheck-only snippet collections synced into `docs/{server,client}.md`
+- `examples/guides/` — per-page snippet companions for the `docs/` guide pages (one `<section>/<page>.examples.ts` per page); fences sync via `pnpm sync:snippets`, and the runnable ones are executed in CI by `pnpm docs:examples`
 
 ## Message Flow (Bidirectional Protocol)
 

README.md

@@ -2,17 +2,17 @@
 
 <!-- prettier-ignore -->
 > [!IMPORTANT]
-> **This is the `main` branch which contains v2 of the SDK (currently in development, pre-alpha).**
+> **This is the `main` branch — v2 of the SDK, now in beta** (`@modelcontextprotocol/server`, `@modelcontextprotocol/client`), implementing the [2026-07-28 MCP spec](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/).
 >
-> We anticipate a stable v2 release in Q3 2026 along with the [updated MCP spec](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/). Until then, **v1.x remains the recommended version** for production use. v1.x will continue to receive bug fixes and security updates for at least 6 months after v2 ships to give people time to upgrade.
+> **Have feedback? Please [open a v2 issue](https://github.com/modelcontextprotocol/typescript-sdk/issues/new?template=v2-feedback.yml)** — it is the most useful thing you can do for the SDK right now. The [v2 documentation](https://ts.sdk.modelcontextprotocol.io/v2/) starts with a ten-minute server tutorial.
 >
-> For v1 documentation, see the [V1 API docs](https://ts.sdk.modelcontextprotocol.io/). For v2 API docs, see [`/v2/`](https://ts.sdk.modelcontextprotocol.io/v2/).
+> We expect a stable release alongside the full release of the 2026-07-28 spec on July 28, 2026. Until then, **v1.x remains the supported release for production**; it keeps receiving bug fixes and security updates for at least 6 months after v2 ships. v1 documentation: [ts.sdk.modelcontextprotocol.io](https://ts.sdk.modelcontextprotocol.io/) · v2: [`/v2/`](https://ts.sdk.modelcontextprotocol.io/v2/).
 
 <!-- prettier-ignore -->
 > [!WARNING]
-> **We're temporarily restricting PRs to contributors only to manage reviewer capacity while implementation work for the [new spec](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/) is ongoing**
+> **We're limiting pull requests to contributors while we land the [2026-07-28 spec](https://blog.modelcontextprotocol.io/posts/2026-07-28-release-candidate/) implementation.**
 >
-> Please continue to submit issues as your main source of feedback. We anticipate reopening once we have a stable release for the new spec, currently slated to launch on July 28, 2026.
+> [Issues](https://github.com/modelcontextprotocol/typescript-sdk/issues/new?template=v2-feedback.yml) are the most useful feedback right now — we'll reopen PRs as v2 stabilizes.
 
 [![NPM Version - Server](https://img.shields.io/npm/v/%40modelcontextprotocol%2Fserver?label=%40modelcontextprotocol%2Fserver)](https://www.npmjs.com/package/@modelcontextprotocol/server)
 [![NPM Version - Client](https://img.shields.io/npm/v/%40modelcontextprotocol%2Fclient?label=%40modelcontextprotocol%2Fclient)](https://www.npmjs.com/package/@modelcontextprotocol/client) ![MIT licensed](https://img.shields.io/npm/l/%40modelcontextprotocol%2Fserver)
@@ -129,22 +129,22 @@ async function main() {
 main();
 ```
 
-Ready to build something real? Follow the step-by-step quickstart tutorials:
+Ready to build something real? Follow the step-by-step tutorials:
 
-- [Build a weather server](docs/server-quickstart.md) — server quickstart
-- [Build an LLM-powered chatbot](docs/client-quickstart.md) — client quickstart
+- [Build your first server](docs/get-started/first-server.md) — a stdio weather-alert server, from `npm init` to a tool call
+- [Build your first client](docs/get-started/first-client.md) — connect to that server, list its tools, and call them
 
-The complete code for each tutorial is in [`examples/server-quickstart/`](https://github.com/modelcontextprotocol/typescript-sdk/tree/main/examples/server-quickstart/) and
-[`examples/client-quickstart/`](https://github.com/modelcontextprotocol/typescript-sdk/tree/main/examples/client-quickstart/). For more advanced runnable examples, see:
+For runnable, end-to-end examples beyond the tutorials, see:
 
 - [`examples/README.md`](examples/README.md) — runnable, self-verifying client/server example pairs (one story per directory)
 
 ## Documentation
 
-- [Server Guide](docs/server.md) — building MCP servers: transports, tools, resources, prompts, server-initiated requests, and deployment
-- [Client Guide](docs/client.md) — building MCP clients: connecting, tools, resources, prompts, server-initiated requests, and error handling
-- [FAQ](docs/faq.md) — frequently asked questions and troubleshooting
-- [API docs](https://modelcontextprotocol.github.io/typescript-sdk/)
+- [Build a server](docs/get-started/first-server.md) — your first MCP server, step by step
+- [Build a client](docs/get-started/first-client.md) — your first MCP client, step by step
+- [Documentation site](https://ts.sdk.modelcontextprotocol.io/v2/) — the full guides: tools, resources, prompts, serving over HTTP and stdio, clients, OAuth, and migration
+- [Troubleshooting](docs/troubleshooting.md) — common errors and their fixes
+- [API reference](https://ts.sdk.modelcontextprotocol.io/v2/api/)
 - [MCP documentation](https://modelcontextprotocol.io/docs)
 - [MCP specification](https://modelcontextprotocol.io/specification/latest)
 

docs/.vitepress/config.mts

@@ -24,7 +24,7 @@ export default defineConfig({
     title: 'MCP TypeScript SDK',
     description: 'The TypeScript SDK implementation of the Model Context Protocol specification.',
     base: '/v2/',
-    srcExclude: ['v1/**', 'behavior-surface-pins.md'],
+    srcExclude: ['v1/**', '_meta/**', 'behavior-surface-pins.md'],
     sitemap: { hostname: 'https://ts.sdk.modelcontextprotocol.io/v2/' },
     markdown: {
         config(md) {
@@ -44,26 +44,82 @@ export default defineConfig({
     },
     themeConfig: {
         nav: [
-            { text: 'Guide', link: '/server-quickstart', activeMatch: '^/(server|client|faq)' },
+            { text: 'Get started', link: '/get-started/first-server', activeMatch: '^/get-started/' },
+            { text: 'Servers', link: '/servers/tools', activeMatch: '^/(servers|serving)/' },
+            { text: 'Clients', link: '/clients/connect', activeMatch: '^/clients/' },
             { text: 'Migration', link: '/migration/', activeMatch: '^/migration/' },
             { text: 'API Reference', link: '/api/', activeMatch: '^/api/' },
             { text: 'V1 Docs', link: 'https://ts.sdk.modelcontextprotocol.io/' }
         ],
         sidebar: [
             {
-                text: 'Getting started',
+                text: 'Get started',
                 items: [
-                    { text: 'Server Quickstart', link: '/server-quickstart' },
-                    { text: 'Client Quickstart', link: '/client-quickstart' }
+                    { text: 'Build a server', link: '/get-started/first-server' },
+                    { text: 'Plug into a real host', link: '/get-started/real-host' },
+                    { text: 'Build a client', link: '/get-started/first-client' },
+                    { text: 'Packages', link: '/get-started/packages' },
+                    { text: 'Examples', link: '/get-started/examples' }
                 ]
             },
             {
-                text: 'Guides',
+                text: 'Servers',
                 items: [
-                    { text: 'Server', link: '/server' },
-                    { text: 'Client', link: '/client' }
+                    { text: 'Tools', link: '/servers/tools' },
+                    { text: 'Resources', link: '/servers/resources' },
+                    { text: 'Prompts', link: '/servers/prompts' },
+                    { text: 'Completion', link: '/servers/completion' },
+                    { text: 'Logging, progress, cancellation', link: '/servers/logging-progress-cancellation' },
+                    { text: 'Elicitation', link: '/servers/elicitation' },
+                    { text: 'Sampling (sunset)', link: '/servers/sampling' },
+                    { text: 'Input required', link: '/servers/input-required' },
+                    { text: 'Notifications', link: '/servers/notifications' },
+                    { text: 'Errors', link: '/servers/errors' }
                 ]
             },
+            {
+                text: 'Serving',
+                items: [
+                    { text: 'stdio', link: '/serving/stdio' },
+                    { text: 'HTTP', link: '/serving/http' },
+                    { text: 'Express', link: '/serving/express' },
+                    { text: 'Hono', link: '/serving/hono' },
+                    { text: 'Fastify', link: '/serving/fastify' },
+                    { text: 'Web-standard runtimes', link: '/serving/web-standard' },
+                    { text: 'Sessions, state, scaling', link: '/serving/sessions-state-scaling' },
+                    { text: 'Authorization', link: '/serving/authorization' },
+                    { text: 'Legacy clients', link: '/serving/legacy-clients' }
+                ]
+            },
+            {
+                text: 'Clients',
+                items: [
+                    { text: 'Connect', link: '/clients/connect' },
+                    { text: 'Calling', link: '/clients/calling' },
+                    { text: 'Handle server requests', link: '/clients/server-requests' },
+                    { text: 'Roots (sunset)', link: '/clients/roots' },
+                    { text: 'Subscriptions', link: '/clients/subscriptions' },
+                    { text: 'OAuth', link: '/clients/oauth' },
+                    { text: 'Machine auth', link: '/clients/machine-auth' },
+                    { text: 'Middleware', link: '/clients/middleware' },
+                    { text: 'Caching', link: '/clients/caching' }
+                ]
+            },
+            { text: 'Protocol versions', link: '/protocol-versions' },
+            {
+                text: 'Advanced',
+                collapsed: true,
+                items: [
+                    { text: 'Low-level server', link: '/advanced/low-level-server' },
+                    { text: 'Custom methods', link: '/advanced/custom-methods' },
+                    { text: 'Schema libraries', link: '/advanced/schema-libraries' },
+                    { text: 'Custom transports', link: '/advanced/custom-transports' },
+                    { text: 'Wire schemas', link: '/advanced/wire-schemas' },
+                    { text: 'Gateway', link: '/advanced/gateway' }
+                ]
+            },
+            { text: 'Testing', link: '/testing' },
+            { text: 'Troubleshooting', link: '/troubleshooting' },
             {
                 text: 'Migration',
                 items: [
@@ -72,10 +128,6 @@ export default defineConfig({
                     { text: '2026-07-28 protocol support', link: '/migration/support-2026-07-28' }
                 ]
             },
-            {
-                text: 'FAQ',
-                items: [{ text: 'FAQ', link: '/faq' }]
-            },
             {
                 text: 'API Reference',
                 collapsed: true,

docs/.vitepress/theme/custom.css

@@ -6,6 +6,24 @@
  * light, white on slate dark. We map that onto VitePress brand variables.
  */
 
+/* ------------------------------------------------------------------ layout */
+
+/*
+ * The default theme caps the doc column at 688px (and the page at 1440px),
+ * which forces horizontal scrolling on most of our ~100-column code blocks.
+ * Let the layout breathe and the column grow so typical snippets fit;
+ * genuinely long lines still scroll inside their own block.
+ */
+:root {
+    --vp-layout-max-width: 1680px;
+}
+
+/* !important: the default rule is a scoped component style ([data-v-…]), which
+   otherwise out-specifies any override written here. */
+.VPDoc.has-aside .content-container {
+    max-width: 960px !important;
+}
+
 /* ---------------------------------------------------------------- branding */
 
 :root {