Resolve the mcp package's exports lazily (PEP 562)

`import mcp` used to import the protocol types plus the entire client and
server stacks (in-memory transport, lowlevel server, HTTP transports, otel,
auth) just to bind the names in `mcp.__all__`.

Each export is now resolved from its home module by a module-level
`__getattr__` on first access and cached in the package namespace; the
old eager import block is mirrored name-for-name under `TYPE_CHECKING`
so type checkers and the docs generator see the same bindings.
`__all__`, `dir(mcp)`, `from mcp import *`, object identity and the
`mcp.types` submodule binding are unchanged.

A bare `import mcp` no longer loads pydantic, mcp_types or any mcp
submodule; each entry point pays only for what it uses.

Author: maxisbey

src/mcp/__init__.py

@@ -1,75 +1,84 @@
-from mcp_types import (
-    CallToolRequest,
-    ClientCapabilities,
-    ClientNotification,
-    ClientRequest,
-    ClientResult,
-    CompleteRequest,
-    CreateMessageRequest,
-    CreateMessageResult,
-    CreateMessageResultWithTools,
-    ErrorData,
-    GetPromptRequest,
-    GetPromptResult,
-    Implementation,
-    IncludeContext,
-    InitializedNotification,
-    InitializeRequest,
-    InitializeResult,
-    JSONRPCError,
-    JSONRPCRequest,
-    JSONRPCResponse,
-    ListPromptsRequest,
-    ListPromptsResult,
-    ListResourcesRequest,
-    ListResourcesResult,
-    ListToolsResult,
-    LoggingLevel,
-    LoggingMessageNotification,
-    Notification,
-    PingRequest,
-    ProgressNotification,
-    PromptsCapability,
-    ReadResourceRequest,
-    ReadResourceResult,
-    Resource,
-    ResourcesCapability,
-    ResourceUpdatedNotification,
-    RootsCapability,
-    SamplingCapability,
-    SamplingContent,
-    SamplingContextCapability,
-    SamplingMessage,
-    SamplingMessageContentBlock,
-    SamplingToolsCapability,
-    ServerCapabilities,
-    ServerNotification,
-    ServerRequest,
-    ServerResult,
-    SetLevelRequest,
-    StopReason,
-    SubscribeRequest,
-    Tool,
-    ToolChoice,
-    ToolResultContent,
-    ToolsCapability,
-    ToolUseContent,
-    UnsubscribeRequest,
-)
-from mcp_types import Role as SamplingRole
+from importlib import import_module
+from typing import TYPE_CHECKING
+
+# Every name below is resolved LAZILY on first access via the module
+# `__getattr__` at the bottom of this file (PEP 562), so a bare `import mcp` no
+# longer imports the protocol types nor the client and server stacks. Type
+# checkers still see the real bindings through these `TYPE_CHECKING` imports,
+# which mirror the runtime lazy map name for name.
+if TYPE_CHECKING:
+    from mcp_types import (
+        CallToolRequest,
+        ClientCapabilities,
+        ClientNotification,
+        ClientRequest,
+        ClientResult,
+        CompleteRequest,
+        CreateMessageRequest,
+        CreateMessageResult,
+        CreateMessageResultWithTools,
+        ErrorData,
+        GetPromptRequest,
+        GetPromptResult,
+        Implementation,
+        IncludeContext,
+        InitializedNotification,
+        InitializeRequest,
+        InitializeResult,
+        JSONRPCError,
+        JSONRPCRequest,
+        JSONRPCResponse,
+        ListPromptsRequest,
+        ListPromptsResult,
+        ListResourcesRequest,
+        ListResourcesResult,
+        ListToolsResult,
+        LoggingLevel,
+        LoggingMessageNotification,
+        Notification,
+        PingRequest,
+        ProgressNotification,
+        PromptsCapability,
+        ReadResourceRequest,
+        ReadResourceResult,
+        Resource,
+        ResourcesCapability,
+        ResourceUpdatedNotification,
+        RootsCapability,
+        SamplingCapability,
+        SamplingContent,
+        SamplingContextCapability,
+        SamplingMessage,
+        SamplingMessageContentBlock,
+        SamplingToolsCapability,
+        ServerCapabilities,
+        ServerNotification,
+        ServerRequest,
+        ServerResult,
+        SetLevelRequest,
+        StopReason,
+        SubscribeRequest,
+        Tool,
+        ToolChoice,
+        ToolResultContent,
+        ToolsCapability,
+        ToolUseContent,
+        UnsubscribeRequest,
+    )
+    from mcp_types import Role as SamplingRole
 
