Rebuild the docs around tested examples; shrink README.v2.md to a pitch (#2978)

pyproject.toml

@@ -137,6 +137,7 @@ include = [
     "src/mcp",
     "src/mcp-types/mcp_types",
     "tests",
+    "docs_src",
     "examples/stories",
     "examples/servers",
     "examples/snippets",
@@ -166,6 +167,9 @@ executionEnvironments = [
     { root = "examples/servers", extraPaths = [
         "examples/servers/simple-auth",
     ], reportUnusedFunction = false },
+    # docs_src/ holds the complete, runnable code examples included into docs/*.md.
+    # Decorated (@mcp.tool/...) module-level functions are never called by name.
+    { root = "docs_src", reportUnusedFunction = false },
 ]
 
 [tool.ruff]