Merge main into fix/pre-parse-json-optional-str

Author: vientooscuro

.github/ISSUE_TEMPLATE/bug.yaml

@@ -11,13 +11,26 @@ body:
     id: checks
     attributes:
       label: Initial Checks
-      description: Just making sure you're using the latest version of MCP Python SDK.
+      description: >
+        Both the 2.x stable line and the 1.x maintenance line are supported, and only
+        the newest release of each line receives fixes.
       options:
-        - label: I confirm that I'm using the latest version of MCP Python SDK
+        - label: I confirm that I'm using the newest release of my line (the latest 2.x, or the latest 1.x if I'm still on v1)
           required: true
         - label: I confirm that I searched for my issue in https://github.com/modelcontextprotocol/python-sdk/issues before opening this issue
           required: true
 
+  - type: dropdown
+    id: release-line
+    attributes:
+      label: Release line
+      description: Which major version of the SDK are you using?
+      options:
+        - 2.x (current stable)
+        - 1.x (maintenance line, v1.x branch)
+    validations:
+      required: true
+
   - type: textarea
     id: description
     attributes:

.github/ISSUE_TEMPLATE/v2-feedback.yaml

@@ -1,15 +1,15 @@
 name: v2 feedback
 description: Bugs, API friction, or docs gaps in v2 of the SDK
 title: "[v2] "
-labels: ["v2-alpha"]
+labels: ["v2"]
 
 body:
   - type: markdown
     attributes:
       value: |
-        Thanks for trying v2. Anything that broke, surprised you, or slowed you down is useful — API feedback is explicitly welcome while v2 is in pre-release.
+        Anything in v2 that broke, surprised you, or slowed you down is useful, including API friction and docs gaps.
 
-        Docs: https://py.sdk.modelcontextprotocol.io/v2/ · Migration from v1: https://py.sdk.modelcontextprotocol.io/v2/migration/
+        Docs: https://py.sdk.modelcontextprotocol.io/ · Migration from v1: https://py.sdk.modelcontextprotocol.io/migration/
 
   - type: textarea
     id: what

.github/actions/conformance/client.py

@@ -11,16 +11,18 @@
       --spec-version is omitted the harness picks per-scenario (LATEST_SPEC_VERSION
       for active scenarios, DRAFT_PROTOCOL_VERSION for draft-only ones).
     - Server URL as last CLI argument (sys.argv[1])
-    - Must exit 0 within 30 seconds
+    - Must exit 0 within the harness --timeout (CI passes 60s; the default is 30s)
 
 Scenarios:
     initialize                              - Connect, initialize, list tools, close
     tools_call                              - Connect, call add_numbers(a=5, b=3), close
     sse-retry                               - Connect, call test_reconnection, close
     json-schema-ref-no-deref                - Connect, list tools (no $ref deref)
+    json-schema-2020-12-preservation        - List tools, echo the focal inputSchema back verbatim
     request-metadata                        - Connect with all callbacks; client stamps _meta
-    http-standard-headers                   - Connect, call a tool (Mcp-* headers checked)
+    http-standard-headers                   - Tool, resource and prompt round-trips (Mcp-* headers checked)
     http-invalid-tool-headers               - List tools, call every surfaced tool (x-mcp-header filter)
+    http-custom-headers                     - Replay the harness's toolCalls (x-mcp-header -> Mcp-Param-*)
     elicitation-sep1034-client-defaults     - Elicitation with default accept callback
     sep-2322-client-request-state           - Drive the MRTR auto-loop (SEP-2322)
     auth/client-credentials-jwt             - Client credentials with private_key_jwt
@@ -38,7 +40,7 @@
 from typing import Any, cast
 from urllib.parse import parse_qs, urlparse
 
-import httpx
+import httpx2
 import mcp_types as types
 from mcp_types.version import MODERN_PROTOCOL_VERSIONS
 from pydantic import AnyUrl
@@ -151,7 +153,7 @@ async def handle_redirect(self, authorization_url: str) -> None:
         """Fetch the authorization URL and extract the auth code from the redirect."""
         logger.debug(f"Fetching authorization URL: {authorization_url}")
 