-# Bind the `mcp.types` submodule on the package, as v1's `from .types import
-# ...` did, so `import mcp` followed by `mcp.types.Tool` keeps working.
-from . import types as types
-from .client._input_required import InputRequiredRoundsExceededError
-from .client.client import Client
-from .client.session import ClientSession
-from .client.session_group import ClientSessionGroup
-from .client.stdio import StdioServerParameters, stdio_client
-from .server.session import ServerSession
-from .server.stdio import stdio_server
-from .shared.exceptions import MCPDeprecationWarning, MCPError, UrlElicitationRequiredError
-from .shared.uri_template import InvalidUriTemplate, UriTemplate
+    # Bind the `mcp.types` submodule on the package, as v1's `from .types import
+    # ...` did, so `import mcp` followed by `mcp.types.Tool` keeps working.
+    from . import types as types
+    from .client._input_required import InputRequiredRoundsExceededError
+    from .client.client import Client
+    from .client.session import ClientSession
+    from .client.session_group import ClientSessionGroup
+    from .client.stdio import StdioServerParameters, stdio_client
+    from .server.session import ServerSession
+    from .server.stdio import stdio_server
+    from .shared.exceptions import MCPDeprecationWarning, MCPError, UrlElicitationRequiredError
+    from .shared.uri_template import InvalidUriTemplate, UriTemplate
 
 __all__ = [
     "CallToolRequest",
@@ -143,3 +152,135 @@
     "stdio_client",
     "stdio_server",
 ]
+
+# ---------------------------------------------------------------------------
+# Lazy attributes (PEP 562).
+#
+# `import mcp` used to pull in the protocol types (`mcp_types`, ~500 pydantic
+# models) plus the entire client and server stacks (in-memory transport ->
+# lowlevel server -> transports/otel/auth) only to bind the names above.
+# Every name is still here - `from mcp import Client`, `mcp.Tool`,
+# `from mcp import *`, `dir(mcp)` all behave exactly as before and resolve to the
+# very same objects - but each is imported from its home module on first access
+# and then cached in this namespace, so `import mcp` alone is nearly free and
+# each entry point pays only for what it actually uses.
+# ---------------------------------------------------------------------------
+
+_MCP_TYPES_NAMES = (
+    "CallToolRequest",
+    "ClientCapabilities",
+    "ClientNotification",
+    "ClientRequest",
+    "ClientResult",
+    "CompleteRequest",
+    "CreateMessageRequest",
+    "CreateMessageResult",
+    "CreateMessageResultWithTools",
+    "ErrorData",
+    "GetPromptRequest",
+    "GetPromptResult",
+    "Implementation",
+    "IncludeContext",
+    "InitializedNotification",
+    "InitializeRequest",
+    "InitializeResult",
+    "JSONRPCError",
+    "JSONRPCRequest",
+    "JSONRPCResponse",
+    "ListPromptsRequest",
+    "ListPromptsResult",
+    "ListResourcesRequest",
+    "ListResourcesResult",
+    "ListToolsResult",
+    "LoggingLevel",
+    "LoggingMessageNotification",
+    "Notification",
+    "PingRequest",
+    "ProgressNotification",
+    "PromptsCapability",
+    "ReadResourceRequest",
+    "ReadResourceResult",
+    "Resource",
+    "ResourcesCapability",
+    "ResourceUpdatedNotification",
+    "RootsCapability",
+    "SamplingCapability",
+    "SamplingContent",
+    "SamplingContextCapability",
+    "SamplingMessage",
+    "SamplingMessageContentBlock",
+    "SamplingToolsCapability",
+    "ServerCapabilities",
+    "ServerNotification",
+    "ServerRequest",
+    "ServerResult",
+    "SetLevelRequest",
+    "StopReason",
+    "SubscribeRequest",
+    "Tool",
+    "ToolChoice",
+    "ToolResultContent",
+    "ToolsCapability",
+    "ToolUseContent",
+    "UnsubscribeRequest",
+)
+
+# name -> (home module, attribute in it); mirrors the TYPE_CHECKING imports
+# above name for name. (No module-level annotations here: on 3.14+ they would
+# add `__annotate__`/`__conditional_annotations__` to the namespace and show up
+# in `dir(mcp)`.)
+_LAZY_ATTRS = {
+    **{name: ("mcp_types", name) for name in _MCP_TYPES_NAMES},
+    "SamplingRole": ("mcp_types", "Role"),
+    "InputRequiredRoundsExceededError": ("mcp.client._input_required", "InputRequiredRoundsExceededError"),
+    "Client": ("mcp.client.client", "Client"),
+    "ClientSession": ("mcp.client.session", "ClientSession"),
+    "ClientSessionGroup": ("mcp.client.session_group", "ClientSessionGroup"),
+    "StdioServerParameters": ("mcp.client.stdio", "StdioServerParameters"),
+    "stdio_client": ("mcp.client.stdio", "stdio_client"),
+    "ServerSession": ("mcp.server.session", "ServerSession"),
+    "stdio_server": ("mcp.server.stdio", "stdio_server"),
+    "MCPDeprecationWarning": ("mcp.shared.exceptions", "MCPDeprecationWarning"),
+    "MCPError": ("mcp.shared.exceptions", "MCPError"),
+    "UrlElicitationRequiredError": ("mcp.shared.exceptions", "UrlElicitationRequiredError"),
+    "InvalidUriTemplate": ("mcp.shared.uri_template", "InvalidUriTemplate"),
+    "UriTemplate": ("mcp.shared.uri_template", "UriTemplate"),
+}
+
+# Submodules a bare `import mcp` used to bind on the package as a side effect
+# of the eager imports (`mcp.types` is documented: v1's `mcp.types.Tool` idiom;
+# `client`/`server`/`shared`/`os` were merely incidental). Each is imported on
+# first touch; the import system then binds it here, so it is cached as well.
+_LAZY_SUBMODULES = frozenset({"types", "client", "os", "server", "shared"})
+
+# Names the lazy machinery itself adds to this namespace; kept out of
+# `dir(mcp)` so it reports exactly what it did when the imports were eager.
+_LAZY_MACHINERY = frozenset(
+    {
+        "TYPE_CHECKING",
+        "import_module",
+        "_LAZY_ATTRS",
+        "_LAZY_MACHINERY",
+        "_LAZY_SUBMODULES",
+        "_MCP_TYPES_NAMES",
+        "__getattr__",
+        "__dir__",
+    }
+)
+
+
+def __getattr__(name: str) -> object:
+    lazy = _LAZY_ATTRS.get(name)
+    if lazy is not None:
+        module_name, attr = lazy
+        value = getattr(import_module(module_name), attr)
+        # Cache on the module: every later access is a plain namespace lookup.
+        globals()[name] = value
+        return value
+    if name in _LAZY_SUBMODULES:
+        return import_module(f"{__name__}.{name}")
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__() -> list[str]:
+    return sorted((globals().keys() - _LAZY_MACHINERY) | _LAZY_ATTRS.keys() | _LAZY_SUBMODULES)

