"""Tests for the MCP Apps extension (`io.modelcontextprotocol/ui`, SEP-2133).

The headline property is SEP-2133 graceful degradation: a UI-bound tool returns

rich output to a client that negotiated Apps and text-only output to one that did

not. The remaining tests pin SDK-defined wiring (the `_meta.ui.resourceUri` stamp,

the `ui://` resource MIME type, capability advertisement, and `ui://`-scheme

validation).

"""

from typing import Any

import mcp_types as types

import pytest

from inline_snapshot import snapshot

from mcp_types import CallToolResult, ReadResourceResult, TextContent, TextResourceContents

from mcp.client import advertise

from mcp.client.client import Client

from mcp.server import Server, ServerRequestContext

from mcp.server.apps import (

APP_MIME_TYPE,

EXTENSION_ID,

Apps,

ResourceCsp,

ResourcePermissions,

client_supports_apps,

)

from mcp.server.mcpserver import MCPServer

from mcp.server.mcpserver.context import Context

from mcp.server.mcpserver.resources import TextResource

pytestmark = pytest.mark.anyio

def _clock_server() -> MCPServer:

apps = Apps()

@apps.tool(resource_uri="ui://clock/app.html", title="Get Time", description="Return the current time.")

def get_time(ctx: Context) -> str:

if not client_supports_apps(ctx):

return "The time is 2026-06-26T00:00:00Z."

return "2026-06-26T00:00:00Z"

apps.add_html_resource("ui://clock/app.html", "<title>Clock</title>", title="Clock")

return MCPServer("clock", extensions=[apps])

async def test_apps_tool_stamps_ui_resource_uri_on_tool_meta() -> None:

"""SDK-defined: `@apps.tool(resource_uri=...)` stamps `_meta.ui.resourceUri` on the

advertised tool, observed end-to-end through `list_tools`."""

async with Client(_clock_server()) as client:

result = await client.list_tools()

assert [(t.name, t.meta) for t in result.tools] == snapshot(

[("get_time", {"ui": {"resourceUri": "ui://clock/app.html"}})]

)

async def test_add_html_resource_serves_ui_resource_at_app_mime_type() -> None:

"""SDK-defined: `add_html_resource` registers the `ui://` resource served as

`text/html;profile=mcp-app`, observed through `read_resource`."""

async with Client(_clock_server()) as client:

result = await client.read_resource("ui://clock/app.html")

assert result == snapshot(

ReadResourceResult(

_meta={"io.modelcontextprotocol/serverInfo": {"name": "clock", "version": ""}},

contents=[

TextResourceContents(

uri="ui://clock/app.html",

mime_type="text/html;profile=mcp-app",

text="<title>Clock</title>",

)

],

)

)

assert isinstance(result.contents[0], TextResourceContents)

assert result.contents[0].mime_type == APP_MIME_TYPE

async def test_auto_mode_carries_apps_extension_under_server_capabilities() -> None:

"""SDK-defined: the Apps extension rides `server/discover`, so a `mode='auto'` client

sees `EXTENSION_ID` under `server_capabilities.extensions`."""

async with Client(_clock_server(), mode="auto") as client:

assert client.server_capabilities.extensions == snapshot({"io.modelcontextprotocol/ui": {}})

async def test_legacy_handshake_drops_apps_extension_from_capabilities() -> None:

"""Pinned gap: the 2025 `ServerCapabilities` wire schema has no `extensions` field,

so a `mode='legacy'` handshake cannot carry the Apps capability -- only `mode='auto'`

(server/discover) does. This pins the divergence rather than fixing it."""

async with Client(_clock_server(), mode="legacy") as client:

assert client.server_capabilities.extensions is None

async def test_apps_tool_returns_rich_output_when_client_negotiated_apps() -> None:

"""SEP-2133 graceful degradation: a client that advertised `EXTENSION_ID` gets the

rich (UI) path, while one that did not gets the text-only fallback. The same tool,

branching on `client_supports_apps(ctx)`, drives both halves."""

server = _clock_server()

async with Client(server, extensions=[advertise(EXTENSION_ID, {"mimeTypes": [APP_MIME_TYPE]})]) as supports:

rich = await supports.call_tool("get_time", {})

async with Client(server) as plain:

fallback = await plain.call_tool("get_time", {})

assert rich.content == snapshot([TextContent(text="2026-06-26T00:00:00Z")])

assert fallback.content == snapshot([TextContent(text="The time is 2026-06-26T00:00:00Z.")])

