Import protocol types through mcp.types in all user-facing code

Every distribution whose modules a project imports should be a
declared dependency, and `mcp` exact-pins `mcp-types` such that
declaring `mcp-types` independently is pointless-to-harmful. So code
that depends on `mcp` should import through `mcp.types` (one declared
dependency, one import root), and `mcp_types` is the spelling only for
projects that install `mcp-types` without the SDK. Previously the
examples and docs imported `mcp_types` directly, modeling exactly the
transitive-import leak this rule forbids.

To let the sweep drop every direct `mcp_types` import, `mcp.types` is
now a package: `types/__init__.py` (the existing mirror) plus a
`types/version.py` mirror of `mcp_types.version` (star re-export, so
every name is the same object), and `mcp_types.version` gains an
explicit `__all__` so its typing import does not leak through the
mirror. A parity test pins the version mirror.

Rewrite the type imports in every example, snippet, and docs tutorial,
remap the `hl_lines` highlights that the import reordering shifted,
and restate the migration guide / What's New / installation docs
around the "import through the package you depend on" rule.

Author: maxisbey

docs/advanced/extensions.md

@@ -128,7 +128,7 @@ The same file's `main()` is the whole client story, both halves of it:
 The one interceptive hook. Override `intercept_tool_call` to observe, short-circuit,
 or veto a tool call:
 
-```python title="server.py" hl_lines="18-25"
+```python title="server.py" hl_lines="17-24"
 --8<-- "docs_src/extensions/tutorial005.py"
 ```
 
@@ -158,7 +158,7 @@ A **client extension** is the same contract from the consuming side: a bundle of
 client-side behaviour behind one identifier. Pass instances to
 `Client(extensions=[...])` and call tools normally:
 
-```python title="client.py" hl_lines="67-69"
+```python title="client.py" hl_lines="66-68"
 --8<-- "docs_src/extensions/tutorial006.py"
 ```
 
@@ -188,7 +188,7 @@ client = Client(mcp, extensions=[advertise("com.example/search")])
 Subclass `ClientExtension` and override only what you need. Three contribution
 kinds, each with a default: `settings()`, `claims()`, and `notifications()`.
 
-```python title="client.py" hl_lines="18-19 44-45 47-48"
+```python title="client.py" hl_lines="17-18 43-44 46-47"
 --8<-- "docs_src/extensions/tutorial006.py"
 ```
 
@@ -226,12 +226,12 @@ claimed shape reaching a session-tier caller raises `UnexpectedClaimedResult`.
 ### Extension verbs
 
 An extension's own request methods need no client-side registration. A vendor request
-type subclasses `mcp_types.Request` and goes through `client.session.send_request`,
+type subclasses `mcp.types.Request` and goes through `client.session.send_request`,
 as in [Serving your own methods](#serving-your-own-methods). One addition: when a
 params key must ride the `Mcp-Name` header (extension specs such as tasks require
 this for their verbs), the request type declares `name_param`:
 
-```python title="client.py" hl_lines="23-26 47-48"
+```python title="client.py" hl_lines="22-25 46-47"
 --8<-- "docs_src/extensions/tutorial007.py"
 ```
 

docs/advanced/low-level-server.md

@@ -14,7 +14,7 @@ For everything else, stay on `MCPServer`.
 
 This is the `search_books` tool that **[Tools](../servers/tools.md)** writes in nine lines of `@mcp.tool()`, with the sugar removed:
 
-```python title="server.py" hl_lines="23 27 33"
+```python title="server.py" hl_lines="22 26 32"
 --8<-- "docs_src/lowlevel/tutorial001.py"
 ```
 
@@ -80,7 +80,7 @@ That generalises. An exception raised from a low-level handler is **always** a p
 
 `on_call_tool` is the single entry point for every tool on the server. You route on `params.name`:
 
-```python title="server.py" hl_lines="39-44"
+```python title="server.py" hl_lines="38-43"
 --8<-- "docs_src/lowlevel/tutorial002.py"
 ```
 
@@ -91,7 +91,7 @@ That generalises. An exception raised from a low-level handler is **always** a p
 
 Declare `output_schema` on the `Tool` and put `structured_content` on the result. Both are yours:
 
-```python title="server.py" hl_lines="20-24 37"
+```python title="server.py" hl_lines="19-23 36"
 --8<-- "docs_src/lowlevel/tutorial003.py"
 ```
 
@@ -117,7 +117,7 @@ The server never compares the two fields. This SDK's `Client` does: return `stru
 
 Use it for record IDs, trace IDs, anything your UI needs and your prompt doesn't:
 
-```python title="server.py" hl_lines="38"
+```python title="server.py" hl_lines="37"
 --8<-- "docs_src/lowlevel/tutorial004.py"
 ```
 
@@ -144,7 +144,7 @@ No `resources`, no `prompts`: there is nothing to back them. Pass `on_list_promp
 
 `Server` is generic in the type its lifespan yields. Annotate it once and the object is typed everywhere it surfaces:
 
-```python title="server.py" hl_lines="25-27 45-46 51"
+```python title="server.py" hl_lines="24-26 44-45 50"
 --8<-- "docs_src/lowlevel/tutorial005.py"
 ```
 

docs/advanced/middleware.md

@@ -16,7 +16,7 @@ If `Server(name, on_call_tool=...)` is new to you, read **[The low-level Server]
 
 One server, one tool, one middleware that logs how long each message took:
 
-```python title="server.py" hl_lines="40-46 50"
+```python title="server.py" hl_lines="39-45 49"
 --8<-- "docs_src/middleware/tutorial001.py"
 ```
 

