From 9dd995562aeab5654561d541dc7fdcdb7ed7353f Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Thu, 22 Jan 2026 14:36:45 -0600 Subject: [PATCH] Format `{@link}` tags with monospace display text Add explicit backtick-wrapped display text to all `{@link}` tags for monospace rendering in TypeDoc output. This improves readability by: - Using monospace font for code references (types, methods, functions) - Stripping module prefixes from display text (e.g., `app!App.connect` displays as `App.connect`) Updated files across the SDK including `App`, `AppBridge`, `PostMessageTransport`, React hooks, server helpers, types, and documentation. Co-Authored-By: Claude Opus 4.5 --- docs/patterns.md | 16 ++-- src/app-bridge.examples.ts | 2 +- src/app-bridge.ts | 94 ++++++++++++------------ src/app.examples.ts | 2 +- src/app.ts | 118 +++++++++++++++--------------- src/generated/schema.ts | 36 ++++----- src/message-transport.examples.ts | 2 +- src/message-transport.ts | 10 +-- src/react/index.tsx | 12 +-- src/react/useApp.tsx | 24 +++--- src/react/useAutoResize.ts | 12 +-- src/react/useDocumentTheme.ts | 4 +- src/react/useHostStyles.ts | 26 +++---- src/server/index.examples.ts | 2 +- src/server/index.ts | 20 ++--- src/spec.types.ts | 36 ++++----- src/styles.examples.ts | 2 +- src/styles.ts | 16 ++-- 18 files changed, 217 insertions(+), 217 deletions(-) diff --git a/docs/patterns.md b/docs/patterns.md index abe8017..46e608e 100644 --- a/docs/patterns.md +++ b/docs/patterns.md @@ -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} diff --git a/src/app-bridge.examples.ts b/src/app-bridge.examples.ts index 8f36cb6..be79b51 100644 --- a/src/app-bridge.examples.ts +++ b/src/app-bridge.examples.ts @@ -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. diff --git a/src/app-bridge.ts b/src/app-bridge.ts index 3083b57..fcffaf4 100644 --- a/src/app-bridge.ts +++ b/src/app-bridge.ts @@ -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. diff --git a/src/app.examples.ts b/src/app.examples.ts index 5c6a4ce..97aa5a0 100644 --- a/src/app.examples.ts +++ b/src/app.examples.ts @@ -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. diff --git a/src/app.ts b/src/app.ts index 4fa8776..9ef0af4 100644 --- a/src/app.ts +++ b/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 { * 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 { * @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 { * 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 { * @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 { * @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 { * 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 { * 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 { * 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 { * 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 { * 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 { * 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 { * @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 { * 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 { * @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 { * 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 { * @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 { * @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 { * 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 { * @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 { ); } - /** @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 { * @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 { * * @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({ @@ -850,12 +850,12 @@ export class App extends Protocol { * 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 { * @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( diff --git a/src/generated/schema.ts b/src/generated/schema.ts index 32277d2..a4dc81c 100644 --- a/src/generated/schema.ts +++ b/src/generated/schema.ts @@ -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({ diff --git a/src/message-transport.examples.ts b/src/message-transport.examples.ts index 38abf46..595a227 100644 --- a/src/message-transport.examples.ts +++ b/src/message-transport.examples.ts @@ -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. diff --git a/src/message-transport.ts b/src/message-transport.ts index c7353cf..33a6437 100644 --- a/src/message-transport.ts +++ b/src/message-transport.ts @@ -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 diff --git a/src/react/index.tsx b/src/react/index.tsx index 5319084..4057684 100644 --- a/src/react/index.tsx +++ b/src/react/index.tsx @@ -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 * diff --git a/src/react/useApp.tsx b/src/react/useApp.tsx index 248f78f..0c823cd 100644 --- a/src/react/useApp.tsx +++ b/src/react/useApp.tsx @@ -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, diff --git a/src/react/useAutoResize.ts b/src/react/useAutoResize.ts index d7e3de7..a1494fe 100644 --- a/src/react/useAutoResize.ts +++ b/src/react/useAutoResize.ts @@ -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, diff --git a/src/react/useDocumentTheme.ts b/src/react/useDocumentTheme.ts index 81a7b16..f3127b5 100644 --- a/src/react/useDocumentTheme.ts +++ b/src/react/useDocumentTheme.ts @@ -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(getDocumentTheme); diff --git a/src/react/useHostStyles.ts b/src/react/useHostStyles.ts index 6c88b71..38d2183 100644 --- a/src/react/useHostStyles.ts +++ b/src/react/useHostStyles.ts @@ -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, diff --git a/src/server/index.examples.ts b/src/server/index.examples.ts index 128279c..03ec549 100644 --- a/src/server/index.examples.ts +++ b/src/server/index.examples.ts @@ -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. diff --git a/src/server/index.ts b/src/server/index.ts index 826c8b3..fbb43fc 100644 --- a/src/server/index.ts +++ b/src/server/index.ts @@ -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, diff --git a/src/spec.types.ts b/src/spec.types.ts index cb6af1f..945753c 100644 --- a/src/spec.types.ts +++ b/src/spec.types.ts @@ -144,7 +144,7 @@ export type McpUiStyles = Record; /** * @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. */ diff --git a/src/styles.examples.ts b/src/styles.examples.ts index 8a92281..3c3f4ca 100644 --- a/src/styles.examples.ts +++ b/src/styles.examples.ts @@ -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. diff --git a/src/styles.ts b/src/styles.ts index 884564b..055fe0f 100644 --- a/src/styles.ts +++ b/src/styles.ts @@ -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";