Keep typing.get_type_hints(Client) resolvable at runtime

Making the server stack a typing-only import in the client module left
the `Client.server` annotation naming `Server` / `MCPServer`, which
`typing.get_type_hints` can then no longer evaluate: string annotations
are evaluated against the module dict, so a module-level `__getattr__`
would not be consulted either.

Spell the annotation through the `mcp.server` namespace instead. Evaluating
the hints then walks the lazy `mcp` package, which imports `mcp.server` at
that moment only; `import mcp.client` stays free of the server stack and the
evaluated hint is the same union of classes as before. The package's
TYPE_CHECKING mirror now also lists the subpackages that its `__getattr__`
resolves on first access, so type checkers see the same chains.

Author: maxisbey

src/mcp/__init__.py

@@ -68,7 +68,14 @@
     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.
+    # ...` did, so `import mcp` followed by `mcp.types.Tool` keeps working. The
+    # other subpackages are mirrored too: at runtime `__getattr__` imports them
+    # on first attribute access (`_LAZY_SUBMODULES`), so `mcp.server.Server`
+    # style chains resolve, and type checkers must see the same members.
+    from . import client as client
+    from . import os as os
+    from . import server as server
+    from . import shared as shared
     from . import types as types
     from .client._input_required import InputRequiredRoundsExceededError
     from .client.client import Client

src/mcp/client/client.py

@@ -43,6 +43,7 @@
 from mcp_types.version import HANDSHAKE_PROTOCOL_VERSIONS, MODERN_PROTOCOL_VERSIONS
 from typing_extensions import TypeIs, deprecated
 
+import mcp
 from mcp.client._input_required import DEFAULT_INPUT_REQUIRED_MAX_ROUNDS, run_input_required_driver
 from mcp.client._probe import negotiate_auto
 from mcp.client._transport import Transport
@@ -321,7 +322,11 @@ async def main():
         ```
     """
 
-    server: Server[Any] | MCPServer | Transport | str
+    # Spelled through the `mcp.server` namespace (not the TYPE_CHECKING-only
+    # `Server`/`MCPServer` names above) so `typing.get_type_hints(Client)`
+    # still resolves at runtime: the lazy `mcp` package imports `mcp.server`
+    # only when the annotation is actually evaluated.
+    server: mcp.server.Server[Any] | mcp.server.MCPServer | Transport | str
     """The MCP server to connect to.
 
     If the server is a `Server` or `MCPServer` instance, it will be connected in-process.

tests/client/test_client.py

@@ -6,6 +6,7 @@
 import json
 import subprocess
 import sys
+import typing
 from collections.abc import AsyncIterator, Iterator
 from contextlib import asynccontextmanager, contextmanager
 from unittest.mock import patch
@@ -446,6 +447,16 @@ def test_client_entry_points_load_the_server_stack_and_http_transports_only_when
     assert after_url_client == ["httpx2"]
 
 
+def test_client_annotations_still_evaluate_at_runtime():
+    """SDK-defined: `typing.get_type_hints(Client)` resolves even though the server stack is
+    a typing-only import in the client module; the `server` annotation is qualified through
+    the lazy `mcp.server` namespace, which imports it only when the hints are evaluated."""
+    hints = typing.get_type_hints(Client)
+    server_targets = typing.get_args(hints["server"])
+    assert MCPServer in server_targets
+    assert str in server_targets
+
+
 async def test_client_uses_transport_directly(app: MCPServer):
     transport = InMemoryTransport(app)
     async with Client(transport, mode="legacy") as client: