adcontextprotocol
diff --git a/‎src/adcp/server/mcp_tools.py‎
Lines changed: 51 additions & 3 deletions b/‎src/adcp/server/mcp_tools.py‎
Lines changed: 51 additions & 3 deletions
diff --git a/‎src/adcp/validation/envelope.py‎
Lines changed: 102 additions & 0 deletions b/‎src/adcp/validation/envelope.py‎
Lines changed: 102 additions & 0 deletions
@@ -21,6 +21,7 @@
 import copy
 import difflib
 import logging
+import os
 from collections.abc import Callable, Iterable
 from typing import Any
 
@@ -1945,6 +1946,7 @@ def create_tool_caller(
     from adcp.exceptions import ADCPTaskError
     from adcp.server.helpers import inject_context
     from adcp.types import Error
+    from adcp.validation.envelope import UnsupportedVersionError, detect_wire_version
     from adcp.validation.schema_errors import build_adcp_validation_error_payload
     from adcp.validation.schema_validator import (
         format_issues,
@@ -1980,8 +1982,52 @@ async def call_tool(params: dict[str, Any], context: ToolContext | None = None)
                     ],
                 ) from exc
 
+        # Wire-version detection: read ``adcp_version`` / ``adcp_major_version``
+        # off the post-hook params (legacy buyers may rely on a hook to
+        # populate the envelope, so this runs after pre_validation_hook).
+        # ``None`` means the buyer didn't claim a version — fall through
+        # to the SDK pin via ``version=None`` on the validator.
+        #
+        # Strictness gate: setting ``ADCP_STRICT_VERSION_ENVELOPE=1``
+        # raises ``VERSION_UNSUPPORTED`` for unsupported claims (the
+        # spec-prescribed behaviour). The default (off) logs a warning
+        # and falls through to SDK-pin validation — adopters with test
+        # fixtures using placeholder version values (``adcp_major_version=4``
+        # was a common sentinel before this gate existed) keep working
+        # while they migrate. Strict will become the default in 5.3.
+        try:
+            wire_version = detect_wire_version(params)
+        except UnsupportedVersionError as exc:
+            if os.environ.get("ADCP_STRICT_VERSION_ENVELOPE", "0") == "1":
+                raise ADCPTaskError(
+                    operation=method_name,
+                    errors=[
+                        Error(
+                            code="VERSION_UNSUPPORTED",
+                            message=str(exc),
+                            # Preserve the wire field's original type so
+                            # buyer telemetry sees the same shape they
+                            # sent (int for ``adcp_major_version``, str
+                            # for ``adcp_version``).
+                            details={
+                                "claimed_version": exc.wire_value,
+                                "supported_versions": list(exc.supported),
+                            },
+                        )
+                    ],
+                ) from exc
+            logger.warning(
+                "Wire-version envelope rejected by detect_wire_version (%s); "
+                "falling through to SDK-pin validation. "
+                "Set ADCP_STRICT_VERSION_ENVELOPE=1 to raise "
+                "VERSION_UNSUPPORTED instead. Strict will become the default "
+                "in 5.3.",
+                exc,
+            )
+            wire_version = None
+
         if request_mode is not None and request_mode != "off":
-            outcome = validate_request(method_name, params)
+            outcome = validate_request(method_name, params, version=wire_version)
             if not outcome.valid:
                 summary = format_issues(outcome.issues)
                 if request_mode == "strict":
@@ -2076,7 +2122,7 @@ async def call_tool(params: dict[str, Any], context: ToolContext | None = None)
             # per-tool response schema would false-positive on it and
             # convert a real protocol error into a fake VALIDATION_ERROR.
             if "adcp_error" not in result:
