From ed3384690b276f34155a3804668b9e8e71268cfb Mon Sep 17 00:00:00 2001 From: Enrique Moreno <403428+chuwik@users.noreply.github.com> Date: Thu, 19 Nov 2026 14:27:33 -0800 Subject: [PATCH] spec(draft): let servers offer composer mentions through a read-only search tool Adds a mentions setting to the server's io.modelcontextprotocol/ui extension settings that names a read-only tool hosts can call to offer per-item @-mentions in the composer, with the tool's argument and result shapes. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com> --- specification/draft/apps.mdx | 73 ++++++++++++++++++++ src/generated/schema.json | 125 +++++++++++++++++++++++++++++++++++ src/generated/schema.test.ts | 30 +++++++++ src/generated/schema.ts | 47 +++++++++++++ src/spec.types.ts | 36 ++++++++++ src/types.ts | 3 + 6 files changed, 314 insertions(+) diff --git a/specification/draft/apps.mdx b/specification/draft/apps.mdx index bbf486e13..32dbaed7b 100644 --- a/specification/draft/apps.mdx +++ b/specification/draft/apps.mdx @@ -2235,6 +2235,74 @@ A tool's return value `v` becomes `{ "content": [], "structuredContent": v }` wh See [ext-apps#35](https://github.com/modelcontextprotocol/ext-apps/issues/35), [ext-apps#796](https://github.com/modelcontextprotocol/ext-apps/issues/796) and [ext-apps#797](https://github.com/modelcontextprotocol/ext-apps/issues/797) for discussion. +### Composer Mentions + +Hosts often let users mention a server in the composer. A server can also let users mention the items inside it (a person, a file, a ticket, a part) by naming one of its tools as a mention search tool. The Host calls that tool as the user types, shows the results in its mention picker, and adds the picked item to the user's message. + +#### Server Declaration + +The server names the tool in its extension settings: + +```json +{ + "capabilities": { + "extensions": { + "io.modelcontextprotocol/ui": { + "mentions": { "searchTool": "parts_mention_search" } + } + } + } +} +``` + +```typescript +interface McpUiServerCapabilities { + mentions?: { + /** Name of a read-only tool on this server that searches mentionable items. */ + searchTool: string; + }; +} +``` + +#### Search Tool + +```typescript +// Tool arguments +interface McpUiMentionSearchParams { + /** What the user has typed after the mention trigger. May be empty. */ + query: string; +} + +// Tool result structuredContent +interface McpUiMentionSearchResult { + /** Items the user can mention, best match first. */ + items: ResourceLink[]; +} +``` + +```json +// tools/call result +{ + "content": [{ "type": "text", "text": "{\"items\":[...]}" }], + "structuredContent": { + "items": [ + { "type": "resource_link", "uri": "cad://parts/m8-hex-bolt", "name": "m8-hex-bolt", "title": "M8 hex bolt" } + ] + } +} +``` + +Server behavior: +- The tool named by `searchTool` MUST exist on the server, MUST set `annotations.readOnlyHint` to `true`, and MUST accept `{ query: string }` with no other required arguments. +- The tool SHOULD set `_meta.ui.visibility` to `["app"]`, so that it stays out of the model's tool list. + +Host behavior: +- Host MAY offer the server's items in its mention picker, calling `searchTool` with the text the user has typed. These calls are made by the Host, not the model, and do not depend on the tool's visibility. +- Host MUST send only the mention query to the server, never the rest of the user's draft. Host SHOULD debounce calls and SHOULD only query servers the user has enabled. +- When the user picks an item, Host adds it to the user's message as a `resource_link` content block and MAY show it as a chip. Host MAY resolve it with `resources/read` on the same server, and MUST NOT resolve it through a different server. +- Host MUST render item names and titles as plain text. +- Host applies its usual tool policy to these calls. Since the user starts the search and the tool is declared read-only, Host MAY skip per-call approval. + ### Client\<\>Server Capability Negotiation Clients and servers negotiate MCP Apps support through the standard MCP extensions capability mechanism (defined in SEP-1724). @@ -2299,6 +2367,10 @@ if (uiCap?.mimeTypes?.includes(RESOURCE_MIME_TYPE)) { } ``` +**Server Settings:** + +Servers MAY advertise MCP Apps settings under the same extension identifier in their own capabilities. The only setting defined today is `mentions` (see [Composer Mentions](#composer-mentions)). + **Graceful Degradation:** - Servers SHOULD provide text-only fallback behavior for all UI-enabled tools @@ -2705,6 +2777,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. +- **Mention search:** A mention search tool receives what the user types after the mention trigger. Hosts send only that text, only to servers the user has enabled, and treat the returned items as untrusted server data. - **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..d3c585a6e 100644 --- a/src/generated/schema.json +++ b/src/generated/schema.json @@ -3752,6 +3752,113 @@ "required": ["method"], "additionalProperties": false }, + "McpUiMentionSearchParams": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "query": { + "type": "string", + "description": "What the user has typed after the mention trigger. May be empty." + } + }, + "required": ["query"], + "additionalProperties": false + }, + "McpUiMentionSearchResult": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "items": { + "type": "array", + "items": { + "type": "object", + "properties": { + "name": { + "type": "string" + }, + "title": { + "type": "string" + }, + "icons": { + "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 + } + }, + "uri": { + "type": "string" + }, + "description": { + "type": "string" + }, + "mimeType": { + "type": "string" + }, + "size": { + "type": "number" + }, + "annotations": { + "type": "object", + "properties": { + "audience": { + "type": "array", + "items": { + "type": "string", + "enum": ["user", "assistant"] + } + }, + "priority": { + "type": "number", + "minimum": 0, + "maximum": 1 + }, + "lastModified": { + "type": "string", + "format": "date-time", + "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" + } + }, + "additionalProperties": false + }, + "_meta": { + "type": "object", + "properties": {}, + "additionalProperties": {} + }, + "type": { + "type": "string", + "const": "resource_link" + } + }, + "required": ["name", "uri", "type"], + "additionalProperties": false + }, + "description": "Items the user can mention, best match first." + } + }, + "required": ["items"], + "additionalProperties": false + }, "McpUiMessageRequest": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", @@ -4501,6 +4608,24 @@ "required": ["method", "params"], "additionalProperties": false }, + "McpUiServerCapabilities": { + "$schema": "https://json-schema.org/draft/2020-12/schema", + "type": "object", + "properties": { + "mentions": { + "description": "The server offers per-item composer mentions through one of its tools.", + "type": "object", + "properties": { + "searchTool": { + "type": "string" + } + }, + "required": ["searchTool"], + "additionalProperties": false + } + }, + "additionalProperties": false + }, "McpUiSizeChangedNotification": { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", diff --git a/src/generated/schema.test.ts b/src/generated/schema.test.ts index 57d989fd0..929cd156d 100644 --- a/src/generated/schema.test.ts +++ b/src/generated/schema.test.ts @@ -131,6 +131,14 @@ export type McpUiClientCapabilitiesSchemaInferredType = z.infer< typeof generated.McpUiClientCapabilitiesSchema >; +export type McpUiServerCapabilitiesSchemaInferredType = z.infer< + typeof generated.McpUiServerCapabilitiesSchema +>; + +export type McpUiMentionSearchParamsSchemaInferredType = z.infer< + typeof generated.McpUiMentionSearchParamsSchema +>; + export type McpUiDownloadFileRequestSchemaInferredType = z.infer< typeof generated.McpUiDownloadFileRequestSchema >; @@ -167,6 +175,10 @@ export type McpUiInitializeResultSchemaInferredType = z.infer< typeof generated.McpUiInitializeResultSchema >; +export type McpUiMentionSearchResultSchemaInferredType = z.infer< + typeof generated.McpUiMentionSearchResultSchema +>; + expectType({} as McpUiThemeSchemaInferredType); expectType({} as spec.McpUiTheme); expectType({} as McpUiDisplayModeSchemaInferredType); @@ -311,6 +323,18 @@ expectType( expectType( {} as spec.McpUiClientCapabilities, ); +expectType( + {} as McpUiServerCapabilitiesSchemaInferredType, +); +expectType( + {} as spec.McpUiServerCapabilities, +); +expectType( + {} as McpUiMentionSearchParamsSchemaInferredType, +); +expectType( + {} as spec.McpUiMentionSearchParams, +); expectType( {} as McpUiDownloadFileRequestSchemaInferredType, ); @@ -361,3 +385,9 @@ expectType( expectType( {} as spec.McpUiInitializeResult, ); +expectType( + {} as McpUiMentionSearchResultSchemaInferredType, +); +expectType( + {} as spec.McpUiMentionSearchResult, +); diff --git a/src/generated/schema.ts b/src/generated/schema.ts index 214b227c2..4ef4318af 100644 --- a/src/generated/schema.ts +++ b/src/generated/schema.ts @@ -772,6 +772,42 @@ export const McpUiClientCapabilitiesSchema = z.object({ ), }); +/** + * @description MCP Apps settings advertised by servers to clients. + * + * Servers advertise these under `capabilities.extensions["io.modelcontextprotocol/ui"]`. + */ +export const McpUiServerCapabilitiesSchema = z.object({ + /** + * @description The server offers per-item composer mentions through one of its tools. + */ + mentions: z + .object({ + /** + * @description Name of a read-only tool on this server that searches mentionable items. + * It takes {@link McpUiMentionSearchParams `McpUiMentionSearchParams`} and returns {@link McpUiMentionSearchResult `McpUiMentionSearchResult`} as `structuredContent`. + */ + searchTool: z.string(), + }) + .optional() + .describe( + "The server offers per-item composer mentions through one of its tools.", + ), +}); + +/** + * @description Arguments of a server's mention search tool. + * @see {@link McpUiServerCapabilities `McpUiServerCapabilities`} + */ +export const McpUiMentionSearchParamsSchema = z.object({ + /** @description What the user has typed after the mention trigger. May be empty. */ + query: z + .string() + .describe( + "What the user has typed after the mention trigger. May be empty.", + ), +}); + /** * @description Request to download a file through the host. * @@ -1056,3 +1092,14 @@ export const McpUiInitializeResultSchema = z ), }) .passthrough(); + +/** + * @description `structuredContent` returned by a server's mention search tool. + * @see {@link McpUiServerCapabilities `McpUiServerCapabilities`} + */ +export const McpUiMentionSearchResultSchema = z.object({ + /** @description Items the user can mention, best match first. */ + items: z + .array(ResourceLinkSchema) + .describe("Items the user can mention, best match first."), +}); diff --git a/src/spec.types.ts b/src/spec.types.ts index 0c4539637..8ae541bea 100644 --- a/src/spec.types.ts +++ b/src/spec.types.ts @@ -856,3 +856,39 @@ export interface McpUiClientCapabilities { */ mimeTypes?: string[]; } + +/** + * @description MCP Apps settings advertised by servers to clients. + * + * Servers advertise these under `capabilities.extensions["io.modelcontextprotocol/ui"]`. + */ +export interface McpUiServerCapabilities { + /** + * @description The server offers per-item composer mentions through one of its tools. + */ + mentions?: { + /** + * @description Name of a read-only tool on this server that searches mentionable items. + * It takes {@link McpUiMentionSearchParams `McpUiMentionSearchParams`} and returns {@link McpUiMentionSearchResult `McpUiMentionSearchResult`} as `structuredContent`. + */ + searchTool: string; + }; +} + +/** + * @description Arguments of a server's mention search tool. + * @see {@link McpUiServerCapabilities `McpUiServerCapabilities`} + */ +export interface McpUiMentionSearchParams { + /** @description What the user has typed after the mention trigger. May be empty. */ + query: string; +} + +/** + * @description `structuredContent` returned by a server's mention search tool. + * @see {@link McpUiServerCapabilities `McpUiServerCapabilities`} + */ +export interface McpUiMentionSearchResult { + /** @description Items the user can mention, best match first. */ + items: ResourceLink[]; +} diff --git a/src/types.ts b/src/types.ts index e4ed629c4..5ff4ef19b 100644 --- a/src/types.ts +++ b/src/types.ts @@ -116,6 +116,9 @@ export { type McpUiToolVisibility, type McpUiToolMeta, type McpUiClientCapabilities, + type McpUiServerCapabilities, + type McpUiMentionSearchParams, + type McpUiMentionSearchResult, } from "./spec.types.js"; // Re-export all schemas from generated/schema.ts (already PascalCase)