diff --git a/docs/migrate_from_openai_apps.md b/docs/migrate_from_openai_apps.md index fb64e73be..52198acba 100644 --- a/docs/migrate_from_openai_apps.md +++ b/docs/migrate_from_openai_apps.md @@ -265,9 +265,9 @@ Client-side migration involves replacing the implicit `window.openai` global wit | -------------------------------------------------- | --------------------------------------------------------- | ----------------------------------- | | `await window.openai.requestDisplayMode({ mode })` | `await app.requestDisplayMode({ mode })` | Same API | | — | Check `app.getHostContext()?.availableDisplayModes` first | MCP lets you check what's available | -| `_meta["openai/ui"].preferredDisplayMode` | `preferredDisplayMode` in the `App` capabilities | A hint; see below | +| `_meta["openai/ui"].preferredDisplayMode` | `_meta.ui.preferredDisplayMode` on the UI resource | A hint; see below | -`_meta["openai/ui"].preferredDisplayMode` comes from OpenAI's [MCP extensions](https://github.com/openai/mcp-extensions/blob/main/docs/spec.md#display-modes), where it is set on the UI resource. In MCP Apps the View declares the preference itself when it connects (`new App(appInfo, { availableDisplayModes, preferredDisplayMode })`), and the host may ignore it. +`_meta["openai/ui"].availableDisplayModes` and `preferredDisplayMode` come from OpenAI's [MCP extensions](https://github.com/openai/mcp-extensions/blob/main/docs/spec.md#display-modes). MCP Apps uses the same names in the same place, the UI resource content item, under `_meta.ui` instead of `_meta["openai/ui"]`. The host may ignore the preference. ### Size Reporting diff --git a/docs/patterns.md b/docs/patterns.md index 39f723138..1e4ba25ea 100644 --- a/docs/patterns.md +++ b/docs/patterns.md @@ -447,23 +447,35 @@ In fullscreen mode, remove the container's border radius so content extends to t } ``` -If your View is mainly useful on a large surface, declare `fullscreen` as its preferred display mode. This is a hint for how the host first shows the View. The host may ignore it, or apply it just after the View is first shown, so keep the `onhostcontextchanged` handler above: +If your View is mainly useful on a large surface, declare `fullscreen` as its preferred display mode on the UI resource. The host reads it before the View loads, so it can open the View in fullscreen right away. It is a hint: the host may ignore it, or apply it just after the View is first shown, so keep the `onhostcontextchanged` handler above: -```ts source="../src/app.examples.ts#App_constructor_preferredDisplayMode" -const app = new App( - { name: "MyApp", version: "1.0.0" }, +```ts source="../src/server/index.examples.ts#registerAppResource_preferredDisplayMode" +registerAppResource( + server, + "Map", + "ui://map/view.html", { - availableDisplayModes: ["inline", "fullscreen"], - preferredDisplayMode: "fullscreen", + description: "Interactive map", }, + async () => ({ + contents: [ + { + uri: "ui://map/view.html", + mimeType: RESOURCE_MIME_TYPE, + text: mapHtml, + _meta: { + ui: { + // Known before the View loads, so the host can open it in fullscreen + // right away. A hint: the host may still show it inline. + availableDisplayModes: ["inline", "fullscreen"], + preferredDisplayMode: "fullscreen", + }, + }, + }, + ], + }), ); -await app.connect(); - -// The host may ignore the preference: read the actual mode. -const container = document.getElementById("main")!; -const isFullscreen = app.getHostContext()?.displayMode === "fullscreen"; -container.classList.toggle("fullscreen", isFullscreen); ``` > [!NOTE] diff --git a/examples/basic-host/src/implementation.ts b/examples/basic-host/src/implementation.ts index 9998ae5f0..de07e51a3 100644 --- a/examples/basic-host/src/implementation.ts +++ b/examples/basic-host/src/implementation.ts @@ -1,4 +1,4 @@ -import { RESOURCE_MIME_TYPE, getToolUiResourceUri, type McpUiSandboxProxyReadyNotification, AppBridge, PostMessageTransport, type McpUiResourceCsp, type McpUiResourcePermissions, buildAllowAttribute, type McpUiUpdateModelContextRequest, type McpUiMessageRequest } from "@modelcontextprotocol/ext-apps/app-bridge"; +import { RESOURCE_MIME_TYPE, getToolUiResourceUri, type McpUiSandboxProxyReadyNotification, AppBridge, PostMessageTransport, type McpUiResourceCsp, type McpUiResourcePermissions, type McpUiDisplayMode, buildAllowAttribute, type McpUiUpdateModelContextRequest, type McpUiMessageRequest } from "@modelcontextprotocol/ext-apps/app-bridge"; import { Client, SSEClientTransport, @@ -76,6 +76,8 @@ interface UiResourceData { html: string; csp?: McpUiResourceCsp; permissions?: McpUiResourcePermissions; + availableDisplayModes?: McpUiDisplayMode[]; + preferredDisplayMode?: McpUiDisplayMode; } export interface ToolCallInfo { @@ -155,8 +157,10 @@ async function getUiResource(serverInfo: ServerInfo, uri: string): Promise { - appBridge.removeEventListener("initialized", applyPreferredDisplayMode); - const caps = appBridge.getAppCapabilities(); - if ( - caps?.preferredDisplayMode === "fullscreen" && - caps.availableDisplayModes?.includes("fullscreen") && - (options?.displayMode ?? "inline") === "inline" - ) { - log.info("Applying the app's preferred display mode: fullscreen"); - appBridge.sendHostContextChange({ displayMode: "fullscreen" }); - callbacks?.onDisplayModeChange?.("fullscreen"); - } - }; - appBridge.addEventListener("initialized", applyPreferredDisplayMode); - return appBridge; } + + +/** + * Choose how to first show the app, from its resource's `_meta.ui` display + * mode hints. This host offers only inline and fullscreen, so fullscreen is + * the one preference to act on, and only if the resource lists it as available + * (or lists no modes). + */ +export function initialDisplayMode( + { availableDisplayModes, preferredDisplayMode }: UiResourceData, +): "inline" | "fullscreen" { + return preferredDisplayMode === "fullscreen" && + (availableDisplayModes?.includes("fullscreen") ?? true) + ? "fullscreen" + : "inline"; +} diff --git a/examples/basic-host/src/index.tsx b/examples/basic-host/src/index.tsx index 9afa9fc35..0878f1d2f 100644 --- a/examples/basic-host/src/index.tsx +++ b/examples/basic-host/src/index.tsx @@ -2,7 +2,7 @@ import { getToolUiResourceUri, McpUiToolMetaSchema } from "@modelcontextprotocol import type { Tool } from "@modelcontextprotocol/client"; import { Component, type ErrorInfo, type ReactNode, StrictMode, Suspense, use, useEffect, useMemo, useRef, useState } from "react"; import { createRoot } from "react-dom/client"; -import { callTool, connectToServer, hasAppHtml, initializeApp, loadSandboxProxy, log, newAppBridge, type ServerInfo, type ToolCallInfo, type ModelContext, type AppMessage } from "./implementation"; +import { callTool, connectToServer, hasAppHtml, initialDisplayMode, initializeApp, loadSandboxProxy, log, newAppBridge, type ServerInfo, type ToolCallInfo, type ModelContext, type AppMessage } from "./implementation"; import { getTheme, toggleTheme, onThemeChange, type Theme } from "./theme"; import styles from "./index.module.css"; @@ -434,13 +434,17 @@ function AppIFramePanel({ toolCallInfo, isDestroying, onTeardownComplete }: AppI // First get CSP and permissions from resource, then load sandbox // CSP is set via HTTP headers (tamper-proof), permissions via iframe allow attribute - toolCallInfo.appResourcePromise.then(({ csp, permissions }) => { + toolCallInfo.appResourcePromise.then((resource) => { + const { csp, permissions } = resource; loadSandboxProxy(iframe, csp, permissions).then((firstTime) => { // The `firstTime` check guards against React Strict Mode's double // invocation (mount → unmount → remount simulation in development). // Outside of Strict Mode, this `useEffect` runs only once per // `toolCallInfo`. if (firstTime) { + // Apply the resource's display mode hints before the app is shown. + const firstMode = initialDisplayMode(resource); + setDisplayMode(firstMode); const appBridge = newAppBridge(toolCallInfo.serverInfo, iframe, { onContextUpdate: setModelContext, onMessage: (msg) => setMessages((prev) => [...prev, msg]), @@ -448,7 +452,7 @@ function AppIFramePanel({ toolCallInfo, isDestroying, onTeardownComplete }: AppI }, { // Provide container dimensions - maxHeight for flexible sizing containerDimensions: { maxHeight: 6000 }, - displayMode: "inline", + displayMode: firstMode, }); appBridgeRef.current = appBridge; initializeApp(iframe, appBridge, toolCallInfo); diff --git a/specification/draft/apps.mdx b/specification/draft/apps.mdx index 1a7e44302..2e2583acb 100644 --- a/specification/draft/apps.mdx +++ b/specification/draft/apps.mdx @@ -225,6 +225,25 @@ interface UIResourceMeta { * - omitted: host decides border */ prefersBorder?: boolean, + /** + * Display modes the view supports + * + * Same meaning as `appCapabilities.availableDisplayModes` (see Display Modes), + * but known before the view loads, so the host can choose how it first shows it. + * + * @example + * ["inline", "fullscreen"] + */ + availableDisplayModes?: Array<"inline" | "fullscreen" | "pip">, + /** + * Display mode in which the view prefers to be first shown + * + * A hint: the host MAY ignore it. See Display Modes section for details. + * + * @example + * "fullscreen" + */ + preferredDisplayMode?: "inline" | "fullscreen" | "pip", } ``` @@ -254,6 +273,8 @@ The resource content is returned via `resources/read`: }; domain?: string; prefersBorder?: boolean; + availableDisplayModes?: Array<"inline" | "fullscreen" | "pip">; + preferredDisplayMode?: "inline" | "fullscreen" | "pip"; }; }; }]; @@ -262,7 +283,7 @@ The resource content is returned via `resources/read`: #### Metadata Location -`UIResourceMeta` (CSP, permissions, domain, prefersBorder) may be provided on either or both: +`UIResourceMeta` (CSP, permissions, domain, prefersBorder, availableDisplayModes, preferredDisplayMode) may be provided on either or both: - **`resources/list`:** On the resource entry's `_meta.ui` field. Useful as a static default that hosts can review at connection time. - **`resources/read`:** On each content item's `_meta.ui` field. Useful for per-response overrides or dynamic metadata that is only known at read time. @@ -560,12 +581,6 @@ interface McpUiAppCapabilities { * @example ["inline", "fullscreen"] */ availableDisplayModes?: Array<"inline" | "fullscreen" | "pip">; - /** - * Display mode in which the app prefers to be first shown. A hint: the host MAY ignore it. - * See Display Modes section for details. - * @example "fullscreen" - */ - preferredDisplayMode?: "inline" | "fullscreen" | "pip"; } ``` @@ -843,27 +858,30 @@ Hosts declare which display modes they support in `HostContext.availableDisplayM #### Preferred Display Mode -A View can name the display mode in which it prefers to be first shown, in `appCapabilities.preferredDisplayMode`. This suits Views that are mainly useful on a large surface, such as an editor, a dashboard or a map. +A UI resource can declare the display modes its View supports and the one in which it prefers to be first shown, in `_meta.ui.availableDisplayModes` and `_meta.ui.preferredDisplayMode`. Both follow the [Metadata Location](#metadata-location) rules. They are on the resource rather than in `ui/initialize` so that a Host can choose how it first shows the View before the View has loaded, and the user does not see it move. This suits Views that are mainly useful on a large surface, such as an editor, a dashboard or a map. -```typescript -// Example: View supports inline and fullscreen, and prefers to start in fullscreen +```json +// resources/read content item: View supports inline and fullscreen, and prefers to start in fullscreen { - method: "ui/initialize", - params: { - appCapabilities: { - availableDisplayModes: ["inline", "fullscreen"], - preferredDisplayMode: "fullscreen" - }, - // ... + "uri": "ui://map-server/map", + "mimeType": "text/html;profile=mcp-app", + "text": "...", + "_meta": { + "ui": { + "availableDisplayModes": ["inline", "fullscreen"], + "preferredDisplayMode": "fullscreen" + } } } ``` -The preference is a hint. The Host chooses how it first shows the View and how much weight it gives to the preference, for example when several Views prefer `fullscreen` at once. The View sends the preference before it has seen `HostContext.availableDisplayModes`, so checking that the mode is available falls to the Host. +The preference is a hint. The Host chooses how it first shows the View and how much weight it gives to the preference, for example when several Views prefer `fullscreen` at once. + +A Host that applies the preference should do so before it first shows the View, and tells the View in the `hostContext.displayMode` of its `ui/initialize` result. A Host that has already shown the View, for example inline while the tool runs, may instead move it once, no later than when it sends the first `ui/notifications/tool-result`. After that, a Host should not use the preference to move the View without a user action: to change mode later, Views use `ui/request-display-mode`. -A Host that applies the preference should do so before it first shows the View, so that the user does not see the View move. It tells the View either in the `hostContext.displayMode` of its `ui/initialize` result, or in a `ui/notifications/host-context-changed` sent after `ui/notifications/initialized`. A Host that has already shown the View, for example inline while the tool runs, may instead move it once, no later than when it sends the first `ui/notifications/tool-result`. After that, a Host should not use the preference to move the View without a user action: to change mode later, Views use `ui/request-display-mode`. +Once the View has initialized, `appCapabilities.availableDisplayModes` is authoritative. A View that declares display modes on its resource SHOULD declare the same list there. -Note (non-normative): the name and the meaning of this field follow OpenAI's [MCP extensions](https://github.com/openai/mcp-extensions/blob/15e0f4745e7c95865ee2195de5b79f4148b21418/docs/spec.md#display-modes), which define `_meta["openai/ui"].preferredDisplayMode` as the preferred initial display mode. There it is on the UI resource content item rather than in `ui/initialize`; this specification does not define that key. +Note (non-normative): these fields follow OpenAI's [MCP extensions](https://github.com/openai/mcp-extensions/blob/39f91ad0bdf1435aadb879172ab2467d0e97cead/docs/spec.md#display-modes), which define `availableDisplayModes` and `preferredDisplayMode` under `_meta["openai/ui"]` on the UI resource content item. This specification does not define that key. #### Requesting Changes @@ -879,19 +897,20 @@ Hosts notify views of display mode changes via `ui/notifications/host-context-ch - View MUST declare all display modes it supports in `appCapabilities.availableDisplayModes` during initialization. - View MUST check if the requested mode is in `availableDisplayModes` from host context before requesting a mode change. - View MUST handle the response mode differing from the requested mode. -- View that sets `appCapabilities.preferredDisplayMode` MUST also list that mode in `appCapabilities.availableDisplayModes`. -- View MUST handle being shown in a display mode other than `appCapabilities.preferredDisplayMode`. +- A UI resource that sets both `_meta.ui.preferredDisplayMode` and `_meta.ui.availableDisplayModes` MUST list the preferred mode in `availableDisplayModes`. +- View MUST handle being shown in a display mode other than its resource's `_meta.ui.preferredDisplayMode`. **Host behavior:** - Host MUST NOT switch the View to a display mode that does not appear in its `appCapabilities.availableDisplayModes`, if set. - Host MUST return the resulting mode (whether updated or not) in the response to `ui/request-display-mode`. - If the requested mode is not available, Host SHOULD return the current display mode in the response. - Host MAY decline display mode requests from Views that did not declare said modes in their capabilities. -- Host MAY ignore `appCapabilities.preferredDisplayMode`, for example in favor of a choice the user has made, or by declining to start a View in `fullscreen` or `pip` without a user action. -- Host MUST NOT refuse `ui/initialize` because it does not offer the preferred mode (one of the display modes defined above), or because `appCapabilities.availableDisplayModes`, if set, lacks it; it ignores the preference instead. -- Host that applies `appCapabilities.preferredDisplayMode` SHOULD do so before it first shows the View. A Host that has already shown the View MAY instead apply it once, no later than when it sends the first `ui/notifications/tool-result`, unless the user has changed the View's display mode in the meantime. -- After that, Host SHOULD NOT use the preference to change the View's display mode without a user action. A repeated `ui/initialize` from a View that is already shown does not renew the preference. -- Host that applies `appCapabilities.preferredDisplayMode` SHOULD report the resulting mode in `hostContext.displayMode`. +- Host MAY ignore `_meta.ui.preferredDisplayMode`, for example in favor of a choice the user has made, or by declining to start a View in `fullscreen` or `pip` without a user action. +- Host MUST ignore `_meta.ui.preferredDisplayMode` if the resource's `_meta.ui.availableDisplayModes` is set and does not list it. +- Host that chose a display mode from the resource's `_meta.ui` before the View initialized, and finds that mode missing from `appCapabilities.availableDisplayModes`, SHOULD move the View to a mode that list includes and report it in `ui/notifications/host-context-changed`. +- Host that applies `_meta.ui.preferredDisplayMode` SHOULD do so before it first shows the View. A Host that has already shown the View MAY instead apply it once, no later than when it sends the first `ui/notifications/tool-result`, unless the user has changed the View's display mode in the meantime. +- After that, Host SHOULD NOT use the preference to change the View's display mode without a user action. Re-reading the resource for a View that is already shown does not renew the preference. +- Host that applies `_meta.ui.preferredDisplayMode` SHOULD report the resulting mode in `hostContext.displayMode`. ### Theming diff --git a/src/app-bridge.examples.ts b/src/app-bridge.examples.ts index 5d7fdd777..47ad6234f 100644 --- a/src/app-bridge.examples.ts +++ b/src/app-bridge.examples.ts @@ -13,7 +13,7 @@ import type { CreateMessageResult, } from "@modelcontextprotocol/server"; import { AppBridge, PostMessageTransport } from "./app-bridge.js"; -import type { McpUiDisplayMode, McpUiHostContext } from "./types.js"; +import type { McpUiDisplayMode } from "./types.js"; /** * Example: Basic usage of the AppBridge class with PostMessageTransport. @@ -95,34 +95,6 @@ function AppBridge_getAppCapabilities_checkAfterInit(bridge: AppBridge) { //#endregion AppBridge_getAppCapabilities_checkAfterInit } -/** - * Example: Apply the View's preferred display mode. - */ -function AppBridge_getAppCapabilities_preferredDisplayMode( - bridge: AppBridge, - hostContext: McpUiHostContext, -) { - //#region AppBridge_getAppCapabilities_preferredDisplayMode - let applied = false; - bridge.addEventListener("initialized", () => { - // The preference is for how the View is first shown: apply it once. - if (applied) return; - applied = true; - - const caps = bridge.getAppCapabilities(); - const preferred = caps?.preferredDisplayMode; - // A hint: only for a mode that both the View and the host support. - if ( - preferred && - caps.availableDisplayModes?.includes(preferred) && - hostContext.availableDisplayModes?.includes(preferred) - ) { - bridge.setHostContext({ ...hostContext, displayMode: preferred }); - } - }); - //#endregion AppBridge_getAppCapabilities_preferredDisplayMode -} - /** * Example: Log View information after initialization. */ diff --git a/src/app-bridge.test.ts b/src/app-bridge.test.ts index 6fa8f251a..a87b0e7db 100644 --- a/src/app-bridge.test.ts +++ b/src/app-bridge.test.ts @@ -163,75 +163,6 @@ describe("App <-> AppBridge integration", () => { expect(appCaps).toEqual(appCapabilities); }); - it("Bridge receives the app's preferred display mode", async () => { - const appCapabilities = { - availableDisplayModes: ["inline" as const, "fullscreen" as const], - preferredDisplayMode: "fullscreen" as const, - }; - app = new App(testAppInfo, appCapabilities, { autoResize: false }); - - await bridge.connect(bridgeTransport); - await app.connect(appTransport); - - expect(bridge.getAppCapabilities()).toEqual(appCapabilities); - }); - - it("App learns from host context that its preferred display mode was applied", async () => { - app = new App( - testAppInfo, - { - availableDisplayModes: ["inline", "fullscreen"], - preferredDisplayMode: "fullscreen", - }, - { autoResize: false }, - ); - const hostContext: ReturnType = { - theme: "dark", - displayMode: "inline", - availableDisplayModes: ["inline", "fullscreen"], - }; - bridge = new AppBridge( - createMockClient() as Client, - testHostInfo, - testHostCapabilities, - { hostContext }, - ); - bridge.addEventListener("initialized", () => { - const caps = bridge.getAppCapabilities(); - const preferred = caps?.preferredDisplayMode; - if ( - preferred && - caps?.availableDisplayModes?.includes(preferred) && - hostContext.availableDisplayModes?.includes(preferred) - ) { - bridge.setHostContext({ ...hostContext, displayMode: preferred }); - } - }); - - await bridge.connect(bridgeTransport); - await app.connect(appTransport); - await flush(); - - expect(app.getHostContext()).toEqual({ - ...hostContext, - displayMode: "fullscreen", - }); - }); - - it("Bridge refuses ui/initialize when the preferred display mode is not a known mode", async () => { - app = new App( - testAppInfo, - { preferredDisplayMode: "not-a-mode" as never }, - { autoResize: false }, - ); - - await bridge.connect(bridgeTransport); - await expect(app.connect(appTransport)).rejects.toMatchObject({ - code: -32602, - }); - expect(bridge.getAppCapabilities()).toBeUndefined(); - }); - it("App receives initial hostContext after connect", async () => { // Need fresh transports for new bridge const [newAppTransport, newBridgeTransport] = diff --git a/src/app-bridge.ts b/src/app-bridge.ts index cc9da0e4e..1ac4db485 100644 --- a/src/app-bridge.ts +++ b/src/app-bridge.ts @@ -618,27 +618,6 @@ export class AppBridge extends Protocol { * }; * ``` * - * @example Apply the view's preferred display mode - * ```ts source="./app-bridge.examples.ts#AppBridge_getAppCapabilities_preferredDisplayMode" - * let applied = false; - * bridge.addEventListener("initialized", () => { - * // The preference is for how the View is first shown: apply it once. - * if (applied) return; - * applied = true; - * - * const caps = bridge.getAppCapabilities(); - * const preferred = caps?.preferredDisplayMode; - * // A hint: only for a mode that both the View and the host support. - * if ( - * preferred && - * caps.availableDisplayModes?.includes(preferred) && - * hostContext.availableDisplayModes?.includes(preferred) - * ) { - * bridge.setHostContext({ ...hostContext, displayMode: preferred }); - * } - * }); - * ``` - * * @see {@link McpUiAppCapabilities `McpUiAppCapabilities`} for the capabilities structure */ getAppCapabilities(): McpUiAppCapabilities | undefined { diff --git a/src/app.examples.ts b/src/app.examples.ts index 8eb7b5b91..7d475efa0 100644 --- a/src/app.examples.ts +++ b/src/app.examples.ts @@ -583,27 +583,6 @@ async function App_requestDisplayMode_toggle(app: App) { //#endregion App_requestDisplayMode_toggle } -/** - * Example: Prefer to be first shown in fullscreen. - */ -async function App_constructor_preferredDisplayMode() { - //#region App_constructor_preferredDisplayMode - const app = new App( - { name: "MyApp", version: "1.0.0" }, - { - availableDisplayModes: ["inline", "fullscreen"], - preferredDisplayMode: "fullscreen", - }, - ); - await app.connect(); - - // The host may ignore the preference: read the actual mode. - const container = document.getElementById("main")!; - const isFullscreen = app.getHostContext()?.displayMode === "fullscreen"; - container.classList.toggle("fullscreen", isFullscreen); - //#endregion App_constructor_preferredDisplayMode -} - /** * Example: Manually notify host of size change. */ diff --git a/src/app.ts b/src/app.ts index 34df6669d..d97eb9ae0 100644 --- a/src/app.ts +++ b/src/app.ts @@ -577,23 +577,6 @@ export class App extends Protocol { * { autoResize: true }, // options * ); * ``` - * - * @example Prefer to be first shown in fullscreen - * ```ts source="./app.examples.ts#App_constructor_preferredDisplayMode" - * const app = new App( - * { name: "MyApp", version: "1.0.0" }, - * { - * availableDisplayModes: ["inline", "fullscreen"], - * preferredDisplayMode: "fullscreen", - * }, - * ); - * await app.connect(); - * - * // The host may ignore the preference: read the actual mode. - * const container = document.getElementById("main")!; - * const isFullscreen = app.getHostContext()?.displayMode === "fullscreen"; - * container.classList.toggle("fullscreen", isFullscreen); - * ``` */ constructor( private _appInfo: Implementation, diff --git a/src/generated/schema.json b/src/generated/schema.json index 1b741f846..7eb08ea79 100644 --- a/src/generated/schema.json +++ b/src/generated/schema.json @@ -54,23 +54,6 @@ ], "description": "Display mode for UI presentation." } - }, - "preferredDisplayMode": { - "description": "Display mode in which the app prefers to be first shown.\n\nA hint: the host chooses how it first shows the app and may ignore this value. The app reads the mode it is displayed in from `hostContext.displayMode`. Must also be listed in `availableDisplayModes`.", - "anyOf": [ - { - "type": "string", - "const": "inline" - }, - { - "type": "string", - "const": "fullscreen" - }, - { - "type": "string", - "const": "pip" - } - ] } }, "additionalProperties": false @@ -2657,23 +2640,6 @@ ], "description": "Display mode for UI presentation." } - }, - "preferredDisplayMode": { - "description": "Display mode in which the app prefers to be first shown.\n\nA hint: the host chooses how it first shows the app and may ignore this value. The app reads the mode it is displayed in from `hostContext.displayMode`. Must also be listed in `availableDisplayModes`.", - "anyOf": [ - { - "type": "string", - "const": "inline" - }, - { - "type": "string", - "const": "fullscreen" - }, - { - "type": "string", - "const": "pip" - } - ] } }, "additionalProperties": false, @@ -4365,6 +4331,44 @@ "prefersBorder": { "description": "Visual boundary preference - true if view prefers a visible border.\n\nBoolean requesting whether a visible border and background is provided by the host. Specifying an explicit value for this is recommended because hosts' defaults may vary.\n\n- `true`: request visible border + background\n- `false`: request no visible border + background\n- omitted: host decides border", "type": "boolean" + }, + "availableDisplayModes": { + "description": "Display modes the view supports, known before the view loads.\n\nSame meaning as `appCapabilities.availableDisplayModes`, which stays authoritative once the view has initialized. Lets the host choose how it first shows the view without waiting for `ui/initialize`.", + "type": "array", + "items": { + "anyOf": [ + { + "type": "string", + "const": "inline" + }, + { + "type": "string", + "const": "fullscreen" + }, + { + "type": "string", + "const": "pip" + } + ], + "description": "Display mode for UI presentation." + } + }, + "preferredDisplayMode": { + "description": "Display mode in which the view prefers to be first shown.\n\nA hint: the host chooses how it first shows the view and may ignore this value. The view reads the mode it is displayed in from `hostContext.displayMode`. If `availableDisplayModes` is set, it must list this mode.", + "anyOf": [ + { + "type": "string", + "const": "inline" + }, + { + "type": "string", + "const": "fullscreen" + }, + { + "type": "string", + "const": "pip" + } + ] } }, "additionalProperties": false diff --git a/src/generated/schema.ts b/src/generated/schema.ts index 82b09ee10..b134eddab 100644 --- a/src/generated/schema.ts +++ b/src/generated/schema.ts @@ -614,14 +614,6 @@ export const McpUiAppCapabilitiesSchema = z.object({ .array(McpUiDisplayModeSchema) .optional() .describe("Display modes the app supports."), - /** - * @description Display mode in which the app prefers to be first shown. - * - * A hint: the host chooses how it first shows the app and may ignore this value. The app reads the mode it is displayed in from `hostContext.displayMode`. Must also be listed in `availableDisplayModes`. - */ - preferredDisplayMode: McpUiDisplayModeSchema.optional().describe( - "Display mode in which the app prefers to be first shown.\n\nA hint: the host chooses how it first shows the app and may ignore this value. The app reads the mode it is displayed in from `hostContext.displayMode`. Must also be listed in `availableDisplayModes`.", - ), }); /** @@ -687,6 +679,25 @@ export const McpUiResourceMetaSchema = z.object({ .describe( "Visual boundary preference - true if view prefers a visible border.\n\nBoolean requesting whether a visible border and background is provided by the host. Specifying an explicit value for this is recommended because hosts' defaults may vary.\n\n- `true`: request visible border + background\n- `false`: request no visible border + background\n- omitted: host decides border", ), + /** + * @description Display modes the view supports, known before the view loads. + * + * Same meaning as `appCapabilities.availableDisplayModes`, which stays authoritative once the view has initialized. Lets the host choose how it first shows the view without waiting for `ui/initialize`. + */ + availableDisplayModes: z + .array(McpUiDisplayModeSchema) + .optional() + .describe( + "Display modes the view supports, known before the view loads.\n\nSame meaning as `appCapabilities.availableDisplayModes`, which stays authoritative once the view has initialized. Lets the host choose how it first shows the view without waiting for `ui/initialize`.", + ), + /** + * @description Display mode in which the view prefers to be first shown. + * + * A hint: the host chooses how it first shows the view and may ignore this value. The view reads the mode it is displayed in from `hostContext.displayMode`. If `availableDisplayModes` is set, it must list this mode. + */ + preferredDisplayMode: McpUiDisplayModeSchema.optional().describe( + "Display mode in which the view prefers to be first shown.\n\nA hint: the host chooses how it first shows the view and may ignore this value. The view reads the mode it is displayed in from `hostContext.displayMode`. If `availableDisplayModes` is set, it must list this mode.", + ), }); /** diff --git a/src/server/index.examples.ts b/src/server/index.examples.ts index 9ceebcebb..ef7ad9b13 100644 --- a/src/server/index.examples.ts +++ b/src/server/index.examples.ts @@ -196,6 +196,43 @@ function registerAppResource_withCsp( //#endregion registerAppResource_withCsp } +/** + * Example: registerAppResource declaring the display modes the View supports + * and the one it prefers to be first shown in. + */ +function registerAppResource_preferredDisplayMode( + server: McpServer, + mapHtml: string, +) { + //#region registerAppResource_preferredDisplayMode + registerAppResource( + server, + "Map", + "ui://map/view.html", + { + description: "Interactive map", + }, + async () => ({ + contents: [ + { + uri: "ui://map/view.html", + mimeType: RESOURCE_MIME_TYPE, + text: mapHtml, + _meta: { + ui: { + // Known before the View loads, so the host can open it in fullscreen + // right away. A hint: the host may still show it inline. + availableDisplayModes: ["inline", "fullscreen"], + preferredDisplayMode: "fullscreen", + }, + }, + }, + ], + }), + ); + //#endregion registerAppResource_preferredDisplayMode +} + /** * Example: registerAppResource with stable origin for external API CORS allowlists. */ diff --git a/src/server/index.test.ts b/src/server/index.test.ts index 489d0b0de..e3a0d2f98 100644 --- a/src/server/index.test.ts +++ b/src/server/index.test.ts @@ -14,6 +14,7 @@ import { } from "@modelcontextprotocol/server"; import { Client } from "@modelcontextprotocol/client"; import { z } from "zod/v4"; +import { McpUiResourceMetaSchema, type McpUiResourceMeta } from "../types.js"; describe("registerAppTool", () => { it("should pass through config to server.registerTool", () => { @@ -440,6 +441,23 @@ describe("registerAppResource", () => { }); }); +describe("McpUiResourceMetaSchema display mode hints", () => { + it("accepts available and preferred display modes", () => { + const meta: McpUiResourceMeta = { + availableDisplayModes: ["inline", "fullscreen"], + preferredDisplayMode: "fullscreen", + }; + expect(McpUiResourceMetaSchema.parse(meta)).toEqual(meta); + }); + + it("rejects a preferred display mode that is not a known mode", () => { + expect( + McpUiResourceMetaSchema.safeParse({ preferredDisplayMode: "split" }) + .success, + ).toBe(false); + }); +}); + describe("getUiCapability", () => { const MIME_TYPE = "text/html;profile=mcp-app"; diff --git a/src/server/index.ts b/src/server/index.ts index 5fad055a0..b7e50df2e 100644 --- a/src/server/index.ts +++ b/src/server/index.ts @@ -384,6 +384,35 @@ export type ReadResourceCallback = McpUiReadResourceCallback; * ); * ``` * + * @example With a preferred initial display mode + * ```ts source="./index.examples.ts#registerAppResource_preferredDisplayMode" + * registerAppResource( + * server, + * "Map", + * "ui://map/view.html", + * { + * description: "Interactive map", + * }, + * async () => ({ + * contents: [ + * { + * uri: "ui://map/view.html", + * mimeType: RESOURCE_MIME_TYPE, + * text: mapHtml, + * _meta: { + * ui: { + * // Known before the View loads, so the host can open it in fullscreen + * // right away. A hint: the host may still show it inline. + * availableDisplayModes: ["inline", "fullscreen"], + * preferredDisplayMode: "fullscreen", + * }, + * }, + * }, + * ], + * }), + * ); + * ``` + * * @example With stable origin for external API CORS allowlists * ```ts source="./index.examples.ts#registerAppResource_withDomain" * // Computes a stable origin from an MCP server URL for hosting in Claude. diff --git a/src/spec.types.ts b/src/spec.types.ts index 9fdbc912d..cd28dbbae 100644 --- a/src/spec.types.ts +++ b/src/spec.types.ts @@ -545,12 +545,6 @@ export interface McpUiAppCapabilities { }; /** @description Display modes the app supports. */ availableDisplayModes?: McpUiDisplayMode[]; - /** - * @description Display mode in which the app prefers to be first shown. - * - * A hint: the host chooses how it first shows the app and may ignore this value. The app reads the mode it is displayed in from `hostContext.displayMode`. Must also be listed in `availableDisplayModes`. - */ - preferredDisplayMode?: McpUiDisplayMode; } /** @@ -734,6 +728,18 @@ export interface McpUiResourceMeta { * - omitted: host decides border */ prefersBorder?: boolean; + /** + * @description Display modes the view supports, known before the view loads. + * + * Same meaning as `appCapabilities.availableDisplayModes`, which stays authoritative once the view has initialized. Lets the host choose how it first shows the view without waiting for `ui/initialize`. + */ + availableDisplayModes?: McpUiDisplayMode[]; + /** + * @description Display mode in which the view prefers to be first shown. + * + * A hint: the host chooses how it first shows the view and may ignore this value. The view reads the mode it is displayed in from `hostContext.displayMode`. If `availableDisplayModes` is set, it must list this mode. + */ + preferredDisplayMode?: McpUiDisplayMode; } /**