-        async with httpx.AsyncClient() as client:
+        async with httpx2.AsyncClient() as client:
             response = await client.get(
                 authorization_url,
                 follow_redirects=False,
@@ -252,6 +254,21 @@ async def run_json_schema_ref_no_deref(server_url: str) -> None:
         await client.list_tools()
 
 
+@register("json-schema-2020-12-preservation")
+async def run_json_schema_2020_12_preservation(server_url: str) -> None:
+    """List tools, then echo the focal tool's inputSchema back verbatim (SEP-1613 / SEP-2106).
+
+    The harness diffs what the client round-trips through `json_schema_echo` against its
+    fixture to detect 2020-12 keywords ($schema, $defs, $anchor, additionalProperties,
+    allOf/anyOf, if/then/else) being stripped while parsing tools/list. Unlike
+    json-schema-ref-no-deref, this mock is version-aware, so client_mode() applies.
+    """
+    async with Client(server_url, mode=client_mode()) as client:
+        listed = await client.list_tools()
+        focal = next(tool for tool in listed.tools if tool.name == "json_schema_2020_12_tool")
+        await client.call_tool("json_schema_echo", {"schema": focal.input_schema})
+
+
 @register("tools_call")
 async def run_tools_call(server_url: str) -> None:
     """Connect, list tools, call add_numbers(a=5, b=3), close."""
@@ -294,11 +311,24 @@ async def run_request_metadata(server_url: str) -> None:
 
 @register("http-standard-headers")
 async def run_http_standard_headers(server_url: str) -> None:
-    """Connect on the modern path so Mcp-Method / Mcp-Name / MCP-Protocol-Version are sent (SEP-2243)."""
+    """Touch tools, resources and prompts on the modern path so each standard header is checked (SEP-2243).
+
+    The scenario inspects Mcp-Method on each request and Mcp-Name on tools/call,
+    resources/read and prompts/get, and reports methods the client never sent as
+    SKIPPED rather than failed, so exercise one of each. initialize and
+    notifications/initialized stay SKIPPED: the modern path discovers via
+    server/discover and never sends them.
+    """
     async with Client(server_url, mode=client_mode()) as client:
-        await client.list_tools()
-        result = await client.call_tool("add_numbers", {"a": 5, "b": 3})
-        logger.debug(f"add_numbers result: {result}")
+        tools = await client.list_tools()
+        if tools.tools:
+            await client.call_tool(tools.tools[0].name, _stub_required_args(tools.tools[0].input_schema))
+        resources = await client.list_resources()
+        if resources.resources:
+            await client.read_resource(resources.resources[0].uri)
+        prompts = await client.list_prompts()
+        if prompts.prompts:
+            await client.get_prompt(prompts.prompts[0].name)
 
 
 def _stub_required_args(input_schema: dict[str, Any]) -> dict[str, Any]:
@@ -486,13 +516,13 @@ async def run_enterprise_managed_authorization(server_url: str) -> None:
     # learn it from the harness's PRM document (RFC 9728); production
     # deployments would supply it as static configuration instead.
     prm_url = build_protected_resource_metadata_discovery_urls(None, server_url)[0]
-    async with httpx.AsyncClient(timeout=30.0) as http:
+    async with httpx2.AsyncClient(timeout=30.0) as http:
         prm = (await http.get(prm_url)).raise_for_status().json()
     as_issuer = prm["authorization_servers"][0]
 
     async def fetch_id_jag(audience: str, resource: str) -> str:
         """Leg 1 - RFC 8693 token-exchange at the enterprise IdP."""
-        async with httpx.AsyncClient(timeout=30.0) as http:
+        async with httpx2.AsyncClient(timeout=30.0) as http:
             resp = await http.post(
                 idp_token_endpoint,
                 data={
@@ -563,9 +593,9 @@ async def run_auth_code_client(server_url: str) -> None:
     await _run_auth_session(server_url, oauth_auth)
 
 
-async def _run_auth_session(server_url: str, oauth_auth: httpx.Auth) -> None:
+async def _run_auth_session(server_url: str, oauth_auth: httpx2.Auth) -> None:
     """Common session logic for all OAuth flows."""
-    http_client = httpx.AsyncClient(auth=oauth_auth, timeout=30.0)
+    http_client = httpx2.AsyncClient(auth=oauth_auth, timeout=30.0)
     transport = streamable_http_client(url=server_url, http_client=http_client)
     async with Client(transport, mode=client_mode(), elicitation_callback=default_elicitation_callback) as client:
         logger.debug("Initialized successfully")

.github/actions/conformance/expected-failures.2025-11-25.yml

@@ -0,0 +1,26 @@
+# Expected failures at the 2025-11-25 wire, read by the `--suite all
+# --spec-version 2025-11-25` server and client legs: every scenario the pinned
+# harness marks applicable at 2025-11-25, run over the stateful handshake.
+#
+# That selection is a superset of the frozen 2025-11-25 requirement set (`npx
+# $CONFORMANCE_PKG list --requirements 2025-11-25`), so an entry here for a
+# scenario in that set means `conformance tier-check` scores the SDK below 100%
+# for 2025-11-25 even though CI is green; link the tracking issue next to any
+# such entry.
+#
+# Kept separate from expected-failures.yml even though the bare `--suite all`
+# legs currently run these same scenarios at 2025-11-25 too: the harness's
+# default wire is due to move (modelcontextprotocol/conformance#426) and this
+# file must keep meaning 2025-11-25. Until then a failure here also needs an
+# entry there. The file is passed even while empty: run-client.sh keys its solo
+# re-verification off the harness's baseline output.
+#
+# Baseline established against the harness pinned via CONFORMANCE_PKG in
+# .github/workflows/conformance.yml. New conformance releases are adopted by
+# deliberately bumping that pin and reconciling all three expected-failures
+# files in the same change. Entries MUST be removed as they start passing (the
+# runner fails on stale entries).
+
+client: []
+
+server: []

.github/actions/conformance/expected-failures.2026-07-28.yml

@@ -1,19 +1,23 @@
-# Expected failures for the carried-forward 2026-07-28 legs
-# (`--suite all --spec-version 2026-07-28` for both server and client).
+# Expected failures at the 2026-07-28 wire, read by the `--suite all
+# --spec-version 2026-07-28` server and client legs: every scenario the pinned
+# harness marks applicable at 2026-07-28, run stateless with per-request _meta.
+#
+# That selection is a superset of the frozen 2026-07-28 requirement set (`npx
+# $CONFORMANCE_PKG list --requirements 2026-07-28`), so an entry here for a
+# scenario in that set means `conformance tier-check` scores the SDK below 100%
+# for 2026-07-28 even though CI is green; link the tracking issue next to any
+# such entry.
 #
 # This baseline is separate from expected-failures.yml because entries are
-# keyed by scenario name only: a scenario that passes at its default version
-# in the 2025 legs but fails when forced to 2026-07-28 (or vice versa) cannot
-# be expressed in a shared file (the passing leg would flag the entry as
-# stale). Like expected-failures.yml, this single file covers both
-# directions: the client 2026 leg reads the `client:` section and the server
-# 2026 leg reads the `server:` section. Both burn down independently of the
-# 2025 legs.
+# keyed by scenario name only: a scenario that passes at the harness default
+# wire in the bare `--suite all` legs but fails when forced to 2026-07-28 (or
+# vice versa) cannot be expressed in a shared file. Where the bare legs already
+# default a scenario to 2026-07-28, a failure here also needs an entry there.
 #
 # Baseline established against the harness pinned via CONFORMANCE_PKG in
 # .github/workflows/conformance.yml. New conformance releases are adopted by
-# deliberately bumping that pin and reconciling both this file and
-# expected-failures.yml in the same change.
+# deliberately bumping that pin and reconciling all three expected-failures
+# files in the same change.
 #
 # Entries are grouped by what unblocks them. As each gap closes the
 # corresponding scenarios start passing and MUST be removed from this list

.github/actions/conformance/expected-failures.yml

@@ -1,23 +1,44 @@
-# Conformance scenarios not yet passing against the Python SDK on main.
-# CI exits 0 if only these fail, exits 1 on unexpected failures or stale entries.
+# Conformance scenarios not yet passing against the Python SDK on main, read by
+# the bare `--suite all` server and client legs (every scenario shipped with the
+# pinned harness, each at the harness's default wire for it). CI exits 0 if only
+# these fail, exits 1 on unexpected failures or stale entries.
+#
+# The wire-pinned legs read expected-failures.2025-11-25.yml and
+# expected-failures.2026-07-28.yml instead; see the header of
+# .github/workflows/conformance.yml for the leg layout.
 #
 # Baseline established against the harness pinned via CONFORMANCE_PKG in
 # .github/workflows/conformance.yml. New conformance releases are adopted by
-# deliberately bumping that pin and reconciling both this file and
-# expected-failures.2026-07-28.yml in the same change.
+# deliberately bumping that pin and reconciling all three expected-failures
+# files in the same change.
 #
 # Entries are grouped by SEP. As each SEP lands in the SDK the corresponding
 # scenarios start passing and MUST be removed from this list (the runner fails
 # on stale entries), so the baseline burns down per milestone.
 
-client: []
+client:
+  # SEP-1932 (DPoP): the SDK's OAuth client does not implement DPoP proofs.
+  # The entries are per-check (conformance #406) because both scenarios
+  # pass their non-DPoP checks (discovery, token acquisition, request
+  # flow) live.
+  - auth/dpop:sep-1932-client-token-request-proof
+  - auth/dpop:sep-1932-client-dpop-auth-scheme
+  - auth/dpop:sep-1932-client-fresh-proof
+  - auth/dpop-nonce:sep-1932-client-token-request-proof
+  - auth/dpop-nonce:sep-1932-client-dpop-auth-scheme
+  - auth/dpop-nonce:sep-1932-client-fresh-proof
+  - auth/dpop-nonce:sep-1932-client-as-nonce
+  - auth/dpop-nonce:sep-1932-client-rs-nonce
+  # Workload identity federation: the OAuth client does not implement the
+  # urn:ietf:params:oauth:grant-type:jwt-bearer grant (it answers with
+  # authorization_code). Per-check for the same reason.
+  - auth/wif-jwt-bearer:wif-grant-type
 
 server:
   # SEP-2663 (io.modelcontextprotocol/tasks): the SDK does not implement the
-  # tasks extension yet. These extension-tagged scenarios are selected only by
-  # the bare `--suite all` leg — extension scenarios never match a
-  # --spec-version filter and the active/draft suites exclude them — so these
-  # entries are inert for the other legs that read this file.
+  # tasks extension yet. The bare `--suite all` leg is the only one that
+  # reaches these extension-tagged scenarios (they never match a
+  # --spec-version filter), so these entries live here only.
   #
   # `tasks-status-notifications` is intentionally NOT listed: the harness
   # skips it unconditionally (pending its rewrite against subscriptions/

.github/actions/conformance/run-client.sh

@@ -1,6 +1,6 @@
 #!/bin/bash
 # Run a client conformance suite, re-verifying unexpected failures solo.
-# Concurrent suite runs on a 2-vCPU runner can push scenarios with real-time
+# Concurrent suite runs on a hosted runner can push scenarios with real-time
 # waits past tolerance; solo, a real failure fails again while a contention
 # artifact passes. Failures that only reproduce under concurrency are excused.
 set -uo pipefail
@@ -101,4 +101,8 @@ if [ -n "$output_dir" ]; then
     printf '%s\n' "${scenarios[@]}" > "$output_dir/FLAKE_RESCUED"
 fi
 echo "All ${#scenarios[@]} unexpected failure(s) passed when re-run solo; the suite failures were parallel-run contention."
+# Surface the rescue on the run summary; the log line above and the
+# FLAKE_RESCUED marker in the uploaded results are otherwise easy to miss on a
+# green run.
+echo "::warning title=Conformance flake rescued::${scenarios[*]} failed under suite concurrency and passed solo${output_dir:+ (see ${output_dir}-solo and FLAKE_RESCUED in the uploaded results)}."
 exit 0

.github/dependabot.yml

@@ -10,6 +10,10 @@ updates:
       python-packages:
         patterns:
           - "*"
+      python-security:
+        applies-to: security-updates
+        patterns:
+          - "*"
   - package-ecosystem: "github-actions"
     directory: "/"
     schedule:

.github/pull_request_template.md

@@ -0,0 +1,38 @@
+<!--
+Pull requests from outside the maintainer team need to link an open issue that
+a maintainer has assigned to you (or one labeled `help wanted`); others are
+closed automatically until that's in place. See CONTRIBUTING.md for details.
+-->
+
+Fixes #
+
+<!-- Provide a brief summary of your changes -->
+
+## Motivation and Context
+<!-- Why is this change needed? What problem does it solve? -->
+
+## How Has This Been Tested?
+<!-- Have you tested this in a real application? Which scenarios were tested? -->
+
+## Breaking Changes
+<!-- Will users need to update their code or configurations? -->
+
+## Types of changes
+<!-- What types of changes does your code introduce? Put an `x` in all the boxes that apply: -->
+- [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change (fix or feature that would cause existing functionality to change)
+- [ ] Documentation update
+
+## Checklist
+<!-- Go over all the following points, and put an `x` in all the boxes that apply. -->
+- [ ] I am assigned to the linked issue (or it is labeled `help wanted`, or I'm a maintainer)
+- [ ] I have disclosed any AI assistance and can explain the change in my own words
+- [ ] I have read the [MCP Documentation](https://modelcontextprotocol.io)
+- [ ] My code follows the repository's style guidelines
+- [ ] New and existing tests pass locally
+- [ ] I have added appropriate error handling
+- [ ] I have added or updated documentation as needed
+
+## Additional context
+<!-- Add any other context, implementation notes, or design decisions -->