diff --git a/specification/draft/apps.mdx b/specification/draft/apps.mdx index bbf486e13..79cf9f78d 100644 --- a/specification/draft/apps.mdx +++ b/specification/draft/apps.mdx @@ -775,6 +775,13 @@ interface HostCapabilities { updateModelContext?: SupportedContentBlockModalities; /** Host supports receiving content messages (ui/message) from the view. */ message?: SupportedContentBlockModalities; + /** Host supports the `send` and `target` options of ui/message. */ + messageOptions?: { + /** Host supports `send: false` with `target: "active"`: add the content to the current draft. */ + draft?: {}; + /** Host supports `target: "new"`. With `draft` also present, `send: false` opens an editable draft in a new conversation. */ + newConversation?: {}; + }; /** * Host supports LLM sampling (sampling/createMessage) from the view. * Mirrors MCP ClientCapabilities.sampling so hosts can pass it through. @@ -1195,7 +1202,9 @@ Host behavior: content: { type: "text", text: string - } + }, + send?: boolean, // false: add to the user's draft without sending. Default true. + target?: "active" | "new" // Conversation that receives it. Default "active". } } @@ -1220,6 +1229,41 @@ Host behavior: * Host SHOULD add the message to the conversation context, preserving the specified role. * Host MAY request user consent. +**Drafts and new conversations.** By default, `ui/message` sends the message in the conversation that contains the View. Two optional parameters change that, when the Host advertises them in `hostCapabilities.messageOptions`: + +| `send` | `target` | Effect | Capability | +| --- | --- | --- | --- | +| `true` (default) | `"active"` (default) | Send in the current conversation (today's behavior) | none | +| `false` | `"active"` | Add the content to the user's current draft, without sending | `draft` | +| `true` | `"new"` | Start a new conversation with the content as its first message | `newConversation` | +| `false` | `"new"` | Open a new conversation with the content as an editable draft | `draft` and `newConversation` | + +```typescript +// "Ask about this": put a prompt and the selected item in the user's draft +{ + jsonrpc: "2.0", + id: 4, + method: "ui/message", + params: { + role: "user", + content: [ + { type: "text", text: "Compare this part with the M6 hex bolt: " }, + { type: "resource_link", uri: "cad://parts/m8-hex-bolt", name: "M8 hex bolt" } + ], + send: false + } +} +``` + +Host behavior: +* With `send: false`, Host MUST NOT send the content. Host SHOULD append it to the draft and keep what the user has already typed. +* With `target: "new"`, Host starts a new conversation. Host MAY ask the user to confirm before switching to it, and SHOULD do so only after a user action in the View. +* If Host does not support the requested combination, it MUST return an error (or `isError: true`) and MUST NOT send the content instead. +* Non-text content follows `hostCapabilities.message`. Host MAY show `resource_link` and `image` blocks as attachments on the draft. + +View behavior: +* View MUST NOT set `send: false` or `target: "new"` unless the matching `hostCapabilities.messageOptions` field is present. A Host that does not support these options ignores them and sends the message. + `ui/request-display-mode` - Request host to change display mode ```typescript @@ -2705,6 +2749,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. +- **Message drafts and new conversations:** `ui/message` with `send: false` lets the user read and edit View-supplied text before it reaches the model, which limits prompt injection through View content. `target: "new"` changes what the user is looking at, so Hosts tie it to a user action in the View. - **Resource consumption:** Malicious View can consume CPU/memory. Hosts should implement resource limits. ## Reservations in MCP diff --git a/src/app-bridge.test.ts b/src/app-bridge.test.ts index a87b0e7db..fba78e531 100644 --- a/src/app-bridge.test.ts +++ b/src/app-bridge.test.ts @@ -629,6 +629,24 @@ describe("App <-> AppBridge integration", () => { expect(result).toEqual({}); }); + it("app.sendMessage passes the send and target options to the host", async () => { + const receivedMessages: unknown[] = []; + bridge.onmessage = async (params) => { + receivedMessages.push(params); + return {}; + }; + + await app.connect(appTransport); + await app.sendMessage({ + role: "user", + content: [{ type: "text", text: "Draft from app" }], + send: false, + target: "new", + }); + + expect(receivedMessages[0]).toMatchObject({ send: false, target: "new" }); + }); + it("app.sendMessage returns error result when handler indicates error", async () => { bridge.onmessage = async () => { return { isError: true }; diff --git a/src/generated/schema.json b/src/generated/schema.json index 25b7f6b05..9e08256fe 100644 --- a/src/generated/schema.json +++ b/src/generated/schema.json @@ -520,6 +520,25 @@ }, "additionalProperties": false }, + "messageOptions": { + "description": "Host supports the `send` and `target` options of ui/message.", + "type": "object", + "properties": { + "draft": { + "description": "Host supports `send: false` with `target: \"active\"`: add the content to the current draft.", + "type": "object", + "properties": {}, + "additionalProperties": false + }, + "newConversation": { + "description": "Host supports `target: \"new\"`. With `draft` also present, `send: false` opens an editable draft in a new conversation.", + "type": "object", + "properties": {}, + "additionalProperties": false + } + }, + "additionalProperties": false + }, "sampling": { "description": "Host supports LLM sampling (sampling/createMessage) from the view.\nMirrors the MCP `ClientCapabilities.sampling` shape so hosts can pass it through.", "type": "object", @@ -2931,6 +2950,25 @@ }, "additionalProperties": false }, + "messageOptions": { + "description": "Host supports the `send` and `target` options of ui/message.", + "type": "object", + "properties": { + "draft": { + "description": "Host supports `send: false` with `target: \"active\"`: add the content to the current draft.", + "type": "object", + "properties": {}, + "additionalProperties": false + }, + "newConversation": { + "description": "Host supports `target: \"new\"`. With `draft` also present, `send: false` opens an editable draft in a new conversation.", + "type": "object", + "properties": {}, + "additionalProperties": false + } + }, + "additionalProperties": false + }, "sampling": { "description": "Host supports LLM sampling (sampling/createMessage) from the view.\nMirrors the MCP `ClientCapabilities.sampling` shape so hosts can pass it through.", "type": "object", @@ -4087,6 +4125,23 @@ ] }, "description": "Message content blocks (text, image, etc.)." + }, + "send": { + "description": "Whether to send the message. `false` adds the content to the user's draft without sending it. Default: `true`.\n\nOnly set `false` when `hostCapabilities.messageOptions` advertises the matching option: hosts that do not support it send the message.", + "type": "boolean" + }, + "target": { + "description": "Conversation that receives the message: `\"active\"`, the one that contains the View (default), or `\"new\"`, a new conversation.\n\nOnly set `\"new\"` when `hostCapabilities.messageOptions.newConversation` is present.", + "anyOf": [ + { + "type": "string", + "const": "active" + }, + { + "type": "string", + "const": "new" + } + ] } }, "required": ["role", "content"], diff --git a/src/generated/schema.ts b/src/generated/schema.ts index 214b227c2..2f531f46f 100644 --- a/src/generated/schema.ts +++ b/src/generated/schema.ts @@ -563,6 +563,26 @@ export const McpUiHostCapabilitiesSchema = z.object({ message: McpUiSupportedContentBlockModalitiesSchema.optional().describe( "Host supports receiving content messages (ui/message) from the view.", ), + /** @description Host supports the `send` and `target` options of ui/message. */ + messageOptions: z + .object({ + /** @description Host supports `send: false` with `target: "active"`: add the content to the current draft. */ + draft: z + .object({}) + .optional() + .describe( + 'Host supports `send: false` with `target: "active"`: add the content to the current draft.', + ), + /** @description Host supports `target: "new"`. With `draft` also present, `send: false` opens an editable draft in a new conversation. */ + newConversation: z + .object({}) + .optional() + .describe( + 'Host supports `target: "new"`. With `draft` also present, `send: false` opens an editable draft in a new conversation.', + ), + }) + .optional() + .describe("Host supports the `send` and `target` options of ui/message."), /** * @description Host supports LLM sampling (sampling/createMessage) from the view. * Mirrors the MCP `ClientCapabilities.sampling` shape so hosts can pass it through. @@ -809,6 +829,28 @@ export const McpUiMessageRequestSchema = z.object({ content: z .array(ContentBlockSchema) .describe("Message content blocks (text, image, etc.)."), + /** + * @description Whether to send the message. `false` adds the content to the user's draft without sending it. Default: `true`. + * + * Only set `false` when `hostCapabilities.messageOptions` advertises the matching option: hosts that do not support it send the message. + */ + send: z + .boolean() + .optional() + .describe( + "Whether to send the message. `false` adds the content to the user's draft without sending it. Default: `true`.\n\nOnly set `false` when `hostCapabilities.messageOptions` advertises the matching option: hosts that do not support it send the message.", + ), + /** + * @description Conversation that receives the message: `"active"`, the one that contains the View (default), or `"new"`, a new conversation. + * + * Only set `"new"` when `hostCapabilities.messageOptions.newConversation` is present. + */ + target: z + .union([z.literal("active"), z.literal("new")]) + .optional() + .describe( + 'Conversation that receives the message: `"active"`, the one that contains the View (default), or `"new"`, a new conversation.\n\nOnly set `"new"` when `hostCapabilities.messageOptions.newConversation` is present.', + ), }), }); diff --git a/src/spec.types.ts b/src/spec.types.ts index 0c4539637..5bf9d784b 100644 --- a/src/spec.types.ts +++ b/src/spec.types.ts @@ -212,6 +212,18 @@ export interface McpUiMessageRequest { role: "user"; /** @description Message content blocks (text, image, etc.). */ content: ContentBlock[]; + /** + * @description Whether to send the message. `false` adds the content to the user's draft without sending it. Default: `true`. + * + * Only set `false` when `hostCapabilities.messageOptions` advertises the matching option: hosts that do not support it send the message. + */ + send?: boolean; + /** + * @description Conversation that receives the message: `"active"`, the one that contains the View (default), or `"new"`, a new conversation. + * + * Only set `"new"` when `hostCapabilities.messageOptions.newConversation` is present. + */ + target?: "active" | "new"; }; } @@ -521,6 +533,13 @@ export interface McpUiHostCapabilities { updateModelContext?: McpUiSupportedContentBlockModalities; /** @description Host supports receiving content messages (ui/message) from the view. */ message?: McpUiSupportedContentBlockModalities; + /** @description Host supports the `send` and `target` options of ui/message. */ + messageOptions?: { + /** @description Host supports `send: false` with `target: "active"`: add the content to the current draft. */ + draft?: {}; + /** @description Host supports `target: "new"`. With `draft` also present, `send: false` opens an editable draft in a new conversation. */ + newConversation?: {}; + }; /** * @description Host supports LLM sampling (sampling/createMessage) from the view. * Mirrors the MCP `ClientCapabilities.sampling` shape so hosts can pass it through.