tests/test_init.py

@@ -0,0 +1,51 @@
+"""The `mcp` package namespace: lazy exports (PEP 562) that stay identical to the eager originals."""
+
+import subprocess
+import sys
+
+import pytest
+from inline_snapshot import snapshot
+
+import mcp
+import mcp.shared.exceptions
+
+
+def test_exported_name_is_the_home_module_object_and_is_cached_on_the_package():
+    """SDK-defined: `mcp.MCPError` is `mcp.shared.exceptions.MCPError`, cached after first access."""
+    assert mcp.MCPError is mcp.shared.exceptions.MCPError
+    assert vars(mcp)["MCPError"] is mcp.shared.exceptions.MCPError
+
+
+def test_dir_lists_every_export_and_the_bound_submodules():
+    """SDK-defined: `dir(mcp)` reports all of `__all__` plus the submodules a bare import binds."""
+    listing = set(dir(mcp))
+    assert set(mcp.__all__) <= listing
+    assert {"client", "os", "server", "shared", "types"} <= listing
+
+
+def test_unknown_attribute_raises_attribute_error():
+    """SDK-defined: a name that is neither an export nor a submodule raises AttributeError."""
+    with pytest.raises(AttributeError):
+        getattr(mcp, "no_such_name")
+
+
+def test_bare_import_mcp_does_not_load_the_types_or_client_or_server_stacks():
+    """SDK-defined: `import mcp` is lazy - the protocol types and the client/server stacks
+    load on first use, not on package import.
+
+    A fresh interpreter is required to observe `sys.modules` after a bare import: this
+    test process imported all of them long ago.
+    """
+    probe = (
+        "import mcp, sys\n"
+        "print(sorted(m for m in sys.modules if m.split('.')[0] in {'mcp', 'mcp_types', 'pydantic'}))\n"
+    )
+    result = subprocess.run(
+        [sys.executable, "-c", probe],
+        capture_output=True,
+        text=True,
+        check=False,
+        timeout=20,
+    )
+    assert result.returncode == 0, result.stderr
+    assert result.stdout == snapshot("['mcp']\n")