docs/advanced/pagination.md

@@ -10,7 +10,7 @@ Pagination is for the server whose resource list is really a database: thousands
 
 ## A server that pages
 
-```python title="server.py" hl_lines="13 16-17"
+```python title="server.py" hl_lines="12 15-16"
 --8<-- "docs_src/pagination/tutorial001.py"
 ```
 
@@ -38,7 +38,7 @@ The tenth page comes back with `next_cursor` set to `None`. Done.
 
 Every `list_*` method on `Client` (`list_tools`, `list_resources`, `list_resource_templates`, `list_prompts`) takes a `cursor=` keyword. Draining a paged list is one `while True`:
 
-```python title="client.py" hl_lines="27-33"
+```python title="client.py" hl_lines="26-32"
 --8<-- "docs_src/pagination/tutorial002.py"
 ```
 

docs/client/caching.md

@@ -25,7 +25,7 @@ Out of the box every result says `ttlMs: 0, cacheScope: "private"`: immediately
 
 On the low-level `Server`, handlers build their results by hand, and `ttl_ms` / `cache_scope` are just fields on the result models. A handler that sets them explicitly always wins over the constructor map, field by field:
 
-```python title="server.py" hl_lines="11 17"
+```python title="server.py" hl_lines="10 16"
 --8<-- "docs_src/caching/tutorial002.py"
 ```
 
@@ -39,7 +39,7 @@ One caveat on paginated lists: the protocol requires the **same `cacheScope` on
 
 On a 2026-07-28 session, `Client` honors the hints for you: it has a built-in response cache, on by default. A result that arrives carrying a `ttlMs` is stored, and an identical call within that TTL is served from the cache with no round trip. A result that carries *no* hint is not cached: hint-less results get `CacheConfig.default_ttl_ms`, which defaults to `0` (immediately stale), so a server that declares nothing sees exactly the call-for-call traffic it always did.
 
-```python title="client.py" hl_lines="34 36 39"
+```python title="client.py" hl_lines="33 35 38"
 --8<-- "docs_src/caching/tutorial003.py"
 ```
 

docs/client/callbacks.md

@@ -19,7 +19,7 @@ That is the server half, and the **[Elicitation](../handlers/elicitation.md)** p
 
 ## The elicitation callback
 
-```python title="client.py" hl_lines="7-11 17-18"
+```python title="client.py" hl_lines="6-10 16-17"
 --8<-- "docs_src/client_callbacks/tutorial002.py"
 ```
 

docs/client/index.md

@@ -135,7 +135,7 @@ A tool that raises does **not** raise in your client. It comes back as an ordina
 
 The resource verbs come in pairs: two ways to list, one way to read.
 
-```python title="client.py" hl_lines="23-32"
+```python title="client.py" hl_lines="22-31"
 --8<-- "docs_src/client/tutorial004.py"
 ```
 
@@ -174,7 +174,7 @@ A host hands those messages straight to the model. That is the whole feature.
 
 A server with a completion handler can autocomplete prompt and resource-template arguments as the user types.
 
-```python title="client.py" hl_lines="28-32"
+```python title="client.py" hl_lines="27-31"
 --8<-- "docs_src/client/tutorial006.py"
 ```
 
@@ -187,7 +187,7 @@ The answer is in `result.completion.values`. Type `"p"` and the server comes bac
 
 Every `list_*` method takes a `cursor=` keyword and every result carries a `next_cursor`. When `next_cursor` is `None`, you have everything.
 
-```python title="client.py" hl_lines="23-31"
+```python title="client.py" hl_lines="22-30"
 --8<-- "docs_src/client/tutorial007.py"
 ```
 

docs/client/session-groups.md

@@ -42,7 +42,7 @@ Create a `ClientSessionGroup` and call **`connect_to_server`** once per server:
 
 You fix this at the group, not at the servers. Pass a function of `(name, server_info)` and the group runs it on every name it registers:
 
-```python title="client.py" hl_lines="8-9 16"
+```python title="client.py" hl_lines="7-8 15"
 --8<-- "docs_src/session_groups/tutorial004.py"
 ```
 

docs/client/subscriptions.md

@@ -8,7 +8,7 @@ This page is the client end: opening the stream, watching it beside your main fl
 
 A subscription is one context manager. Entering it sends the request, with your keyword arguments as the subscription filter, and waits for the server's acknowledgment, so the stream is live by the time the block starts.
 
-```python title="client.py" hl_lines="16 19 29"
+```python title="client.py" hl_lines="15 18 28"
 --8<-- "docs_src/subscriptions/tutorial003.py"
 ```
 

docs/get-started/installation.md

@@ -31,9 +31,9 @@ These docs describe **v2**, currently a release candidate, so the version pin is
 
 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.
+* `mcp-types`: every protocol type (requests, results, content blocks) as its own package, versioned in lockstep with the SDK. Code that depends on `mcp` imports it through the `mcp.types` alias (every `from mcp.types import ...` in these docs); import `mcp_types` directly only in a project that installs `mcp-types` without the SDK.
 * [`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`](https://docs.pydantic.dev/): what every `mcp.types` model is built on, plus all schema generation and validation.
 * [`httpx2`](https://pypi.org/project/httpx2/): the HTTP client behind the Streamable HTTP and SSE *client* transports, with server-sent events support built in.
 * [`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.