Add story-style examples suite (27 stories + harness + CI) (#2957)

examples/README.md

@@ -1,5 +1,22 @@
-# Python SDK Examples
+# Python SDK examples
 
-This folders aims to provide simple examples of using the Python SDK. Please refer to the
-[servers repository](https://github.com/modelcontextprotocol/servers)
-for real-world servers.
+- [`stories/`](stories/) — **the canonical reference.** One self-verifying
+  example per protocol feature, each with its own README. Start with
+  [`stories/tools/`](stories/tools/); the [stories README](stories/README.md)
+  has the full table and how to run them.
+- [`snippets/`](snippets/) — short extracts embedded into `README.v2.md`. Kept
+  minimal and in sync with the top-level README; not intended to be run
+  standalone.
+- [`servers/everything-server/`](servers/everything-server/) — the conformance
+  target for the cross-SDK
+  [conformance suite](https://github.com/modelcontextprotocol/conformance).
+  Exercises every server capability in one process.
+- [`mcpserver/`](mcpserver/) — single-file v1-era examples retained for the
+  migration guide; superseded by `stories/` and slated for removal.
+- [`clients/`](clients/) and the remaining [`servers/`](servers/) directories
+  (`simple-*`, `sse-polling-demo`, `structured-output-lowlevel`) — standalone
+  v1-era projects still linked from `README.v2.md`; retained pending
+  consolidation into `stories/`.
+
+For real-world servers see the
+[servers repository](https://github.com/modelcontextprotocol/servers).