From 046a9c0b0f5952fed2d6afc58c751bf23c8cc144 Mon Sep 17 00:00:00 2001 From: Enrique Moreno <403428+chuwik@users.noreply.github.com> Date: Thu, 19 Nov 2026 14:20:55 -0800 Subject: [PATCH] spec(draft): let hosts label a View with its document title and icon Adds ui/notifications/document-info-changed and hostCapabilities.documentInfo, plus host guidance for using the View's title and icon in host chrome without letting them replace the server's identity. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- scripts/generate-schemas.ts | 1 + specification/draft/apps.mdx | 51 ++++++++++++++++++++++++++++++ src/generated/schema.json | 61 ++++++++++++++++++++++++++++++++++++ src/generated/schema.test.ts | 10 ++++++ src/generated/schema.ts | 31 ++++++++++++++++++ src/spec.types.ts | 20 ++++++++++++ src/types.ts | 5 +++ 7 files changed, 179 insertions(+) diff --git a/scripts/generate-schemas.ts b/scripts/generate-schemas.ts index 0ff9f049f..7f353f65b 100644 --- a/scripts/generate-schemas.ts +++ b/scripts/generate-schemas.ts @@ -78,6 +78,7 @@ const EXTERNAL_TYPE_SCHEMAS = [ "ContentBlockSchema", "CallToolResultSchema", "EmbeddedResourceSchema", + "IconSchema", "ImplementationSchema", "RequestIdSchema", "ResourceLinkSchema", diff --git a/specification/draft/apps.mdx b/specification/draft/apps.mdx index bbf486e13..081c98e14 100644 --- a/specification/draft/apps.mdx +++ b/specification/draft/apps.mdx @@ -735,6 +735,8 @@ interface HostCapabilities { openLinks?: {}; /** Host supports file downloads via ui/download-file. */ downloadFile?: {}; + /** Host may label the View with its document title and icon (ui/notifications/document-info-changed). */ + documentInfo?: {}; /** Host can proxy tool calls to the MCP server. */ serverTools?: { /** Host supports tools/list_changed notifications. */ @@ -908,6 +910,39 @@ Hosts notify views of display mode changes via `ui/notifications/host-context-ch - 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. +### View Title and Icon + +Hosts that show a View in their own chrome, such as a tab, a panel header or a window title, need a label and an icon for it. A View already names itself the way any web page does, with `document.title` and ``, but the Host cannot read them from a sandboxed cross-origin iframe. Hosts get them in two ways: + +- **From the resource HTML.** A Host MAY take the `` element and the first `<link rel="icon">` from the HTML returned by `resources/read`, to label the View before it runs. +- **From the View.** A View MAY send `ui/notifications/document-info-changed` with its current `title` and `icons`, after initialization and whenever they change. + +```typescript +// View -> Host, e.g. after the user opens a document in the View +{ + jsonrpc: "2.0", + method: "ui/notifications/document-info-changed", + params: { + title: "Q3 board deck", + icons: [{ src: "data:image/svg+xml;base64,...", mimeType: "image/svg+xml" }] + } +} +``` + +For the label, the Host SHOULD use, in order: the latest title from `ui/notifications/document-info-changed`, the `<title>` of the resource HTML, the tool's display name (`title`, then `annotations.title`, then `name`), the UI resource's `title` or `name`, then the server's name. For the icon: the latest notified icon, the resource HTML's icon, the tool's icon, then the server's icon. + +**Host behavior:** +- Host MAY use the View's title and icon wherever it shows the View in its own chrome. +- Host MUST render the title as plain text. Host SHOULD truncate it (for example to 80 characters) and strip control and bidirectional-override characters. +- Host MUST keep the server's identity, taken from information the Host controls (such as the server's name and icon), visible next to the View's label. The View's title and icon MUST NOT replace that identity in permission prompts, consent dialogs, or anywhere else the user decides whom to trust. +- Host SHOULD rate-limit updates, for example to one per second, and MAY ignore a title that copies the Host's own UI strings. +- Host SHOULD only load icons from `data:` URIs or from origins in the resource's `csp.resourceDomains`, MUST fetch them without credentials, and MAY rasterize or size-limit them. +- Host that does not support this omits `hostCapabilities.documentInfo` and ignores the notification. + +**View behavior:** +- View SHOULD keep its `<title>` meaningful, since Hosts may show it without a notification. +- View SHOULD NOT use a title or icon that imitates the Host or another app. + ### Theming Hosts can optionally pass CSS custom properties via `HostContext.styles.variables` for visual cohesion with the host environment. @@ -1510,6 +1545,21 @@ The View MAY send this notification to request that the host tear it down. This - Host MAY defer or ignore the teardown request. - If the Host accepts the request, it MUST follow the graceful termination process by sending `ui/resource-teardown` to the View. The Host SHOULD wait for a response before tearing down the resource (to prevent data loss). +`ui/notifications/document-info-changed` - View's document title or icon changed + +```typescript +{ + jsonrpc: "2.0", + method: "ui/notifications/document-info-changed", + params: { + title?: string, // The View's document title, as plain text. "" clears it. + icons?: Icon[] // MCP Icon objects (src, mimeType, sizes, theme). [] clears them. + } +} +``` + +The View MAY send this notification after `ui/notifications/initialized`, and whenever its title or icon changes. Omitted fields leave the previous value unchanged. Views SHOULD only send it when `hostCapabilities.documentInfo` is present. See [View Title and Icon](#view-title-and-icon) for how Hosts use it. + `ui/notifications/host-context-changed` - Host context has changed ```typescript @@ -2705,6 +2755,7 @@ App tools MUST be tied to the app's lifecycle: ### Other risks - **Social engineering:** UI can still display misleading content. Hosts should clearly indicate sandboxed UI boundaries. +- **View titles and icons:** A View can name itself after the Host or another app ("Settings", "Sign in"). Hosts that show a View's title or icon keep the server's identity visible next to it and never use them in trust decisions. See [View Title and Icon](#view-title-and-icon). - **Resource consumption:** Malicious View can consume CPU/memory. Hosts should implement resource limits. ## Reservations in MCP diff --git a/src/generated/schema.json b/src/generated/schema.json index 25b7f6b05..6ef2eaab9 100644 --- a/src/generated/schema.json +++ b/src/generated/schema.json @@ -90,6 +90,55 @@ ], "description": "Display mode for UI presentation." }, + "McpUiDocumentInfoChangedNotification": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "method": { + "type": "string", + "const": "ui/notifications/document-info-changed" + }, + "params": { + "type": "object", + "properties": { + "title": { + "description": "The View's current document title, as plain text. An empty string clears it.", + "type": "string" + }, + "icons": { + "description": "Icons for the View. An empty array clears them.", + "type": "array", + "items": { + "type": "object", + "properties": { + "src": { + "type": "string" + }, + "mimeType": { + "type": "string" + }, + "sizes": { + "type": "array", + "items": { + "type": "string" + } + }, + "theme": { + "type": "string", + "enum": ["light", "dark"] + } + }, + "required": ["src"], + "additionalProperties": false + } + } + }, + "additionalProperties": false + } + }, + "required": ["method", "params"], + "additionalProperties": false + }, "McpUiDownloadFileRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", @@ -333,6 +382,12 @@ "properties": {}, "additionalProperties": false }, + "documentInfo": { + "description": "Host may label the View with its document title and icon (ui/notifications/document-info-changed).", + "type": "object", + "properties": {}, + "additionalProperties": false + }, "serverTools": { "description": "Host can proxy tool calls to the MCP server.", "type": "object", @@ -2744,6 +2799,12 @@ "properties": {}, "additionalProperties": false }, + "documentInfo": { + "description": "Host may label the View with its document title and icon (ui/notifications/document-info-changed).", + "type": "object", + "properties": {}, + "additionalProperties": false + }, "serverTools": { "description": "Host can proxy tool calls to the MCP server.", "type": "object", diff --git a/src/generated/schema.test.ts b/src/generated/schema.test.ts index 57d989fd0..b13133aeb 100644 --- a/src/generated/schema.test.ts +++ b/src/generated/schema.test.ts @@ -159,6 +159,10 @@ export type McpUiUpdateModelContextRequestSchemaInferredType = z.infer< typeof generated.McpUiUpdateModelContextRequestSchema >; +export type McpUiDocumentInfoChangedNotificationSchemaInferredType = z.infer< + typeof generated.McpUiDocumentInfoChangedNotificationSchema +>; + export type McpUiInitializeRequestSchemaInferredType = z.infer< typeof generated.McpUiInitializeRequestSchema >; @@ -349,6 +353,12 @@ expectType<spec.McpUiUpdateModelContextRequest>( expectType<McpUiUpdateModelContextRequestSchemaInferredType>( {} as spec.McpUiUpdateModelContextRequest, ); +expectType<spec.McpUiDocumentInfoChangedNotification>( + {} as McpUiDocumentInfoChangedNotificationSchemaInferredType, +); +expectType<McpUiDocumentInfoChangedNotificationSchemaInferredType>( + {} as spec.McpUiDocumentInfoChangedNotification, +); expectType<spec.McpUiInitializeRequest>( {} as McpUiInitializeRequestSchemaInferredType, ); diff --git a/src/generated/schema.ts b/src/generated/schema.ts index 214b227c2..ff296eaf0 100644 --- a/src/generated/schema.ts +++ b/src/generated/schema.ts @@ -6,6 +6,7 @@ import { ContentBlockSchema, CallToolResultSchema, EmbeddedResourceSchema, + IconSchema, ImplementationSchema, RequestIdSchema, ResourceLinkSchema, @@ -516,6 +517,13 @@ export const McpUiHostCapabilitiesSchema = z.object({ .object({}) .optional() .describe("Host supports file downloads via ui/download-file."), + /** @description Host may label the View with its document title and icon (ui/notifications/document-info-changed). */ + documentInfo: z + .object({}) + .optional() + .describe( + "Host may label the View with its document title and icon (ui/notifications/document-info-changed).", + ), /** @description Host can proxy tool calls to the MCP server. */ serverTools: z .object({ @@ -1012,6 +1020,29 @@ export const McpUiUpdateModelContextRequestSchema = z.object({ }), }); +/** + * @description Notification of the View's document title and icon (View -> Host). + * Hosts that show the View in their own chrome (a tab, panel header or window title) may use them as its label. + * Omitted fields leave the previous value unchanged. + */ +export const McpUiDocumentInfoChangedNotificationSchema = z.object({ + method: z.literal("ui/notifications/document-info-changed"), + params: z.object({ + /** @description The View's current document title, as plain text. An empty string clears it. */ + title: z + .string() + .optional() + .describe( + "The View's current document title, as plain text. An empty string clears it.", + ), + /** @description Icons for the View. An empty array clears them. */ + icons: z + .array(IconSchema) + .optional() + .describe("Icons for the View. An empty array clears them."), + }), +}); + /** * @description Initialization request sent from View to Host. * @see {@link app!App.connect `App.connect`} for the method that sends this request diff --git a/src/spec.types.ts b/src/spec.types.ts index 0c4539637..745c18dec 100644 --- a/src/spec.types.ts +++ b/src/spec.types.ts @@ -14,6 +14,7 @@ import type { CallToolResult, ContentBlock, EmbeddedResource, + Icon, Implementation, RequestId, ResourceLink, @@ -487,6 +488,21 @@ export interface McpUiRequestTeardownNotification { params?: {}; } +/** + * @description Notification of the View's document title and icon (View -> Host). + * Hosts that show the View in their own chrome (a tab, panel header or window title) may use them as its label. + * Omitted fields leave the previous value unchanged. + */ +export interface McpUiDocumentInfoChangedNotification { + method: "ui/notifications/document-info-changed"; + params: { + /** @description The View's current document title, as plain text. An empty string clears it. */ + title?: string; + /** @description Icons for the View. An empty array clears them. */ + icons?: Icon[]; + }; +} + /** * @description Capabilities supported by the host application. * @see {@link McpUiInitializeResult `McpUiInitializeResult`} for the initialization result that includes these capabilities @@ -498,6 +514,8 @@ export interface McpUiHostCapabilities { openLinks?: {}; /** @description Host supports file downloads via ui/download-file. */ downloadFile?: {}; + /** @description Host may label the View with its document title and icon (ui/notifications/document-info-changed). */ + documentInfo?: {}; /** @description Host can proxy tool calls to the MCP server. */ serverTools?: { /** @description Host supports tools/list_changed notifications. */ @@ -833,6 +851,8 @@ export const HOST_CONTEXT_CHANGED_METHOD: McpUiHostContextChangedNotification["m "ui/notifications/host-context-changed"; export const REQUEST_TEARDOWN_METHOD: McpUiRequestTeardownNotification["method"] = "ui/notifications/request-teardown"; +export const DOCUMENT_INFO_CHANGED_METHOD: McpUiDocumentInfoChangedNotification["method"] = + "ui/notifications/document-info-changed"; export const RESOURCE_TEARDOWN_METHOD: McpUiResourceTeardownRequest["method"] = "ui/resource-teardown"; export const INITIALIZE_METHOD: McpUiInitializeRequest["method"] = diff --git a/src/types.ts b/src/types.ts index e4ed629c4..44651dac1 100644 --- a/src/types.ts +++ b/src/types.ts @@ -33,6 +33,7 @@ import type { ToolListChangedNotification, } from "@modelcontextprotocol/client"; import type { + McpUiDocumentInfoChangedNotification, McpUiDownloadFileRequest, McpUiDownloadFileResult, McpUiHostContextChangedNotification, @@ -73,6 +74,7 @@ export { TOOL_CANCELLED_METHOD, HOST_CONTEXT_CHANGED_METHOD, REQUEST_TEARDOWN_METHOD, + DOCUMENT_INFO_CHANGED_METHOD, RESOURCE_TEARDOWN_METHOD, INITIALIZE_METHOD, INITIALIZED_METHOD, @@ -103,6 +105,7 @@ export { type McpUiResourceTeardownRequest, type McpUiResourceTeardownResult, type McpUiRequestTeardownNotification, + type McpUiDocumentInfoChangedNotification, type McpUiHostCapabilities, type McpUiAppCapabilities, type McpUiInitializeRequest, @@ -144,6 +147,7 @@ export { McpUiResourceTeardownRequestSchema, McpUiResourceTeardownResultSchema, McpUiRequestTeardownNotificationSchema, + McpUiDocumentInfoChangedNotificationSchema, McpUiHostCapabilitiesSchema, McpUiAppCapabilitiesSchema, McpUiInitializeRequestSchema, @@ -202,6 +206,7 @@ export type AppNotification = | McpUiSizeChangedNotification | McpUiSandboxProxyReadyNotification | McpUiRequestTeardownNotification + | McpUiDocumentInfoChangedNotification | LoggingMessageNotification; /**