async def _observed_client_supports_apps(ui_settings: dict[str, Any] | None) -> bool:

"""Run one probe `tools/call` and report what `client_supports_apps` saw server-side.

Exercises the lowlevel `ServerRequestContext` form, which reads the client's

advertised extensions off `session.client_params`.

"""

observed: list[bool] = []

async def list_tools(

ctx: ServerRequestContext, params: types.PaginatedRequestParams | None

) -> types.ListToolsResult:

return types.ListToolsResult(tools=[types.Tool(name="probe", input_schema={"type": "object"})])

async def call_tool(ctx: ServerRequestContext, params: types.CallToolRequestParams) -> CallToolResult:

assert params.name == "probe"

observed.append(client_supports_apps(ctx))

return CallToolResult(content=[TextContent(text="ok")])

server = Server("probe", on_list_tools=list_tools, on_call_tool=call_tool)

extensions = None if ui_settings is None else [advertise(EXTENSION_ID, ui_settings)]

async with Client(server, extensions=extensions) as client:

await client.call_tool("probe", {})

return observed[0]

@pytest.mark.parametrize(

("ui_settings", "expected"),

[

pytest.param({"mimeTypes": [APP_MIME_TYPE]}, True, id="html-mime-listed"),

pytest.param({"mimeTypes": (APP_MIME_TYPE,)}, True, id="in-process-tuple-mime-types"),

pytest.param(None, False, id="extension-not-declared"),

pytest.param({"mimeTypes": ["application/x-other"]}, False, id="html-mime-not-offered"),

pytest.param({}, False, id="mime-types-key-missing"),

],

)

async def test_client_supports_apps_from_lowlevel_request_context(

ui_settings: dict[str, Any] | None, expected: bool

) -> None:

"""ext-apps: `client_supports_apps` is `True` only when the client declared the ui

extension AND listed `text/html;profile=mcp-app` in its `mimeTypes` settings — a

required field, so its absence means unsupported (the reference SDK's check is

`uiCap?.mimeTypes?.includes(...)`)."""

assert await _observed_client_supports_apps(ui_settings) is expected

def test_apps_tool_rejects_non_ui_resource_uri() -> None:

"""SDK-defined: `@apps.tool` accepts only `ui://` URIs; any other scheme is a

programmer error raised at decoration time."""

apps = Apps()

with pytest.raises(ValueError):

apps.tool(resource_uri="https://example.com/app.html")

def test_add_html_resource_rejects_non_ui_resource_uri() -> None:

"""SDK-defined: `add_html_resource` accepts only `ui://` URIs; any other scheme is

a programmer error raised at registration time."""

apps = Apps()

with pytest.raises(ValueError):

apps.add_html_resource("https://example.com/app.html", "<title>x</title>")

def _widget() -> str:

"""A UI-bound tool body (shared so its one covered call serves both meta tests)."""

return "x"

async def test_apps_tool_stamps_visibility_when_given() -> None:

"""SDK-defined: `@apps.tool(visibility=...)` is stamped into `_meta.ui.visibility`."""

apps = Apps()

apps.tool(resource_uri="ui://v/app.html", visibility=["app"])(_widget)

apps.add_html_resource("ui://v/app.html", "<title>v</title>")

async with Client(MCPServer("v", extensions=[apps])) as client:

result = await client.list_tools()

called = await client.call_tool("_widget", {})

assert result.tools[0].meta == snapshot({"ui": {"resourceUri": "ui://v/app.html", "visibility": ["app"]}})

assert called.content == snapshot([TextContent(text="x")])

async def test_apps_tool_merges_extra_meta_alongside_ui() -> None:

"""SDK-defined: `@apps.tool(meta=...)` merges extra `_meta` keys with the `ui` entry

(previously a `meta=` argument raised a duplicate-keyword TypeError)."""

apps = Apps()

apps.tool(resource_uri="ui://m/app.html", meta={"com.example/k": 1})(_widget)

apps.add_html_resource("ui://m/app.html", "<title>m</title>")

async with Client(MCPServer("m", extensions=[apps])) as client:

result = await client.list_tools()

assert result.tools[0].meta == snapshot({"com.example/k": 1, "ui": {"resourceUri": "ui://m/app.html"}})

async def test_add_html_resource_stamps_csp_and_permissions_on_resource_meta() -> None:

"""SDK-defined: `csp`/`permissions` populate the resource's `_meta.ui` per ext-apps."""

apps = Apps()

