Moving the HTTP transport and auth imports under TYPE_CHECKING made
typing.get_type_hints() raise NameError on public methods it used to
resolve on: MCPServer.streamable_http_app / sse_app / run_sse_async /
run_streamable_http_async / session_manager and Server.streamable_http_app
/ session_manager (EventStore, TransportSecuritySettings,
StreamableHTTPSessionManager, AuthSettings, OAuthAuthorizationServerProvider,
TokenVerifier were typing-only names in real annotations).
Two of those types get web-framework-free homes so the server modules can
import them for real without loading starlette: the resumability contract
(EventStore, EventMessage, EventCallback, EventId, StreamId) moves to
mcp.server.event_store, and mcp.server.transport_security keeps only the
pydantic TransportSecuritySettings while its starlette middleware moves
beside the transports. Both old import paths keep working with the same
objects. The session manager and the OAuth annotations are spelled through
the lazy mcp.server namespace instead (the trick already used for
Client.server), so they evaluate on demand and MCPServer stops importing
the OAuth provider stack at module load. The starlette-owned annotations
of the app builders (Starlette, Route, Request/Response) stay typing-only;
get_type_hints on those methods needs starlette's names supplied by the
caller.
Three implementations of lazy module attributes had grown: the
hand-rolled __getattr__/__dir__ in mcp/__init__.py, the submodule
fallback factory used by the four package inits, and a one-name
__getattr__ in mcp.server.elicitation. They shared two problems.
An unconditional module-level __getattr__ is visible to type checkers,
so pyright typed every misspelled `mcp.<name>` (and `mcp.client.<name>`,
...) as `object` instead of reporting it. And the submodule fallback ran
a filesystem find_spec on every attribute miss and speculatively imported
whatever matched, so a name sweep (cloudpickle's whichmodule, hasattr
probes) could import real submodules as a side effect, while
dir(mcp.client) no longer listed submodules it would happily resolve.
mcp.shared._lazy.lazy_module_attrs now serves all of them: lazy exports
(a `(module, attr)` pair or a zero-argument loader, resolved once and
cached in the namespace) plus known submodules (an explicit set, or the
package's real submodules listed once on first need). A miss is a plain
AttributeError with no search and no import, and __dir__ reports the
exports and submodules. Every caller binds the pair under
`if not TYPE_CHECKING:`, so attribute typos are pyright errors again
while the TYPE_CHECKING mirrors keep the real names typed. The
mcp.server.auth package gets the same fallback so qualified annotations
such as `mcp.server.auth.provider.TokenVerifier` resolve on demand.
The elicitation gate's wire-schema type is resolved through the same
mechanism from a cached accessor, so validating rendered schemas no
longer re-executes the wire-package import on every call.
Its module-level import moved into the validation function that uses it, so
the attribute would otherwise disappear from the module namespace. Resolve it
on first access via a module-level __getattr__ (and keep it in dir()) so
existing references to mcp.server.elicitation.PrimitiveSchemaDefinition keep
working without reintroducing the import at module load.
The method body had been marked `# pragma: no cover` (widened further once
httpx2 moved into the method). Exercise it against an httpx2 MockTransport
instead, covering both the response body and the raise_for_status path, and
drop the pragma.
Max Isbey