modelcontextprotocol/python-sdk
Watch
1
0
Fork
You've already forked python-sdk
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Make the per-version wire packages private (mcp_types._v*) (#3191)

Browse source
This commit is contained in:
Max 2026-07-27 22:16:48 +01:00 • committed by GitHub
commit b9422f1c9b
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
13 changed files with 133 additions and 127 deletions
Download patch file Download diff file Expand all files Collapse all files

2
.github/workflows/shared.yml vendored
View file

@ -51,7 +51,7 @@ jobs:
- name: mcp-types installs and imports standalone - name: mcp-types installs and imports standalone
run: | run: |
uv run --isolated --no-project --with ./src/mcp-types python -c \ uv run --isolated --no-project --with ./src/mcp-types python -c \
"import mcp_types, mcp_types.jsonrpc, mcp_types.methods, mcp_types.version, mcp_types.v2025_11_25, mcp_types.v2026_07_28" "import mcp_types, mcp_types.jsonrpc, mcp_types.methods, mcp_types.version, mcp_types._v2025_11_25, mcp_types._v2026_07_28"
test: test:
name: test (${{ matrix.python-version }}, ${{ matrix.dep-resolution.name }}, ${{ matrix.os }}) name: test (${{ matrix.python-version }}, ${{ matrix.dep-resolution.name }}, ${{ matrix.os }})

5
docs/migration.md
View file

@ -175,6 +175,11 @@ continues to re-export the type names at the top level, so `from mcp import Tool
unchanged. Only the `mcp.types` submodule and `mcp.shared.version` were removed. The unchanged. Only the `mcp.types` submodule and `mcp.shared.version` were removed. The
package's API reference is at [`mcp_types`](api/mcp_types/index.md). package's API reference is at [`mcp_types`](api/mcp_types/index.md).
The supported import surface is `mcp_types`, `mcp_types.jsonrpc`, `mcp_types.methods`, and
`mcp_types.version`. Underscore-prefixed submodules (`mcp_types._types`, and the generated
per-protocol-version packages `mcp_types._v2025_11_25` / `mcp_types._v2026_07_28`) are internal
validators with unstable class names; don't import from them.
**Why:** keeping the wire types in their own package lets tooling and lightweight clients **Why:** keeping the wire types in their own package lets tooling and lightweight clients
depend on the protocol schema without pulling in `httpx2`, `starlette`, `uvicorn`, and the depend on the protocol schema without pulling in `httpx2`, `starlette`, `uvicorn`, and the
rest of the server/transport stack. rest of the server/transport stack.

2
pyproject.toml
View file

@ -218,7 +218,7 @@ max-complexity = 24 # Default is 10
[tool.ruff.lint.per-file-ignores] [tool.ruff.lint.per-file-ignores]
"__init__.py" = ["F401"] "__init__.py" = ["F401"]
# Generated by scripts/gen_surface_types.py: raw datamodel-codegen output (TID251 lifts the repo-wide RootModel ban for these generated validators). # Generated by scripts/gen_surface_types.py: raw datamodel-codegen output (TID251 lifts the repo-wide RootModel ban for these generated validators).
"src/mcp-types/mcp_types/v*/__init__.py" = ["D212", "E501", "I001", "TID251", "UP007", "UP037"] "src/mcp-types/mcp_types/_v*/__init__.py" = ["D212", "E501", "I001", "TID251", "UP007", "UP037"]
"tests/server/mcpserver/test_func_metadata.py" = ["E501"] "tests/server/mcpserver/test_func_metadata.py" = ["E501"]
"tests/shared/test_progress_notifications.py" = ["PLW0603"] "tests/shared/test_progress_notifications.py" = ["PLW0603"]

4
schema/README.md
View file

@ -3,8 +3,8 @@
JSON Schema files for each protocol version the SDK has a wire-shape surface JSON Schema files for each protocol version the SDK has a wire-shape surface
package for, vendored from the [spec repository] at the commit recorded in package for, vendored from the [spec repository] at the commit recorded in
`PINNED.json`. `scripts/gen_surface_types.py` reads these to regenerate `PINNED.json`. `scripts/gen_surface_types.py` reads these to regenerate
`src/mcp-types/mcp_types/v<version>/__init__.py`; CI runs the generator with `src/mcp-types/mcp_types/_v<version>/__init__.py` (underscore-private: internal
`--check`. validators, not public API); CI runs the generator with `--check`.
To bump: drop the new `schema.json` here as `<protocol-version>.json`, update To bump: drop the new `schema.json` here as `<protocol-version>.json`, update
the matching entry in `PINNED.json` (commit + sha256), and run the matching entry in `PINNED.json` (commit + sha256), and run

7
scripts/gen_surface_types.py
View file

@ -1,8 +1,9 @@
"""Regenerate the per-version wire-shape surface packages from vendored schemas. """Regenerate the per-version wire-shape surface packages from vendored schemas.
Runs `datamodel-code-generator` over each `schema/PINNED.json` entry and Runs `datamodel-code-generator` over each `schema/PINNED.json` entry and
writes the result to `src/mcp-types/mcp_types/v<version>/__init__.py` with only the writes the result to `src/mcp-types/mcp_types/_v<version>/__init__.py` (the
fixes the raw output needs: a small JSON pre-patch for the known underscore marks these as internal validators, not public API) with only
the fixes the raw output needs: a small JSON pre-patch for the known
`number`-as-`integer` schema.json defect, a header, full URLs for the spec's `number`-as-`integer` schema.json defect, a header, full URLs for the spec's
site-absolute doc links, and per-version epilogue aliases. Run with site-absolute doc links, and per-version epilogue aliases. Run with
`uv run --frozen --group codegen python scripts/gen_surface_types.py [--check]`. `uv run --frozen --group codegen python scripts/gen_surface_types.py [--check]`.
@ -270,7 +271,7 @@ def main(argv: list[str] | None = None) -> int:
drift = False drift = False
for entry in load_pinned(): for entry in load_pinned():
target = TYPES_DIR / ("v" + entry["protocol_version"].replace("-", "_")) / "__init__.py" target = TYPES_DIR / ("_v" + entry["protocol_version"].replace("-", "_")) / "__init__.py"
candidate = build(entry) candidate = build(entry)
if not args.check: if not args.check:
target.parent.mkdir(parents=True, exist_ok=True) target.parent.mkdir(parents=True, exist_ok=True)

2
src/mcp-types/mcp_types/_types.py
View file

@ -3,7 +3,7 @@
One model per protocol construct, carrying every field from every supported One model per protocol construct, carrying every field from every supported
protocol version, so application code sees a single set of types regardless of protocol version, so application code sees a single set of types regardless of
the negotiated version. Per-field docstrings note version availability. The the negotiated version. Per-field docstrings note version availability. The
`mcp_types.v*` surface packages carry the schema-exact wire shapes. `mcp_types._v*` surface packages carry the schema-exact wire shapes.
""" """
from __future__ import annotations from __future__ import annotations

3526
src/mcp-types/mcp_types/_v2025_11_25/__init__.py Normal file
View file

File diff suppressed because it is too large Load diff

3746
src/mcp-types/mcp_types/_v2026_07_28/__init__.py Normal file
View file

File diff suppressed because it is too large Load diff

2
src/mcp-types/mcp_types/_wire_base.py
View file

@ -1,4 +1,4 @@
"""Shared pydantic base for the generated `mcp_types.v*` wire-shape packages.""" """Shared pydantic base for the generated `mcp_types._v*` wire-shape packages."""
from pydantic import BaseModel, ConfigDict from pydantic import BaseModel, ConfigDict

6
src/mcp-types/mcp_types/methods.py
View file

@ -1,6 +1,6 @@
"""Per-version method maps and parse/serialize functions for MCP traffic. """Per-version method maps and parse/serialize functions for MCP traffic.
This module is supported public API; the `mcp_types.v*` packages it draws on This module is supported public API; the `mcp_types._v*` packages it draws on
are internal validators and not for direct import. are internal validators and not for direct import.
Surface maps key `(method, version)` to per-version wire types (key absence is Surface maps key `(method, version)` to per-version wire types (key absence is
@ -18,8 +18,8 @@ from typing import Any, Final, Literal, TypeGuard, TypeVar, cast, get_args
from pydantic import BaseModel, TypeAdapter from pydantic import BaseModel, TypeAdapter
import mcp_types as types import mcp_types as types
import mcp_types.v2025_11_25 as v2025 import mcp_types._v2025_11_25 as v2025
import mcp_types.v2026_07_28 as v2026 import mcp_types._v2026_07_28 as v2026
from mcp_types.version import KNOWN_PROTOCOL_VERSIONS from mcp_types.version import KNOWN_PROTOCOL_VERSIONS
__all__ = [ __all__ = [

2
src/mcp/server/elicitation.py
View file

@ -7,7 +7,7 @@ from typing import Any, Generic, Literal, TypeVar
from mcp_types import RequestId from mcp_types import RequestId
# Internal surface package; imported as the gate's source of truth for spec-valid property schemas. # Internal surface package; imported as the gate's source of truth for spec-valid property schemas.
from mcp_types.v2025_11_25 import PrimitiveSchemaDefinition from mcp_types._v2025_11_25 import PrimitiveSchemaDefinition
from pydantic import BaseModel, ValidationError from pydantic import BaseModel, ValidationError
from pydantic.json_schema import GenerateJsonSchema, JsonSchemaValue from pydantic.json_schema import GenerateJsonSchema, JsonSchemaValue
from pydantic_core import core_schema from pydantic_core import core_schema

14
tests/types/test_methods.py
View file

@ -6,8 +6,8 @@ from types import MappingProxyType, UnionType
from typing import Any, get_args from typing import Any, get_args
import mcp_types as types import mcp_types as types
import mcp_types.v2025_11_25 as v2025 import mcp_types._v2025_11_25 as v2025
import mcp_types.v2026_07_28 as v2026 import mcp_types._v2026_07_28 as v2026
import pydantic import pydantic
import pytest import pytest
from mcp_types import methods from mcp_types import methods
@ -295,11 +295,11 @@ EMPTY_CLIENT_RESPONSE_METHODS = frozenset({"ping"})
# Pre-2026 versions share the 2025-11-25 surface package. # Pre-2026 versions share the 2025-11-25 surface package.
PACKAGE_BY_VERSION = { PACKAGE_BY_VERSION = {
"2024-11-05": "mcp_types.v2025_11_25", "2024-11-05": "mcp_types._v2025_11_25",
"2025-03-26": "mcp_types.v2025_11_25", "2025-03-26": "mcp_types._v2025_11_25",
"2025-06-18": "mcp_types.v2025_11_25", "2025-06-18": "mcp_types._v2025_11_25",
"2025-11-25": "mcp_types.v2025_11_25", "2025-11-25": "mcp_types._v2025_11_25",
"2026-07-28": "mcp_types.v2026_07_28", "2026-07-28": "mcp_types._v2026_07_28",
} }
# The reserved `params._meta` entries the 2026 surface accepts on every request. # The reserved `params._meta` entries the 2026 surface accepts on every request.

214
tests/types/test_parity.py
View file

@ -7,8 +7,8 @@ from types import ModuleType
import mcp_types as monolith import mcp_types as monolith
import mcp_types._types as _types import mcp_types._types as _types
import mcp_types.v2025_11_25 as v2025_11_25 import mcp_types._v2025_11_25 as v2025_11_25
import mcp_types.v2026_07_28 as v2026_07_28 import mcp_types._v2026_07_28 as v2026_07_28
import pytest import pytest
from pydantic import BaseModel from pydantic import BaseModel
@ -19,116 +19,116 @@ ENVELOPE_FIELDS: frozenset[str] = frozenset({"jsonrpc", "id"})
# Surface classes whose monolith counterpart has a different name (key: "<surface_tail>.<ClassName>"). # Surface classes whose monolith counterpart has a different name (key: "<surface_tail>.<ClassName>").
NAME_MAP: dict[str, type[BaseModel]] = { NAME_MAP: dict[str, type[BaseModel]] = {
# v2025_11_25 # _v2025_11_25
"v2025_11_25.Argument": monolith.CompletionArgument, "_v2025_11_25.Argument": monolith.CompletionArgument,
"v2025_11_25.Context": monolith.CompletionContext, "_v2025_11_25.Context": monolith.CompletionContext,
"v2025_11_25.Data": monolith.ElicitationRequiredErrorData, "_v2025_11_25.Data": monolith.ElicitationRequiredErrorData,
"v2025_11_25.Elicitation": monolith.ElicitationCapability, "_v2025_11_25.Elicitation": monolith.ElicitationCapability,
"v2025_11_25.Elicitation1": monolith.TasksElicitationCapability, "_v2025_11_25.Elicitation1": monolith.TasksElicitationCapability,
"v2025_11_25.ElicitationCompleteNotification": monolith.ElicitCompleteNotification, "_v2025_11_25.ElicitationCompleteNotification": monolith.ElicitCompleteNotification,
"v2025_11_25.Params": monolith.CancelTaskRequestParams, "_v2025_11_25.Params": monolith.CancelTaskRequestParams,
"v2025_11_25.Params1": monolith.ElicitCompleteNotificationParams, "_v2025_11_25.Params1": monolith.ElicitCompleteNotificationParams,
"v2025_11_25.Params2": monolith.GetTaskPayloadRequestParams, "_v2025_11_25.Params2": monolith.GetTaskPayloadRequestParams,
"v2025_11_25.Params3": monolith.GetTaskRequestParams, "_v2025_11_25.Params3": monolith.GetTaskRequestParams,
"v2025_11_25.Error": monolith.ErrorData, "_v2025_11_25.Error": monolith.ErrorData,
"v2025_11_25.JSONRPCErrorResponse": monolith.JSONRPCError, "_v2025_11_25.JSONRPCErrorResponse": monolith.JSONRPCError,
"v2025_11_25.JSONRPCResultResponse": monolith.JSONRPCResponse, "_v2025_11_25.JSONRPCResultResponse": monolith.JSONRPCResponse,
"v2025_11_25.Prompts": monolith.PromptsCapability, "_v2025_11_25.Prompts": monolith.PromptsCapability,
"v2025_11_25.Requests": monolith.ClientTasksRequestsCapability, "_v2025_11_25.Requests": monolith.ClientTasksRequestsCapability,
"v2025_11_25.Requests1": monolith.ServerTasksRequestsCapability, "_v2025_11_25.Requests1": monolith.ServerTasksRequestsCapability,
"v2025_11_25.Resources": monolith.ResourcesCapability, "_v2025_11_25.Resources": monolith.ResourcesCapability,
"v2025_11_25.Roots": monolith.RootsCapability, "_v2025_11_25.Roots": monolith.RootsCapability,
"v2025_11_25.Sampling": monolith.SamplingCapability, "_v2025_11_25.Sampling": monolith.SamplingCapability,
"v2025_11_25.Sampling1": monolith.TasksSamplingCapability, "_v2025_11_25.Sampling1": monolith.TasksSamplingCapability,
"v2025_11_25.Tasks": monolith.ClientTasksCapability, "_v2025_11_25.Tasks": monolith.ClientTasksCapability,
"v2025_11_25.Tasks1": monolith.ServerTasksCapability, "_v2025_11_25.Tasks1": monolith.ServerTasksCapability,
"v2025_11_25.Tools": monolith.TasksToolsCapability, "_v2025_11_25.Tools": monolith.TasksToolsCapability,
"v2025_11_25.Tools1": monolith.ToolsCapability, "_v2025_11_25.Tools1": monolith.ToolsCapability,
# v2026_07_28 # _v2026_07_28
"v2026_07_28.Argument": monolith.CompletionArgument, "_v2026_07_28.Argument": monolith.CompletionArgument,
"v2026_07_28.Context": monolith.CompletionContext, "_v2026_07_28.Context": monolith.CompletionContext,
"v2026_07_28.Data": monolith.MissingRequiredClientCapabilityErrorData, "_v2026_07_28.Data": monolith.MissingRequiredClientCapabilityErrorData,
"v2026_07_28.Data1": monolith.UnsupportedProtocolVersionErrorData, "_v2026_07_28.Data1": monolith.UnsupportedProtocolVersionErrorData,
"v2026_07_28.Elicitation": monolith.ElicitationCapability, "_v2026_07_28.Elicitation": monolith.ElicitationCapability,
"v2026_07_28.Error": monolith.ErrorData, "_v2026_07_28.Error": monolith.ErrorData,
"v2026_07_28.JSONRPCErrorResponse": monolith.JSONRPCError, "_v2026_07_28.JSONRPCErrorResponse": monolith.JSONRPCError,
"v2026_07_28.JSONRPCResultResponse": monolith.JSONRPCResponse, "_v2026_07_28.JSONRPCResultResponse": monolith.JSONRPCResponse,
"v2026_07_28.Prompts": monolith.PromptsCapability, "_v2026_07_28.Prompts": monolith.PromptsCapability,
"v2026_07_28.Resources": monolith.ResourcesCapability, "_v2026_07_28.Resources": monolith.ResourcesCapability,
"v2026_07_28.Sampling": monolith.SamplingCapability, "_v2026_07_28.Sampling": monolith.SamplingCapability,
"v2026_07_28.Tools": monolith.ToolsCapability, "_v2026_07_28.Tools": monolith.ToolsCapability,
} }
# Surface classes with no monolith equivalent (envelope wrappers, JSON-Schema fragments modelled as `dict`). # Surface classes with no monolith equivalent (envelope wrappers, JSON-Schema fragments modelled as `dict`).
SKIP: frozenset[str] = frozenset( SKIP: frozenset[str] = frozenset(
{ {
# v2025_11_25 # _v2025_11_25
"v2025_11_25.AnyOfItem", "_v2025_11_25.AnyOfItem",
"v2025_11_25.BooleanSchema", "_v2025_11_25.BooleanSchema",
"v2025_11_25.Error1", "_v2025_11_25.Error1",
"v2025_11_25.Icons", "_v2025_11_25.Icons",
"v2025_11_25.InputSchema", "_v2025_11_25.InputSchema",
"v2025_11_25.Items", "_v2025_11_25.Items",
"v2025_11_25.Items1", "_v2025_11_25.Items1",
"v2025_11_25.LegacyTitledEnumSchema", "_v2025_11_25.LegacyTitledEnumSchema",
"v2025_11_25.Meta", "_v2025_11_25.Meta",
"v2025_11_25.NumberSchema", "_v2025_11_25.NumberSchema",
"v2025_11_25.OneOfItem", "_v2025_11_25.OneOfItem",
"v2025_11_25.OutputSchema", "_v2025_11_25.OutputSchema",
"v2025_11_25.RequestedSchema", "_v2025_11_25.RequestedSchema",
"v2025_11_25.ResourceRequestParams", "_v2025_11_25.ResourceRequestParams",
"v2025_11_25.StringSchema", "_v2025_11_25.StringSchema",
"v2025_11_25.TaskAugmentedRequestParams", "_v2025_11_25.TaskAugmentedRequestParams",
"v2025_11_25.TitledMultiSelectEnumSchema", "_v2025_11_25.TitledMultiSelectEnumSchema",
"v2025_11_25.TitledSingleSelectEnumSchema", "_v2025_11_25.TitledSingleSelectEnumSchema",
"v2025_11_25.URLElicitationRequiredError", "_v2025_11_25.URLElicitationRequiredError",
"v2025_11_25.UntitledMultiSelectEnumSchema", "_v2025_11_25.UntitledMultiSelectEnumSchema",
"v2025_11_25.UntitledSingleSelectEnumSchema", "_v2025_11_25.UntitledSingleSelectEnumSchema",
# v2026_07_28 # _v2026_07_28
"v2026_07_28.AnyOfItem", "_v2026_07_28.AnyOfItem",
"v2026_07_28.BooleanSchema", "_v2026_07_28.BooleanSchema",
"v2026_07_28.CallToolResultResponse", "_v2026_07_28.CallToolResultResponse",
"v2026_07_28.ClientNotification", "_v2026_07_28.ClientNotification",
"v2026_07_28.CompleteResultResponse", "_v2026_07_28.CompleteResultResponse",
"v2026_07_28.DiscoverResultResponse", "_v2026_07_28.DiscoverResultResponse",
"v2026_07_28.Error1", "_v2026_07_28.Error1",
"v2026_07_28.Error2", "_v2026_07_28.Error2",
"v2026_07_28.Error3", "_v2026_07_28.Error3",
"v2026_07_28.GetPromptResultResponse", "_v2026_07_28.GetPromptResultResponse",
"v2026_07_28.HeaderMismatchError", "_v2026_07_28.HeaderMismatchError",
"v2026_07_28.Icons", "_v2026_07_28.Icons",
"v2026_07_28.InputSchema", "_v2026_07_28.InputSchema",
"v2026_07_28.InternalError", "_v2026_07_28.InternalError",
"v2026_07_28.InvalidParamsError", "_v2026_07_28.InvalidParamsError",
"v2026_07_28.InvalidRequestError", "_v2026_07_28.InvalidRequestError",
"v2026_07_28.Items", "_v2026_07_28.Items",
"v2026_07_28.Items1", "_v2026_07_28.Items1",
"v2026_07_28.LegacyTitledEnumSchema", "_v2026_07_28.LegacyTitledEnumSchema",
"v2026_07_28.ListPromptsResultResponse", "_v2026_07_28.ListPromptsResultResponse",
"v2026_07_28.ListResourceTemplatesResultResponse", "_v2026_07_28.ListResourceTemplatesResultResponse",
"v2026_07_28.ListResourcesResultResponse", "_v2026_07_28.ListResourcesResultResponse",
"v2026_07_28.ListToolsResultResponse", "_v2026_07_28.ListToolsResultResponse",
"v2026_07_28.MetaObject", "_v2026_07_28.MetaObject",
"v2026_07_28.MethodNotFoundError", "_v2026_07_28.MethodNotFoundError",
"v2026_07_28.MissingRequiredClientCapabilityError", "_v2026_07_28.MissingRequiredClientCapabilityError",
"v2026_07_28.NotificationMetaObject", "_v2026_07_28.NotificationMetaObject",
"v2026_07_28.NumberSchema", "_v2026_07_28.NumberSchema",
"v2026_07_28.OneOfItem", "_v2026_07_28.OneOfItem",
"v2026_07_28.OutputSchema", "_v2026_07_28.OutputSchema",
"v2026_07_28.Params", "_v2026_07_28.Params",
"v2026_07_28.ParseError", "_v2026_07_28.ParseError",
"v2026_07_28.ReadResourceResultResponse", "_v2026_07_28.ReadResourceResultResponse",
"v2026_07_28.RequestMetaObject", "_v2026_07_28.RequestMetaObject",
"v2026_07_28.RequestedSchema", "_v2026_07_28.RequestedSchema",
"v2026_07_28.ResourceRequestParams", "_v2026_07_28.ResourceRequestParams",
"v2026_07_28.ResultMetaObject", "_v2026_07_28.ResultMetaObject",
"v2026_07_28.StringSchema", "_v2026_07_28.StringSchema",
"v2026_07_28.SubscriptionsListenResultMeta", "_v2026_07_28.SubscriptionsListenResultMeta",
"v2026_07_28.TitledMultiSelectEnumSchema", "_v2026_07_28.TitledMultiSelectEnumSchema",
"v2026_07_28.TitledSingleSelectEnumSchema", "_v2026_07_28.TitledSingleSelectEnumSchema",
"v2026_07_28.UnsupportedProtocolVersionError", "_v2026_07_28.UnsupportedProtocolVersionError",
"v2026_07_28.UntitledMultiSelectEnumSchema", "_v2026_07_28.UntitledMultiSelectEnumSchema",
"v2026_07_28.UntitledSingleSelectEnumSchema", "_v2026_07_28.UntitledSingleSelectEnumSchema",
} }
) )