Merge remote-tracking branch 'origin/main' into fix/1401-surface-transport-exceptions

Author: functionxX

CONTRIBUTING.md

@@ -48,10 +48,25 @@ Bug fixes for clear, reproducible issues are welcome—but still create an issue
 | [`help wanted`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22) | Experienced contributors | Maintainers probably won't get to this |
 | [`ready for work`](https://github.com/modelcontextprotocol/python-sdk/issues?q=is%3Aopen+is%3Aissue+label%3A%22ready+for+work%22) | Maintainers | Triaged and ready for a maintainer to pick up |
 
-Issues labeled `needs confirmation` or `needs maintainer action` are **not** ready for work—wait for maintainer input first.
+Issues labeled `needs confirmation` or `needs maintainer` are **not** ready for work—wait for maintainer input first.
 
 Before starting, comment on the issue so we can assign it to you. This prevents duplicate effort.
 
+## Issue Triage
+
+Every new issue gets a first look from a maintainer within two business days. That first look is the *triage*: it means labeling the issue and deciding whether it is valid and actionable, not fixing it.
+
+The core labels follow the shared [MCP SDK taxonomy](https://modelcontextprotocol.io/community/sdk-tiers#issue-triage-labels) (the repository also carries workflow labels of its own, such as `needs maintainer` and `needs decision`): one **type** (`bug`, `enhancement`, `question`), one **status** (`needs confirmation`, `needs repro`, `ready for work`, `good first issue`, `help wanted`), and — once actionable — one **priority**:
+
+| Label | Meaning | Commitment |
+|-------|---------|------------|
+| `P0` | Critical: core functionality failures (connections, message exchange, tools/resources/prompts) or a High/Critical-severity security issue | resolved within 7 days |
+| `P1` | Significant bug affecting many users | next release |
+| `P2` | Moderate issue or valuable feature request | as capacity allows |
+| `P3` | Nice-to-have or rare edge case | opportunistic |
+
+Security reports do not belong in the issue tracker; [SECURITY.md](SECURITY.md) has the private channel.
+
 ## Development Setup
 
 1. Make sure you have Python 3.10+ installed
@@ -154,6 +169,7 @@ A few dozen lines can be reviewed in minutes. Hundreds of lines across many file
 2. Add tests for new functionality
 3. Ensure CI passes
 4. Address review feedback
+5. Dependency bound changes and new runtime dependencies follow the [Dependency Policy](DEPENDENCY_POLICY.md)
 
 ## Code of Conduct
 

DEPENDENCY_POLICY.md

@@ -0,0 +1,15 @@
+# Dependency Policy
+
+`mcp` is a library that lives inside other people's environments, so its requirements are chosen to constrain your resolver as little as possible while still describing what the SDK needs.
+
+## How requirements are declared
+
+Every runtime dependency is a `>=` floor set to the oldest version that provides what the SDK uses, with no upper bound unless a dependency's next major is known to break the SDK. The one exception is `mcp-types`, the wire-types package released in lockstep with `mcp`: each `mcp` release requires exactly its own version of it, so it is the other half of the SDK rather than an independent constraint.
+
+## When a floor moves
+
+A floor is raised only when the SDK starts relying on functionality or a fix that first appeared in that version — not because the dependency published a security advisory. The `>=` bound already lets, and expects, you to run the newest release your other constraints allow, so a higher floor would only shrink the environments the SDK installs into; nor does the SDK add code to work around a dependency's vulnerability, since the fix belongs upstream and in your lockfile ([background](https://github.com/Kludex/uvicorn/discussions/2643), [python-sdk#1552](https://github.com/modelcontextprotocol/python-sdk/issues/1552)). Floor raises may ship in a minor release under the [versioning policy](VERSIONING.md) and are called out in the release notes. Adding a new runtime dependency, or moving one to its next major version, is decided in an issue before the pull request.
+
+## Automated updates
+
+[Dependabot](https://github.com/modelcontextprotocol/python-sdk/blob/main/.github/dependabot.yml) opens monthly, grouped pull requests for the `uv` lockfile and for GitHub Actions. These refresh the versions the SDK is developed and tested against; the requirements published to PyPI move only under the rules above.

RELEASE.md

@@ -2,10 +2,17 @@
 
 ## Bumping Dependencies
 
+[`DEPENDENCY_POLICY.md`](DEPENDENCY_POLICY.md) says *when* a bound should
+move; this is the mechanics.
+
 1. Change the dependency version in `pyproject.toml`. The root `mcp` project's
    runtime dependencies are dynamic and live under
    `[tool.hatch.metadata.hooks.uv-dynamic-versioning].dependencies`.
-2. Upgrade lock with `uv lock --resolution lowest-direct`
+2. Regenerate the lock with `uv lock` (or `uv lock --upgrade-package <package>`
+   to move just that package's locked version). The committed `uv.lock` is a
+   normal (default-strategy) resolution; the `lowest-direct` resolution that
+   proves the floors still work is applied only by its CI matrix leg at test
+   time and is never committed.
 
 ## Release lines
 
@@ -104,8 +111,9 @@ hand for the same reason as above. Then ask someone to review the release.
 Pre-releases of the next version are cut from `main` with a PEP 440
 pre-release tag: `aN` for alphas, later `bN`/`rcN` for betas and release
 candidates. The PEP 440 suffix is what keeps `pip install mcp` on the stable
-version — installers only select a pre-release when it is requested explicitly (an
-exact pin, a specifier that names a pre-release version, or `--pre`).
+version — installers do not pick a pre-release for a plain `mcp` requirement while a
+final release satisfies it; a pre-release is opted into with an exact pin, a
+specifier that names a pre-release version, or `--pre`.
 
 1. During a pre-release phase the README and docs pin the exact pre-release
    version, so update those examples first (grep the outgoing version — the

ROADMAP.md

@@ -0,0 +1,21 @@
+# Roadmap
+
+The SDK's work is organized by MCP specification revision, with one GitHub project board per revision; each item is an issue or pull request you can follow.
+
+## The 2026-07-28 revision
+
+v2 implements the [2026-07-28 specification](https://modelcontextprotocol.io/specification/2026-07-28) and negotiates back to every earlier revision. Board: **[python-sdk · 2026-07-28 spec](https://github.com/orgs/modelcontextprotocol/projects/42)**; the cross-SDK view is [2026-07-28 Spec Implementation](https://github.com/orgs/modelcontextprotocol/projects/41). Still open there: making advertised capabilities configurable rather than pre-computed ([#2896](https://github.com/modelcontextprotocol/python-sdk/issues/2896)).
+
+## Not yet implemented
+
+Of the extensions and optional client-auth mechanisms not yet implemented, those the conformance suite already exercises appear in its expected-failures baseline, [`.github/actions/conformance/expected-failures.yml`](.github/actions/conformance/expected-failures.yml), which burns down as each lands. The main ones:
+
+* **Tasks extension** (`io.modelcontextprotocol/tasks`, [SEP-2663](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/seps/2663-tasks-extension.md)) — deferred at 2.0 because the 2026-07-28 design is wire-incompatible with the earlier in-core Tasks; tracked in [#2806](https://github.com/modelcontextprotocol/python-sdk/issues/2806).
+* **DPoP-bound access tokens** ([SEP-1932](https://github.com/modelcontextprotocol/modelcontextprotocol/issues/1932)) in the OAuth client.
+* **The workload-identity `jwt-bearer` grant** in the OAuth client.
+
+Everything else — bugs and smaller features — lives in the [issue tracker](https://github.com/modelcontextprotocol/python-sdk/issues), prioritized `P0`–`P3`. The SDK aims to release support for each new specification revision alongside that revision.
+
+## The previous major
+
+`v1.x` is a maintenance line: critical bug fixes and security fixes only. Support terms are in [Versioning and support policy](VERSIONING.md#support-and-announcements); the path off it is the **[Migration Guide](https://py.sdk.modelcontextprotocol.io/migration/)**.

VERSIONING.md

@@ -0,0 +1,45 @@
+# Versioning and support policy
+
+What a version number of `mcp` promises: which changes can arrive in a minor release, which wait for a major, how deprecations are announced, and which release lines are supported.
+
+## The version number
+
+[Semantic Versioning](https://semver.org/) semantics in [PEP 440](https://peps.python.org/pep-0440/) syntax, taken from the git tag: in `2.X.Y`, **X** (minor) carries new functionality and every non-breaking change, **Y** (patch) carries bug fixes only, and a breaking change to the public API lands only in a new **major**. Pre-releases are cut from `main` as `aN`/`bN`/`rcN`; installers prefer final releases by default, so an unpinned `pip install mcp` stays on a stable release whenever one satisfies your requirement. `mcp` and its wire-types package `mcp-types` release in lockstep, each `mcp` requiring exactly the matching `mcp-types`.
+
+## The public API
+
+The promise covers every name exported by `mcp` and `mcp_types` (their `__all__`), the import paths, signatures, and behavior documented on the [documentation site](https://py.sdk.modelcontextprotocol.io/) and in its [API Reference](https://py.sdk.modelcontextprotocol.io/api/mcp/). It does not cover underscore-prefixed names, undocumented modules, or the wording of log lines, warnings, and exception messages (their types and documented raise conditions are covered). APIs labelled **provisional** (for example the middleware chain) may still change in a minor release; **experimental** APIs are opt-in previews.
+
+## Breaking and non-breaking changes
+
+Held for the next major:
+
+* removing or renaming a public name,
+* changing a signature, return type, raised exception type, or documented behavior so that working code stops working,
+* removing a documented import path, extra, or CLI command.
+
+Allowed in a minor:
+
+* additions — functions, defaulted parameters, classes, fields, enum members,
+* changes to provisional or experimental APIs,
+* new deprecation warnings, and retired protocol features ceasing to work on connections that negotiate a revision without them (their Python names stay, deprecated, until a major),
+* raising a dependency floor the SDK needs (see the [dependency policy](DEPENDENCY_POLICY.md)) when the dependency's changes don't reach you through the SDK's API, or dropping a Python version after its upstream end-of-life — both called out in the release notes,
+* bug fixes, including ones that make the SDK match its documented or specified behavior.
+
+## Deprecations
+
+**SDK APIs** are deprecated before removal: they keep working for at least one minor release, marked with [`typing_extensions.deprecated`](https://typing-extensions.readthedocs.io/en/latest/#typing_extensions.deprecated) wherever Python can carry the marker (docstring and migration guide otherwise), and are removed only in a major. **Protocol features** the specification retires keep their implementation through the spec's deprecation window and warn with `MCPDeprecationWarning`, a `UserWarning` subclass that shows by default; what still functions depends on the revision a connection negotiated — see [Deprecated features](https://py.sdk.modelcontextprotocol.io/deprecated/).
+
+## Support and announcements
+
+Two lines are maintained, and only the newest release of each receives fixes:
+
+* **2.x** (`main`) — bug fixes, security fixes, and features.
+* **1.x** ([`v1.x`](https://github.com/modelcontextprotocol/python-sdk/tree/v1.x)) — critical bug fixes and security fixes.
+
+Where changes are announced:
+
+* [SECURITY.md](https://github.com/modelcontextprotocol/python-sdk/blob/main/SECURITY.md) has the vulnerability reporting process.
+* Every release publishes notes on [GitHub Releases](https://github.com/modelcontextprotocol/python-sdk/releases).
+* Every breaking change between majors is documented in the [Migration Guide](https://py.sdk.modelcontextprotocol.io/migration/) before it merges.
+* Pull requests that make a breaking change carry the `breaking change` label.

src/mcp/client/session.py

@@ -4,10 +4,10 @@
 import logging
 from collections.abc import Callable, Mapping, Sequence
 from dataclasses import dataclass
-from functools import reduce
+from functools import cache, reduce
 from operator import or_
-from types import TracebackType
-from typing import TYPE_CHECKING, Annotated, Any, Final, Literal, Protocol, TypeAlias, cast, overload
+from types import TracebackType, UnionType
+from typing import TYPE_CHECKING, Annotated, Any, Final, Literal, Protocol, TypeAlias, cast, get_args, overload
 
 import anyio
 import anyio.abc
@@ -30,6 +30,7 @@
 from mcp_types import methods as _methods
 from mcp_types.version import (
     HANDSHAKE_PROTOCOL_VERSIONS,
+    KNOWN_PROTOCOL_VERSIONS,
     LATEST_HANDSHAKE_VERSION,
     LATEST_MODERN_VERSION,
     MODERN_PROTOCOL_VERSIONS,
@@ -77,6 +78,45 @@ def _clamp_inbound_ttl(raw: dict[str, Any]) -> None:
         raw["ttlMs"] = 0
 
 
+@cache
+def _wire_fields(target: type[BaseModel] | UnionType) -> frozenset[str]:
+    """Top-level wire keys `target` declares (its members', for a union).
+
+    A `RootModel` row (e.g. an empty result carried as `RootModel[Result]`)
+    reports its wrapped type's keys, not the pydantic-internal `root`.
+    """
+    members: tuple[Any, ...] = get_args(target) if isinstance(target, UnionType) else (target,)
+    models = [m for m in members if isinstance(m, type) and issubclass(m, BaseModel)]
+    fields: set[str] = set()
+    for model in models:
+        if getattr(model, "__pydantic_root_model__", False):  # a RootModel wrapper row
+            fields |= _wire_fields(model.model_fields["root"].annotation)
+        else:
+            fields.update(field.alias or name for name, field in model.model_fields.items())
+    return frozenset(fields)
+
+
+@cache
+def _later_revision_fields(method: str, version: str) -> frozenset[str]:
+    """Result keys a revision newer than `version` declares for `method` but `version` doesn't.
+
+    The version-free result types carry every revision's fields, so such a key
+    (e.g. 2026-07-28 `ttlMs`/`cacheScope` on a pre-2026 session) is outside the
+    negotiated contract yet would still parse into the model and trip that later
+    revision's constraints. Empty at the newest known revision.
+    """
+    current = _methods.SERVER_RESULTS.get((method, version))
+    if current is None or version not in KNOWN_PROTOCOL_VERSIONS:
+        return frozenset()
+    newer = KNOWN_PROTOCOL_VERSIONS[KNOWN_PROTOCOL_VERSIONS.index(version) + 1 :]
+    later: set[str] = set()
+    for revision in newer:
+        row = _methods.SERVER_RESULTS.get((method, revision))
+        if row is not None:
+            later |= _wire_fields(row)
+    return frozenset(later) - _wire_fields(current)
+
+
 def _same_schema(a: dict[str, Any] | None, b: dict[str, Any] | None) -> bool:
     """JSON equality for two output schemas.
 
@@ -558,6 +598,11 @@ async def send_request(
             _methods.validate_server_result(method, version, raw)
         except KeyError:
             pass
+        # Drop a later revision's fields (e.g. 2026-07-28 cache hints on a pre-2026
+        # session): they are outside the negotiated contract, and the version-free
+        # result type would otherwise apply that revision's constraints to them.
+        if not (foreign := _later_revision_fields(method, version)).isdisjoint(raw):
+            raw = {key: value for key, value in raw.items() if key not in foreign}
         if isinstance(result_type, TypeAdapter):
             return result_type.validate_python(raw, by_name=False)
         return result_type.model_validate(raw, by_name=False)

tests/client/test_session.py

@@ -1759,6 +1759,75 @@ async def test_a_boolean_inbound_ttl_is_not_clamped_only_coerced_by_validation(w
     assert result.ttl_ms == int(wire_ttl)
 
 
+_LEGACY_HINTED_RESULTS: list[tuple[str, dict[str, Any]]] = [
+    ("list_tools", {"tools": []}),
+    ("list_prompts", {"prompts": []}),
+    ("list_resources", {"resources": []}),
+    ("list_resource_templates", {"resourceTemplates": []}),
+    ("read_resource", {"contents": []}),
+]
+
+_LEGACY_TAGGED_RESULTS: list[tuple[str, dict[str, Any]]] = [
+    ("call_tool", {"content": []}),
+    ("get_prompt", {"messages": []}),
+]
+
+
+def _legacy_init(version: str) -> dict[str, Any]:
+    return InitializeResult(
+        protocol_version=version,
+        capabilities=ServerCapabilities(),
+        server_info=Implementation(name="mock-server", version="0.1.0"),
+    ).model_dump(by_alias=True, mode="json", exclude_none=True)
+
+
+async def _call_legacy(session: ClientSession, verb: str) -> Any:
+    if verb == "read_resource":
+        return await session.read_resource("mem://x")
+    if verb == "call_tool":
+        return await session.call_tool("t", {})
+    if verb == "get_prompt":
+        return await session.get_prompt("p")
+    return await getattr(session, verb)()
+
+
+@pytest.mark.anyio
+@pytest.mark.parametrize("version", HANDSHAKE_PROTOCOL_VERSIONS)
+@pytest.mark.parametrize(("verb", "body"), _LEGACY_HINTED_RESULTS)
+async def test_cache_hints_from_a_legacy_server_never_reach_the_result(
+    version: str, verb: str, body: dict[str, Any]
+) -> None:
+    """SDK-defined: on any pre-2026 session the caching fields are outside the negotiated
+    schema, so whatever a server puts in them - even values the 2026-07-28 enum
+    rejects - is dropped and the model shows its conservative defaults."""
+    dispatcher = _ScriptedDispatcher(_legacy_init(version), {**body, "ttlMs": -1, "cacheScope": "session"})
+    with anyio.fail_after(5):
+        async with ClientSession(dispatcher=dispatcher) as session:
+            await session.initialize()
+            result = await _call_legacy(session, verb)
+    assert (result.ttl_ms, result.cache_scope) == (0, "private")
+    assert not {"ttl_ms", "cache_scope"} & result.model_fields_set
+
+
+@pytest.mark.anyio
+@pytest.mark.parametrize(("verb", "body"), _LEGACY_TAGGED_RESULTS)
+async def test_a_2026_result_type_tag_from_a_legacy_server_never_reaches_the_result(
+    verb: str, body: dict[str, Any]
+) -> None:
+    """SDK-defined: `resultType` is 2026-07-28 vocabulary that also feeds result-union
+    routing, so a tag on a pre-2026 wire (even one no union arm claims) is dropped and
+    the plain result is returned rather than mis-routing or failing."""
+    # `call_tool` re-lists tools to validate structured content; that answer trails harmlessly for `get_prompt`.
+    dispatcher = _ScriptedDispatcher(
+        _legacy_init(LATEST_HANDSHAKE_VERSION), {**body, "resultType": "task"}, {"tools": []}
+    )
+    with anyio.fail_after(5):
+        async with ClientSession(dispatcher=dispatcher) as session:
+            await session.initialize()
+            result = await _call_legacy(session, verb)
+    assert result.result_type == "complete"
+
+
 @pytest.mark.anyio
 async def test_session_call_tool_returns_input_required_result_when_opted_in() -> None:
     """`ClientSession.call_tool(..., allow_input_required=True)` surfaces the