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

.changeset/config.json

@@ -8,10 +8,9 @@
     "baseBranch": "main",
     "updateInternalDependencies": "patch",
     "ignore": [
-        "@modelcontextprotocol/examples-client",
+        "@modelcontextprotocol/examples",
         "@modelcontextprotocol/examples-client-quickstart",
-        "@modelcontextprotocol/examples-server",
         "@modelcontextprotocol/examples-server-quickstart",
-        "@modelcontextprotocol/examples-shared"
+        "@mcp-examples/*"
     ]
 }

.changeset/pre.json

@@ -5,11 +5,9 @@
     "@modelcontextprotocol/eslint-config": "2.0.0",
     "@modelcontextprotocol/tsconfig": "2.0.0",
     "@modelcontextprotocol/vitest-config": "2.0.0",
-    "@modelcontextprotocol/examples-client": "2.0.0-alpha.0",
+    "@modelcontextprotocol/examples": "2.0.0-alpha.0",
     "@modelcontextprotocol/examples-client-quickstart": "2.0.0-alpha.0",
-    "@modelcontextprotocol/examples-server": "2.0.0-alpha.0",
     "@modelcontextprotocol/examples-server-quickstart": "2.0.0-alpha.0",
-    "@modelcontextprotocol/examples-shared": "2.0.0-alpha.0",
     "@modelcontextprotocol/client": "2.0.0-alpha.0",
     "@modelcontextprotocol/core": "2.0.0-alpha.0",
     "@modelcontextprotocol/express": "2.0.0-alpha.0",

.github/workflows/examples.yml

@@ -0,0 +1,44 @@
+name: Examples
+
+on:
+    push:
+        branches:
+            - main
+            - v2-2026-07-28
+    pull_request:
+    workflow_dispatch:
+
+concurrency:
+    group: ${{ github.workflow }}-${{ github.ref }}
+    cancel-in-progress: true
+
+jobs:
+    # Builds the workspace + examples and e2e-runs every examples/<story>/ pair
+    # over every transport it supports. Each client.ts is a self-verifying test
+    # (asserts and exits non-zero on any mismatch). This is part of the per-PR
+    # gate basket — a red examples run blocks merge.
+    examples:
+        name: examples (build + e2e)
+        runs-on: ubuntu-latest
+        steps:
+            - uses: actions/checkout@v6
+
+            - name: Install pnpm
+              uses: pnpm/action-setup@fc06bc1257f339d1d5d8b3a19a8cae5388b55320 # v5.0.0
+              with:
+                  run_install: false
+
+            - uses: actions/setup-node@v6
+              with:
+                  node-version: 24
+                  cache: pnpm
+                  cache-dependency-path: pnpm-lock.yaml
+
+            - run: pnpm install
+
+            # The workspace packages the examples import resolve to built dists
+            # (the gap that killed an earlier examples smoke suite).
+            - run: pnpm run build:all
+
+            - name: Run all example pairs (transport × era)
+              run: pnpm tsx scripts/run-examples.ts

.prettierrc.json

@@ -13,7 +13,8 @@
         {
             "files": "**/*.md",
             "options": {
-                "printWidth": 280
+                "printWidth": 280,
+                "proseWrap": "preserve"
             }
         }
     ]

CLAUDE.md

@@ -121,11 +121,15 @@ Pluggable JSON Schema validation (`packages/core/src/validators/`):
 
 ### Examples
 
-Runnable examples in `examples/`:
-
-- `examples/server/src/` - Various server configurations (stateful, stateless, OAuth, etc.)
-- `examples/client/src/` - Client examples (basic, OAuth, parallel calls, etc.)
-- `examples/shared/src/` - Shared utilities (OAuth demo provider, etc.)
+Runnable examples in `examples/<story>/{server.ts,client.ts}` — each story is its own
+`@mcp-examples/<story>` workspace package and a self-verifying e2e test (the client connects,
+asserts results, exits non-zero on mismatch). `pnpm run:examples` runs every story over its
+configured transport×era legs; the `examples (build + e2e)` CI job is part of the per-PR gate
+basket. See `examples/README.md` for the full story matrix.
+
+- `examples/harness.ts` — dual-transport scaffold (`connectFromArgs`, `runServerFromArgs`, `httpUrlFromArgs`, `runClient`)
+- `examples/shared/` — `@mcp-examples/shared` package (demo OAuth provider, `InMemoryEventStore`)
+- `examples/guides/` — typecheck-only snippet collections synced into `docs/{server,client}.md`
 
 ## Message Flow (Bidirectional Protocol)
 

CONTRIBUTING.md

@@ -112,16 +112,19 @@ Then:
 
 ### Running Examples
 
-See [`examples/server/README.md`](examples/server/README.md) and [`examples/client/README.md`](examples/client/README.md) for a full list of runnable examples.
+See [`examples/README.md`](examples/README.md) for the full list of runnable examples — one self-verifying client/server pair per directory.
 
 Quick start:
 
 ```bash
-# Run a server example
-pnpm --filter @modelcontextprotocol/examples-server exec tsx src/simpleStreamableHttp.ts
+# Run any story's server
+pnpm --filter @mcp-examples/tools server -- --http --port 3000
 
-# Run a client example (in another terminal)
-pnpm --filter @modelcontextprotocol/examples-client exec tsx src/simpleStreamableHttp.ts
+# Run its client (in another terminal)
+pnpm --filter @mcp-examples/tools client -- --http http://127.0.0.1:3000/
+
+# Run every story over every transport × era leg
+pnpm run:examples
 ```
 
 ## Releasing v1.x Patches

README.md

@@ -137,8 +137,7 @@ Ready to build something real? Follow the step-by-step quickstart tutorials:
 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:
 
-- [`examples/server/README.md`](examples/server/README.md) — server examples index
-- [`examples/client/README.md`](examples/client/README.md) — client examples index
+- [`examples/README.md`](examples/README.md) — runnable, self-verifying client/server example pairs (one story per directory)
 
 ## Documentation
 

docs/client-quickstart.md

@@ -420,5 +420,5 @@ If you see:
 Now that you have a working client, here are some ways to go further:
 
 - [**Client guide**](./client.md) — Add OAuth, middleware, sampling, and more to your client.
-- [**Example clients**](https://github.com/modelcontextprotocol/typescript-sdk/tree/main/examples/client) — Browse runnable client examples.
+- [**Example clients**](https://github.com/modelcontextprotocol/typescript-sdk/tree/main/examples) — Browse runnable client examples.
 - [**FAQ**](./faq.md) — Troubleshoot common errors.