Merge remote-tracking branch 'origin/main' into resolver-dependency-injection

Author: maxisbey

.github/actions/conformance/client.py

@@ -22,9 +22,10 @@
     http-standard-headers                   - Connect, call a tool (Mcp-* headers checked)
     http-invalid-tool-headers               - List tools, call every surfaced tool (x-mcp-header filter)
     elicitation-sep1034-client-defaults     - Elicitation with default accept callback
-    sep-2322-client-request-state           - Drive the manual MRTR retry surface
+    sep-2322-client-request-state           - Drive the MRTR auto-loop (SEP-2322)
     auth/client-credentials-jwt             - Client credentials with private_key_jwt
     auth/client-credentials-basic           - Client credentials with client_secret_basic
+    auth/enterprise-managed-authorization   - SEP-990 ID-JAG (RFC 8693 + RFC 7523 jwt-bearer)
     auth/*                                  - Authorization code flow (default for auth scenarios)
 """
 
@@ -48,6 +49,8 @@
     PrivateKeyJWTOAuthProvider,
     SignedJWTParameters,
 )
+from mcp.client.auth.extensions.identity_assertion import IdentityAssertionOAuthProvider
+from mcp.client.auth.utils import build_protected_resource_metadata_discovery_urls
 from mcp.client.client import Client
 from mcp.client.context import ClientRequestContext
 from mcp.client.streamable_http import streamable_http_client
@@ -374,46 +377,28 @@ async def run_elicitation_defaults(server_url: str) -> None:
 
 @register("sep-2322-client-request-state")
 async def run_mrtr_client(server_url: str) -> None:
-    """Drive the manual MRTR retry surface against the SEP-2322 client mock.
-
-    The mock speaks the modern lifecycle (server/discover, no initialize) and
-    inspects the wire params of each tools/call round, so this exercises the
-    explicit allow_input_required=True path rather than an auto-loop: round 1
-    receives an InputRequiredResult, the fixture fulfils the elicitation
-    locally, then round 2 retries with input_responses + the echoed
-    request_state. Passing request_state straight off the typed result -- a
-    str when the server sent one, None when it didn't -- lets the
-    serializer's exclude_none drop the key in the no-state case without a
-    branch here. The unrelated call between rounds proves MRTR params don't
-    leak across tools, and the no-result-type call must parse as a complete
-    CallToolResult with no retry.
+    """Drive the SEP-2322 client mock through `Client.call_tool`'s auto-loop.
+
+    The mock inspects raw `tools/call` params, so registering an
+    `elicitation_callback` and letting the driver run is enough to satisfy
+    all five wire-shape checks: the driver echoes `request_state` byte-exact
+    and omits it when the server sent none, every retry mints a fresh
+    JSON-RPC id, the unrelated call between auto-loops carries no MRTR
+    params, and the no-`resultType` response parses as a terminal
+    `CallToolResult` so the driver never retries it.
     """
-    async with Client(server_url, mode=client_mode()) as client:
-        await client.list_tools()
-        confirm = {"confirm": types.ElicitResult(action="accept", content={"confirmed": True})}
 
-        r1 = await client.call_tool("test_mrtr_echo_state", {}, allow_input_required=True)
-        assert isinstance(r1, types.InputRequiredResult)
-
-        await client.call_tool("test_mrtr_unrelated", {})
+    async def confirm(
+        context: ClientRequestContext, params: types.ElicitRequestParams
+    ) -> types.ElicitResult | types.ErrorData:
+        return types.ElicitResult(action="accept", content={"confirmed": True})
 
-        await client.call_tool(
-            "test_mrtr_echo_state",
-            {},
-            input_responses=confirm,
-            request_state=r1.request_state,
-            allow_input_required=True,
-        )
+    async with Client(server_url, mode=client_mode(), elicitation_callback=confirm) as client:
+        await client.list_tools()
 
-        r2 = await client.call_tool("test_mrtr_no_state", {}, allow_input_required=True)
-        assert isinstance(r2, types.InputRequiredResult)
-        await client.call_tool(
-            "test_mrtr_no_state",
-            {},
-            input_responses=confirm,
-            request_state=r2.request_state,
-            allow_input_required=True,
-        )
+        await client.call_tool("test_mrtr_echo_state", {})
+        await client.call_tool("test_mrtr_unrelated", {})
+        await client.call_tool("test_mrtr_no_state", {})
 
         result = await client.call_tool("test_mrtr_no_result_type", {})
         assert isinstance(result, types.CallToolResult)
@@ -472,6 +457,70 @@ async def run_client_credentials_basic(server_url: str) -> None:
     await _run_auth_session(server_url, oauth_auth)
 
 
+@register("auth/enterprise-managed-authorization")
+async def run_enterprise_managed_authorization(server_url: str) -> None:
+    """SEP-990 enterprise-managed authorization: RFC 8693 token-exchange at the
+    enterprise IdP for an ID-JAG, then RFC 7523 jwt-bearer at the MCP
+    authorization server."""
+    context = get_conformance_context()
+    client_id = context.get("client_id")
+    client_secret = context.get("client_secret")
+    idp_client_id = context.get("idp_client_id")
+    idp_id_token = context.get("idp_id_token")
+    idp_token_endpoint = context.get("idp_token_endpoint")
+
+    if not client_id:
+        raise RuntimeError("MCP_CONFORMANCE_CONTEXT missing 'client_id'")
+    if not client_secret:
+        raise RuntimeError("MCP_CONFORMANCE_CONTEXT missing 'client_secret'")
+    if not idp_client_id:
+        raise RuntimeError("MCP_CONFORMANCE_CONTEXT missing 'idp_client_id'")
+    if not idp_id_token:
+        raise RuntimeError("MCP_CONFORMANCE_CONTEXT missing 'idp_id_token'")
+    if not idp_token_endpoint:
+        raise RuntimeError("MCP_CONFORMANCE_CONTEXT missing 'idp_token_endpoint'")
+
+    # IdentityAssertionOAuthProvider takes the AS issuer as configuration (the
+    # SEP-990 trust model: the resource server is never asked which AS to use).
+    # The harness does not put the issuer in context, so for conformance we
+    # 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:
+        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:
+            resp = await http.post(
+                idp_token_endpoint,
+                data={
+                    "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
+                    "requested_token_type": "urn:ietf:params:oauth:token-type:id-jag",
+                    "subject_token": idp_id_token,
+                    "subject_token_type": "urn:ietf:params:oauth:token-type:id_token",
+                    "audience": audience,
+                    "resource": resource,
+                    "client_id": idp_client_id,
+                },
+            )
+            resp.raise_for_status()
+            return resp.json()["access_token"]
+
+    oauth_auth = IdentityAssertionOAuthProvider(
+        server_url=server_url,
+        storage=InMemoryTokenStorage(),
+        client_id=client_id,
+        client_secret=client_secret,
+        issuer=as_issuer,
+        assertion_provider=fetch_id_jag,
+        token_endpoint_auth_method="client_secret_basic",
+    )
+
+    await _run_auth_session(server_url, oauth_auth)
+
+
 async def run_auth_code_client(server_url: str) -> None:
     """Authorization code flow (default for auth/* scenarios)."""
     callback_handler = ConformanceOAuthCallbackHandler()
@@ -514,7 +563,7 @@ 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: OAuthClientProvider) -> None:
+async def _run_auth_session(server_url: str, oauth_auth: httpx.Auth) -> None:
     """Common session logic for all OAuth flows."""
     http_client = httpx.AsyncClient(auth=oauth_auth, timeout=30.0)
     transport = streamable_http_client(url=server_url, http_client=http_client)

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

@@ -20,18 +20,9 @@
 # (the runner fails on stale entries), so the baseline burns down per
 # milestone.
 
-client:
-  []
-  # auth/enterprise-managed-authorization (SEP-990) is in the 2025 baseline but
-  # NOT here: the harness skips it as inapplicable at --spec-version 2026-07-28
-  # (it is an extension scenario not carried into the 2026 wire), so it is
-  # neither run nor evaluated on this leg.
+client: []
 
 server:
-  # The stateless 2026 path now reaches handlers for plain request/response
-  # scenarios; tools-call-with-progress still fails because the stateless
-  # server has no channel for server→client progress notifications.
-  - tools-call-with-progress
   # SEP-2322 (multi-round-trip requests / IncompleteResult): the prompt pipeline
   # cannot return InputRequiredResult from MCPServer yet (tools/call can).
   - input-required-result-non-tool-request

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

@@ -10,11 +10,7 @@
 # scenarios start passing and MUST be removed from this list (the runner fails
 # on stale entries), so the baseline burns down per milestone.
 
-client:
-  # --- Pre-existing scenarios that fail on checks added after conformance 0.1.15 ---
-  # SEP-990 (enterprise-managed authorization extension): no fixture handler /
-  # client support for the token-exchange + JWT bearer flow.
-  - auth/enterprise-managed-authorization
+client: []
 
 server:
   # --- Draft-spec scenarios (in `--suite draft`; the `active` suite is green) ---

docs/advanced/apps.md

@@ -0,0 +1,160 @@
+# MCP Apps
+
+An **MCP App** is a tool with a face: alongside its data, the tool points at an HTML
+document the host renders as an interactive surface.
+
+Two parts, always two parts:
+
+1. **A tool** that does the work and returns data, like any other tool.
+2. **A `ui://` resource** containing the HTML the host shows for it.
+
+The tool carries a `_meta.ui.resourceUri` reference to the resource. The host fetches
+it with `resources/read`, renders it in a **sandboxed iframe**, and pushes the tool's
+result into that iframe via `postMessage`. Your server never sends or receives any
+`ui/*` messages: that traffic is between the host and the iframe. You serve a tool
+and an HTML document; the host does the theater.
+
+The SDK ships this as the built-in `Apps` extension (`io.modelcontextprotocol/ui`).
+If [Extensions](extensions.md) are new to you, skim that page first. One minute,
+then come back.
+
+## A clock with a face
+
+```python title="server.py" hl_lines="18 21 29 31"
+--8<-- "docs_src/apps/tutorial001.py"
+```
+
+Four moves:
+
+* `Apps()`: one instance holds your UI-bound tools and their resources.
+* `@apps.tool(resource_uri="ui://clock/app.html")`: a regular tool, plus the
+  `_meta.ui.resourceUri` stamp. Everything `@mcp.tool()` accepts (name, title,
+  description, ...) passes through.
+* `apps.add_html_resource("ui://clock/app.html", CLOCK_HTML)`: the matching
+  resource, served as `text/html;profile=mcp-app`. That exact MIME type is what
+  tells a host "this is an app, render it".
+* `MCPServer("clock", extensions=[apps])`: opt in. The server now advertises
+  `io.modelcontextprotocol/ui` under `capabilities.extensions`.
+
+The HTML itself listens for the host's `postMessage` and shows the result. For real
+apps, use the official [`@modelcontextprotocol/ext-apps`](https://github.com/modelcontextprotocol/ext-apps)
+browser SDK inside your HTML. It gives you `ontoolresult`, `callServerTool`,
+`getHostContext`, and `onhostcontextchanged` instead of raw message events.
+
+## Graceful degradation
+
+Not every client renders apps. The spec is blunt about what that means for you:
+
+> Tools **MUST** return a meaningful `content` array even when UI is available.
+
+The model reads `content`; the iframe is for humans. A UI-capable host still feeds
+the text result to the model, and a text-only client gets *only* that. So the
+canonical pattern is one tool, two answers. Look at `get_time` again:
+
+```python title="server.py" hl_lines="22-26"
+--8<-- "docs_src/apps/tutorial001.py"
+```
+
+`client_supports_apps(ctx)` is `True` only when the client declared the
+`io.modelcontextprotocol/ui` extension **and** listed `text/html;profile=mcp-app`
+in its `mimeTypes` settings. The field is required, so a client that omits it
+does not count. That is exactly what `main()` in the same file declares: the
+client half of the negotiation, and the rich answer comes back.
+
+!!! warning
+    Never return a placeholder like `"[Rendered UI]"` as the only content. If the
+    fallback text is useless, the tool is useless to every text-only client and to
+    the model itself. Write the sentence.
+
+## Locking the iframe down
+
+The resource side carries the security metadata: what the iframe may load, which
+browser permissions it wants, how it would like to be framed:
+
+```python title="server.py" hl_lines="9 19-22"
+--8<-- "docs_src/apps/tutorial002.py"
+```
+
+`csp` and `permissions` are **requests to the host**, not server behaviour. The host
+builds the iframe's Content-Security-Policy and Permissions-Policy from them, and it
+may refuse. Feature-detect in your JS rather than assuming a grant.
+
+`ResourceCsp`, field by field (Python name, wire key, what the host does with it):
+
+| Python | Wire (`_meta.ui.csp`) | Controls |
+|---|---|---|
+| `connect_domains` | `connectDomains` | `connect-src`: where `fetch`/XHR may go |
+| `resource_domains` | `resourceDomains` | `img-src`, `style-src`, ...: static assets |
+| `frame_domains` | `frameDomains` | `frame-src`: nested iframes |
+| `base_uri_domains` | `baseUriDomains` | `base-uri`: what `<base>` may point at |
+
+`ResourcePermissions`: each field requests a browser permission for the iframe.
+
+| Python | Wire (`_meta.ui.permissions`) |
+|---|---|
+| `camera` | `camera` |
+| `microphone` | `microphone` |
+| `geolocation` | `geolocation` |
+| `clipboard_write` | `clipboardWrite` |
+
+!!! note
+    CSP and permissions live on the **resource**, never on the tool. The spec's tool
+    metadata has no slot for them, and hosts ignore them there. The SDK makes the
+    mistake unrepresentable: `@apps.tool()` simply has no `csp` parameter.
+
+### Visibility
+
+`visibility=["app"]` on a tool says "this exists for the iframe, not the model":
+
+* `"model"`: the model may call it.
+* `"app"`: the iframe may call it (via `callServerTool`).
+* Omitted: both, which is the default.
+
+Filtering is the **host's** job. Your server lists app-only tools in `tools/list`
+like any other; the host hides them from the model. Don't filter server-side.
+
+## The rules the SDK enforces
+
+All of these fail at startup, not in production:
+
+* A `resource_uri` or resource URI that isn't `ui://...` is a `ValueError` at
+  decoration/registration time.
+* A tool bound to a URI with **no matching registered resource** is a `ValueError`
+  when `MCPServer(extensions=[apps])` consumes the extension. A tool advertising
+  HTML that 404s on `resources/read` is a misconfiguration, so it refuses to
+  construct.
+* `meta={"ui": ...}` on `@apps.tool()` is a `ValueError`. The decorator owns
+  `_meta["ui"]`; say it with `resource_uri=` and `visibility=`. Other `meta=` keys
+  merge fine alongside.
+
+Neither the TypeScript ext-apps SDK nor FastMCP catches any of these today; we'd
+rather you find out before a host does.
+
+## Beyond inline HTML
+
+`add_html_resource` covers the common case: a string of HTML. For anything else,
+HTML on disk or generated content, build the resource yourself and hand it over:
+
+```python title="server.py" hl_lines="12 18"
+--8<-- "docs_src/apps/tutorial003.py"
+```
+
+`add_resource` fills in the `text/html;profile=mcp-app` MIME type when the resource
+doesn't set one explicitly, and rejects an explicit mismatch: a `ui://` resource
+under any other MIME type is one no host will render.
+
+!!! tip
+    Targeting a pre-GA host that still reads the deprecated flat
+    `_meta["ui/resourceUri"]` key? Merge it yourself:
+    `@apps.tool(resource_uri="ui://x", meta={"ui/resourceUri": "ui://x"})`.
+    The nested `ui` object is the spec shape; the flat key is on its way out.
+
+## See it run
+
+The `apps` story in `examples/stories/` is this page as a runnable pair: a server
+with a UI-bound clock tool and a client that negotiates Apps, reads the tool's
+`_meta.ui.resourceUri`, fetches the HTML, and calls the tool.
+
+```bash
+uv run python -m stories.apps.client
+```

docs/advanced/authorization.md

@@ -109,6 +109,8 @@ To watch all three parties move, run `examples/servers/simple-auth/` from the SD
     server inside your MCP server. It predates the AS/RS separation that the MCP authorization spec
     is built around. New servers should not reach for it.
 
+An authorization server can also accept an enterprise identity provider's signed assertion in place of a user clicking through a consent screen, and the SDK supports both sides of that exchange. The grant, and the client that presents it, is **Identity assertion**.
+
 ## Recap
 
 * Over Streamable HTTP your server is an OAuth 2.1 **resource server**: it verifies tokens, it never issues them.