Add mcp.types deprecation shim over mcp_types

`import mcp.types` is the most common v1 idiom, and in v2 it fails
with ModuleNotFoundError, which reads as a broken install. Restore it
as a compatibility shim that re-exports mcp_types and emits an
MCPDeprecationWarning on first import, naming both breaks at first
contact: the new module and the snake_case field renames. It is
slated for removal in v3.

The v1 names that no longer exist raise an ImportError naming the
replacement, rather than a bare "cannot import name". The shim is
excluded from the generated API reference and documented in the
migration guide.

Author: maxisbey

docs/migration.md

@@ -14,7 +14,7 @@ Every section heading below names the API it affects, so searching this page for
 |---|---|---|
 | `FastMCP` renamed to `MCPServer` | `ModuleNotFoundError: No module named 'mcp.server.fastmcp'` | [`FastMCP` renamed](#fastmcp-renamed-to-mcpserver) |
 | Fields renamed from camelCase to snake_case | `AttributeError: 'Tool' object has no attribute 'inputSchema'` | [snake_case fields](#field-names-changed-from-camelcase-to-snake_case) |
-| `mcp.types` moved to the `mcp-types` package | `ModuleNotFoundError: No module named 'mcp.types'` | [`mcp.types` moved](#mcptypes-moved-to-the-mcp-types-package) |
+| `mcp.types` moved to the `mcp-types` package | `MCPDeprecationWarning: mcp.types is deprecated; import from mcp_types.` | [`mcp.types` moved](#mcptypes-moved-to-the-mcp-types-package) |
 | `McpError` renamed to `MCPError` | `ImportError: cannot import name 'McpError' from 'mcp'` | [`McpError` renamed](#mcperror-renamed-to-mcperror) |
 | Resource URIs are `str`, not `AnyUrl` | `AttributeError: 'str' object has no attribute 'host'` | [URI type](#resource-uri-type-changed-from-anyurl-to-str) |
 | `streamablehttp_client` removed | `ImportError: cannot import name 'streamablehttp_client'` | [`streamablehttp_client`](#streamablehttp_client-removed) |
@@ -172,8 +172,16 @@ The protocol wire types now live in a standalone distribution, `mcp-types`, impo
 `mcp_types`. Its only runtime dependencies are `pydantic` and `typing-extensions`, so code
 that just needs to (de)serialize MCP traffic can install it without the full SDK. The `mcp` package depends on `mcp-types` and
 continues to re-export the type names at the top level, so `from mcp import Tool` is
-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).
+unchanged. `mcp.shared.version` was removed. The package's API reference is at
+[`mcp_types`](api/mcp_types/index.md).
+
+`import mcp.types` still works in v2, as a compatibility shim that mirrors `mcp_types` and
+emits an `MCPDeprecationWarning` on first import; it will be removed in v3, so switch to
+`mcp_types` now. The shim only restores the import: the field renames below still apply, so
+code that imports through it can go on to fail on camelCase attribute access. The 23 names
+that no longer exist (listed under
+[Removed type aliases and classes](#removed-type-aliases-and-classes)) raise an
+`ImportError` from the shim that names their replacement.
 
 **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

pyproject.toml

@@ -217,6 +217,8 @@ max-complexity = 24 # Default is 10
 
 [tool.ruff.lint.per-file-ignores]
 "__init__.py" = ["F401"]
+# Deprecated compat shim that mirrors the whole mcp_types namespace by design.
+"src/mcp/types.py" = ["F403"]
 # 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"]
 "tests/server/mcpserver/test_func_metadata.py" = ["E501"]

scripts/docs/gen_ref_pages.py

@@ -30,6 +30,10 @@
 # it from `src/` would emit the unimportable `mcp-types.mcp_types.*`.
 PACKAGES = (ROOT / "src" / "mcp", ROOT / "src" / "mcp-types" / "mcp_types")
 
+# Deprecated compatibility shims: they mirror another module's namespace and
+# are documented in the migration guide, so they earn no API page of their own.
+EXCLUDED = frozenset({"mcp.types"})
+
 _KIND_SECTIONS = {
     griffe.Kind.MODULE: "Modules",
     griffe.Kind.CLASS: "Classes",
@@ -185,6 +189,8 @@ def generate() -> list[NavItem]:
                 continue
 
             ident = ".".join(parts)
+            if ident in EXCLUDED:
+                continue
             documented.add(ident)
             stubs[API_DIR / doc_path] = _stub(parts[-1], f"::: {ident}")
             pages[ident] = API_DIR / doc_path

src/mcp/types.py

@@ -0,0 +1,64 @@
+"""Deprecated: the protocol types moved to the standalone `mcp_types` package.
+
+`import mcp.types` still works in v2 as a compatibility shim, but it emits an
+`MCPDeprecationWarning` and will be removed in v3. Import from `mcp_types` instead:
+
+    from mcp_types import Tool, TextContent
+
+Field names also changed from camelCase to snake_case (`tool.input_schema`, not
+`tool.inputSchema`), so an import that succeeds through this shim can still fail
+later on attribute access. See the migration guide, "Types and wire format".
+"""
+
+# A wildcard mirror of the mcp_types namespace is the whole point of this shim.
+# pyright: reportWildcardImportFromLibrary=false
+
+import warnings
+
+from mcp_types import *
+from mcp_types import __all__ as __all__
+
+from mcp.shared.exceptions import MCPDeprecationWarning
+
+warnings.warn(
+    "mcp.types is deprecated; import from mcp_types. Fields are now snake_case; see the migration guide.",
+    MCPDeprecationWarning,
+    stacklevel=2,
+)
+
+# Names v1's mcp.types exposed that no longer exist. A bare "cannot import name"
+# leaves people grepping; naming the replacement finishes the migration step.
+_REMOVED = {
+    "Content": "use ContentBlock",
+    "ResourceReference": "use ResourceTemplateReference",
+    "Cursor": "use str",
+    "AnyFunction": "use Callable[..., Any]",
+    "MethodT": "it was an internal TypeVar, not public API",
+    "RequestParamsT": "it was an internal TypeVar, not public API",
+    "NotificationParamsT": "it was an internal TypeVar, not public API",
+    "ClientRequestType": "the union is now the bare name ClientRequest",
+    "ClientNotificationType": "the union is now the bare name ClientNotification",
+    "ClientResultType": "the union is now the bare name ClientResult",
+    "ServerRequestType": "the union is now the bare name ServerRequest",
+    "ServerNotificationType": "the union is now the bare name ServerNotification",
+    "ServerResultType": "the union is now the bare name ServerResult",
+    "TaskExecutionMode": "use the string literals directly",
+    "TASK_FORBIDDEN": "use the string literal 'forbidden'",
+    "TASK_OPTIONAL": "use the string literal 'optional'",
+    "TASK_REQUIRED": "use the string literal 'required'",
+    "TASK_STATUS_CANCELLED": "use the string literal 'cancelled'; TaskStatus remains",
+    "TASK_STATUS_COMPLETED": "use the string literal 'completed'; TaskStatus remains",
+    "TASK_STATUS_FAILED": "use the string literal 'failed'; TaskStatus remains",
+    "TASK_STATUS_INPUT_REQUIRED": "use the string literal 'input_required'; TaskStatus remains",
+    "TASK_STATUS_WORKING": "use the string literal 'working'; TaskStatus remains",
+}
+
+
+def __getattr__(name: str) -> object:
+    if (hint := _REMOVED.get(name)) is not None:
+        # ImportError, not AttributeError: `from mcp.types import X` swallows an
+        # AttributeError raised here and reports a generic "cannot import name",
+        # discarding the hint; an ImportError propagates through both the
+        # from-import and plain attribute-access paths with the message intact.
+        raise ImportError(f"mcp.types.{name} was removed in v2; {hint}. See the migration guide.")
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

tests/test_types.py

@@ -1,5 +1,9 @@
+import importlib
+import sys
+from types import ModuleType
 from typing import Any
 
+import mcp_types
 import pytest
 from inline_snapshot import snapshot
 from mcp_types import (
@@ -38,6 +42,9 @@
 )
 from pydantic import ValidationError
 
+import mcp
+from mcp import MCPDeprecationWarning
+
 
 @pytest.mark.anyio
 async def test_jsonrpc_request():
@@ -445,3 +452,44 @@ def test_input_required_result_requires_at_least_one_of_input_requests_or_reques
     with pytest.raises(ValidationError):
         InputRequiredResult(input_requests={})
     assert InputRequiredResult(request_state="s").input_requests is None
+
+
+def _import_deprecated_mcp_types_shim() -> ModuleType:
+    """Re-import the `mcp.types` compatibility shim so its import-time warning fires again."""
+    sys.modules.pop("mcp.types", None)
+    with pytest.warns(MCPDeprecationWarning) as record:
+        module = importlib.import_module("mcp.types")
+    assert str(record[0].message) == snapshot(
+        "mcp.types is deprecated; import from mcp_types. Fields are now snake_case; see the migration guide."
+    )
+    return module
+
+
+def test_deprecated_mcp_types_import_warns_and_mirrors_mcp_types():
+    """SDK-defined: the v1 `mcp.types` module is a warning shim that mirrors `mcp_types` exactly."""
+    module = _import_deprecated_mcp_types_shim()
+    assert module.__all__ == mcp_types.__all__
+    assert module.Tool is mcp_types.Tool
+    # Importing the submodule binds it on the package, so v1's `from mcp import types`
+    # idiom resolves to the same shim module.
+    assert getattr(mcp, "types") is module
+
+
+def test_deprecated_mcp_types_names_the_replacement_for_a_name_removed_in_v2():
+    """SDK-defined: a v1 name that no longer exists raises an error naming its v2 replacement."""
+    module = _import_deprecated_mcp_types_shim()
+    # ImportError rather than AttributeError so `from mcp.types import Content` keeps this
+    # message: the from-import path replaces an AttributeError with a generic one.
+    with pytest.raises(ImportError) as exc_info:
+        getattr(module, "Content")
+    assert str(exc_info.value) == snapshot(
+        "mcp.types.Content was removed in v2; use ContentBlock. See the migration guide."
+    )
+
+
+def test_deprecated_mcp_types_unknown_attribute_raises_attribute_error():
+    """SDK-defined: an unknown attribute is a normal AttributeError, so `hasattr` still works."""
+    module = _import_deprecated_mcp_types_shim()
+    with pytest.raises(AttributeError):
+        getattr(module, "not_a_protocol_type")
+    assert not hasattr(module, "not_a_protocol_type")