docs: standardize UI terminology to use "view" consistently (#325)
* docs: standardize UI terminology to use "view" consistently Replaces "widget" and "Guest UI" terminology with "view" across the codebase as decided in the community survey. This change updates: - Specification document - SDK source code and JSDoc comments - Example servers and documentation - Plugin documentation and skills Closes #71 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Liad Yosef
GitHub
parent
9e42ee05a3
commit
4fc71656a3
1 changed files with 381 additions and 393 deletions
|
|
@ -195,9 +195,9 @@ interface UIResourceMeta {
|
|||
clipboardWrite?: {},
|
||||
},
|
||||
/**
|
||||
* Dedicated origin for widget
|
||||
* Dedicated origin for view
|
||||
*
|
||||
* Optional domain for the widget's sandbox origin. Useful when widgets need
|
||||
* Optional domain for the view's sandbox origin. Useful when views need
|
||||
* stable, dedicated origins for OAuth callbacks, CORS policies, or API key allowlists.
|
||||
*
|
||||
* **Host-dependent:** The format and validation rules for this field are
|
||||
|
|
@ -291,7 +291,7 @@ Example:
|
|||
{
|
||||
"uri": "ui://weather-server/dashboard-template",
|
||||
"name": "weather_dashboard",
|
||||
"description": "Interactive weather dashboard widget",
|
||||
"description": "Interactive weather dashboard view",
|
||||
"mimeType": "text/html;profile=mcp-app"
|
||||
}
|
||||
|
||||
|
|
@ -417,7 +417,7 @@ Conceptually, UI iframes act as MCP clients, connecting to the host via a `postM
|
|||
```typescript
|
||||
// UI iframe initializes MCP client
|
||||
const transport = new MessageTransport(window.parent);
|
||||
const client = new Client({ name: "ui-widget", version: "1.0.0" });
|
||||
const client = new Client({ name: "ui-view", version: "1.0.0" });
|
||||
await client.connect(transport);
|
||||
```
|
||||
|
||||
|
|
@ -467,22 +467,22 @@ Hosts act as MCP servers (that can proxy the actual MCP server), receiving and h
|
|||
|
||||
### Sandbox proxy
|
||||
|
||||
If the Host is a web page, it MUST wrap the Guest UI and communicate with it through an intermediate Sandbox proxy.
|
||||
If the Host is a web page, it MUST wrap the View and communicate with it through an intermediate Sandbox proxy.
|
||||
|
||||
1. The Host and the Sandbox MUST have different origins.
|
||||
2. The Sandbox MUST have the following permissions: `allow-scripts`, `allow-same-origin`.
|
||||
3. The Sandbox MUST send a `ui/notifications/sandbox-proxy-ready` notification to the host when it's ready to process an `ui/notifications/sandbox-resource-ready` notification.
|
||||
4. Once the Sandbox is ready, the Host MUST send the raw HTML resource to load in a `ui/notifications/sandbox-resource-ready` notification.
|
||||
5. The Sandbox MUST load the raw HTML of the Guest UI with CSP settings that:
|
||||
5. The Sandbox MUST load the raw HTML of the View with CSP settings that:
|
||||
- Enforce the domains declared in `ui.csp` metadata
|
||||
- If `frameDomains` is provided, allow nested iframes from declared origins; otherwise use `frame-src 'none'`
|
||||
- If `baseUriDomains` is provided, allow base URIs from declared origins; otherwise use `base-uri 'self'`
|
||||
- Block dangerous features (`object-src 'none'`)
|
||||
- Apply restrictive defaults if no CSP metadata is provided
|
||||
- If `permissions` is declared, the Sandbox MAY set the inner iframe's `allow` attribute accordingly
|
||||
6. The Sandbox MUST forward messages sent by the Host to the Guest UI, and vice versa, for any method that doesn’t start with `ui/notifications/sandbox-`. This includes lifecycle messages, e.g., `ui/initialize` request & `ui/notifications/initialized` notification both sent by the Guest UI. The Host MUST NOT send any request or notification to the Guest UI before it receives an `initialized` notification.
|
||||
7. The Sandbox SHOULD NOT create/send any requests to the Host or to the Guest UI (this would require synthesizing new request ids).
|
||||
8. The Host MAY forward any message from the Guest UI (coming via the Sandbox) to the MCP Apps server, for any method that doesn’t start with `ui/`. While the Host SHOULD ensure the Guest UI’s MCP connection is spec-compliant, it MAY decide to block some messages or subject them to further user approval.
|
||||
6. The Sandbox MUST forward messages sent by the Host to the View, and vice versa, for any method that doesn't start with `ui/notifications/sandbox-`. This includes lifecycle messages, e.g., `ui/initialize` request & `ui/notifications/initialized` notification both sent by the View. The Host MUST NOT send any request or notification to the View before it receives an `initialized` notification.
|
||||
7. The Sandbox SHOULD NOT create/send any requests to the Host or to the View (this would require synthesizing new request ids).
|
||||
8. The Host MAY forward any message from the View (coming via the Sandbox) to the MCP Apps server, for any method that doesn't start with `ui/`. While the Host SHOULD ensure the View's MCP connection is spec-compliant, it MAY decide to block some messages or subject them to further user approval.
|
||||
|
||||
### Standard MCP Messages
|
||||
|
||||
|
|
@ -507,7 +507,7 @@ UI iframes can use the following subset of standard MCP protocol messages:
|
|||
|
||||
### Host Context in `McpUiInitializeResult`
|
||||
|
||||
When the Guest UI sends an `ui/initialize` request to the Host, the Host SHOULD include UI-specific context in the `McpUiInitializeResult`'s `hostContext` field:
|
||||
When the View sends an `ui/initialize` request to the Host, the Host SHOULD include UI-specific context in the `McpUiInitializeResult`'s `hostContext` field:
|
||||
|
||||
```typescript
|
||||
interface HostContext {
|
||||
|
|
@ -598,7 +598,7 @@ Example:
|
|||
|
||||
### Host Capabilities
|
||||
|
||||
`HostCapabilities` are sent to the Guest UI as part of the response to `ui/initialize` (inside `McpUiInitializeResult`).
|
||||
`HostCapabilities` are sent to the View as part of the response to `ui/initialize` (inside `McpUiInitializeResult`).
|
||||
They describe the features and capabilities that the Host supports.
|
||||
|
||||
```typescript
|
||||
|
|
@ -983,9 +983,9 @@ Host behavior:
|
|||
* If the requested mode is not available, Host SHOULD return the current display mode in the response.
|
||||
* Host MAY coerce modes on certain platforms (e.g., "pip" to "fullscreen" on mobile).
|
||||
|
||||
Guest UI behavior:
|
||||
* Guest UI SHOULD check `availableDisplayModes` in host context before requesting a mode change.
|
||||
* Guest UI MUST handle the response mode differing from the requested mode.
|
||||
View behavior:
|
||||
* View SHOULD check `availableDisplayModes` in host context before requesting a mode change.
|
||||
* View MUST handle the response mode differing from the requested mode.
|
||||
|
||||
`ui/update-model-context` - Update the model context
|
||||
|
||||
|
|
@ -1019,7 +1019,7 @@ Guest UI behavior:
|
|||
}
|
||||
```
|
||||
|
||||
Guest UI MAY send this request to update the Host's model context. This context will be used in future turns. Each request overwrites the previous context sent by the Guest UI.
|
||||
The View MAY send this request to update the Host's model context. This context will be used in future turns. Each request overwrites the previous context sent by the View.
|
||||
This event serves a different use case from `notifications/message` (logging) and `ui/message` (which also trigger follow-ups).
|
||||
|
||||
Host behavior:
|
||||
|
|
@ -1032,7 +1032,7 @@ Host behavior:
|
|||
|
||||
#### Notifications (Host → UI)
|
||||
|
||||
`ui/notifications/tool-input` - Host MUST send this notification with the complete tool arguments after the Guest UI's initialize request completes.
|
||||
`ui/notifications/tool-input` - Host MUST send this notification with the complete tool arguments after the View's initialize request completes.
|
||||
|
||||
```typescript
|
||||
{
|
||||
|
|
@ -1044,7 +1044,7 @@ Host behavior:
|
|||
}
|
||||
```
|
||||
|
||||
Host sends this notification after the Guest UI's initialize request completes, when tool arguments become available. This notification is sent at most once and is required before sending `ui/notifications/tool-result`.
|
||||
Host sends this notification after the View's initialize request completes, when tool arguments become available. This notification is sent at most once and is required before sending `ui/notifications/tool-result`.
|
||||
|
||||
`ui/notifications/tool-input-partial` - Host MAY send this notification zero or more times while the agent is streaming tool arguments, before `ui/notifications/tool-input` is sent.
|
||||
|
||||
|
|
@ -1064,7 +1064,7 @@ The arguments object represents best-effort recovery of incomplete JSON, with un
|
|||
- MAY send recovered arguments as they become available during streaming
|
||||
- MUST stop sending once `ui/notifications/tool-input` is sent with complete arguments
|
||||
|
||||
Guest UI behavior (optional):
|
||||
View behavior (optional):
|
||||
|
||||
- MAY ignore these notifications entirely
|
||||
- MAY render progressive loading/streaming states based on available fields
|
||||
|
|
@ -1143,7 +1143,7 @@ Host SHOULD wait for a response before tearing down the resource (to prevent dat
|
|||
}
|
||||
```
|
||||
|
||||
Guest UI SHOULD send this notification when rendered content body size changes (e.g. using ResizeObserver API to report up to date size).
|
||||
The View SHOULD send this notification when rendered content body size changes (e.g. using ResizeObserver API to report up to date size).
|
||||
|
||||
`ui/notifications/host-context-changed` - Host context has changed
|
||||
|
||||
|
|
@ -1155,7 +1155,7 @@ Guest UI SHOULD send this notification when rendered content body size changes (
|
|||
}
|
||||
```
|
||||
|
||||
Host MAY send this notification when any context field changes (e.g., theme toggle, display mode change, device orientation change, window/panel resize). This notification contains partial updates - Guest UI SHOULD merge received fields with its current context state.
|
||||
Host MAY send this notification when any context field changes (e.g., theme toggle, display mode change, device orientation change, window/panel resize). This notification contains partial updates - the View SHOULD merge received fields with its current context state.
|
||||
|
||||
#### Reserved Messages (Sandbox Proxy)
|
||||
|
||||
|
|
@ -1219,7 +1219,7 @@ sequenceDiagram
|
|||
```mermaid
|
||||
sequenceDiagram
|
||||
participant H as Host
|
||||
participant UI as Guest UI (iframe)
|
||||
participant UI as View (iframe)
|
||||
participant P as Sandbox Proxy
|
||||
participant S as MCP Server
|
||||
|
||||
|
|
@ -1228,7 +1228,7 @@ sequenceDiagram
|
|||
H ->> S: tools/call to Tool with _meta.ui metadata
|
||||
and UI initialization
|
||||
alt Desktop/Native hosts
|
||||
H ->> H: Render Guest UI in an iframe (HTML from the ui:// resource)
|
||||
H ->> H: Render View in an iframe (HTML from the ui:// resource)
|
||||
else Web hosts
|
||||
H ->> H: Render Sandbox Proxy in an iframe (different origin)
|
||||
P ->> H: ui/notifications/sandbox-proxy-ready
|
||||
|
|
@ -1251,7 +1251,7 @@ sequenceDiagram
|
|||
end
|
||||
```
|
||||
|
||||
Note: when the Guest UI is rendered inside a sandbox, the sandbox transparently passes messages between the Guest UI and the Host, except for messages named `ui/notifications/sandbox-*`.
|
||||
Note: when the View is rendered inside a sandbox, the sandbox transparently passes messages between the View and the Host, except for messages named `ui/notifications/sandbox-*`.
|
||||
|
||||
#### 3. Interactive Phase
|
||||
|
||||
|
|
@ -1259,7 +1259,7 @@ Note: when the Guest UI is rendered inside a sandbox, the sandbox transparently
|
|||
sequenceDiagram
|
||||
actor U as User / Agent
|
||||
participant H as Host
|
||||
participant UI as Guest UI (iframe)
|
||||
participant UI as View (iframe)
|
||||
participant S as MCP Server
|
||||
loop Interactive phase
|
||||
U ->> UI: interaction (e.g., click)
|
||||
|
|
@ -1302,7 +1302,7 @@ sequenceDiagram
|
|||
```mermaid
|
||||
sequenceDiagram
|
||||
participant H as Host
|
||||
participant UI as Guest UI (iframe)
|
||||
participant UI as View (iframe)
|
||||
H ->> UI: ui/resource-teardown
|
||||
UI --> UI: Graceful termination
|
||||
UI -->> H: ui/resource-teardown response
|
||||
|
|
@ -1414,7 +1414,7 @@ await client.callTool("get_weather", { location: "New York" });
|
|||
// Result returned via standard tools/call response
|
||||
```
|
||||
|
||||
This pattern enables interactive, self-updating widgets.
|
||||
This pattern enables interactive, self-updating views.
|
||||
|
||||
Note: Tools with `visibility: ["app"]` are hidden from the agent but remain callable by apps via `tools/call`. This enables UI-only interactions (refresh buttons, form submissions) without exposing implementation details to the model. See the Visibility section under Resource Discovery for details.
|
||||
|
||||
|
|
@ -1501,7 +1501,7 @@ This specification defines the Minimum Viable Product (MVP) for MCP Apps. Future
|
|||
- Support multiple UI resources in a tool response
|
||||
- State persistence and restoration
|
||||
- Custom sandbox policies per resource
|
||||
- Widget-to-widget communication
|
||||
- View-to-View communication
|
||||
- Screenshot/preview generation APIs
|
||||
|
||||
## Rationale
|
||||
|
|
|
|||
Loading…
Reference in a new issue