From 5eaaed520aadd41a27f7fb8f497199efffe921c0 Mon Sep 17 00:00:00 2001 From: Enrique Moreno <403428+chuwik@users.noreply.github.com> Date: Thu, 19 Nov 2026 14:25:34 -0800 Subject: [PATCH] spec(draft): group ui/update-model-context blocks and honor annotations.audience Adds _meta.ui.group for display grouping of model context, and host guidance for annotations.audience so background context can stay out of the user's context chips while still reaching the model. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- specification/draft/apps.mdx | 43 ++++++++++++++++++++++++++++++++++++ src/generated/schema.json | 19 ++++++++++++++++ src/generated/schema.test.ts | 10 +++++++++ src/generated/schema.ts | 23 +++++++++++++++++++ src/spec.types.ts | 16 ++++++++++++++ src/types.ts | 2 ++ 6 files changed, 113 insertions(+) diff --git a/specification/draft/apps.mdx b/specification/draft/apps.mdx index bbf486e13..782a1f4c7 100644 --- a/specification/draft/apps.mdx +++ b/specification/draft/apps.mdx @@ -1288,6 +1288,48 @@ Host behavior: - If multiple updates are received before the next user message, Host SHOULD only send the last update to the model - MAY display context updates to the user +**Groups and audience.** Hosts that display context to the user (for example as chips or attachments next to the composer) need to know which blocks belong together and which are not meant for the user. Content blocks in `ui/update-model-context` MAY carry: + +- **`_meta.ui.group`**: `{ title: string }`, a non-empty, plain-text label shared by related blocks. +- **`annotations.audience`**: the standard MCP content annotation (`Array<"user" | "assistant">`). + +```typescript +interface McpUiContentBlockMeta { + /** Groups related content blocks for display. */ + group?: { + /** Non-empty, plain-text label shared by related blocks. */ + title: string; + }; +} +``` + +```typescript +// Five selected rows shown as one "Selected rows" item, the filter as another, +// and an internal ID the user does not need to see +{ + jsonrpc: "2.0", + id: 5, + method: "ui/update-model-context", + params: { + content: [ + { type: "text", text: "Row 12: ACME Corp, $1.2M", _meta: { ui: { group: { title: "Selected rows" } } } }, + { type: "text", text: "Row 31: Globex, $0.8M", _meta: { ui: { group: { title: "Selected rows" } } } }, + { type: "text", text: "Region = EMEA", _meta: { ui: { group: { title: "Filter" } } } }, + { type: "text", text: "Sheet ID: 8f3c2a", annotations: { audience: ["assistant"] } } + ] + } +} +``` + +Host behavior: +- Host that displays context MAY show the blocks that share a `group.title` as one item labelled with that title. Blocks without a group go in a Host-defined default group. Host MUST render the title as plain text and SHOULD truncate it. +- Grouping is for display only. Each request still replaces the View's whole context. +- A block whose `annotations.audience` is `["assistant"]` is background context: Host SHOULD NOT show it as a user-visible or removable item, and still provides it to the model. +- A block whose `annotations.audience` does not include `"assistant"` MAY be shown to the user, and SHOULD NOT be sent to the model. +- A block without `annotations.audience` is for both, as before. +- Host SHOULD still let the user inspect all context a View has provided, including background context, for example in a details view. +- Host SHOULD NOT send `_meta.ui` presentation hints to the model. + #### Requests (Host → App) When Apps declare the `tools` capability, the Host can send standard MCP tool requests to the App: @@ -2705,6 +2747,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. +- **Background model context:** Context marked `annotations.audience: ["assistant"]` is hidden from the user's view of the conversation and could carry injected instructions. Hosts treat it as untrusted View content, like all model context, and let users inspect it on request. - **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..fe77e7b7f 100644 --- a/src/generated/schema.json +++ b/src/generated/schema.json @@ -72,6 +72,25 @@ }, "additionalProperties": false }, + "McpUiContentBlockMeta": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "group": { + "description": "Groups related content blocks for display. Blocks with the same `title` belong together.\n\nDisplay only: it does not change what the model receives, and each `ui/update-model-context` request still replaces the View's whole context.", + "type": "object", + "properties": { + "title": { + "type": "string", + "description": "Non-empty, plain-text label shared by related blocks." + } + }, + "required": ["title"], + "additionalProperties": false + } + }, + "additionalProperties": false + }, "McpUiDisplayMode": { "$schema": "https://json-schema.org/draft/2020-12/schema", "anyOf": [ diff --git a/src/generated/schema.test.ts b/src/generated/schema.test.ts index 57d989fd0..a86efa8f3 100644 --- a/src/generated/schema.test.ts +++ b/src/generated/schema.test.ts @@ -79,6 +79,10 @@ export type McpUiHostStylesSchemaInferredType = z.infer< typeof generated.McpUiHostStylesSchema >; +export type McpUiContentBlockMetaSchemaInferredType = z.infer< + typeof generated.McpUiContentBlockMetaSchema +>; + export type McpUiResourceTeardownRequestSchemaInferredType = z.infer< typeof generated.McpUiResourceTeardownRequestSchema >; @@ -241,6 +245,12 @@ expectType({} as McpUiHostCssSchemaInferredType); expectType({} as spec.McpUiHostCss); expectType({} as McpUiHostStylesSchemaInferredType); expectType({} as spec.McpUiHostStyles); +expectType( + {} as McpUiContentBlockMetaSchemaInferredType, +); +expectType( + {} as spec.McpUiContentBlockMeta, +); expectType( {} as McpUiResourceTeardownRequestSchemaInferredType, ); diff --git a/src/generated/schema.ts b/src/generated/schema.ts index 214b227c2..183f44dfb 100644 --- a/src/generated/schema.ts +++ b/src/generated/schema.ts @@ -430,6 +430,29 @@ export const McpUiHostStylesSchema = z.object({ ), }); +/** + * @description Presentation hints a View may set under `_meta.ui` on content blocks it sends in `ui/update-model-context`. + * Hosts should not send these hints to the model. + */ +export const McpUiContentBlockMetaSchema = z.object({ + /** + * @description Groups related content blocks for display. Blocks with the same `title` belong together. + * + * Display only: it does not change what the model receives, and each `ui/update-model-context` request still replaces the View's whole context. + */ + group: z + .object({ + /** @description Non-empty, plain-text label shared by related blocks. */ + title: z + .string() + .describe("Non-empty, plain-text label shared by related blocks."), + }) + .optional() + .describe( + "Groups related content blocks for display. Blocks with the same `title` belong together.\n\nDisplay only: it does not change what the model receives, and each `ui/update-model-context` request still replaces the View's whole context.", + ), +}); + /** * @description Request for graceful shutdown of the View (Host -> View). * @see {@link app-bridge!AppBridge.teardownResource `AppBridge.teardownResource`} for the host method that sends this diff --git a/src/spec.types.ts b/src/spec.types.ts index 0c4539637..c06837194 100644 --- a/src/spec.types.ts +++ b/src/spec.types.ts @@ -417,6 +417,22 @@ export interface McpUiHostContextChangedNotification { params: McpUiHostContext; } +/** + * @description Presentation hints a View may set under `_meta.ui` on content blocks it sends in `ui/update-model-context`. + * Hosts should not send these hints to the model. + */ +export interface McpUiContentBlockMeta { + /** + * @description Groups related content blocks for display. Blocks with the same `title` belong together. + * + * Display only: it does not change what the model receives, and each `ui/update-model-context` request still replaces the View's whole context. + */ + group?: { + /** @description Non-empty, plain-text label shared by related blocks. */ + title: string; + }; +} + /** * @description Request to update the agent's context without requiring a follow-up action (View -> Host). * diff --git a/src/types.ts b/src/types.ts index e4ed629c4..e8bb909f0 100644 --- a/src/types.ts +++ b/src/types.ts @@ -90,6 +90,7 @@ export { type McpUiMessageRequest, type McpUiMessageResult, type McpUiUpdateModelContextRequest, + type McpUiContentBlockMeta, type McpUiSupportedContentBlockModalities, type McpUiSandboxProxyReadyNotification, type McpUiSandboxResourceReadyNotification, @@ -132,6 +133,7 @@ export { McpUiMessageResultSchema, McpUiUpdateModelContextRequestSchema, McpUiSupportedContentBlockModalitiesSchema, + McpUiContentBlockMetaSchema, McpUiSandboxProxyReadyNotificationSchema, McpUiSandboxResourceReadyNotificationSchema, McpUiSizeChangedNotificationSchema,