Max Isbey
ec5b2258c9
Every import path now pays only for what it uses, with no public API added or removed: - The protocol models (mcp.types / mcp_types, incl. the JSON-RPC envelopes and the generated per-version wire packages) build their pydantic validators on first use instead of at import (defer_build), through one shared private base class. First-use builds are serialised behind a single process-wide lock, since released pydantic does not make concurrent first use of a deferred model thread-safe; this also fixes a pre-existing concurrent-first-use failure that reproduces on main. - `import mcp` binds the client/server names lazily on first attribute access (PEP 562) instead of importing both stacks eagerly, and the client no longer imports the server, so client entry points stop loading the server, the web stack, httpx2 and cryptography. - The web application stack (starlette's app machinery, sse_starlette, uvicorn) loads with the app builders that use it, and each protocol version's wire package loads on the first message parsed for that version rather than both loading at import. On the fresh-interpreter harness `import mcp` is ~0.4x of v1 (main is ~1.6x), the client entry points ~0.6x of v1, `import mcp.server.mcpserver` ~0.7x, and time-to-ready / stdio cold start land at parity with v1. RSS after `import mcp` is 19 MiB (v1 43.5, main 57). Steady-state per-call latency is unchanged. Observable-but-incidental differences (removed incidental namespace bindings, deeper submodules no longer imported as a side effect of a bare `import mcp`, get_type_hints needing localns= for a documented set of callables, pre-first-use introspection) are catalogued in docs/migration.md; ratchet tests pin the import footprints and the concurrent-first-use safety.
210 lines
7.1 KiB
YAML
210 lines
7.1 KiB
YAML
site_name: MCP Python SDK
|
|
site_description: The official Python SDK for the Model Context Protocol
|
|
|
|
repo_name: modelcontextprotocol/python-sdk
|
|
repo_url: https://github.com/modelcontextprotocol/python-sdk
|
|
edit_uri: edit/main/docs/
|
|
site_url: https://py.sdk.modelcontextprotocol.io/
|
|
|
|
# TODO(Marcelo): Add Anthropic copyright?
|
|
# copyright: © Model Context Protocol 2025 to present
|
|
|
|
# The "API Reference" entry is a placeholder: `scripts/docs/gen_ref_pages.py`
|
|
# generates the `docs/api/` tree and `scripts/docs/build_config.py` splices the
|
|
# real nested nav in before the build. See `scripts/docs/build.sh`.
|
|
nav:
|
|
- MCP Python SDK: index.md
|
|
- "What's new in v2": whats-new.md
|
|
- Get started:
|
|
- get-started/index.md
|
|
- Installation: get-started/installation.md
|
|
- First steps: get-started/first-steps.md
|
|
- Connect to a real host: get-started/real-host.md
|
|
- Testing: get-started/testing.md
|
|
- Servers:
|
|
- servers/index.md
|
|
- Tools: servers/tools.md
|
|
- Structured Output: servers/structured-output.md
|
|
- Resources: servers/resources.md
|
|
- URI templates: servers/uri-templates.md
|
|
- Prompts: servers/prompts.md
|
|
- Completions: servers/completions.md
|
|
- "Images, audio & icons": servers/media.md
|
|
- Handling errors: servers/handling-errors.md
|
|
- Inside your handler:
|
|
- handlers/index.md
|
|
- The Context: handlers/context.md
|
|
- Dependencies: handlers/dependencies.md
|
|
- Lifespan: handlers/lifespan.md
|
|
- Elicitation: handlers/elicitation.md
|
|
- Multi-round-trip requests: handlers/multi-round-trip.md
|
|
- Sampling and roots: handlers/sampling-and-roots.md
|
|
- Progress: handlers/progress.md
|
|
- Logging: handlers/logging.md
|
|
- Subscriptions: handlers/subscriptions.md
|
|
- Running your server:
|
|
- run/index.md
|
|
- Add to an existing app: run/asgi.md
|
|
- Deploy & scale: run/deploy.md
|
|
- Authorization: run/authorization.md
|
|
- OpenTelemetry: run/opentelemetry.md
|
|
- Serving legacy clients: run/legacy-clients.md
|
|
- Clients:
|
|
- client/index.md
|
|
- Callbacks: client/callbacks.md
|
|
- Transports: client/transports.md
|
|
- OAuth: client/oauth-clients.md
|
|
- Identity assertion: client/identity-assertion.md
|
|
- Multiple servers: client/session-groups.md
|
|
- Subscriptions: client/subscriptions.md
|
|
- Caching: client/caching.md
|
|
- Protocol versions: protocol-versions.md
|
|
- Deprecated features: deprecated.md
|
|
- Advanced:
|
|
- advanced/index.md
|
|
- The low-level Server: advanced/low-level-server.md
|
|
- Pagination: advanced/pagination.md
|
|
- Middleware: advanced/middleware.md
|
|
- Extensions: advanced/extensions.md
|
|
- MCP Apps: advanced/apps.md
|
|
- Startup cost: advanced/startup.md
|
|
- Troubleshooting: troubleshooting.md
|
|
- Migration Guide: migration.md
|
|
- API Reference: api/
|
|
|
|
theme:
|
|
name: "material"
|
|
custom_dir: docs/.overrides
|
|
font:
|
|
text: Inter
|
|
code: JetBrains Mono
|
|
icon:
|
|
logo: mcp
|
|
favicon: favicon.svg
|
|
palette:
|
|
- media: "(prefers-color-scheme)"
|
|
scheme: default
|
|
primary: black
|
|
accent: black
|
|
toggle:
|
|
icon: material/lightbulb
|
|
name: "Switch to light mode"
|
|
- media: "(prefers-color-scheme: light)"
|
|
scheme: default
|
|
primary: black
|
|
accent: black
|
|
toggle:
|
|
icon: material/lightbulb-outline
|
|
name: "Switch to dark mode"
|
|
- media: "(prefers-color-scheme: dark)"
|
|
scheme: slate
|
|
primary: black
|
|
accent: white
|
|
toggle:
|
|
icon: material/lightbulb-auto-outline
|
|
name: "Switch to system preference"
|
|
features:
|
|
- search.suggest
|
|
- search.highlight
|
|
- content.tabs.link
|
|
- content.code.annotate
|
|
- content.code.copy
|
|
- content.code.select
|
|
- navigation.footer
|
|
- navigation.indexes
|
|
- navigation.instant
|
|
- navigation.instant.prefetch
|
|
- navigation.instant.progress
|
|
- navigation.path
|
|
- navigation.prune
|
|
- navigation.sections
|
|
- navigation.top
|
|
- navigation.tracking
|
|
- toc.follow
|
|
|
|
extra_css:
|
|
- extra.css
|
|
|
|
markdown_extensions:
|
|
- tables
|
|
- abbr
|
|
- admonition
|
|
- attr_list
|
|
- def_list
|
|
- footnotes
|
|
- md_in_html
|
|
- pymdownx.betterem
|
|
- pymdownx.details
|
|
- pymdownx.caret
|
|
- pymdownx.critic
|
|
- pymdownx.mark
|
|
# Code examples live as complete, importable, tested files under `docs_src/`
|
|
# and are included into pages with `--8<-- "docs_src/<chapter>/tutorialNNN.py"`
|
|
# (resolved against the repo root, which is the build's working directory).
|
|
# `check_paths: true` turns a renamed/deleted example into a build failure
|
|
# instead of a silently empty code block.
|
|
- pymdownx.snippets:
|
|
base_path: [.]
|
|
check_paths: true
|
|
- pymdownx.tilde
|
|
- pymdownx.inlinehilite
|
|
- pymdownx.highlight:
|
|
pygments_lang_class: true
|
|
- pymdownx.superfences:
|
|
custom_fences:
|
|
- name: mermaid
|
|
class: mermaid
|
|
format: pymdownx.superfences.fence_code_format
|
|
# Zensical re-implements the emoji extension; the generator/index functions
|
|
# live under `zensical.extensions.emoji`, not `material.extensions.emoji`.
|
|
- pymdownx.emoji:
|
|
emoji_index: zensical.extensions.emoji.twemoji
|
|
emoji_generator: zensical.extensions.emoji.to_svg
|
|
options:
|
|
custom_icons:
|
|
- docs/.overrides/.icons
|
|
- pymdownx.tabbed:
|
|
alternate_style: true
|
|
- pymdownx.tasklist:
|
|
custom_checkbox: true
|
|
- sane_lists # this means you can start a list from any number
|
|
|
|
# Zensical natively watches these beyond docs/: page content is assembled
|
|
# from src/ (mkdocstrings) and docs_src/ (snippet includes), so serve
|
|
# live-reload must react to both.
|
|
watch:
|
|
- src
|
|
- docs_src
|
|
|
|
# Zensical natively re-implements `search`, `glightbox` and `mkdocstrings`; it
|
|
# does not run arbitrary MkDocs plugins or hooks. The former `gen-files`,
|
|
# `literate-nav` and `llms_txt` hook are handled by the standalone scripts
|
|
# under `scripts/docs/` (see scripts/docs/build.sh). The `social` plugin was
|
|
# dropped: Zensical has no social-card support, and the cards were gated on
|
|
# ENABLE_SOCIAL_CARDS, which no workflow ever set.
|
|
plugins:
|
|
- search
|
|
- glightbox
|
|
- mkdocstrings:
|
|
handlers:
|
|
python:
|
|
paths: [src, src/mcp-types]
|
|
# Zensical renders pages in undefined (filesystem-dependent) order
|
|
# against one shared griffe collection, so a cross-package re-export
|
|
# (`mcp` -> `mcp_types`) resolves only if its target package happens
|
|
# to have been collected first. Chasing exported aliases into their
|
|
# packages at load time makes resolution order-independent;
|
|
# scripts/docs/check_render_order.py enforces that property.
|
|
load_external_modules: true
|
|
options:
|
|
relative_crossrefs: true
|
|
members_order: source
|
|
separate_signature: true
|
|
show_signature_annotations: true
|
|
signature_crossrefs: true
|
|
group_by_category: false
|
|
inventories:
|
|
- url: https://docs.python.org/3/objects.inv
|
|
- url: https://docs.pydantic.dev/latest/objects.inv
|
|
- url: https://typing-extensions.readthedocs.io/en/latest/objects.inv
|