github-featured/modelcontextprotocol--python-sdk
2
0
Fork 0
Code Issues Pull Requests Deployments Models Agent Notes Packages Projects Releases Wiki Activity

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
parent 45f2a88a9a
commit b9422f1c9b
13 changed files with 133 additions and 127 deletions
Download Patch File Download Diff File Expand all files Collapse all files
.github/workflows/shared.yml
+1 -1
View File
@@ -51,7 +51,7 @@ jobs:
- name: mcp-types installs and imports standalone
run: |
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:
name: test (${{ matrix.python-version }}, ${{ matrix.dep-resolution.name }}, ${{ matrix.os }})
docs/migration.md
+5
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
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
depend on the protocol schema without pulling in `httpx2`, `starlette`, `uvicorn`, and the
rest of the server/transport stack.
pyproject.toml
+1 -1
View File
@@ -218,7 +218,7 @@ max-complexity = 24 # Default is 10
[tool.ruff.lint.per-file-ignores]
"__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).
"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/shared/test_progress_notifications.py" = ["PLW0603"]
schema/README.md
+2 -2
View File
@@ -3,8 +3,8 @@
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
`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
`--check`.
`src/mcp-types/mcp_types/_v<version>/__init__.py` (underscore-private: internal
validators, not public API); CI runs the generator with `--check`.
To bump: drop the new `schema.json` here as `<protocol-version>.json`, update
the matching entry in `PINNED.json` (commit + sha256), and run
scripts/gen_surface_types.py
+4 -3
View File
@@ -1,8 +1,9 @@
"""Regenerate the per-version wire-shape surface packages from vendored schemas.
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
fixes the raw output needs: a small JSON pre-patch for the known
writes the result to `src/mcp-types/mcp_types/_v<version>/__init__.py` (the
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
site-absolute doc links, and per-version epilogue aliases. Run with
`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
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)
if not args.check:
target.parent.mkdir(parents=True, exist_ok=True)
src/mcp-types/mcp_types/_types.py
+1 -1
View File
@@ -3,7 +3,7 @@
One model per protocol construct, carrying every field from every supported
protocol version, so application code sees a single set of types regardless of
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
src/mcp-types/mcp_types/v2025_11_25/__init__.py → src/mcp-types/mcp_types/_v2025_11_25/__init__.py
View File
src/mcp-types/mcp_types/v2026_07_28/__init__.py → src/mcp-types/mcp_types/_v2026_07_28/__init__.py
View File
src/mcp-types/mcp_types/_wire_base.py
+1 -1
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
src/mcp-types/mcp_types/methods.py
+3 -3
View File
@@ -1,6 +1,6 @@
"""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.
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
import mcp_types as types
import mcp_types.v2025_11_25 as v2025
import mcp_types.v2026_07_28 as v2026
import mcp_types._v2025_11_25 as v2025
import mcp_types._v2026_07_28 as v2026
from mcp_types.version import KNOWN_PROTOCOL_VERSIONS
__all__ = [
src/mcp/server/elicitation.py
+1 -1
View File
@@ -7,7 +7,7 @@ from typing import Any, Generic, Literal, TypeVar
from mcp_types import RequestId
# 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.json_schema import GenerateJsonSchema, JsonSchemaValue
from pydantic_core import core_schema
tests/types/test_methods.py
+7 -7
View File
@@ -6,8 +6,8 @@ from types import MappingProxyType, UnionType
from typing import Any, get_args
import mcp_types as types
import mcp_types.v2025_11_25 as v2025
import mcp_types.v2026_07_28 as v2026
import mcp_types._v2025_11_25 as v2025
import mcp_types._v2026_07_28 as v2026
import pydantic
import pytest
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.
PACKAGE_BY_VERSION = {
"2024-11-05": "mcp_types.v2025_11_25",
"2025-03-26": "mcp_types.v2025_11_25",
"2025-06-18": "mcp_types.v2025_11_25",
"2025-11-25": "mcp_types.v2025_11_25",
"2026-07-28": "mcp_types.v2026_07_28",
"2024-11-05": "mcp_types._v2025_11_25",
"2025-03-26": "mcp_types._v2025_11_25",
"2025-06-18": "mcp_types._v2025_11_25",
"2025-11-25": "mcp_types._v2025_11_25",
"2026-07-28": "mcp_types._v2026_07_28",
}
# The reserved `params._meta` entries the 2026 surface accepts on every request.
tests/types/test_parity.py
+107 -107
View File
@@ -7,8 +7,8 @@ from types import ModuleType
import mcp_types as monolith
import mcp_types._types as _types
import mcp_types.v2025_11_25 as v2025_11_25
import mcp_types.v2026_07_28 as v2026_07_28
import mcp_types._v2025_11_25 as v2025_11_25
import mcp_types._v2026_07_28 as v2026_07_28
import pytest
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>").
NAME_MAP: dict[str, type[BaseModel]] = {
# v2025_11_25
"v2025_11_25.Argument": monolith.CompletionArgument,
"v2025_11_25.Context": monolith.CompletionContext,
"v2025_11_25.Data": monolith.ElicitationRequiredErrorData,
"v2025_11_25.Elicitation": monolith.ElicitationCapability,
"v2025_11_25.Elicitation1": monolith.TasksElicitationCapability,
"v2025_11_25.ElicitationCompleteNotification": monolith.ElicitCompleteNotification,
"v2025_11_25.Params": monolith.CancelTaskRequestParams,
"v2025_11_25.Params1": monolith.ElicitCompleteNotificationParams,
"v2025_11_25.Params2": monolith.GetTaskPayloadRequestParams,
"v2025_11_25.Params3": monolith.GetTaskRequestParams,
"v2025_11_25.Error": monolith.ErrorData,
"v2025_11_25.JSONRPCErrorResponse": monolith.JSONRPCError,
"v2025_11_25.JSONRPCResultResponse": monolith.JSONRPCResponse,
"v2025_11_25.Prompts": monolith.PromptsCapability,
"v2025_11_25.Requests": monolith.ClientTasksRequestsCapability,
"v2025_11_25.Requests1": monolith.ServerTasksRequestsCapability,
"v2025_11_25.Resources": monolith.ResourcesCapability,
"v2025_11_25.Roots": monolith.RootsCapability,
"v2025_11_25.Sampling": monolith.SamplingCapability,
"v2025_11_25.Sampling1": monolith.TasksSamplingCapability,
"v2025_11_25.Tasks": monolith.ClientTasksCapability,
"v2025_11_25.Tasks1": monolith.ServerTasksCapability,
"v2025_11_25.Tools": monolith.TasksToolsCapability,
"v2025_11_25.Tools1": monolith.ToolsCapability,
# v2026_07_28
"v2026_07_28.Argument": monolith.CompletionArgument,
"v2026_07_28.Context": monolith.CompletionContext,
"v2026_07_28.Data": monolith.MissingRequiredClientCapabilityErrorData,
"v2026_07_28.Data1": monolith.UnsupportedProtocolVersionErrorData,
"v2026_07_28.Elicitation": monolith.ElicitationCapability,
"v2026_07_28.Error": monolith.ErrorData,
"v2026_07_28.JSONRPCErrorResponse": monolith.JSONRPCError,
"v2026_07_28.JSONRPCResultResponse": monolith.JSONRPCResponse,
"v2026_07_28.Prompts": monolith.PromptsCapability,
"v2026_07_28.Resources": monolith.ResourcesCapability,
"v2026_07_28.Sampling": monolith.SamplingCapability,
"v2026_07_28.Tools": monolith.ToolsCapability,
# _v2025_11_25
"_v2025_11_25.Argument": monolith.CompletionArgument,
"_v2025_11_25.Context": monolith.CompletionContext,
"_v2025_11_25.Data": monolith.ElicitationRequiredErrorData,
"_v2025_11_25.Elicitation": monolith.ElicitationCapability,
"_v2025_11_25.Elicitation1": monolith.TasksElicitationCapability,
"_v2025_11_25.ElicitationCompleteNotification": monolith.ElicitCompleteNotification,
"_v2025_11_25.Params": monolith.CancelTaskRequestParams,
"_v2025_11_25.Params1": monolith.ElicitCompleteNotificationParams,
"_v2025_11_25.Params2": monolith.GetTaskPayloadRequestParams,
"_v2025_11_25.Params3": monolith.GetTaskRequestParams,
"_v2025_11_25.Error": monolith.ErrorData,
"_v2025_11_25.JSONRPCErrorResponse": monolith.JSONRPCError,
"_v2025_11_25.JSONRPCResultResponse": monolith.JSONRPCResponse,
"_v2025_11_25.Prompts": monolith.PromptsCapability,
"_v2025_11_25.Requests": monolith.ClientTasksRequestsCapability,
"_v2025_11_25.Requests1": monolith.ServerTasksRequestsCapability,
"_v2025_11_25.Resources": monolith.ResourcesCapability,
"_v2025_11_25.Roots": monolith.RootsCapability,
"_v2025_11_25.Sampling": monolith.SamplingCapability,
"_v2025_11_25.Sampling1": monolith.TasksSamplingCapability,
"_v2025_11_25.Tasks": monolith.ClientTasksCapability,
"_v2025_11_25.Tasks1": monolith.ServerTasksCapability,
"_v2025_11_25.Tools": monolith.TasksToolsCapability,
"_v2025_11_25.Tools1": monolith.ToolsCapability,
# _v2026_07_28
"_v2026_07_28.Argument": monolith.CompletionArgument,
"_v2026_07_28.Context": monolith.CompletionContext,
"_v2026_07_28.Data": monolith.MissingRequiredClientCapabilityErrorData,
"_v2026_07_28.Data1": monolith.UnsupportedProtocolVersionErrorData,
"_v2026_07_28.Elicitation": monolith.ElicitationCapability,
"_v2026_07_28.Error": monolith.ErrorData,
"_v2026_07_28.JSONRPCErrorResponse": monolith.JSONRPCError,
"_v2026_07_28.JSONRPCResultResponse": monolith.JSONRPCResponse,
"_v2026_07_28.Prompts": monolith.PromptsCapability,
"_v2026_07_28.Resources": monolith.ResourcesCapability,
"_v2026_07_28.Sampling": monolith.SamplingCapability,
"_v2026_07_28.Tools": monolith.ToolsCapability,
}
# Surface classes with no monolith equivalent (envelope wrappers, JSON-Schema fragments modelled as `dict`).
SKIP: frozenset[str] = frozenset(
{
# v2025_11_25
"v2025_11_25.AnyOfItem",
"v2025_11_25.BooleanSchema",
"v2025_11_25.Error1",
"v2025_11_25.Icons",
"v2025_11_25.InputSchema",
"v2025_11_25.Items",
"v2025_11_25.Items1",
"v2025_11_25.LegacyTitledEnumSchema",
"v2025_11_25.Meta",
"v2025_11_25.NumberSchema",
"v2025_11_25.OneOfItem",
"v2025_11_25.OutputSchema",
"v2025_11_25.RequestedSchema",
"v2025_11_25.ResourceRequestParams",
"v2025_11_25.StringSchema",
"v2025_11_25.TaskAugmentedRequestParams",
"v2025_11_25.TitledMultiSelectEnumSchema",
"v2025_11_25.TitledSingleSelectEnumSchema",
"v2025_11_25.URLElicitationRequiredError",
"v2025_11_25.UntitledMultiSelectEnumSchema",
"v2025_11_25.UntitledSingleSelectEnumSchema",
# v2026_07_28
"v2026_07_28.AnyOfItem",
"v2026_07_28.BooleanSchema",
"v2026_07_28.CallToolResultResponse",
"v2026_07_28.ClientNotification",
"v2026_07_28.CompleteResultResponse",
"v2026_07_28.DiscoverResultResponse",
"v2026_07_28.Error1",
"v2026_07_28.Error2",
"v2026_07_28.Error3",
"v2026_07_28.GetPromptResultResponse",
"v2026_07_28.HeaderMismatchError",
"v2026_07_28.Icons",
"v2026_07_28.InputSchema",
"v2026_07_28.InternalError",
"v2026_07_28.InvalidParamsError",
"v2026_07_28.InvalidRequestError",
"v2026_07_28.Items",
"v2026_07_28.Items1",
"v2026_07_28.LegacyTitledEnumSchema",
"v2026_07_28.ListPromptsResultResponse",
"v2026_07_28.ListResourceTemplatesResultResponse",
"v2026_07_28.ListResourcesResultResponse",
"v2026_07_28.ListToolsResultResponse",
"v2026_07_28.MetaObject",
"v2026_07_28.MethodNotFoundError",
"v2026_07_28.MissingRequiredClientCapabilityError",
"v2026_07_28.NotificationMetaObject",
"v2026_07_28.NumberSchema",
"v2026_07_28.OneOfItem",
"v2026_07_28.OutputSchema",
"v2026_07_28.Params",
"v2026_07_28.ParseError",
"v2026_07_28.ReadResourceResultResponse",
"v2026_07_28.RequestMetaObject",
"v2026_07_28.RequestedSchema",
"v2026_07_28.ResourceRequestParams",
"v2026_07_28.ResultMetaObject",
"v2026_07_28.StringSchema",
"v2026_07_28.SubscriptionsListenResultMeta",
"v2026_07_28.TitledMultiSelectEnumSchema",
"v2026_07_28.TitledSingleSelectEnumSchema",
"v2026_07_28.UnsupportedProtocolVersionError",
"v2026_07_28.UntitledMultiSelectEnumSchema",
"v2026_07_28.UntitledSingleSelectEnumSchema",
# _v2025_11_25
"_v2025_11_25.AnyOfItem",
"_v2025_11_25.BooleanSchema",
"_v2025_11_25.Error1",
"_v2025_11_25.Icons",
"_v2025_11_25.InputSchema",
"_v2025_11_25.Items",
"_v2025_11_25.Items1",
"_v2025_11_25.LegacyTitledEnumSchema",
"_v2025_11_25.Meta",
"_v2025_11_25.NumberSchema",
"_v2025_11_25.OneOfItem",
"_v2025_11_25.OutputSchema",
"_v2025_11_25.RequestedSchema",
"_v2025_11_25.ResourceRequestParams",
"_v2025_11_25.StringSchema",
"_v2025_11_25.TaskAugmentedRequestParams",
"_v2025_11_25.TitledMultiSelectEnumSchema",
"_v2025_11_25.TitledSingleSelectEnumSchema",
"_v2025_11_25.URLElicitationRequiredError",
"_v2025_11_25.UntitledMultiSelectEnumSchema",
"_v2025_11_25.UntitledSingleSelectEnumSchema",
# _v2026_07_28
"_v2026_07_28.AnyOfItem",
"_v2026_07_28.BooleanSchema",
"_v2026_07_28.CallToolResultResponse",
"_v2026_07_28.ClientNotification",
"_v2026_07_28.CompleteResultResponse",
"_v2026_07_28.DiscoverResultResponse",
"_v2026_07_28.Error1",
"_v2026_07_28.Error2",
"_v2026_07_28.Error3",
"_v2026_07_28.GetPromptResultResponse",
"_v2026_07_28.HeaderMismatchError",
"_v2026_07_28.Icons",
"_v2026_07_28.InputSchema",
"_v2026_07_28.InternalError",
"_v2026_07_28.InvalidParamsError",
"_v2026_07_28.InvalidRequestError",
"_v2026_07_28.Items",
"_v2026_07_28.Items1",
"_v2026_07_28.LegacyTitledEnumSchema",
"_v2026_07_28.ListPromptsResultResponse",
"_v2026_07_28.ListResourceTemplatesResultResponse",
"_v2026_07_28.ListResourcesResultResponse",
"_v2026_07_28.ListToolsResultResponse",
"_v2026_07_28.MetaObject",
"_v2026_07_28.MethodNotFoundError",
"_v2026_07_28.MissingRequiredClientCapabilityError",
"_v2026_07_28.NotificationMetaObject",
"_v2026_07_28.NumberSchema",
"_v2026_07_28.OneOfItem",
"_v2026_07_28.OutputSchema",
"_v2026_07_28.Params",
"_v2026_07_28.ParseError",
"_v2026_07_28.ReadResourceResultResponse",
"_v2026_07_28.RequestMetaObject",
"_v2026_07_28.RequestedSchema",
"_v2026_07_28.ResourceRequestParams",
"_v2026_07_28.ResultMetaObject",
"_v2026_07_28.StringSchema",
"_v2026_07_28.SubscriptionsListenResultMeta",
"_v2026_07_28.TitledMultiSelectEnumSchema",
"_v2026_07_28.TitledSingleSelectEnumSchema",
"_v2026_07_28.UnsupportedProtocolVersionError",
"_v2026_07_28.UntitledMultiSelectEnumSchema",
"_v2026_07_28.UntitledSingleSelectEnumSchema",
}
)