apps.add_html_resource(

"ui://r/app.html",

"<title>r</title>",

csp=ResourceCsp(connect_domains=["https://api.example.com"]),

permissions=ResourcePermissions(camera={}),

domain="r.example.com",

prefers_border=True,

)

async with Client(MCPServer("r", extensions=[apps])) as client:

listed = await client.list_resources()

result = await client.read_resource("ui://r/app.html")

expected_ui_meta = snapshot(

{

"ui": {

"csp": {"connectDomains": ["https://api.example.com"]},

"permissions": {"camera": {}},

"domain": "r.example.com",

"prefersBorder": True,

}

}

)

# Hosts read `_meta.ui` from the read content item, with the list entry as

# fallback — the SDK stamps the same value in both places.

assert isinstance(result.contents[0], TextResourceContents)

assert result.contents[0].meta == expected_ui_meta

assert listed.resources[0].meta == expected_ui_meta

def test_apps_tool_with_unregistered_resource_uri_is_rejected_at_construction() -> None:

"""SDK-defined: a tool whose `resource_uri` has no matching registered resource would

advertise a `_meta.ui.resourceUri` that 404s on `resources/read`; the misconfiguration

is rejected when the server consumes the extension."""

apps = Apps()

apps.tool(resource_uri="ui://missing/app.html")(_widget)

with pytest.raises(ValueError) as exc_info:

MCPServer("broken", extensions=[apps])

assert str(exc_info.value) == snapshot(

"Apps tool '_widget' binds resource_uri 'ui://missing/app.html', but no such resource "

"is registered; add it with add_html_resource() or add_resource()"

)

async def test_add_resource_registers_a_prebuilt_ui_resource() -> None:

"""SDK-defined: `add_resource` is the escape hatch for pre-built `ui://` resources

that `add_html_resource` cannot express; it satisfies a tool's `resource_uri` binding."""

apps = Apps()

apps.tool(resource_uri="ui://prebuilt/app.html")(_widget)

apps.add_resource(

TextResource(uri="ui://prebuilt/app.html", name="prebuilt", mime_type=APP_MIME_TYPE, text="<title>p</title>")

)

async with Client(MCPServer("p", extensions=[apps])) as client:

result = await client.read_resource("ui://prebuilt/app.html")

assert isinstance(result.contents[0], TextResourceContents)

assert result.contents[0].text == "<title>p</title>"

def test_add_resource_rejects_non_ui_resource_uri() -> None:

"""SDK-defined: `add_resource` accepts only `ui://` URIs, like the other registrars."""

apps = Apps()

with pytest.raises(ValueError):

apps.add_resource(TextResource(uri="https://example.com/app.html", name="x", text="x"))

def test_apps_tool_rejects_a_ui_meta_key() -> None:

"""SDK-defined: the decorator owns `_meta['ui']` — a caller-supplied `'ui'` entry would be

silently clobbered, so it is rejected at decoration time (use `resource_uri=`/`visibility=`)."""

apps = Apps()

with pytest.raises(ValueError) as exc_info:

apps.tool(resource_uri="ui://c/app.html", meta={"ui": {"resourceUri": "ui://other.html"}})

assert str(exc_info.value) == snapshot(

"Apps.tool() owns _meta['ui']; pass resource_uri=/visibility= instead of a 'ui' meta key"

)

async def test_add_resource_defaults_the_mime_type_to_the_app_mime() -> None:

"""ext-apps: hosts only render `ui://` resources served as `text/html;profile=mcp-app`,

so a resource registered without an explicit `mime_type` gets it by default."""

apps = Apps()

apps.add_resource(TextResource(uri="ui://d/app.html", name="d", text="<title>d</title>"))

async with Client(MCPServer("d", extensions=[apps])) as client:

result = await client.read_resource("ui://d/app.html")

assert isinstance(result.contents[0], TextResourceContents)

assert result.contents[0].mime_type == APP_MIME_TYPE

def test_add_resource_rejects_an_explicit_non_app_mime_type() -> None:

"""ext-apps: an explicit `mime_type` other than `text/html;profile=mcp-app` would make

the resource unrenderable; the mismatch is rejected at registration."""

apps = Apps()

with pytest.raises(ValueError) as exc_info:

apps.add_resource(TextResource(uri="ui://e/app.html", name="e", mime_type="text/html", text="x"))

assert str(exc_info.value) == snapshot(

"MCP Apps resources are served as 'text/html;profile=mcp-app', got 'text/html'"

)