Make the per-version wire packages private (mcp_types._v*) (#3191)

Author: maxisbey

.github/workflows/shared.yml

@@ -51,7 +51,7 @@ jobs:
       - name: mcp-types installs and imports standalone
         run: |
           uv run --isolated --no-project --with ./src/mcp-types python -c \
-            "import mcp_types, mcp_types.jsonrpc, mcp_types.methods, mcp_types.version, mcp_types.v2025_11_25, mcp_types.v2026_07_28"
+            "import mcp_types, mcp_types.jsonrpc, mcp_types.methods, mcp_types.version, mcp_types._v2025_11_25, mcp_types._v2026_07_28"
 
   test:
     name: test (${{ matrix.python-version }}, ${{ matrix.dep-resolution.name }}, ${{ matrix.os }})

docs/migration.md

@@ -175,6 +175,11 @@ continues to re-export the type names at the top level, so `from mcp import Tool
 unchanged. Only the `mcp.types` submodule and `mcp.shared.version` were removed. The
 package's API reference is at [`mcp_types`](api/mcp_types/index.md).
 
+The supported import surface is `mcp_types`, `mcp_types.jsonrpc`, `mcp_types.methods`, and
+`mcp_types.version`. Underscore-prefixed submodules (`mcp_types._types`, and the generated
+per-protocol-version packages `mcp_types._v2025_11_25` / `mcp_types._v2026_07_28`) are internal
+validators with unstable class names; don't import from them.
+
 **Why:** keeping the wire types in their own package lets tooling and lightweight clients
 depend on the protocol schema without pulling in `httpx2`, `starlette`, `uvicorn`, and the
 rest of the server/transport stack.

pyproject.toml

@@ -218,7 +218,7 @@ max-complexity = 24 # Default is 10
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = ["F401"]
 # Generated by scripts/gen_surface_types.py: raw datamodel-codegen output (TID251 lifts the repo-wide RootModel ban for these generated validators).
-"src/mcp-types/mcp_types/v*/__init__.py" = ["D212", "E501", "I001", "TID251", "UP007", "UP037"]
+"src/mcp-types/mcp_types/_v*/__init__.py" = ["D212", "E501", "I001", "TID251", "UP007", "UP037"]
 "tests/server/mcpserver/test_func_metadata.py" = ["E501"]
 "tests/shared/test_progress_notifications.py" = ["PLW0603"]
 

schema/README.md

@@ -3,8 +3,8 @@
 JSON Schema files for each protocol version the SDK has a wire-shape surface
 package for, vendored from the [spec repository] at the commit recorded in
 `PINNED.json`. `scripts/gen_surface_types.py` reads these to regenerate
-`src/mcp-types/mcp_types/v<version>/__init__.py`; CI runs the generator with
-`--check`.
+`src/mcp-types/mcp_types/_v<version>/__init__.py` (underscore-private: internal
+validators, not public API); CI runs the generator with `--check`.
 
 To bump: drop the new `schema.json` here as `<protocol-version>.json`, update
 the matching entry in `PINNED.json` (commit + sha256), and run

scripts/gen_surface_types.py

@@ -1,8 +1,9 @@
 """Regenerate the per-version wire-shape surface packages from vendored schemas.
 
 Runs `datamodel-code-generator` over each `schema/PINNED.json` entry and
-writes the result to `src/mcp-types/mcp_types/v<version>/__init__.py` with only the
-fixes the raw output needs: a small JSON pre-patch for the known
+writes the result to `src/mcp-types/mcp_types/_v<version>/__init__.py` (the
+underscore marks these as internal validators, not public API) with only
+the fixes the raw output needs: a small JSON pre-patch for the known
 `number`-as-`integer` schema.json defect, a header, full URLs for the spec's
 site-absolute doc links, and per-version epilogue aliases. Run with
 `uv run --frozen --group codegen python scripts/gen_surface_types.py [--check]`.
@@ -270,7 +271,7 @@ def main(argv: list[str] | None = None) -> int:
 
     drift = False
     for entry in load_pinned():
-        target = TYPES_DIR / ("v" + entry["protocol_version"].replace("-", "_")) / "__init__.py"
+        target = TYPES_DIR / ("_v" + entry["protocol_version"].replace("-", "_")) / "__init__.py"
         candidate = build(entry)
         if not args.check:
             target.parent.mkdir(parents=True, exist_ok=True)

src/mcp-types/mcp_types/_types.py

@@ -3,7 +3,7 @@
 One model per protocol construct, carrying every field from every supported
 protocol version, so application code sees a single set of types regardless of
 the negotiated version. Per-field docstrings note version availability. The
-`mcp_types.v*` surface packages carry the schema-exact wire shapes.
+`mcp_types._v*` surface packages carry the schema-exact wire shapes.
 """
 
 from __future__ import annotations

…-types/mcp_types/v2025_11_25/__init__.py …types/mcp_types/_v2025_11_25/__init__.pysrc/mcp-types/mcp_types/v2025_11_25/__init__.py renamed to src/mcp-types/mcp_types/_v2025_11_25/__init__.py src/mcp-types/mcp_types/v2025_11_25/__init__.py renamed to src/mcp-types/mcp_types/_v2025_11_25/__init__.py

@@ -1,4 +1,4 @@
-"""Shared pydantic base for the generated `mcp_types.v*` wire-shape packages."""
+"""Shared pydantic base for the generated `mcp_types._v*` wire-shape packages."""
 
 from pydantic import BaseModel, ConfigDict
 

…-types/mcp_types/v2026_07_28/__init__.py …types/mcp_types/_v2026_07_28/__init__.pysrc/mcp-types/mcp_types/v2026_07_28/__init__.py renamed to src/mcp-types/mcp_types/_v2026_07_28/__init__.py src/mcp-types/mcp_types/v2026_07_28/__init__.py renamed to src/mcp-types/mcp_types/_v2026_07_28/__init__.py

@@ -1,6 +1,6 @@
 """Per-version method maps and parse/serialize functions for MCP traffic.
 
-This module is supported public API; the `mcp_types.v*` packages it draws on
+This module is supported public API; the `mcp_types._v*` packages it draws on
 are internal validators and not for direct import.
 
 Surface maps key `(method, version)` to per-version wire types (key absence is
@@ -18,8 +18,8 @@
 from pydantic import BaseModel, TypeAdapter
 
 import mcp_types as types
-import mcp_types.v2025_11_25 as v2025
-import mcp_types.v2026_07_28 as v2026
+import mcp_types._v2025_11_25 as v2025
+import mcp_types._v2026_07_28 as v2026
 from mcp_types.version import KNOWN_PROTOCOL_VERSIONS
 
 __all__ = [