Rebuild the docs around tested examples; shrink README.v2.md to a pitch

[maxisbey]

What this is

A ground-up rewrite of the SDK's documentation as a tutorial, replacing most of the 2,500-line README.v2.md with a docs/ tree where every code example is a complete file that the test suite imports and runs.

No new dependencies and no new infrastructure: the pieces (pymdownx.snippets, pytest-examples, the in-memory Client, mkdocs strict mode) were already in the repo. This PR makes them load-bearing.

How a chapter works

docs_src/tools/tutorial004.py      # a complete, runnable server: the example IS a file
docs/tutorial/tools.md             # the page includes it:  --8<-- "docs_src/tools/tutorial004.py"
tests/docs_src/test_tools.py       # drives it through Client(mcp) in memory and asserts
                                   # exactly what the page's prose claims

So a page can say "call it with limit=100 and the call fails before your function runs" and there is a test named after that sentence proving it. When the SDK changes behaviour, the docs fail in CI instead of drifting.

The book

• Tutorial - User Guide (14): first steps, tools, structured output, resources, prompts, the Context, handling errors, lifespan, media, completions, elicitation, progress, logging, testing
• Running your server (2): mcp.run(), stdio/Streamable HTTP, the CLI, settings; ASGI mounting and deployment
• The Client (4): the client object, callbacks, client transports, protocol versions
• Advanced (8): multi-round-trip requests, the low-level Server, pagination, middleware, authorization, OAuth clients, session groups, deprecated features
• README.v2.md shrinks to a short intro (badges, one server, one client) that points at the docs; docs/concepts.md, docs/authorization.md, docs/low-level-server.md and docs/testing.md are replaced by chapters.

Validation (all of it runs in CI)

• tests/docs_src/: 649 tests drive every example through the in-memory Client, at 100% branch coverage.
• tests/docs_src/test_shape.py: book-wide invariants. Every docs_src file is included by a page, every --8<-- target exists, no private mcp import, no deprecated or retired API in anything a reader copies, plain-ASCII punctuation, every example imports.
• tests/test_examples.py (pytest-examples) lints every inline fence on every page.
• A new docs job runs mkdocs build --strict on PRs, so a broken include or nav entry is a red check.
• docs_src/ is type-checked by pyright and linted/formatted by ruff like any other source.

Notes for reviewers

• The deprecated 2026-07-28 surfaces (sampling push, roots, protocol logging) are documented in exactly one place, advanced/deprecated.md, and used by zero examples; a per-module warning filter in tests/docs_src/ turns an accidental use into a hard test failure.
• Two small src/mcp changes ride along: 21 # pragma: no cover markers on lines the new tests execute are removed (strict-no-cover requires it), and the Client(mode=...) error hint now uses a semicolon instead of a U+2014 dash, because docs/client/protocol-versions.md quotes that error verbatim and the docs use plain-ASCII punctuation throughout.
• Deliberate follow-ups, not in this PR: turn the bold cross-references into links, give the client-side examples an if __name__ == "__main__" block, document MCPServer(website_url=...).

_{AI Disclaimer}

[cubic-dev-ai]

4 issues found across 198 files

<sub>Partial review: This PR has more than 50 files, so cubic reviewed the highest-priority files first. During the trial, paid plans get a higher file limit.
You can try an ultrareview to bypass the file limit, comment @cubic-dev-ai ultrareview. Learn more.

Fix all with cubic | Re-trigger cubic</sub>

[cubic-dev-ai]

1 issue found across 33 files (changes from recent commits).

<sub>Reply with feedback, questions, or to request a fix.

Fix all with cubic | Re-trigger cubic</sub>

[Kludex]

Shouldn't this just be src? I don't think docs_src is necessary.

[maxisbey]

It's load-bearing for mkdocs serve, because the pages don't contain their code blocks any more: every example is a file under docs_src/ pulled in with --8<--, and snippets resolve from the repo root, outside mkdocs' default watch set. With the entry:

INFO - Watching paths for changes: 'docs', 'mkdocs.yml', 'src/mcp', 'docs_src'

and without it docs_src is absent, so editing an example while serve is running doesn't rebuild the page that includes it (same reason src/mcp is in the list, for mkdocstrings). It only affects serve. Happy to drop it if you'd rather, but it's the difference between live-reload working and not for the files a docs author actually edits.

_{AI Disclaimer}

[claude]

🟡 The 'Try it' step says to go to Resources and read greeting://World, but the example server registers greeting as a templated resource (@mcp.resource("greeting://{name}")), so the Inspector's Resources list is empty and the entry only appears under Resource Templates, where the reader has to supply name=World first. Consider mirroring the wording the very next chapter (docs/tutorial/first-steps.md) already uses for the identical resource, e.g. 'find greeting under Resource Templates, give it the name World, and read it'.

Extended reasoning...

What the page says vs. what the server does. docs/index.md line 73 instructs: "Now go to Resources and read greeting://World", followed by the expected output Hello, World!. The example the page includes (docs_src/index/tutorial001.py) registers the resource as a template: @mcp.resource("greeting://{name}"). A templated resource is never listed as a concrete resource, so in the Inspector the Resources list for this server is empty; greeting shows up only in the Resource Templates section, where the reader must type World into the name field before anything can be read. There is no listed entry called greeting://World to click on, so the sentence cannot be followed exactly as written.

It contradicts the very next chapter. docs/tutorial/first-steps.md (line 65) walks through the identical resource on the identical server shape and goes out of its way to explain this exact behaviour: "The Resources list is empty. greeting is under Resource Templates, because greeting://{name} has a parameter: there is no single resource to list until someone supplies a name. Give it World and read it." So the landing page promises an experience that the next page explicitly says will not happen. A first-time reader who hits the empty list on the landing page gets their first moment of "the docs are wrong" on the very first page of a docs rewrite whose stated premise is that every claim is exact and test-backed.

Why the existing tests don't catch it. tests/docs_src/test_index.py exercises tutorial001.py through the in-memory Client (read_resource("greeting://World") works fine programmatically, since resources/read matches templates). The discrepancy is purely about what the Inspector's UI shows and what the prose tells the reader to click, which no test can see.

Step-by-step. (1) The reader pastes server.py from the landing page and runs uv run mcp dev server.py. (2) They follow line 73, open the Resources tab, and look for greeting://World in the resources list. (3) The list is empty — @mcp.resource("greeting://{name}") produces a resource template, which the Inspector lists separately under Resource Templates. (4) They have to notice that section themselves, click greeting, type World into the name field, and read it — a step the page never mentions, but which first-steps.md spells out for the same resource one click later.

On the counter-argument. One reviewer noted that "Resources" is the name of the Inspector tab, and that tab also contains the Resource Templates section — so the reader does land in the right place and will figure it out within seconds. That is fair, and it is why this is a nit rather than a blocker: the friction is small and self-resolving. But the instruction still elides the one step (supplying name) that makes the read possible, and it still tells a different story than the next chapter tells about the same server. The first-steps wording exists precisely because the author judged this worth explaining; the landing page should not contradict it.

How to fix. One phrase: e.g. "Now go to Resources, find greeting under Resource Templates, give it the name World, and read it:" — or any wording that matches first-steps.md. Prose-only, no code or test changes.