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

docs/installation.md

@@ -1,31 +1,49 @@
 # Installation
 
-The Python SDK is available on PyPI as [`mcp`](https://pypi.org/project/mcp/) so installation is as simple as:
+The Python SDK is on PyPI as [`mcp`](https://pypi.org/project/mcp/). It requires **Python 3.10+**.
+
+These docs describe **v2**, which is in alpha, so the version pin is not optional yet:
+
+=== "uv"
+
+    ```bash
+    uv add "mcp[cli]==2.0.0a3"
+    ```
 
 === "pip"
 
     ```bash
-    pip install mcp
-    ```
-=== "uv"
-
-    ```bash
-    uv add mcp
+    pip install "mcp[cli]==2.0.0a3"
     ```
 
-The following dependencies are automatically installed:
+!!! warning "Why the pin"
+    Installers never select a pre-release unless you name one, so an unpinned `uv add "mcp[cli]"`
+    gives you the latest **v1.x** release, which these docs do not describe. Check the
+    [release history](https://pypi.org/project/mcp/#history) for the newest alpha before you copy
+    the line above.
 
-- [`httpx`](https://pypi.org/project/httpx/): HTTP client to handle HTTP Streamable and SSE transports.
-- [`httpx-sse`](https://pypi.org/project/httpx-sse/): HTTP client to handle SSE transport.
-- [`pydantic`](https://pypi.org/project/pydantic/): Types, JSON schema generation, data validation, and [more](https://docs.pydantic.dev/latest/).
-- [`starlette`](https://pypi.org/project/starlette/): Web framework used to build the HTTP transport endpoints.
-- [`python-multipart`](https://pypi.org/project/python-multipart/): Handle HTTP body parsing.
-- [`sse-starlette`](https://pypi.org/project/sse-starlette/): Server-Sent Events for Starlette, used to build the SSE transport endpoint.
-- [`pydantic-settings`](https://pypi.org/project/pydantic-settings/): Settings management used in MCPServer.
-- [`uvicorn`](https://pypi.org/project/uvicorn/): ASGI server used to run the HTTP transport endpoints.
-- [`jsonschema`](https://pypi.org/project/jsonschema/): JSON schema validation.
-- [`pywin32`](https://pypi.org/project/pywin32/): Windows specific dependencies for the CLI tools.
+    The same applies to one-off commands: `uv run --with "mcp==2.0.0a3" ...`, not `uv run --with mcp ...`.
 
-This package has the following optional groups:
+    If your *package* depends on `mcp`, add a `<2` upper bound (for example `mcp>=1.27,<2`) before
+    the stable v2 lands so the major version bump doesn't surprise you.
 
-- `cli`: Installs `typer` and `python-dotenv` for the MCP CLI tools.
+## What gets installed
+
+You don't need to know any of this to use the SDK, but if you're wondering what each dependency is for:
+
+* `mcp-types`: every protocol type (requests, results, content blocks) as its own package, versioned in lockstep with the SDK. Every `from mcp_types import ...` in these docs is this package.
+* [`anyio`](https://anyio.readthedocs.io/): the async runtime. The whole SDK is written against anyio, so it runs on either `asyncio` or `trio`.
+* [`pydantic`](https://docs.pydantic.dev/): what every `mcp_types` model is built on, plus all schema generation and validation.
+* [`pydantic-settings`](https://docs.pydantic.dev/latest/concepts/pydantic_settings/): server configuration via `MCP_*` environment variables and `.env` files.
+* [`httpx`](https://www.python-httpx.org/) and [`httpx-sse`](https://pypi.org/project/httpx-sse/): the HTTP client behind the Streamable HTTP and SSE *client* transports.
+* [`starlette`](https://www.starlette.io/), [`uvicorn`](https://www.uvicorn.org/), [`sse-starlette`](https://pypi.org/project/sse-starlette/), and [`python-multipart`](https://pypi.org/project/python-multipart/): the HTTP *server* transports.
+* [`jsonschema`](https://pypi.org/project/jsonschema/): validates a tool's structured output against its declared output schema.
+* [`pyjwt[crypto]`](https://pyjwt.readthedocs.io/): OAuth token handling for authorization.
+* [`opentelemetry-api`](https://opentelemetry-python.readthedocs.io/): just the lightweight API, so the SDK's tracing middleware costs nothing unless you install an OpenTelemetry SDK and exporter yourself.
+* [`typing-extensions`](https://typing-extensions.readthedocs.io/) and `typing-inspection`: modern typing features on Python 3.10.
+* `pywin32`: Windows only, used for `stdio` subprocess management.
+
+## Optional extras
+
+* `mcp[cli]` adds [`typer`](https://typer.tiangolo.com/) and `python-dotenv` for the `mcp` command-line tool (`mcp dev`, `mcp run`, `mcp install`). You'll want this during development; you may not need it in a deployed server.
+* `mcp[rich]` adds [`rich`](https://rich.readthedocs.io/) for nicer server logs.