René's URL Explorer Experiment

Title: Rebuild the docs around tested examples; shrink README.v2.md to a pitch by maxisbey · Pull Request #2978 · modelcontextprotocol/python-sdk · GitHub

Open Graph Title: Rebuild the docs around tested examples; shrink README.v2.md to a pitch by maxisbey · Pull Request #2978 · modelcontextprotocol/python-sdk

X Title: Rebuild the docs around tested examples; shrink README.v2.md to a pitch by maxisbey · Pull Request #2978 · modelcontextprotocol/python-sdk

Description: 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

Open Graph Description: 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 t...

X Description: What this is A ground-up rewrite of the SDK&#39;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 t...

Opengraph URL: https://github.com/modelcontextprotocol/python-sdk/pull/2978

X: @github

direct link

Domain: github.com

Links:

Viewport: width=device-width