-                outcome = validate_response(method_name, result)
+                outcome = validate_response(method_name, result, version=wire_version)
                 if not outcome.valid:
                     summary = format_issues(outcome.issues)
                     logger.warning(
@@ -2109,7 +2155,9 @@ def __init__(
         *,
         advertise_all: bool = False,
         validation: ValidationHookConfig | None = None,
-        pre_validation_hooks: dict[str, Callable[[str, dict[str, Any]], dict[str, Any]]] | None = None,
+        pre_validation_hooks: (
+            dict[str, Callable[[str, dict[str, Any]], dict[str, Any]]] | None
+        ) = None,
     ):
         """Create tool set from handler.
 
 
@@ -0,0 +1,102 @@
+"""Wire-version detection for inbound AdCP requests.
+
+Per the AdCP version-envelope contract (``core/version-envelope.json``),
+every request carries either:
+
+* ``adcp_version`` — release-precision string (``"3.0"``, ``"3.1"``,
+  ``"3.1-beta"``). Added in 3.1+; takes precedence when present.
+* ``adcp_major_version`` — integer (``2``, ``3``). The pre-3.1 wire shape
+  and the lowest common denominator for buyers that don't yet emit the
+  release-precision field.
+
+:func:`detect_wire_version` collapses both shapes to a release-precision
+string the loader can pass to :func:`adcp.validation.schema_loader.get_validator`
+as ``version=``. A buyer claiming an unsupported version raises a
+:class:`UnsupportedVersionError`, which the dispatcher converts to an
+``AdcpError`` with code ``VERSION_UNSUPPORTED`` per the spec.
+
+Mirrors the JS SDK's ``applyVersionEnvelope`` in
+``src/lib/protocols/index.ts``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from adcp._version import COMPATIBLE_ADCP_VERSIONS, normalize_to_release_precision
+
+
+class UnsupportedVersionError(ValueError):
+    """The wire version the buyer claims isn't supported by this server.
+
+    Carries the original wire value plus the supported list so the
+    dispatcher can echo both into ``VERSION_UNSUPPORTED`` error details.
+    """
+
+    def __init__(self, wire_value: str | int, supported: tuple[str, ...]) -> None:
+        self.wire_value = wire_value
+        self.supported = supported
+        super().__init__(
+            f"AdCP version {wire_value!r} is not supported by this server "
+            f"(supported release-precision versions: {list(supported)})."
+        )
+
+
+def detect_wire_version(
+    payload: Any,
+    *,
+    supported: tuple[str, ...] = COMPATIBLE_ADCP_VERSIONS,
+) -> str | None:
+    """Return the release-precision version a request claims, or ``None``.
+
+    Resolution order:
+
+    1. ``payload['adcp_version']`` — string, normalized to release
+       precision (``"3.0.7"`` → ``"3.0"``). Must be in ``supported`` or
+       raises :class:`UnsupportedVersionError`.
+    2. ``payload['adcp_major_version']`` — int. Maps to the highest minor
+       in ``supported`` for that major. No supported minor for the major
+       raises :class:`UnsupportedVersionError`.
+    3. Neither field set — returns ``None`` so the caller falls back to
+       the SDK's compile-time pin.
+
+    Non-dict payloads return ``None`` (validation skipped — the schema
+    layer rejects non-dict requests via its own type check).
+    """
+    if not isinstance(payload, dict):
+        return None
+
+    explicit = payload.get("adcp_version")
+    if isinstance(explicit, str) and explicit:
+        try:
+            normalized = normalize_to_release_precision(explicit)
+        except ValueError as exc:
+            raise UnsupportedVersionError(explicit, supported) from exc
+        if normalized not in supported:
+            raise UnsupportedVersionError(explicit, supported)
+        return normalized
+    # Empty-string ``adcp_version`` falls through to ``adcp_major_version``
+    # intentionally — pre-3.1 buyers may set both fields, and an empty
+    # string from a half-migrated client shouldn't override the int field.
+
+    major_value = payload.get("adcp_major_version")
+    # Wire field is strictly an int per spec (``minimum:1, maximum:99``).
+    # Two type-coercion cases that would otherwise bypass the supported-set
+    # check silently — reject loudly instead:
+    # * ``bool`` is an ``int`` subclass; ``True``/``False`` would map to
+    #   major=1/0.
+    # * String ints (``"3"``) from a buyer that JSON-stringified the field —
+    #   ``isinstance(x, int)`` returns False, so without an explicit check
+    #   the buyer would silently get SDK-pin validation instead of an error.
+    if isinstance(major_value, str):
+        raise UnsupportedVersionError(major_value, supported)
+    if isinstance(major_value, int) and not isinstance(major_value, bool):
+        if major_value < 1:
+            raise UnsupportedVersionError(major_value, supported)
+        candidates = [v for v in supported if v.startswith(f"{major_value}.")]
+        if not candidates:
+            raise UnsupportedVersionError(major_value, supported)
+        # Highest supported minor for this major.
+        return max(candidates, key=lambda v: int(v.split(".")[1].split("-")[0]))
+
+    return None