Merge pull request #323 from jonathanhefner/format-typedoc-links
Format `{@link}` tags with monospace display text
This commit is contained in:
Jonathan Hefner
GitHub
commit
9e42ee05a3
18 changed files with 217 additions and 217 deletions
|
|
@ -8,7 +8,7 @@ This document covers common patterns and recipes for building MCP 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}
|
||||
|
||||
|
|
@ -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.
|
||||
|
||||
**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}
|
||||
|
||||
|
|
@ -56,11 +56,11 @@ _See [`examples/basic-server-vanillajs/`](https://github.com/modelcontextprotoco
|
|||
|
||||
## 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}
|
||||
|
||||
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}
|
||||
|
||||
|
|
@ -68,7 +68,7 @@ _See [`examples/shadertoy-server/`](https://github.com/modelcontextprotocol/ext-
|
|||
|
||||
## 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}
|
||||
|
||||
|
|
@ -76,7 +76,7 @@ _See [`examples/map-server/`](https://github.com/modelcontextprotocol/ext-apps/t
|
|||
|
||||
## 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}
|
||||
|
||||
|
|
@ -90,7 +90,7 @@ To persist widget state across conversation reloads (e.g., current page in a PDF
|
|||
|
||||
{@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}
|
||||
|
||||
|
|
@ -106,7 +106,7 @@ _See [`examples/shadertoy-server/`](https://github.com/modelcontextprotocol/ext-
|
|||
|
||||
## 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}
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
* Each function's region markers define the code snippet that appears in the docs.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
*
|
||||
* @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 & {
|
||||
hostContext?: McpUiHostContext;
|
||||
|
|
@ -190,7 +190,7 @@ type RequestHandlerExtra = Parameters<
|
|||
>[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
|
||||
* 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
|
||||
* 2. **Connect**: Call `connect()` with transport to establish communication
|
||||
* 3. **Wait for init**: Guest UI sends initialize request, bridge responds
|
||||
* 4. **Send data**: Call {@link sendToolInput}, {@link sendToolResult}, etc.
|
||||
* 5. **Teardown**: Call {@link teardownResource} before unmounting iframe
|
||||
* 4. **Send data**: Call {@link sendToolInput `sendToolInput`}, {@link sendToolResult `sendToolResult`}, etc.
|
||||
* 5. **Teardown**: Call {@link teardownResource `teardownResource`} before unmounting iframe
|
||||
*
|
||||
* @example Basic usage
|
||||
* {@includeCode ./app-bridge.examples.ts#AppBridge_basicUsage}
|
||||
|
|
@ -230,9 +230,9 @@ export class AppBridge extends Protocol<
|
|||
* Create a new AppBridge instance.
|
||||
*
|
||||
* @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
|
||||
* 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 _capabilities - Features and capabilities the host supports
|
||||
* @param options - Configuration options (inherited from Protocol)
|
||||
|
|
@ -282,7 +282,7 @@ export class AppBridge extends Protocol<
|
|||
* @example Check Guest UI capabilities after initialization
|
||||
* {@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 {
|
||||
return this._appCapabilities;
|
||||
|
|
@ -307,7 +307,7 @@ export class AppBridge extends Protocol<
|
|||
* Optional handler for ping requests from the Guest UI.
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* 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
|
||||
* {@includeCode ./app-bridge.examples.ts#AppBridge_onsizechange_handleResize}
|
||||
*
|
||||
* @see {@link McpUiSizeChangedNotification} for the notification type
|
||||
* @see {@link app!App.sendSizeChanged} - the Guest UI method that sends these notifications
|
||||
* @see {@link McpUiSizeChangedNotification `McpUiSizeChangedNotification`} for the notification type
|
||||
* @see {@link app!App.sendSizeChanged `App.sendSizeChanged`} - the Guest UI method that sends these notifications
|
||||
*/
|
||||
set onsizechange(
|
||||
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
|
||||
* 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.
|
||||
*
|
||||
* @example
|
||||
|
|
@ -372,8 +372,8 @@ export class AppBridge extends Protocol<
|
|||
* ```
|
||||
*
|
||||
* @internal
|
||||
* @see {@link McpUiSandboxProxyReadyNotification} for the notification type
|
||||
* @see {@link sendSandboxResourceReady} for sending content to the sandbox
|
||||
* @see {@link McpUiSandboxProxyReadyNotification `McpUiSandboxProxyReadyNotification`} for the notification type
|
||||
* @see {@link sendSandboxResourceReady `sendSandboxResourceReady`} for sending content to the sandbox
|
||||
*/
|
||||
set onsandboxready(
|
||||
callback: (params: McpUiSandboxProxyReadyNotification["params"]) => void,
|
||||
|
|
@ -392,8 +392,8 @@ export class AppBridge extends Protocol<
|
|||
* @example
|
||||
* {@includeCode ./app-bridge.examples.ts#AppBridge_oninitialized_sendToolInput}
|
||||
*
|
||||
* @see {@link McpUiInitializedNotification} for the notification type
|
||||
* @see {@link sendToolInput} for sending tool arguments to the Guest UI
|
||||
* @see {@link McpUiInitializedNotification `McpUiInitializedNotification`} for the notification type
|
||||
* @see {@link sendToolInput `sendToolInput`} for sending tool arguments to the Guest UI
|
||||
*/
|
||||
set oninitialized(
|
||||
callback: (params: McpUiInitializedNotification["params"]) => void,
|
||||
|
|
@ -424,8 +424,8 @@ export class AppBridge extends Protocol<
|
|||
* @example
|
||||
* {@includeCode ./app-bridge.examples.ts#AppBridge_onmessage_logMessage}
|
||||
*
|
||||
* @see {@link McpUiMessageRequest} for the request type
|
||||
* @see {@link McpUiMessageResult} for the result type
|
||||
* @see {@link McpUiMessageRequest `McpUiMessageRequest`} for the request type
|
||||
* @see {@link McpUiMessageResult `McpUiMessageResult`} for the result type
|
||||
*/
|
||||
set onmessage(
|
||||
callback: (
|
||||
|
|
@ -462,8 +462,8 @@ export class AppBridge extends Protocol<
|
|||
* @example
|
||||
* {@includeCode ./app-bridge.examples.ts#AppBridge_onopenlink_handleRequest}
|
||||
*
|
||||
* @see {@link McpUiOpenLinkRequest} for the request type
|
||||
* @see {@link McpUiOpenLinkResult} for the result type
|
||||
* @see {@link McpUiOpenLinkRequest `McpUiOpenLinkRequest`} for the request type
|
||||
* @see {@link McpUiOpenLinkResult `McpUiOpenLinkResult`} for the result type
|
||||
*/
|
||||
set onopenlink(
|
||||
callback: (
|
||||
|
|
@ -501,8 +501,8 @@ export class AppBridge extends Protocol<
|
|||
* @example
|
||||
* {@includeCode ./app-bridge.examples.ts#AppBridge_onrequestdisplaymode_handleRequest}
|
||||
*
|
||||
* @see {@link McpUiRequestDisplayModeRequest} for the request type
|
||||
* @see {@link McpUiRequestDisplayModeResult} for the result type
|
||||
* @see {@link McpUiRequestDisplayModeRequest `McpUiRequestDisplayModeRequest`} for the request type
|
||||
* @see {@link McpUiRequestDisplayModeResult `McpUiRequestDisplayModeResult`} for the result type
|
||||
*/
|
||||
set onrequestdisplaymode(
|
||||
callback: (
|
||||
|
|
@ -563,7 +563,7 @@ export class AppBridge extends Protocol<
|
|||
* @example
|
||||
* {@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(
|
||||
callback: (
|
||||
|
|
@ -866,7 +866,7 @@ export class AppBridge extends Protocol<
|
|||
*
|
||||
* @returns Host capabilities object
|
||||
*
|
||||
* @see {@link McpUiHostCapabilities} for the capabilities structure
|
||||
* @see {@link McpUiHostCapabilities `McpUiHostCapabilities`} for the capabilities structure
|
||||
*/
|
||||
getCapabilities(): McpUiHostCapabilities {
|
||||
return this._capabilities;
|
||||
|
|
@ -920,8 +920,8 @@ export class AppBridge extends Protocol<
|
|||
* @example Update multiple context fields
|
||||
* {@includeCode ./app-bridge.examples.ts#AppBridge_setHostContext_updateMultiple}
|
||||
*
|
||||
* @see {@link McpUiHostContext} for the context structure
|
||||
* @see {@link McpUiHostContextChangedNotification} for the notification type
|
||||
* @see {@link McpUiHostContext `McpUiHostContext`} for the context structure
|
||||
* @see {@link McpUiHostContextChangedNotification `McpUiHostContextChangedNotification`} for the notification type
|
||||
*/
|
||||
setHostContext(hostContext: 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.
|
||||
*
|
||||
* 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.
|
||||
* 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.
|
||||
*
|
||||
* The host MUST send this notification after the Guest UI completes initialization
|
||||
* (after {@link oninitialized} callback fires) and complete tool arguments become available.
|
||||
* This notification is sent exactly once and is required before {@link sendToolResult}.
|
||||
* (after {@link oninitialized `oninitialized`} callback fires) and complete tool arguments become available.
|
||||
* This notification is sent exactly once and is required before {@link sendToolResult `sendToolResult`}.
|
||||
*
|
||||
* @param params - Complete tool call arguments
|
||||
*
|
||||
* @example
|
||||
* {@includeCode ./app-bridge.examples.ts#AppBridge_sendToolInput_afterInit}
|
||||
*
|
||||
* @see {@link McpUiToolInputNotification} for the notification type
|
||||
* @see {@link oninitialized} for the initialization callback
|
||||
* @see {@link sendToolResult} for sending results after execution
|
||||
* @see {@link McpUiToolInputNotification `McpUiToolInputNotification`} for the notification type
|
||||
* @see {@link oninitialized `oninitialized`} for the initialization callback
|
||||
* @see {@link sendToolResult `sendToolResult`} for sending results after execution
|
||||
*/
|
||||
sendToolInput(params: McpUiToolInputNotification["params"]) {
|
||||
return this.notification({
|
||||
|
|
@ -988,7 +988,7 @@ export class AppBridge extends Protocol<
|
|||
* Send streaming partial tool arguments to the Guest UI.
|
||||
*
|
||||
* 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
|
||||
* Guest UI.
|
||||
*
|
||||
|
|
@ -1000,8 +1000,8 @@ export class AppBridge extends Protocol<
|
|||
* @example Stream partial arguments as they arrive
|
||||
* {@includeCode ./app-bridge.examples.ts#AppBridge_sendToolInputPartial_streaming}
|
||||
*
|
||||
* @see {@link McpUiToolInputPartialNotification} for the notification type
|
||||
* @see {@link sendToolInput} for sending complete arguments
|
||||
* @see {@link McpUiToolInputPartialNotification `McpUiToolInputPartialNotification`} for the notification type
|
||||
* @see {@link sendToolInput `sendToolInput`} for sending complete arguments
|
||||
*/
|
||||
sendToolInputPartial(params: McpUiToolInputPartialNotification["params"]) {
|
||||
return this.notification({
|
||||
|
|
@ -1016,15 +1016,15 @@ export class AppBridge extends Protocol<
|
|||
* The host MUST send this notification when tool execution completes successfully,
|
||||
* 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
|
||||
* {@link sendToolInput}.
|
||||
* {@link sendToolInput `sendToolInput`}.
|
||||
*
|
||||
* @param params - Standard MCP tool execution result
|
||||
*
|
||||
* @example
|
||||
* {@includeCode ./app-bridge.examples.ts#AppBridge_sendToolResult_afterExecution}
|
||||
*
|
||||
* @see {@link McpUiToolResultNotification} for the notification type
|
||||
* @see {@link sendToolInput} for sending tool arguments before results
|
||||
* @see {@link McpUiToolResultNotification `McpUiToolResultNotification`} for the notification type
|
||||
* @see {@link sendToolInput `sendToolInput`} for sending tool arguments before results
|
||||
*/
|
||||
sendToolResult(params: McpUiToolResultNotification["params"]) {
|
||||
return this.notification({
|
||||
|
|
@ -1050,9 +1050,9 @@ export class AppBridge extends Protocol<
|
|||
* @example System-level cancellation
|
||||
* {@includeCode ./app-bridge.examples.ts#AppBridge_sendToolCancelled_systemLevel}
|
||||
*
|
||||
* @see {@link McpUiToolCancelledNotification} for the notification type
|
||||
* @see {@link sendToolResult} for sending successful results
|
||||
* @see {@link sendToolInput} for sending tool arguments
|
||||
* @see {@link McpUiToolCancelledNotification `McpUiToolCancelledNotification`} for the notification type
|
||||
* @see {@link sendToolResult `sendToolResult`} for sending successful results
|
||||
* @see {@link sendToolInput `sendToolInput`} for sending tool arguments
|
||||
*/
|
||||
sendToolCancelled(params: McpUiToolCancelledNotification["params"]) {
|
||||
return this.notification({
|
||||
|
|
@ -1074,7 +1074,7 @@ export class AppBridge extends Protocol<
|
|||
* - `sandbox`: Optional sandbox attribute value (e.g., "allow-scripts")
|
||||
*
|
||||
* @internal
|
||||
* @see {@link onsandboxready} for handling the sandbox proxy ready notification
|
||||
* @see {@link onsandboxready `onsandboxready`} for handling the sandbox proxy ready notification
|
||||
*/
|
||||
sendSandboxResourceReady(
|
||||
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;
|
||||
|
||||
/**
|
||||
|
|
@ -1129,13 +1129,13 @@ export class AppBridge extends Protocol<
|
|||
* - Prompts (prompts/list, notifications/prompts/list_changed)
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* @param transport - Transport layer (typically {@link PostMessageTransport})
|
||||
* @param transport - Transport layer (typically {@link PostMessageTransport `PostMessageTransport`})
|
||||
* @returns Promise resolving when connection is established
|
||||
*
|
||||
* @throws {Error} If a client was passed but server capabilities are not available.
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
* Each function's region markers define the code snippet that appears in the docs.
|
||||
|
|
|
|||
118
src/app.ts
118
src/app.ts
|
|
@ -65,10 +65,10 @@ export {
|
|||
* 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.
|
||||
* 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
|
||||
* 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.
|
||||
*
|
||||
* @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.
|
||||
*
|
||||
* 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";
|
||||
|
||||
/**
|
||||
* Options for configuring {@link App} behavior.
|
||||
* Options for configuring {@link App `App`} behavior.
|
||||
*
|
||||
* 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`.
|
||||
*
|
||||
* 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`
|
||||
* notifications to the host.
|
||||
*
|
||||
|
|
@ -122,7 +122,7 @@ type RequestHandlerExtra = Parameters<
|
|||
*
|
||||
* ## 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
|
||||
* 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.
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* @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
|
||||
* {@includeCode ./app.examples.ts#App_getHostCapabilities_checkAfterConnection}
|
||||
*
|
||||
* @see {@link connect} for the initialization handshake
|
||||
* @see {@link McpUiHostCapabilities} for the capabilities structure
|
||||
* @see {@link connect `connect`} for the initialization handshake
|
||||
* @see {@link McpUiHostCapabilities `McpUiHostCapabilities`} for the capabilities structure
|
||||
*/
|
||||
getHostCapabilities(): McpUiHostCapabilities | undefined {
|
||||
return this._hostCapabilities;
|
||||
|
|
@ -212,7 +212,7 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
|
|||
* Get the host's implementation info discovered during initialization.
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* @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
|
||||
* {@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 {
|
||||
return this._hostInfo;
|
||||
|
|
@ -241,9 +241,9 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
|
|||
* @example Access host context after connection
|
||||
* {@includeCode ./app.examples.ts#App_getHostContext_accessAfterConnection}
|
||||
*
|
||||
* @see {@link connect} for the initialization handshake
|
||||
* @see {@link onhostcontextchanged} for context change notifications
|
||||
* @see {@link McpUiHostContext} for the context structure
|
||||
* @see {@link connect `connect`} for the initialization handshake
|
||||
* @see {@link onhostcontextchanged `onhostcontextchanged`} for context change notifications
|
||||
* @see {@link McpUiHostContext `McpUiHostContext`} for the context structure
|
||||
*/
|
||||
getHostContext(): McpUiHostContext | undefined {
|
||||
return this._hostContext;
|
||||
|
|
@ -259,15 +259,15 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
|
|||
* This setter is a convenience wrapper around `setNotificationHandler()` that
|
||||
* 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
|
||||
* {@includeCode ./app.examples.ts#App_ontoolinput_setter}
|
||||
*
|
||||
* @see {@link setNotificationHandler} for the underlying method
|
||||
* @see {@link McpUiToolInputNotification} for the notification structure
|
||||
* @see {@link setNotificationHandler `setNotificationHandler`} for the underlying method
|
||||
* @see {@link McpUiToolInputNotification `McpUiToolInputNotification`} for the notification structure
|
||||
*/
|
||||
set ontoolinput(
|
||||
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
|
||||
* 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
|
||||
* {@includeCode ./app.examples.ts#App_ontoolinputpartial_progressiveRendering}
|
||||
*
|
||||
* @see {@link setNotificationHandler} for the underlying method
|
||||
* @see {@link McpUiToolInputPartialNotification} for the notification structure
|
||||
* @see {@link ontoolinput} for the complete tool input handler
|
||||
* @see {@link setNotificationHandler `setNotificationHandler`} for the underlying method
|
||||
* @see {@link McpUiToolInputPartialNotification `McpUiToolInputPartialNotification`} for the notification structure
|
||||
* @see {@link ontoolinput `ontoolinput`} for the complete tool input handler
|
||||
*/
|
||||
set ontoolinputpartial(
|
||||
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
|
||||
* 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
|
||||
* {@includeCode ./app.examples.ts#App_ontoolresult_displayResults}
|
||||
*
|
||||
* @see {@link setNotificationHandler} for the underlying method
|
||||
* @see {@link McpUiToolResultNotification} for the notification structure
|
||||
* @see {@link ontoolinput} for the initial tool input handler
|
||||
* @see {@link setNotificationHandler `setNotificationHandler`} for the underlying method
|
||||
* @see {@link McpUiToolResultNotification `McpUiToolResultNotification`} for the notification structure
|
||||
* @see {@link ontoolinput `ontoolinput`} for the initial tool input handler
|
||||
*/
|
||||
set ontoolresult(
|
||||
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
|
||||
* 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
|
||||
* {@includeCode ./app.examples.ts#App_ontoolcancelled_handleCancellation}
|
||||
*
|
||||
* @see {@link setNotificationHandler} for the underlying method
|
||||
* @see {@link McpUiToolCancelledNotification} for the notification structure
|
||||
* @see {@link ontoolresult} for successful tool completion
|
||||
* @see {@link setNotificationHandler `setNotificationHandler`} for the underlying method
|
||||
* @see {@link McpUiToolCancelledNotification `McpUiToolCancelledNotification`} for the notification structure
|
||||
* @see {@link ontoolresult `ontoolresult`} for successful tool completion
|
||||
*/
|
||||
set ontoolcancelled(
|
||||
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.
|
||||
*
|
||||
* 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.
|
||||
*
|
||||
* 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
|
||||
*
|
||||
* @example Respond to theme changes
|
||||
* {@includeCode ./app.examples.ts#App_onhostcontextchanged_respondToTheme}
|
||||
*
|
||||
* @see {@link setNotificationHandler} for the underlying method
|
||||
* @see {@link McpUiHostContextChangedNotification} for the notification structure
|
||||
* @see {@link McpUiHostContext} for the full context structure
|
||||
* @see {@link setNotificationHandler `setNotificationHandler`} for the underlying method
|
||||
* @see {@link McpUiHostContextChangedNotification `McpUiHostContextChangedNotification`} for the notification structure
|
||||
* @see {@link McpUiHostContext `McpUiHostContext`} for the full context structure
|
||||
*/
|
||||
set onhostcontextchanged(
|
||||
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
|
||||
* 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.
|
||||
* 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
|
||||
* {@includeCode ./app.examples.ts#App_onteardown_performCleanup}
|
||||
*
|
||||
* @see {@link setRequestHandler} for the underlying method
|
||||
* @see {@link McpUiResourceTeardownRequest} for the request structure
|
||||
* @see {@link setRequestHandler `setRequestHandler`} for the underlying method
|
||||
* @see {@link McpUiResourceTeardownRequest `McpUiResourceTeardownRequest`} for the request structure
|
||||
*/
|
||||
set onteardown(
|
||||
callback: (
|
||||
|
|
@ -457,7 +457,7 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
|
|||
* This setter is a convenience wrapper around `setRequestHandler()` that
|
||||
* 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.
|
||||
* 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
|
||||
* {@includeCode ./app.examples.ts#App_oncalltool_handleFromHost}
|
||||
*
|
||||
* @see {@link setRequestHandler} for the underlying method
|
||||
* @see {@link setRequestHandler `setRequestHandler`} for the underlying method
|
||||
*/
|
||||
set oncalltool(
|
||||
callback: (
|
||||
|
|
@ -491,7 +491,7 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
|
|||
* This setter is a convenience wrapper around `setRequestHandler()` that
|
||||
* 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
|
||||
* 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
|
||||
* {@includeCode ./app.examples.ts#App_onlisttools_returnTools}
|
||||
*
|
||||
* @see {@link setRequestHandler} for the underlying method
|
||||
* @see {@link oncalltool} for handling tool execution
|
||||
* @see {@link setRequestHandler `setRequestHandler`} for the underlying method
|
||||
* @see {@link oncalltool `oncalltool`} for handling tool execution
|
||||
*/
|
||||
set onlisttools(
|
||||
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
|
||||
* {@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) {
|
||||
return this.request(
|
||||
|
|
@ -655,7 +655,7 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
|
|||
* Update the host's model context with app state.
|
||||
*
|
||||
* 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
|
||||
* 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
|
||||
* {@includeCode ./app.examples.ts#App_openLink_documentation}
|
||||
*
|
||||
* @see {@link McpUiOpenLinkRequest} for request structure
|
||||
* @see {@link McpUiOpenLinkResult} for result structure
|
||||
* @see {@link McpUiOpenLinkRequest `McpUiOpenLinkRequest`} for request structure
|
||||
* @see {@link McpUiOpenLinkResult `McpUiOpenLinkResult`} for result structure
|
||||
*/
|
||||
openLink(params: McpUiOpenLinkRequest["params"], options?: RequestOptions) {
|
||||
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;
|
||||
|
||||
/**
|
||||
|
|
@ -736,8 +736,8 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
|
|||
* @example Toggle display mode
|
||||
* {@includeCode ./app.examples.ts#App_requestDisplayMode_toggle}
|
||||
*
|
||||
* @see {@link McpUiRequestDisplayModeRequest} for request structure
|
||||
* @see {@link McpUiHostContext} for checking availableDisplayModes
|
||||
* @see {@link McpUiRequestDisplayModeRequest `McpUiRequestDisplayModeRequest`} for request structure
|
||||
* @see {@link McpUiHostContext `McpUiHostContext`} for checking availableDisplayModes
|
||||
*/
|
||||
requestDisplayMode(
|
||||
params: McpUiRequestDisplayModeRequest["params"],
|
||||
|
|
@ -766,7 +766,7 @@ export class App extends Protocol<AppRequest, AppNotification, AppResult> {
|
|||
*
|
||||
* @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"]) {
|
||||
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
|
||||
* 3. Receives host capabilities and context in response
|
||||
* 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
|
||||
* 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
|
||||
*
|
||||
* @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
|
||||
* {@includeCode ./app.examples.ts#App_connect_withPostMessageTransport}
|
||||
*
|
||||
* @see {@link McpUiInitializeRequest} for the initialization request structure
|
||||
* @see {@link McpUiInitializedNotification} for the initialized notification
|
||||
* @see {@link PostMessageTransport} for the typical transport implementation
|
||||
* @see {@link McpUiInitializeRequest `McpUiInitializeRequest`} for the initialization request structure
|
||||
* @see {@link McpUiInitializedNotification `McpUiInitializedNotification`} for the initialized notification
|
||||
* @see {@link PostMessageTransport `PostMessageTransport`} for the typical transport implementation
|
||||
*/
|
||||
override async connect(
|
||||
transport: Transport = new PostMessageTransport(
|
||||
|
|
|
|||
36
src/generated/schema.ts
generated
36
src/generated/schema.ts
generated
|
|
@ -135,7 +135,7 @@ export const McpUiStylesSchema = z
|
|||
|
||||
/**
|
||||
* @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({
|
||||
method: z.literal("ui/open-link"),
|
||||
|
|
@ -147,7 +147,7 @@ export const McpUiOpenLinkRequestSchema = z.object({
|
|||
|
||||
/**
|
||||
* @description Result from opening a URL.
|
||||
* @see {@link McpUiOpenLinkRequest}
|
||||
* @see {@link McpUiOpenLinkRequest `McpUiOpenLinkRequest`}
|
||||
*/
|
||||
export const McpUiOpenLinkResultSchema = z
|
||||
.object({
|
||||
|
|
@ -163,7 +163,7 @@ export const McpUiOpenLinkResultSchema = z
|
|||
|
||||
/**
|
||||
* @description Result from sending a message.
|
||||
* @see {@link McpUiMessageRequest}
|
||||
* @see {@link McpUiMessageRequest `McpUiMessageRequest`}
|
||||
*/
|
||||
export const McpUiMessageResultSchema = z
|
||||
.object({
|
||||
|
|
@ -247,7 +247,7 @@ export const McpUiResourcePermissionsSchema = z.object({
|
|||
|
||||
/**
|
||||
* @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({
|
||||
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.
|
||||
*/
|
||||
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(),
|
||||
});
|
||||
|
||||
|
|
@ -339,7 +339,7 @@ export const McpUiHostStylesSchema = z.object({
|
|||
|
||||
/**
|
||||
* @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({
|
||||
method: z.literal("ui/resource-teardown"),
|
||||
|
|
@ -348,7 +348,7 @@ export const McpUiResourceTeardownRequestSchema = z.object({
|
|||
|
||||
/**
|
||||
* @description Result from graceful shutdown request.
|
||||
* @see {@link McpUiResourceTeardownRequest}
|
||||
* @see {@link McpUiResourceTeardownRequest `McpUiResourceTeardownRequest`}
|
||||
*/
|
||||
export const McpUiResourceTeardownResultSchema = z.record(
|
||||
z.string(),
|
||||
|
|
@ -387,7 +387,7 @@ export const McpUiSupportedContentBlockModalitiesSchema = z.object({
|
|||
|
||||
/**
|
||||
* @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({
|
||||
/** @description Experimental features (structure TBD). */
|
||||
|
|
@ -450,8 +450,8 @@ export const McpUiHostCapabilitiesSchema = z.object({
|
|||
});
|
||||
|
||||
/**
|
||||
* @description Capabilities provided by the Guest UI ({@link app!App}).
|
||||
* @see {@link McpUiInitializeRequest} for the initialization request that includes these capabilities
|
||||
* @description Capabilities provided by the Guest UI ({@link app!App `App`}).
|
||||
* @see {@link McpUiInitializeRequest `McpUiInitializeRequest`} for the initialization request that includes these capabilities
|
||||
*/
|
||||
export const McpUiAppCapabilitiesSchema = z.object({
|
||||
/** @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).
|
||||
* @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({
|
||||
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.
|
||||
* The host will respond with the actual display mode that was set,
|
||||
* 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({
|
||||
method: z.literal("ui/request-display-mode"),
|
||||
|
|
@ -523,7 +523,7 @@ export const McpUiRequestDisplayModeRequestSchema = z.object({
|
|||
|
||||
/**
|
||||
* @description Result from requesting a display mode change.
|
||||
* @see {@link McpUiRequestDisplayModeRequest}
|
||||
* @see {@link McpUiRequestDisplayModeRequest `McpUiRequestDisplayModeRequest`}
|
||||
*/
|
||||
export const McpUiRequestDisplayModeResultSchema = z
|
||||
.object({
|
||||
|
|
@ -567,7 +567,7 @@ export const McpUiToolMetaSchema = z.object({
|
|||
|
||||
/**
|
||||
* @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({
|
||||
method: z.literal("ui/message"),
|
||||
|
|
@ -740,7 +740,7 @@ export const McpUiHostContextSchema = z
|
|||
|
||||
/**
|
||||
* @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({
|
||||
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
|
||||
* (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({
|
||||
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.
|
||||
* @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({
|
||||
method: z.literal("ui/initialize"),
|
||||
|
|
@ -805,7 +805,7 @@ export const McpUiInitializeRequestSchema = z.object({
|
|||
|
||||
/**
|
||||
* @description Initialization result returned from Host to Guest UI.
|
||||
* @see {@link McpUiInitializeRequest}
|
||||
* @see {@link McpUiInitializeRequest `McpUiInitializeRequest`}
|
||||
*/
|
||||
export const McpUiInitializeResultSchema = z
|
||||
.object({
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
* Each function's region markers define the code snippet that appears in the docs.
|
||||
|
|
|
|||
|
|
@ -29,8 +29,8 @@ import {
|
|||
* **Host**:
|
||||
* {@includeCode ./message-transport.examples.ts#PostMessageTransport_host}
|
||||
*
|
||||
* @see {@link app!App.connect} for Guest UI usage
|
||||
* @see {@link app-bridge!AppBridge.connect} for Host usage
|
||||
* @see {@link app!App.connect `App.connect`} for Guest UI usage
|
||||
* @see {@link app-bridge!AppBridge.connect `AppBridge.connect`} for Host usage
|
||||
*/
|
||||
export class PostMessageTransport implements Transport {
|
||||
private messageListener: (
|
||||
|
|
@ -102,7 +102,7 @@ export class PostMessageTransport implements Transport {
|
|||
/**
|
||||
* 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() {
|
||||
window.removeEventListener("message", this.messageListener);
|
||||
|
|
@ -112,7 +112,7 @@ export class PostMessageTransport implements Transport {
|
|||
/**
|
||||
* 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;
|
||||
|
||||
|
|
@ -129,7 +129,7 @@ export class PostMessageTransport implements Transport {
|
|||
/**
|
||||
* 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.
|
||||
*
|
||||
* @param message - The validated JSON-RPC message
|
||||
|
|
|
|||
|
|
@ -3,16 +3,16 @@
|
|||
*
|
||||
* This module provides React hooks and utilities for easily building
|
||||
* 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.
|
||||
*
|
||||
* ## Main Exports
|
||||
*
|
||||
* - {@link useApp} - React hook to create and connect an MCP App
|
||||
* - {@link useHostStyleVariables} - React hook to apply host style variables and theme
|
||||
* - {@link useHostFonts} - React hook to apply host fonts
|
||||
* - {@link useDocumentTheme} - React hook for reactive document theme
|
||||
* - {@link useAutoResize} - React hook for manual auto-resize control (rarely needed)
|
||||
* - {@link useApp `useApp`} - React hook to create and connect an MCP App
|
||||
* - {@link useHostStyleVariables `useHostStyleVariables`} - React hook to apply host style variables and theme
|
||||
* - {@link useHostFonts `useHostFonts`} - React hook to apply host fonts
|
||||
* - {@link useDocumentTheme `useDocumentTheme`} - React hook for reactive document theme
|
||||
* - {@link useAutoResize `useAutoResize`} - React hook for manual auto-resize control (rarely needed)
|
||||
*
|
||||
* @module @modelcontextprotocol/ext-apps/react
|
||||
*
|
||||
|
|
|
|||
|
|
@ -5,14 +5,14 @@ import { App, McpUiAppCapabilities, PostMessageTransport } 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
|
||||
* 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 useAutoResize} for manual auto-resize control with custom `App` options
|
||||
* @see {@link useApp `useApp`} for the hook that uses these options
|
||||
* @see {@link useAutoResize `useAutoResize`} for manual auto-resize control with custom `App` options
|
||||
*/
|
||||
export interface UseAppOptions {
|
||||
/** App identification (name and version) */
|
||||
|
|
@ -22,7 +22,7 @@ export interface UseAppOptions {
|
|||
*/
|
||||
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
|
||||
* 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 {
|
||||
/** The connected {@link App} instance, null during initialization */
|
||||
/** The connected {@link App `App`} instance, null during initialization */
|
||||
app: App | null;
|
||||
/** Whether initialization completed successfully */
|
||||
isConnected: boolean;
|
||||
|
|
@ -50,8 +50,8 @@ export interface AppState {
|
|||
/**
|
||||
* React hook to create and connect an MCP App.
|
||||
*
|
||||
* This hook manages {@link App} creation and connection. It automatically
|
||||
* creates a {@link PostMessageTransport} to window.parent and handles
|
||||
* This hook manages {@link App `App`} creation and connection. It automatically
|
||||
* creates a {@link PostMessageTransport `PostMessageTransport`} to window.parent and handles
|
||||
* initialization.
|
||||
*
|
||||
* 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.
|
||||
* 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
|
||||
* 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
|
||||
* @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
|
||||
* {@includeCode ./useApp.examples.tsx#useApp_basicUsage}
|
||||
*
|
||||
* @see {@link App.connect} for the underlying connection method
|
||||
* @see {@link useAutoResize} for manual auto-resize control when using custom App options
|
||||
* @see {@link App.connect `App.connect`} for the underlying connection method
|
||||
* @see {@link useAutoResize `useAutoResize`} for manual auto-resize control when using custom App options
|
||||
*/
|
||||
export function useApp({
|
||||
appInfo,
|
||||
|
|
|
|||
|
|
@ -9,12 +9,12 @@ import { App } from "../app";
|
|||
*
|
||||
* 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
|
||||
* 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.
|
||||
*
|
||||
* @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`
|
||||
* and `document.documentElement` regardless of this value. Passing a ref will
|
||||
* 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
|
||||
* {@includeCode ./useAutoResize.examples.tsx#useAutoResize_manualApp}
|
||||
*
|
||||
* @see {@link App.setupSizeChangedNotifications} for the underlying implementation
|
||||
* @see {@link useApp} which enables auto-resize by default
|
||||
* @see {@link App} constructor for configuring `autoResize` option
|
||||
* @see {@link App.setupSizeChangedNotifications `App.setupSizeChangedNotifications`} for the underlying implementation
|
||||
* @see {@link useApp `useApp`} which enables auto-resize by default
|
||||
* @see {@link App `App`} constructor for configuring `autoResize` option
|
||||
*/
|
||||
export function useAutoResize(
|
||||
app: App | null,
|
||||
|
|
|
|||
|
|
@ -20,8 +20,8 @@ import { McpUiTheme } from "../types";
|
|||
* @example Use with theme-aware styling
|
||||
* {@includeCode ./useDocumentTheme.examples.tsx#useDocumentTheme_themedButton}
|
||||
*
|
||||
* @see {@link getDocumentTheme} for the underlying function
|
||||
* @see {@link applyDocumentTheme} to set the theme
|
||||
* @see {@link getDocumentTheme `getDocumentTheme`} for the underlying function
|
||||
* @see {@link applyDocumentTheme `applyDocumentTheme`} to set the theme
|
||||
*/
|
||||
export function useDocumentTheme(): McpUiTheme {
|
||||
const [theme, setTheme] = useState<McpUiTheme>(getDocumentTheme);
|
||||
|
|
|
|||
|
|
@ -21,17 +21,17 @@ import { McpUiHostContext } from "../types";
|
|||
* this hook ensures they work correctly by setting the `color-scheme` property
|
||||
* 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).
|
||||
* If provided, styles and theme will be applied immediately on mount.
|
||||
*
|
||||
* @example
|
||||
* {@includeCode ./useHostStyles.examples.tsx#useHostStyleVariables_basicUsage}
|
||||
*
|
||||
* @see {@link applyHostStyleVariables} for the underlying styles function
|
||||
* @see {@link applyDocumentTheme} for the underlying theme function
|
||||
* @see {@link useHostFonts} for applying host fonts
|
||||
* @see {@link McpUiStyles} for available CSS variables
|
||||
* @see {@link applyHostStyleVariables `applyHostStyleVariables`} for the underlying styles function
|
||||
* @see {@link applyDocumentTheme `applyDocumentTheme`} for the underlying theme function
|
||||
* @see {@link useHostFonts `useHostFonts`} for applying host fonts
|
||||
* @see {@link McpUiStyles `McpUiStyles`} for available CSS variables
|
||||
*/
|
||||
export function useHostStyleVariables(
|
||||
app: App | null,
|
||||
|
|
@ -84,15 +84,15 @@ export function useHostStyleVariables(
|
|||
* The hook also applies fonts from the initial host context when
|
||||
* 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).
|
||||
* If provided, fonts will be applied immediately on mount.
|
||||
*
|
||||
* @example Basic usage with useApp
|
||||
* {@includeCode ./useHostStyles.examples.tsx#useHostFonts_basicUsage}
|
||||
*
|
||||
* @see {@link applyHostFonts} for the underlying fonts function
|
||||
* @see {@link useHostStyleVariables} for applying style variables and theme
|
||||
* @see {@link applyHostFonts `applyHostFonts`} for the underlying fonts function
|
||||
* @see {@link useHostStyleVariables `useHostStyleVariables`} for applying style variables and theme
|
||||
*/
|
||||
export function useHostFonts(
|
||||
app: App | null,
|
||||
|
|
@ -128,18 +128,18 @@ export function useHostFonts(
|
|||
/**
|
||||
* Applies all host styling (CSS variables, theme, and fonts) to match the host application.
|
||||
*
|
||||
* This is a convenience hook that combines {@link useHostStyleVariables} and
|
||||
* {@link useHostFonts}. Use the individual hooks if you need more control.
|
||||
* This is a convenience hook that combines {@link useHostStyleVariables `useHostStyleVariables`} and
|
||||
* {@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).
|
||||
* Pass `app?.getHostContext()` to apply styles immediately on mount.
|
||||
*
|
||||
* @example
|
||||
* {@includeCode ./useHostStyles.examples.tsx#useHostStyles_basicUsage}
|
||||
*
|
||||
* @see {@link useHostStyleVariables} for style variables and theme only
|
||||
* @see {@link useHostFonts} for fonts only
|
||||
* @see {@link useHostStyleVariables `useHostStyleVariables`} for style variables and theme only
|
||||
* @see {@link useHostFonts `useHostFonts`} for fonts only
|
||||
*/
|
||||
export function useHostStyles(
|
||||
app: App | null,
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
* Each function's region markers define the code snippet that appears in the docs.
|
||||
|
|
|
|||
|
|
@ -2,8 +2,8 @@
|
|||
* 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
|
||||
* your tool should render an {@link app!App} in the client. They handle UI metadata normalization
|
||||
* and provide sensible defaults for the MCP Apps MIME type ({@link RESOURCE_MIME_TYPE}).
|
||||
* 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 `RESOURCE_MIME_TYPE`}).
|
||||
*
|
||||
* @module server-helpers
|
||||
*
|
||||
|
|
@ -37,7 +37,7 @@ export type { ResourceMetadata, ToolCallback, ReadResourceCallback };
|
|||
|
||||
/**
|
||||
* 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 {
|
||||
title?: string;
|
||||
|
|
@ -51,12 +51,12 @@ export interface ToolConfig {
|
|||
/**
|
||||
* 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:
|
||||
* - `_meta.ui.resourceUri` (preferred)
|
||||
* - `_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 {
|
||||
_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
|
||||
* for configuring security policies and rendering preferences.
|
||||
*
|
||||
* @see {@link registerAppResource} for usage
|
||||
* @see {@link registerAppResource `registerAppResource`} for usage
|
||||
*/
|
||||
export interface McpUiAppResourceConfig extends ResourceMetadata {
|
||||
/**
|
||||
|
|
@ -123,7 +123,7 @@ export interface McpUiAppResourceConfig extends ResourceMetadata {
|
|||
* @example Tool hidden from model, only callable by UI
|
||||
* {@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<
|
||||
OutputArgs extends ZodRawShapeCompat | AnySchema,
|
||||
|
|
@ -160,7 +160,7 @@ export function registerAppTool<
|
|||
* Register an app resource with the MCP server.
|
||||
*
|
||||
* 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
|
||||
*
|
||||
* @param server - The MCP server instance
|
||||
|
|
@ -175,7 +175,7 @@ export function registerAppTool<
|
|||
* @example With CSP configuration for external domains
|
||||
* {@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(
|
||||
server: Pick<McpServer, "registerResource">,
|
||||
|
|
|
|||
|
|
@ -144,7 +144,7 @@ export type McpUiStyles = Record<McpUiStyleVariableKey, string | undefined>;
|
|||
|
||||
/**
|
||||
* @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 {
|
||||
method: "ui/open-link";
|
||||
|
|
@ -156,7 +156,7 @@ export interface McpUiOpenLinkRequest {
|
|||
|
||||
/**
|
||||
* @description Result from opening a URL.
|
||||
* @see {@link McpUiOpenLinkRequest}
|
||||
* @see {@link McpUiOpenLinkRequest `McpUiOpenLinkRequest`}
|
||||
*/
|
||||
export interface McpUiOpenLinkResult {
|
||||
/** @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.
|
||||
* @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 {
|
||||
method: "ui/message";
|
||||
|
|
@ -184,7 +184,7 @@ export interface McpUiMessageRequest {
|
|||
|
||||
/**
|
||||
* @description Result from sending a message.
|
||||
* @see {@link McpUiMessageRequest}
|
||||
* @see {@link McpUiMessageRequest `McpUiMessageRequest`}
|
||||
*/
|
||||
export interface McpUiMessageResult {
|
||||
/** @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).
|
||||
* @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 {
|
||||
method: "ui/notifications/size-changed";
|
||||
|
|
@ -287,7 +287,7 @@ export interface McpUiToolCancelledNotification {
|
|||
* @description CSS blocks that can be injected by apps.
|
||||
*/
|
||||
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;
|
||||
}
|
||||
|
||||
|
|
@ -376,7 +376,7 @@ export interface McpUiHostContext {
|
|||
|
||||
/**
|
||||
* @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 {
|
||||
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
|
||||
* (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 {
|
||||
method: "ui/update-model-context";
|
||||
|
|
@ -408,7 +408,7 @@ export interface McpUiUpdateModelContextRequest {
|
|||
|
||||
/**
|
||||
* @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 {
|
||||
method: "ui/resource-teardown";
|
||||
|
|
@ -417,7 +417,7 @@ export interface McpUiResourceTeardownRequest {
|
|||
|
||||
/**
|
||||
* @description Result from graceful shutdown request.
|
||||
* @see {@link McpUiResourceTeardownRequest}
|
||||
* @see {@link McpUiResourceTeardownRequest `McpUiResourceTeardownRequest`}
|
||||
*/
|
||||
export interface McpUiResourceTeardownResult {
|
||||
/**
|
||||
|
|
@ -443,7 +443,7 @@ export interface McpUiSupportedContentBlockModalities {
|
|||
|
||||
/**
|
||||
* @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 {
|
||||
/** @description Experimental features (structure TBD). */
|
||||
|
|
@ -476,8 +476,8 @@ export interface McpUiHostCapabilities {
|
|||
}
|
||||
|
||||
/**
|
||||
* @description Capabilities provided by the Guest UI ({@link app!App}).
|
||||
* @see {@link McpUiInitializeRequest} for the initialization request that includes these capabilities
|
||||
* @description Capabilities provided by the Guest UI ({@link app!App `App`}).
|
||||
* @see {@link McpUiInitializeRequest `McpUiInitializeRequest`} for the initialization request that includes these capabilities
|
||||
*/
|
||||
export interface McpUiAppCapabilities {
|
||||
/** @description Experimental features (structure TBD). */
|
||||
|
|
@ -491,7 +491,7 @@ export interface McpUiAppCapabilities {
|
|||
|
||||
/**
|
||||
* @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 {
|
||||
method: "ui/initialize";
|
||||
|
|
@ -507,7 +507,7 @@ export interface McpUiInitializeRequest {
|
|||
|
||||
/**
|
||||
* @description Initialization result returned from Host to Guest UI.
|
||||
* @see {@link McpUiInitializeRequest}
|
||||
* @see {@link McpUiInitializeRequest `McpUiInitializeRequest`}
|
||||
*/
|
||||
export interface McpUiInitializeResult {
|
||||
/** @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).
|
||||
* @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 {
|
||||
method: "ui/notifications/initialized";
|
||||
|
|
@ -582,7 +582,7 @@ export interface McpUiResourceMeta {
|
|||
* @description Request to change the display mode of the UI.
|
||||
* The host will respond with the actual display mode that was set,
|
||||
* 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 {
|
||||
method: "ui/request-display-mode";
|
||||
|
|
@ -594,7 +594,7 @@ export interface McpUiRequestDisplayModeRequest {
|
|||
|
||||
/**
|
||||
* @description Result from requesting a display mode change.
|
||||
* @see {@link McpUiRequestDisplayModeRequest}
|
||||
* @see {@link McpUiRequestDisplayModeRequest `McpUiRequestDisplayModeRequest`}
|
||||
*/
|
||||
export interface McpUiRequestDisplayModeResult {
|
||||
/** @description The display mode that was actually set. May differ from requested if not supported. */
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
* Each function's region markers define the code snippet that appears in the docs.
|
||||
|
|
|
|||
|
|
@ -12,8 +12,8 @@ import { McpUiStyles, McpUiTheme } from "./types";
|
|||
* @example Check current theme
|
||||
* {@includeCode ./styles.examples.ts#getDocumentTheme_checkCurrent}
|
||||
*
|
||||
* @see {@link applyDocumentTheme} to set the theme
|
||||
* @see {@link McpUiTheme} for the theme type
|
||||
* @see {@link applyDocumentTheme `applyDocumentTheme`} to set the theme
|
||||
* @see {@link McpUiTheme `McpUiTheme`} for the theme type
|
||||
*/
|
||||
export function getDocumentTheme(): McpUiTheme {
|
||||
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 McpUiTheme} for the theme type
|
||||
* @see {@link getDocumentTheme `getDocumentTheme`} to read the current theme
|
||||
* @see {@link McpUiTheme `McpUiTheme`} for the theme type
|
||||
*/
|
||||
export function applyDocumentTheme(theme: McpUiTheme): void {
|
||||
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.
|
||||
*
|
||||
* 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`).
|
||||
* This allows apps to use the host's theming values via CSS variables like
|
||||
* `var(--color-background-primary)`.
|
||||
|
|
@ -90,8 +90,8 @@ export function applyDocumentTheme(theme: McpUiTheme): void {
|
|||
* }
|
||||
* ```
|
||||
*
|
||||
* @see {@link McpUiStyles} for the available CSS variables
|
||||
* @see {@link McpUiHostContext} for the full host context structure
|
||||
* @see {@link McpUiStyles `McpUiStyles`} for the available CSS variables
|
||||
* @see {@link McpUiHostContext `McpUiHostContext`} for the full host context structure
|
||||
*/
|
||||
export function applyHostStyleVariables(
|
||||
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 {
|
||||
const styleId = "__mcp-host-fonts";
|
||||
|
|
|
|||
Loading…
Reference in a new issue