modelcontextprotocol/ext-apps
Watch
1
0
Fork
You've already forked ext-apps
 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Merge pull request #323 from jonathanhefner/format-typedoc-links

Browse source 
Format `{@link}` tags with monospace display text
This commit is contained in:
Jonathan Hefner 2026-01-22 17:32:33 -06:00 • committed by GitHub
commit 9e42ee05a3
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
18 changed files with 217 additions and 217 deletions
Download patch file Download diff file Expand all files Collapse all files

16
docs/patterns.md
View file

@ -8,7 +8,7 @@ This document covers common patterns and recipes for building MCP Apps.
## Tools that are private to Apps ## Tools that are private to Apps
Set {@link types!McpUiToolMeta.visibility Tool.\_meta.ui.visibility} to `["app"]` to make tools only callable by Apps (hidden from the model). This is useful for UI-driven actions like updating quantities, toggling settings, or other interactions that shouldn't appear in the model's tool list. Set {@link types!McpUiToolMeta.visibility `Tool._meta.ui.visibility`} to `["app"]` to make tools only callable by Apps (hidden from the model). This is useful for UI-driven actions like updating quantities, toggling settings, or other interactions that shouldn't appear in the model's tool list.
{@includeCode ../src/server/index.examples.ts#registerAppTool_appOnlyVisibility} {@includeCode ../src/server/index.examples.ts#registerAppTool_appOnlyVisibility}
@ -32,7 +32,7 @@ _See [`examples/pdf-server/`](https://github.com/modelcontextprotocol/ext-apps/t
**Server-side**: Tool handler validates inputs and returns `{ isError: true, content: [...] }`. The model receives this error through the normal tool call response. **Server-side**: Tool handler validates inputs and returns `{ isError: true, content: [...] }`. The model receives this error through the normal tool call response.
**Client-side**: If a runtime error occurs (e.g., API failure, permission denied, resource unavailable), use {@link app!App.updateModelContext updateModelContext} to inform the model: **Client-side**: If a runtime error occurs (e.g., API failure, permission denied, resource unavailable), use {@link app!App.updateModelContext `updateModelContext`} to inform the model:
{@includeCode ../src/app.examples.ts#App_updateModelContext_reportError} {@includeCode ../src/app.examples.ts#App_updateModelContext_reportError}
@ -56,11 +56,11 @@ _See [`examples/basic-server-vanillajs/`](https://github.com/modelcontextprotoco
## Entering / Exiting fullscreen ## Entering / Exiting fullscreen
Toggle fullscreen mode by calling {@link app!App.requestDisplayMode requestDisplayMode}: Toggle fullscreen mode by calling {@link app!App.requestDisplayMode `requestDisplayMode`}:
{@includeCode ../src/app.examples.ts#App_requestDisplayMode_toggle} {@includeCode ../src/app.examples.ts#App_requestDisplayMode_toggle}
Listen for display mode changes via {@link app!App.onhostcontextchanged onhostcontextchanged} to update your UI: Listen for display mode changes via {@link app!App.onhostcontextchanged `onhostcontextchanged`} to update your UI:
{@includeCode ../src/app.examples.ts#App_onhostcontextchanged_respondToDisplayMode} {@includeCode ../src/app.examples.ts#App_onhostcontextchanged_respondToDisplayMode}
@ -68,7 +68,7 @@ _See [`examples/shadertoy-server/`](https://github.com/modelcontextprotocol/ext-
## Passing contextual information from the App to the Model ## Passing contextual information from the App to the Model
Use {@link app!App.updateModelContext updateModelContext} to keep the model informed about what the user is viewing or interacting with. Structure the content with YAML frontmatter for easy parsing: Use {@link app!App.updateModelContext `updateModelContext`} to keep the model informed about what the user is viewing or interacting with. Structure the content with YAML frontmatter for easy parsing:
{@includeCode ../src/app.examples.ts#App_updateModelContext_appState} {@includeCode ../src/app.examples.ts#App_updateModelContext_appState}
@ -76,7 +76,7 @@ _See [`examples/map-server/`](https://github.com/modelcontextprotocol/ext-apps/t
## Sending large follow-up messages ## Sending large follow-up messages
When you need to send more data than fits in a message, use {@link app!App.updateModelContext updateModelContext} to set the context first, then {@link app!App.sendMessage sendMessage} with a brief prompt to trigger a response: When you need to send more data than fits in a message, use {@link app!App.updateModelContext `updateModelContext`} to set the context first, then {@link app!App.sendMessage `sendMessage`} with a brief prompt to trigger a response:
{@includeCode ../src/app.examples.ts#App_sendMessage_withLargeContext} {@includeCode ../src/app.examples.ts#App_sendMessage_withLargeContext}
@ -90,7 +90,7 @@ To persist widget state across conversation reloads (e.g., current page in a PDF
{@includeCode ./patterns.tsx#persistDataServer} {@includeCode ./patterns.tsx#persistDataServer}
**Client-side**: Receive the UUID in {@link app!App.ontoolresult ontoolresult} and use it as the storage key: **Client-side**: Receive the UUID in {@link app!App.ontoolresult `ontoolresult`} and use it as the storage key:
{@includeCode ./patterns.tsx#persistData} {@includeCode ./patterns.tsx#persistData}
@ -106,7 +106,7 @@ _See [`examples/shadertoy-server/`](https://github.com/modelcontextprotocol/ext-
## Lowering perceived latency ## Lowering perceived latency
Use {@link app!App.ontoolinputpartial ontoolinputpartial} to receive streaming tool arguments as they arrive, allowing you to show a loading preview before the complete input is available. Use {@link app!App.ontoolinputpartial `ontoolinputpartial`} to receive streaming tool arguments as they arrive, allowing you to show a loading preview before the complete input is available.
{@includeCode ../src/app.examples.ts#App_ontoolinputpartial_progressiveRendering} {@includeCode ../src/app.examples.ts#App_ontoolinputpartial_progressiveRendering}

2
src/app-bridge.examples.ts
View file

@ -1,5 +1,5 @@
/** /**
* Type-checked examples for {@link AppBridge}. * Type-checked examples for {@link AppBridge `AppBridge`}.
* *
* These examples are included in the API documentation via `@includeCode` tags. * These examples are included in the API documentation via `@includeCode` tags.
* Each function's region markers define the code snippet that appears in the docs. * Each function's region markers define the code snippet that appears in the docs.

94
src/app-bridge.ts
View file

@ -157,12 +157,12 @@ export function buildAllowAttribute(
} }
/** /**
* Options for configuring {@link AppBridge} behavior. * 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 Guest UI
* *
* @see `ProtocolOptions` from @modelcontextprotocol/sdk for available options * @see `ProtocolOptions` from @modelcontextprotocol/sdk for available options
* @see {@link McpUiHostContext} for the hostContext structure * @see {@link McpUiHostContext `McpUiHostContext`} for the hostContext structure
*/ */
export type HostOptions = ProtocolOptions & { export type HostOptions = ProtocolOptions & {
hostContext?: McpUiHostContext; hostContext?: McpUiHostContext;
@ -190,7 +190,7 @@ type RequestHandlerExtra = Parameters<
>[1]; >[1];
/** /**
* Host-side bridge for communicating with a single Guest UI ({@link app!App}). * Host-side bridge for communicating with a single Guest UI ({@link app!App `App`}).
* *
* `AppBridge` extends the MCP SDK's `Protocol` class and acts as a proxy between * `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 Guest UI running in an iframe. When an MCP client
@ -211,8 +211,8 @@ type RequestHandlerExtra = Parameters<
* 1. **Create**: Instantiate `AppBridge` with MCP client and capabilities * 1. **Create**: Instantiate `AppBridge` with MCP client and capabilities
* 2. **Connect**: Call `connect()` with transport to establish communication * 2. **Connect**: Call `connect()` with transport to establish communication
* 3. **Wait for init**: Guest UI sends initialize request, bridge responds * 3. **Wait for init**: Guest UI sends initialize request, bridge responds
* 4. **Send data**: Call {@link sendToolInput}, {@link sendToolResult}, etc. * 4. **Send data**: Call {@link sendToolInput `sendToolInput`}, {@link sendToolResult `sendToolResult`}, etc.
* 5. **Teardown**: Call {@link teardownResource} before unmounting iframe * 5. **Teardown**: Call {@link teardownResource `teardownResource`} before unmounting iframe
* *
* @example Basic usage * @example Basic usage
* {@includeCode ./app-bridge.examples.ts#AppBridge_basicUsage} * {@includeCode ./app-bridge.examples.ts#AppBridge_basicUsage}
@ -230,9 +230,9 @@ export class AppBridge extends Protocol<
* Create a new AppBridge instance. * Create a new AppBridge instance.
* *
* @param _client - MCP client connected to the server, or `null`. When provided, * @param _client - MCP client connected to the server, or `null`. When provided,
* {@link connect} will automatically set up forwarding of MCP requests/notifications * {@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 Guest UI and the server. When `null`, you must register handlers
* manually using the {@link oncalltool}, {@link onlistresources}, etc. setters. * manually using the {@link oncalltool `oncalltool`}, {@link onlistresources `onlistresources`}, etc. setters.
* @param _hostInfo - Host application identification (name and version) * @param _hostInfo - Host application identification (name and version)
* @param _capabilities - Features and capabilities the host supports * @param _capabilities - Features and capabilities the host supports
* @param options - Configuration options (inherited from Protocol) * @param options - Configuration options (inherited from Protocol)
@ -282,7 +282,7 @@ export class AppBridge extends Protocol<
* @example Check Guest UI capabilities after initialization * @example Check Guest UI capabilities after initialization
* {@includeCode ./app-bridge.examples.ts#AppBridge_getAppCapabilities_checkAfterInit} * {@includeCode ./app-bridge.examples.ts#AppBridge_getAppCapabilities_checkAfterInit}
* *
* @see {@link McpUiAppCapabilities} for the capabilities structure * @see {@link McpUiAppCapabilities `McpUiAppCapabilities`} for the capabilities structure
*/ */
getAppCapabilities(): McpUiAppCapabilities | undefined { getAppCapabilities(): McpUiAppCapabilities | undefined {
return this._appCapabilities; return this._appCapabilities;
@ -307,7 +307,7 @@ export class AppBridge extends Protocol<
* Optional handler for ping requests from the Guest UI. * Optional handler for ping requests from the Guest UI.
* *
* The Guest UI can send standard MCP `ping` requests to verify the connection * The Guest UI can send standard MCP `ping` requests to verify the connection
* is alive. The {@link AppBridge} automatically responds with an empty object, but this * is alive. The {@link AppBridge `AppBridge`} automatically responds with an empty object, but this
* handler allows the host to observe or log ping activity. * handler allows the host to observe or log ping activity.
* *
* Unlike the other handlers which use setters, this is a direct property * Unlike the other handlers which use setters, this is a direct property
@ -329,13 +329,13 @@ export class AppBridge extends Protocol<
* adjust the iframe container dimensions based on the Guest UI's content. * adjust the iframe container dimensions based on the Guest UI's content.
* *
* Note: This is for Guest UI → Host communication. To notify the Guest UI of * Note: This is for Guest UI → Host communication. To notify the Guest UI of
* host container dimension changes, use {@link setHostContext}. * host container dimension changes, use {@link setHostContext `setHostContext`}.
* *
* @example * @example
* {@includeCode ./app-bridge.examples.ts#AppBridge_onsizechange_handleResize} * {@includeCode ./app-bridge.examples.ts#AppBridge_onsizechange_handleResize}
* *
* @see {@link McpUiSizeChangedNotification} for the notification type * @see {@link McpUiSizeChangedNotification `McpUiSizeChangedNotification`} for the notification type
* @see {@link app!App.sendSizeChanged} - the Guest UI method that sends these notifications * @see {@link app!App.sendSizeChanged `App.sendSizeChanged`} - the Guest UI method that sends these notifications
*/ */
set onsizechange( set onsizechange(
callback: (params: McpUiSizeChangedNotification["params"]) => void, callback: (params: McpUiSizeChangedNotification["params"]) => void,
@ -353,7 +353,7 @@ export class AppBridge extends Protocol<
* `ui/notifications/sandbox-proxy-ready` after it loads and is ready to receive * `ui/notifications/sandbox-proxy-ready` after it loads and is ready to receive
* HTML content. * HTML content.
* *
* When this fires, the host should call {@link sendSandboxResourceReady} with * When this fires, the host should call {@link sendSandboxResourceReady `sendSandboxResourceReady`} with
* the HTML content to load into the inner sandboxed iframe. * the HTML content to load into the inner sandboxed iframe.
* *
* @example * @example
@ -372,8 +372,8 @@ export class AppBridge extends Protocol<
* ``` * ```
* *
* @internal * @internal
* @see {@link McpUiSandboxProxyReadyNotification} for the notification type * @see {@link McpUiSandboxProxyReadyNotification `McpUiSandboxProxyReadyNotification`} for the notification type
* @see {@link sendSandboxResourceReady} for sending content to the sandbox * @see {@link sendSandboxResourceReady `sendSandboxResourceReady`} for sending content to the sandbox
*/ */
set onsandboxready( set onsandboxready(
callback: (params: McpUiSandboxProxyReadyNotification["params"]) => void, callback: (params: McpUiSandboxProxyReadyNotification["params"]) => void,
@ -392,8 +392,8 @@ export class AppBridge extends Protocol<
* @example * @example
* {@includeCode ./app-bridge.examples.ts#AppBridge_oninitialized_sendToolInput} * {@includeCode ./app-bridge.examples.ts#AppBridge_oninitialized_sendToolInput}
* *
* @see {@link McpUiInitializedNotification} for the notification type * @see {@link McpUiInitializedNotification `McpUiInitializedNotification`} for the notification type
* @see {@link sendToolInput} for sending tool arguments to the Guest UI * @see {@link sendToolInput `sendToolInput`} for sending tool arguments to the Guest UI
*/ */
set oninitialized( set oninitialized(
callback: (params: McpUiInitializedNotification["params"]) => void, callback: (params: McpUiInitializedNotification["params"]) => void,
@ -424,8 +424,8 @@ export class AppBridge extends Protocol<
* @example * @example
* {@includeCode ./app-bridge.examples.ts#AppBridge_onmessage_logMessage} * {@includeCode ./app-bridge.examples.ts#AppBridge_onmessage_logMessage}
* *
* @see {@link McpUiMessageRequest} for the request type * @see {@link McpUiMessageRequest `McpUiMessageRequest`} for the request type
* @see {@link McpUiMessageResult} for the result type * @see {@link McpUiMessageResult `McpUiMessageResult`} for the result type
*/ */
set onmessage( set onmessage(
callback: ( callback: (
@ -462,8 +462,8 @@ export class AppBridge extends Protocol<
* @example * @example
* {@includeCode ./app-bridge.examples.ts#AppBridge_onopenlink_handleRequest} * {@includeCode ./app-bridge.examples.ts#AppBridge_onopenlink_handleRequest}
* *
* @see {@link McpUiOpenLinkRequest} for the request type * @see {@link McpUiOpenLinkRequest `McpUiOpenLinkRequest`} for the request type
* @see {@link McpUiOpenLinkResult} for the result type * @see {@link McpUiOpenLinkResult `McpUiOpenLinkResult`} for the result type
*/ */
set onopenlink( set onopenlink(
callback: ( callback: (
@ -501,8 +501,8 @@ export class AppBridge extends Protocol<
* @example * @example
* {@includeCode ./app-bridge.examples.ts#AppBridge_onrequestdisplaymode_handleRequest} * {@includeCode ./app-bridge.examples.ts#AppBridge_onrequestdisplaymode_handleRequest}
* *
* @see {@link McpUiRequestDisplayModeRequest} for the request type * @see {@link McpUiRequestDisplayModeRequest `McpUiRequestDisplayModeRequest`} for the request type
* @see {@link McpUiRequestDisplayModeResult} for the result type * @see {@link McpUiRequestDisplayModeResult `McpUiRequestDisplayModeResult`} for the result type
*/ */
set onrequestdisplaymode( set onrequestdisplaymode(
callback: ( callback: (
@ -563,7 +563,7 @@ export class AppBridge extends Protocol<
* @example * @example
* {@includeCode ./app-bridge.examples.ts#AppBridge_onupdatemodelcontext_storeContext} * {@includeCode ./app-bridge.examples.ts#AppBridge_onupdatemodelcontext_storeContext}
* *
* @see {@link McpUiUpdateModelContextRequest} for the request type * @see {@link McpUiUpdateModelContextRequest `McpUiUpdateModelContextRequest`} for the request type
*/ */
set onupdatemodelcontext( set onupdatemodelcontext(
callback: ( callback: (
@ -866,7 +866,7 @@ export class AppBridge extends Protocol<
* *
* @returns Host capabilities object * @returns Host capabilities object
* *
* @see {@link McpUiHostCapabilities} for the capabilities structure * @see {@link McpUiHostCapabilities `McpUiHostCapabilities`} for the capabilities structure
*/ */
getCapabilities(): McpUiHostCapabilities { getCapabilities(): McpUiHostCapabilities {
return this._capabilities; return this._capabilities;
@ -920,8 +920,8 @@ export class AppBridge extends Protocol<
* @example Update multiple context fields * @example Update multiple context fields
* {@includeCode ./app-bridge.examples.ts#AppBridge_setHostContext_updateMultiple} * {@includeCode ./app-bridge.examples.ts#AppBridge_setHostContext_updateMultiple}
* *
* @see {@link McpUiHostContext} for the context structure * @see {@link McpUiHostContext `McpUiHostContext`} for the context structure
* @see {@link McpUiHostContextChangedNotification} for the notification type * @see {@link McpUiHostContextChangedNotification `McpUiHostContextChangedNotification`} for the notification type
*/ */
setHostContext(hostContext: McpUiHostContext) { setHostContext(hostContext: McpUiHostContext) {
const changes: McpUiHostContext = {}; const changes: McpUiHostContext = {};
@ -946,7 +946,7 @@ export class AppBridge extends Protocol<
/** /**
* Low-level method to notify the Guest UI of host context changes. * Low-level method to notify the Guest UI of host context changes.
* *
* Most hosts should use {@link setHostContext} instead, which automatically * Most hosts should use {@link setHostContext `setHostContext`} instead, which automatically
* detects changes and calls this method with only the modified fields. * detects changes and calls this method with only the modified fields.
* Use this directly only when you need fine-grained control over change detection. * Use this directly only when you need fine-grained control over change detection.
* *
@ -965,17 +965,17 @@ export class AppBridge extends Protocol<
* Send complete tool arguments to the Guest UI. * Send complete tool arguments to the Guest UI.
* *
* The host MUST send this notification after the Guest UI completes initialization * The host MUST send this notification after the Guest UI completes initialization
* (after {@link oninitialized} callback fires) and complete tool arguments become available. * (after {@link oninitialized `oninitialized`} callback fires) and complete tool arguments become available.
* This notification is sent exactly once and is required before {@link sendToolResult}. * This notification is sent exactly once and is required before {@link sendToolResult `sendToolResult`}.
* *
* @param params - Complete tool call arguments * @param params - Complete tool call arguments
* *
* @example * @example
* {@includeCode ./app-bridge.examples.ts#AppBridge_sendToolInput_afterInit} * {@includeCode ./app-bridge.examples.ts#AppBridge_sendToolInput_afterInit}
* *
* @see {@link McpUiToolInputNotification} for the notification type * @see {@link McpUiToolInputNotification `McpUiToolInputNotification`} for the notification type
* @see {@link oninitialized} for the initialization callback * @see {@link oninitialized `oninitialized`} for the initialization callback
* @see {@link sendToolResult} for sending results after execution * @see {@link sendToolResult `sendToolResult`} for sending results after execution
*/ */
sendToolInput(params: McpUiToolInputNotification["params"]) { sendToolInput(params: McpUiToolInputNotification["params"]) {
return this.notification({ return this.notification({
@ -988,7 +988,7 @@ export class AppBridge extends Protocol<
* Send streaming partial tool arguments to the Guest UI. * Send streaming partial tool arguments to the Guest UI.
* *
* The host MAY send this notification zero or more times while tool arguments * The host MAY send this notification zero or more times while tool arguments
* are being streamed, before {@link sendToolInput} is called with complete * are being streamed, before {@link sendToolInput `sendToolInput`} is called with complete
* arguments. This enables progressive rendering of tool arguments in the * arguments. This enables progressive rendering of tool arguments in the
* Guest UI. * Guest UI.
* *
@ -1000,8 +1000,8 @@ export class AppBridge extends Protocol<
* @example Stream partial arguments as they arrive * @example Stream partial arguments as they arrive
* {@includeCode ./app-bridge.examples.ts#AppBridge_sendToolInputPartial_streaming} * {@includeCode ./app-bridge.examples.ts#AppBridge_sendToolInputPartial_streaming}
* *
* @see {@link McpUiToolInputPartialNotification} for the notification type * @see {@link McpUiToolInputPartialNotification `McpUiToolInputPartialNotification`} for the notification type
* @see {@link sendToolInput} for sending complete arguments * @see {@link sendToolInput `sendToolInput`} for sending complete arguments
*/ */
sendToolInputPartial(params: McpUiToolInputPartialNotification["params"]) { sendToolInputPartial(params: McpUiToolInputPartialNotification["params"]) {
return this.notification({ return this.notification({
@ -1016,15 +1016,15 @@ export class AppBridge extends Protocol<
* The host MUST send this notification when tool execution completes successfully, * 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 UI is still displayed. If the UI was closed before execution
* completes, the host MAY skip this notification. This must be sent after * completes, the host MAY skip this notification. This must be sent after
* {@link sendToolInput}. * {@link sendToolInput `sendToolInput`}.
* *
* @param params - Standard MCP tool execution result * @param params - Standard MCP tool execution result
* *
* @example * @example
* {@includeCode ./app-bridge.examples.ts#AppBridge_sendToolResult_afterExecution} * {@includeCode ./app-bridge.examples.ts#AppBridge_sendToolResult_afterExecution}
* *
* @see {@link McpUiToolResultNotification} for the notification type * @see {@link McpUiToolResultNotification `McpUiToolResultNotification`} for the notification type
* @see {@link sendToolInput} for sending tool arguments before results * @see {@link sendToolInput `sendToolInput`} for sending tool arguments before results
*/ */
sendToolResult(params: McpUiToolResultNotification["params"]) { sendToolResult(params: McpUiToolResultNotification["params"]) {
return this.notification({ return this.notification({
@ -1050,9 +1050,9 @@ export class AppBridge extends Protocol<
* @example System-level cancellation * @example System-level cancellation
* {@includeCode ./app-bridge.examples.ts#AppBridge_sendToolCancelled_systemLevel} * {@includeCode ./app-bridge.examples.ts#AppBridge_sendToolCancelled_systemLevel}
* *
* @see {@link McpUiToolCancelledNotification} for the notification type * @see {@link McpUiToolCancelledNotification `McpUiToolCancelledNotification`} for the notification type
* @see {@link sendToolResult} for sending successful results * @see {@link sendToolResult `sendToolResult`} for sending successful results
* @see {@link sendToolInput} for sending tool arguments * @see {@link sendToolInput `sendToolInput`} for sending tool arguments
*/ */
sendToolCancelled(params: McpUiToolCancelledNotification["params"]) { sendToolCancelled(params: McpUiToolCancelledNotification["params"]) {
return this.notification({ return this.notification({
@ -1074,7 +1074,7 @@ export class AppBridge extends Protocol<
* - `sandbox`: Optional sandbox attribute value (e.g., "allow-scripts") * - `sandbox`: Optional sandbox attribute value (e.g., "allow-scripts")
* *
* @internal * @internal
* @see {@link onsandboxready} for handling the sandbox proxy ready notification * @see {@link onsandboxready `onsandboxready`} for handling the sandbox proxy ready notification
*/ */
sendSandboxResourceReady( sendSandboxResourceReady(
params: McpUiSandboxResourceReadyNotification["params"], params: McpUiSandboxResourceReadyNotification["params"],
@ -1115,7 +1115,7 @@ export class AppBridge extends Protocol<
); );
} }
/** @deprecated Use {@link teardownResource} instead */ /** @deprecated Use {@link teardownResource `teardownResource`} instead */
sendResourceTeardown: AppBridge["teardownResource"] = this.teardownResource; sendResourceTeardown: AppBridge["teardownResource"] = this.teardownResource;
/** /**
@ -1129,13 +1129,13 @@ export class AppBridge extends Protocol<
* - Prompts (prompts/list, notifications/prompts/list_changed) * - Prompts (prompts/list, notifications/prompts/list_changed)
* *
* If no client was passed to the constructor, no automatic forwarding is set up * If no client was passed to the constructor, no automatic forwarding is set up
* and you must register handlers manually using the {@link oncalltool}, {@link onlistresources}, * and you must register handlers manually using the {@link oncalltool `oncalltool`}, {@link onlistresources `onlistresources`},
* etc. setters. * etc. setters.
* *
* After calling connect, wait for the {@link oninitialized} callback before sending * 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 Guest UI.
* *
* @param transport - Transport layer (typically {@link PostMessageTransport}) * @param transport - Transport layer (typically {@link PostMessageTransport `PostMessageTransport`})
* @returns Promise resolving when connection is established * @returns Promise resolving when connection is established
* *
* @throws {Error} If a client was passed but server capabilities are not available. * @throws {Error} If a client was passed but server capabilities are not available.

2
src/app.examples.ts
View file

@ -1,5 +1,5 @@
/** /**
* Type-checked examples for {@link App} and constants in {@link ./app.ts}. * Type-checked examples for {@link App `App`} and constants in {@link ./app.ts `app.ts`}.
* *
* These examples are included in the API documentation via `@includeCode` tags. * These examples are included in the API documentation via `@includeCode` tags.
* Each function's region markers define the code snippet that appears in the docs. * Each function's region markers define the code snippet that appears in the docs.

118
src/app.ts
View file

@ -65,10 +65,10 @@ export {
* MCP servers include this key in tool definition metadata (via `tools/list`) * MCP servers include this key in tool definition metadata (via `tools/list`)
* to indicate which UI resource should be displayed when the tool is called. * to indicate which UI resource should be displayed when the tool is called.
* When hosts see a tool with this metadata, they fetch and render the * When hosts see a tool with this metadata, they fetch and render the
* corresponding {@link App}. * corresponding {@link App `App`}.
* *
* **Note**: This constant is provided for reference. App developers typically * **Note**: This constant is provided for reference. App developers typically
* don't need to use it directly. Prefer using {@link server-helpers!registerAppTool} * don't need to use it directly. Prefer using {@link server-helpers!registerAppTool `registerAppTool`}
* with the `_meta.ui.resourceUri` format instead. * with the `_meta.ui.resourceUri` format instead.
* *
* @example How MCP servers use this key (server-side, not in Apps) * @example How MCP servers use this key (server-side, not in Apps)
@ -84,12 +84,12 @@ export const RESOURCE_URI_META_KEY = "ui/resourceUri";
* *
* Identifies HTML content as an MCP App UI resource. * Identifies HTML content as an MCP App UI resource.
* *
* Used by {@link server-helpers!registerAppResource} as the default MIME type for app resources. * Used by {@link server-helpers!registerAppResource `registerAppResource`} as the default MIME type for app resources.
*/ */
export const RESOURCE_MIME_TYPE = "text/html;profile=mcp-app"; export const RESOURCE_MIME_TYPE = "text/html;profile=mcp-app";
/** /**
* Options for configuring {@link App} behavior. * Options for configuring {@link App `App`} behavior.
* *
* Extends `ProtocolOptions` from the MCP SDK with `App`-specific configuration. * Extends `ProtocolOptions` from the MCP SDK with `App`-specific configuration.
* *
@ -99,7 +99,7 @@ type AppOptions = ProtocolOptions & {
/** /**
* Automatically report size changes to the host using `ResizeObserver`. * Automatically report size changes to the host using `ResizeObserver`.
* *
* When enabled, the {@link App} monitors `document.body` and `document.documentElement` * When enabled, the {@link App `App`} monitors `document.body` and `document.documentElement`
* for size changes and automatically sends `ui/notifications/size-changed` * for size changes and automatically sends `ui/notifications/size-changed`
* notifications to the host. * notifications to the host.
* *
@ -122,7 +122,7 @@ type RequestHandlerExtra = Parameters<
* *
* ## Architecture * ## Architecture
* *
* Guest UIs (Apps) act as MCP clients connecting to the host via {@link PostMessageTransport}. * Guest UIs (Apps) act as MCP clients connecting to the host via {@link PostMessageTransport `PostMessageTransport`}.
* The host proxies requests to the actual MCP server and forwards * The host proxies requests to the actual MCP server and forwards
* responses back to the App. * responses back to the App.
* *
@ -193,7 +193,7 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
* Get the host's capabilities discovered during initialization. * Get the host's capabilities discovered during initialization.
* *
* Returns the capabilities that the host advertised during the * Returns the capabilities that the host advertised during the
* {@link connect} handshake. Returns `undefined` if called before * {@link connect `connect`} handshake. Returns `undefined` if called before
* connection is established. * connection is established.
* *
* @returns Host capabilities, or `undefined` if not yet connected * @returns Host capabilities, or `undefined` if not yet connected
@ -201,8 +201,8 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
* @example Check host capabilities after connection * @example Check host capabilities after connection
* {@includeCode ./app.examples.ts#App_getHostCapabilities_checkAfterConnection} * {@includeCode ./app.examples.ts#App_getHostCapabilities_checkAfterConnection}
* *
* @see {@link connect} for the initialization handshake * @see {@link connect `connect`} for the initialization handshake
* @see {@link McpUiHostCapabilities} for the capabilities structure * @see {@link McpUiHostCapabilities `McpUiHostCapabilities`} for the capabilities structure
*/ */
getHostCapabilities(): McpUiHostCapabilities | undefined { getHostCapabilities(): McpUiHostCapabilities | undefined {
return this._hostCapabilities; return this._hostCapabilities;
@ -212,7 +212,7 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
* Get the host's implementation info discovered during initialization. * Get the host's implementation info discovered during initialization.
* *
* Returns the host's name and version as advertised during the * Returns the host's name and version as advertised during the
* {@link connect} handshake. Returns `undefined` if called before * {@link connect `connect`} handshake. Returns `undefined` if called before
* connection is established. * connection is established.
* *
* @returns Host implementation info, or `undefined` if not yet connected * @returns Host implementation info, or `undefined` if not yet connected
@ -220,7 +220,7 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
* @example Log host information after connection * @example Log host information after connection
* {@includeCode ./app.examples.ts#App_getHostVersion_logAfterConnection} * {@includeCode ./app.examples.ts#App_getHostVersion_logAfterConnection}
* *
* @see {@link connect} for the initialization handshake * @see {@link connect `connect`} for the initialization handshake
*/ */
getHostVersion(): Implementation | undefined { getHostVersion(): Implementation | undefined {
return this._hostInfo; return this._hostInfo;
@ -241,9 +241,9 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
* @example Access host context after connection * @example Access host context after connection
* {@includeCode ./app.examples.ts#App_getHostContext_accessAfterConnection} * {@includeCode ./app.examples.ts#App_getHostContext_accessAfterConnection}
* *
* @see {@link connect} for the initialization handshake * @see {@link connect `connect`} for the initialization handshake
* @see {@link onhostcontextchanged} for context change notifications * @see {@link onhostcontextchanged `onhostcontextchanged`} for context change notifications
* @see {@link McpUiHostContext} for the context structure * @see {@link McpUiHostContext `McpUiHostContext`} for the context structure
*/ */
getHostContext(): McpUiHostContext | undefined { getHostContext(): McpUiHostContext | undefined {
return this._hostContext; return this._hostContext;
@ -259,15 +259,15 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
* This setter is a convenience wrapper around `setNotificationHandler()` that * This setter is a convenience wrapper around `setNotificationHandler()` that
* automatically handles the notification schema and extracts the params for you. * automatically handles the notification schema and extracts the params for you.
* *
* Register handlers before calling {@link connect} to avoid missing notifications. * Register handlers before calling {@link connect `connect`} to avoid missing notifications.
* *
* @param callback - Function called with the tool input params ({@link McpUiToolInputNotification.params}) * @param callback - Function called with the tool input params ({@link McpUiToolInputNotification.params `McpUiToolInputNotification.params`})
* *
* @example * @example
* {@includeCode ./app.examples.ts#App_ontoolinput_setter} * {@includeCode ./app.examples.ts#App_ontoolinput_setter}
* *
* @see {@link setNotificationHandler} for the underlying method * @see {@link setNotificationHandler `setNotificationHandler`} for the underlying method
* @see {@link McpUiToolInputNotification} for the notification structure * @see {@link McpUiToolInputNotification `McpUiToolInputNotification`} for the notification structure
*/ */
set ontoolinput( set ontoolinput(
callback: (params: McpUiToolInputNotification["params"]) => void, callback: (params: McpUiToolInputNotification["params"]) => void,
@ -292,16 +292,16 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
* This setter is a convenience wrapper around `setNotificationHandler()` that * This setter is a convenience wrapper around `setNotificationHandler()` that
* automatically handles the notification schema and extracts the params for you. * automatically handles the notification schema and extracts the params for you.
* *
* Register handlers before calling {@link connect} to avoid missing notifications. * Register handlers before calling {@link connect `connect`} to avoid missing notifications.
* *
* @param callback - Function called with each partial tool input update ({@link McpUiToolInputPartialNotification.params}) * @param callback - Function called with each partial tool input update ({@link McpUiToolInputPartialNotification.params `McpUiToolInputPartialNotification.params`})
* *
* @example Progressive rendering of tool arguments * @example Progressive rendering of tool arguments
* {@includeCode ./app.examples.ts#App_ontoolinputpartial_progressiveRendering} * {@includeCode ./app.examples.ts#App_ontoolinputpartial_progressiveRendering}
* *
* @see {@link setNotificationHandler} for the underlying method * @see {@link setNotificationHandler `setNotificationHandler`} for the underlying method
* @see {@link McpUiToolInputPartialNotification} for the notification structure * @see {@link McpUiToolInputPartialNotification `McpUiToolInputPartialNotification`} for the notification structure
* @see {@link ontoolinput} for the complete tool input handler * @see {@link ontoolinput `ontoolinput`} for the complete tool input handler
*/ */
set ontoolinputpartial( set ontoolinputpartial(
callback: (params: McpUiToolInputPartialNotification["params"]) => void, callback: (params: McpUiToolInputPartialNotification["params"]) => void,
@ -321,16 +321,16 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
* This setter is a convenience wrapper around `setNotificationHandler()` that * This setter is a convenience wrapper around `setNotificationHandler()` that
* automatically handles the notification schema and extracts the params for you. * automatically handles the notification schema and extracts the params for you.
* *
* Register handlers before calling {@link connect} to avoid missing notifications. * Register handlers before calling {@link connect `connect`} to avoid missing notifications.
* *
* @param callback - Function called with the tool result ({@link McpUiToolResultNotification.params}) * @param callback - Function called with the tool result ({@link McpUiToolResultNotification.params `McpUiToolResultNotification.params`})
* *
* @example Display tool execution results * @example Display tool execution results
* {@includeCode ./app.examples.ts#App_ontoolresult_displayResults} * {@includeCode ./app.examples.ts#App_ontoolresult_displayResults}
* *
* @see {@link setNotificationHandler} for the underlying method * @see {@link setNotificationHandler `setNotificationHandler`} for the underlying method
* @see {@link McpUiToolResultNotification} for the notification structure * @see {@link McpUiToolResultNotification `McpUiToolResultNotification`} for the notification structure
* @see {@link ontoolinput} for the initial tool input handler * @see {@link ontoolinput `ontoolinput`} for the initial tool input handler
*/ */
set ontoolresult( set ontoolresult(
callback: (params: McpUiToolResultNotification["params"]) => void, callback: (params: McpUiToolResultNotification["params"]) => void,
@ -351,16 +351,16 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
* This setter is a convenience wrapper around `setNotificationHandler()` that * This setter is a convenience wrapper around `setNotificationHandler()` that
* automatically handles the notification schema and extracts the params for you. * automatically handles the notification schema and extracts the params for you.
* *
* Register handlers before calling {@link connect} to avoid missing notifications. * Register handlers before calling {@link connect `connect`} to avoid missing notifications.
* *
* @param callback - Function called when tool execution is cancelled. Receives optional cancellation reason — see {@link McpUiToolCancelledNotification.params}. * @param callback - Function called when tool execution is cancelled. Receives optional cancellation reason — see {@link McpUiToolCancelledNotification.params `McpUiToolCancelledNotification.params`}.
* *
* @example Handle tool cancellation * @example Handle tool cancellation
* {@includeCode ./app.examples.ts#App_ontoolcancelled_handleCancellation} * {@includeCode ./app.examples.ts#App_ontoolcancelled_handleCancellation}
* *
* @see {@link setNotificationHandler} for the underlying method * @see {@link setNotificationHandler `setNotificationHandler`} for the underlying method
* @see {@link McpUiToolCancelledNotification} for the notification structure * @see {@link McpUiToolCancelledNotification `McpUiToolCancelledNotification`} for the notification structure
* @see {@link ontoolresult} for successful tool completion * @see {@link ontoolresult `ontoolresult`} for successful tool completion
*/ */
set ontoolcancelled( set ontoolcancelled(
callback: (params: McpUiToolCancelledNotification["params"]) => void, callback: (params: McpUiToolCancelledNotification["params"]) => void,
@ -382,19 +382,19 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
* automatically handles the notification schema and extracts the params for you. * automatically handles the notification schema and extracts the params for you.
* *
* Notification params are automatically merged into the internal host context * Notification params are automatically merged into the internal host context
* before the callback is invoked. This means {@link getHostContext} will * before the callback is invoked. This means {@link getHostContext `getHostContext`} will
* return the updated values even before your callback runs. * return the updated values even before your callback runs.
* *
* Register handlers before calling {@link connect} to avoid missing notifications. * Register handlers before calling {@link connect `connect`} to avoid missing notifications.
* *
* @param callback - Function called with the updated host context * @param callback - Function called with the updated host context
* *
* @example Respond to theme changes * @example Respond to theme changes
* {@includeCode ./app.examples.ts#App_onhostcontextchanged_respondToTheme} * {@includeCode ./app.examples.ts#App_onhostcontextchanged_respondToTheme}
* *
* @see {@link setNotificationHandler} for the underlying method * @see {@link setNotificationHandler `setNotificationHandler`} for the underlying method
* @see {@link McpUiHostContextChangedNotification} for the notification structure * @see {@link McpUiHostContextChangedNotification `McpUiHostContextChangedNotification`} for the notification structure
* @see {@link McpUiHostContext} for the full context structure * @see {@link McpUiHostContext `McpUiHostContext`} for the full context structure
*/ */
set onhostcontextchanged( set onhostcontextchanged(
callback: (params: McpUiHostContextChangedNotification["params"]) => void, callback: (params: McpUiHostContextChangedNotification["params"]) => void,
@ -422,7 +422,7 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
* This setter is a convenience wrapper around `setRequestHandler()` that * This setter is a convenience wrapper around `setRequestHandler()` that
* automatically handles the request schema. * automatically handles the request schema.
* *
* Register handlers before calling {@link connect} to avoid missing requests. * Register handlers before calling {@link connect `connect`} to avoid missing requests.
* *
* @param callback - Function called when teardown is requested. * @param callback - Function called when teardown is requested.
* Must return `McpUiResourceTeardownResult` (can be an empty object `{}`) or a Promise resolving to it. * Must return `McpUiResourceTeardownResult` (can be an empty object `{}`) or a Promise resolving to it.
@ -430,8 +430,8 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
* @example Perform cleanup before teardown * @example Perform cleanup before teardown
* {@includeCode ./app.examples.ts#App_onteardown_performCleanup} * {@includeCode ./app.examples.ts#App_onteardown_performCleanup}
* *
* @see {@link setRequestHandler} for the underlying method * @see {@link setRequestHandler `setRequestHandler`} for the underlying method
* @see {@link McpUiResourceTeardownRequest} for the request structure * @see {@link McpUiResourceTeardownRequest `McpUiResourceTeardownRequest`} for the request structure
*/ */
set onteardown( set onteardown(
callback: ( callback: (
@ -457,7 +457,7 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
* This setter is a convenience wrapper around `setRequestHandler()` that * This setter is a convenience wrapper around `setRequestHandler()` that
* automatically handles the request schema and extracts the params for you. * automatically handles the request schema and extracts the params for you.
* *
* Register handlers before calling {@link connect} to avoid missing requests. * Register handlers before calling {@link connect `connect`} to avoid missing requests.
* *
* @param callback - Async function that executes the tool and returns the result. * @param callback - Async function that executes the tool and returns the result.
* The callback will only be invoked if the app declared tool capabilities * The callback will only be invoked if the app declared tool capabilities
@ -466,7 +466,7 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
* @example Handle tool calls from the host * @example Handle tool calls from the host
* {@includeCode ./app.examples.ts#App_oncalltool_handleFromHost} * {@includeCode ./app.examples.ts#App_oncalltool_handleFromHost}
* *
* @see {@link setRequestHandler} for the underlying method * @see {@link setRequestHandler `setRequestHandler`} for the underlying method
*/ */
set oncalltool( set oncalltool(
callback: ( callback: (
@ -491,7 +491,7 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
* This setter is a convenience wrapper around `setRequestHandler()` that * This setter is a convenience wrapper around `setRequestHandler()` that
* automatically handles the request schema and extracts the params for you. * automatically handles the request schema and extracts the params for you.
* *
* Register handlers before calling {@link connect} to avoid missing requests. * Register handlers before calling {@link connect `connect`} to avoid missing requests.
* *
* @param callback - Async function that returns tool names as strings (simplified * @param callback - Async function that returns tool names as strings (simplified
* from full `ListToolsResult` with `Tool` objects). Registration is always * from full `ListToolsResult` with `Tool` objects). Registration is always
@ -500,8 +500,8 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
* @example Return available tools * @example Return available tools
* {@includeCode ./app.examples.ts#App_onlisttools_returnTools} * {@includeCode ./app.examples.ts#App_onlisttools_returnTools}
* *
* @see {@link setRequestHandler} for the underlying method * @see {@link setRequestHandler `setRequestHandler`} for the underlying method
* @see {@link oncalltool} for handling tool execution * @see {@link oncalltool `oncalltool`} for handling tool execution
*/ */
set onlisttools( set onlisttools(
callback: ( callback: (
@ -618,7 +618,7 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
* @example Send follow-up message after offloading large data to model context * @example Send follow-up message after offloading large data to model context
* {@includeCode ./app.examples.ts#App_sendMessage_withLargeContext} * {@includeCode ./app.examples.ts#App_sendMessage_withLargeContext}
* *
* @see {@link McpUiMessageRequest} for request structure * @see {@link McpUiMessageRequest `McpUiMessageRequest`} for request structure
*/ */
sendMessage(params: McpUiMessageRequest["params"], options?: RequestOptions) { sendMessage(params: McpUiMessageRequest["params"], options?: RequestOptions) {
return this.request( return this.request(
@ -655,7 +655,7 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
* Update the host's model context with app state. * Update the host's model context with app state.
* *
* Context updates are intended to be available to the model in future * Context updates are intended to be available to the model in future
* turns, without triggering an immediate model response (unlike {@link sendMessage}). * turns, without triggering an immediate model response (unlike {@link sendMessage `sendMessage`}).
* *
* The host will typically defer sending the context to the model until the * The host will typically defer sending the context to the model until the
* next user message — either from the actual user or via `sendMessage`. Only * next user message — either from the actual user or via `sendMessage`. Only
@ -704,8 +704,8 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
* @example Open documentation link * @example Open documentation link
* {@includeCode ./app.examples.ts#App_openLink_documentation} * {@includeCode ./app.examples.ts#App_openLink_documentation}
* *
* @see {@link McpUiOpenLinkRequest} for request structure * @see {@link McpUiOpenLinkRequest `McpUiOpenLinkRequest`} for request structure
* @see {@link McpUiOpenLinkResult} for result structure * @see {@link McpUiOpenLinkResult `McpUiOpenLinkResult`} for result structure
*/ */
openLink(params: McpUiOpenLinkRequest["params"], options?: RequestOptions) { openLink(params: McpUiOpenLinkRequest["params"], options?: RequestOptions) {
return this.request( return this.request(
@ -718,7 +718,7 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
); );
} }
/** @deprecated Use {@link openLink} instead */ /** @deprecated Use {@link openLink `openLink`} instead */
sendOpenLink: App["openLink"] = this.openLink; sendOpenLink: App["openLink"] = this.openLink;
/** /**
@ -736,8 +736,8 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
* @example Toggle display mode * @example Toggle display mode
* {@includeCode ./app.examples.ts#App_requestDisplayMode_toggle} * {@includeCode ./app.examples.ts#App_requestDisplayMode_toggle}
* *
* @see {@link McpUiRequestDisplayModeRequest} for request structure * @see {@link McpUiRequestDisplayModeRequest `McpUiRequestDisplayModeRequest`} for request structure
* @see {@link McpUiHostContext} for checking availableDisplayModes * @see {@link McpUiHostContext `McpUiHostContext`} for checking availableDisplayModes
*/ */
requestDisplayMode( requestDisplayMode(
params: McpUiRequestDisplayModeRequest["params"], params: McpUiRequestDisplayModeRequest["params"],
@ -766,7 +766,7 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
* *
* @returns Promise that resolves when the notification is sent * @returns Promise that resolves when the notification is sent
* *
* @see {@link McpUiSizeChangedNotification} for notification structure * @see {@link McpUiSizeChangedNotification `McpUiSizeChangedNotification`} for notification structure
*/ */
sendSizeChanged(params: McpUiSizeChangedNotification["params"]) { sendSizeChanged(params: McpUiSizeChangedNotification["params"]) {
return this.notification(<McpUiSizeChangedNotification>{ return this.notification(<McpUiSizeChangedNotification>{
@ -850,12 +850,12 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
* 2. Sends `ui/initialize` request with app info and capabilities * 2. Sends `ui/initialize` request with app info and capabilities
* 3. Receives host capabilities and context in response * 3. Receives host capabilities and context in response
* 4. Sends `ui/notifications/initialized` notification * 4. Sends `ui/notifications/initialized` notification
* 5. Sets up auto-resize using {@link setupSizeChangedNotifications} if enabled (default) * 5. Sets up auto-resize using {@link setupSizeChangedNotifications `setupSizeChangedNotifications`} if enabled (default)
* *
* If initialization fails, the connection is automatically closed and an error * If initialization fails, the connection is automatically closed and an error
* is thrown. * is thrown.
* *
* @param transport - Transport layer (typically {@link PostMessageTransport}) * @param transport - Transport layer (typically {@link PostMessageTransport `PostMessageTransport`})
* @param options - Request options for the initialize request * @param options - Request options for the initialize request
* *
* @throws {Error} If initialization fails or connection is lost * @throws {Error} If initialization fails or connection is lost
@ -863,9 +863,9 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
* @example Connect with PostMessageTransport * @example Connect with PostMessageTransport
* {@includeCode ./app.examples.ts#App_connect_withPostMessageTransport} * {@includeCode ./app.examples.ts#App_connect_withPostMessageTransport}
* *
* @see {@link McpUiInitializeRequest} for the initialization request structure * @see {@link McpUiInitializeRequest `McpUiInitializeRequest`} for the initialization request structure
* @see {@link McpUiInitializedNotification} for the initialized notification * @see {@link McpUiInitializedNotification `McpUiInitializedNotification`} for the initialized notification
* @see {@link PostMessageTransport} for the typical transport implementation * @see {@link PostMessageTransport `PostMessageTransport`} for the typical transport implementation
*/ */
override async connect( override async connect(
transport: Transport = new PostMessageTransport( transport: Transport = new PostMessageTransport(

36
src/generated/schema.ts generated
View file

@ -135,7 +135,7 @@ export const McpUiStylesSchema = z
/** /**
* @description Request to open an external URL in the host's default browser. * @description Request to open an external URL in the host's default browser.
* @see {@link app!App.openLink} for the method that sends this request * @see {@link app!App.openLink `App.openLink`} for the method that sends this request
*/ */
export const McpUiOpenLinkRequestSchema = z.object({ export const McpUiOpenLinkRequestSchema = z.object({
method: z.literal("ui/open-link"), method: z.literal("ui/open-link"),
@ -147,7 +147,7 @@ export const McpUiOpenLinkRequestSchema = z.object({
/** /**
* @description Result from opening a URL. * @description Result from opening a URL.
* @see {@link McpUiOpenLinkRequest} * @see {@link McpUiOpenLinkRequest `McpUiOpenLinkRequest`}
*/ */
export const McpUiOpenLinkResultSchema = z export const McpUiOpenLinkResultSchema = z
.object({ .object({
@ -163,7 +163,7 @@ export const McpUiOpenLinkResultSchema = z
/** /**
* @description Result from sending a message. * @description Result from sending a message.
* @see {@link McpUiMessageRequest} * @see {@link McpUiMessageRequest `McpUiMessageRequest`}
*/ */
export const McpUiMessageResultSchema = z export const McpUiMessageResultSchema = z
.object({ .object({
@ -247,7 +247,7 @@ export const McpUiResourcePermissionsSchema = z.object({
/** /**
* @description Notification of UI size changes (Guest UI -> Host). * @description Notification of UI size changes (Guest UI -> Host).
* @see {@link app!App.sendSizeChanged} for the method to send this from Guest UI * @see {@link app!App.sendSizeChanged `App.sendSizeChanged`} for the method to send this from Guest UI
*/ */
export const McpUiSizeChangedNotificationSchema = z.object({ export const McpUiSizeChangedNotificationSchema = z.object({
method: z.literal("ui/notifications/size-changed"), method: z.literal("ui/notifications/size-changed"),
@ -319,7 +319,7 @@ export const McpUiToolCancelledNotificationSchema = z.object({
* @description CSS blocks that can be injected by apps. * @description CSS blocks that can be injected by apps.
*/ */
export const McpUiHostCssSchema = z.object({ export const McpUiHostCssSchema = z.object({
/** @description CSS for font loading (`@font-face` rules or `@import` statements). Apps must apply using {@link applyHostFonts}. */ /** @description CSS for font loading (`@font-face` rules or `@import` statements). Apps must apply using {@link applyHostFonts `applyHostFonts`}. */
fonts: z.string().optional(), fonts: z.string().optional(),
}); });
@ -339,7 +339,7 @@ export const McpUiHostStylesSchema = z.object({
/** /**
* @description Request for graceful shutdown of the Guest UI (Host -> Guest UI). * @description Request for graceful shutdown of the Guest UI (Host -> Guest UI).
* @see {@link app-bridge!AppBridge.teardownResource} for the host method that sends this * @see {@link app-bridge!AppBridge.teardownResource `AppBridge.teardownResource`} for the host method that sends this
*/ */
export const McpUiResourceTeardownRequestSchema = z.object({ export const McpUiResourceTeardownRequestSchema = z.object({
method: z.literal("ui/resource-teardown"), method: z.literal("ui/resource-teardown"),
@ -348,7 +348,7 @@ export const McpUiResourceTeardownRequestSchema = z.object({
/** /**
* @description Result from graceful shutdown request. * @description Result from graceful shutdown request.
* @see {@link McpUiResourceTeardownRequest} * @see {@link McpUiResourceTeardownRequest `McpUiResourceTeardownRequest`}
*/ */
export const McpUiResourceTeardownResultSchema = z.record( export const McpUiResourceTeardownResultSchema = z.record(
z.string(), z.string(),
@ -387,7 +387,7 @@ export const McpUiSupportedContentBlockModalitiesSchema = z.object({
/** /**
* @description Capabilities supported by the host application. * @description Capabilities supported by the host application.
* @see {@link McpUiInitializeResult} for the initialization result that includes these capabilities * @see {@link McpUiInitializeResult `McpUiInitializeResult`} for the initialization result that includes these capabilities
*/ */
export const McpUiHostCapabilitiesSchema = z.object({ export const McpUiHostCapabilitiesSchema = z.object({
/** @description Experimental features (structure TBD). */ /** @description Experimental features (structure TBD). */
@ -450,8 +450,8 @@ export const McpUiHostCapabilitiesSchema = z.object({
}); });
/** /**
* @description Capabilities provided by the Guest UI ({@link app!App}). * @description Capabilities provided by the Guest UI ({@link app!App `App`}).
* @see {@link McpUiInitializeRequest} for the initialization request that includes these capabilities * @see {@link McpUiInitializeRequest `McpUiInitializeRequest`} for the initialization request that includes these capabilities
*/ */
export const McpUiAppCapabilitiesSchema = z.object({ export const McpUiAppCapabilitiesSchema = z.object({
/** @description Experimental features (structure TBD). */ /** @description Experimental features (structure TBD). */
@ -474,7 +474,7 @@ export const McpUiAppCapabilitiesSchema = z.object({
/** /**
* @description Notification that Guest UI has completed initialization (Guest UI -> Host). * @description Notification that Guest UI has completed initialization (Guest UI -> Host).
* @see {@link app!App.connect} for the method that sends this notification * @see {@link app!App.connect `App.connect`} for the method that sends this notification
*/ */
export const McpUiInitializedNotificationSchema = z.object({ export const McpUiInitializedNotificationSchema = z.object({
method: z.literal("ui/notifications/initialized"), method: z.literal("ui/notifications/initialized"),
@ -511,7 +511,7 @@ export const McpUiResourceMetaSchema = z.object({
* @description Request to change the display mode of the UI. * @description Request to change the display mode of the UI.
* The host will respond with the actual display mode that was set, * The host will respond with the actual display mode that was set,
* which may differ from the requested mode if not supported. * which may differ from the requested mode if not supported.
* @see {@link app!App.requestDisplayMode} for the method that sends this request * @see {@link app!App.requestDisplayMode `App.requestDisplayMode`} for the method that sends this request
*/ */
export const McpUiRequestDisplayModeRequestSchema = z.object({ export const McpUiRequestDisplayModeRequestSchema = z.object({
method: z.literal("ui/request-display-mode"), method: z.literal("ui/request-display-mode"),
@ -523,7 +523,7 @@ export const McpUiRequestDisplayModeRequestSchema = z.object({
/** /**
* @description Result from requesting a display mode change. * @description Result from requesting a display mode change.
* @see {@link McpUiRequestDisplayModeRequest} * @see {@link McpUiRequestDisplayModeRequest `McpUiRequestDisplayModeRequest`}
*/ */
export const McpUiRequestDisplayModeResultSchema = z export const McpUiRequestDisplayModeResultSchema = z
.object({ .object({
@ -567,7 +567,7 @@ export const McpUiToolMetaSchema = z.object({
/** /**
* @description Request to send a message to the host's chat interface. * @description Request to send a message to the host's chat interface.
* @see {@link app!App.sendMessage} for the method that sends this request * @see {@link app!App.sendMessage `App.sendMessage`} for the method that sends this request
*/ */
export const McpUiMessageRequestSchema = z.object({ export const McpUiMessageRequestSchema = z.object({
method: z.literal("ui/message"), method: z.literal("ui/message"),
@ -740,7 +740,7 @@ export const McpUiHostContextSchema = z
/** /**
* @description Notification that host context has changed (Host -> Guest UI). * @description Notification that host context has changed (Host -> Guest UI).
* @see {@link McpUiHostContext} for the full context structure * @see {@link McpUiHostContext `McpUiHostContext`} for the full context structure
*/ */
export const McpUiHostContextChangedNotificationSchema = z.object({ export const McpUiHostContextChangedNotificationSchema = z.object({
method: z.literal("ui/notifications/host-context-changed"), method: z.literal("ui/notifications/host-context-changed"),
@ -760,7 +760,7 @@ export const McpUiHostContextChangedNotificationSchema = z.object({
* The host will typically defer sending the context to the model until the next user message * The host will typically defer sending the context to the model until the next user message
* (including `ui/message`), and will only send the last update received. * (including `ui/message`), and will only send the last update received.
* *
* @see {@link app.App.updateModelContext} for the method that sends this request * @see {@link app.App.updateModelContext `App.updateModelContext`} for the method that sends this request
*/ */
export const McpUiUpdateModelContextRequestSchema = z.object({ export const McpUiUpdateModelContextRequestSchema = z.object({
method: z.literal("ui/update-model-context"), method: z.literal("ui/update-model-context"),
@ -785,7 +785,7 @@ export const McpUiUpdateModelContextRequestSchema = z.object({
/** /**
* @description Initialization request sent from Guest UI to Host. * @description Initialization request sent from Guest UI to Host.
* @see {@link app!App.connect} for the method that sends this request * @see {@link app!App.connect `App.connect`} for the method that sends this request
*/ */
export const McpUiInitializeRequestSchema = z.object({ export const McpUiInitializeRequestSchema = z.object({
method: z.literal("ui/initialize"), method: z.literal("ui/initialize"),
@ -805,7 +805,7 @@ export const McpUiInitializeRequestSchema = z.object({
/** /**
* @description Initialization result returned from Host to Guest UI. * @description Initialization result returned from Host to Guest UI.
* @see {@link McpUiInitializeRequest} * @see {@link McpUiInitializeRequest `McpUiInitializeRequest`}
*/ */
export const McpUiInitializeResultSchema = z export const McpUiInitializeResultSchema = z
.object({ .object({

2
src/message-transport.examples.ts
View file

@ -1,5 +1,5 @@
/** /**
* Type-checked examples for {@link PostMessageTransport}. * Type-checked examples for {@link PostMessageTransport `PostMessageTransport`}.
* *
* These examples are included in the API documentation via `@includeCode` tags. * These examples are included in the API documentation via `@includeCode` tags.
* Each function's region markers define the code snippet that appears in the docs. * Each function's region markers define the code snippet that appears in the docs.

10
src/message-transport.ts
View file

@ -29,8 +29,8 @@ import {
* **Host**: * **Host**:
* {@includeCode ./message-transport.examples.ts#PostMessageTransport_host} * {@includeCode ./message-transport.examples.ts#PostMessageTransport_host}
* *
* @see {@link app!App.connect} for Guest UI usage * @see {@link app!App.connect `App.connect`} for Guest UI usage
* @see {@link app-bridge!AppBridge.connect} for Host usage * @see {@link app-bridge!AppBridge.connect `AppBridge.connect`} for Host usage
*/ */
export class PostMessageTransport implements Transport { export class PostMessageTransport implements Transport {
private messageListener: ( private messageListener: (
@ -102,7 +102,7 @@ export class PostMessageTransport implements Transport {
/** /**
* Stop listening for messages and cleanup. * Stop listening for messages and cleanup.
* *
* Removes the message event listener and calls the {@link onclose} callback if set. * Removes the message event listener and calls the {@link onclose `onclose`} callback if set.
*/ */
async close() { async close() {
window.removeEventListener("message", this.messageListener); window.removeEventListener("message", this.messageListener);
@ -112,7 +112,7 @@ export class PostMessageTransport implements Transport {
/** /**
* Called when the transport is closed. * Called when the transport is closed.
* *
* Set this handler to be notified when {@link close} is called. * Set this handler to be notified when {@link close `close`} is called.
*/ */
onclose?: () => void; onclose?: () => void;
@ -129,7 +129,7 @@ export class PostMessageTransport implements Transport {
/** /**
* Called when a valid JSON-RPC message is received. * Called when a valid JSON-RPC message is received.
* *
* This handler is invoked after message validation succeeds. The {@link start} * This handler is invoked after message validation succeeds. The {@link start `start`}
* method must be called before messages will be received. * method must be called before messages will be received.
* *
* @param message - The validated JSON-RPC message * @param message - The validated JSON-RPC message

12
src/react/index.tsx
View file

@ -3,16 +3,16 @@
* *
* This module provides React hooks and utilities for easily building * This module provides React hooks and utilities for easily building
* interactive MCP Apps using React. This is optional - the core SDK * interactive MCP Apps using React. This is optional - the core SDK
* ({@link App}, {@link PostMessageTransport}) is framework-agnostic and can be * ({@link App `App`}, {@link PostMessageTransport `PostMessageTransport`}) is framework-agnostic and can be
* used with any UI framework or vanilla JavaScript. * used with any UI framework or vanilla JavaScript.
* *
* ## Main Exports * ## Main Exports
* *
* - {@link useApp} - React hook to create and connect an MCP App * - {@link useApp `useApp`} - React hook to create and connect an MCP App
* - {@link useHostStyleVariables} - React hook to apply host style variables and theme * - {@link useHostStyleVariables `useHostStyleVariables`} - React hook to apply host style variables and theme
* - {@link useHostFonts} - React hook to apply host fonts * - {@link useHostFonts `useHostFonts`} - React hook to apply host fonts
* - {@link useDocumentTheme} - React hook for reactive document theme * - {@link useDocumentTheme `useDocumentTheme`} - React hook for reactive document theme
* - {@link useAutoResize} - React hook for manual auto-resize control (rarely needed) * - {@link useAutoResize `useAutoResize`} - React hook for manual auto-resize control (rarely needed)
* *
* @module @modelcontextprotocol/ext-apps/react * @module @modelcontextprotocol/ext-apps/react
* *

24
src/react/useApp.tsx
View file

@ -5,14 +5,14 @@ import { App, McpUiAppCapabilities, PostMessageTransport } from "../app";
export * from "../app"; export * from "../app";
/** /**
* Options for configuring the {@link useApp} hook. * Options for configuring the {@link useApp `useApp`} hook.
* *
* Note: This interface does NOT expose {@link App} options like `autoResize`. * Note: This interface does NOT expose {@link App `App`} options like `autoResize`.
* The hook creates the `App` with default options (`autoResize: true`). If you * The hook creates the `App` with default options (`autoResize: true`). If you
* need custom `App` options, create the `App` manually instead of using this hook. * need custom `App` options, create the `App` manually instead of using this hook.
* *
* @see {@link useApp} for the hook that uses these options * @see {@link useApp `useApp`} for the hook that uses these options
* @see {@link useAutoResize} for manual auto-resize control with custom `App` options * @see {@link useAutoResize `useAutoResize`} for manual auto-resize control with custom `App` options
*/ */
export interface UseAppOptions { export interface UseAppOptions {
/** App identification (name and version) */ /** App identification (name and version) */
@ -22,7 +22,7 @@ export interface UseAppOptions {
*/ */
capabilities: McpUiAppCapabilities; capabilities: McpUiAppCapabilities;
/** /**
* Called after {@link App} is created but before connection. * Called after {@link App `App`} is created but before connection.
* *
* Use this to register request/notification handlers that need to be in place * Use this to register request/notification handlers that need to be in place
* before the initialization handshake completes. * before the initialization handshake completes.
@ -36,10 +36,10 @@ export interface UseAppOptions {
} }
/** /**
* State returned by the {@link useApp} hook. * State returned by the {@link useApp `useApp`} hook.
*/ */
export interface AppState { export interface AppState {
/** The connected {@link App} instance, null during initialization */ /** The connected {@link App `App`} instance, null during initialization */
app: App | null; app: App | null;
/** Whether initialization completed successfully */ /** Whether initialization completed successfully */
isConnected: boolean; isConnected: boolean;
@ -50,8 +50,8 @@ export interface AppState {
/** /**
* React hook to create and connect an MCP App. * React hook to create and connect an MCP App.
* *
* This hook manages {@link App} creation and connection. It automatically * This hook manages {@link App `App`} creation and connection. It automatically
* creates a {@link PostMessageTransport} to window.parent and handles * creates a {@link PostMessageTransport `PostMessageTransport`} to window.parent and handles
* initialization. * initialization.
* *
* This hook is part of the optional React integration. The core SDK (`App`, * This hook is part of the optional React integration. The core SDK (`App`,
@ -62,7 +62,7 @@ export interface AppState {
* to avoid reconnection loops. Options are only used during the initial mount. * to avoid reconnection loops. Options are only used during the initial mount.
* Furthermore, the `App` instance is NOT closed on unmount. This avoids cleanup * Furthermore, the `App` instance is NOT closed on unmount. This avoids cleanup
* issues during React Strict Mode's double-mount cycle. If you need to * issues during React Strict Mode's double-mount cycle. If you need to
* explicitly close the `App`, call {@link App.close} manually. * explicitly close the `App`, call {@link App.close `App.close`} manually.
* *
* @param options - Configuration for the app * @param options - Configuration for the app
* @returns Current connection state and app instance. If connection fails during * @returns Current connection state and app instance. If connection fails during
@ -72,8 +72,8 @@ export interface AppState {
* @example Basic usage of useApp hook with common event handlers * @example Basic usage of useApp hook with common event handlers
* {@includeCode ./useApp.examples.tsx#useApp_basicUsage} * {@includeCode ./useApp.examples.tsx#useApp_basicUsage}
* *
* @see {@link App.connect} for the underlying connection method * @see {@link App.connect `App.connect`} for the underlying connection method
* @see {@link useAutoResize} for manual auto-resize control when using custom App options * @see {@link useAutoResize `useAutoResize`} for manual auto-resize control when using custom App options
*/ */
export function useApp({ export function useApp({
appInfo, appInfo,

12
src/react/useAutoResize.ts
View file

@ -9,12 +9,12 @@ import { App } from "../app";
* *
* The hook automatically cleans up the `ResizeObserver` when the component unmounts. * The hook automatically cleans up the `ResizeObserver` when the component unmounts.
* *
* **Note**: This hook is rarely needed since the {@link useApp} hook automatically enables * **Note**: This hook is rarely needed since the {@link useApp `useApp`} hook automatically enables
* auto-resize by default. This hook is provided for advanced cases where you * auto-resize by default. This hook is provided for advanced cases where you
* create the {@link App} manually with `autoResize: false` and want to add auto-resize * create the {@link App `App`} manually with `autoResize: false` and want to add auto-resize
* behavior later. * behavior later.
* *
* @param app - The connected {@link App} instance, or null during initialization * @param app - The connected {@link App `App`} instance, or null during initialization
* @param elementRef - Currently unused. The hook always observes `document.body` * @param elementRef - Currently unused. The hook always observes `document.body`
* and `document.documentElement` regardless of this value. Passing a ref will * and `document.documentElement` regardless of this value. Passing a ref will
* cause unnecessary effect re-runs; omit this parameter. * cause unnecessary effect re-runs; omit this parameter.
@ -22,9 +22,9 @@ import { App } from "../app";
* @example Manual App creation with custom auto-resize control * @example Manual App creation with custom auto-resize control
* {@includeCode ./useAutoResize.examples.tsx#useAutoResize_manualApp} * {@includeCode ./useAutoResize.examples.tsx#useAutoResize_manualApp}
* *
* @see {@link App.setupSizeChangedNotifications} for the underlying implementation * @see {@link App.setupSizeChangedNotifications `App.setupSizeChangedNotifications`} for the underlying implementation
* @see {@link useApp} which enables auto-resize by default * @see {@link useApp `useApp`} which enables auto-resize by default
* @see {@link App} constructor for configuring `autoResize` option * @see {@link App `App`} constructor for configuring `autoResize` option
*/ */
export function useAutoResize( export function useAutoResize(
app: App | null, app: App | null,

4
src/react/useDocumentTheme.ts
View file

@ -20,8 +20,8 @@ import { McpUiTheme } from "../types";
* @example Use with theme-aware styling * @example Use with theme-aware styling
* {@includeCode ./useDocumentTheme.examples.tsx#useDocumentTheme_themedButton} * {@includeCode ./useDocumentTheme.examples.tsx#useDocumentTheme_themedButton}
* *
* @see {@link getDocumentTheme} for the underlying function * @see {@link getDocumentTheme `getDocumentTheme`} for the underlying function
* @see {@link applyDocumentTheme} to set the theme * @see {@link applyDocumentTheme `applyDocumentTheme`} to set the theme
*/ */
export function useDocumentTheme(): McpUiTheme { export function useDocumentTheme(): McpUiTheme {
const [theme, setTheme] = useState<McpUiTheme>(getDocumentTheme); const [theme, setTheme] = useState<McpUiTheme>(getDocumentTheme);

26
src/react/useHostStyles.ts
View file

@ -21,17 +21,17 @@ import { McpUiHostContext } from "../types";
* this hook ensures they work correctly by setting the `color-scheme` property * this hook ensures they work correctly by setting the `color-scheme` property
* based on the host's theme preference. * based on the host's theme preference.
* *
* @param app - The connected {@link App} instance, or null during initialization * @param app - The connected {@link App `App`} instance, or null during initialization
* @param initialContext - Initial host context from the connection (optional). * @param initialContext - Initial host context from the connection (optional).
* If provided, styles and theme will be applied immediately on mount. * If provided, styles and theme will be applied immediately on mount.
* *
* @example * @example
* {@includeCode ./useHostStyles.examples.tsx#useHostStyleVariables_basicUsage} * {@includeCode ./useHostStyles.examples.tsx#useHostStyleVariables_basicUsage}
* *
* @see {@link applyHostStyleVariables} for the underlying styles function * @see {@link applyHostStyleVariables `applyHostStyleVariables`} for the underlying styles function
* @see {@link applyDocumentTheme} for the underlying theme function * @see {@link applyDocumentTheme `applyDocumentTheme`} for the underlying theme function
* @see {@link useHostFonts} for applying host fonts * @see {@link useHostFonts `useHostFonts`} for applying host fonts
* @see {@link McpUiStyles} for available CSS variables * @see {@link McpUiStyles `McpUiStyles`} for available CSS variables
*/ */
export function useHostStyleVariables( export function useHostStyleVariables(
app: App | null, app: App | null,
@ -84,15 +84,15 @@ export function useHostStyleVariables(
* The hook also applies fonts from the initial host context when * The hook also applies fonts from the initial host context when
* the app first connects. * the app first connects.
* *
* @param app - The connected {@link App} instance, or null during initialization * @param app - The connected {@link App `App`} instance, or null during initialization
* @param initialContext - Initial host context from the connection (optional). * @param initialContext - Initial host context from the connection (optional).
* If provided, fonts will be applied immediately on mount. * If provided, fonts will be applied immediately on mount.
* *
* @example Basic usage with useApp * @example Basic usage with useApp
* {@includeCode ./useHostStyles.examples.tsx#useHostFonts_basicUsage} * {@includeCode ./useHostStyles.examples.tsx#useHostFonts_basicUsage}
* *
* @see {@link applyHostFonts} for the underlying fonts function * @see {@link applyHostFonts `applyHostFonts`} for the underlying fonts function
* @see {@link useHostStyleVariables} for applying style variables and theme * @see {@link useHostStyleVariables `useHostStyleVariables`} for applying style variables and theme
*/ */
export function useHostFonts( export function useHostFonts(
app: App | null, app: App | null,
@ -128,18 +128,18 @@ export function useHostFonts(
/** /**
* Applies all host styling (CSS variables, theme, and fonts) to match the host application. * Applies all host styling (CSS variables, theme, and fonts) to match the host application.
* *
* This is a convenience hook that combines {@link useHostStyleVariables} and * This is a convenience hook that combines {@link useHostStyleVariables `useHostStyleVariables`} and
* {@link useHostFonts}. Use the individual hooks if you need more control. * {@link useHostFonts `useHostFonts`}. Use the individual hooks if you need more control.
* *
* @param app - The connected {@link App} instance, or null during initialization * @param app - The connected {@link App `App`} instance, or null during initialization
* @param initialContext - Initial host context from the connection (optional). * @param initialContext - Initial host context from the connection (optional).
* Pass `app?.getHostContext()` to apply styles immediately on mount. * Pass `app?.getHostContext()` to apply styles immediately on mount.
* *
* @example * @example
* {@includeCode ./useHostStyles.examples.tsx#useHostStyles_basicUsage} * {@includeCode ./useHostStyles.examples.tsx#useHostStyles_basicUsage}
* *
* @see {@link useHostStyleVariables} for style variables and theme only * @see {@link useHostStyleVariables `useHostStyleVariables`} for style variables and theme only
* @see {@link useHostFonts} for fonts only * @see {@link useHostFonts `useHostFonts`} for fonts only
*/ */
export function useHostStyles( export function useHostStyles(
app: App | null, app: App | null,

2
src/server/index.examples.ts
View file

@ -1,5 +1,5 @@
/** /**
* Type-checked examples for {@link registerAppTool} and {@link registerAppResource}. * Type-checked examples for {@link registerAppTool `registerAppTool`} and {@link registerAppResource `registerAppResource`}.
* *
* These examples are included in the API documentation via `@includeCode` tags. * These examples are included in the API documentation via `@includeCode` tags.
* Each function's region markers define the code snippet that appears in the docs. * Each function's region markers define the code snippet that appears in the docs.

20
src/server/index.ts
View file

@ -2,8 +2,8 @@
* Utilities for MCP servers to register tools and resources that display interactive UIs. * Utilities for MCP servers to register tools and resources that display interactive UIs.
* *
* Use these helpers instead of the base SDK's `registerTool` and `registerResource` when * Use these helpers instead of the base SDK's `registerTool` and `registerResource` when
* your tool should render an {@link app!App} in the client. They handle UI metadata normalization * your tool should render an {@link app!App `App`} in the client. They handle UI metadata normalization
* and provide sensible defaults for the MCP Apps MIME type ({@link RESOURCE_MIME_TYPE}). * and provide sensible defaults for the MCP Apps MIME type ({@link RESOURCE_MIME_TYPE `RESOURCE_MIME_TYPE`}).
* *
* @module server-helpers * @module server-helpers
* *
@ -37,7 +37,7 @@ export type { ResourceMetadata, ToolCallback, ReadResourceCallback };
/** /**
* Base tool configuration matching the standard MCP server tool options. * Base tool configuration matching the standard MCP server tool options.
* Extended by {@link McpUiAppToolConfig} to add UI metadata requirements. * Extended by {@link McpUiAppToolConfig `McpUiAppToolConfig`} to add UI metadata requirements.
*/ */
export interface ToolConfig { export interface ToolConfig {
title?: string; title?: string;
@ -51,12 +51,12 @@ export interface ToolConfig {
/** /**
* Configuration for tools that render an interactive UI. * Configuration for tools that render an interactive UI.
* *
* Extends {@link ToolConfig} with a required `_meta` field that specifies UI metadata. * Extends {@link ToolConfig `ToolConfig`} with a required `_meta` field that specifies UI metadata.
* The UI resource can be specified in two ways: * The UI resource can be specified in two ways:
* - `_meta.ui.resourceUri` (preferred) * - `_meta.ui.resourceUri` (preferred)
* - `_meta["ui/resourceUri"]` (deprecated, for backward compatibility) * - `_meta["ui/resourceUri"]` (deprecated, for backward compatibility)
* *
* @see {@link registerAppTool} for the recommended way to register app tools * @see {@link registerAppTool `registerAppTool`} for the recommended way to register app tools
*/ */
export interface McpUiAppToolConfig extends ToolConfig { export interface McpUiAppToolConfig extends ToolConfig {
_meta: { _meta: {
@ -80,12 +80,12 @@ export interface McpUiAppToolConfig extends ToolConfig {
} }
/** /**
* MCP App Resource configuration for {@link registerAppResource}. * MCP App Resource configuration for {@link registerAppResource `registerAppResource`}.
* *
* Extends the base MCP SDK `ResourceMetadata` with optional UI metadata * Extends the base MCP SDK `ResourceMetadata` with optional UI metadata
* for configuring security policies and rendering preferences. * for configuring security policies and rendering preferences.
* *
* @see {@link registerAppResource} for usage * @see {@link registerAppResource `registerAppResource`} for usage
*/ */
export interface McpUiAppResourceConfig extends ResourceMetadata { export interface McpUiAppResourceConfig extends ResourceMetadata {
/** /**
@ -123,7 +123,7 @@ export interface McpUiAppResourceConfig extends ResourceMetadata {
* @example Tool hidden from model, only callable by UI * @example Tool hidden from model, only callable by UI
* {@includeCode ./index.examples.ts#registerAppTool_appOnlyVisibility} * {@includeCode ./index.examples.ts#registerAppTool_appOnlyVisibility}
* *
* @see {@link registerAppResource} to register the HTML resource referenced by the tool * @see {@link registerAppResource `registerAppResource`} to register the HTML resource referenced by the tool
*/ */
export function registerAppTool< export function registerAppTool<
OutputArgs extends ZodRawShapeCompat | AnySchema, OutputArgs extends ZodRawShapeCompat | AnySchema,
@ -160,7 +160,7 @@ export function registerAppTool<
* Register an app resource with the MCP server. * Register an app resource with the MCP server.
* *
* This is a convenience wrapper around `server.registerResource` that: * This is a convenience wrapper around `server.registerResource` that:
* - Defaults the MIME type to {@link RESOURCE_MIME_TYPE} (`"text/html;profile=mcp-app"`) * - Defaults the MIME type to {@link RESOURCE_MIME_TYPE `RESOURCE_MIME_TYPE`} (`"text/html;profile=mcp-app"`)
* - Provides a cleaner API matching the SDK's callback signature * - Provides a cleaner API matching the SDK's callback signature
* *
* @param server - The MCP server instance * @param server - The MCP server instance
@ -175,7 +175,7 @@ export function registerAppTool<
* @example With CSP configuration for external domains * @example With CSP configuration for external domains
* {@includeCode ./index.examples.ts#registerAppResource_withCsp} * {@includeCode ./index.examples.ts#registerAppResource_withCsp}
* *
* @see {@link registerAppTool} to register tools that reference this resource * @see {@link registerAppTool `registerAppTool`} to register tools that reference this resource
*/ */
export function registerAppResource( export function registerAppResource(
server: Pick<McpServer, "registerResource">, server: Pick<McpServer, "registerResource">,

36
src/spec.types.ts
View file

@ -144,7 +144,7 @@ export type McpUiStyles = Record<McpUiStyleVariableKey, string | undefined>;
/** /**
* @description Request to open an external URL in the host's default browser. * @description Request to open an external URL in the host's default browser.
* @see {@link app!App.openLink} for the method that sends this request * @see {@link app!App.openLink `App.openLink`} for the method that sends this request
*/ */
export interface McpUiOpenLinkRequest { export interface McpUiOpenLinkRequest {
method: "ui/open-link"; method: "ui/open-link";
@ -156,7 +156,7 @@ export interface McpUiOpenLinkRequest {
/** /**
* @description Result from opening a URL. * @description Result from opening a URL.
* @see {@link McpUiOpenLinkRequest} * @see {@link McpUiOpenLinkRequest `McpUiOpenLinkRequest`}
*/ */
export interface McpUiOpenLinkResult { export interface McpUiOpenLinkResult {
/** @description True if the host failed to open the URL (e.g., due to security policy). */ /** @description True if the host failed to open the URL (e.g., due to security policy). */
@ -170,7 +170,7 @@ export interface McpUiOpenLinkResult {
/** /**
* @description Request to send a message to the host's chat interface. * @description Request to send a message to the host's chat interface.
* @see {@link app!App.sendMessage} for the method that sends this request * @see {@link app!App.sendMessage `App.sendMessage`} for the method that sends this request
*/ */
export interface McpUiMessageRequest { export interface McpUiMessageRequest {
method: "ui/message"; method: "ui/message";
@ -184,7 +184,7 @@ export interface McpUiMessageRequest {
/** /**
* @description Result from sending a message. * @description Result from sending a message.
* @see {@link McpUiMessageRequest} * @see {@link McpUiMessageRequest `McpUiMessageRequest`}
*/ */
export interface McpUiMessageResult { export interface McpUiMessageResult {
/** @description True if the host rejected or failed to deliver the message. */ /** @description True if the host rejected or failed to deliver the message. */
@ -227,7 +227,7 @@ export interface McpUiSandboxResourceReadyNotification {
/** /**
* @description Notification of UI size changes (Guest UI -> Host). * @description Notification of UI size changes (Guest UI -> Host).
* @see {@link app!App.sendSizeChanged} for the method to send this from Guest UI * @see {@link app!App.sendSizeChanged `App.sendSizeChanged`} for the method to send this from Guest UI
*/ */
export interface McpUiSizeChangedNotification { export interface McpUiSizeChangedNotification {
method: "ui/notifications/size-changed"; method: "ui/notifications/size-changed";
@ -287,7 +287,7 @@ export interface McpUiToolCancelledNotification {
* @description CSS blocks that can be injected by apps. * @description CSS blocks that can be injected by apps.
*/ */
export interface McpUiHostCss { export interface McpUiHostCss {
/** @description CSS for font loading (`@font-face` rules or `@import` statements). Apps must apply using {@link applyHostFonts}. */ /** @description CSS for font loading (`@font-face` rules or `@import` statements). Apps must apply using {@link applyHostFonts `applyHostFonts`}. */
fonts?: string; fonts?: string;
} }
@ -376,7 +376,7 @@ export interface McpUiHostContext {
/** /**
* @description Notification that host context has changed (Host -> Guest UI). * @description Notification that host context has changed (Host -> Guest UI).
* @see {@link McpUiHostContext} for the full context structure * @see {@link McpUiHostContext `McpUiHostContext`} for the full context structure
*/ */
export interface McpUiHostContextChangedNotification { export interface McpUiHostContextChangedNotification {
method: "ui/notifications/host-context-changed"; method: "ui/notifications/host-context-changed";
@ -394,7 +394,7 @@ export interface McpUiHostContextChangedNotification {
* The host will typically defer sending the context to the model until the next user message * The host will typically defer sending the context to the model until the next user message
* (including `ui/message`), and will only send the last update received. * (including `ui/message`), and will only send the last update received.
* *
* @see {@link app.App.updateModelContext} for the method that sends this request * @see {@link app.App.updateModelContext `App.updateModelContext`} for the method that sends this request
*/ */
export interface McpUiUpdateModelContextRequest { export interface McpUiUpdateModelContextRequest {
method: "ui/update-model-context"; method: "ui/update-model-context";
@ -408,7 +408,7 @@ export interface McpUiUpdateModelContextRequest {
/** /**
* @description Request for graceful shutdown of the Guest UI (Host -> Guest UI). * @description Request for graceful shutdown of the Guest UI (Host -> Guest UI).
* @see {@link app-bridge!AppBridge.teardownResource} for the host method that sends this * @see {@link app-bridge!AppBridge.teardownResource `AppBridge.teardownResource`} for the host method that sends this
*/ */
export interface McpUiResourceTeardownRequest { export interface McpUiResourceTeardownRequest {
method: "ui/resource-teardown"; method: "ui/resource-teardown";
@ -417,7 +417,7 @@ export interface McpUiResourceTeardownRequest {
/** /**
* @description Result from graceful shutdown request. * @description Result from graceful shutdown request.
* @see {@link McpUiResourceTeardownRequest} * @see {@link McpUiResourceTeardownRequest `McpUiResourceTeardownRequest`}
*/ */
export interface McpUiResourceTeardownResult { export interface McpUiResourceTeardownResult {
/** /**
@ -443,7 +443,7 @@ export interface McpUiSupportedContentBlockModalities {
/** /**
* @description Capabilities supported by the host application. * @description Capabilities supported by the host application.
* @see {@link McpUiInitializeResult} for the initialization result that includes these capabilities * @see {@link McpUiInitializeResult `McpUiInitializeResult`} for the initialization result that includes these capabilities
*/ */
export interface McpUiHostCapabilities { export interface McpUiHostCapabilities {
/** @description Experimental features (structure TBD). */ /** @description Experimental features (structure TBD). */
@ -476,8 +476,8 @@ export interface McpUiHostCapabilities {
} }
/** /**
* @description Capabilities provided by the Guest UI ({@link app!App}). * @description Capabilities provided by the Guest UI ({@link app!App `App`}).
* @see {@link McpUiInitializeRequest} for the initialization request that includes these capabilities * @see {@link McpUiInitializeRequest `McpUiInitializeRequest`} for the initialization request that includes these capabilities
*/ */
export interface McpUiAppCapabilities { export interface McpUiAppCapabilities {
/** @description Experimental features (structure TBD). */ /** @description Experimental features (structure TBD). */
@ -491,7 +491,7 @@ export interface McpUiAppCapabilities {
/** /**
* @description Initialization request sent from Guest UI to Host. * @description Initialization request sent from Guest UI to Host.
* @see {@link app!App.connect} for the method that sends this request * @see {@link app!App.connect `App.connect`} for the method that sends this request
*/ */
export interface McpUiInitializeRequest { export interface McpUiInitializeRequest {
method: "ui/initialize"; method: "ui/initialize";
@ -507,7 +507,7 @@ export interface McpUiInitializeRequest {
/** /**
* @description Initialization result returned from Host to Guest UI. * @description Initialization result returned from Host to Guest UI.
* @see {@link McpUiInitializeRequest} * @see {@link McpUiInitializeRequest `McpUiInitializeRequest`}
*/ */
export interface McpUiInitializeResult { export interface McpUiInitializeResult {
/** @description Negotiated protocol version string (e.g., "2025-11-21"). */ /** @description Negotiated protocol version string (e.g., "2025-11-21"). */
@ -527,7 +527,7 @@ export interface McpUiInitializeResult {
/** /**
* @description Notification that Guest UI has completed initialization (Guest UI -> Host). * @description Notification that Guest UI has completed initialization (Guest UI -> Host).
* @see {@link app!App.connect} for the method that sends this notification * @see {@link app!App.connect `App.connect`} for the method that sends this notification
*/ */
export interface McpUiInitializedNotification { export interface McpUiInitializedNotification {
method: "ui/notifications/initialized"; method: "ui/notifications/initialized";
@ -582,7 +582,7 @@ export interface McpUiResourceMeta {
* @description Request to change the display mode of the UI. * @description Request to change the display mode of the UI.
* The host will respond with the actual display mode that was set, * The host will respond with the actual display mode that was set,
* which may differ from the requested mode if not supported. * which may differ from the requested mode if not supported.
* @see {@link app!App.requestDisplayMode} for the method that sends this request * @see {@link app!App.requestDisplayMode `App.requestDisplayMode`} for the method that sends this request
*/ */
export interface McpUiRequestDisplayModeRequest { export interface McpUiRequestDisplayModeRequest {
method: "ui/request-display-mode"; method: "ui/request-display-mode";
@ -594,7 +594,7 @@ export interface McpUiRequestDisplayModeRequest {
/** /**
* @description Result from requesting a display mode change. * @description Result from requesting a display mode change.
* @see {@link McpUiRequestDisplayModeRequest} * @see {@link McpUiRequestDisplayModeRequest `McpUiRequestDisplayModeRequest`}
*/ */
export interface McpUiRequestDisplayModeResult { export interface McpUiRequestDisplayModeResult {
/** @description The display mode that was actually set. May differ from requested if not supported. */ /** @description The display mode that was actually set. May differ from requested if not supported. */

2
src/styles.examples.ts
View file

@ -1,5 +1,5 @@
/** /**
* Type-checked examples for style utilities in {@link ./styles.ts}. * Type-checked examples for style utilities in {@link ./styles.ts `styles.ts`}.
* *
* These examples are included in the API documentation via `@includeCode` tags. * These examples are included in the API documentation via `@includeCode` tags.
* Each function's region markers define the code snippet that appears in the docs. * Each function's region markers define the code snippet that appears in the docs.

16
src/styles.ts
View file

@ -12,8 +12,8 @@ import { McpUiStyles, McpUiTheme } from "./types";
* @example Check current theme * @example Check current theme
* {@includeCode ./styles.examples.ts#getDocumentTheme_checkCurrent} * {@includeCode ./styles.examples.ts#getDocumentTheme_checkCurrent}
* *
* @see {@link applyDocumentTheme} to set the theme * @see {@link applyDocumentTheme `applyDocumentTheme`} to set the theme
* @see {@link McpUiTheme} for the theme type * @see {@link McpUiTheme `McpUiTheme`} for the theme type
*/ */
export function getDocumentTheme(): McpUiTheme { export function getDocumentTheme(): McpUiTheme {
const theme = document.documentElement.getAttribute("data-theme"); const theme = document.documentElement.getAttribute("data-theme");
@ -51,8 +51,8 @@ export function getDocumentTheme(): McpUiTheme {
* } * }
* ``` * ```
* *
* @see {@link getDocumentTheme} to read the current theme * @see {@link getDocumentTheme `getDocumentTheme`} to read the current theme
* @see {@link McpUiTheme} for the theme type * @see {@link McpUiTheme `McpUiTheme`} for the theme type
*/ */
export function applyDocumentTheme(theme: McpUiTheme): void { export function applyDocumentTheme(theme: McpUiTheme): void {
const root = document.documentElement; const root = document.documentElement;
@ -63,7 +63,7 @@ export function applyDocumentTheme(theme: McpUiTheme): void {
/** /**
* Apply host style variables as CSS custom properties on an element. * Apply host style variables as CSS custom properties on an element.
* *
* This function takes the `variables` object from {@link McpUiHostContext.styles} and sets * This function takes the `variables` object from {@link McpUiHostContext.styles `McpUiHostContext.styles`} and sets
* each CSS variable on the specified root element (defaults to `document.documentElement`). * each CSS variable on the specified root element (defaults to `document.documentElement`).
* This allows apps to use the host's theming values via CSS variables like * This allows apps to use the host's theming values via CSS variables like
* `var(--color-background-primary)`. * `var(--color-background-primary)`.
@ -90,8 +90,8 @@ export function applyDocumentTheme(theme: McpUiTheme): void {
* } * }
* ``` * ```
* *
* @see {@link McpUiStyles} for the available CSS variables * @see {@link McpUiStyles `McpUiStyles`} for the available CSS variables
* @see {@link McpUiHostContext} for the full host context structure * @see {@link McpUiHostContext `McpUiHostContext`} for the full host context structure
*/ */
export function applyHostStyleVariables( export function applyHostStyleVariables(
styles: McpUiStyles, styles: McpUiStyles,
@ -133,7 +133,7 @@ export function applyHostStyleVariables(
* } * }
* ``` * ```
* *
* @see {@link McpUiHostContext} for the full host context structure * @see {@link McpUiHostContext `McpUiHostContext`} for the full host context structure
*/ */
export function applyHostFonts(fontCss: string): void { export function applyHostFonts(fontCss: string): void {
const styleId = "__mcp-host-fonts"; const styleId = "__mcp-host-fonts";