Resolve submodules of mcp.client, mcp.server, mcp.shared and mcp.os on attribute access

Adds a small PEP 562 __getattr__ factory (mcp.shared._lazy_submodules) and
installs it on the four packages, so attribute chains that used to resolve only
because the top-level package imported everything eagerly - e.g.
import mcp; mcp.client.stdio.stdio_client - keep resolving now that the mcp
package is lazy: touching pkg.name imports the submodule pkg.name if it exists,
raising AttributeError otherwise and surfacing a submodule's own missing
dependency as its real ImportError.

Author: maxisbey

src/mcp/client/__init__.py

@@ -21,6 +21,7 @@
     advertise,
 )
 from mcp.client.session import ClientSession, IncomingMessage
+from mcp.shared._lazy_submodules import submodule_getattr as _submodule_getattr
 
 __all__ = [
     "CacheConfig",
@@ -42,3 +43,8 @@
     "UnexpectedClaimedResult",
     "advertise",
 ]
+
+# `mcp.client.<submodule>` (stdio, sse, session_group, auth, ...) resolves by
+# attribute access even before that submodule was imported: the lazy `mcp`
+# package no longer imports them all up front. See mcp.shared._lazy_submodules.
+__getattr__ = _submodule_getattr(__name__)

src/mcp/os/__init__.py

@@ -1 +1,7 @@
 """Platform-specific utilities for MCP."""
+
+from mcp.shared._lazy_submodules import submodule_getattr as _submodule_getattr
+
+# `mcp.os.posix` / `mcp.os.win32` resolve by attribute access even before they
+# were imported.
+__getattr__ = _submodule_getattr(__name__)

src/mcp/server/__init__.py

@@ -1,7 +1,14 @@
+from mcp.shared._lazy_submodules import submodule_getattr as _submodule_getattr
+
 from .caching import CacheHint
 from .context import ServerRequestContext
 from .lowlevel import NotificationOptions, Server
 from .mcpserver import MCPServer
 from .models import InitializationOptions
 
 __all__ = ["CacheHint", "Server", "ServerRequestContext", "MCPServer", "NotificationOptions", "InitializationOptions"]
+
+# `mcp.server.<submodule>` (stdio, session, streamable_http, auth, ...)
+# resolves by attribute access even before that submodule was imported:
+# the lazy `mcp` package no longer imports them all up front.
+__getattr__ = _submodule_getattr(__name__)

src/mcp/shared/__init__.py

@@ -0,0 +1,5 @@
+from mcp.shared._lazy_submodules import submodule_getattr as _submodule_getattr
+
+# `mcp.shared.<submodule>` (exceptions, memory, message, ...) resolves by
+# attribute access even before that submodule was imported.
+__getattr__ = _submodule_getattr(__name__)

src/mcp/shared/_lazy_submodules.py

@@ -0,0 +1,34 @@
+"""Lazy submodule access for packages (PEP 562 module `__getattr__` factory).
+
+A bare `import mcp` used to import most of the SDK eagerly, so attribute chains
+such as `mcp.client.stdio.stdio_client` resolved without ever importing the
+submodule explicitly. The `mcp` package is lazy now; a package that installs
+this `__getattr__` keeps such chains working - touching `pkg.<name>` imports the
+submodule `pkg.<name>` when there is one - without importing anything up front.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from importlib import import_module
+
+
+def submodule_getattr(package_name: str) -> Callable[[str], object]:
+    """Build a module `__getattr__` that imports `package_name.<attr>` on demand."""
+
+    def __getattr__(name: str) -> object:
+        if name.startswith("__"):
+            # Dunder lookups (`__test__`, `__path__`, ...) are protocol probes,
+            # never submodules; answer them without a filesystem search.
+            raise AttributeError(f"module {package_name!r} has no attribute {name!r}")
+        module_name = f"{package_name}.{name}"
+        try:
+            return import_module(module_name)
+        except ModuleNotFoundError as exc:
+            if exc.name != module_name:
+                # A submodule that exists but has a missing dependency of its
+                # own: surface the real ImportError, not a misleading AttributeError.
+                raise
+            raise AttributeError(f"module {package_name!r} has no attribute {name!r}") from None
+
+    return __getattr__

tests/shared/lazy_submodule_fixture/__init__.py

@@ -0,0 +1,5 @@
+"""A package that installs `submodule_getattr`, for tests/shared/test_lazy_submodules.py."""
+
+from mcp.shared._lazy_submodules import submodule_getattr
+
+__getattr__ = submodule_getattr(__name__)

tests/shared/lazy_submodule_fixture/broken.py

@@ -0,0 +1,5 @@
+"""A submodule whose own import fails on a missing dependency."""
+
+from importlib import import_module
+
+MARKER = import_module("definitely_not_installed_dependency_xyz")

tests/shared/lazy_submodule_fixture/fine.py

@@ -0,0 +1,3 @@
+"""An importable submodule."""
+
+MARKER = "ok"

tests/shared/test_lazy_submodules.py

@@ -0,0 +1,53 @@
+"""`mcp.shared._lazy_submodules`: package attribute access imports the submodule of that name."""
+
+import subprocess
+import sys
+from types import ModuleType
+
+import pytest
+from inline_snapshot import snapshot
+
+import tests.shared.lazy_submodule_fixture as fixture_pkg
+
+
+def test_package_attribute_imports_the_submodule_of_that_name():
+    """SDK-defined: `pkg.<name>` imports `pkg.<name>` on first touch and binds it on the package."""
+    submodule = getattr(fixture_pkg, "fine")
+    assert isinstance(submodule, ModuleType)
+    assert submodule.MARKER == "ok"
+    assert submodule is sys.modules["tests.shared.lazy_submodule_fixture.fine"]
+    assert vars(fixture_pkg)["fine"] is submodule
+
+
+def test_missing_submodule_raises_attribute_error():
+    """SDK-defined: a name with no such submodule is a plain AttributeError."""
+    with pytest.raises(AttributeError):
+        getattr(fixture_pkg, "no_such_submodule")
+
+
+def test_dunder_probe_raises_attribute_error_without_a_submodule_search():
+    """SDK-defined: dunder names are protocol probes, never submodules."""
+    with pytest.raises(AttributeError):
+        getattr(fixture_pkg, "__no_such_dunder__")
+
+
+def test_submodule_with_a_missing_dependency_surfaces_the_real_import_error():
+    """SDK-defined: an existing submodule that fails to import raises its own error, not AttributeError."""
+    with pytest.raises(ModuleNotFoundError) as exc_info:
+        getattr(fixture_pkg, "broken")
+    assert exc_info.value.name == "definitely_not_installed_dependency_xyz"
+
+
+def test_bare_import_mcp_still_resolves_deep_submodule_chains():
+    """SDK-defined: after only `import mcp`, `mcp.client.stdio.stdio_client` etc. still resolve.
+
+    A fresh interpreter is required: this process already imported those modules.
+    """
+    probe = (
+        "import mcp\n"
+        "print([mcp.client.stdio.stdio_client.__name__, mcp.server.stdio.stdio_server.__name__,\n"
+        "       mcp.shared.memory.__name__, mcp.os.posix.__name__])\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("['stdio_client', 'stdio_server', 'mcp.shared.memory', 'mcp.os.posix']\n")