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
|
|
@ -159,7 +159,7 @@ export function buildAllowAttribute(
|
|||
/**
|
||||
* Options for configuring {@link AppBridge `AppBridge`} behavior.
|
||||
*
|
||||
* @property hostContext - Optional initial host context to provide to the Guest UI
|
||||
* @property hostContext - Optional initial host context to provide to the view
|
||||
*
|
||||
* @see `ProtocolOptions` from @modelcontextprotocol/sdk for available options
|
||||
* @see {@link McpUiHostContext `McpUiHostContext`} for the hostContext structure
|
||||
|
|
@ -190,27 +190,27 @@ type RequestHandlerExtra = Parameters<
|
|||
>[1];
|
||||
|
||||
/**
|
||||
* Host-side bridge for communicating with a single Guest UI ({@link app!App `App`}).
|
||||
* Host-side bridge for communicating with a single View ({@link app!App `App`}).
|
||||
*
|
||||
* `AppBridge` extends the MCP SDK's `Protocol` class and acts as a proxy between
|
||||
* the host application and a Guest UI running in an iframe. When an MCP client
|
||||
* the host application and a view running in an iframe. When an MCP client
|
||||
* is provided to the constructor, it automatically forwards MCP server capabilities
|
||||
* (tools, resources, prompts) to the Guest UI. It also handles the initialization
|
||||
* (tools, resources, prompts) to the view. It also handles the initialization
|
||||
* handshake.
|
||||
*
|
||||
* ## Architecture
|
||||
*
|
||||
* **Guest UI ↔ AppBridge ↔ Host ↔ MCP Server**
|
||||
* **View ↔ AppBridge ↔ Host ↔ MCP Server**
|
||||
*
|
||||
* The bridge proxies requests from the Guest UI to the MCP server and forwards
|
||||
* The bridge proxies requests from the view to the MCP server and forwards
|
||||
* responses back. It also sends host-initiated notifications like tool input
|
||||
* and results to the Guest UI.
|
||||
* and results to the view.
|
||||
*
|
||||
* ## Lifecycle
|
||||
*
|
||||
* 1. **Create**: Instantiate `AppBridge` with MCP client and capabilities
|
||||
* 2. **Connect**: Call `connect()` with transport to establish communication
|
||||
* 3. **Wait for init**: Guest UI sends initialize request, bridge responds
|
||||
* 3. **Wait for init**: View sends initialize request, bridge responds
|
||||
* 4. **Send data**: Call {@link sendToolInput `sendToolInput`}, {@link sendToolResult `sendToolResult`}, etc.
|
||||
* 5. **Teardown**: Call {@link teardownResource `teardownResource`} before unmounting iframe
|
||||
*
|
||||
|
|
@ -231,7 +231,7 @@ export class AppBridge extends Protocol<
|
|||
*
|
||||
* @param _client - MCP client connected to the server, or `null`. When provided,
|
||||
* {@link connect `connect`} will automatically set up forwarding of MCP requests/notifications
|
||||
* between the Guest UI and the server. When `null`, you must register handlers
|
||||
* between the View and the server. When `null`, you must register handlers
|
||||
* manually using the {@link oncalltool `oncalltool`}, {@link onlistresources `onlistresources`}, etc. setters.
|
||||
* @param _hostInfo - Host application identification (name and version)
|
||||
* @param _capabilities - Features and capabilities the host supports
|
||||
|
|
@ -271,15 +271,15 @@ export class AppBridge extends Protocol<
|
|||
}
|
||||
|
||||
/**
|
||||
* Get the Guest UI's capabilities discovered during initialization.
|
||||
* Get the view's capabilities discovered during initialization.
|
||||
*
|
||||
* Returns the capabilities that the Guest UI advertised during its
|
||||
* Returns the capabilities that the view advertised during its
|
||||
* initialization request. Returns `undefined` if called before
|
||||
* initialization completes.
|
||||
*
|
||||
* @returns Guest UI capabilities, or `undefined` if not yet initialized
|
||||
* @returns view capabilities, or `undefined` if not yet initialized
|
||||
*
|
||||
* @example Check Guest UI capabilities after initialization
|
||||
* @example Check view capabilities after initialization
|
||||
* {@includeCode ./app-bridge.examples.ts#AppBridge_getAppCapabilities_checkAfterInit}
|
||||
*
|
||||
* @see {@link McpUiAppCapabilities `McpUiAppCapabilities`} for the capabilities structure
|
||||
|
|
@ -289,14 +289,14 @@ export class AppBridge extends Protocol<
|
|||
}
|
||||
|
||||
/**
|
||||
* Get the Guest UI's implementation info discovered during initialization.
|
||||
* Get the view's implementation info discovered during initialization.
|
||||
*
|
||||
* Returns the Guest UI's name and version as provided in its initialization
|
||||
* Returns the view's name and version as provided in its initialization
|
||||
* request. Returns `undefined` if called before initialization completes.
|
||||
*
|
||||
* @returns Guest UI implementation info, or `undefined` if not yet initialized
|
||||
* @returns view implementation info, or `undefined` if not yet initialized
|
||||
*
|
||||
* @example Log Guest UI information after initialization
|
||||
* @example Log view information after initialization
|
||||
* {@includeCode ./app-bridge.examples.ts#AppBridge_getAppVersion_logAfterInit}
|
||||
*/
|
||||
getAppVersion(): Implementation | undefined {
|
||||
|
|
@ -304,9 +304,9 @@ export class AppBridge extends Protocol<
|
|||
}
|
||||
|
||||
/**
|
||||
* Optional handler for ping requests from the Guest UI.
|
||||
* Optional handler for ping requests from the view.
|
||||
*
|
||||
* The Guest UI can send standard MCP `ping` requests to verify the connection
|
||||
* The View can send standard MCP `ping` requests to verify the connection
|
||||
* is alive. The {@link AppBridge `AppBridge`} automatically responds with an empty object, but this
|
||||
* handler allows the host to observe or log ping activity.
|
||||
*
|
||||
|
|
@ -322,20 +322,20 @@ export class AppBridge extends Protocol<
|
|||
onping?: (params: PingRequest["params"], extra: RequestHandlerExtra) => void;
|
||||
|
||||
/**
|
||||
* Register a handler for size change notifications from the Guest UI.
|
||||
* Register a handler for size change notifications from the view.
|
||||
*
|
||||
* The Guest UI sends `ui/notifications/size-changed` when its rendered content
|
||||
* The view sends `ui/notifications/size-changed` when its rendered content
|
||||
* size changes, typically via `ResizeObserver`. Set this callback to dynamically
|
||||
* adjust the iframe container dimensions based on the Guest UI's content.
|
||||
* adjust the iframe container dimensions based on the view's content.
|
||||
*
|
||||
* Note: This is for Guest UI → Host communication. To notify the Guest UI of
|
||||
* Note: This is for View → Host communication. To notify the View of
|
||||
* host container dimension changes, use {@link setHostContext `setHostContext`}.
|
||||
*
|
||||
* @example
|
||||
* {@includeCode ./app-bridge.examples.ts#AppBridge_onsizechange_handleResize}
|
||||
*
|
||||
* @see {@link McpUiSizeChangedNotification `McpUiSizeChangedNotification`} for the notification type
|
||||
* @see {@link app!App.sendSizeChanged `App.sendSizeChanged`} - the Guest UI method that sends these notifications
|
||||
* @see {@link app!App.sendSizeChanged `App.sendSizeChanged`} - the View method that sends these notifications
|
||||
*/
|
||||
set onsizechange(
|
||||
callback: (params: McpUiSizeChangedNotification["params"]) => void,
|
||||
|
|
@ -384,16 +384,16 @@ export class AppBridge extends Protocol<
|
|||
}
|
||||
|
||||
/**
|
||||
* Called when the Guest UI completes initialization.
|
||||
* Called when the view completes initialization.
|
||||
*
|
||||
* Set this callback to be notified when the Guest UI has finished its
|
||||
* Set this callback to be notified when the view has finished its
|
||||
* initialization handshake and is ready to receive tool input and other data.
|
||||
*
|
||||
* @example
|
||||
* {@includeCode ./app-bridge.examples.ts#AppBridge_oninitialized_sendToolInput}
|
||||
*
|
||||
* @see {@link McpUiInitializedNotification `McpUiInitializedNotification`} for the notification type
|
||||
* @see {@link sendToolInput `sendToolInput`} for sending tool arguments to the Guest UI
|
||||
* @see {@link sendToolInput `sendToolInput`} for sending tool arguments to the View
|
||||
*/
|
||||
set oninitialized(
|
||||
callback: (params: McpUiInitializedNotification["params"]) => void,
|
||||
|
|
@ -404,9 +404,9 @@ export class AppBridge extends Protocol<
|
|||
}
|
||||
|
||||
/**
|
||||
* Register a handler for message requests from the Guest UI.
|
||||
* Register a handler for message requests from the view.
|
||||
*
|
||||
* The Guest UI sends `ui/message` requests when it wants to add a message to
|
||||
* The view sends `ui/message` requests when it wants to add a message to
|
||||
* the host's chat interface. This enables interactive apps to communicate with
|
||||
* the user through the conversation thread.
|
||||
*
|
||||
|
|
@ -442,9 +442,9 @@ export class AppBridge extends Protocol<
|
|||
}
|
||||
|
||||
/**
|
||||
* Register a handler for external link requests from the Guest UI.
|
||||
* Register a handler for external link requests from the view.
|
||||
*
|
||||
* The Guest UI sends `ui/open-link` requests when it wants to open an external
|
||||
* The view sends `ui/open-link` requests when it wants to open an external
|
||||
* URL in the host's default browser. The handler should validate the URL and
|
||||
* open it according to the host's security policy and user preferences.
|
||||
*
|
||||
|
|
@ -480,9 +480,9 @@ export class AppBridge extends Protocol<
|
|||
}
|
||||
|
||||
/**
|
||||
* Register a handler for display mode change requests from the Guest UI.
|
||||
* Register a handler for display mode change requests from the view.
|
||||
*
|
||||
* The Guest UI sends `ui/request-display-mode` requests when it wants to change
|
||||
* The view sends `ui/request-display-mode` requests when it wants to change
|
||||
* its display mode (e.g., from "inline" to "fullscreen"). The handler should
|
||||
* check if the requested mode is in `availableDisplayModes` from the host context,
|
||||
* update the display mode if supported, and return the actual mode that was set.
|
||||
|
|
@ -519,9 +519,9 @@ export class AppBridge extends Protocol<
|
|||
}
|
||||
|
||||
/**
|
||||
* Register a handler for logging messages from the Guest UI.
|
||||
* Register a handler for logging messages from the view.
|
||||
*
|
||||
* The Guest UI sends standard MCP `notifications/message` (logging) notifications
|
||||
* The view sends standard MCP `notifications/message` (logging) notifications
|
||||
* to report debugging information, errors, warnings, and other telemetry to the
|
||||
* host. The host can display these in a console, log them to a file, or send
|
||||
* them to a monitoring service.
|
||||
|
|
@ -549,10 +549,10 @@ export class AppBridge extends Protocol<
|
|||
}
|
||||
|
||||
/**
|
||||
* Register a handler for model context updates from the Guest UI.
|
||||
* Register a handler for model context updates from the view.
|
||||
*
|
||||
* The Guest UI sends `ui/update-model-context` requests to update the Host's
|
||||
* model context. Each request overwrites the previous context stored by the Guest UI.
|
||||
* The view sends `ui/update-model-context` requests to update the Host's
|
||||
* model context. Each request overwrites the previous context stored by the view.
|
||||
* Unlike logging messages, context updates are intended to be available to
|
||||
* the model in future turns. Unlike messages, context updates do not trigger follow-ups.
|
||||
*
|
||||
|
|
@ -580,9 +580,9 @@ export class AppBridge extends Protocol<
|
|||
}
|
||||
|
||||
/**
|
||||
* Register a handler for tool call requests from the Guest UI.
|
||||
* Register a handler for tool call requests from the view.
|
||||
*
|
||||
* The Guest UI sends `tools/call` requests to execute MCP server tools. This
|
||||
* The view sends `tools/call` requests to execute MCP server tools. This
|
||||
* handler allows the host to intercept and process these requests, typically
|
||||
* by forwarding them to the MCP server.
|
||||
*
|
||||
|
|
@ -609,10 +609,10 @@ export class AppBridge extends Protocol<
|
|||
}
|
||||
|
||||
/**
|
||||
* Notify the Guest UI that the MCP server's tool list has changed.
|
||||
* Notify the view that the MCP server's tool list has changed.
|
||||
*
|
||||
* The host sends `notifications/tools/list_changed` to the Guest UI when it
|
||||
* receives this notification from the MCP server. This allows the Guest UI
|
||||
* The host sends `notifications/tools/list_changed` to the view when it
|
||||
* receives this notification from the MCP server. This allows the view
|
||||
* to refresh its tool cache or UI accordingly.
|
||||
*
|
||||
* @param params - Optional notification params (typically empty)
|
||||
|
|
@ -635,9 +635,9 @@ export class AppBridge extends Protocol<
|
|||
}
|
||||
|
||||
/**
|
||||
* Register a handler for list resources requests from the Guest UI.
|
||||
* Register a handler for list resources requests from the view.
|
||||
*
|
||||
* The Guest UI sends `resources/list` requests to enumerate available MCP
|
||||
* The view sends `resources/list` requests to enumerate available MCP
|
||||
* resources. This handler allows the host to intercept and process these
|
||||
* requests, typically by forwarding them to the MCP server.
|
||||
*
|
||||
|
|
@ -667,9 +667,9 @@ export class AppBridge extends Protocol<
|
|||
}
|
||||
|
||||
/**
|
||||
* Register a handler for list resource templates requests from the Guest UI.
|
||||
* Register a handler for list resource templates requests from the view.
|
||||
*
|
||||
* The Guest UI sends `resources/templates/list` requests to enumerate available
|
||||
* The view sends `resources/templates/list` requests to enumerate available
|
||||
* MCP resource templates. This handler allows the host to intercept and process
|
||||
* these requests, typically by forwarding them to the MCP server.
|
||||
*
|
||||
|
|
@ -707,9 +707,9 @@ export class AppBridge extends Protocol<
|
|||
}
|
||||
|
||||
/**
|
||||
* Register a handler for read resource requests from the Guest UI.
|
||||
* Register a handler for read resource requests from the view.
|
||||
*
|
||||
* The Guest UI sends `resources/read` requests to retrieve the contents of an
|
||||
* The view sends `resources/read` requests to retrieve the contents of an
|
||||
* MCP resource. This handler allows the host to intercept and process these
|
||||
* requests, typically by forwarding them to the MCP server.
|
||||
*
|
||||
|
|
@ -739,10 +739,10 @@ export class AppBridge extends Protocol<
|
|||
}
|
||||
|
||||
/**
|
||||
* Notify the Guest UI that the MCP server's resource list has changed.
|
||||
* Notify the view that the MCP server's resource list has changed.
|
||||
*
|
||||
* The host sends `notifications/resources/list_changed` to the Guest UI when it
|
||||
* receives this notification from the MCP server. This allows the Guest UI
|
||||
* The host sends `notifications/resources/list_changed` to the view when it
|
||||
* receives this notification from the MCP server. This allows the view
|
||||
* to refresh its resource cache or UI accordingly.
|
||||
*
|
||||
* @param params - Optional notification params (typically empty)
|
||||
|
|
@ -767,9 +767,9 @@ export class AppBridge extends Protocol<
|
|||
}
|
||||
|
||||
/**
|
||||
* Register a handler for list prompts requests from the Guest UI.
|
||||
* Register a handler for list prompts requests from the view.
|
||||
*
|
||||
* The Guest UI sends `prompts/list` requests to enumerate available MCP
|
||||
* The view sends `prompts/list` requests to enumerate available MCP
|
||||
* prompts. This handler allows the host to intercept and process these
|
||||
* requests, typically by forwarding them to the MCP server.
|
||||
*
|
||||
|
|
@ -796,10 +796,10 @@ export class AppBridge extends Protocol<
|
|||
}
|
||||
|
||||
/**
|
||||
* Notify the Guest UI that the MCP server's prompt list has changed.
|
||||
* Notify the view that the MCP server's prompt list has changed.
|
||||
*
|
||||
* The host sends `notifications/prompts/list_changed` to the Guest UI when it
|
||||
* receives this notification from the MCP server. This allows the Guest UI
|
||||
* The host sends `notifications/prompts/list_changed` to the view when it
|
||||
* receives this notification from the MCP server. This allows the view
|
||||
* to refresh its prompt cache or UI accordingly.
|
||||
*
|
||||
* @param params - Optional notification params (typically empty)
|
||||
|
|
@ -899,14 +899,14 @@ export class AppBridge extends Protocol<
|
|||
}
|
||||
|
||||
/**
|
||||
* Update the host context and notify the Guest UI of changes.
|
||||
* Update the host context and notify the view of changes.
|
||||
*
|
||||
* Compares fields present in the new context with the current context and sends a
|
||||
* `ui/notifications/host-context-changed` notification containing only fields
|
||||
* that have been added or modified. If no fields have changed, no notification is sent.
|
||||
* The new context fully replaces the internal state.
|
||||
*
|
||||
* Common use cases include notifying the Guest UI when:
|
||||
* Common use cases include notifying the view when:
|
||||
* - Theme changes (light/dark mode toggle)
|
||||
* - Viewport size changes (window resize)
|
||||
* - Display mode changes (inline/fullscreen)
|
||||
|
|
@ -944,7 +944,7 @@ export class AppBridge extends Protocol<
|
|||
}
|
||||
|
||||
/**
|
||||
* Low-level method to notify the Guest UI of host context changes.
|
||||
* Low-level method to notify the view of host context changes.
|
||||
*
|
||||
* Most hosts should use {@link setHostContext `setHostContext`} instead, which automatically
|
||||
* detects changes and calls this method with only the modified fields.
|
||||
|
|
@ -962,9 +962,9 @@ export class AppBridge extends Protocol<
|
|||
}
|
||||
|
||||
/**
|
||||
* Send complete tool arguments to the Guest UI.
|
||||
* Send complete tool arguments to the view.
|
||||
*
|
||||
* The host MUST send this notification after the Guest UI completes initialization
|
||||
* The host MUST send this notification after the View completes initialization
|
||||
* (after {@link oninitialized `oninitialized`} callback fires) and complete tool arguments become available.
|
||||
* This notification is sent exactly once and is required before {@link sendToolResult `sendToolResult`}.
|
||||
*
|
||||
|
|
@ -985,14 +985,14 @@ export class AppBridge extends Protocol<
|
|||
}
|
||||
|
||||
/**
|
||||
* Send streaming partial tool arguments to the Guest UI.
|
||||
* Send streaming partial tool arguments to the view.
|
||||
*
|
||||
* The host MAY send this notification zero or more times while tool arguments
|
||||
* are being streamed, before {@link sendToolInput `sendToolInput`} is called with complete
|
||||
* arguments. This enables progressive rendering of tool arguments in the
|
||||
* Guest UI.
|
||||
* view.
|
||||
*
|
||||
* The arguments represent best-effort recovery of incomplete JSON. Guest UIs
|
||||
* The arguments represent best-effort recovery of incomplete JSON. views
|
||||
* SHOULD handle missing or changing fields gracefully between notifications.
|
||||
*
|
||||
* @param params - Partial tool call arguments (may be incomplete)
|
||||
|
|
@ -1011,10 +1011,10 @@ export class AppBridge extends Protocol<
|
|||
}
|
||||
|
||||
/**
|
||||
* Send tool execution result to the Guest UI.
|
||||
* Send tool execution result to the view.
|
||||
*
|
||||
* The host MUST send this notification when tool execution completes successfully,
|
||||
* provided the UI is still displayed. If the UI was closed before execution
|
||||
* provided the view is still displayed. If the view was closed before execution
|
||||
* completes, the host MAY skip this notification. This must be sent after
|
||||
* {@link sendToolInput `sendToolInput`}.
|
||||
*
|
||||
|
|
@ -1034,11 +1034,11 @@ export class AppBridge extends Protocol<
|
|||
}
|
||||
|
||||
/**
|
||||
* Notify the Guest UI that tool execution was cancelled.
|
||||
* Notify the view that tool execution was cancelled.
|
||||
*
|
||||
* The host MUST send this notification if tool execution was cancelled for any
|
||||
* reason, including user action, sampling error, classifier intervention, or
|
||||
* any other interruption. This allows the Guest UI to update its state and
|
||||
* any other interruption. This allows the view to update its state and
|
||||
* display appropriate feedback to the user.
|
||||
*
|
||||
* @param params - Cancellation details object
|
||||
|
|
@ -1086,17 +1086,17 @@ export class AppBridge extends Protocol<
|
|||
}
|
||||
|
||||
/**
|
||||
* Request graceful shutdown of the Guest UI.
|
||||
* Request graceful shutdown of the view.
|
||||
*
|
||||
* The host MUST send this request before tearing down the UI resource (before
|
||||
* unmounting the iframe). This gives the Guest UI an opportunity to save state,
|
||||
* unmounting the iframe). This gives the view an opportunity to save state,
|
||||
* cancel pending operations, or show confirmation dialogs.
|
||||
*
|
||||
* The host SHOULD wait for the response before unmounting to prevent data loss.
|
||||
*
|
||||
* @param params - Empty params object
|
||||
* @param options - Request options (timeout, etc.)
|
||||
* @returns Promise resolving when Guest UI confirms readiness for teardown
|
||||
* @returns Promise resolving when view confirms readiness for teardown
|
||||
*
|
||||
* @example
|
||||
* {@includeCode ./app-bridge.examples.ts#AppBridge_teardownResource_gracefulShutdown}
|
||||
|
|
@ -1119,11 +1119,11 @@ export class AppBridge extends Protocol<
|
|||
sendResourceTeardown: AppBridge["teardownResource"] = this.teardownResource;
|
||||
|
||||
/**
|
||||
* Connect to the Guest UI via transport and optionally set up message forwarding.
|
||||
* Connect to the view via transport and optionally set up message forwarding.
|
||||
*
|
||||
* This method establishes the transport connection. If an MCP client was passed
|
||||
* to the constructor, it also automatically sets up request/notification forwarding
|
||||
* based on the MCP server's capabilities, proxying the following to the Guest UI:
|
||||
* based on the MCP server's capabilities, proxying the following to the view:
|
||||
* - Tools (tools/call, notifications/tools/list_changed)
|
||||
* - Resources (resources/list, resources/read, resources/templates/list, notifications/resources/list_changed)
|
||||
* - Prompts (prompts/list, notifications/prompts/list_changed)
|
||||
|
|
@ -1133,7 +1133,7 @@ export class AppBridge extends Protocol<
|
|||
* etc. setters.
|
||||
*
|
||||
* After calling connect, wait for the {@link oninitialized `oninitialized`} callback before sending
|
||||
* tool input and other data to the Guest UI.
|
||||
* tool input and other data to the View.
|
||||
*
|
||||
* @param transport - Transport layer (typically {@link PostMessageTransport `PostMessageTransport`})
|
||||
* @returns Promise resolving when connection is established
|
||||
|
|
@ -1152,7 +1152,7 @@ export class AppBridge extends Protocol<
|
|||
async connect(transport: Transport) {
|
||||
if (this._client) {
|
||||
// When a client was passed to the constructor, automatically forward
|
||||
// MCP requests/notifications between the Guest UI and the server
|
||||
// MCP requests/notifications between the view and the server
|
||||
const serverCapabilities = this._client.getServerCapabilities();
|
||||
if (!serverCapabilities) {
|
||||
throw new Error("Client server capabilities not available");
|
||||
|
|
|
|||
Loading…
Reference in a new issue