Skip to content

[experimental - do not merge] Cut startup cost: lazy exports, pay-for-what-you-use imports, deferred model builds #3220

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
maxisbey wants to merge 32 commits into
base: main
Choose a base branch
from
+3,759 −1,050
Draft

[experimental - do not merge] Cut startup cost: lazy exports, pay-for-what-you-use imports, deferred model builds #3220

Changes from 1 commit
Commits
Show all changes
32 commits
Select commit Hold shift + click to select a range
622aed5
Resolve the mcp package's exports lazily (PEP 562)
maxisbey Jul 29, 2026
2128b57
Resolve submodules of mcp.client, mcp.server, mcp.shared and mcp.os o…
maxisbey Jul 29, 2026
1c1b7f8
Stop mcp.client from importing the server stack
maxisbey Jul 29, 2026
1e00f42
Load httpx2 with the HTTP transports only
maxisbey Jul 29, 2026
5b25303
Keep typing.get_type_hints(Client) resolvable at runtime
maxisbey Jul 29, 2026
fcaf297
Make server-side imports pay-for-what-you-use
maxisbey Jul 29, 2026
3ac881f
Test HttpResource.read() instead of excluding it from coverage
maxisbey Jul 29, 2026
0237ed9
Load per-version wire packages lazily from the methods surface maps
maxisbey Jul 29, 2026
2a7fb0c
Keep PrimitiveSchemaDefinition reachable on mcp.server.elicitation
maxisbey Jul 29, 2026
ff6c36e
Add an import-cost ratchet for the SDK's entry points
maxisbey Jul 29, 2026
2a13e6d
Keep the Client type-hints test green on Python 3.10
maxisbey Jul 29, 2026
1f3fbc7
Use one lazy-attribute helper for the packages, invisible to type che…
maxisbey Jul 29, 2026
cdc78fc
Keep the public server signatures resolvable by typing.get_type_hints
maxisbey Jul 29, 2026
9ef39b6
Load the OAuth provider stack and cryptography with their first user,…
maxisbey Jul 29, 2026
695b1ab
Keep the wire packages statically discoverable to bundlers
maxisbey Jul 29, 2026
b8bc17d
Defer building the generated wire models and emit them in dependency …
maxisbey Jul 29, 2026
08f4385
Defer building the monolith protocol models and routing adapters
maxisbey Jul 29, 2026
45bb6c9
Defer building the SDK's own eager pydantic models and adapters
maxisbey Jul 29, 2026
1facb57
Document the import-cost contract and the deferred-work model
maxisbey Jul 29, 2026
d515c85
Cover the deferred-signature edge cases: instance access and defer_bu…
maxisbey Jul 29, 2026
8c9f2a2
Serialize the deferred first build of the SDK's pydantic models
maxisbey Jul 29, 2026
33471c7
Add mcp.warm(): opt-in prewarming for the deferred validators
maxisbey Jul 29, 2026
7fae576
Document the deferred-work bills and correct the import-cost bullets
maxisbey Jul 29, 2026
53a46e6
Construct DEFAULT_CLIENT_INFO without building the Implementation model
maxisbey Jul 29, 2026
986d3b9
Import the internal deferred_model decorator under a private name
maxisbey Jul 29, 2026
e02caca
Fail generation if a non-class statement sits between generated classes
maxisbey Jul 29, 2026
fc4f4e6
Cover the decorator's refusal paths and the runtime-only lazy-init br…
maxisbey Jul 29, 2026
b592f09
Generate a deferred model's JSON schema under the rebuild lock too
maxisbey Jul 29, 2026
6da7ba4
Spell warm()'s every-version flag as all_versions and return a frozen…
maxisbey Jul 29, 2026
008c74e
Document the prewarm recipe and the rebuild lock's terms
maxisbey Jul 29, 2026
cb7c68c
Resolve attribute chains through the four leaf sub-packages too
maxisbey Jul 29, 2026
2716d09
Pin the decorator's refusal messages and describe two wire-base tests
maxisbey Jul 29, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Prev Previous commit
Next Next commit
Construct DEFAULT_CLIENT_INFO without building the Implementation model 
The default Implementation instance was validated at import, which
force-built the deferred Implementation model on every client import
(~0.7 ms). The two literals are trusted, so model_construct produces an
equal instance (same dict, same fields set) without touching the
validator; the model now builds on the first real message instead.
  • Loading branch information
@maxisbey
maxisbey committed Jul 29, 2026
commit 53a46e6c1c5bd8c72dad4aa57e21e21644d8868d
4 changes: 3 additions & 1 deletion src/mcp/client/session.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,9 @@
# `attrs`/`referencing` tree) in at module scope costs every client that never validates.
from jsonschema.protocols import Validator

DEFAULT_CLIENT_INFO = types.Implementation(name="mcp", version="0.1.0")
# Trusted literal: `model_construct` skips validation so importing this module does not
# force-build the deferred `Implementation` model; equal to the validated instance.
DEFAULT_CLIENT_INFO = types.Implementation.model_construct(name="mcp", version="0.1.0")
DISCOVER_TIMEOUT_SECONDS = 10.0
_NOTIFICATION_QUEUE_SIZE: Final = 256

Expand Down